diff --git a/docs/_meta.ts b/docs/_meta.ts new file mode 100644 index 00000000..4939cb31 --- /dev/null +++ b/docs/_meta.ts @@ -0,0 +1,10 @@ +export default { + index: 'Welcome to Qwen Code', + cli: 'CLI', + core: 'Core', + tools: 'Tools', + features: 'Features', + 'ide-integration': 'IDE Integration', + development: 'Development', + support: 'Support', +}; diff --git a/docs/Uninstall.md b/docs/cli/Uninstall.md similarity index 100% rename from docs/Uninstall.md rename to docs/cli/Uninstall.md diff --git a/docs/cli/_meta.ts b/docs/cli/_meta.ts new file mode 100644 index 00000000..1557b595 --- /dev/null +++ b/docs/cli/_meta.ts @@ -0,0 +1,35 @@ +export default { + index: 'Introduction', + authentication: 'Authentication', + 'openai-auth': 'OpenAI Authentication', + commands: 'Commands', + configuration: 'Configuration', + 'configuration-v1': 'Configuration (v1)', + themes: 'Themes', + tutorials: 'Tutorials', + 'keyboard-shortcuts': 'Keyboard Shortcuts', + 'trusted-folders': 'Trusted Folders', + 'qwen-ignore': 'Ignoring Files', + Uninstall: 'Uninstall', +}; + +/** + * + * { "label": "Introduction", "slug": "docs/cli" }, + { "label": "Authentication", "slug": "docs/cli/authentication" }, + { "label": "Commands", "slug": "docs/cli/commands" }, + { "label": "Configuration", "slug": "docs/cli/configuration" }, + { "label": "Checkpointing", "slug": "docs/checkpointing" }, + { "label": "Extensions", "slug": "docs/extension" }, + { "label": "Headless Mode", "slug": "docs/headless" }, + { "label": "IDE Integration", "slug": "docs/ide-integration" }, + { + "label": "IDE Companion Spec", + "slug": "docs/ide-companion-spec" + }, + { "label": "Telemetry", "slug": "docs/telemetry" }, + { "label": "Themes", "slug": "docs/cli/themes" }, + { "label": "Token Caching", "slug": "docs/cli/token-caching" }, + { "label": "Trusted Folders", "slug": "docs/trusted-folders" }, + { "label": "Tutorials", "slug": "docs/cli/tutorials" } + */ diff --git a/docs/cli/index.md b/docs/cli/index.md index 6dd24b2a..e5d3ddc6 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -1,17 +1,14 @@ # 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 - **[Authentication](./authentication.md):** A guide to setting up authentication with Qwen OAuth and OpenAI-compatible providers. - **[Commands](./commands.md):** A reference for Qwen Code CLI commands (e.g., `/help`, `/tools`, `/theme`). - **[Configuration](./configuration.md):** A guide to tailoring Qwen Code CLI behavior using configuration files. -- **[Headless Mode](../headless.md):** A comprehensive guide to using Qwen Code programmatically for scripting and automation. -- **[Token Caching](./token-caching.md):** Optimize API costs through token caching. - **[Themes](./themes.md)**: A guide to customizing the CLI's appearance with different themes. - **[Tutorials](tutorials.md)**: A tutorial showing how to use Qwen Code to automate a development task. -- **[Welcome Back](./welcome-back.md)**: Learn about the Welcome Back feature that helps you resume work seamlessly across sessions. ## Non-interactive mode diff --git a/docs/keyboard-shortcuts.md b/docs/cli/keyboard-shortcuts.md similarity index 100% rename from docs/keyboard-shortcuts.md rename to docs/cli/keyboard-shortcuts.md diff --git a/docs/qwen-ignore.md b/docs/cli/qwen-ignore.md similarity index 100% rename from docs/qwen-ignore.md rename to docs/cli/qwen-ignore.md diff --git a/docs/trusted-folders.md b/docs/cli/trusted-folders.md similarity index 100% rename from docs/trusted-folders.md rename to docs/cli/trusted-folders.md diff --git a/docs/development/_meta.ts b/docs/development/_meta.ts new file mode 100644 index 00000000..6428e766 --- /dev/null +++ b/docs/development/_meta.ts @@ -0,0 +1,8 @@ +export default { + architecture: 'Architecture', + npm: 'NPM', + deployment: 'Deployment', + telemetry: 'Telemetry', + 'integration-tests': 'Integration Tests', + 'issue-and-pr-automation': 'Issue and PR Automation', +}; diff --git a/docs/architecture.md b/docs/development/architecture.md similarity index 100% rename from docs/architecture.md rename to docs/development/architecture.md diff --git a/docs/deployment.md b/docs/development/deployment.md similarity index 100% rename from docs/deployment.md rename to docs/development/deployment.md diff --git a/docs/integration-tests.md b/docs/development/integration-tests.md similarity index 100% rename from docs/integration-tests.md rename to docs/development/integration-tests.md diff --git a/docs/issue-and-pr-automation.md b/docs/development/issue-and-pr-automation.md similarity index 100% rename from docs/issue-and-pr-automation.md rename to docs/development/issue-and-pr-automation.md diff --git a/docs/npm.md b/docs/development/npm.md similarity index 100% rename from docs/npm.md rename to docs/development/npm.md diff --git a/docs/telemetry.md b/docs/development/telemetry.md similarity index 100% rename from docs/telemetry.md rename to docs/development/telemetry.md diff --git a/docs/extension-releasing.md b/docs/extensions/extension-releasing.md similarity index 100% rename from docs/extension-releasing.md rename to docs/extensions/extension-releasing.md diff --git a/docs/extension.md b/docs/extensions/extension.md similarity index 100% rename from docs/extension.md rename to docs/extensions/extension.md diff --git a/docs/getting-started-extensions.md b/docs/extensions/getting-started-extensions.md similarity index 100% rename from docs/getting-started-extensions.md rename to docs/extensions/getting-started-extensions.md diff --git a/docs/features/_meta.ts b/docs/features/_meta.ts new file mode 100644 index 00000000..de2c5fcd --- /dev/null +++ b/docs/features/_meta.ts @@ -0,0 +1,8 @@ +export default { + subagents: 'Subagents', + checkpointing: 'Checkpointing', + sandbox: 'Sandbox Support', + 'headless-mode': 'Headless Mode', + 'welcome-back': 'Welcome Back', + 'token-caching': 'Token Caching', +}; diff --git a/docs/checkpointing.md b/docs/features/checkpointing.md similarity index 100% rename from docs/checkpointing.md rename to docs/features/checkpointing.md diff --git a/docs/headless.md b/docs/features/headless.md similarity index 100% rename from docs/headless.md rename to docs/features/headless.md diff --git a/docs/sandbox.md b/docs/features/sandbox.md similarity index 100% rename from docs/sandbox.md rename to docs/features/sandbox.md diff --git a/docs/subagents.md b/docs/features/subagents.md similarity index 100% rename from docs/subagents.md rename to docs/features/subagents.md diff --git a/docs/cli/token-caching.md b/docs/features/token-caching.md similarity index 100% rename from docs/cli/token-caching.md rename to docs/features/token-caching.md diff --git a/docs/cli/welcome-back.md b/docs/features/welcome-back.md similarity index 100% rename from docs/cli/welcome-back.md rename to docs/features/welcome-back.md diff --git a/docs/ide-integration/_meta.ts b/docs/ide-integration/_meta.ts new file mode 100644 index 00000000..b2169d3e --- /dev/null +++ b/docs/ide-integration/_meta.ts @@ -0,0 +1,4 @@ +export default { + 'ide-integration': 'Introduction', + 'ide-companion-spec': 'IDE Companion Spec', +}; diff --git a/docs/ide-companion-spec.md b/docs/ide-integration/ide-companion-spec.md similarity index 100% rename from docs/ide-companion-spec.md rename to docs/ide-integration/ide-companion-spec.md diff --git a/docs/ide-integration.md b/docs/ide-integration/ide-integration.md similarity index 100% rename from docs/ide-integration.md rename to docs/ide-integration/ide-integration.md diff --git a/docs/index.md b/docs/index.md index 02e5ce4f..53e00dd3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,42 +1,344 @@ # 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. +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. -## Overview +## ๐Ÿš€ Why Choose Qwen Code? -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`. +- ๐ŸŽฏ **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. -## Navigating the documentation +## Installation -This documentation is organized into the following sections: +### Prerequisites -- **[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. +Ensure you have [Node.js version 20](https://nodejs.org/en/download) or higher installed. -We hope this documentation helps you make the most of Qwen Code! +```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/support/_meta.ts b/docs/support/_meta.ts new file mode 100644 index 00000000..9140d4fe --- /dev/null +++ b/docs/support/_meta.ts @@ -0,0 +1,4 @@ +export default { + troubleshooting: 'Troubleshooting', + 'tos-privacy': 'Terms of Service', +}; diff --git a/docs/tos-privacy.md b/docs/support/tos-privacy.md similarity index 100% rename from docs/tos-privacy.md rename to docs/support/tos-privacy.md diff --git a/docs/troubleshooting.md b/docs/support/troubleshooting.md similarity index 100% rename from docs/troubleshooting.md rename to docs/support/troubleshooting.md diff --git a/docs/tools/_meta.ts b/docs/tools/_meta.ts new file mode 100644 index 00000000..dc18f5e0 --- /dev/null +++ b/docs/tools/_meta.ts @@ -0,0 +1,11 @@ +export default { + index: 'Introduction', + 'file-system': 'File System', + 'multi-file': 'Multi-File Read', + shell: 'Shell', + 'todo-write': 'Todo Write', + 'web-fetch': 'Web Fetch', + 'web-search': 'Web Search', + memory: 'Memory', + 'mcp-server': 'MCP Servers', +}; diff --git a/docs/tools/index.md b/docs/tools/index.md index 6c3cec3d..6798ec6c 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.