@tencent-ai/agent-sdk 0.3.99 → 0.3.100

package/cli/dist/web-ui/docs/cn/cli/cli-reference.md

@@ -0,0 +1,187 @@
+# CLI 参考
+
+> CodeBuddy Code 命令行工具完整参考手册，包含所有命令和参数说明。
+
+## CLI 命令
+
+| 命令                                | 说明                                     | 示例                                           |
+| :---------------------------------- | :--------------------------------------- | :--------------------------------------------- |
+| `codebuddy`                         | 启动交互式 REPL                          | `codebuddy`                                    |
+| `codebuddy "查询"`                  | 带初始提示词启动 REPL                    | `codebuddy "解释这个项目"`                     |
+| `codebuddy -p "查询"`               | 通过 SDK 查询后退出                      | `codebuddy -p "解释这个函数"`                  |
+| `cat 文件 \| codebuddy -p "查询"`   | 处理管道内容                             | `cat logs.txt \| codebuddy -p "分析日志"`      |
+| `codebuddy -c`                      | 继续最近的对话                           | `codebuddy -c`                                 |
+| `codebuddy -c -p "查询"`            | 通过 SDK 继续对话                        | `codebuddy -c -p "检查类型错误"`               |
+| `codebuddy -r "<session-id>" "查询"` | 通过 ID 恢复会话                         | `codebuddy -r "abc123" "完成这个 MR"`          |
+| `codebuddy update`                  | 更新到最新版本                           | `codebuddy update`                             |
+| `codebuddy mcp`                     | 配置 Model Context Protocol (MCP) 服务器 | 参见 [CodeBuddy Code MCP 文档](./mcp.md)      |
+
+## CLI 参数
+
+自定义 CodeBuddy Code 行为的命令行参数：
+
+| 参数                             | 说明                                                                                                                              | 示例                                                                                               |
+| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |
+| `--add-dir`                      | 添加额外的工作目录供 CodeBuddy 访问（验证每个路径是否存在）                                                                         | `codebuddy --add-dir ../apps ../lib`                                                               |
+| `--agents`                       | 通过 JSON 动态定义自定义[子代理](./sub-agents.md)（格式见下文）                                                                     | `codebuddy --agents '{"reviewer":{"description":"审查代码","prompt":"你是代码审查员"}}'`            |
+| `--allowedTools`                 | 除了[settings.json 文件](./settings.md)外,无需提示用户即可允许的工具列表                                                          | `"Bash(git log:*)" "Bash(git diff:*)" "Read"`                                                      |
+| `--disallowedTools`              | 除了[settings.json 文件](./settings.md)外,应禁止使用的工具列表                                                                    | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"`                                                      |
+| `--tools`                        | 限制可用的内置工具集（白名单）。空字符串 `""` 禁用所有内置工具，`"default"` 使用全部工具，或指定逗号分隔的工具名                      | `codebuddy --tools "Bash,Read,Edit"`                                                               |
+| `--print`, `-p`                  | 打印响应后退出,不进入交互模式                             | `codebuddy -p "查询"`                                                                              |
+| `--settings`                     | 从 JSON 文件或 JSON 字符串加载额外的设置配置                                                                                       | `codebuddy --settings '{"model":"gpt-5"}' "查询"`                                                  |
+| `--setting-sources`              | 指定要加载的设置源,逗号分隔（可选值: `user`, `project`, `local`）。默认: `user,project,local`                                      | `codebuddy --setting-sources project,local "查询"`                                                 |
+| `--system-prompt`                | 用自定义文本替换整个系统提示词（在交互和打印模式下都可用）                                                                          | `codebuddy --system-prompt "你是 Python 专家"`                                                     |
+| `--system-prompt-file`           | 从文件加载系统提示词,替换默认提示词(仅打印模式)                                                                                   | `codebuddy -p --system-prompt-file ./custom-prompt.txt "查询"`                                     |
+| `--append-system-prompt`         | 在默认系统提示词末尾追加自定义文本（在交互和打印模式下都可用）                                                                      | `codebuddy --append-system-prompt "始终使用 TypeScript"`                                           |
+| `--output-format`                | 指定打印模式的输出格式(选项: `text`, `json`, `stream-json`)                                                                       | `codebuddy -p "查询" --output-format json`                                                         |
+| `--input-format`                 | 指定打印模式的输入格式(选项: `text`, `stream-json`)                                                                               | `codebuddy -p --output-format json --input-format stream-json`                                     |
+| `--json-schema`                  | 使用 JSON Schema 验证结构化输出。示例: `'{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}'`                                                                                   | `codebuddy -p --output-format json --json-schema '{"type":"object","properties":{...}}' "查询"`    |
+| `--include-partial-messages`     | 在输出中包含部分流式事件（需要 `--print` 和 `--output-format=stream-json`)                                                         | `codebuddy -p --output-format stream-json --include-partial-messages "查询"`                       |
+| `--verbose`                      | 启用详细日志记录,显示完整的轮次输出(在打印和交互模式下都有助于调试)                                                               | `codebuddy --verbose`                                                                              |
+| `--max-turns`                    | 限制非交互模式下的代理轮次数                                                                                                      | `codebuddy -p --max-turns 3 "查询"`                                                                |
+| `--model`                        | 使用别名设置当前会话的模型，如最新模型的别名（`sonnet` 或 `opus`）或模型全名                                                         | `codebuddy --model gpt-5`                                                                          |
+| `--text-to-image-model`          | 设置文生图功能使用的模型 ID                                                                                                           | `codebuddy --text-to-image-model your-image-model`                                                 |
+| `--image-to-image-model`         | 设置图生图功能使用的模型 ID                                                                                                           | `codebuddy --image-to-image-model your-edit-model`                                                 |
+| `--permission-mode`              | 以指定的[权限模式](./iam.md#permission-modes)开始                                                                                 | `codebuddy --permission-mode plan`                                                                 |
+| `--permission-prompt-tool`       | 指定在非交互模式下处理权限提示的 MCP 工具                                                                                         | `codebuddy -p --permission-prompt-tool mcp_auth_tool "查询"`                                       |
+| `--resume`                       | 通过 ID 恢复特定会话,或在交互模式下选择                                                                                           | `codebuddy --resume abc123 "查询"`                                                                 |
+| `--continue`                     | 加载当前目录中最近的对话                                                                                                          | `codebuddy --continue`                                                                             |
+| `-y` / `--dangerously-skip-permissions` | 跳过权限提示（谨慎使用）                                                                                                            | `codebuddy -y` 或 `codebuddy --dangerously-skip-permissions`                                       |
+| `--ide`                          | 启动时自动连接到 IDE（如果恰好有一个有效的 IDE 可用且打开了当前工作目录）                                                          | `codebuddy --ide`                                                                                  |
+| `--sandbox`                      | 在沙箱中运行 CodeBuddy（详见下方[沙箱模式](#沙箱模式-beta))                                                                        | `codebuddy --sandbox "分析项目"`                                                                   |
+| `--debug`                        | 启用调试模式,支持可选的类别过滤                                                                                                   | `codebuddy --debug`                                                                                |
+| `--worktree [name]`              | 在独立的 git worktree 中运行（详见 [Worktree 文档](./worktree.md)）                                                               | `codebuddy --worktree` 或 `codebuddy --worktree my-feature`                                        |
+| `--tmux`                         | 在 tmux 会话中运行（与 `--worktree` 配合使用）                                                                                     | `codebuddy --worktree --tmux`                                                                      |
+
+> **重要提示**：在使用 `-p/--print` 参数进行非交互式执行时,涉及文件读写、命令执行、网络请求等操作通常需要添加 `-y` （或 `--dangerously-skip-permissions`)参数才能执行，否则操作会被阻止。
+
+<Tip>
+  `--output-format json` 参数特别适用于脚本和自动化，允许您以编程方式解析 CodeBuddy 的响应。
+</Tip>
+
+### Agents 参数格式
+
+`--agents` 参数接受定义一个或多个自定义子代理的 JSON 对象。每个子代理需要一个唯一的名称（作为键）和一个包含以下字段的定义对象：
+
+| 字段          | 必需 | 说明                                                                           |
+| :------------ | :--- | :----------------------------------------------------------------------------- |
+| `description` | 是   | 何时应调用子代理的自然语言描述                                                 |
+| `prompt`      | 是   | 指导子代理行为的系统提示词                                                     |
+| `tools`       | 否   | 子代理可以使用的特定工具数组（如 `["Read", "Edit", "Bash"]`)。省略则继承所有工具 |
+| `model`       | 否   | 要使用的模型别名: `sonnet`、`opus` 或 `haiku`。省略则使用默认子代理模型        |
+
+示例：
+
+```bash
+codebuddy --agents '{
+  "code-reviewer": {
+    "description": "专业代码审查员。代码更改后主动使用。",
+    "prompt": "你是高级代码审查员。专注于代码质量、安全性和最佳实践。",
+    "tools": ["Read", "Grep", "Glob", "Bash"],
+    "model": "sonnet"
+  },
+  "debugger": {
+    "description": "错误和测试失败的调试专家。",
+    "prompt": "你是专业调试人员。分析错误，识别根本原因并提供修复方案。"
+  }
+}'
+```
+
+有关创建和使用子代理的更多详细信息，请参见[子代理文档](./sub-agents.md)。
+
+### 系统提示词参数
+
+CodeBuddy Code 提供三个自定义系统提示词的参数，每个参数用途不同：
+
+| 参数                     | 行为                   | 模式            | 使用场景                                       |
+| :----------------------- | :--------------------- | :-------------- | :--------------------------------------------- |
+| `--system-prompt`        | **替换**整个默认提示词 | 交互 + 打印模式 | 完全控制 CodeBuddy 的行为和指令                |
+| `--system-prompt-file`   | 用文件内容**替换**     | 仅打印模式      | 从文件加载提示词以确保可重现性和版本控制       |
+| `--append-system-prompt` | **追加**到默认提示词   | 交互 + 打印模式 | 添加特定指令同时保留默认 CodeBuddy Code 行为   |
+
+**何时使用：**
+
+* **`--system-prompt`**：当您需要完全控制 CodeBuddy 的系统提示词时使用。这会移除所有默认 CodeBuddy Code 指令，给您一个空白画布。
+  ```bash
+  codebuddy --system-prompt "你是只编写带类型注解代码的 Python 专家"
+  ```
+
+* **`--system-prompt-file`**：当您想从文件加载自定义提示词时使用，适用于团队一致性或版本控制的提示词模板。
+  ```bash
+  codebuddy -p --system-prompt-file ./prompts/code-review.txt "审查这个 MR"
+  ```
+
+* **`--append-system-prompt`**：当您想添加特定指令同时保留 CodeBuddy Code 的默认功能时使用。这是大多数用例的最安全选项。
+  ```bash
+  codebuddy --append-system-prompt "始终使用 TypeScript 并包含 JSDoc 注释"
+  ```
+
+<Note>
+  `--system-prompt` 和 `--system-prompt-file` 互斥。不能同时使用这两个参数。
+</Note>
+
+<Tip>
+  对于大多数用例，建议使用 `--append-system-prompt`,因为它在添加自定义需求的同时保留了 CodeBuddy Code 的内置功能。仅当需要完全控制系统提示词时才使用 `--system-prompt` 或 `--system-prompt-file`。
+</Tip>
+
+## 沙箱模式 （Beta)
+
+> **Beta 功能**: Sandbox 功能目前处于 Beta 阶段。
+> 
+> **详细文档**：查看 [沙箱使用指南](./sandboxing.md) 获取完整的沙箱使用说明、最佳实践和故障排查。
+
+### 沙箱参数
+
+```bash
+--sandbox [url]                       在沙箱中运行 CodeBuddy:
+                                      - 不带参数或 "container"：使用容器 （Docker/Podman)
+                                      - 提供完整的 E2B API URL：使用云端沙箱
+--sandbox-upload-dir                  上传当前工作目录到沙箱 （仅 E2B)
+--sandbox-new                         强制创建新沙箱 （忽略缓存的沙箱）
+--sandbox-id <id>                     连接到指定的沙箱 ID 或别名
+--sandbox-kill                        退出时终止沙箱 （默认： 保持运行以便复用）
+--teleport <value>                    Teleport 模式： 连接到远程创建的沙箱
+```
+
+### 沙箱使用示例
+
+```bash
+# 容器沙箱 （Docker/Podman，自动挂载当前目录）
+codebuddy --sandbox "分析这个项目"
+
+# E2B 云端沙箱 （自动复用）
+codebuddy --sandbox https://api.e2b.dev "创建 Python web 应用"
+
+# 强制创建新沙箱
+codebuddy --sandbox --sandbox-new "从头开始"
+
+# 连接到指定沙箱
+codebuddy --sandbox --sandbox-id sb_abc123 "继续工作"
+
+# 退出时清理沙箱
+codebuddy --sandbox --sandbox-kill "临时测试"
+
+# Teleport 模式 - 连接到远程创建的沙箱
+codebuddy --teleport session_abc123XYZ4567890 "连接到远程沙箱"
+```
+
+### 沙箱环境变量
+
+```bash
+E2B_API_KEY                          E2B API 密钥 （E2B 沙箱必需）
+E2B_TEMPLATE                         E2B 模板 ID （默认： base)
+CODEBUDDY_SANDBOX_IMAGE              自定义 Docker 镜像 （容器沙箱）
+```
+
+## 下一步
+
+掌握 CLI 命令后，您可以：
+
+- **[学习交互模式](./interactive-mode.md)** - 掌握键盘快捷键和技巧
+- **[探索斜杠命令](./slash-commands.md)** - 了解内置命令
+- **[Skills 技能系统](./skills.md)** - 扩展 AI 专业能力
+- **[学习 MCP 集成](./mcp.md)** - 扩展工具能力
+
+---
+
+*精确的命令行操作是高效开发的基础*