@tencent-ai/agent-sdk 0.3.98 → 0.3.100

package/cli/dist/web-ui/docs/cn/cli/terminal-config.md

@@ -0,0 +1,77 @@
+# 优化终端配置
+
+> CodeBuddy Code 在合适的终端配置下能发挥最佳性能。按照以下指南优化您的使用体验。
+
+## 🎨 主题和外观
+
+CodeBuddy Code 无法控制您终端的主题，这由您的终端应用程序处理。您可以随时通过 `/config` 命令将 CodeBuddy Code 的主题与终端主题匹配。
+
+如需进一步自定义 CodeBuddy Code 界面本身，您可以配置[自定义状态行](statusline.md)在终端底部显示上下文信息，如当前模型、工作目录或 git 分支等。
+
+## ⌨️ 换行输入
+
+在 CodeBuddy Code 中输入换行符有以下几种方式：
+
+* **Ctrl+J**:跨平台快捷键，在多行输入时按 Ctrl+J 即可插入换行
+* **快速转义**:输入 `\` 后按 Enter 即可创建换行
+* **Shift+Enter**:通过 `/terminal-setup` 命令自动配置（推荐）
+
+### 配置 Shift+Enter（推荐）:
+
+在 CodeBuddy Code 中运行 `/terminal-setup` 命令，自动配置 Shift+Enter 快捷键。
+
+支持的终端：
+* **macOS**: iTerm2, Terminal.app
+* **IDE**: VSCode, Cursor, Windsurf, Zed, CodeBuddy
+* **JetBrains**: PyCharm, IntelliJ IDEA, WebStorm, PhpStorm, GoLand, Rider, CLion, RubyMine, AppCode, DataGrip
+* **终端模拟器**: Ghostty, WezTerm, Kitty, Alacritty, Hyper, Tabby, Warp
+* **Windows**: Windows Terminal
+
+### 配置 Option+Enter(VS Code、iTerm2 或 macOS Terminal.app):
+
+**对于 Mac Terminal.app:**
+
+1. 打开 设置 → 描述文件 → 键盘
+2. 勾选"将 Option 用作 Meta 键"
+
+**对于 iTerm2 和 VS Code 终端：**
+
+1. 打开 Settings → Profiles → Keys
+2. 在"General"下，将 Left/Right Option 键设置为"Esc+"
+
+## 🔔 通知设置
+
+通过合适的通知配置，让您在 CodeBuddy 完成任务时不会错过：
+
+### iTerm 2 系统通知
+
+为 iTerm 2 配置任务完成时的提醒：
+
+1. 打开 iTerm 2 偏好设置
+2. 导航到 Profiles → Terminal
+3. 启用"Silence bell"和 Filter Alerts → “Send escape sequence-generated alerts”
+4. 设置您偏好的通知延迟
+
+注意：这些通知功能仅适用于 iTerm 2,在 macOS 默认终端中不可用。
+
+### 自定义通知 Hook
+
+如需高级通知处理，您可以创建[通知 Hook](hooks.md#notification)来运行自己的逻辑。
+
+## 📝 处理大量输入
+
+在处理大量代码或长指令时：
+
+* **避免直接粘贴**:CodeBuddy Code 可能无法很好地处理非常长的粘贴内容
+* **使用基于文件的工作流**:将内容写入文件并要求 CodeBuddy 读取它
+* **注意 VS Code 的限制**:VS Code 终端特别容易截断长粘贴内容
+
+## ⌨️ Vim 模式
+
+CodeBuddy Code 支持部分 Vim 快捷键，可以通过 `/vim` 命令启用,或通过 `/config` 配置。
+
+支持的功能子集包括：
+
+* 模式切换：`Esc`（切换到 NORMAL 模式）、`i`/`I`、`a`/`A`、`o`/`O`（切换到 INSERT 模式）
+* 导航：`h`/`j`/`k`/`l`、`w`/`e`/`b`、`0`/`$`/`^`、`gg`/`G`
+* 编辑：`x`、`dw`/`de`/`db`/`dd`/`D`、`cw`/`ce`/`cb`/`cc`/`C`、`.`（重复）

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

@@ -0,0 +1,99 @@
+# 工具参考
+
+> CodeBuddy Code 可用工具的完整参考，包括权限要求。
+
+CodeBuddy Code 内置一系列工具来帮助理解和修改代码库。下表中的工具名称即为[权限规则](iam.md#工具特定的权限规则)、[子代理工具列表](sub-agents.md)和 [Hook 匹配器](hooks.md)中使用的标识符。
+
+| 工具 | 说明 | 需要权限 |
+| :--- | :--- | :------- |
+| `Agent` | 生成具有独立上下文窗口的[子代理](sub-agents.md)来处理任务 | 否 |
+| `AskUserQuestion` | 向用户提出多选问题，收集需求或澄清歧义 | 是 |
+| `Bash` | 在你的环境中执行 Shell 命令。参见 [Bash 工具行为](#bash-工具行为) | 是 |
+| `CronCreate` | 在当前会话内调度定时或一次性任务（退出后失效）。参见[定时任务](scheduled-tasks.md) | 否 |
+| `CronDelete` | 按 ID 取消定时任务 | 否 |
+| `CronList` | 列出当前会话中所有定时任务 | 否 |
+| `DeferExecuteTool` | 执行通过 `ToolSearch` 发现的延迟加载工具 | 否 |
+| `Edit` | 对文件进行精确的字符串替换编辑 | 是 |
+| `EnterPlanMode` | 切换到计划模式，在编码前设计实现方案 | 否 |
+| `EnterWorktree` | 创建隔离的 [git worktree](worktree.md) 并切换到其中 | 是 |
+| `ExitPlanMode` | 提交计划供用户审批并退出计划模式 | 是 |
+| `Glob` | 基于 glob 模式查找文件 | 否 |
+| `Grep` | 在文件内容中搜索正则表达式模式 | 否 |
+| `ImageEdit` | 基于文本指令编辑或修改已有图片 | 是 |
+| `ImageGen` | 根据文本描述生成图片 | 是 |
+| `LeaveWorktree` | 退出 worktree 会话并返回原始目录 | 是 |
+| `LSP` | 通过语言服务器提供代码智能。文件编辑后自动报告类型错误和警告。还支持跳转定义、查找引用、获取类型信息、列出符号、查找实现、追踪调用层级等导航操作。需要[代码智能插件](plugins.md)及其语言服务器二进制文件 | 否 |
+| `MultiEdit` | 在单个原子操作中对同一文件执行多步编辑 | 是 |
+| `NotebookEdit` | 修改 Jupyter notebook 单元格内容 | 是 |
+| `Read` | 读取文件内容，支持图片、PDF 和 Jupyter notebook | 否 |
+| `SendMessage` | 在 [Agent 团队](agent-teams.md)中向队友发送消息 | 否 |
+| `Skill` | 在主对话中执行 [Skill 技能](skills.md) | 否 |
+| `SlashCommand` | 执行自定义[斜杠命令](slash-commands.md) | 是 |
+| `StructuredOutput` | 返回符合 JSON Schema 的结构化输出 | 否 |
+| `TaskCreate` | 创建新任务到任务列表 | 否 |
+| `TaskGet` | 获取特定任务的完整详情 | 否 |
+| `TaskList` | 列出所有任务及其当前状态 | 否 |
+| `TaskOutput` | 获取后台任务或子代理的输出 | 否 |
+| `TaskStop` | 按 ID 终止正在运行的后台任务 | 否 |
+| `TaskUpdate` | 更新任务状态、依赖、详情或删除任务 | 否 |
+| `TeamCreate` | 创建 [Agent 团队](agent-teams.md)以协调多个代理协作 | 否 |
+| `TeamDelete` | 删除 Agent 团队及其任务目录 | 否 |
+| `ToolSearch` | 搜索并加载延迟加载的工具，支持内置工具和 [MCP 工具](mcp.md#延迟加载-defer_loading) | 否 |
+| `WebFetch` | 获取指定 URL 的内容并进行 AI 分析 | 是 |
+| `WebSearch` | 执行网络搜索 | 是 |
+| `Write` | 创建或覆盖文件 | 是 |
+
+权限规则可通过 `/permissions` 命令或在[权限设置](settings.md#权限设置)中配置。另请参阅[工具特定的权限规则](iam.md#工具特定的权限规则)。
+
+## 工具别名
+
+部分工具拥有别名，可在权限规则中互换使用：
+
+| 工具 | 别名 |
+| :--- | :--- |
+| `TaskOutput` | `BashOutput` |
+| `TaskStop` | `KillShell` |
+
+## Bash 工具行为
+
+Bash 工具在独立进程中执行每条命令，具有以下持久化特性：
+
+* **工作目录**在命令间保持不变。设置 `CODEBUDDY_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` 可在每次命令后重置到项目目录。
+* **环境变量不会持久化**。一条命令中的 `export` 不会在下一条命令中生效。
+
+在启动 CodeBuddy Code 前激活你的 virtualenv 或 conda 环境。要使环境变量在 Bash 命令间持久化，启动前设置 [`CODEBUDDY_ENV_FILE`](env-vars.md) 指向一个 shell 脚本，或使用 [SessionStart Hook](hooks.md) 动态填充。
+
+### 沙箱模式
+
+Bash 工具支持[沙箱隔离](bash-sandboxing.md)，可限制文件系统和网络访问。启用沙箱时，命令在受限环境中执行，防止未授权的系统访问。
+
+通过 `dangerouslyDisableSandbox` 参数可逐条命令绕过沙箱（需要用户审批）。
+
+### 后台执行
+
+通过 `run_in_background` 参数可将命令在后台运行，使用 `TaskOutput` 工具读取输出。适用于长时间运行的构建、测试等场景。
+
+## 延迟加载工具
+
+部分工具（如通过 [MCP 服务器](mcp.md)提供的工具）采用延迟加载机制。这些工具不会在初始工具列表中出现，需要通过 `ToolSearch` 发现和激活。一旦激活，工具在会话剩余时间内保持可用。
+
+通过产品配置可以将内置工具设置为延迟加载：
+
+```json
+{
+  "tools": {
+    "ToolName": {
+      "deferLoading": true
+    }
+  }
+}
+```
+
+## 另请参阅
+
+* [身份和访问管理](iam.md)：权限系统、规则语法和工具特定规则
+* [子代理](sub-agents.md)：为子代理配置工具访问权限
+* [Hooks 钩子系统](hooks-guide.md)：在工具执行前后运行自定义命令
+* [MCP 集成](mcp.md)：通过 MCP 服务器扩展可用工具
+* [定时任务](scheduled-tasks.md)：使用 CronCreate 调度自动化任务
+* [Agent 团队](agent-teams.md)：多代理协作的团队系统

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

@@ -0,0 +1,190 @@
+# 故障排查与最佳实践
+
+本文档涵盖常见问题解决方案和使用优化建议。
+
+
+## 常见问题
+
+### 额度共享
+
+CLI、CodeBuddy IDE 和 CodeBuddy Plugin 共享同一账号的资源配额。
+
+### JetBrains IDE 中 ESC 键不生效
+
+JetBrains 终端对 ESC 键处理不同，改用 `Ctrl+ESC` 或 `Shift+ESC`。
+
+| 操作 | 标准终端 | JetBrains 终端 |
+|-----|---------|---------------|
+| 退出/取消 | `ESC` | `Ctrl+ESC` 或 `Shift+ESC` |
+
+### 模型切换
+
+```
+/model              # 交互式选择
+/model [模型名称]    # 直接切换
+/status             # 查看当前模型
+```
+
+### --serve 模式网络访问问题
+
+#### 局域网 IP 访问报 `ERR_EMPTY_RESPONSE`
+
+**症状**：使用 `codebuddy --serve` 启动后，通过局域网 IP（如 `http://10.31.110.26:52477`）访问时，浏览器报 `ERR_EMPTY_RESPONSE`（未发送任何数据）。
+
+**原因**：HTTP 服务默认监听 `127.0.0.1`（本地回环地址），只接受本机连接。使用局域网 IP 访问时，请求到达了机器但被服务拒绝。
+
+**解决方案**：启动时添加 `--host 0.0.0.0` 参数，使服务监听所有网络接口：
+
+```bash
+codebuddy --serve --host 0.0.0.0 --port 8080
+```
+
+> 非回环地址启动时会自动启用密码认证，密码在控制台输出中可见。
+
+#### 确认服务监听状态
+
+可以通过以下命令检查服务是否正确监听：
+
+```bash
+# macOS / Linux
+lsof -i :PORT_NUMBER
+
+# 或
+netstat -an | grep PORT_NUMBER
+```
+
+- 若显示 `127.0.0.1:PORT` — 只接受本机连接
+- 若显示 `0.0.0.0:PORT` 或 `*:PORT` — 接受所有网络连接
+
+---
+
+## 更新
+
+### 自动更新
+
+默认开启，下次启动时自动应用新版本。通过 `/config` 管理开关。
+
+### 手动更新
+
+```bash
+codebuddy update                                    # 内置命令（推荐）
+npm install -g @tencent-ai/codebuddy-code@latest   # npm 更新
+```
+
+### 版本检查
+
+```bash
+codebuddy --version                                 # 当前版本
+npm view @tencent-ai/codebuddy-code version        # 最新版本
+```
+
+---
+
+## 从 Claude Code 迁移
+
+### 迁移内容
+
+| 目录/文件 | 说明 |
+|----------|------|
+| `agents/` | 自定义 agents 配置 |
+| `commands/` | 斜杠命令定义 |
+| `skills/` | 专业技能定义 |
+| `CLAUDE.md` → `CODEBUDDY.md` | AI 指令和记忆文档 |
+
+### 方案一：符号链接（推荐）
+
+共享配置，修改一处两边生效。
+
+```bash
+# macOS/Linux
+cd ~/.codebuddy
+ln -s ~/.claude/agents agents
+ln -s ~/.claude/commands commands
+ln -s ~/.claude/skills skills
+ln -s ~/.claude/CLAUDE.md CODEBUDDY.md
+```
+
+```powershell
+# Windows (需管理员权限)
+cd $env:USERPROFILE\.codebuddy
+New-Item -ItemType SymbolicLink -Path agents -Target $env:USERPROFILE\.claude\agents
+New-Item -ItemType SymbolicLink -Path commands -Target $env:USERPROFILE\.claude\commands
+New-Item -ItemType SymbolicLink -Path skills -Target $env:USERPROFILE\.claude\skills
+New-Item -ItemType SymbolicLink -Path CODEBUDDY.md -Target $env:USERPROFILE\.claude\CLAUDE.md
+```
+
+### 方案二：复制文件
+
+独立配置，互不影响。
+
+```bash
+# macOS/Linux
+cp -r ~/.claude/agents ~/.codebuddy/agents
+cp -r ~/.claude/commands ~/.codebuddy/commands
+cp -r ~/.claude/skills ~/.codebuddy/skills
+cp ~/.claude/CLAUDE.md ~/.codebuddy/CODEBUDDY.md
+```
+
+```powershell
+# Windows
+Copy-Item -Recurse $env:USERPROFILE\.claude\agents $env:USERPROFILE\.codebuddy\agents
+Copy-Item -Recurse $env:USERPROFILE\.claude\commands $env:USERPROFILE\.codebuddy\commands
+Copy-Item -Recurse $env:USERPROFILE\.claude\skills $env:USERPROFILE\.codebuddy\skills
+Copy-Item $env:USERPROFILE\.claude\CLAUDE.md $env:USERPROFILE\.codebuddy\CODEBUDDY.md
+```
+
+### 插件 Skills 一键安装
+
+Claude Code 插件中的 Skills 支持一键安装，安装后自动加载。
+
+### 验证迁移
+
+```bash
+codebuddy         # 启动
+/skills           # 检查 Skills
+/config           # 查看配置
+```
+
+---
+
+## 成本优化
+
+### 核心原则
+
+- 新任务用 `/clear` 开启新会话
+- 长对话用 `/compact` 压缩历史
+- 用 `@filename` 引用文件，避免粘贴代码
+
+### 会话管理命令
+
+| 命令 | 功能 |
+|-----|------|
+| `/cost` | 查看 Token 消耗 |
+| `/clear` | 开启新会话 |
+| `/compact` | 压缩历史 |
+| `/resume` | 恢复旧对话 |
+
+### 成本对比
+
+| 方式 | 输入 Token | 相对成本 |
+|-----|-----------|---------|
+| 单会话连续 10 个任务 | ~50,000 | 高 |
+| 每个任务新会话 | ~15,000 | 低 |
+| 定期 `/compact` | ~25,000 | 中 |
+
+### 推荐做法
+
+- ✓ 新任务开新会话
+- ✓ 每 20-30 轮用 `/compact`
+- ✓ 用 `@filename` 引用文件
+- ✓ 精简提问
+
+### 避免做法
+
+- ✗ 同一会话处理多个无关任务
+- ✗ 对话超过 30 轮不清理
+- ✗ 重复粘贴已知代码
+
+---
+
+**更多帮助**：[快速入门指南](./quickstart.md)

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

