diff --git a/docs/tools/qwen-code/01-overview.md b/docs/tools/qwen-code/01-overview.md index 0f1a53b1..69d4b0e7 100644 --- a/docs/tools/qwen-code/01-overview.md +++ b/docs/tools/qwen-code/01-overview.md @@ -59,7 +59,13 @@ AGENTS.md 声明：*"This project is based on Google Gemini CLI with adaptations ## 安装 ```bash -# npm（推荐，需要 Node.js 20+） +# 一键安装脚本（推荐，Linux/macOS） +curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash + +# Windows（以管理员身份运行 CMD） +curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat + +# npm（需要 Node.js 20+） npm install -g @qwen-code/qwen-code@latest # bun @@ -72,6 +78,8 @@ brew install qwen-code qwen --version ``` +> **VS Code 扩展（Beta）**：Qwen Code Companion 提供图形化 IDE 体验，从 VS Code Marketplace 安装即可在侧边栏中使用。 + ## 模型支持 | 提供商 | 默认模型 | 认证方式 | 免费额度 | diff --git a/docs/tools/qwen-code/02-commands.md b/docs/tools/qwen-code/02-commands.md index efedc40a..13486e56 100644 --- a/docs/tools/qwen-code/02-commands.md +++ b/docs/tools/qwen-code/02-commands.md @@ -124,6 +124,54 @@ Qwen Code 提供 41 个内置斜杠命令，加上从 MCP prompts、bundled skil | `/memory` | `show` / `add` / `refresh` | 查看/添加/刷新记忆 | | `/stats` | `model` / `tools` | 模型/工具使用统计 | +## 其他命令类型 + +> 来源：[官方文档](https://qwenlm.github.io/qwen-code-docs/zh/users/features/commands/) + +除斜杠命令外，Qwen Code 还支持 3 种命令类型： + +### @ 命令（文件/目录注入） + +```bash +@src/auth/login.ts # 将文件内容注入为上下文 +@src/components/ # 递归读取目录下所有文本文件注入为上下文 +``` + +### ! 命令（Shell 执行） + +```bash +!git status # 直接执行 Shell 命令 +!npm test # 运行测试 +! # 单独 ! 进入 Shell 模式 +``` + +### 自定义命令（Markdown 文件） + +在 `~/.qwen/commands/`（用户级）或 `.qwen/commands/`（项目级）放置 `.md` 文件： + +```markdown +--- +name: deploy +description: 部署到测试环境 +--- + +请执行以下部署步骤： +1. 运行 !{npm run build} 构建项目 +2. 读取 @{deploy.config.json} 获取配置 +3. 使用 {{args}} 作为目标环境参数 +``` + +支持变量（处理顺序：`@{...}` → `!{...}` → `{{args}}`）： +- `{{args}}`——参数注入 +- `!{command}`——Shell 命令执行 +- `@{filepath}`——文件内容注入 + +**目录映射规则**：`commands/git/commit.md` → `/git:commit` + +> **注**：TOML 格式命令文件已弃用但仍受支持，便于旧命令迁移。`!` 命令执行时自动设置 `QWEN_CODE=1` 环境变量。`@` 路径含空格时用 `\` 转义（如 `@My\ Documents/file.txt`）。 + +项目级命令优先于用户级。 + ## CLI 参数 ```bash diff --git a/docs/tools/qwen-code/05-settings.md b/docs/tools/qwen-code/05-settings.md new file mode 100644 index 00000000..afb4ad6b --- /dev/null +++ b/docs/tools/qwen-code/05-settings.md @@ -0,0 +1,284 @@ +# 5. Qwen Code 配置系统 + +> 来源：[官方文档](https://qwenlm.github.io/qwen-code-docs/zh/users/configuration/settings/)，v0.3.0+ 嵌套结构格式 + +## 配置层级（7 层优先级） + +| 层级 | 配置来源 | 说明 | +|------|----------|------| +| 1（最低） | 默认值 | 硬编码默认值 | +| 2 | 系统默认配置文件 | `/etc/qwen-code/system-defaults.json` | +| 3 | 用户配置文件 | `~/.qwen/settings.json` | +| 4 | 项目配置文件 | `.qwen/settings.json` | +| 5 | 系统配置文件 | `/etc/qwen-code/settings.json`（企业管控） | +| 6 | 环境变量 | `QWEN_*` 系列 + `.env` 文件 | +| 7（最高） | 命令行参数 | `--model`、`--yolo` 等 | + +## 设置文件位置 + +| 文件类型 | Linux | macOS | Windows | +|----------|-------|-------|---------| +| 系统默认 | `/etc/qwen-code/system-defaults.json` | `/Library/Application Support/QwenCode/system-defaults.json` | `C:\ProgramData\qwen-code\system-defaults.json` | +| 用户设置 | `~/.qwen/settings.json` | 同 | 同 | +| 项目设置 | `.qwen/settings.json` | 同 | 同 | +| 系统设置 | `/etc/qwen-code/settings.json` | `/Library/Application Support/QwenCode/settings.json` | `C:\ProgramData\qwen-code\settings.json` | + +> **环境变量引用**：`settings.json` 中字符串值支持 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量。 + +## 设置项参考 + +> 以下覆盖官方文档中的所有分类。路径可通过 `QWEN_CODE_SYSTEM_DEFAULTS_PATH` 和 `QWEN_CODE_SYSTEM_SETTINGS_PATH` 环境变量覆盖。 + +### general（常规） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `general.preferredEditor` | string | — | 打开文件的首选编辑器 | +| `general.vimMode` | boolean | `false` | 启用 Vim 键绑定 | +| `general.enableAutoUpdate` | boolean | `true` | 自动检查并安装更新 | +| `general.gitCoAuthor` | boolean | `true` | Git 提交自动添加 Co-authored-by | +| `general.checkpointing.enabled` | boolean | `false` | 启用会话检查点（支持恢复） | +| `general.defaultFileEncoding` | string | `"utf-8"` | 新建文件编码（`"utf-8"` 或 `"utf-8-bom"`） | + +### output（输出） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `output.format` | string | `"text"` | CLI 输出格式：`"text"` 或 `"json"` | + +### model（模型） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `model.name` | string | — | 会话使用的模型 | +| `model.maxSessionTurns` | number | `-1` | 单次会话最大交互轮数（-1 无限制） | +| `model.generationConfig` | object | — | 高级生成参数（详见用户指南 modelProviders 章节） | +| `model.chatCompression.contextPercentageThreshold` | number | `0.7` | 压缩触发阈值（0~1，0.7 = 70%）。设为 0 禁用压缩 | +| `model.skipNextSpeakerCheck` | boolean | `false` | 跳过下一轮发言者检查 | +| `model.skipLoopDetection` | boolean | `false` | 禁用循环检测（频繁误报时可启用） | +| `model.skipStartupContext` | boolean | `false` | 跳过启动时发送工作区上下文 | +| `model.enableOpenAILogging` | boolean | `false` | 启用 OpenAI API 调用日志 | +| `model.openAILoggingDir` | string | — | 日志目录（支持 `~`、相对路径、绝对路径） | + +### ui（界面） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `ui.theme` | string | — | 颜色主题 | +| `ui.customThemes` | object | `{}` | 自定义主题定义 | +| `ui.hideTips` | boolean | `false` | 隐藏提示信息 | +| `ui.hideBanner` | boolean | `false` | 隐藏横幅 | +| `ui.hideFooter` | boolean | `false` | 隐藏底部页脚 | +| `ui.showLineNumbers` | boolean | `true` | 代码块显示行号 | +| `ui.showMemoryUsage` | boolean | `false` | 显示内存使用量 | +| `ui.showCitations` | boolean | `true` | 显示引用来源 | +| `ui.hideWindowTitle` | boolean | `false` | 隐藏窗口标题栏 | +| `ui.accessibility.enableLoadingPhrases` | boolean | `true` | 加载状态提示语（无障碍时禁用） | +| `ui.accessibility.screenReader` | boolean | `false` | 屏幕阅读器模式 | +| `ui.customWittyPhrases` | string[] | `[]` | 自定义加载提示语列表 | +| `ui.enableWelcomeBack` | boolean | `true` | 返回项目时显示"欢迎回来"对话框 | + +### ide（IDE 集成） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `ide.enabled` | boolean | `false` | 启用 IDE 集成模式 | +| `ide.hasSeenNudge` | boolean | `false` | 用户是否已看到 IDE 提示 | + +### tools（工具） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `tools.approvalMode` | string | `"default"` | 审批模式：`plan`/`default`/`auto-edit`/`yolo` | +| `tools.sandbox` | boolean/string | — | 沙箱环境（`true`/`false`/`"docker"`/`"podman"`） | +| `tools.shell.enableInteractiveShell` | boolean | `false` | 使用 node-pty 交互式 Shell | +| `tools.core` | string[] | — | 内置工具白名单（支持命令级限制） | +| `tools.exclude` | string[] | — | 排除工具黑名单 | +| `tools.allowed` | string[] | — | 跳过确认的工具列表 | +| `tools.discoveryCommand` | string | — | 工具发现命令 | +| `tools.callCommand` | string | — | 自定义工具调用命令 | +| `tools.useRipgrep` | boolean | `true` | 使用 ripgrep 搜索 | +| `tools.useBuiltinRipgrep` | boolean | `true` | 使用内置 ripgrep 二进制（`false` 时用系统 `rg`） | +| `tools.truncateToolOutputThreshold` | number | `25000` | 工具输出截断字符数 | +| `tools.truncateToolOutputLines` | number | `1000` | 截断时保留最大行数 | + +> **安全提示**：`tools.exclude` 中对 Shell 的命令级限制基于简单字符串匹配，易被绕过。建议用 `tools.core` 显式声明允许的命令。 + +### context（上下文） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `context.fileName` | string/string[] | — | 上下文文件名（默认 `QWEN.md`，支持数组） | +| `context.includeDirectories` | string[] | `[]` | 额外包含的目录（最多 5 个） | +| `context.fileFiltering.respectGitIgnore` | boolean | `true` | 搜索时遵守 .gitignore | +| `context.fileFiltering.respectQwenIgnore` | boolean | `true` | 搜索时遵守 .qwenignore | +| `context.importFormat` | string | — | 导入记忆时使用的格式 | +| `context.loadFromIncludeDirectories` | boolean | `false` | `/memory refresh` 是否从所有目录加载 QWEN.md | +| `context.fileFiltering.enableFuzzySearch` | boolean | `true` | 启用模糊搜索（大项目可禁用提升性能） | +| `context.fileFiltering.enableRecursiveFileSearch` | boolean | `true` | @ 补全时递归搜索文件 | + +### mcpServers（MCP 服务器） + +| 属性 | 类型 | 说明 | +|------|------|------| +| `command` | string | Stdio 启动命令 | +| `args` | string[] | 命令参数 | +| `env` | object | 环境变量 | +| `cwd` | string | 工作目录 | +| `url` | string | SSE 服务器 URL | +| `httpUrl` | string | Streamable HTTP 服务器 URL | +| `headers` | object | 自定义 HTTP 头 | +| `timeout` | number | 超时（毫秒） | +| `trust` | boolean | 信任服务器（跳过确认） | +| `description` | string | 服务器描述 | +| `includeTools` | string[] | 工具白名单 | +| `excludeTools` | string[] | 工具黑名单（优先于 includeTools） | + +> 连接优先级：`httpUrl` > `url` > `command` + +### mcp（MCP 全局配置） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `mcp.serverCommand` | string | — | 启动 MCP 服务器的命令 | +| `mcp.allowed` | string[] | — | 允许连接的 MCP 服务器白名单 | +| `mcp.excluded` | string[] | — | 禁止连接的黑名单（优先于 allowed） | + +> 优先级：`httpUrl` > `url` > `command` + +### privacy（隐私） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `privacy.usageStatisticsEnabled` | boolean | `true` | 使用统计收集 | + +### security（安全） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `security.folderTrust.enabled` | boolean | `false` | 文件夹信任 | +| `security.auth.selectedType` | string | — | 当前认证类型 | +| `security.auth.enforcedType` | string | — | 强制认证类型（企业用） | +| `security.auth.useExternal` | boolean | — | 使用外部认证流程 | + +### advanced（高级） + +| 设置 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `advanced.autoConfigureMemory` | boolean | `false` | 自动配置 Node.js 内存限制 | +| `advanced.dnsResolutionOrder` | string | — | DNS 解析顺序 | +| `advanced.excludedEnvVars` | string[] | `["DEBUG","DEBUG_MODE"]` | 从项目上下文排除的环境变量 | +| `advanced.bugCommand` | object | — | `/bug` 命令 URL 覆盖 | +| `advanced.tavilyApiKey` | string | — | Tavily Web 搜索 API Key（旧格式） | + +### telemetry（遥测） + +| 设置 | 说明 | +|------|------| +| `telemetry.enabled` | 遥测开关 | +| `telemetry.target` | 遥测目标（`local`/`gcp`） | +| `telemetry.otlpEndpoint` | OTLP 端点 | +| `telemetry.otlpProtocol` | OTLP 协议（`grpc`/`http`） | +| `telemetry.logPrompts` | 日志中包含用户提示词 | +| `telemetry.outfile` | 本地遥测输出文件路径 | +| `telemetry.useCollector` | 使用外部 OTLP 收集器 | + +## 配置迁移（旧格式→新格式） + +v0.3.0 起，旧的否定式命名自动迁移为肯定式： + +| 旧设置 | 新设置 | +|--------|--------| +| `disableAutoUpdate` + `disableUpdateNag` | `general.enableAutoUpdate` | +| `disableLoadingPhrases` | `ui.accessibility.enableLoadingPhrases` | +| `disableFuzzySearch` | `context.fileFiltering.enableFuzzySearch` | +| `disableCacheControl` | `model.generationConfig.enableCacheControl` | + +> 布尔值自动取反：`disableAutoUpdate: true` → `enableAutoUpdate: false` + +## 完整示例 + +```json +{ + "general": { + "vimMode": true, + "preferredEditor": "code" + }, + "ui": { + "theme": "GitHub", + "hideTips": false + }, + "model": { + "name": "qwen3-coder-plus", + "maxSessionTurns": 10, + "generationConfig": { + "timeout": 60000, + "contextWindowSize": 128000, + "samplingParams": { "temperature": 0.2, "max_tokens": 4096 } + } + }, + "tools": { + "approvalMode": "default", + "sandbox": "docker" + }, + "context": { + "fileName": ["QWEN.md", "CONTEXT.md"], + "includeDirectories": ["~/shared-context"] + }, + "mcpServers": { + "postgres": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-postgres"], + "env": { "DATABASE_URL": "$DATABASE_URL" } + } + }, + "privacy": { + "usageStatisticsEnabled": true + } +} +``` + +## 环境变量 + +| 变量 | 说明 | +|------|------| +| `QWEN_TELEMETRY_ENABLED` | 遥测开关（覆盖 settings） | +| `QWEN_SANDBOX` | 沙箱模式 | +| `SEATBELT_PROFILE` | macOS Seatbelt 配置（`permissive-open`/`strict`） | +| `NO_COLOR` | 禁用彩色输出 | +| `TAVILY_API_KEY` | Tavily Web 搜索 API Key | +| `DEBUG` / `DEBUG_MODE` | 启用调试日志 | +| `QWEN_CODE_SYSTEM_DEFAULTS_PATH` | 覆盖系统默认配置文件路径 | +| `QWEN_CODE_SYSTEM_SETTINGS_PATH` | 覆盖系统设置文件路径 | +| `QWEN_CODE_LANG` | 设置 UI 语言 | +| `CLI_TITLE` | 自定义 CLI 标题 | + +## 沙箱 + +沙箱默认禁用，以下场景自动或手动启用： +- `--sandbox` / `-s` 参数 +- `QWEN_SANDBOX` 环境变量 +- `--yolo` 模式下默认启用沙箱 +- 支持 Docker / Podman / macOS Seatbelt / 自定义命令 + +macOS Seatbelt 配置文件（通过 `SEATBELT_PROFILE` 环境变量切换）： +- `permissive-open`（默认）：仅限制写入 +- `strict`：严格模式 +- 自定义：`.qwen/sandbox-macos-.sb` + +## 信任文件夹 + +通过 `security.folderTrust.enabled: true` 启用。未信任的文件夹中，Qwen Code 会： +- 忽略 `.qwen/settings.json` 和 `.env` 文件 +- 禁用扩展 +- 强制手动工具确认 + +## 退出码 + +| 码 | 错误 | 说明 | +|---|------|------| +| 41 | FatalAuthenticationError | 认证失败 | +| 42 | FatalInputError | 无效输入 | +| 44 | FatalSandboxError | 沙箱错误 | +| 52 | FatalConfigError | settings.json 无效 | +| 53 | FatalTurnLimitedError | 达到最大轮数 | diff --git a/docs/tools/qwen-code/06-extensions.md b/docs/tools/qwen-code/06-extensions.md new file mode 100644 index 00000000..0af4f62c --- /dev/null +++ b/docs/tools/qwen-code/06-extensions.md @@ -0,0 +1,140 @@ +# 6. Qwen Code 扩展系统 + +> 来源：[官方文档](https://qwenlm.github.io/qwen-code-docs/zh/users/extension/introduction/) + +## 概述 + +Qwen Code 扩展将提示词、MCP 服务器、子智能体、技能和自定义命令打包为统一格式。关键特性：**跨平台兼容**——来自 Gemini CLI 扩展画廊和 Claude Code 应用市场的扩展可直接安装。 + +## 扩展管理命令 + +### 交互式（斜杠命令） + +| 命令 | 说明 | +|------|------| +| `/extensions` 或 `/extensions manage` | 管理已安装扩展 | +| `/extensions install ` | 从 Git URL、本地路径或市场安装 | +| `/extensions explore Gemini` | 打开 Gemini CLI 扩展画廊 | +| `/extensions explore Claude Code` | 打开 Claude Code 应用市场 | + +### CLI 命令 + +```bash +# 安装 +qwen extensions install +qwen extensions install / +qwen extensions install /path/to/local/extension + +# Claude Code 市场 +qwen extensions install +qwen extensions install : + +# 卸载 +qwen extensions uninstall + +# 禁用/启用 +qwen extensions disable # 用户级 +qwen extensions disable --scope=workspace # 仅当前项目 +qwen extensions enable + +# 更新 +qwen extensions update +qwen extensions update --all + +# 设置管理 +qwen extensions settings set [--scope user|workspace] +qwen extensions settings list +qwen extensions settings show +qwen extensions settings unset +``` + +## 跨平台安装 + +### Claude Code 插件 + +```bash +qwen extensions install +# 例如： +qwen extensions install f/awesome-chatgpt-prompts:prompts.chat +``` + +安装过程自动转换： +- `claude-plugin.json` → `qwen-extension.json` +- Agent 配置 → Qwen 子 Agent 格式 +- Skill 配置 → Qwen Skill 格式 +- 工具映射自动处理 + +### Gemini CLI 扩展 + +```bash +qwen extensions install +``` + +安装过程自动转换： +- `gemini-extension.json` → `qwen-extension.json` +- TOML 命令文件 → Markdown 格式 +- MCP 服务器、上下文文件、设置均保留 + +## 扩展结构 + +``` +~/.qwen/extensions/my-extension/ +├── qwen-extension.json # 扩展元数据（必须） +├── QWEN.md # 上下文文件（可选，自动加载） +├── commands/ # 自定义命令（.md 文件） +│ ├── deploy.md +│ └── gcs/ +│ └── sync.md # → 注册为 /gcs:sync +├── skills/ # 自定义技能 +│ └── pdf-processor/ +│ └── SKILL.md +└── agents/ # 自定义子智能体（.yaml 或 .md） + └── testing-expert.yaml +``` + +### qwen-extension.json + +```json +{ + "name": "my-extension", + "version": "1.0.0", + "mcpServers": { + "my-server": { + "command": "node", + "args": ["my-server.js"] + } + }, + "contextFileName": "QWEN.md", + "commands": "commands", + "skills": "skills", + "agents": "agents", + "settings": [ + { + "name": "API Key", + "description": "服务所需的 API 密钥", + "envVar": "MY_API_KEY", + "sensitive": true + } + ] +} +``` + +### 变量替换 + +| 变量 | 说明 | +|------|------| +| `${extensionPath}` | 扩展完整路径 | +| `${workspacePath}` | 当前工作区路径 | +| `${/}` 或 `${pathSeparator}` | 路径分隔符 | + +## 命令冲突解决 + +扩展命令优先级最低： +- **无冲突**：使用自然名称（如 `/deploy`） +- **与用户/项目命令冲突**：添加扩展前缀（如 `/gcp.deploy`） + +## 设置作用域 + +扩展设置支持两级： +- **用户级**（默认）：`~/.qwen/.env`，所有项目生效 +- **工作区级**：`.qwen/.env`，仅当前项目，优先级更高 diff --git a/docs/tools/qwen-code/README.md b/docs/tools/qwen-code/README.md index 21331cd6..77780da9 100644 --- a/docs/tools/qwen-code/README.md +++ b/docs/tools/qwen-code/README.md @@ -8,6 +8,8 @@ | [02-commands.md](./02-commands.md) | 41 个斜杠命令、子命令、CLI 参数 | | [03-architecture.md](./03-architecture.md) | 技术架构、Agent Loop、Arena、扩展系统 | | [04-tools.md](./04-tools.md) | 16 个核心工具、MCP 动态工具、权限分类 | +| [05-settings.md](./05-settings.md) | 完整配置参考（7 层优先级、settings.json 全字段） | +| [06-extensions.md](./06-extensions.md) | 扩展系统（Claude/Gemini 跨平台兼容、qwen-extension.json） | | [EVIDENCE.md](./EVIDENCE.md) | 源码分析证据（遥测、认证、模型、Arena） | | [用户指南](../../guides/qwen-code-user-guide.md) | 安装、免费使用、Arena 模式 |