vrr/qwen-code
2
0
Fork 0
mirror of https://github.com/QwenLM/qwen-code.git synced 2026-04-28 11:41:04 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

feat: add docs

Browse source
This commit is contained in:
LaZzyMan 2026-01-19 14:51:49 +08:00
parent a546e84887
commit 6e641b8def
14 changed files with 467 additions and 327 deletions
Download patch file Download diff file Expand all files Collapse all files

80
docs/developers/extensions/extension.md
View file

@ -4,11 +4,25 @@ Qwen Code extensions package prompts, MCP servers, and custom commands into a fa
## Extension management
We offer a suite of extension management tools using `qwen extensions` commands.
We offer a suite of extension management tools using both `qwen extensions` CLI commands and `/extensions` slash commands within the interactive CLI.
Note that these commands are not supported from within the CLI, although you can list installed extensions using the `/extensions list` subcommand.
### Runtime Extension Management (Slash Commands)
Note that all of these commands will only be reflected in active CLI sessions on restart.
You can manage extensions at runtime within the interactive CLI using `/extensions` slash commands. These commands support hot-reloading, meaning changes take effect immediately without restarting the application.
| Command | Description |
| ------------------------------------------------------ | --------------------------------------------------------------- |
| `/extensions` or `/extensions list` | List all installed extensions with their status |
| `/extensions install <source>` | Install an extension from a git URL, local path, or marketplace |
| `/extensions uninstall <name>` | Uninstall an extension |
| `/extensions enable <name> --scope <user\|workspace>` | Enable an extension |
| `/extensions disable <name> --scope <user\|workspace>` | Disable an extension |
| `/extensions update <name>` | Update a specific extension |
| `/extensions update --all` | Update all extensions with available updates |
### CLI Extension Management
You can also manage extensions using `qwen extensions` CLI commands. Note that changes made via CLI commands will be reflected in active CLI sessions on restart.
### Installing an extension
@ -98,7 +112,18 @@ The `qwen-extension.json` file contains the configuration for the extension. The
}
},
"contextFileName": "QWEN.md",
"excludeTools": ["run_shell_command"]
"excludeTools": ["run_shell_command"],
"commands": "commands",
"skills": "skills",
"agents": "agents",
"settings": [
{
"name": "API Key",
"description": "Your API key for the service",
"envVar": "MY_API_KEY",
"sensitive": true
}
]
}
```
@ -108,12 +133,18 @@ The `qwen-extension.json` file contains the configuration for the extension. The
- Note that all MCP server configuration options are supported except for `trust`.
- `contextFileName`: The name of the file that contains the context for the extension. This will be used to load the context from the extension directory. If this property is not used but a `QWEN.md` file is present in your extension directory, then that file will be loaded.
- `excludeTools`: An array of tool names to exclude from the model. You can also specify command-specific restrictions for tools that support it, like the `run_shell_command` tool. For example, `"excludeTools": ["run_shell_command(rm -rf)"]` will block the `rm -rf` command. Note that this differs from the MCP server `excludeTools` functionality, which can be listed in the MCP server config. **Important:** Tools specified in `excludeTools` will be disabled for the entire conversation context and will affect all subsequent queries in the current session.
- `commands`: The directory containing custom commands (default: `commands`). Commands are `.md` files that define prompts.
- `skills`: The directory containing custom skills (default: `skills`). Skills are discovered automatically and become available via the `/skills` command.
- `agents`: The directory containing custom subagents (default: `agents`). Subagents are `.yaml` or `.md` files that define specialized AI assistants.
- `settings`: An array of settings that the extension requires. When installing, users will be prompted to provide values for these settings. The values are stored securely and passed to MCP servers as environment variables.
When Qwen Code starts, it loads all the extensions and merges their configurations. If there are any conflicts, the workspace configuration takes precedence.
### Custom commands
Extensions can provide [custom commands](./cli/commands.md#custom-commands) by placing TOML files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions.
Extensions can provide [custom commands](./cli/commands.md#custom-commands) by placing Markdown files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions.
> **Note:** The command format has been updated from TOML to Markdown. TOML files are deprecated but still supported. You can migrate existing TOML commands using the automatic migration prompt that appears when TOML files are detected.
**Example**
@ -123,15 +154,46 @@ An extension named `gcp` with the following structure:
.qwen/extensions/gcp/
├── qwen-extension.json
└── commands/
├── deploy.toml
├── deploy.md
└── gcs/
└── sync.toml
└── sync.md
```
Would provide these commands:
- `/deploy` - Shows as `[gcp] Custom command from deploy.toml` in help
- `/gcs:sync` - Shows as `[gcp] Custom command from sync.toml` in help
- `/deploy` - Shows as `[gcp] Custom command from deploy.md` in help
- `/gcs:sync` - Shows as `[gcp] Custom command from sync.md` in help
### Custom skills
Extensions can provide custom skills by placing skill files in a `skills/` subdirectory within the extension directory. Each skill should have a `SKILL.md` file with YAML frontmatter defining the skill's name and description.
**Example**
```
.qwen/extensions/my-extension/
├── qwen-extension.json
└── skills/
└── pdf-processor/
└── SKILL.md
```
The skill will be available via the `/skills` command when the extension is active.
### Custom subagents
Extensions can provide custom subagents by placing agent configuration files in an `agents/` subdirectory within the extension directory. Agents are defined using YAML or Markdown files.
**Example**
```
.qwen/extensions/my-extension/
├── qwen-extension.json
└── agents/
└── testing-expert.yaml
```
Extension subagents appear in the subagent manager dialog under "Extension Agents" section.
### Conflict resolution

