diff --git a/docs/_meta.ts b/docs/_meta.ts index 07afc2acd..4939cb311 100644 --- a/docs/_meta.ts +++ b/docs/_meta.ts @@ -1,5 +1,5 @@ export default { - overview: 'Overview', + index: 'Welcome to Qwen Code', cli: 'CLI', core: 'Core', tools: 'Tools', diff --git a/docs/cli/_meta.ts b/docs/cli/_meta.ts index 172638709..1557b5955 100644 --- a/docs/cli/_meta.ts +++ b/docs/cli/_meta.ts @@ -9,8 +9,8 @@ export default { tutorials: 'Tutorials', 'keyboard-shortcuts': 'Keyboard Shortcuts', 'trusted-folders': 'Trusted Folders', - Uninstall: 'Uninstall', 'qwen-ignore': 'Ignoring Files', + Uninstall: 'Uninstall', }; /** diff --git a/docs/cli/index.md b/docs/cli/index.md index 0a7dd20cc..e5d3ddc6b 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -1,6 +1,6 @@ # Qwen Code CLI -Within Qwen Code, `packages/cli` is the frontend for users to send and receive prompts with Qwen and other AI models and their associated tools. For a general overview of Qwen Code, see the [main documentation page](../index.md). +Within Qwen Code, `packages/cli` is the frontend for users to send and receive prompts with Qwen and other AI models and their associated tools. For a general overview of Qwen Code ## Navigating this section diff --git a/docs/development/_meta.ts b/docs/development/_meta.ts index e984be784..6428e766e 100644 --- a/docs/development/_meta.ts +++ b/docs/development/_meta.ts @@ -1,6 +1,7 @@ export default { + architecture: 'Architecture', npm: 'NPM', - releases: 'Releases', + deployment: 'Deployment', telemetry: 'Telemetry', 'integration-tests': 'Integration Tests', 'issue-and-pr-automation': 'Issue and PR Automation', diff --git a/docs/overview/architecture.md b/docs/development/architecture.md similarity index 100% rename from docs/overview/architecture.md rename to docs/development/architecture.md diff --git a/docs/features/_meta.ts b/docs/features/_meta.ts index 92a594b10..de2c5fcdd 100644 --- a/docs/features/_meta.ts +++ b/docs/features/_meta.ts @@ -1,5 +1,5 @@ export default { - subagent: 'Subagent', + subagents: 'Subagents', checkpointing: 'Checkpointing', sandbox: 'Sandbox Support', 'headless-mode': 'Headless Mode', diff --git a/docs/ide-integration/_meta.ts b/docs/ide-integration/_meta.ts index 61c0cf10e..b2169d3e2 100644 --- a/docs/ide-integration/_meta.ts +++ b/docs/ide-integration/_meta.ts @@ -1,4 +1,4 @@ export default { - index: 'Introduction', + 'ide-integration': 'Introduction', 'ide-companion-spec': 'IDE Companion Spec', }; diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..53e00dd38 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,344 @@ +# Welcome to Qwen Code documentation + +Qwen Code is a powerful command-line AI workflow tool adapted from [**Gemini CLI**](https://github.com/google-gemini/gemini-cli) ([details](./README.gemini.md)), specifically optimized for [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) models. It enhances your development workflow with advanced code understanding, automated tasks, and intelligent assistance. + +## ๐Ÿš€ Why Choose Qwen Code? + +- ๐ŸŽฏ **Free Tier:** Up to 60 requests/min and 2,000 requests/day with your [QwenChat](https://chat.qwen.ai/) account. +- ๐Ÿง  **Advanced Model:** Specially optimized for [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) for superior code understanding and assistance. +- ๐Ÿ† **Comprehensive Features:** Includes subagents, Plan Mode, TodoWrite, vision model support, and full OpenAI API compatibilityโ€”all seamlessly integrated. +- ๐Ÿ”ง **Built-in & Extensible Tools:** Includes file system operations, shell command execution, web fetch/search, and moreโ€”all easily extended via the Model Context Protocol (MCP) for custom integrations. +- ๐Ÿ’ป **Developer-Centric:** Built for terminal-first workflowsโ€”perfect for command-line enthusiasts. +- ๐Ÿ›ก๏ธ **Open Source:** Apache 2.0 licensed for maximum freedom and transparency. + +## Installation + +### Prerequisites + +Ensure you have [Node.js version 20](https://nodejs.org/en/download) or higher installed. + +```bash +curl -qL https://www.npmjs.com/install.sh | sh +``` + +### Install from npm + +```bash +npm install -g @qwen-code/qwen-code@latest +qwen --version +``` + +### Install from source + +```bash +git clone https://github.com/QwenLM/qwen-code.git +cd qwen-code +npm install +npm install -g . +``` + +### Install globally with Homebrew (macOS/Linux) + +```bash +brew install qwen-code +``` + +## Quick Start + +```bash +# Start Qwen Code +qwen + +# Example commands +> Explain this codebase structure +> Help me refactor this function +> Generate unit tests for this module +``` + +### Session Management + +Control your token usage with configurable session limits to optimize costs and performance. + +#### Configure Session Token Limit + +Create or edit `.qwen/settings.json` in your home directory: + +```json +{ + "sessionTokenLimit": 32000 +} +``` + +#### Session Commands + +- **`/compress`** - Compress conversation history to continue within token limits +- **`/clear`** - Clear all conversation history and start fresh +- **`/stats`** - Check current token usage and limits + +> ๐Ÿ“ **Note**: Session token limit applies to a single conversation, not cumulative API calls. + +### Vision Model Configuration + +Qwen Code includes intelligent vision model auto-switching that detects images in your input and can automatically switch to vision-capable models for multimodal analysis. **This feature is enabled by default** - when you include images in your queries, you'll see a dialog asking how you'd like to handle the vision model switch. + +#### Skip the Switch Dialog (Optional) + +If you don't want to see the interactive dialog each time, configure the default behavior in your `.qwen/settings.json`: + +```json +{ + "experimental": { + "vlmSwitchMode": "once" + } +} +``` + +**Available modes:** + +- **`"once"`** - Switch to vision model for this query only, then revert +- **`"session"`** - Switch to vision model for the entire session +- **`"persist"`** - Continue with current model (no switching) +- **Not set** - Show interactive dialog each time (default) + +#### Command Line Override + +You can also set the behavior via command line: + +```bash +# Switch once per query +qwen --vlm-switch-mode once + +# Switch for entire session +qwen --vlm-switch-mode session + +# Never switch automatically +qwen --vlm-switch-mode persist +``` + +#### Disable Vision Models (Optional) + +To completely disable vision model support, add to your `.qwen/settings.json`: + +```json +{ + "experimental": { + "visionModelPreview": false + } +} +``` + +> ๐Ÿ’ก **Tip**: In YOLO mode (`--yolo`), vision switching happens automatically without prompts when images are detected. + +### Authorization + +Choose your preferred authentication method based on your needs: + +#### 1. Qwen OAuth (๐Ÿš€ Recommended - Start in 30 seconds) + +The easiest way to get started - completely free with generous quotas: + +```bash +# Just run this command and follow the browser authentication +qwen +``` + +**What happens:** + +1. **Instant Setup**: CLI opens your browser automatically +2. **One-Click Login**: Authenticate with your qwen.ai account +3. **Automatic Management**: Credentials cached locally for future use +4. **No Configuration**: Zero setup required - just start coding! + +**Free Tier Benefits:** + +- โœ… **2,000 requests/day** (no token counting needed) +- โœ… **60 requests/minute** rate limit +- โœ… **Automatic credential refresh** +- โœ… **Zero cost** for individual users +- โ„น๏ธ **Note**: Model fallback may occur to maintain service quality + +#### 2. OpenAI-Compatible API + +Use API keys for OpenAI or other compatible providers: + +**Configuration Methods:** + +1. **Environment Variables** + + ```bash + export OPENAI_API_KEY="your_api_key_here" + export OPENAI_BASE_URL="your_api_endpoint" + export OPENAI_MODEL="your_model_choice" + ``` + +2. **Project `.env` File** + Create a `.env` file in your project root: + ```env + OPENAI_API_KEY=your_api_key_here + OPENAI_BASE_URL=your_api_endpoint + OPENAI_MODEL=your_model_choice + ``` + +**API Provider Options** + +> โš ๏ธ **Regional Notice:** +> +> - **Mainland China**: Use Alibaba Cloud Bailian or ModelScope +> - **International**: Use Alibaba Cloud ModelStudio or OpenRouter + +
+๐Ÿ‡จ๐Ÿ‡ณ For Users in Mainland China + +**Option 1: Alibaba Cloud Bailian** ([Apply for API Key](https://bailian.console.aliyun.com/)) + +```bash +export OPENAI_API_KEY="your_api_key_here" +export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" +export OPENAI_MODEL="qwen3-coder-plus" +``` + +**Option 2: ModelScope (Free Tier)** ([Apply for API Key](https://modelscope.cn/docs/model-service/API-Inference/intro)) + +- โœ… **2,000 free API calls per day** +- โš ๏ธ Connect your Aliyun account to avoid authentication errors + +```bash +export OPENAI_API_KEY="your_api_key_here" +export OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1" +export OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct" +``` + +
+ +
+๐ŸŒ For International Users + +**Option 1: Alibaba Cloud ModelStudio** ([Apply for API Key](https://modelstudio.console.alibabacloud.com/)) + +```bash +export OPENAI_API_KEY="your_api_key_here" +export OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1" +export OPENAI_MODEL="qwen3-coder-plus" +``` + +**Option 2: OpenRouter (Free Tier Available)** ([Apply for API Key](https://openrouter.ai/)) + +```bash +export OPENAI_API_KEY="your_api_key_here" +export OPENAI_BASE_URL="https://openrouter.ai/api/v1" +export OPENAI_MODEL="qwen/qwen3-coder:free" +``` + +
+ +## Usage Examples + +### ๐Ÿ” Explore Codebases + +```bash +cd your-project/ +qwen + +# Architecture analysis +> Describe the main pieces of this system's architecture +> What are the key dependencies and how do they interact? +> Find all API endpoints and their authentication methods +``` + +### ๐Ÿ’ป Code Development + +```bash +# Refactoring +> Refactor this function to improve readability and performance +> Convert this class to use dependency injection +> Split this large module into smaller, focused components + +# Code generation +> Create a REST API endpoint for user management +> Generate unit tests for the authentication module +> Add error handling to all database operations +``` + +### ๐Ÿ”„ Automate Workflows + +```bash +# Git automation +> Analyze git commits from the last 7 days, grouped by feature +> Create a changelog from recent commits +> Find all TODO comments and create GitHub issues + +# File operations +> Convert all images in this directory to PNG format +> Rename all test files to follow the *.test.ts pattern +> Find and remove all console.log statements +``` + +### ๐Ÿ› Debugging & Analysis + +```bash +# Performance analysis +> Identify performance bottlenecks in this React component +> Find all N+1 query problems in the codebase + +# Security audit +> Check for potential SQL injection vulnerabilities +> Find all hardcoded credentials or API keys +``` + +## Popular Tasks + +### ๐Ÿ“š Understand New Codebases + +```text +> What are the core business logic components? +> What security mechanisms are in place? +> How does the data flow through the system? +> What are the main design patterns used? +> Generate a dependency graph for this module +``` + +### ๐Ÿ”จ Code Refactoring & Optimization + +```text +> What parts of this module can be optimized? +> Help me refactor this class to follow SOLID principles +> Add proper error handling and logging +> Convert callbacks to async/await pattern +> Implement caching for expensive operations +``` + +### ๐Ÿ“ Documentation & Testing + +```text +> Generate comprehensive JSDoc comments for all public APIs +> Write unit tests with edge cases for this component +> Create API documentation in OpenAPI format +> Add inline comments explaining complex algorithms +> Generate a README for this module +``` + +### ๐Ÿš€ Development Acceleration + +```text +> Set up a new Express server with authentication +> Create a React component with TypeScript and tests +> Implement a rate limiter middleware +> Add database migrations for new schema +> Configure CI/CD pipeline for this project +``` + +## Commands & Shortcuts + +### Session Commands + +- `/help` - Display available commands +- `/clear` - Clear conversation history +- `/compress` - Compress history to save tokens +- `/stats` - Show current session information +- `/exit` or `/quit` - Exit Qwen Code + +### Keyboard Shortcuts + +- `Ctrl+C` - Cancel current operation +- `Ctrl+D` - Exit (on empty line) +- `Up/Down` - Navigate command history diff --git a/docs/overview/_meta.ts b/docs/overview/_meta.ts deleted file mode 100644 index b5508759b..000000000 --- a/docs/overview/_meta.ts +++ /dev/null @@ -1,4 +0,0 @@ -export default { - index: 'Introduction', - architecture: 'Architecture Overview', -}; diff --git a/docs/overview/index.md b/docs/overview/index.md deleted file mode 100644 index 02e5ce4fc..000000000 --- a/docs/overview/index.md +++ /dev/null @@ -1,42 +0,0 @@ -# Welcome to Qwen Code documentation - -This documentation provides a comprehensive guide to installing, using, and developing Qwen Code. This tool lets you interact with AI models through a command-line interface. - -## Overview - -Qwen Code brings the capabilities of advanced code models to your terminal in an interactive Read-Eval-Print Loop (REPL) environment. Qwen Code consists of a client-side application (`packages/cli`) that communicates with a local server (`packages/core`). Qwen Code also contains a variety of tools for tasks such as performing file system operations, running shells, and web fetching, which are managed by `packages/core`. - -## Navigating the documentation - -This documentation is organized into the following sections: - -- **[Execution and Deployment](./deployment.md):** Information for running Qwen Code. -- **[Architecture Overview](./architecture.md):** Understand the high-level design of Qwen Code, including its components and how they interact. -- **CLI Usage:** Documentation for `packages/cli`. - - **[CLI Introduction](./cli/index.md):** Overview of the command-line interface. - - **[Commands](./cli/commands.md):** Description of available CLI commands. - - **[Configuration](./cli/configuration.md):** Information on configuring the CLI. - - **[Checkpointing](./checkpointing.md):** Documentation for the checkpointing feature. - - **[Extensions](./extension.md):** How to extend the CLI with new functionality. - - **[IDE Integration](./ide-integration.md):** Connect the CLI to your editor. - - **[IDE Companion Extension Spec](./ide-companion-spec.md):** Spec for building IDE companion extensions. - - **[Telemetry](./telemetry.md):** Overview of telemetry in the CLI. - - **[Trusted Folders](./trusted-folders.md):** An overview of the Trusted Folders security feature. -- **Core Details:** Documentation for `packages/core`. - - **[Core Introduction](./core/index.md):** Overview of the core component. - - **[Tools API](./core/tools-api.md):** Information on how the core manages and exposes tools. -- **Tools:** - - **[Tools Overview](./tools/index.md):** Overview of the available tools. - - **[File System Tools](./tools/file-system.md):** Documentation for the `read_file` and `write_file` tools. - - **[Multi-File Read Tool](./tools/multi-file.md):** Documentation for the `read_many_files` tool. - - **[Shell Tool](./tools/shell.md):** Documentation for the `run_shell_command` tool. - - **[Web Fetch Tool](./tools/web-fetch.md):** Documentation for the `web_fetch` tool. - - **[Web Search Tool](./tools/web-search.md):** Documentation for the `web_search` tool. - - **[Memory Tool](./tools/memory.md):** Documentation for the `save_memory` tool. -- **[Subagents](./subagents.md):** Specialized AI assistants for focused tasks with comprehensive management, configuration, and usage guidance. -- **[Contributing & Development Guide](../CONTRIBUTING.md):** Information for contributors and developers, including setup, building, testing, and coding conventions. -- **[NPM](./npm.md):** Details on how the project's packages are structured -- **[Troubleshooting Guide](./troubleshooting.md):** Find solutions to common problems and FAQs. -- **[Terms of Service and Privacy Notice](./tos-privacy.md):** Information on the terms of service and privacy notices applicable to your use of Qwen Code. - -We hope this documentation helps you make the most of Qwen Code! diff --git a/docs/support/_meta.ts b/docs/support/_meta.ts index 62085ee58..9140d4fe7 100644 --- a/docs/support/_meta.ts +++ b/docs/support/_meta.ts @@ -1,5 +1,4 @@ export default { - faq: 'FAQ', troubleshooting: 'Troubleshooting', 'tos-privacy': 'Terms of Service', }; diff --git a/docs/tools/_meta.ts b/docs/tools/_meta.ts index 9d0ee9ca4..dc18f5e07 100644 --- a/docs/tools/_meta.ts +++ b/docs/tools/_meta.ts @@ -1,5 +1,5 @@ export default { - overview: 'Overview', + index: 'Introduction', 'file-system': 'File System', 'multi-file': 'Multi-File Read', shell: 'Shell', diff --git a/docs/tools/index.md b/docs/tools/index.md index 6c3cec3d8..6798ec6c3 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -54,4 +54,3 @@ Qwen Code's built-in tools can be broadly categorized as follows: Additionally, these tools incorporate: - **[MCP servers](./mcp-server.md)**: MCP servers act as a bridge between the model and your local environment or other services like APIs. -- **[Sandboxing](../sandbox.md)**: Sandboxing isolates the model and its changes from your environment to reduce potential risk.