From 1123b9f0fc1315c39650a8d9694a3afda861454d Mon Sep 17 00:00:00 2001 From: sontoriyama Date: Sat, 11 Oct 2025 05:33:23 +0200 Subject: [PATCH 01/40] docs: add comprehensive MCP Quick Start guides and examples - Add MCP Quick Start Guide with 5 practical examples - Add 30+ ready-to-use MCP configuration examples - Add MCP testing and validation guide - Update tools documentation index with MCP guide links This documentation makes it easier for users to get started with Model Context Protocol servers in Qwen Code, reducing setup time from hours to minutes. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- docs/mcp-example-configs.md | 534 +++++++++++++++++++++++++++++++++ docs/mcp-quick-start.md | 418 ++++++++++++++++++++++++++ docs/mcp-testing-validation.md | 382 +++++++++++++++++++++++ docs/tools/index.md | 3 + 4 files changed, 1337 insertions(+) create mode 100644 docs/mcp-example-configs.md create mode 100644 docs/mcp-quick-start.md create mode 100644 docs/mcp-testing-validation.md diff --git a/docs/mcp-example-configs.md b/docs/mcp-example-configs.md new file mode 100644 index 00000000..9cd64d99 --- /dev/null +++ b/docs/mcp-example-configs.md @@ -0,0 +1,534 @@ +# MCP Example Configurations + +Ready-to-use MCP server configurations for common scenarios. + +## 📁 Local Development + +### Basic Setup + +```json +{ + "mcpServers": { + "workspace": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "trust": true, + "description": "Full workspace access" + } + } +} +``` + +### Multi-Directory Project + +```json +{ + "mcpServers": { + "frontend": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "./src", + "./public", + "./tests" + ], + "trust": true, + "description": "Frontend development files" + }, + "config": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "./config", + "./.env.example" + ], + "trust": true, + "includeTools": ["read_file", "list_directory"], + "description": "Configuration files (read-only)" + } + } +} +``` + +## 🧠 Memory & Context + +### Persistent Memory + +```json +{ + "mcpServers": { + "project-memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "trust": true, + "description": "Remember project context across sessions" + } + } +} +``` + +### Combined with Filesystem + +```json +{ + "mcpServers": { + "files": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "trust": true + }, + "memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "trust": true + } + } +} +``` + +## 🌐 Remote Servers (HTTP/SSE) + +### HTTP MCP Server + +```json +{ + "mcpServers": { + "remote-api": { + "httpUrl": "https://api.example.com/mcp", + "headers": { + "Authorization": "Bearer ${API_TOKEN}", + "Content-Type": "application/json" + }, + "timeout": 30000, + "description": "Remote MCP API" + } + } +} +``` + +### SSE Server with OAuth + +```json +{ + "mcpServers": { + "sse-service": { + "url": "https://mcp.example.com/sse", + "oauth": { + "enabled": true, + "scopes": ["read", "write"] + }, + "timeout": 60000, + "description": "SSE server with OAuth" + } + } +} +``` + +## 🐍 Python MCP Servers + +### Simple Python Server + +```json +{ + "mcpServers": { + "python-tools": { + "command": "python", + "args": ["-m", "my_mcp_server"], + "env": { + "PYTHONPATH": "${PWD}", + "DEBUG": "false" + }, + "description": "Custom Python MCP tools" + } + } +} +``` + +### Python with Virtual Environment + +```json +{ + "mcpServers": { + "python-venv": { + "command": "./venv/bin/python", + "args": ["-m", "mcp_server"], + "cwd": "./", + "env": { + "VIRTUAL_ENV": "${PWD}/venv" + }, + "description": "Python server in virtual environment" + } + } +} +``` + +## 🐳 Docker Containers + +### Basic Docker Server + +```json +{ + "mcpServers": { + "docker-mcp": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "my-mcp-server:latest" + ], + "timeout": 45000, + "description": "MCP server in Docker" + } + } +} +``` + +### Docker with Volume Mounts + +```json +{ + "mcpServers": { + "docker-workspace": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-v", + "${PWD}:/workspace", + "-w", + "/workspace", + "-e", + "API_KEY", + "mcp-tools:latest" + ], + "env": { + "API_KEY": "${MY_API_KEY}" + }, + "description": "Docker MCP with workspace access" + } + } +} +``` + +## 🛡️ Security-Focused Configs + +### Read-Only Filesystem + +```json +{ + "mcpServers": { + "readonly-docs": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "./docs", + "./README.md" + ], + "includeTools": ["read_file", "list_directory", "search_files"], + "excludeTools": [ + "write_file", + "create_directory", + "move_file", + "delete_file" + ], + "trust": true, + "description": "Read-only documentation access" + } + } +} +``` + +### Untrusted External Server + +```json +{ + "mcpServers": { + "external-api": { + "httpUrl": "https://external-mcp.example.com/api", + "trust": false, + "timeout": 15000, + "includeTools": ["search", "analyze"], + "description": "External API (requires confirmation)" + } + } +} +``` + +## 📊 Database Access + +### PostgreSQL MCP Server + +```json +{ + "mcpServers": { + "postgres": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-postgres", + "${DATABASE_URL}" + ], + "env": { + "DATABASE_URL": "$POSTGRES_CONNECTION_STRING" + }, + "timeout": 30000, + "trust": false, + "description": "PostgreSQL database access" + } + } +} +``` + +## 🧪 Testing & Development + +### Test Environment + +```json +{ + "mcpServers": { + "test-files": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "./tests", + "./fixtures" + ], + "trust": true, + "description": "Test files and fixtures" + }, + "test-memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "trust": true, + "description": "Test session memory" + } + } +} +``` + +### Debug Configuration + +```json +{ + "mcpServers": { + "debug-server": { + "command": "node", + "args": ["--inspect", "mcp-server.js"], + "env": { + "DEBUG": "*", + "LOG_LEVEL": "verbose" + }, + "timeout": 60000, + "description": "MCP server with debugging enabled" + } + } +} +``` + +## 🔄 CI/CD Integration + +### GitHub Actions Environment + +```json +{ + "mcpServers": { + "ci-workspace": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "${GITHUB_WORKSPACE}" + ], + "env": { + "GITHUB_TOKEN": "$GITHUB_TOKEN", + "CI": "true" + }, + "trust": true, + "description": "CI/CD workspace access" + } + } +} +``` + +## 🌟 Advanced Patterns + +### Multiple Servers Same Type + +```json +{ + "mcpServers": { + "project-a": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "../project-a"], + "description": "Project A files" + }, + "project-b": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "../project-b"], + "description": "Project B files" + }, + "shared-memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "description": "Shared knowledge across projects" + } + } +} +``` + +### Conditional Server Selection + +User-level config (`~/.qwen/settings.json`): +```json +{ + "mcpServers": { + "global-memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "trust": true, + "description": "Global memory across all projects" + } + } +} +``` + +Project-level config (`.qwen/settings.json`): +```json +{ + "mcpServers": { + "project-files": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "trust": true, + "description": "Project-specific files" + } + } +} +``` + +## 📝 Configuration Validation + +### Check Your Config + +```bash +# List configured servers +qwen mcp list + +# Show server details and schemas +qwen mcp list --schema + +# Test connection +qwen mcp list --descriptions +``` + +### Common Mistakes + +❌ **Wrong:** +```json +{ + "mcpServers": { + "server": { + "command": "mcp-server", // Not in PATH + "args": ["./"] + } + } +} +``` + +✅ **Correct:** +```json +{ + "mcpServers": { + "server": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "description": "Uses npx to ensure server is available" + } + } +} +``` + +## 🎯 Best Practices + +1. **Use descriptive names** - Make server purposes clear +2. **Set appropriate timeouts** - Match your server's response time +3. **Trust local servers** - Skip confirmation for your own tools +4. **Filter tools** - Use `includeTools`/`excludeTools` for security +5. **Document configs** - Add descriptions for team members +6. **Environment variables** - Keep secrets out of configs +7. **Test independently** - Verify servers work before configuring + +## 🔗 Quick Copy-Paste Configs + +### Starter Pack + +```json +{ + "mcpServers": { + "files": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "trust": true + }, + "memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "trust": true + } + } +} +``` + +### Documentation Project + +```json +{ + "mcpServers": { + "docs": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"], + "includeTools": ["read_file", "list_directory"], + "trust": true + } + } +} +``` + +### Full-Stack Development + +```json +{ + "mcpServers": { + "frontend": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./frontend"], + "trust": true + }, + "backend": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./backend"], + "trust": true + }, + "shared": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./shared"], + "trust": true + }, + "memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "trust": true + } + } +} +``` + +--- + +**Need help?** Check `qwen mcp --help` or refer to the [complete MCP documentation](./tools/mcp-server.md). diff --git a/docs/mcp-quick-start.md b/docs/mcp-quick-start.md new file mode 100644 index 00000000..2256ddaf --- /dev/null +++ b/docs/mcp-quick-start.md @@ -0,0 +1,418 @@ +# MCP Quick Start Guide - Practical Examples + +This guide provides real-world examples to get you started with Model Context Protocol (MCP) servers in Qwen Code. + +## 🚀 Getting Started in 5 Minutes + +### Step 1: Install MCP Servers + +Install official MCP servers from Anthropic: + +```bash +# Filesystem access +npm install -g @modelcontextprotocol/server-filesystem + +# Memory & Knowledge Graph +npm install -g @modelcontextprotocol/server-memory + +# Sequential thinking +npm install -g @modelcontextprotocol/server-sequential-thinking +``` + +### Step 2: Configure Your First MCP Server + +Create or edit `.qwen/settings.json` in your project: + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "description": "Access project files" + } + } +} +``` + +### Step 3: Verify Connection + +```bash +qwen mcp list +``` + +You should see: +``` +✓ filesystem: npx -y @modelcontextprotocol/server-filesystem ./ (stdio) - Connected +``` + +## 📚 Practical Examples + +### Example 1: Local Development Assistant + +**Use Case:** Work on a Node.js project with file access and memory. + +**Configuration (`.qwen/settings.json`):** + +```json +{ + "mcpServers": { + "project-files": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "./src", + "./tests", + "./docs" + ], + "description": "Access source code, tests, and documentation", + "trust": true + }, + "project-memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "description": "Remember project decisions and context", + "trust": true + } + } +} +``` + +**Usage:** +```bash +qwen + +> Remember: This project uses React 18 with TypeScript and follows Airbnb style guide +> List all files in the src directory +> Read src/App.tsx and suggest improvements +``` + +### Example 2: Multi-Repository Development + +**Use Case:** Working across multiple codebases simultaneously. + +**Configuration:** + +```json +{ + "mcpServers": { + "frontend": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "../frontend-app" + ], + "description": "Frontend repository access" + }, + "backend": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "../backend-api" + ], + "description": "Backend repository access" + }, + "shared-memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "description": "Shared knowledge across repositories" + } + } +} +``` + +### Example 3: Documentation-Only Access + +**Use Case:** Safe access to documentation without risking code changes. + +**Configuration:** + +```json +{ + "mcpServers": { + "docs": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "./docs", + "./README.md" + ], + "description": "Read-only documentation access", + "trust": true, + "includeTools": ["read_file", "list_directory"] + } + } +} +``` + +### Example 4: Custom Python MCP Server + +**Use Case:** Integrate custom Python tools via MCP. + +**Server File (`mcp_server.py`):** + +```python +#!/usr/bin/env python3 +import sys +from mcp.server.stdio import stdio_server +from mcp.server import Server +from mcp.types import Tool, TextContent + +server = Server("custom-tools") + +@server.list_tools() +async def list_tools() -> list[Tool]: + return [ + Tool( + name="analyze_python_code", + description="Static analysis of Python code", + inputSchema={ + "type": "object", + "properties": { + "file_path": {"type": "string"} + }, + "required": ["file_path"] + } + ) + ] + +@server.call_tool() +async def call_tool(name: str, arguments: dict) -> list[TextContent]: + if name == "analyze_python_code": + # Your custom logic here + return [TextContent(type="text", text=f"Analysis of {arguments['file_path']}")] + +async def main(): + async with stdio_server() as (read_stream, write_stream): + await server.run(read_stream, write_stream, server.create_initialization_options()) + +if __name__ == "__main__": + import asyncio + asyncio.run(main()) +``` + +**Configuration:** + +```json +{ + "mcpServers": { + "python-tools": { + "command": "python", + "args": ["mcp_server.py"], + "env": { + "PYTHONPATH": "${PWD}" + }, + "description": "Custom Python analysis tools" + } + } +} +``` + +### Example 5: Docker-Based MCP Server + +**Use Case:** Run MCP servers in isolated containers. + +**Configuration:** + +```json +{ + "mcpServers": { + "containerized-tools": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-v", + "${PWD}:/workspace", + "-w", + "/workspace", + "my-mcp-server:latest" + ], + "description": "MCP tools running in Docker" + } + } +} +``` + +## 🔧 Configuration Tips + +### Environment Variables + +Use environment variables for sensitive data: + +```json +{ + "mcpServers": { + "api-server": { + "command": "node", + "args": ["api-server.js"], + "env": { + "API_KEY": "${MY_API_KEY}", + "DATABASE_URL": "$DB_CONNECTION" + } + } + } +} +``` + +### Trust Settings + +Trust servers you control to skip confirmation dialogs: + +```json +{ + "mcpServers": { + "trusted-server": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "trust": true + } + } +} +``` + +### Tool Filtering + +Limit which tools are available: + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "includeTools": ["read_file", "list_directory"], + "excludeTools": ["write_file", "move_file"] + } + } +} +``` + +## 🎯 Common Use Cases + +### Code Review Assistant + +```json +{ + "mcpServers": { + "codebase": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "description": "Full codebase access for reviews" + }, + "review-memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "description": "Remember review comments and patterns" + } + } +} +``` + +**Usage:** +```bash +qwen + +> Review the changes in src/components/ +> Remember: We follow the single responsibility principle +> Check if all new components have tests +``` + +### Documentation Generator + +```json +{ + "mcpServers": { + "source": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"], + "includeTools": ["read_file", "list_directory"] + }, + "docs-writer": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"], + "includeTools": ["write_file", "create_directory"] + } + } +} +``` + +### Learning Assistant + +```json +{ + "mcpServers": { + "tutorials": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "./tutorials", + "./examples" + ], + "trust": true + }, + "learning-progress": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "description": "Track learning progress and concepts" + } + } +} +``` + +## 🛠️ Troubleshooting + +### Server Won't Connect + +1. **Check the command is accessible:** + ```bash + npx -y @modelcontextprotocol/server-filesystem ./ + ``` + +2. **Verify directory permissions:** + ```bash + ls -la ./ + ``` + +3. **Check logs:** + ```bash + qwen --debug + ``` + +### No Tools Discovered + +Ensure the server actually provides tools: +```bash +qwen mcp list --schema +``` + +### Tools Not Executing + +- Check parameter schemas match +- Verify timeout settings (increase if needed) +- Test the server independently first + +## 📖 Further Reading + +- [MCP Server Documentation](./tools/mcp-server.md) - Complete reference +- [Official MCP Specification](https://modelcontextprotocol.io/) - Protocol details +- [MCP Server Examples](https://github.com/modelcontextprotocol/servers) - Community servers + +## 🎓 Next Steps + +1. ✅ Configure your first MCP server +2. ✅ Verify connection with `qwen mcp list` +3. ✅ Try basic file operations +4. ✅ Add memory for persistent context +5. ✅ Explore community MCP servers +6. ✅ Build your own custom server + +--- + +**Pro Tip:** Start with trusted local servers (`trust: true`) for faster iteration, then add confirmation for production use. diff --git a/docs/mcp-testing-validation.md b/docs/mcp-testing-validation.md new file mode 100644 index 00000000..32b61420 --- /dev/null +++ b/docs/mcp-testing-validation.md @@ -0,0 +1,382 @@ +# MCP Testing & Validation Guide + +This guide helps you test and validate your MCP server configurations. + +## ✅ Quick Validation Checklist + +### 1. Check MCP Servers Are Configured + +```bash +qwen mcp list +``` + +**Expected output:** +``` +Configured MCP servers: + +✓ filesystem: npx -y @modelcontextprotocol/server-filesystem ./ (stdio) - Connected +✓ memory: npx -y @modelcontextprotocol/server-memory (stdio) - Connected +``` + +**Status indicators:** +- ✓ (green) - Connected successfully +- ✗ (red) - Connection failed or not connected + +### 2. Verify Server Is Installed + +Test the server command directly: + +```bash +# Filesystem server +npx -y @modelcontextprotocol/server-filesystem --help + +# Memory server +npx -y @modelcontextprotocol/server-memory --help + +# Custom server +python mcp_server.py --help +``` + +### 3. Check Configuration File Syntax + +Validate your JSON configuration: + +```bash +# Linux/macOS +cat .qwen/settings.json | jq . + +# Windows PowerShell +Get-Content .qwen/settings.json | ConvertFrom-Json | ConvertTo-Json +``` + +### 4. Test Within Qwen Code Session + +Start an interactive session and check MCP status: + +```bash +qwen + +# Inside the session: +/mcp # Show all MCP servers and tools +/mcp desc # Show tool descriptions +/mcp schema # Show tool parameter schemas +``` + +## 🧪 Test Cases + +### Test Case 1: Filesystem Server + +**Configuration:** +```json +{ + "mcpServers": { + "test-fs": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "trust": true + } + } +} +``` + +**Validation:** +1. List files: Start `qwen` and ask "List all files in this directory" +2. Read file: "Read the README.md file" +3. Verify output contains actual file contents + +**Expected Tools:** +- `read_file` - Read file contents +- `write_file` - Write to files +- `list_directory` - List directory contents +- `create_directory` - Create directories +- `move_file` - Move/rename files +- `search_files` - Search for files +- `get_file_info` - Get file metadata + +### Test Case 2: Memory Server + +**Configuration:** +```json +{ + "mcpServers": { + "test-memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "trust": true + } + } +} +``` + +**Validation:** +1. Store information: "Remember that this project uses React 18" +2. Query: "What JavaScript framework does this project use?" +3. Verify it recalls the information from step 1 + +**Expected Tools:** +- `create_entities` - Create knowledge entities +- `create_relations` - Create relationships between entities +- `add_observations` - Add observations to entities +- `delete_entities` - Remove entities +- `delete_observations` - Remove observations +- `delete_relations` - Remove relationships +- `read_graph` - Read entire knowledge graph +- `search_nodes` - Search for specific nodes +- `open_nodes` - Open specific nodes by name + +### Test Case 3: Multiple Servers + +**Configuration:** +```json +{ + "mcpServers": { + "files": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "trust": true + }, + "memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"], + "trust": true + } + } +} +``` + +**Validation:** +1. Check both servers are connected: `qwen mcp list` +2. Use filesystem tool: "List all JavaScript files" +3. Use memory tool: "Remember that we prefer TypeScript" +4. Verify both tools work simultaneously + +### Test Case 4: Tool Filtering + +**Configuration:** +```json +{ + "mcpServers": { + "readonly-fs": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "includeTools": ["read_file", "list_directory"], + "trust": true + } + } +} +``` + +**Validation:** +1. Start qwen session +2. Run `/mcp desc` to list available tools +3. Verify only `read_file` and `list_directory` are present +4. Verify `write_file`, `create_directory`, etc. are NOT available + +### Test Case 5: Untrusted Server Confirmation + +**Configuration:** +```json +{ + "mcpServers": { + "untrusted": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"], + "trust": false + } + } +} +``` + +**Validation:** +1. Ask qwen to read a file +2. Confirmation dialog should appear before execution +3. Options should include: + - Proceed once + - Always allow this tool + - Always allow this server + - Cancel + +## 🔍 Debugging Failed Connections + +### Issue: Server Shows "Disconnected" + +**Diagnostic steps:** + +1. **Test command manually:** + ```bash + npx -y @modelcontextprotocol/server-filesystem ./ + ``` + +2. **Check for errors:** + ```bash + qwen --debug + ``` + +3. **Verify paths are correct:** + ```bash + # Check if directory exists + ls ./ + + # Check if command is in PATH + which npx # Linux/macOS + where npx # Windows + ``` + +4. **Check permissions:** + ```bash + # Verify read/execute permissions + ls -la ./ + ``` + +5. **Review environment variables:** + ```bash + echo $PATH + echo $PYTHONPATH # For Python servers + ``` + +### Issue: No Tools Discovered + +**Diagnostic steps:** + +1. **Verify server implements MCP protocol:** + ```bash + # For stdio servers, test input/output manually + echo '{"jsonrpc": "2.0", "method": "initialize", "id": 1}' | npx -y @modelcontextprotocol/server-filesystem ./ + ``` + +2. **Check server logs:** + ```bash + # Some servers log to stderr + qwen --debug 2>&1 | grep MCP + ``` + +3. **Verify server version:** + ```bash + npm list -g @modelcontextprotocol/server-filesystem + ``` + +### Issue: Tools Fail to Execute + +**Diagnostic steps:** + +1. **Check parameter format:** + - Ensure parameters match the expected schema + - Verify JSON encoding is correct + +2. **Increase timeout:** + ```json + { + "mcpServers": { + "slow-server": { + "command": "...", + "timeout": 60000 + } + } + } + ``` + +3. **Check server implementation:** + - Verify the server actually implements the tool + - Test the tool independently if possible + +## 📊 Validation Results + +### Expected Server Connection Times + +| Server Type | Typical Connection Time | Timeout Recommendation | +|-------------|------------------------|------------------------| +| Filesystem | < 1 second | 10-30 seconds | +| Memory | < 1 second | 10-30 seconds | +| HTTP/SSE | 1-3 seconds | 30-60 seconds | +| Custom Python | 2-5 seconds | 30-60 seconds | +| Docker | 5-10 seconds | 60-120 seconds | + +### Tool Execution Times + +| Tool Type | Typical Duration | Timeout Recommendation | +|-------------------|-----------------|------------------------| +| Read file | < 100ms | 5-10 seconds | +| List directory | < 500ms | 10-15 seconds | +| Search files | 1-5 seconds | 30-60 seconds | +| Memory operations | < 1 second | 10-30 seconds | +| API calls | 1-10 seconds | 30-120 seconds | + +## 🎯 Success Criteria + +Your MCP configuration is working correctly if: + +✅ `qwen mcp list` shows all servers as "Connected" +✅ `/mcp` command in qwen session displays tools +✅ Tool executions complete without errors +✅ Confirmation dialogs appear for untrusted servers (if `trust: false`) +✅ Tool filtering works as expected (include/exclude) +✅ Environment variables are properly substituted +✅ Timeouts are appropriate for your server's response time + +## 🚀 Performance Tips + +1. **Use `trust: true` for local servers** to skip confirmation dialogs +2. **Set appropriate timeouts** - too low causes failures, too high slows down errors +3. **Filter tools** - Only enable tools you actually need +4. **Test servers independently** before configuring in qwen +5. **Use `--debug` flag** during initial setup +6. **Monitor resource usage** for long-running or resource-intensive servers + +## 📝 Validation Script Example + +Create a test script to automate validation: + +```bash +#!/bin/bash +# validate-mcp.sh + +echo "Testing MCP configuration..." + +# Test 1: Check config file exists +if [ ! -f .qwen/settings.json ]; then + echo "❌ Missing .qwen/settings.json" + exit 1 +fi +echo "✅ Config file exists" + +# Test 2: Validate JSON syntax +if ! cat .qwen/settings.json | jq . > /dev/null 2>&1; then + echo "❌ Invalid JSON in settings.json" + exit 1 +fi +echo "✅ Valid JSON syntax" + +# Test 3: Check servers are configured +SERVER_COUNT=$(cat .qwen/settings.json | jq '.mcpServers | length') +if [ "$SERVER_COUNT" -eq 0 ]; then + echo "❌ No MCP servers configured" + exit 1 +fi +echo "✅ $SERVER_COUNT MCP server(s) configured" + +# Test 4: Check connection status +qwen mcp list | grep -q "Connected" +if [ $? -eq 0 ]; then + echo "✅ At least one server is connected" +else + echo "❌ No servers connected" + exit 1 +fi + +echo "" +echo "✅ All validation checks passed!" +``` + +## 📚 Next Steps + +After validation: + +1. **Start using MCP tools** in your workflow +2. **Document your custom configurations** for team members +3. **Share your successful configs** with the community +4. **Monitor performance** and adjust timeouts as needed +5. **Explore more MCP servers** from the community + +--- + +**Having issues?** Check the [MCP troubleshooting guide](./tools/mcp-server.md#troubleshooting) or open an issue on GitHub. diff --git a/docs/tools/index.md b/docs/tools/index.md index 6c3cec3d..73d480df 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -54,4 +54,7 @@ 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. + - **[MCP Quick Start Guide](../mcp-quick-start.md)**: Get started with MCP in 5 minutes with practical examples + - **[MCP Example Configurations](../mcp-example-configs.md)**: Ready-to-use configurations for common scenarios + - **[MCP Testing & Validation](../mcp-testing-validation.md)**: Test and validate your MCP server setups - **[Sandboxing](../sandbox.md)**: Sandboxing isolates the model and its changes from your environment to reduce potential risk. From 17785c418d7555c257fc6ca389ebe51fac3c099d Mon Sep 17 00:00:00 2001 From: pomelo-nwu Date: Thu, 4 Dec 2025 18:26:05 +0800 Subject: [PATCH 02/40] feat: restructure docs --- .../assets/connected_devtools.png | Bin .../assets/gemini-screenshot.png | Bin .../assets/qwen-screenshot.png | Bin .../{ => developers}/assets/release_patch.png | Bin .../assets/theme-ansi-light.png | Bin docs/{ => developers}/assets/theme-ansi.png | Bin .../assets/theme-atom-one.png | Bin .../assets/theme-ayu-light.png | Bin docs/{ => developers}/assets/theme-ayu.png | Bin docs/{ => developers}/assets/theme-custom.png | Bin .../assets/theme-default-light.png | Bin .../{ => developers}/assets/theme-default.png | Bin .../{ => developers}/assets/theme-dracula.png | Bin .../assets/theme-github-light.png | Bin docs/{ => developers}/assets/theme-github.png | Bin .../assets/theme-google-light.png | Bin .../assets/theme-xcode-light.png | Bin docs/{ => developers}/cli/Uninstall.md | 0 docs/{ => developers}/cli/_meta.ts | 0 docs/{ => developers}/cli/authentication.md | 0 docs/{ => developers}/cli/commands.md | 0 docs/{ => developers}/cli/configuration-v1.md | 0 docs/{ => developers}/cli/configuration.md | 0 docs/{ => developers}/cli/index.md | 0 .../cli/keyboard-shortcuts.md | 0 docs/{ => developers}/cli/language.md | 0 docs/{ => developers}/cli/openai-auth.md | 0 docs/{ => developers}/cli/qwen-ignore.md | 0 docs/{ => developers}/cli/themes.md | 0 docs/{ => developers}/cli/trusted-folders.md | 0 docs/{ => developers}/cli/tutorials.md | 0 docs/{ => developers}/core/index.md | 0 docs/{ => developers}/core/memport.md | 0 docs/{ => developers}/core/tools-api.md | 0 docs/{ => developers}/development/_meta.ts | 0 .../development/architecture.md | 0 .../development/deployment.md | 0 .../development/integration-tests.md | 0 .../development/issue-and-pr-automation.md | 0 docs/{ => developers}/development/npm.md | 0 .../{ => developers}/development/telemetry.md | 0 .../{ => developers}/examples/proxy-script.md | 0 .../extensions/extension-releasing.md | 0 docs/{ => developers}/extensions/extension.md | 0 .../extensions/getting-started-extensions.md | 0 docs/{ => developers}/mermaid/context.mmd | 0 docs/{ => developers}/mermaid/render-path.mmd | 0 docs/{ => developers}/tools/_meta.ts | 0 docs/{ => developers}/tools/file-system.md | 0 docs/{ => developers}/tools/index.md | 0 docs/{ => developers}/tools/mcp-server.md | 0 docs/{ => developers}/tools/memory.md | 0 docs/{ => developers}/tools/multi-file.md | 0 docs/{ => developers}/tools/shell.md | 0 docs/{ => developers}/tools/todo-write.md | 0 docs/{ => developers}/tools/web-fetch.md | 0 docs/{ => developers}/tools/web-search.md | 0 docs/index.md | 344 ------------------ docs/sidebar.json | 68 ---- docs/{ => users}/features/_meta.ts | 0 docs/{ => users}/features/checkpointing.md | 0 docs/{ => users}/features/headless.md | 0 docs/{ => users}/features/sandbox.md | 0 docs/{ => users}/features/subagents.md | 0 docs/{ => users}/features/token-caching.md | 0 docs/{ => users}/features/welcome-back.md | 0 docs/{ => users}/ide-integration/_meta.ts | 0 .../ide-integration/ide-companion-spec.md | 0 .../ide-integration/ide-integration.md | 0 docs/{ => users}/support/_meta.ts | 0 docs/{ => users}/support/tos-privacy.md | 0 docs/{ => users}/support/troubleshooting.md | 0 72 files changed, 412 deletions(-) rename docs/{ => developers}/assets/connected_devtools.png (100%) rename docs/{ => developers}/assets/gemini-screenshot.png (100%) rename docs/{ => developers}/assets/qwen-screenshot.png (100%) rename docs/{ => developers}/assets/release_patch.png (100%) rename docs/{ => developers}/assets/theme-ansi-light.png (100%) rename docs/{ => developers}/assets/theme-ansi.png (100%) rename docs/{ => developers}/assets/theme-atom-one.png (100%) rename docs/{ => developers}/assets/theme-ayu-light.png (100%) rename docs/{ => developers}/assets/theme-ayu.png (100%) rename docs/{ => developers}/assets/theme-custom.png (100%) rename docs/{ => developers}/assets/theme-default-light.png (100%) rename docs/{ => developers}/assets/theme-default.png (100%) rename docs/{ => developers}/assets/theme-dracula.png (100%) rename docs/{ => developers}/assets/theme-github-light.png (100%) rename docs/{ => developers}/assets/theme-github.png (100%) rename docs/{ => developers}/assets/theme-google-light.png (100%) rename docs/{ => developers}/assets/theme-xcode-light.png (100%) rename docs/{ => developers}/cli/Uninstall.md (100%) rename docs/{ => developers}/cli/_meta.ts (100%) rename docs/{ => developers}/cli/authentication.md (100%) rename docs/{ => developers}/cli/commands.md (100%) rename docs/{ => developers}/cli/configuration-v1.md (100%) rename docs/{ => developers}/cli/configuration.md (100%) rename docs/{ => developers}/cli/index.md (100%) rename docs/{ => developers}/cli/keyboard-shortcuts.md (100%) rename docs/{ => developers}/cli/language.md (100%) rename docs/{ => developers}/cli/openai-auth.md (100%) rename docs/{ => developers}/cli/qwen-ignore.md (100%) rename docs/{ => developers}/cli/themes.md (100%) rename docs/{ => developers}/cli/trusted-folders.md (100%) rename docs/{ => developers}/cli/tutorials.md (100%) rename docs/{ => developers}/core/index.md (100%) rename docs/{ => developers}/core/memport.md (100%) rename docs/{ => developers}/core/tools-api.md (100%) rename docs/{ => developers}/development/_meta.ts (100%) rename docs/{ => developers}/development/architecture.md (100%) rename docs/{ => developers}/development/deployment.md (100%) rename docs/{ => developers}/development/integration-tests.md (100%) rename docs/{ => developers}/development/issue-and-pr-automation.md (100%) rename docs/{ => developers}/development/npm.md (100%) rename docs/{ => developers}/development/telemetry.md (100%) rename docs/{ => developers}/examples/proxy-script.md (100%) rename docs/{ => developers}/extensions/extension-releasing.md (100%) rename docs/{ => developers}/extensions/extension.md (100%) rename docs/{ => developers}/extensions/getting-started-extensions.md (100%) rename docs/{ => developers}/mermaid/context.mmd (100%) rename docs/{ => developers}/mermaid/render-path.mmd (100%) rename docs/{ => developers}/tools/_meta.ts (100%) rename docs/{ => developers}/tools/file-system.md (100%) rename docs/{ => developers}/tools/index.md (100%) rename docs/{ => developers}/tools/mcp-server.md (100%) rename docs/{ => developers}/tools/memory.md (100%) rename docs/{ => developers}/tools/multi-file.md (100%) rename docs/{ => developers}/tools/shell.md (100%) rename docs/{ => developers}/tools/todo-write.md (100%) rename docs/{ => developers}/tools/web-fetch.md (100%) rename docs/{ => developers}/tools/web-search.md (100%) delete mode 100644 docs/index.md delete mode 100644 docs/sidebar.json rename docs/{ => users}/features/_meta.ts (100%) rename docs/{ => users}/features/checkpointing.md (100%) rename docs/{ => users}/features/headless.md (100%) rename docs/{ => users}/features/sandbox.md (100%) rename docs/{ => users}/features/subagents.md (100%) rename docs/{ => users}/features/token-caching.md (100%) rename docs/{ => users}/features/welcome-back.md (100%) rename docs/{ => users}/ide-integration/_meta.ts (100%) rename docs/{ => users}/ide-integration/ide-companion-spec.md (100%) rename docs/{ => users}/ide-integration/ide-integration.md (100%) rename docs/{ => users}/support/_meta.ts (100%) rename docs/{ => users}/support/tos-privacy.md (100%) rename docs/{ => users}/support/troubleshooting.md (100%) diff --git a/docs/assets/connected_devtools.png b/docs/developers/assets/connected_devtools.png similarity index 100% rename from docs/assets/connected_devtools.png rename to docs/developers/assets/connected_devtools.png diff --git a/docs/assets/gemini-screenshot.png b/docs/developers/assets/gemini-screenshot.png similarity index 100% rename from docs/assets/gemini-screenshot.png rename to docs/developers/assets/gemini-screenshot.png diff --git a/docs/assets/qwen-screenshot.png b/docs/developers/assets/qwen-screenshot.png similarity index 100% rename from docs/assets/qwen-screenshot.png rename to docs/developers/assets/qwen-screenshot.png diff --git a/docs/assets/release_patch.png b/docs/developers/assets/release_patch.png similarity index 100% rename from docs/assets/release_patch.png rename to docs/developers/assets/release_patch.png diff --git a/docs/assets/theme-ansi-light.png b/docs/developers/assets/theme-ansi-light.png similarity index 100% rename from docs/assets/theme-ansi-light.png rename to docs/developers/assets/theme-ansi-light.png diff --git a/docs/assets/theme-ansi.png b/docs/developers/assets/theme-ansi.png similarity index 100% rename from docs/assets/theme-ansi.png rename to docs/developers/assets/theme-ansi.png diff --git a/docs/assets/theme-atom-one.png b/docs/developers/assets/theme-atom-one.png similarity index 100% rename from docs/assets/theme-atom-one.png rename to docs/developers/assets/theme-atom-one.png diff --git a/docs/assets/theme-ayu-light.png b/docs/developers/assets/theme-ayu-light.png similarity index 100% rename from docs/assets/theme-ayu-light.png rename to docs/developers/assets/theme-ayu-light.png diff --git a/docs/assets/theme-ayu.png b/docs/developers/assets/theme-ayu.png similarity index 100% rename from docs/assets/theme-ayu.png rename to docs/developers/assets/theme-ayu.png diff --git a/docs/assets/theme-custom.png b/docs/developers/assets/theme-custom.png similarity index 100% rename from docs/assets/theme-custom.png rename to docs/developers/assets/theme-custom.png diff --git a/docs/assets/theme-default-light.png b/docs/developers/assets/theme-default-light.png similarity index 100% rename from docs/assets/theme-default-light.png rename to docs/developers/assets/theme-default-light.png diff --git a/docs/assets/theme-default.png b/docs/developers/assets/theme-default.png similarity index 100% rename from docs/assets/theme-default.png rename to docs/developers/assets/theme-default.png diff --git a/docs/assets/theme-dracula.png b/docs/developers/assets/theme-dracula.png similarity index 100% rename from docs/assets/theme-dracula.png rename to docs/developers/assets/theme-dracula.png diff --git a/docs/assets/theme-github-light.png b/docs/developers/assets/theme-github-light.png similarity index 100% rename from docs/assets/theme-github-light.png rename to docs/developers/assets/theme-github-light.png diff --git a/docs/assets/theme-github.png b/docs/developers/assets/theme-github.png similarity index 100% rename from docs/assets/theme-github.png rename to docs/developers/assets/theme-github.png diff --git a/docs/assets/theme-google-light.png b/docs/developers/assets/theme-google-light.png similarity index 100% rename from docs/assets/theme-google-light.png rename to docs/developers/assets/theme-google-light.png diff --git a/docs/assets/theme-xcode-light.png b/docs/developers/assets/theme-xcode-light.png similarity index 100% rename from docs/assets/theme-xcode-light.png rename to docs/developers/assets/theme-xcode-light.png diff --git a/docs/cli/Uninstall.md b/docs/developers/cli/Uninstall.md similarity index 100% rename from docs/cli/Uninstall.md rename to docs/developers/cli/Uninstall.md diff --git a/docs/cli/_meta.ts b/docs/developers/cli/_meta.ts similarity index 100% rename from docs/cli/_meta.ts rename to docs/developers/cli/_meta.ts diff --git a/docs/cli/authentication.md b/docs/developers/cli/authentication.md similarity index 100% rename from docs/cli/authentication.md rename to docs/developers/cli/authentication.md diff --git a/docs/cli/commands.md b/docs/developers/cli/commands.md similarity index 100% rename from docs/cli/commands.md rename to docs/developers/cli/commands.md diff --git a/docs/cli/configuration-v1.md b/docs/developers/cli/configuration-v1.md similarity index 100% rename from docs/cli/configuration-v1.md rename to docs/developers/cli/configuration-v1.md diff --git a/docs/cli/configuration.md b/docs/developers/cli/configuration.md similarity index 100% rename from docs/cli/configuration.md rename to docs/developers/cli/configuration.md diff --git a/docs/cli/index.md b/docs/developers/cli/index.md similarity index 100% rename from docs/cli/index.md rename to docs/developers/cli/index.md diff --git a/docs/cli/keyboard-shortcuts.md b/docs/developers/cli/keyboard-shortcuts.md similarity index 100% rename from docs/cli/keyboard-shortcuts.md rename to docs/developers/cli/keyboard-shortcuts.md diff --git a/docs/cli/language.md b/docs/developers/cli/language.md similarity index 100% rename from docs/cli/language.md rename to docs/developers/cli/language.md diff --git a/docs/cli/openai-auth.md b/docs/developers/cli/openai-auth.md similarity index 100% rename from docs/cli/openai-auth.md rename to docs/developers/cli/openai-auth.md diff --git a/docs/cli/qwen-ignore.md b/docs/developers/cli/qwen-ignore.md similarity index 100% rename from docs/cli/qwen-ignore.md rename to docs/developers/cli/qwen-ignore.md diff --git a/docs/cli/themes.md b/docs/developers/cli/themes.md similarity index 100% rename from docs/cli/themes.md rename to docs/developers/cli/themes.md diff --git a/docs/cli/trusted-folders.md b/docs/developers/cli/trusted-folders.md similarity index 100% rename from docs/cli/trusted-folders.md rename to docs/developers/cli/trusted-folders.md diff --git a/docs/cli/tutorials.md b/docs/developers/cli/tutorials.md similarity index 100% rename from docs/cli/tutorials.md rename to docs/developers/cli/tutorials.md diff --git a/docs/core/index.md b/docs/developers/core/index.md similarity index 100% rename from docs/core/index.md rename to docs/developers/core/index.md diff --git a/docs/core/memport.md b/docs/developers/core/memport.md similarity index 100% rename from docs/core/memport.md rename to docs/developers/core/memport.md diff --git a/docs/core/tools-api.md b/docs/developers/core/tools-api.md similarity index 100% rename from docs/core/tools-api.md rename to docs/developers/core/tools-api.md diff --git a/docs/development/_meta.ts b/docs/developers/development/_meta.ts similarity index 100% rename from docs/development/_meta.ts rename to docs/developers/development/_meta.ts diff --git a/docs/development/architecture.md b/docs/developers/development/architecture.md similarity index 100% rename from docs/development/architecture.md rename to docs/developers/development/architecture.md diff --git a/docs/development/deployment.md b/docs/developers/development/deployment.md similarity index 100% rename from docs/development/deployment.md rename to docs/developers/development/deployment.md diff --git a/docs/development/integration-tests.md b/docs/developers/development/integration-tests.md similarity index 100% rename from docs/development/integration-tests.md rename to docs/developers/development/integration-tests.md diff --git a/docs/development/issue-and-pr-automation.md b/docs/developers/development/issue-and-pr-automation.md similarity index 100% rename from docs/development/issue-and-pr-automation.md rename to docs/developers/development/issue-and-pr-automation.md diff --git a/docs/development/npm.md b/docs/developers/development/npm.md similarity index 100% rename from docs/development/npm.md rename to docs/developers/development/npm.md diff --git a/docs/development/telemetry.md b/docs/developers/development/telemetry.md similarity index 100% rename from docs/development/telemetry.md rename to docs/developers/development/telemetry.md diff --git a/docs/examples/proxy-script.md b/docs/developers/examples/proxy-script.md similarity index 100% rename from docs/examples/proxy-script.md rename to docs/developers/examples/proxy-script.md diff --git a/docs/extensions/extension-releasing.md b/docs/developers/extensions/extension-releasing.md similarity index 100% rename from docs/extensions/extension-releasing.md rename to docs/developers/extensions/extension-releasing.md diff --git a/docs/extensions/extension.md b/docs/developers/extensions/extension.md similarity index 100% rename from docs/extensions/extension.md rename to docs/developers/extensions/extension.md diff --git a/docs/extensions/getting-started-extensions.md b/docs/developers/extensions/getting-started-extensions.md similarity index 100% rename from docs/extensions/getting-started-extensions.md rename to docs/developers/extensions/getting-started-extensions.md diff --git a/docs/mermaid/context.mmd b/docs/developers/mermaid/context.mmd similarity index 100% rename from docs/mermaid/context.mmd rename to docs/developers/mermaid/context.mmd diff --git a/docs/mermaid/render-path.mmd b/docs/developers/mermaid/render-path.mmd similarity index 100% rename from docs/mermaid/render-path.mmd rename to docs/developers/mermaid/render-path.mmd diff --git a/docs/tools/_meta.ts b/docs/developers/tools/_meta.ts similarity index 100% rename from docs/tools/_meta.ts rename to docs/developers/tools/_meta.ts diff --git a/docs/tools/file-system.md b/docs/developers/tools/file-system.md similarity index 100% rename from docs/tools/file-system.md rename to docs/developers/tools/file-system.md diff --git a/docs/tools/index.md b/docs/developers/tools/index.md similarity index 100% rename from docs/tools/index.md rename to docs/developers/tools/index.md diff --git a/docs/tools/mcp-server.md b/docs/developers/tools/mcp-server.md similarity index 100% rename from docs/tools/mcp-server.md rename to docs/developers/tools/mcp-server.md diff --git a/docs/tools/memory.md b/docs/developers/tools/memory.md similarity index 100% rename from docs/tools/memory.md rename to docs/developers/tools/memory.md diff --git a/docs/tools/multi-file.md b/docs/developers/tools/multi-file.md similarity index 100% rename from docs/tools/multi-file.md rename to docs/developers/tools/multi-file.md diff --git a/docs/tools/shell.md b/docs/developers/tools/shell.md similarity index 100% rename from docs/tools/shell.md rename to docs/developers/tools/shell.md diff --git a/docs/tools/todo-write.md b/docs/developers/tools/todo-write.md similarity index 100% rename from docs/tools/todo-write.md rename to docs/developers/tools/todo-write.md diff --git a/docs/tools/web-fetch.md b/docs/developers/tools/web-fetch.md similarity index 100% rename from docs/tools/web-fetch.md rename to docs/developers/tools/web-fetch.md diff --git a/docs/tools/web-search.md b/docs/developers/tools/web-search.md similarity index 100% rename from docs/tools/web-search.md rename to docs/developers/tools/web-search.md diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 07fc1db6..00000000 --- a/docs/index.md +++ /dev/null @@ -1,344 +0,0 @@ -# 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`** (aliases: `/reset`, `/new`) - Clear conversation history, start a fresh session, and free up context -- **`/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` (aliases: `/reset`, `/new`) - Clear conversation history and start a fresh session -- `/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/sidebar.json b/docs/sidebar.json deleted file mode 100644 index b4a75052..00000000 --- a/docs/sidebar.json +++ /dev/null @@ -1,68 +0,0 @@ -[ - { - "label": "Overview", - "items": [ - { "label": "Welcome", "slug": "docs" }, - { "label": "Execution and Deployment", "slug": "docs/deployment" }, - { "label": "Architecture Overview", "slug": "docs/architecture" } - ] - }, - { - "label": "CLI", - "items": [ - { "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" } - ] - }, - { - "label": "Core", - "items": [ - { "label": "Introduction", "slug": "docs/core" }, - { "label": "Tools API", "slug": "docs/core/tools-api" }, - { "label": "Memory Import Processor", "slug": "docs/core/memport" } - ] - }, - { - "label": "Tools", - "items": [ - { "label": "Overview", "slug": "docs/tools" }, - { "label": "File System", "slug": "docs/tools/file-system" }, - { "label": "Multi-File Read", "slug": "docs/tools/multi-file" }, - { "label": "Shell", "slug": "docs/tools/shell" }, - { "label": "Web Fetch", "slug": "docs/tools/web-fetch" }, - { "label": "Web Search", "slug": "docs/tools/web-search" }, - { "label": "Memory", "slug": "docs/tools/memory" }, - { "label": "MCP Servers", "slug": "docs/tools/mcp-server" }, - { "label": "Sandboxing", "slug": "docs/sandbox" } - ] - }, - { - "label": "Development", - "items": [ - { "label": "NPM", "slug": "docs/npm" }, - { "label": "Releases", "slug": "docs/releases" } - ] - }, - { - "label": "Support", - "items": [ - { "label": "Troubleshooting", "slug": "docs/troubleshooting" }, - { "label": "Terms of Service", "slug": "docs/tos-privacy" } - ] - } -] diff --git a/docs/features/_meta.ts b/docs/users/features/_meta.ts similarity index 100% rename from docs/features/_meta.ts rename to docs/users/features/_meta.ts diff --git a/docs/features/checkpointing.md b/docs/users/features/checkpointing.md similarity index 100% rename from docs/features/checkpointing.md rename to docs/users/features/checkpointing.md diff --git a/docs/features/headless.md b/docs/users/features/headless.md similarity index 100% rename from docs/features/headless.md rename to docs/users/features/headless.md diff --git a/docs/features/sandbox.md b/docs/users/features/sandbox.md similarity index 100% rename from docs/features/sandbox.md rename to docs/users/features/sandbox.md diff --git a/docs/features/subagents.md b/docs/users/features/subagents.md similarity index 100% rename from docs/features/subagents.md rename to docs/users/features/subagents.md diff --git a/docs/features/token-caching.md b/docs/users/features/token-caching.md similarity index 100% rename from docs/features/token-caching.md rename to docs/users/features/token-caching.md diff --git a/docs/features/welcome-back.md b/docs/users/features/welcome-back.md similarity index 100% rename from docs/features/welcome-back.md rename to docs/users/features/welcome-back.md diff --git a/docs/ide-integration/_meta.ts b/docs/users/ide-integration/_meta.ts similarity index 100% rename from docs/ide-integration/_meta.ts rename to docs/users/ide-integration/_meta.ts diff --git a/docs/ide-integration/ide-companion-spec.md b/docs/users/ide-integration/ide-companion-spec.md similarity index 100% rename from docs/ide-integration/ide-companion-spec.md rename to docs/users/ide-integration/ide-companion-spec.md diff --git a/docs/ide-integration/ide-integration.md b/docs/users/ide-integration/ide-integration.md similarity index 100% rename from docs/ide-integration/ide-integration.md rename to docs/users/ide-integration/ide-integration.md diff --git a/docs/support/_meta.ts b/docs/users/support/_meta.ts similarity index 100% rename from docs/support/_meta.ts rename to docs/users/support/_meta.ts diff --git a/docs/support/tos-privacy.md b/docs/users/support/tos-privacy.md similarity index 100% rename from docs/support/tos-privacy.md rename to docs/users/support/tos-privacy.md diff --git a/docs/support/troubleshooting.md b/docs/users/support/troubleshooting.md similarity index 100% rename from docs/support/troubleshooting.md rename to docs/users/support/troubleshooting.md From bfe8133ea3f2108984d1481e63220e716c21f3af Mon Sep 17 00:00:00 2001 From: pomelo-nwu Date: Fri, 5 Dec 2025 10:51:57 +0800 Subject: [PATCH 03/40] feat: refactor docs --- docs/_meta.ts | 20 +++++++------ docs/developers/_meta.ts | 23 +++++++++++++++ .../{development => }/architecture.md | 0 docs/developers/cli/_meta.ts | 5 ---- docs/developers/contributing.md | 0 docs/developers/development/_meta.ts | 2 -- docs/developers/roadmap.md | 1 + docs/index.md | 0 docs/users/_meta.ts | 28 +++++++++++++++++++ docs/users/common-workflow.md | 0 docs/users/configuration/_meta.ts | 7 +++++ docs/users/configuration/memory.md | 0 .../configuration}/qwen-ignore.md | 0 docs/users/configuration/settings.md | 0 .../cli => users/configuration}/themes.md | 0 .../configuration}/trusted-folders.md | 0 docs/users/features/_meta.ts | 13 +++++++-- docs/users/features/approval-mode.md | 0 docs/users/features/mcp.md | 0 docs/users/features/sub-commands.md | 0 docs/users/integration-github-action.md | 0 docs/users/integration-vscode.md | 0 docs/users/integration-zed.md | 0 docs/users/overview.md | 0 docs/users/quick-start.md | 0 docs/users/reference/_meta.ts | 3 ++ .../reference}/keyboard-shortcuts.md | 0 .../cli => users/support}/Uninstall.md | 0 docs/users/support/_meta.ts | 2 ++ 29 files changed, 86 insertions(+), 18 deletions(-) create mode 100644 docs/developers/_meta.ts rename docs/developers/{development => }/architecture.md (100%) create mode 100644 docs/developers/contributing.md create mode 100644 docs/developers/roadmap.md create mode 100644 docs/index.md create mode 100644 docs/users/_meta.ts create mode 100644 docs/users/common-workflow.md create mode 100644 docs/users/configuration/_meta.ts create mode 100644 docs/users/configuration/memory.md rename docs/{developers/cli => users/configuration}/qwen-ignore.md (100%) create mode 100644 docs/users/configuration/settings.md rename docs/{developers/cli => users/configuration}/themes.md (100%) rename docs/{developers/cli => users/configuration}/trusted-folders.md (100%) create mode 100644 docs/users/features/approval-mode.md create mode 100644 docs/users/features/mcp.md create mode 100644 docs/users/features/sub-commands.md create mode 100644 docs/users/integration-github-action.md create mode 100644 docs/users/integration-vscode.md create mode 100644 docs/users/integration-zed.md create mode 100644 docs/users/overview.md create mode 100644 docs/users/quick-start.md create mode 100644 docs/users/reference/_meta.ts rename docs/{developers/cli => users/reference}/keyboard-shortcuts.md (100%) rename docs/{developers/cli => users/support}/Uninstall.md (100%) diff --git a/docs/_meta.ts b/docs/_meta.ts index 4939cb31..10f50a10 100644 --- a/docs/_meta.ts +++ b/docs/_meta.ts @@ -1,10 +1,14 @@ export default { - index: 'Welcome to Qwen Code', - cli: 'CLI', - core: 'Core', - tools: 'Tools', - features: 'Features', - 'ide-integration': 'IDE Integration', - development: 'Development', - support: 'Support', + index: { + type: 'page', + display: 'hidden', + }, + users: { + type: 'page', + title: 'User Guide', + }, + developers: { + type: 'page', + title: 'Developer Guide', + }, }; diff --git a/docs/developers/_meta.ts b/docs/developers/_meta.ts new file mode 100644 index 00000000..b73a4b9e --- /dev/null +++ b/docs/developers/_meta.ts @@ -0,0 +1,23 @@ +export default { + 'Contribute to Qwen Code': { + title: 'Contribute to Qwen Code', + type: 'separator', + }, + architecture: 'Architecture', + contributing: 'Contributing Guide', + roadmap: 'Roadmap', + 'Qwen Code SDK': { + title: 'Qwen Code SDK', + type: 'separator', + }, + 'Dive Into Qwen Code': { + title: 'Dive Into Qwen Code', + type: 'separator', + }, + cli: { + display: 'hidden', + }, + core: 'Core', + tools: 'Tools', + // development: 'Development', +}; diff --git a/docs/developers/development/architecture.md b/docs/developers/architecture.md similarity index 100% rename from docs/developers/development/architecture.md rename to docs/developers/architecture.md diff --git a/docs/developers/cli/_meta.ts b/docs/developers/cli/_meta.ts index 1557b595..2f80cc41 100644 --- a/docs/developers/cli/_meta.ts +++ b/docs/developers/cli/_meta.ts @@ -5,12 +5,7 @@ export default { 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', }; /** diff --git a/docs/developers/contributing.md b/docs/developers/contributing.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/developers/development/_meta.ts b/docs/developers/development/_meta.ts index 6428e766..c6d99614 100644 --- a/docs/developers/development/_meta.ts +++ b/docs/developers/development/_meta.ts @@ -1,7 +1,5 @@ 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/developers/roadmap.md b/docs/developers/roadmap.md new file mode 100644 index 00000000..4213424a --- /dev/null +++ b/docs/developers/roadmap.md @@ -0,0 +1 @@ +# Qwen Code RoadMap diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/users/_meta.ts b/docs/users/_meta.ts new file mode 100644 index 00000000..d932d41c --- /dev/null +++ b/docs/users/_meta.ts @@ -0,0 +1,28 @@ +export default { + 'Getting started': { + type: 'separator', + title: 'Getting started', // Title is optional + }, + overview: 'Overview', + 'quick-start': 'QuickStart', + 'common-workflow': 'Command Workflows', + 'Outside of the terminal': { + type: 'separator', + title: 'Outside of the terminal', // Title is optional + }, + 'integration-github-action': 'Github Action', + 'integration-vscode': 'VSCode Extension', + 'integration-zed': 'Zed IDE', + 'Code with Qwen Code': { + type: 'separator', + title: 'Code with Qwen Code', // Title is optional + }, + features: 'Features', + configuration: 'Configuration', + reference: 'Reference', + support: 'Support', + // need refine + 'ide-integration': { + display: 'hidden', + }, +}; diff --git a/docs/users/common-workflow.md b/docs/users/common-workflow.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/users/configuration/_meta.ts b/docs/users/configuration/_meta.ts new file mode 100644 index 00000000..f8f17c07 --- /dev/null +++ b/docs/users/configuration/_meta.ts @@ -0,0 +1,7 @@ +export default { + settings: 'Settings File', + memory: 'Memory Management', + 'trusted-folders': 'Trusted Folders', + 'qwen-ignore': 'Ignoring Files', + themes: 'Themes', +}; diff --git a/docs/users/configuration/memory.md b/docs/users/configuration/memory.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/developers/cli/qwen-ignore.md b/docs/users/configuration/qwen-ignore.md similarity index 100% rename from docs/developers/cli/qwen-ignore.md rename to docs/users/configuration/qwen-ignore.md diff --git a/docs/users/configuration/settings.md b/docs/users/configuration/settings.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/developers/cli/themes.md b/docs/users/configuration/themes.md similarity index 100% rename from docs/developers/cli/themes.md rename to docs/users/configuration/themes.md diff --git a/docs/developers/cli/trusted-folders.md b/docs/users/configuration/trusted-folders.md similarity index 100% rename from docs/developers/cli/trusted-folders.md rename to docs/users/configuration/trusted-folders.md diff --git a/docs/users/features/_meta.ts b/docs/users/features/_meta.ts index 7ad3361c..39736dfc 100644 --- a/docs/users/features/_meta.ts +++ b/docs/users/features/_meta.ts @@ -1,8 +1,15 @@ export default { subagents: 'Subagents', - checkpointing: 'Checkpointing', - sandbox: 'Sandbox Support', + 'sub-commands': 'Sub Commands', + checkpointing: { + display: 'hidden', + }, headless: 'Headless Mode', - 'welcome-back': 'Welcome Back', + 'welcome-back': { + display: 'hidden', + }, + 'approval-mode': 'Approval Mode', 'token-caching': 'Token Caching', + mcp: 'MCP', + sandbox: 'Sandboxing', }; diff --git a/docs/users/features/approval-mode.md b/docs/users/features/approval-mode.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/users/features/mcp.md b/docs/users/features/mcp.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/users/features/sub-commands.md b/docs/users/features/sub-commands.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/users/integration-github-action.md b/docs/users/integration-github-action.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/users/integration-vscode.md b/docs/users/integration-vscode.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/users/integration-zed.md b/docs/users/integration-zed.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/users/overview.md b/docs/users/overview.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/users/quick-start.md b/docs/users/quick-start.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/users/reference/_meta.ts b/docs/users/reference/_meta.ts new file mode 100644 index 00000000..a4c232e8 --- /dev/null +++ b/docs/users/reference/_meta.ts @@ -0,0 +1,3 @@ +export default { + 'keyboard-shortcuts': 'Keyboard Shortcuts', +}; diff --git a/docs/developers/cli/keyboard-shortcuts.md b/docs/users/reference/keyboard-shortcuts.md similarity index 100% rename from docs/developers/cli/keyboard-shortcuts.md rename to docs/users/reference/keyboard-shortcuts.md diff --git a/docs/developers/cli/Uninstall.md b/docs/users/support/Uninstall.md similarity index 100% rename from docs/developers/cli/Uninstall.md rename to docs/users/support/Uninstall.md diff --git a/docs/users/support/_meta.ts b/docs/users/support/_meta.ts index 9140d4fe..1407565a 100644 --- a/docs/users/support/_meta.ts +++ b/docs/users/support/_meta.ts @@ -1,4 +1,6 @@ export default { troubleshooting: 'Troubleshooting', 'tos-privacy': 'Terms of Service', + + Uninstall: 'Uninstall', }; From d2ed3e73f4416379126c222d34187bad6910c422 Mon Sep 17 00:00:00 2001 From: Joeytoday Date: Fri, 5 Dec 2025 11:50:44 +0800 Subject: [PATCH 04/40] docs: update overview docs --- docs/users/overview.md | 127 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) diff --git a/docs/users/overview.md b/docs/users/overview.md index e69de29b..552d7e26 100644 --- a/docs/users/overview.md +++ b/docs/users/overview.md @@ -0,0 +1,127 @@ +# Qwen Code overview + +> Learn about Qwen Code, Anthropic's agentic coding tool that lives in your terminal and helps you turn ideas into code faster than ever before. + +## Get started in 30 seconds + +Prerequisites: + +* A [Claude.ai](https://claude.ai) (recommended) or [Claude Console](https://console.anthropic.com/) account + +**Install Qwen Code:** + + + + ```bash theme={null} + curl -fsSL https://claude.ai/install.sh | bash + ```q + + + + ```bash theme={null} + brew install --cask claude-code + ``` + + + + ```powershell theme={null} + irm https://claude.ai/install.ps1 | iex + ``` + + + + ```bash theme={null} + npm install -g @anthropic-ai/claude-code + ``` + + Requires [Node.js 18+](https://nodejs.org/en/download/) + + + +**Start using Qwen Code:** + +```bash theme={null} +cd your-project +claude +``` + +You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 mins) →](/en/quickstart) + + + See [advanced setup](/en/setup) for installation options or [troubleshooting](/en/troubleshooting) if you hit issues. + + + + **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new [VS Code extension](/en/vs-code) provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Claude directly in your sidebar. + + +## What Qwen Code does for you + +* **Build features from descriptions**: Tell Claude what you want to build in plain English. It will make a plan, write the code, and ensure it works. +* **Debug and fix issues**: Describe a bug or paste an error message. Qwen Code will analyze your codebase, identify the problem, and implement a fix. +* **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Qwen Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](/en/mcp) can pull from external datasources like Google Drive, Figma, and Slack. +* **Automate tedious tasks**: Fix fiddly lint issues, resolve merge conflicts, and write release notes. Do all this in a single command from your developer machines, or automatically in CI. + +## Why developers love Qwen Code + +* **Works in your terminal**: Not another chat window. Not another IDE. Qwen Code meets you where you already work, with the tools you already love. +* **Takes action**: Qwen Code can directly edit files, run commands, and create commits. Need more? [MCP](/en/mcp) lets Claude read your design docs in Google Drive, update your tickets in Jira, or use *your* custom developer tooling. +* **Unix philosophy**: Qwen Code is composable and scriptable. `tail -f app.log | claude -p "Slack me if you see any anomalies appear in this log stream"` *works*. Your CI can run `claude -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`. +* **Enterprise-ready**: Use the Claude API, or host on AWS or GCP. Enterprise-grade [security](/en/security), [privacy](/en/data-usage), and [compliance](https://trust.anthropic.com/) is built-in. + +## Next steps + + + + See Qwen Code in action with practical examples + + + + Step-by-step guides for common workflows + + + + Solutions for common issues with Qwen Code + + + + Add Qwen Code to your IDE + + + +## Additional resources + + + + Create custom AI agents with the Claude Agent SDK + + + + Configure Qwen Code with Amazon Bedrock or Google Vertex AI + + + + Customize Qwen Code for your workflow + + + + Learn about CLI commands and controls + + + + Clone our development container reference implementation + + + + Discover Qwen Code's safeguards and best practices for safe usage + + + + Understand how Qwen Code handles your data + + + + +--- + +> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt \ No newline at end of file From 0a8281f2dd94937f6e36dd09b8f0828519f63ff6 Mon Sep 17 00:00:00 2001 From: xuewenjie Date: Mon, 8 Dec 2025 10:58:50 +0800 Subject: [PATCH 05/40] fix: handle case-insensitive path comparison in glob tool on Windows --- packages/core/src/tools/glob.test.ts | 36 ++++++++++++++++++++++++++++ packages/core/src/tools/glob.ts | 11 +++++++-- 2 files changed, 45 insertions(+), 2 deletions(-) diff --git a/packages/core/src/tools/glob.test.ts b/packages/core/src/tools/glob.test.ts index 3729c251..ecfc27d9 100644 --- a/packages/core/src/tools/glob.test.ts +++ b/packages/core/src/tools/glob.test.ts @@ -198,6 +198,42 @@ describe('GlobTool', () => { ); }); + it('should find files even if workspace path casing differs from glob results (Windows)', async () => { + // Only relevant for Windows + if (process.platform !== 'win32') { + return; + } + + // 1. Create a path with mismatched casing for the workspace root + // e.g., if tempRootDir is "C:\Users\...", make it "c:\Users\..." + const drive = path.parse(tempRootDir).root; + if (!drive || !drive.match(/^[A-Z]:\\/)) { + // Skip if we can't determine/manipulate the drive letter easily + return; + } + + const lowerDrive = drive.toLowerCase(); + const mismatchedRootDir = + lowerDrive + tempRootDir.substring(drive.length); + + // 2. Create a new GlobTool instance with this mismatched root + const mismatchedConfig = { + ...mockConfig, + getTargetDir: () => mismatchedRootDir, + getWorkspaceContext: () => + createMockWorkspaceContext(mismatchedRootDir), + } as unknown as Config; + + const mismatchedGlobTool = new GlobTool(mismatchedConfig); + + // 3. Execute search + const params: GlobToolParams = { pattern: '*.txt' }; + const invocation = mismatchedGlobTool.build(params); + const result = await invocation.execute(abortSignal); + + expect(result.llmContent).toContain('Found 2 file(s)'); + }); + it('should return error if path is outside workspace', async () => { // Bypassing validation to test execute method directly vi.spyOn(globTool, 'validateToolParams').mockReturnValue(null); diff --git a/packages/core/src/tools/glob.ts b/packages/core/src/tools/glob.ts index 29b6cf86..38cc0de9 100644 --- a/packages/core/src/tools/glob.ts +++ b/packages/core/src/tools/glob.ts @@ -134,12 +134,19 @@ class GlobToolInvocation extends BaseToolInvocation< this.getFileFilteringOptions(), ); + const normalizePathForComparison = (p: string) => + process.platform === 'win32' ? p.toLowerCase() : p; + const filteredAbsolutePaths = new Set( - filteredPaths.map((p) => path.resolve(this.config.getTargetDir(), p)), + filteredPaths.map((p) => + normalizePathForComparison( + path.resolve(this.config.getTargetDir(), p), + ), + ), ); const filteredEntries = allEntries.filter((entry) => - filteredAbsolutePaths.has(entry.fullpath()), + filteredAbsolutePaths.has(normalizePathForComparison(entry.fullpath())), ); if (!filteredEntries || filteredEntries.length === 0) { From f7b94f9b634c9aad31107513105c1387534d3b6f Mon Sep 17 00:00:00 2001 From: joeytoday Date: Mon, 8 Dec 2025 17:48:39 +0800 Subject: [PATCH 06/40] docs: update overview and common workflows, add quickstart guide --- docs/users/common-workflow.md | 819 ++++++++++++++++++++++++++++++++++ docs/users/overview.md | 139 +++--- docs/users/quick-start.md | 0 docs/users/quickstart.md | 312 +++++++++++++ 4 files changed, 1201 insertions(+), 69 deletions(-) delete mode 100644 docs/users/quick-start.md create mode 100644 docs/users/quickstart.md diff --git a/docs/users/common-workflow.md b/docs/users/common-workflow.md index e69de29b..554292a5 100644 --- a/docs/users/common-workflow.md +++ b/docs/users/common-workflow.md @@ -0,0 +1,819 @@ + +# Common workflows + +> Learn about common workflows with Qwen Code. + +Each task in this document includes clear instructions, example commands, and best practices to help you get the most from Qwen Code. + +## Understand new codebases + +### Get a quick codebase overview + +Suppose you've just joined a new project and need to understand its structure quickly. + +1. Navigate to the project root directory + +```bash +cd /path/to/project +``` + +2. Start Qwen Code + +```bash +qwen +``` + +3. Ask for a high-level overview + +``` +give me an overview of this codebase +``` + +4. Dive deeper into specific components + +``` +explain the main architecture patterns used here +``` + +``` +what are the key data models? +``` + +``` +how is authentication handled? +``` + +> [!tip] Tips: +> +> - Start with broad questions, then narrow down to specific areas +> - Ask about coding conventions and patterns used in the project +> - Request a glossary of project-specific terms + + +### Find relevant code + +Suppose you need to locate code related to a specific feature or functionality. + +1. Ask Qwen Code to find relevant files + +``` +find the files that handle user authentication +``` + +2. Get context on how components interact + +``` +how do these authentication files work together? +``` + +3. Understand the execution flow + +``` +trace the login process from front-end to database +``` + +> [!tip] Tips +> +> - Be specific about what you're looking for +> - Use domain language from the project + +## Fix bugs efficiently + +Suppose you've encountered an error message and need to find and fix its source. + +1. Share the error with Qwen Code +``` +I'm seeing an error when I run npm test +``` + +2. Ask for fix recommendations +``` +suggest a few ways to fix the @ts-ignore in user. ts +``` + +3. Apply the fix +``` +update user. ts to add the null check you suggested +``` + +> [!tip] Tips: +> +> - Tell Qwen Code the command to reproduce the issue and get a stack trace +> - Mention any steps to reproduce the error +> - Let Qwen Code know if the error is intermittent or consistent + +## Refactor code + +Suppose you need to update old code to use modern patterns and practices. + +1. Identify legacy code for refactoring + +``` +find deprecated API usage in our codebase +``` + +2. Get refactoring recommendations + +``` +suggest how to refactor utils.js to use modern JavaScript features +``` + +3. Apply the changes safely + +``` +refactor utils.js to use ES 2024 features while maintaining the same behavior +``` + +4. Verify the refactoring + +``` +run tests for the refactored code +``` + +> [!tip] Tips: +> +> - Ask Qwen Code to explain the benefits of the modern approach +> - Request that changes maintain backward compatibility when needed +> - Do refactoring in small, testable increments + +## Use specialized subagents + +Suppose you want to use specialized AI subagents to handle specific tasks more effectively. + +1. View available subagents + +``` +/agents +``` + +This shows all available subagents and lets you create new ones. + +2. Use subagents automatically + +Qwen Code automatically delegates appropriate tasks to specialized subagents: + +``` +review my recent code changes for security issues +``` + +``` +run all tests and fix any failures +``` + +3. Explicitly request specific subagents + +``` +use the code-reviewer subagent to check the auth module +``` + +``` +have the debugger subagent investigate why users can't log in +``` + +4. Create custom subagents for your workflow + +``` +/agents +``` + +Then select "Create New subagent" and follow the prompts to define: + +- A unique identifier that describes the subagent's purpose (for example, `code-reviewer`, `api-designer`). +- When Qwen Code should use this agent +- Which tools it can access +- A system prompt describing the agent's role and behavior + +> [!tip] Tips: +> +> - Create project-specific subagents in `.qwen-code/agents/` for team sharing +> - Use descriptive `description` fields to enable automatic delegation +> - Limit tool access to what each subagent actually needs +> - Check the [subagents documentation](/sub-agents) for detailed examples + + +## Use Plan Mode for safe code analysis + +Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely. + +### When to use Plan Mode + +- **Multi-step implementation**: When your feature requires making edits to many files +- **Code exploration**: When you want to research the codebase thoroughly before changing anything +- **Interactive development**: When you want to iterate on the direction with Qwen Code + +### How to use Plan Mode + +**Turn on Plan Mode during a session** + +You can switch into Plan Mode during a session using **Shift+Tab** to cycle through permission modes. + +If you are in Normal Mode, **Shift+Tab** first switches into Auto-Accept Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** will switch into Plan Mode, indicated by `⏸ plan mode`. + +**Start a new session in Plan Mode** + +To start a new session in Plan Mode, use the `/approval-mode` then select `plan` + +```bash +/approval-mode +``` + +**Run "headless" queries in Plan Mode** + +You can also run a query in Plan Mode directly with `-p` (that is, in ["headless mode"](/en/headless)): + +```bash +/approval-mode plan -p "Analyze the authentication system and suggest improvements" +``` + +### Example: Planning a complex refactor + +```bash +/approval-mode plan +``` + +``` +I need to refactor our authentication system to use OAuth2. Create a detailed migration plan. +``` + +Qwen Code analyzes the current implementation and create a comprehensive plan. Refine with follow-ups: + +``` +What about backward compatibility? +How should we handle database migration? +``` + +### Configure Plan Mode as default + +```json +// .qwen-code/settings.json +{ + "permissions": { + "defaultMode": "plan" + } +} +``` + +See [settings documentation](/en/settings#available-settings) for more configuration options. + +## Work with tests + +Suppose you need to add tests for uncovered code. + +1. Identify untested code + +``` +find functions in NotificationsService. swift that are not covered by tests +``` + +2. Generate test scaffolding +``` +add tests for the notification service +``` + +3. Add meaningful test cases +``` +add test cases for edge conditions in the notification service +``` + +4. Run and verify tests +``` +run the new tests and fix any failures +``` + +Qwen Code can generate tests that follow your project's existing patterns and conventions. When asking for tests, be specific about what behavior you want to verify. Qwen Code examines your existing test files to match the style, frameworks, and assertion patterns already in use. + +For comprehensive coverage, ask Qwen Code to identify edge cases you might have missed. Qwen Code can analyze your code paths and suggest tests for error conditions, boundary values, and unexpected inputs that are easy to overlook. + +## Create pull requests + +Suppose you need to create a well-documented pull request for your changes. + +1. Summarize your changes +``` +summarize the changes I've made to the authentication module +``` + + 2. Generate a pull request with Qwen Code +``` +create a pr +``` + + 3. Review and refine +``` +enhance the PR description with more context about the security improvements +``` + + 4. Add testing details +``` +add information about how these changes were tested +``` + +> [!tip] Tips: +> +> - Ask Qwen Code directly to make a PR for you +> - Review Qwen Code's generated PR before submitting +> - Ask Qwen Code to highlight potential risks or considerations + +## Handle documentation + +Suppose you need to add or update documentation for your code. + +1. Identify undocumented code +``` +find functions without proper JSDoc comments in the auth module +``` + + 2. Generate documentation +``` +add JSDoc comments to the undocumented functions in auth.js +``` + + 3. Review and enhance +``` +improve the generated documentation with more context and examples +``` + + 4. Verify documentation +``` +> check if the documentation follows our project standards +``` + +> [!tip] Tips: +> +> - Specify the documentation style you want (JSDoc, docstrings, etc.) +> - Ask for examples in the documentation +> - Request documentation for public APIs, interfaces, and complex logic + +## Work with images + +Suppose you need to work with images in your codebase, and you want Qwen Code's help analyzing image content. + +1. Add an image to the conversation + +You can use any of these methods: + +1) Drag and drop an image into the Qwen Code window +2) Copy an image and paste it into the CLI with ctrl+v (Do not use cmd+v) +3) Provide an image path to Claude. E.g., "Analyze this image: /path/to/your/image. png" + + 3. Ask Claude to analyze the image +``` +What does this image show? +``` + +``` +Describe the UI elements in this screenshot +``` + +``` +Are there any problematic elements in this diagram? +``` + + 3. Use images for context +``` +Here's a screenshot of the error. What's causing it? +``` + +``` +This is our current database schema. How should we modify it for the new feature? +``` + +4. Get code suggestions from visual content +``` +Generate CSS to match this design mockup +``` + +``` +What HTML structure would recreate this component? +``` + +> [!tip] Tips: +> +> - Use images when text descriptions would be unclear or cumbersome +> - Include screenshots of errors, UI designs, or diagrams for better context +> - You can work with multiple images in a conversation +> - Image analysis works with diagrams, screenshots, mockups, and more + + +## Reference files and directories + +Use `@` to quickly include files or directories without waiting for Qwen Code to read them. + +1. Reference a single file +``` +Explain the logic in @src/utils/auth.js +``` + +This includes the full content of the file in the conversation. + + 2. Reference a directory +``` +What's the structure of @src/components? +``` + +This provides a directory listing with file information. + + 3. Reference MCP resources +``` +Show me the data from @github: repos/owner/repo/issues +``` + +This fetches data from connected MCP servers using the format @server: resource. See [MCP resources](/en/mcp#use-mcp-resources) for details. + +> [!tip] Tips: +> +> - File paths can be relative or absolute +> - @ file references add `QWEN.md` in the file's directory and parent directories to context +> - Directory references show file listings, not contents +> - You can reference multiple files in a single message (for example, "`@file 1.js` and `@file 2.js`") + + +## Use extended thinking + +Suppose you're working on complex architectural decisions, challenging bugs, or planning multi-step implementations that require deep reasoning. + +> [!note] +> +> [Extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) is disabled by default in Qwen Code. You can enable it on-demand by using `Tab` to toggle Thinking on, or by using prompts like "think" or "think hard". You can also enable it permanently by setting the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) in your settings. + +1. Provide context and ask Qwen Code to think +``` +I need to implement a new authentication system using OAuth 2 for our API. Think deeply about the best approach for implementing this in our codebase. +``` + +Qwen Code gathers relevant information from your codebase and uses extended thinking, which is visible in the interface. + + 2. Refine the thinking with follow-up prompts +``` +think about potential security vulnerabilities in this approach +``` + +``` +think hard about edge cases we should handle +``` + +> [!tip] +> Tips to get the most value out of extended thinking: +> +> [Extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) is most valuable for complex tasks such as: +> +> - Planning complex architectural changes +> - Debugging intricate issues +> - Creating implementation plans for new features +> - Understanding complex codebases +> - Evaluating tradeoffs between different approaches +> +> Use `Tab` to toggle Thinking on and off during a session. +> +> The way you prompt for thinking results in varying levels of thinking depth: +> +> - "think" triggers basic extended thinking +> - intensifying phrases such as "keep hard", "think more", "think a lot", or "think longer" triggers deeper thinking +> +> For more extended thinking prompting tips, see [Extended thinking tips](https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/extended-thinking-tips). + +> [!note] +> Qwen Code displays its thinking process as italic gray text above the response. + +## Resume previous conversations + +Suppose you've been working on a task with Qwen Code and need to continue where you left off in a later session. + +Qwen Code provides two options for resuming previous conversations: + + - `--continue` to automatically continue the most recent conversation + - `--resume` to display a conversation picker + +1. Continue the most recent conversation + +```bash +qwen-code --continue +``` + +This immediately resumes your most recent conversation without any prompts. + +2. Continue in non-interactive mode + +```bash +qwen-code --continue --print "Continue with my task" +``` + +Use `--print` with `--continue` to resume the most recent conversation in non-interactive mode, perfect for scripts or automation. + +3. Show conversation picker + +```bash +qwen-code --resume +``` + +This displays an interactive conversation selector with a clean list view showing: + +- Session summary (or initial prompt) +- Metadata: time elapsed, message count, and git branch + +Use arrow keys to navigate and press Enter to select a conversation. Press Esc to exit. + +> [!tip] Tips: +> +> - Conversation history is stored locally on your machine +> - Use `--continue` for quick access to your most recent conversation +> - Use `--resume` when you need to select a specific past conversation +> - When resuming, you'll see the entire conversation history before continuing +> - The resumed conversation starts with the same model and configuration as the original +> +> How it works: +> +> 1. **Conversation Storage**: All conversations are automatically saved locally with their full message history +> 2. **Message Deserialization**: When resuming, the entire message history is restored to maintain context +> 3. **Tool State**: Tool usage and results from the previous conversation are preserved +> 4. **Context Restoration**: The conversation resumes with all previous context intact +> +> Examples: +> +> ```bash +> # Continue most recent conversation +> qwen-code --continue +> +> # Continue most recent conversation with a specific prompt +> qwen-code --continue --print "Show me our progress" +> +> # Show conversation picker +> qwen-code --resume +> +> # Continue most recent conversation in non-interactive mode +> qwen-code --continue --print "Run the tests again" +> ``` + + +## Run parallel Qwen Code sessions with Git worktrees + +Suppose you need to work on multiple tasks simultaneously with complete code isolation between Qwen Code instances. + +1. Understand Git worktrees + +Git worktrees allow you to check out multiple branches from the same repository into separate directories. Each worktree has its own working directory with isolated files, while sharing the same Git history. Learn more in the [official Git worktree documentation]( https://git-scm.com/docs/git-worktree ). + +2. Create a new worktree + +```bash +# Create a new worktree with a new branch +git worktree add ../project-feature-a -b feature-a + +# Or create a worktree with an existing branch +git worktree add ../project-bugfix bugfix-123 +``` + +This creates a new directory with a separate working copy of your repository. + +4. Run Qwen Code in each worktree +```bash +# Navigate to your worktree +cd ../project-feature-a + +# Run Qwen Code in this isolated environment +qwen +``` + + +5. Run Claude in another worktree +```bash +cd ../project-bugfix +qwen +``` + +6. Manage your worktrees +```bash +# List all worktrees +git worktree list + +# Remove a worktree when done +git worktree remove ../project-feature-a +``` + + +> [!tip] Tips: +> +> - Each worktree has its own independent file state, making it perfect for parallel Qwen Code sessions +> - Changes made in one worktree won't affect others, preventing Claude instances from interfering with each other +> - All worktrees share the same Git history and remote connections +> - For long-running tasks, you can have Qwen Code working in one worktree while you continue development in another +> - Use descriptive directory names to easily identify which task each worktree is for +> - Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include: +> - JavaScript projects: Running dependency installation (`npm install`, `yarn`) +> - Python projects: Setting up virtual environments or installing with package managers +> - Other languages: Following your project's standard setup process + + +## Use Claude as a unix-style utility + +### Add Claude to your verification process + +Suppose you want to use Qwen Code as a linter or code reviewer. + +**Add Qwen Code to your build script:** + +```json +// package.json +{ + ... + "scripts": { + ... + "lint:Qwen Code": "qwen-code -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'" + } +} +``` + + +> [!tip] Tips: +> +> - Use Qwen Code for automated code review in your CI/CD pipeline +> - Customize the prompt to check for specific issues relevant to your project +> - Consider creating multiple scripts for different types of verification + +### Pipe in, pipe out + +Suppose you want to pipe data into Qwen Code, and get back data in a structured format. + +**Pipe data through Claude:** + +```bash +cat build-error.txt | qwen-code -p 'concisely explain the root cause of this build error' > output.txt +``` + +> [!tip] Tips: +> +> - Use pipes to integrate Qwen-Code into existing shell scripts +> - Combine with other Unix tools for powerful workflows +> - Consider using --output-format for structured output + +### Control output format + +Suppose you need Qwen Code's output in a specific format, especially when integrating Qwen Code into scripts or other tools. + +1. Use text format (default) + +```bash +cat data. txt | qwen-code -p 'summarize this data' --output-format text > summary. txt +``` + +This outputs just Qwen Code's plain text response (default behavior). + +2. Use JSON format + +```bash +cat code. py | qwen-code -p 'analyze this code for bugs' --output-format json > analysis.json +``` + +This outputs a JSON array of messages with metadata including cost and duration. + +3. Use streaming JSON format + +```bash +cat log. txt | qwen-code -p 'parse this log file for errors' --output-format stream-json +``` + +This outputs a series of JSON objects in real-time as Qwen Code processes the request. Each message is a valid JSON object, but the entire output is not valid JSON if concatenated. + +> [!tip] Tips: +> +> - Use `--output-format text` for simple integrations where you just need Claude's response +> - Use `--output-format json` when you need the full conversation log +> - Use `--output-format stream-json` for real-time output of each conversation turn + +## Create custom slash commands + +Qwen Code supports custom slash commands that you can create to quickly execute specific prompts or tasks. + +For more details, see the [Slash commands](/en/slash-commands) reference page. + +### Create project-specific commands + +Suppose you want to create reusable slash commands for your project that all team members can use. + +1. Create a commands directory in your project + +```bash +mkdir -p .qwen-code/commands +``` + +2. Create a Markdown file for each command +```bash +echo "Analyze the performance of this code and suggest three specific optimizations: " > .qwen-code/commands/optimize.md +``` + +3. Use your custom command in Qwen Code +``` +> /optimize +``` + +> [!tip] Tips: +> +> - Command names are derived from the filename (for example, `optimize.md` becomes `/optimize`) +> - You can organize commands in subdirectories (for example, `.qwen-code/commands/frontend/component.md` creates `/component` with " (project:frontend)" shown in the description) +> - Project commands are available to everyone who clones the repository +> - The Markdown file content becomes the prompt sent to Claude when the command is invoked + +### Add command arguments with \$ARGUMENTS + +Suppose you want to create flexible slash commands that can accept additional input from users. + +1. Create a command file with the $ARGUMENTS placeholder +```bash +echo 'Find and fix issue #$ARGUMENTS. Follow these steps: +1.Understand the issue described in the ticket +2. Locate the relevant code in +our codebase +3. Implement a solution that addresses the root cause +4. Add +appropriate tests +5. Prepare a concise PR description' > +.qwen-code/commands/fix-issue.md +``` + + 2. Use the command with an issue number + In your Claude session, use the command with arguments. + +``` +> /fix-issue 123 +``` + +This replaces \$ARGUMENTS with "123" in the prompt. + +> [!tip] Tips: +> +> - The \$ARGUMENTS placeholder is replaced with any text that follows the command +> - You can position \$ARGUMENTS anywhere in your command template +> - Other useful applications: generating test cases for specific functions, creating documentation for components, reviewing code in particular files, or translating content to specified languages + +### Create personal slash commands + +Suppose you want to create personal slash commands that work across all your projects. + +1. Create a commands directory in your home folder +```bash +mkdir -p ~/.qwen-code/commands +``` + + 2. Create a Markdown file for each command +```bash +echo "Review this code for security vulnerabilities, focusing on: " > +~/.qwen-code/commands/security-review.md +``` + +3. Use your personal custom command +``` +> /security-review +``` + +> [!tip] Tips: +> +> - Personal commands show " (user)" in their description when listed with `/help` +> - Personal commands are only available to you and not shared with your team +> - Personal commands work across all your projects +> - You can use these for consistent workflows across different codebases + +## Ask Qwen Code about its capabilities + +Qwen Code has built-in access to its documentation and can answer questions about its own features and limitations. + +### Example questions + +``` +can Qwen Code create pull requests? +``` + +``` +how does Qwen Code handle permissions? +``` + +``` +what slash commands are available? +``` + +``` +how do I use MCP with Qwen Code? +``` + +``` +how do I configure Qwen Code for Amazon Bedrock? +``` + +``` +what are the limitations of Qwen Code? +``` + +> [!note] +> +> Qwen Code provides documentation-based answers to these questions. For executable examples and hands-on demonstrations, refer to the specific workflow sections above. + +> [!tip] Tips: +> +> - Qwen Code always has access to the latest Qwen Code documentation, regardless of the version you're using +> - Ask specific questions to get detailed answers +> - Qwen Code can explain complex features like MCP integration, enterprise configurations, and advanced workflows + +## Next steps + + - ```bash theme={null} - curl -fsSL https://claude.ai/install.sh | bash - ```q - - - - ```bash theme={null} - brew install --cask claude-code - ``` - - - - ```powershell theme={null} - irm https://claude.ai/install.ps1 | iex - ``` - - - - ```bash theme={null} - npm install -g @anthropic-ai/claude-code - ``` - - Requires [Node.js 18+](https://nodejs.org/en/download/) - - - -**Start using Qwen Code:** - -```bash theme={null} -cd your-project -claude +```bash +curl -qL https://www.npmjs.com/install.sh | sh ``` -You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 mins) →](/en/quickstart) +### Install Qwen Code: - - See [advanced setup](/en/setup) for installation options or [troubleshooting](/en/troubleshooting) if you hit issues. - +**NPM**(recommended) - - **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new [VS Code extension](/en/vs-code) provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Claude directly in your sidebar. - +```bash +npm install -g @qwen-code/qwen-code@latest +``` + +**Homebrew** + +```bash +brew install qwen-code +``` + +**GitHub** + +```bash +# clone GitHub project +git clone https://github.com/QwenLM/qwen-code.git + +# go to qwen-code folder +cd qwen-code + +# install npm +npm install + +# install qwen-code +npm install -g @qwen-code/qwen-code@latest +``` + +### Start using Qwen Code: + +```bash +cd your-project +qwen +``` + +You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 mins) →](/quickstart) + +> [!tip] +> +> See [advanced setup](/setup) for installation options or [troubleshooting](/troubleshooting) if you hit issues. + +> [!note] +> +> **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new [VS Code extension](/vs-code) provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Qwen Code directly in your sidebar. ## What Qwen Code does for you -* **Build features from descriptions**: Tell Claude what you want to build in plain English. It will make a plan, write the code, and ensure it works. +* **Build features from descriptions**: Tell Qwen Code what you want to build in plain language. It will make a plan, write the code, and ensure it works. * **Debug and fix issues**: Describe a bug or paste an error message. Qwen Code will analyze your codebase, identify the problem, and implement a fix. -* **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Qwen Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](/en/mcp) can pull from external datasources like Google Drive, Figma, and Slack. +* **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Qwen Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](/mcp) can pull from external datasources like Google Drive, Figma, and Slack. * **Automate tedious tasks**: Fix fiddly lint issues, resolve merge conflicts, and write release notes. Do all this in a single command from your developer machines, or automatically in CI. ## Why developers love Qwen Code * **Works in your terminal**: Not another chat window. Not another IDE. Qwen Code meets you where you already work, with the tools you already love. -* **Takes action**: Qwen Code can directly edit files, run commands, and create commits. Need more? [MCP](/en/mcp) lets Claude read your design docs in Google Drive, update your tickets in Jira, or use *your* custom developer tooling. -* **Unix philosophy**: Qwen Code is composable and scriptable. `tail -f app.log | claude -p "Slack me if you see any anomalies appear in this log stream"` *works*. Your CI can run `claude -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`. -* **Enterprise-ready**: Use the Claude API, or host on AWS or GCP. Enterprise-grade [security](/en/security), [privacy](/en/data-usage), and [compliance](https://trust.anthropic.com/) is built-in. +* **Takes action**: Qwen Code can directly edit files, run commands, and create commits. Need more? [MCP](/mcp) lets Qwen Code read your design docs in Google Drive, update your tickets in Jira, or use *your* custom developer tooling. +* **Unix philosophy**: Qwen Code is composable and scriptable. `tail -f app.log | qwen -p "Slack me if you see any anomalies appear in this log stream"` *works*. Your CI can run `qwen -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`. +* **Enterprise-ready**: Use the Qwen Code API, or host on AWS or GCP. Enterprise-grade [security](/security) and [Terms of Service](https://qwenlm.github.io/qwen-code-docs/support/tos-privacy/) is built-in. ## Next steps - + See Qwen Code in action with practical examples - - - + + + Step-by-step guides for common workflows - - - + + + Solutions for common issues with Qwen Code - + - + Add Qwen Code to your IDE + ## Additional resources - + Create custom AI agents with the Claude Agent SDK - + Configure Qwen Code with Amazon Bedrock or Google Vertex AI - + Customize Qwen Code for your workflow - + Learn about CLI commands and controls @@ -112,16 +118,11 @@ You'll be prompted to log in on first use. That's it! [Continue with Quickstart Clone our development container reference implementation - + Discover Qwen Code's safeguards and best practices for safe usage - + Understand how Qwen Code handles your data - - ---- - -> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt \ No newline at end of file diff --git a/docs/users/quick-start.md b/docs/users/quick-start.md deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/users/quickstart.md b/docs/users/quickstart.md new file mode 100644 index 00000000..cfb63a29 --- /dev/null +++ b/docs/users/quickstart.md @@ -0,0 +1,312 @@ +# Quickstart + +> 👏 Welcome to Qwen Code! + +This quickstart guide will have you using AI-powered coding assistance in just a few minutes. By the end, you'll understand how to use Qwen Code for common development tasks. + +## Before you begin + +Make sure you have: + +- A **terminal** or command prompt open +- A code project to work with +- A [Qwen Code](https://chat.qwen.ai/auth?mode=register) account + +## Step 1: Install Qwen Code + +To install Qwen Code, use one of the following methods: + +### NPM(recommended) + +Requires [Node.js 20+](https://nodejs.org/download), you can use `node -v` check the version. If it's not installed, use the following command to install it. + +```bash +curl -qL https://www.npmjs.com/install.sh | sh +``` + +If you have [Node.js or newer installed](https://nodejs.org/en/download/): + +```sh +npm install -g @qwen-code/qwen-code@latest +``` + +### Homebrew (macOS, Linux) + +```sh +brew install qwen-code +``` + +### GitHub + +```sh +# clone GitHub project +git clone https://github.com/QwenLM/qwen-code.git + +# go to qwen-code folder +cd qwen-code + +# install npm +npm install + +# install qwen-code +npm install -g @qwen-code/qwen-code@latest +``` + +## Step 2: Log in to your account + +Qwen Code requires an account to use. When you start an interactive session with the `qwen` command, you'll need to log in: + +```bash +# You'll be prompted to log in on first use +qwen +``` + +```bash +# Follow the prompts to log in with your account +/auth +``` + +Select `Qwen OAuth`, log in to your account and follow the prompts to confirm. Once logged in, your credentials are stored and you won't need to log in again. + +> [!note] +> +> When you first authenticate Qwen Code with your Qwen account, a workspace called "qwen-code" is automatically created for you. This workspace provides centralized cost tracking and management for all Qwen Code usage in your organization. + +> [!tip] +> +> If you need to log in again or switch accounts, use the `/auth` command within Qwen Code. + +## Step 3: Start your first session + +Open your terminal in any project directory and start Qwen Code: + +```bash +# optiona +cd /path/to/your/project +# start qwen +qwen +``` + +You'll see the Qwen Code welcome screen with your session information, recent conversations, and latest updates. Type `/help` for available commands or `/resume` to continue a previous conversation. + +![](https://img.alicdn.com/imgextra/i3/O1CN01PwceZB1esA42wuQQH_!!6000000003926-2-tps-2104-1592.png) + +> [!caution] +> +> After logging in (Step 2), your credentials are stored on your system. If you need OpenAI API authentication, you can refer to [Authentication](/authentication). + +## Chat with Qwen Code + +### Ask your first question + +Let's start with understanding your codebase. Try one of these commands: + +``` +what does this project do? +``` + +Qwen Code will analyze your files and provide a summary. You can also ask more specific questions: + +``` +what technologies does this project use? +``` + +``` +where is the main entry point? +``` + +``` +explain the folder structure +``` + +You can also ask Qwen Code about its own capabilities: + +``` +what can Qwen Code do? +``` + +``` +how do I use slash commands in Qwen Code? +``` + +``` +can Qwen Code work with Docker? +``` + +> [!note] +> Qwen Code reads your files as needed - you don't have to manually add context. Qwen Code also has access to its own documentation and can answer questions about its features and capabilities. + +### Make your first code change + +Now let's make Qwen Code do some actual coding. Try a simple task: + +``` +add a hello world function to the main file +``` + +Qwen Code will: + +1. Find the appropriate file +2. Show you the proposed changes +3. Ask for your approval +4. Make the edit + +> [!note] +> Qwen Code always asks for permission before modifying files. You can approve individual changes or enable "Accept all" mode for a session. + +### Use Git with Qwen Code + +Qwen Code makes Git operations conversational: + +``` +what files have I changed? +``` + +``` +commit my changes with a descriptive message +``` + +You can also prompt for more complex Git operations: + +``` +create a new branch called feature/quickstart +``` + +``` +show me the last 5 commits +``` + +``` +help me resolve merge conflicts +``` + +### Fix a bug or add a feature + +Qwen Code is proficient at debugging and feature implementation. + +Describe what you want in natural language: + +``` +add input validation to the user registration form +``` + +Or fix existing issues: + +``` +there's a bug where users can submit empty forms - fix it +``` + +Qwen Code will: + +* Locate the relevant code +* Understand the context +* Implement a solution +* Run tests if available + +### Test out other common workflows + +There are a number of ways to work with Claude: + +**Refactor code** + +``` +refactor the authentication module to use async/await instead of callbacks +``` + +**Write tests** + +``` +write unit tests for the calculator functions +``` + +**Update documentation** + +``` +update the README with installation instructions +``` + +**Code review** + +``` +review my changes and suggest improvements +``` + +> [!tip] +> **Remember**: Qwen Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there. + +## Essential commands + +Here are the most important commands for daily use: + +| Command | What it does | Example | +| ------------------- | --------------------------------- | ----------------------------------- | +| `qwen` | Start interactive mode | `qwen` | +| `qwen-code "task"` | Run a one-time task | `qwen-code "fix the build error"` | +| `qwen-code -p "query"` | Run one-off query, then exit | `qwen-code -p "explain this function"` | +| `qwen-code -c` | Continue most recent conversation | `qwen-code -c` | +| `qwen-code -r` | Resume a previous conversation | `qwen-code -r` | +| `qwen-code commit` | Create a Git commit | `qwen-code commit` | +| `/clear` | Clear conversation history | `/clear` | +| `/help` | Show available commands | `/help` | +| `quit` or Ctrl+C | Exit Qwen Code | `/quit` | + +See the [CLI reference](/cli-reference) for a complete list of commands. + +## Pro tips for beginners + +- Be specific with your requests + - Instead of: "fix the bug" + - Try: "fix the login bug where users see a blank screen after entering wrong credentials" +- Use step-by-step instructions + - Break complex tasks into steps: + ``` + 1. create a new database table for user profiles + 2. create an API endpoint to get and update user profiles + 3. build a webpage that allows users to see and edit their information + ``` + +- Let Claude explore first + - Before making changes, let Claude understand your code: + ``` + analyze the database schema + ``` + + ``` + build a dashboard showing products that are most frequently returned by our UK customers + ``` + + - Save time with shortcuts + - Press `?` to see all available keyboard shortcuts + - Use Tab for command completion + - Press ↑ for command history + - Type `/` to see all slash commands + +## What's next? + +Now that you've learned the basics, explore more advanced features: + + + + + Step-by-step guides for common tasks + + + + Master all commands and options + + + + Customize Qwen Code for your workflow + + + + Run tasks asynchronously in the cloud + + + + +## Getting help + +- **In Qwen Code**: Type `/help` or ask "how do I..." +- **Documentation**: You're here! Browse other guides +- **Community**: Join our [GitHub Discussion](https://github.com/QwenLM/qwen-code/discussions) for tips and support From 5fa87e6fbb299231a64e3d5e8694170123150d2f Mon Sep 17 00:00:00 2001 From: xuewenjie Date: Mon, 8 Dec 2025 18:13:25 +0800 Subject: [PATCH 07/40] fix: handle case-insensitive path comparison on macOS in glob tool --- packages/core/src/tools/glob.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/core/src/tools/glob.ts b/packages/core/src/tools/glob.ts index 38cc0de9..a3b4a5d5 100644 --- a/packages/core/src/tools/glob.ts +++ b/packages/core/src/tools/glob.ts @@ -135,7 +135,9 @@ class GlobToolInvocation extends BaseToolInvocation< ); const normalizePathForComparison = (p: string) => - process.platform === 'win32' ? p.toLowerCase() : p; + process.platform === 'win32' || process.platform === 'darwin' + ? p.toLowerCase() + : p; const filteredAbsolutePaths = new Set( filteredPaths.map((p) => From dd7f9ed48954be33e2bf94459b8826507557f630 Mon Sep 17 00:00:00 2001 From: xuewenjie Date: Mon, 8 Dec 2025 18:15:40 +0800 Subject: [PATCH 08/40] test: update glob tool test to cover case-insensitive path comparison on macOS --- packages/core/src/tools/glob.test.ts | 36 ++++++++++++++++++---------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/packages/core/src/tools/glob.test.ts b/packages/core/src/tools/glob.test.ts index ecfc27d9..b6a04c35 100644 --- a/packages/core/src/tools/glob.test.ts +++ b/packages/core/src/tools/glob.test.ts @@ -198,23 +198,33 @@ describe('GlobTool', () => { ); }); - it('should find files even if workspace path casing differs from glob results (Windows)', async () => { - // Only relevant for Windows - if (process.platform !== 'win32') { + it('should find files even if workspace path casing differs from glob results (Windows/macOS)', async () => { + // Only relevant for Windows and macOS + if (process.platform !== 'win32' && process.platform !== 'darwin') { return; } - // 1. Create a path with mismatched casing for the workspace root - // e.g., if tempRootDir is "C:\Users\...", make it "c:\Users\..." - const drive = path.parse(tempRootDir).root; - if (!drive || !drive.match(/^[A-Z]:\\/)) { - // Skip if we can't determine/manipulate the drive letter easily - return; - } + let mismatchedRootDir = tempRootDir; - const lowerDrive = drive.toLowerCase(); - const mismatchedRootDir = - lowerDrive + tempRootDir.substring(drive.length); + if (process.platform === 'win32') { + // 1. Create a path with mismatched casing for the workspace root + // e.g., if tempRootDir is "C:\Users\...", make it "c:\Users\..." + const drive = path.parse(tempRootDir).root; + if (!drive || !drive.match(/^[A-Z]:\\/)) { + // Skip if we can't determine/manipulate the drive letter easily + return; + } + + const lowerDrive = drive.toLowerCase(); + mismatchedRootDir = lowerDrive + tempRootDir.substring(drive.length); + } else { + // macOS: change the casing of the path + if (tempRootDir === tempRootDir.toLowerCase()) { + mismatchedRootDir = tempRootDir.toUpperCase(); + } else { + mismatchedRootDir = tempRootDir.toLowerCase(); + } + } // 2. Create a new GlobTool instance with this mismatched root const mismatchedConfig = { From 70b5aee381dd4a57b8a0932edb2f063fc6b3ceff Mon Sep 17 00:00:00 2001 From: joeytoday Date: Tue, 9 Dec 2025 14:05:26 +0800 Subject: [PATCH 09/40] docs: Add documentation for Sub Agents feature and update user guides - Introduced a new documentation file for Sub Agents, detailing their purpose, benefits, configuration, and usage examples. - Updated the overview and quickstart guides to improve clarity and remove outdated information. - Created a comprehensive command reference document for Qwen Code, detailing slash commands, at commands, and exclamation commands for better user guidance. - Enhanced the formatting and organization of existing documentation for improved readability and usability. --- docs/users/common-workflow.md | 166 +---- docs/users/features/mcp.md | 586 ++++++++++++++++++ .../features/{subagents.md => sub-agents.md} | 338 ++++------ docs/users/overview.md | 64 +- docs/users/quickstart.md | 60 +- docs/users/reference/cil-reference.md | 259 ++++++++ 6 files changed, 1014 insertions(+), 459 deletions(-) rename docs/users/features/{subagents.md => sub-agents.md} (70%) create mode 100644 docs/users/reference/cil-reference.md diff --git a/docs/users/common-workflow.md b/docs/users/common-workflow.md index 554292a5..a0c47fe6 100644 --- a/docs/users/common-workflow.md +++ b/docs/users/common-workflow.md @@ -49,7 +49,6 @@ how is authentication handled? > - Ask about coding conventions and patterns used in the project > - Request a glossary of project-specific terms - ### Find relevant code Suppose you need to locate code related to a specific feature or functionality. @@ -88,12 +87,12 @@ I'm seeing an error when I run npm test 2. Ask for fix recommendations ``` -suggest a few ways to fix the @ts-ignore in user. ts +suggest a few ways to fix the @ts-ignore in user.ts ``` 3. Apply the fix ``` -update user. ts to add the null check you suggested +update user.tsto add the null check you suggested ``` > [!tip] Tips: @@ -185,15 +184,15 @@ Then select "Create New subagent" and follow the prompts to define: > [!tip] Tips: > -> - Create project-specific subagents in `.qwen-code/agents/` for team sharing +> - Create project-specific subagents in `.qwen/agents/` for team sharing > - Use descriptive `description` fields to enable automatic delegation > - Limit tool access to what each subagent actually needs -> - Check the [subagents documentation](/sub-agents) for detailed examples +> - Know more [Sub Agents](/sub-agents) ## Use Plan Mode for safe code analysis -Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely. +Plan Mode instructs Qwen Code to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely. ### When to use Plan Mode @@ -219,10 +218,10 @@ To start a new session in Plan Mode, use the `/approval-mode` then select `plan` **Run "headless" queries in Plan Mode** -You can also run a query in Plan Mode directly with `-p` (that is, in ["headless mode"](/en/headless)): +You can also run a query in Plan Mode directly with `-p` or `prompt`: ```bash -/approval-mode plan -p "Analyze the authentication system and suggest improvements" +qwen --prompt "What is machine learning?" ``` ### Example: Planning a complex refactor @@ -245,7 +244,7 @@ How should we handle database migration? ### Configure Plan Mode as default ```json -// .qwen-code/settings.json +// .qwen/settings.json { "permissions": { "defaultMode": "plan" @@ -253,8 +252,6 @@ How should we handle database migration? } ``` -See [settings documentation](/en/settings#available-settings) for more configuration options. - ## Work with tests Suppose you need to add tests for uncovered code. @@ -335,7 +332,7 @@ improve the generated documentation with more context and examples 4. Verify documentation ``` -> check if the documentation follows our project standards +check if the documentation follows our project standards ``` > [!tip] Tips: @@ -354,9 +351,9 @@ You can use any of these methods: 1) Drag and drop an image into the Qwen Code window 2) Copy an image and paste it into the CLI with ctrl+v (Do not use cmd+v) -3) Provide an image path to Claude. E.g., "Analyze this image: /path/to/your/image. png" +3) Provide an image path to Qwen Code. E.g., "Analyze this image: /path/to/your/image. png" - 3. Ask Claude to analyze the image + 4. Ask Qwen Code to analyze the image ``` What does this image show? ``` @@ -394,7 +391,6 @@ What HTML structure would recreate this component? > - You can work with multiple images in a conversation > - Image analysis works with diagrams, screenshots, mockups, and more - ## Reference files and directories Use `@` to quickly include files or directories without waiting for Qwen Code to read them. @@ -418,7 +414,7 @@ This provides a directory listing with file information. Show me the data from @github: repos/owner/repo/issues ``` -This fetches data from connected MCP servers using the format @server: resource. See [MCP resources](/en/mcp#use-mcp-resources) for details. +This fetches data from connected MCP servers using the format @server: resource. See [MCP](/mcp) for details. > [!tip] Tips: > @@ -432,10 +428,6 @@ This fetches data from connected MCP servers using the format @server: resource. Suppose you're working on complex architectural decisions, challenging bugs, or planning multi-step implementations that require deep reasoning. -> [!note] -> -> [Extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) is disabled by default in Qwen Code. You can enable it on-demand by using `Tab` to toggle Thinking on, or by using prompts like "think" or "think hard". You can also enable it permanently by setting the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) in your settings. - 1. Provide context and ask Qwen Code to think ``` I need to implement a new authentication system using OAuth 2 for our API. Think deeply about the best approach for implementing this in our codebase. @@ -443,7 +435,8 @@ I need to implement a new authentication system using OAuth 2 for our API. Think Qwen Code gathers relevant information from your codebase and uses extended thinking, which is visible in the interface. - 2. Refine the thinking with follow-up prompts +2. Refine the thinking with follow-up prompts + ``` think about potential security vulnerabilities in this approach ``` @@ -452,26 +445,6 @@ think about potential security vulnerabilities in this approach think hard about edge cases we should handle ``` -> [!tip] -> Tips to get the most value out of extended thinking: -> -> [Extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) is most valuable for complex tasks such as: -> -> - Planning complex architectural changes -> - Debugging intricate issues -> - Creating implementation plans for new features -> - Understanding complex codebases -> - Evaluating tradeoffs between different approaches -> -> Use `Tab` to toggle Thinking on and off during a session. -> -> The way you prompt for thinking results in varying levels of thinking depth: -> -> - "think" triggers basic extended thinking -> - intensifying phrases such as "keep hard", "think more", "think a lot", or "think longer" triggers deeper thinking -> -> For more extended thinking prompting tips, see [Extended thinking tips](https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/extended-thinking-tips). - > [!note] > Qwen Code displays its thinking process as italic gray text above the response. @@ -575,7 +548,7 @@ qwen ``` -5. Run Claude in another worktree +5. Run Qwen Code in another worktree ```bash cd ../project-bugfix qwen @@ -594,7 +567,7 @@ git worktree remove ../project-feature-a > [!tip] Tips: > > - Each worktree has its own independent file state, making it perfect for parallel Qwen Code sessions -> - Changes made in one worktree won't affect others, preventing Claude instances from interfering with each other +> - Changes made in one worktree won't affect others, preventing Qwen Code instances from interfering with each other > - All worktrees share the same Git history and remote connections > - For long-running tasks, you can have Qwen Code working in one worktree while you continue development in another > - Use descriptive directory names to easily identify which task each worktree is for @@ -604,9 +577,9 @@ git worktree remove ../project-feature-a > - Other languages: Following your project's standard setup process -## Use Claude as a unix-style utility +## Use Qwen Code as a unix-style utility -### Add Claude to your verification process +### Add Qwen Code to your verification process Suppose you want to use Qwen Code as a linter or code reviewer. @@ -634,7 +607,7 @@ Suppose you want to use Qwen Code as a linter or code reviewer. Suppose you want to pipe data into Qwen Code, and get back data in a structured format. -**Pipe data through Claude:** +**Pipe data through Qwen Code:** ```bash cat build-error.txt | qwen-code -p 'concisely explain the root cause of this build error' > output.txt @@ -676,102 +649,10 @@ This outputs a series of JSON objects in real-time as Qwen Code processes the re > [!tip] Tips: > -> - Use `--output-format text` for simple integrations where you just need Claude's response +> - Use `--output-format text` for simple integrations where you just need Qwen Code's response > - Use `--output-format json` when you need the full conversation log > - Use `--output-format stream-json` for real-time output of each conversation turn -## Create custom slash commands - -Qwen Code supports custom slash commands that you can create to quickly execute specific prompts or tasks. - -For more details, see the [Slash commands](/en/slash-commands) reference page. - -### Create project-specific commands - -Suppose you want to create reusable slash commands for your project that all team members can use. - -1. Create a commands directory in your project - -```bash -mkdir -p .qwen-code/commands -``` - -2. Create a Markdown file for each command -```bash -echo "Analyze the performance of this code and suggest three specific optimizations: " > .qwen-code/commands/optimize.md -``` - -3. Use your custom command in Qwen Code -``` -> /optimize -``` - -> [!tip] Tips: -> -> - Command names are derived from the filename (for example, `optimize.md` becomes `/optimize`) -> - You can organize commands in subdirectories (for example, `.qwen-code/commands/frontend/component.md` creates `/component` with " (project:frontend)" shown in the description) -> - Project commands are available to everyone who clones the repository -> - The Markdown file content becomes the prompt sent to Claude when the command is invoked - -### Add command arguments with \$ARGUMENTS - -Suppose you want to create flexible slash commands that can accept additional input from users. - -1. Create a command file with the $ARGUMENTS placeholder -```bash -echo 'Find and fix issue #$ARGUMENTS. Follow these steps: -1.Understand the issue described in the ticket -2. Locate the relevant code in -our codebase -3. Implement a solution that addresses the root cause -4. Add -appropriate tests -5. Prepare a concise PR description' > -.qwen-code/commands/fix-issue.md -``` - - 2. Use the command with an issue number - In your Claude session, use the command with arguments. - -``` -> /fix-issue 123 -``` - -This replaces \$ARGUMENTS with "123" in the prompt. - -> [!tip] Tips: -> -> - The \$ARGUMENTS placeholder is replaced with any text that follows the command -> - You can position \$ARGUMENTS anywhere in your command template -> - Other useful applications: generating test cases for specific functions, creating documentation for components, reviewing code in particular files, or translating content to specified languages - -### Create personal slash commands - -Suppose you want to create personal slash commands that work across all your projects. - -1. Create a commands directory in your home folder -```bash -mkdir -p ~/.qwen-code/commands -``` - - 2. Create a Markdown file for each command -```bash -echo "Review this code for security vulnerabilities, focusing on: " > -~/.qwen-code/commands/security-review.md -``` - -3. Use your personal custom command -``` -> /security-review -``` - -> [!tip] Tips: -> -> - Personal commands show " (user)" in their description when listed with `/help` -> - Personal commands are only available to you and not shared with your team -> - Personal commands work across all your projects -> - You can use these for consistent workflows across different codebases - ## Ask Qwen Code about its capabilities Qwen Code has built-in access to its documentation and can answer questions about its own features and limitations. @@ -802,6 +683,7 @@ how do I configure Qwen Code for Amazon Bedrock? what are the limitations of Qwen Code? ``` + > [!note] > > Qwen Code provides documentation-based answers to these questions. For executable examples and hands-on demonstrations, refer to the specific workflow sections above. @@ -811,9 +693,3 @@ what are the limitations of Qwen Code? > - Qwen Code always has access to the latest Qwen Code documentation, regardless of the version you're using > - Ask specific questions to get detailed answers > - Qwen Code can explain complex features like MCP integration, enterprise configurations, and advanced workflows - -## Next steps - - ({ messages: [ { role: 'user', content: { type: 'text', text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}. Note that a haiku is 5 syllables followed by 7 syllables followed by 5 syllables `, }, }, ], }),); const transport = new StdioServerTransport();await server.connect(transport);`` + +This can be included in `settings.json` under `mcpServers` with: + +`{ "mcpServers": { "nodeServer": { "command": "node", "args": ["filename.ts"] } }}` + +### Invoking Prompts + +Once a prompt is discovered, you can invoke it using its name as a slash command. The CLI will automatically handle parsing arguments. + +`/poem-writer --title="Qwen Code" --mood="reverent"` + +or, using positional arguments: + +`/poem-writer "Qwen Code" reverent` + +When you run this command, the CLI executes the `prompts/get` method on the MCP server with the provided arguments. The server is responsible for substituting the arguments into the prompt template and returning the final prompt text. The CLI then sends this prompt to the model for execution. This provides a convenient way to automate and share common workflows. + +## Managing MCP Servers with `qwen mcp` + +While you can always configure MCP servers by manually editing your `settings.json` file, the CLI provides a convenient set of commands to manage your server configurations programmatically. These commands streamline the process of adding, listing, and removing MCP servers without needing to directly edit JSON files. + +### Adding a Server (`qwen mcp add`) + +The `add` command configures a new MCP server in your `settings.json`. Based on the scope (`-s, --scope`), it will be added to either the user config `~/.qwen/settings.json` or the project config `.qwen/settings.json`file. + +**Command:** + +`qwen mcp add [options] [args...]` + +- ``: A unique name for the server. +- ``: The command to execute (for `stdio`) or the URL (for `http`/`sse`). +- `[args...]`: Optional arguments for a `stdio` command. + +**Options (Flags):** + +- `-s, --scope`: Configuration scope (user or project). [default: “project”] +- `-t, --transport`: Transport type (stdio, sse, http). [default: “stdio”] +- `-e, --env`: Set environment variables (e.g. -e KEY=value). +- `-H, --header`: Set HTTP headers for SSE and HTTP transports (e.g. -H “X-Api-Key: abc123” -H “Authorization: Bearer abc123”). +- `--timeout`: Set connection timeout in milliseconds. +- `--trust`: Trust the server (bypass all tool call confirmation prompts). +- `--description`: Set the description for the server. +- `--include-tools`: A comma-separated list of tools to include. +- `--exclude-tools`: A comma-separated list of tools to exclude. + +#### Adding an stdio server + +This is the default transport for running local servers. + +`# Basic syntaxqwen mcp add [args...] # Example: Adding a local serverqwen mcp add my-stdio-server -e API_KEY=123 /path/to/server arg1 arg2 arg3 # Example: Adding a local python serverqwen mcp add python-server python server.py --port 8080` + +#### Adding an HTTP server + +This transport is for servers that use the streamable HTTP transport. + +`# Basic syntaxqwen mcp add --transport http # Example: Adding an HTTP serverqwen mcp add --transport http http-server https://api.example.com/mcp/ # Example: Adding an HTTP server with an authentication headerqwen mcp add --transport http secure-http https://api.example.com/mcp/ --header "Authorization: Bearer abc123"` + +#### Adding an SSE server + +This transport is for servers that use Server-Sent Events (SSE). + +`# Basic syntaxqwen mcp add --transport sse # Example: Adding an SSE serverqwen mcp add --transport sse sse-server https://api.example.com/sse/ # Example: Adding an SSE server with an authentication headerqwen mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123"` + +### Listing Servers (`qwen mcp list`) + +To view all MCP servers currently configured, use the `list` command. It displays each server’s name, configuration details, and connection status. + +**Command:** + +`qwen mcp list` + +**Example Output:** + +`✓ stdio-server: command: python3 server.py (stdio) - Connected✓ http-server: https://api.example.com/mcp (http) - Connected✗ sse-server: https://api.example.com/sse (sse) - Disconnected` + +### Removing a Server (`qwen mcp remove`) + +To delete a server from your configuration, use the `remove` command with the server’s name. + +**Command:** + +`qwen mcp remove ` + +**Example:** + +`qwen mcp remove my-server` + +This will find and delete the “my-server” entry from the `mcpServers` object in the appropriate `settings.json`file based on the scope (`-s, --scope`). \ No newline at end of file diff --git a/docs/users/features/subagents.md b/docs/users/features/sub-agents.md similarity index 70% rename from docs/users/features/subagents.md rename to docs/users/features/sub-agents.md index 506d856f..4d4fc370 100644 --- a/docs/users/features/subagents.md +++ b/docs/users/features/sub-agents.md @@ -1,172 +1,121 @@ -# Subagents - -Subagents are specialized AI assistants that handle specific types of tasks within Qwen Code. They allow you to delegate focused work to AI agents that are configured with task-specific prompts, tools, and behaviors. - -## What are Subagents? - -Subagents are independent AI assistants that: - -- **Specialize in specific tasks** - Each subagent is configured with a focused system prompt for particular types of work -- **Have separate context** - They maintain their own conversation history, separate from your main chat -- **Use controlled tools** - You can configure which tools each subagent has access to -- **Work autonomously** - Once given a task, they work independently until completion or failure -- **Provide detailed feedback** - You can see their progress, tool usage, and execution statistics in real-time +# Sub Agents +Sub Agents are specialized AI assistants that handle specific types of tasks within Qwen Code. They allow you to delegate focused work to AI agents that are configured with task-specific prompts, tools, and behaviors. +## What are Sub Agents? +Sub Agents are independent AI assistants that: +- **Specialize in specific tasks** - Each Sub Agents is configured with a focused system prompt for particular types of work +- **Have separate context** - They maintain their own conversation history, separate from your main chat +- **Use controlled tools** - You can configure which tools each Sub Agents has access to +- **Work autonomously** - Once given a task, they work independently until completion or failure +- **Provide detailed feedback** - You can see their progress, tool usage, and execution statistics in real-time ## Key Benefits - - **Task Specialization**: Create agents optimized for specific workflows (testing, documentation, refactoring, etc.) - **Context Isolation**: Keep specialized work separate from your main conversation - **Reusability**: Save and reuse agent configurations across projects and sessions - **Controlled Access**: Limit which tools each agent can use for security and focus - **Progress Visibility**: Monitor agent execution with real-time progress updates -## How Subagents Work - -1. **Configuration**: You create subagent configurations that define their behavior, tools, and system prompts -2. **Delegation**: The main AI can automatically delegate tasks to appropriate subagents -3. **Execution**: Subagents work independently, using their configured tools to complete tasks +## How Sub Agents Work +1. **Configuration**: You create Sub Agents configurations that define their behavior, tools, and system prompts +2. **Delegation**: The main AI can automatically delegate tasks to appropriate Sub Agents +3. **Execution**: Sub Agents work independently, using their configured tools to complete tasks 4. **Results**: They return results and execution summaries back to the main conversation ## Getting Started - ### Quick Start +1. **Create your first Sub Agents**: -1. **Create your first subagent**: + `/agents create` - ``` - /agents create - ``` - - Follow the guided wizard to create a specialized agent. + Follow the guided wizard to create a specialized agent. 2. **Manage existing agents**: - ``` - /agents manage - ``` + `/agents manage` - View and manage your configured subagents. - -3. **Use subagents automatically**: - Simply ask the main AI to perform tasks that match your subagents' specializations. The AI will automatically delegate appropriate work. + View and manage your configured Sub Agents. +3. **Use Sub Agents automatically**: Simply ask the main AI to perform tasks that match your Sub Agents’ specializations. The AI will automatically delegate appropriate work. + ### Example Usage - ``` User: "Please write comprehensive tests for the authentication module" - -AI: I'll delegate this to your testing specialist subagent. -[Delegates to "testing-expert" subagent] +AI: I'll delegate this to your testing specialist Sub Agents. +[Delegates to "testing-expert" Sub Agents] [Shows real-time progress of test creation] -[Returns with completed test files and execution summary] +[Returns with completed test files and execution summary]` ``` - ## Management - ### CLI Commands - -Subagents are managed through the `/agents` slash command and its subcommands: - -#### `/agents create` - -Creates a new subagent through a guided step wizard. - +Sub Agents are managed through the `/agents` slash command and its subcommands: +#### /agents create +Creates a new Sub Agents through a guided step wizard. **Usage:** - -``` -/agents create -``` - -#### `/agents manage` - -Opens an interactive management dialog for viewing and managing existing subagents. - +`/agents create` +#### /agents manage +Opens an interactive management dialog for viewing and managing existing Sub Agents. **Usage:** - -``` -/agents manage -``` - +`/agents manage` ### Storage Locations - -Subagents are stored as Markdown files in two locations: - -- **Project-level**: `.qwen/agents/` (takes precedence) -- **User-level**: `~/.qwen/agents/` (fallback) +Sub Agents are stored as Markdown files in two locations: +- **Project-level**: `.qwen/agents/` (takes precedence) +- **User-level**: `~/.qwen/agents/` (fallback) This allows you to have both project-specific agents and personal agents that work across all projects. - ### File Format - -Subagents are configured using Markdown files with YAML frontmatter. This format is human-readable and easy to edit with any text editor. - +Sub Agents are configured using Markdown files with YAML frontmatter. This format is human-readable and easy to edit with any text editor. #### Basic Structure - -```markdown +``` --- name: agent-name description: Brief description of when and how to use this agent -tools: - - tool1 - - tool2 - - tool3 # Optional +tools: + - tool1 + - tool2 + - tool3 # Optional --- System prompt content goes here. Multiple paragraphs are supported. You can use ${variable} templating for dynamic content. ``` - #### Example Usage - -```markdown +``` --- name: project-documenter description: Creates project documentation and README files --- - + You are a documentation specialist for the ${project_name} project. - + Your task: ${task_description} - + Working directory: ${current_directory} Generated on: ${timestamp} - + Focus on creating clear, comprehensive documentation that helps both new contributors and end users understand the project. ``` - -## Using Subagents Effectively - +## Using Sub Agents Effectively ### Automatic Delegation - Qwen Code proactively delegates tasks based on: - - The task description in your request -- The description field in subagent configurations +- The description field in Sub Agents configurations - Current context and available tools -To encourage more proactive subagent use, include phrases like "use PROACTIVELY" or "MUST BE USED" in your description field. - +To encourage more proactive Sub Agents use, include phrases like “use PROACTIVELY” or “MUST BE USED” in your description field. ### Explicit Invocation - -Request a specific subagent by mentioning it in your command: - +Request a specific Sub Agents by mentioning it in your command: ``` -> Let the testing-expert subagent create unit tests for the payment module -> Have the documentation-writer subagent update the API reference -> Get the react-specialist subagent to optimize this component's performance +Let the testing-expert Sub Agents create unit tests for the payment module +Have the documentation-writer Sub Agents update the API reference +Get the react-specialist Sub Agents to optimize this component's performance ``` - ## Examples - ### Development Workflow Agents - #### Testing Specialist - Perfect for comprehensive test creation and test-driven development. - -```markdown +``` --- name: testing-expert description: Writes comprehensive unit tests, integration tests, and handles test automation with best practices @@ -176,41 +125,38 @@ tools: - read_many_files - run_shell_command --- - + You are a testing specialist focused on creating high-quality, maintainable tests. - + Your expertise includes: - + - Unit testing with appropriate mocking and isolation - Integration testing for component interactions - Test-driven development practices - Edge case identification and comprehensive coverage - Performance and load testing when appropriate - + For each testing task: - + 1. Analyze the code structure and dependencies 2. Identify key functionality, edge cases, and error conditions 3. Create comprehensive test suites with descriptive names 4. Include proper setup/teardown and meaningful assertions 5. Add comments explaining complex test scenarios 6. Ensure tests are maintainable and follow DRY principles - + Always follow testing best practices for the detected language and framework. Focus on both positive and negative test cases. ``` **Use Cases:** - -- "Write unit tests for the authentication service" -- "Create integration tests for the payment processing workflow" -- "Add test coverage for edge cases in the data validation module" +- “Write unit tests for the authentication service” +- “Create integration tests for the payment processing workflow” +- “Add test coverage for edge cases in the data validation module” #### Documentation Writer - Specialized in creating clear, comprehensive documentation. - -```markdown +``` --- name: documentation-writer description: Creates comprehensive documentation, README files, API docs, and user guides @@ -220,50 +166,47 @@ tools: - read_many_files - web_search --- - + You are a technical documentation specialist for ${project_name}. - + Your role is to create clear, comprehensive documentation that serves both developers and end users. Focus on: - + **For API Documentation:** - + - Clear endpoint descriptions with examples - Parameter details with types and constraints - Response format documentation - Error code explanations - Authentication requirements - + **For User Documentation:** - + - Step-by-step instructions with screenshots when helpful - Installation and setup guides - Configuration options and examples - Troubleshooting sections for common issues - FAQ sections based on common user questions - + **For Developer Documentation:** - + - Architecture overviews and design decisions - Code examples that actually work - Contributing guidelines - Development environment setup - + Always verify code examples and ensure documentation stays current with the actual implementation. Use clear headings, bullet points, and examples. ``` **Use Cases:** - -- "Create API documentation for the user management endpoints" -- "Write a comprehensive README for this project" -- "Document the deployment process with troubleshooting steps" +- “Create API documentation for the user management endpoints” +- “Write a comprehensive README for this project” +- “Document the deployment process with troubleshooting steps” #### Code Reviewer - Focused on code quality, security, and best practices. - -```markdown +``` --- name: code-reviewer description: Reviews code for best practices, security issues, performance, and maintainability @@ -271,11 +214,11 @@ tools: - read_file - read_many_files --- - + You are an experienced code reviewer focused on quality, security, and maintainability. - + Review criteria: - + - **Code Structure**: Organization, modularity, and separation of concerns - **Performance**: Algorithmic efficiency and resource usage - **Security**: Vulnerability assessment and secure coding practices @@ -283,31 +226,27 @@ Review criteria: - **Error Handling**: Proper exception handling and edge case coverage - **Readability**: Clear naming, comments, and code organization - **Testing**: Test coverage and testability considerations - + Provide constructive feedback with: - + 1. **Critical Issues**: Security vulnerabilities, major bugs 2. **Important Improvements**: Performance issues, design problems 3. **Minor Suggestions**: Style improvements, refactoring opportunities 4. **Positive Feedback**: Well-implemented patterns and good practices - + Focus on actionable feedback with specific examples and suggested solutions. Prioritize issues by impact and provide rationale for recommendations. ``` **Use Cases:** - -- "Review this authentication implementation for security issues" -- "Check the performance implications of this database query logic" -- "Evaluate the code structure and suggest improvements" +- “Review this authentication implementation for security issues” +- “Check the performance implications of this database query logic” +- “Evaluate the code structure and suggest improvements” ### Technology-Specific Agents - #### React Specialist - Optimized for React development, hooks, and component patterns. - -```markdown +``` --- name: react-specialist description: Expert in React development, hooks, component patterns, and modern React best practices @@ -317,42 +256,39 @@ tools: - read_many_files - run_shell_command --- - + You are a React specialist with deep expertise in modern React development. - + Your expertise covers: - + - **Component Design**: Functional components, custom hooks, composition patterns - **State Management**: useState, useReducer, Context API, and external libraries - **Performance**: React.memo, useMemo, useCallback, code splitting - **Testing**: React Testing Library, Jest, component testing strategies - **TypeScript Integration**: Proper typing for props, hooks, and components - **Modern Patterns**: Suspense, Error Boundaries, Concurrent Features - + For React tasks: - + 1. Use functional components and hooks by default 2. Implement proper TypeScript typing 3. Follow React best practices and conventions 4. Consider performance implications 5. Include appropriate error handling 6. Write testable, maintainable code - + Always stay current with React best practices and avoid deprecated patterns. Focus on accessibility and user experience considerations. ``` **Use Cases:** - -- "Create a reusable data table component with sorting and filtering" -- "Implement a custom hook for API data fetching with caching" -- "Refactor this class component to use modern React patterns" +- “Create a reusable data table component with sorting and filtering” +- “Implement a custom hook for API data fetching with caching” +- “Refactor this class component to use modern React patterns” #### Python Expert - Specialized in Python development, frameworks, and best practices. - -```markdown +``` --- name: python-expert description: Expert in Python development, frameworks, testing, and Python-specific best practices @@ -362,11 +298,11 @@ tools: - read_many_files - run_shell_command --- - + You are a Python expert with deep knowledge of the Python ecosystem. - + Your expertise includes: - + - **Core Python**: Pythonic patterns, data structures, algorithms - **Frameworks**: Django, Flask, FastAPI, SQLAlchemy - **Testing**: pytest, unittest, mocking, test-driven development @@ -374,9 +310,9 @@ Your expertise includes: - **Async Programming**: asyncio, async/await patterns - **Package Management**: pip, poetry, virtual environments - **Code Quality**: PEP 8, type hints, linting with pylint/flake8 - + For Python tasks: - + 1. Follow PEP 8 style guidelines 2. Use type hints for better code documentation 3. Implement proper error handling with specific exceptions @@ -384,95 +320,68 @@ For Python tasks: 5. Consider performance and memory usage 6. Include appropriate logging 7. Write testable, modular code - + Focus on writing clean, maintainable Python code that follows community standards. ``` **Use Cases:** - -- "Create a FastAPI service for user authentication with JWT tokens" -- "Implement a data processing pipeline with pandas and error handling" -- "Write a CLI tool using argparse with comprehensive help documentation" +- “Create a FastAPI service for user authentication with JWT tokens” +- “Implement a data processing pipeline with pandas and error handling” +- “Write a CLI tool using argparse with comprehensive help documentation” ## Best Practices - ### Design Principles - #### Single Responsibility Principle - -Each subagent should have a clear, focused purpose. - +Each Sub Agents should have a clear, focused purpose. **✅ Good:** - -```markdown +``` --- name: testing-expert description: Writes comprehensive unit tests and integration tests --- ``` - **❌ Avoid:** - -```markdown +``` --- name: general-helper description: Helps with testing, documentation, code review, and deployment --- ``` - -**Why:** Focused agents produce better results and are easier to maintain. - +**Why:** Focused agents produce better results and are easier to maintain. #### Clear Specialization - Define specific expertise areas rather than broad capabilities. - **✅ Good:** - -```markdown +``` --- name: react-performance-optimizer description: Optimizes React applications for performance using profiling and best practices --- ``` - **❌ Avoid:** - -```markdown +``` --- name: frontend-developer description: Works on frontend development tasks --- ``` - -**Why:** Specific expertise leads to more targeted and effective assistance. - +**Why:** Specific expertise leads to more targeted and effective assistance. #### Actionable Descriptions - Write descriptions that clearly indicate when to use the agent. - **✅ Good:** - -```markdown +``` description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns ``` - **❌ Avoid:** - -```markdown +``` description: A helpful code reviewer ``` - -**Why:** Clear descriptions help the main AI choose the right agent for each task. - +**Why:** Clear descriptions help the main AI choose the right agent for each task. ### Configuration Best Practices - #### System Prompt Guidelines - **Be Specific About Expertise:** - -```markdown +``` You are a Python testing specialist with expertise in: - + - pytest framework and fixtures - Mock objects and dependency injection - Test-driven development practices @@ -480,10 +389,9 @@ You are a Python testing specialist with expertise in: ``` **Include Step-by-Step Approaches:** - -```markdown +``` For each testing task: - + 1. Analyze the code structure and dependencies 2. Identify key functionality and edge cases 3. Create comprehensive test suites with clear naming @@ -492,10 +400,9 @@ For each testing task: ``` **Specify Output Standards:** - -```markdown +``` Always follow these standards: - + - Use descriptive test names that explain the scenario - Include both positive and negative test cases - Add docstrings for complex test functions @@ -503,10 +410,9 @@ Always follow these standards: ``` ## Security Considerations - -- **Tool Restrictions**: Subagents only have access to their configured tools +- **Tool Restrictions**: Sub Agents only have access to their configured tools - **Sandboxing**: All tool execution follows the same security model as direct tool use -- **Audit Trail**: All subagent actions are logged and visible in real-time +- **Audit Trail**: All Sub Agents actions are logged and visible in real-time - **Access Control**: Project and user-level separation provides appropriate boundaries - **Sensitive Information**: Avoid including secrets or credentials in agent configurations - **Production Environments**: Consider separate agents for production vs development environments diff --git a/docs/users/overview.md b/docs/users/overview.md index 09e2c629..496e4522 100644 --- a/docs/users/overview.md +++ b/docs/users/overview.md @@ -7,7 +7,7 @@ Prerequisites: - A [Qwen Code](https://chat.qwen.ai/auth?mode=register) account -- Requires [Node.js 20+](https://nodejs.org/download), you can use `node -v` check the version. If it's not installed, use the following command to install it. +- Requires [Node.js 20+](https://nodejs.org/download), you can use `node -v` to check the version. If it's not installed, use the following command to install it. ```bash curl -qL https://www.npmjs.com/install.sh | sh @@ -54,11 +54,13 @@ You'll be prompted to log in on first use. That's it! [Continue with Quickstart > [!tip] > -> See [advanced setup](/setup) for installation options or [troubleshooting](/troubleshooting) if you hit issues. +> See [troubleshooting](/troubleshooting) if you hit issues. > [!note] > -> **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new [VS Code extension](/vs-code) provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Qwen Code directly in your sidebar. +> **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new **VS Code extension** provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Qwen Code directly in your sidebar. +> +> ![](https://gw.alicdn.com/imgextra/i3/O1CN01E6lixr1Ry28a3EvGw_!!6000000002179-2-tps-1198-646.png) ## What Qwen Code does for you @@ -71,58 +73,4 @@ You'll be prompted to log in on first use. That's it! [Continue with Quickstart * **Works in your terminal**: Not another chat window. Not another IDE. Qwen Code meets you where you already work, with the tools you already love. * **Takes action**: Qwen Code can directly edit files, run commands, and create commits. Need more? [MCP](/mcp) lets Qwen Code read your design docs in Google Drive, update your tickets in Jira, or use *your* custom developer tooling. -* **Unix philosophy**: Qwen Code is composable and scriptable. `tail -f app.log | qwen -p "Slack me if you see any anomalies appear in this log stream"` *works*. Your CI can run `qwen -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`. -* **Enterprise-ready**: Use the Qwen Code API, or host on AWS or GCP. Enterprise-grade [security](/security) and [Terms of Service](https://qwenlm.github.io/qwen-code-docs/support/tos-privacy/) is built-in. - -## Next steps - - - - See Qwen Code in action with practical examples - - - - Step-by-step guides for common workflows - - - - Solutions for common issues with Qwen Code - - - - Add Qwen Code to your IDE - - - - -## Additional resources - - - - Create custom AI agents with the Claude Agent SDK - - - - Configure Qwen Code with Amazon Bedrock or Google Vertex AI - - - - Customize Qwen Code for your workflow - - - - Learn about CLI commands and controls - - - - Clone our development container reference implementation - - - - Discover Qwen Code's safeguards and best practices for safe usage - - - - Understand how Qwen Code handles your data - - +* **Unix philosophy**: Qwen Code is composable and scriptable. `tail -f app.log | qwen -p "Slack me if you see any anomalies appear in this log stream"` *works*. Your CI can run `qwen -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`. \ No newline at end of file diff --git a/docs/users/quickstart.md b/docs/users/quickstart.md index cfb63a29..6cd82a3a 100644 --- a/docs/users/quickstart.md +++ b/docs/users/quickstart.md @@ -91,10 +91,6 @@ You'll see the Qwen Code welcome screen with your session information, recent co ![](https://img.alicdn.com/imgextra/i3/O1CN01PwceZB1esA42wuQQH_!!6000000003926-2-tps-2104-1592.png) -> [!caution] -> -> After logging in (Step 2), your credentials are stored on your system. If you need OpenAI API authentication, you can refer to [Authentication](/authentication). - ## Chat with Qwen Code ### Ask your first question @@ -238,17 +234,25 @@ review my changes and suggest improvements Here are the most important commands for daily use: -| Command | What it does | Example | -| ------------------- | --------------------------------- | ----------------------------------- | -| `qwen` | Start interactive mode | `qwen` | -| `qwen-code "task"` | Run a one-time task | `qwen-code "fix the build error"` | -| `qwen-code -p "query"` | Run one-off query, then exit | `qwen-code -p "explain this function"` | -| `qwen-code -c` | Continue most recent conversation | `qwen-code -c` | -| `qwen-code -r` | Resume a previous conversation | `qwen-code -r` | -| `qwen-code commit` | Create a Git commit | `qwen-code commit` | -| `/clear` | Clear conversation history | `/clear` | -| `/help` | Show available commands | `/help` | -| `quit` or Ctrl+C | Exit Qwen Code | `/quit` | +| Command | What it does | Example | +| --------------------- | ------------------------------------------------------ | ---------------------------------- | +| `qwen` | start Qwen Code | `qwen` | +| `/chat` | Manually save and restore conversation history | Requires sub-commands | +| → `save