@@ -0,0 +1,164 @@
+# Web UI
+
+CodeBuddy Code 提供内置的 Web UI，在浏览器中提供完整的交互界面。当您以 serve 模式启动或开启远程控制时，Web UI 自动可用。
+
+## 概述
+
+Web UI 提供与终端界面相同的核心能力，并针对浏览器进行了可视化布局优化：
+
+- **对话**：发送消息、查看对话、实时监控工具执行
+- **终端**：内嵌终端，支持分屏布局（最多 4 个面板）
+- **实例**：管理和切换多个 CodeBuddy Code 实例
+- **远程控制**：连接微信和企业微信渠道
+- **任务**：浏览任务模版并创建定时任务
+- **插件**：管理插件安装和插件市场
+- **设置**：配置主题、语言、模型和权限模式
+- **文档**：浏览 CLI 文档，支持全文搜索
+- **API 文档**：查看交互式 Swagger UI，方便 HTTP API 探索
+
+## 访问 Web UI
+
+### 方式一：Serve 模式
+
+使用 `--serve` 参数启动 CodeBuddy Code：
+
+```bash
+codebuddy --serve --port 7890
+```
+
+然后在浏览器中打开：
+
+```
+http://127.0.0.1:7890
+```
+
+### 方式二：远程控制
+
+在已有的 CodeBuddy Code 会话中启动 Gateway：
+
+```
+/gateway
+```
+
+终端会显示二维码和 URL。用手机扫码或在浏览器中打开 URL。详见[远程控制](remote-control.md)文档。
+
+## 认证方式
+
+Web UI 支持两种认证模式：
+
+| 模式 | 设置 | 说明 |
+|:-----|:-----|:-----|
+| 免认证（默认） | `CODEBUDDY_GATEWAY_AUTH=none` | 无需密码 |
+| 密码认证 | `CODEBUDDY_GATEWAY_AUTH=password` | 启动时终端显示密码 |
+
+认证方式（以下任一方式均可）：
+
+- **URL 参数**：`?password=xxx` — 通过 URL 自动登录
+- **登录页面**：输入终端显示的密码
+- **Bearer Token**：`Authorization: Bearer <password>`，用于 API 访问
+
+在 `~/.codebuddy/settings.json` 中配置：
+
+```json
+{
+  "gateway.auth": "none"
+}
+```
+
+## 功能详解
+
+### 对话视图
+
+默认视图，用于与 Agent 交互。核心功能：
+
+- **富文本消息渲染**：Markdown、语法高亮代码块、表格、图片
+- **工具执行展示**：内联查看工具调用、参数和结果
+- **权限管理**：在浏览器中直接批准或拒绝工具权限
+- **问答面板**：回答 Agent 的多选问题
+- **任务进度**：实时监控后台任务和 Team 进度
+- **会话管理**：新建对话、浏览历史、切换会话
+
+### 终端视图
+
+基于 xterm.js 的内嵌终端：
+
+- **分屏布局**：支持水平和垂直分屏，最多 4 个面板
+- **独立会话**：每个面板有独立的 PTY 会话
+- **持久连接**：终端会话在页面刷新后保持
+- **自适应调整**：窗口大小变化时面板自动调整
+
+### 文档视图
+
+在 Web UI 中直接浏览 CLI 文档：
+
+- **全文搜索**：基于 MiniSearch 搜索所有文档
+- **多语言**：自动跟随 UI 语言设置（中文/英文）
+- **目录导航**：根据文档标题自动生成，带滚动追踪
+- **内部跳转**：文档链接在查看器内导航（SPA 模式）
+- **API 文档**：快速链接到 `/api/docs` 的交互式 Swagger UI
+
+### 实例管理
+
+管理多个 CodeBuddy Code 实例：
+
+- **实例列表**：查看所有运行中的实例及其工作目录和状态
+- **快速切换**：一键切换实例
+- **手动添加**：通过 URL 添加远程实例
+- **隧道支持**：通过 Cloudflare Tunnel 访问实例
+
+### 设置
+
+- **主题**：浅色、深色或跟随系统（自动检测）
+- **语言**：中文、英文或跟随系统（自动检测）
+- **模型**：从可用选项中选择 AI 模型
+- **权限模式**：默认、接受编辑、跳过权限或规划模式
+
+## API 文档
+
+HTTP 服务运行时，可在以下地址访问交互式 API 探索器：
+
+```
+http://127.0.0.1:{PORT}/api/docs
+```
+
+Swagger UI 提供以下功能：
+
+- 浏览所有可用的 REST API 端点
+- 查看请求/响应 Schema
+- 直接在浏览器中测试 API 调用
+- 在 `/api/openapi.json` 下载 OpenAPI 3.1 规范
+
+完整的 API 参考请见 [HTTP API 文档](http-api.md)。
+
+## 移动端支持
+
+Web UI 完全响应式，支持移动设备：
+
+- **侧边栏**：小屏幕上折叠为滑出式抽屉
+- **PWA 支持**：添加到主屏幕获得类原生应用体验
+- **触控优化**：所有交互针对触摸操作优化
+- **扫码访问**：终端扫码即可在手机上打开
+
+## 快捷键
+
+| 快捷键 | 操作 |
+|:-------|:-----|
+| `Enter` | 发送消息 |
+| `Shift+Enter` | 输入换行 |
+| `Escape` | 停止运行中的 Agent |
+
+## 技术细节
+
+- **框架**：React 18 + Zustand 状态管理
+- **通信**：ACP 协议，基于 HTTP/SSE（非 WebSocket）
+- **样式**：Tailwind CSS + CSS 变量主题
+- **终端**：xterm.js + fit addon
+- **搜索**：MiniSearch 客户端全文搜索
+- **Markdown**：react-markdown + remark-gfm + 语法高亮
+
+## 相关文档
+
+- [远程控制](remote-control.md) — 通过 Gateway 和 Tunnel 启动 Web UI
+- [HTTP API](http-api.md) — 完整的 REST API 文档
+- [ACP 协议](acp.md) — IDE 集成的 Agent Client Protocol
+- [设置](settings.md) — 配置选项