110
docs/developers/extensions/getting-started-extensions.md
View file

@ -148,22 +148,119 @@ Custom commands provide a way to create shortcuts for complex prompts. Let's add
mkdir -p commands/fs
```
2. Create a file named `commands/fs/grep-code.toml`:
2. Create a file named `commands/fs/grep-code.md`:
```markdown
---
description: Search for a pattern in code and summarize findings
---
```toml
prompt = """
Please summarize the findings for the pattern `{{args}}`.
Search Results:
!{grep -r {{args}} .}
"""
```
This command, `/fs:grep-code`, will take an argument, run the `grep` shell command with it, and pipe the results into a prompt for summarization.
> **Note:** Commands use Markdown format with optional YAML frontmatter. TOML format is deprecated but still supported for backwards compatibility.
After saving the file, restart the Qwen Code. You can now run `/fs:grep-code "some pattern"` to use your new command.
## Step 5: Add a Custom `QWEN.md`
## Step 5: Add Custom Skills and Subagents (Optional)
Extensions can also provide custom skills and subagents to extend Qwen Code's capabilities.
### Adding a Custom Skill
Skills are model-invoked capabilities that the AI can automatically use when relevant.
1. Create a `skills` directory with a skill subdirectory:
```bash
mkdir -p skills/code-analyzer
```
2. Create a `skills/code-analyzer/SKILL.md` file:
```markdown
---
name: code-analyzer
description: Analyzes code structure and provides insights about complexity, dependencies, and potential improvements
---
# Code Analyzer
## Instructions
When analyzing code, focus on:
- Code complexity and maintainability
- Dependencies and coupling
- Potential performance issues
- Suggestions for improvements
## Examples
- "Analyze the complexity of this function"
- "What are the dependencies of this module?"
```
### Adding a Custom Subagent
Subagents are specialized AI assistants for specific tasks.
1. Create an `agents` directory:
```bash
mkdir -p agents
```
2. Create an `agents/refactoring-expert.md` file:
```markdown
---
name: refactoring-expert
description: Specialized in code refactoring, improving code structure and maintainability
tools:
- read_file
- write_file
- read_many_files
---
You are a refactoring specialist focused on improving code quality.
Your expertise includes:
- Identifying code smells and anti-patterns
- Applying SOLID principles
- Improving code readability and maintainability
- Safe refactoring with minimal risk
For each refactoring task:
1. Analyze the current code structure
2. Identify areas for improvement
3. Propose refactoring steps
4. Implement changes incrementally
5. Verify functionality is preserved
```
3. Update your `qwen-extension.json` to include the new directories:
```json
{
"name": "my-first-extension",
"version": "1.0.0",
"skills": "skills",
"agents": "agents",
"mcpServers": { ... }
}
```
After restarting Qwen Code, your custom skills will be available via `/skills` and subagents via `/agents manage`.
## Step 6: Add a Custom `QWEN.md`
You can provide persistent context to the model by adding a `QWEN.md` file to your extension. This is useful for giving the model instructions on how to behave or information about your extension's tools. Note that you may not always need this for extensions built to expose commands and prompts.
@ -194,7 +291,7 @@ You can provide persistent context to the model by adding a `QWEN.md` file to yo
Restart the CLI again. The model will now have the context from your `QWEN.md` file in every session where the extension is active.
## Step 6: Releasing Your Extension
## Step 7: Releasing Your Extension
Once you are happy with your extension, you can share it with others. The two primary ways of releasing extensions are via a Git repository or through GitHub Releases. Using a public Git repository is the simplest method.
@ -207,6 +304,7 @@ You've successfully created a Qwen Code extension! You learned how to:
- Bootstrap a new extension from a template.
- Add custom tools with an MCP server.
- Create convenient custom commands.
- Add custom skills and subagents.
- Provide persistent context to the model.
- Link your extension for local development.