abbyswag/qwen-code
1
0
Fork 0
mirror of https://github.com/QwenLM/qwen-code.git synced 2025-12-20 08:47:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: update docs

Browse Source
This commit is contained in:
pomelo-nwu
2025-12-15 09:47:03 +08:00
parent 57df439f43
commit 60211b8180
11 changed files with 717 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/developers/tools/_meta.ts
View File

@@ -1,9 +1,11 @@
export default {
index: 'Introduction',
introduction: 'Introduction',
'file-system': 'File System',
'multi-file': 'Multi-File Read',
shell: 'Shell',
'todo-write': 'Todo Write',
task: 'Task',
'exit-plan-mode': 'Exit Plan Mode',
'web-fetch': 'Web Fetch',
'web-search': 'Web Search',
memory: 'Memory',

149
docs/developers/tools/exit-plan-mode.md Normal file
View File

@@ -0,0 +1,149 @@
# Exit Plan Mode Tool (`exit_plan_mode`)
This document describes the `exit_plan_mode` tool for Qwen Code.
## Description
Use `exit_plan_mode` when you are in plan mode and have finished presenting your implementation plan. This tool prompts the user to approve or reject the plan and transitions from planning mode to implementation mode.
The tool is specifically designed for tasks that require planning implementation steps before writing code. It should NOT be used for research or information-gathering tasks.
### Arguments
`exit_plan_mode` takes one argument:
- `plan` (string, required): The implementation plan you want to present to the user for approval. This should be a concise, markdown-formatted plan describing the implementation steps.
## How to use `exit_plan_mode` with Qwen Code
The Exit Plan Mode tool is part of Qwen Code's planning workflow. When you're in plan mode (typically after exploring a codebase and designing an implementation approach), you use this tool to:
1. Present your implementation plan to the user
2. Request approval to proceed with implementation
3. Transition from plan mode to implementation mode based on user response
The tool will prompt the user with your plan and provide options to:
- **Proceed Once**: Approve the plan for this session only
- **Proceed Always**: Approve the plan and enable auto-approval for future edit operations
- **Cancel**: Reject the plan and remain in planning mode
Usage:
```
exit_plan_mode(plan="Your detailed implementation plan here...")
```
## When to Use This Tool
Use `exit_plan_mode` when:
1. **Implementation tasks**: You are planning the implementation steps for a coding task
2. **Plan completion**: You have finished exploring and designing your implementation approach
3. **User approval needed**: You need user confirmation before proceeding with code changes
4. **Code writing tasks**: The task involves writing, modifying, or refactoring code
### Examples of appropriate usage:
- "Help me implement user authentication" → Use after planning the auth system implementation
- "Add a new API endpoint for user management" → Use after designing the endpoint structure
- "Refactor the database layer to use TypeORM" → Use after planning the refactoring approach
## When NOT to Use This Tool
Do NOT use `exit_plan_mode` for:
1. **Research tasks**: Tasks focused on understanding or exploring existing code
2. **Information gathering**: When you're searching, reading, or analyzing without implementing
3. **Documentation tasks**: When creating documentation without code changes
4. **Analysis tasks**: When providing explanations or reviews without implementation
### Examples of inappropriate usage:
- "Search for and understand the implementation of vim mode in the codebase" → Don't use (research task)
- "Explain how the authentication system works" → Don't use (analysis task)
- "Find all TODO comments in the project" → Don't use (information gathering)
## `exit_plan_mode` examples
### Implementation planning example
```
exit_plan_mode(plan="## Implementation Plan for User Dashboard
### 1. Create Dashboard Components
- Create `UserDashboard.tsx` with main dashboard layout
- Add `DashboardStats.tsx` for displaying user statistics
- Implement `ActivityFeed.tsx` for recent user activities
### 2. Add API Integration
- Create `dashboardApi.ts` for dashboard data fetching
- Add endpoints for user stats and activity data
- Implement error handling and loading states
### 3. Update Routing
- Add dashboard route in `App.tsx`
- Update navigation component with dashboard link
- Add route protection for authenticated users
### 4. Testing and Documentation
- Write unit tests for dashboard components
- Add integration tests for API calls
- Update user documentation with dashboard features
This implementation will take approximately 4-6 hours and requires changes to 8-10 files.")
```
### Refactoring plan example
```
exit_plan_mode(plan="## Database Layer Refactoring Plan
### Phase 1: Setup and Configuration
- Install and configure TypeORM dependencies
- Create database connection configuration
- Set up entity definitions for existing models
### Phase 2: Migration
- Create migration scripts for existing data
- Implement new repository pattern using TypeORM
- Replace raw SQL queries with TypeORM query builder
### Phase 3: Testing and Validation
- Update all database tests to use TypeORM
- Validate data integrity after migration
- Performance testing to ensure no regressions
This refactoring will modernize our database layer while maintaining backward compatibility.")
```
## User Response Handling
After calling `exit_plan_mode`, the user can respond in several ways:
- **Proceed Once**: The plan is approved for immediate implementation with default confirmation settings
- **Proceed Always**: The plan is approved and auto-approval is enabled for subsequent edit operations
- **Cancel**: The plan is rejected, and the system remains in plan mode for further planning
The tool automatically adjusts the approval mode based on the user's choice, streamlining the implementation process according to user preferences.
## Important Notes
- **Plan mode only**: This tool should only be used when you are currently in plan mode
- **Implementation focus**: Only use for tasks that involve writing or modifying code
- **Concise plans**: Keep plans focused and concise - aim for clarity over exhaustive detail
- **Markdown support**: Plans support markdown formatting for better readability
- **Single use**: The tool should be used once per planning session when ready to proceed
- **User control**: The final decision to proceed always rests with the user
## Integration with Planning Workflow
The Exit Plan Mode tool is part of a larger planning workflow:
1. **Enter Plan Mode**: User requests or system determines planning is needed
2. **Exploration Phase**: Analyze codebase, understand requirements, explore options
3. **Plan Design**: Create implementation strategy based on exploration
4. **Plan Presentation**: Use `exit_plan_mode` to present plan to user
5. **Implementation Phase**: Upon approval, proceed with planned implementation
This workflow ensures thoughtful implementation approaches and gives users control over significant code changes.

4
docs/developers/tools/file-system.md
View File

@@ -83,7 +83,7 @@ Qwen Code provides a comprehensive suite of tools for interacting with the local
- **Tool name:** `grep_search`
- **Display name:** Grep
- **File:** `ripGrep.ts` (with `grep.ts` as fallback)
- **File:** `grep.ts` (with `ripGrep.ts` as fallback)
- **Parameters:**
- `pattern` (string, required): The regular expression pattern to search for in file contents (e.g., `"function\\s+myFunction"`, `"log.*Error"`).
- `path` (string, optional): File or directory to search in. Defaults to current working directory.
@@ -141,7 +141,7 @@ grep_search(pattern="function", glob="*.js", limit=10)
- `file_path` (string, required): The absolute path to the file to modify.
- `old_string` (string, required): The exact literal text to replace.
**CRITICAL:** This string must uniquely identify the single instance to change. It should include at least 3 lines of context _before_ and _after_ the target text, matching whitespace and indentation precisely. If `old_string` is empty, the tool attempts to create a new file at `file_path` with `new_string` as content.
**CRITICAL:** This string must uniquely identify the single instance to change. It should include sufficient context around the target text, matching whitespace and indentation precisely. If `old_string` is empty, the tool attempts to create a new file at `file_path` with `new_string` as content.
- `new_string` (string, required): The exact literal text to replace `old_string` with.
- `replace_all` (boolean, optional): Replace all occurrences of `old_string`. Defaults to `false`.

2
docs/developers/tools/index.md → docs/developers/tools/introduction.md
View File

@@ -50,6 +50,8 @@ Qwen Code's built-in tools can be broadly categorized as follows:
- **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** A specialized tool for reading content from multiple files or directories, often used by the `@` command.
- **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling information across sessions.
- **[Todo Write Tool](./todo-write.md) (`todo_write`):** For creating and managing structured task lists during coding sessions.
- **[Task Tool](./task.md) (`task`):** For delegating complex tasks to specialized subagents.
- **[Exit Plan Mode Tool](./exit-plan-mode.md) (`exit_plan_mode`):** For exiting plan mode and proceeding with implementation.
Additionally, these tools incorporate:

145
docs/developers/tools/task.md Normal file
View File

@@ -0,0 +1,145 @@
# Task Tool (`task`)
This document describes the `task` tool for Qwen Code.
## Description
Use `task` to launch a specialized subagent to handle complex, multi-step tasks autonomously. The Task tool delegates work to specialized agents that can work independently with access to their own set of tools, allowing for parallel task execution and specialized expertise.
### Arguments
`task` takes the following arguments:
- `description` (string, required): A short (3-5 word) description of the task for user visibility and tracking purposes.
- `prompt` (string, required): The detailed task prompt for the subagent to execute. Should contain comprehensive instructions for autonomous execution.
- `subagent_type` (string, required): The type of specialized agent to use for this task. Must match one of the available configured subagents.
## How to use `task` with Qwen Code
The Task tool dynamically loads available subagents from your configuration and delegates tasks to them. Each subagent runs independently and can use its own set of tools, allowing for specialized expertise and parallel execution.
When you use the Task tool, the subagent will:
1. Receive the task prompt with full autonomy
2. Execute the task using its available tools
3. Return a final result message
4. Terminate (subagents are stateless and single-use)
Usage:
```
task(description="Brief task description", prompt="Detailed task instructions for the subagent", subagent_type="agent_name")
```
## Available Subagents
The available subagents depend on your configuration. Common subagent types might include:
- **general-purpose**: For complex multi-step tasks requiring various tools
- **code-reviewer**: For reviewing and analyzing code quality
- **test-runner**: For running tests and analyzing results
- **documentation-writer**: For creating and updating documentation
You can view available subagents by using the `/agents` command in Qwen Code.
## Task Tool Features
### Real-time Progress Updates
The Task tool provides live updates showing:
- Subagent execution status
- Individual tool calls being made by the subagent
- Tool call results and any errors
- Overall task progress and completion status
### Parallel Execution
You can launch multiple subagents concurrently by calling the Task tool multiple times in a single message, allowing for parallel task execution and improved efficiency.
### Specialized Expertise
Each subagent can be configured with:
- Specific tool access permissions
- Specialized system prompts and instructions
- Custom model configurations
- Domain-specific knowledge and capabilities
## `task` examples
### Delegating to a general-purpose agent
```
task(
description="Code refactoring",
prompt="Please refactor the authentication module in src/auth/ to use modern async/await patterns instead of callbacks. Ensure all tests still pass and update any related documentation.",
subagent_type="general-purpose"
)
```
### Running parallel tasks
```
# Launch code review and test execution in parallel
task(
description="Code review",
prompt="Review the recent changes in the user management module for code quality, security issues, and best practices compliance.",
subagent_type="code-reviewer"
)
task(
description="Run tests",
prompt="Execute the full test suite and analyze any failures. Provide a summary of test coverage and recommendations for improvement.",
subagent_type="test-runner"
)
```
### Documentation generation
```
task(
description="Update docs",
prompt="Generate comprehensive API documentation for the newly implemented REST endpoints in the orders module. Include request/response examples and error codes.",
subagent_type="documentation-writer"
)
```
## When to Use the Task Tool
Use the Task tool when:
1. **Complex multi-step tasks** - Tasks requiring multiple operations that can be handled autonomously
2. **Specialized expertise** - Tasks that benefit from domain-specific knowledge or tools
3. **Parallel execution** - When you have multiple independent tasks that can run simultaneously
4. **Delegation needs** - When you want to hand off a complete task rather than micromanaging steps
5. **Resource-intensive operations** - Tasks that might take significant time or computational resources
## When NOT to Use the Task Tool
Don't use the Task tool for:
- **Simple, single-step operations** - Use direct tools like Read, Edit, etc.
- **Interactive tasks** - Tasks requiring back-and-forth communication
- **Specific file reads** - Use Read tool directly for better performance
- **Simple searches** - Use Grep or Glob tools directly
## Important Notes
- **Stateless execution**: Each subagent invocation is independent with no memory of previous executions
- **Single communication**: Subagents provide one final result message - no ongoing communication
- **Comprehensive prompts**: Your prompt should contain all necessary context and instructions for autonomous execution
- **Tool access**: Subagents only have access to tools configured in their specific configuration
- **Parallel capability**: Multiple subagents can run simultaneously for improved efficiency
- **Configuration dependent**: Available subagent types depend on your system configuration
## Configuration
Subagents are configured through Qwen Code's agent configuration system. Use the `/agents` command to:
- View available subagents
- Create new subagent configurations
- Modify existing subagent settings
- Set tool permissions and capabilities
For more information on configuring subagents, refer to the subagents documentation.

14
docs/developers/tools/todo-write.md
View File

@@ -11,9 +11,9 @@ Use `todo_write` to create and manage a structured task list for your current co
`todo_write` takes one argument:
- `todos` (array, required): An array of todo items, where each item contains:
- `id` (string, required): A unique identifier for the todo item.
- `content` (string, required): The description of the task.
- `status` (string, required): The current status (`pending`, `in_progress`, or `completed`).
- `activeForm` (string, required): The present continuous form describing what is being done (e.g., "Running tests", "Building the project").
## How to use `todo_write` with Qwen Code
@@ -39,19 +39,19 @@ Creating a feature implementation plan:
```
todo_write(todos=[
{
"id": "create-model",
"content": "Create user preferences model",
"status": "pending"
"status": "pending",
"activeForm": "Creating user preferences model"
},
{
"id": "add-endpoints",
"content": "Add API endpoints for preferences",
"status": "pending"
"status": "pending",
"activeForm": "Adding API endpoints for preferences"
},
{
"id": "implement-ui",
"content": "Implement frontend components",
"status": "pending"
"status": "pending",
"activeForm": "Implementing frontend components"
}
])
```