@tencent-ai/codebuddy-code 2.66.2-next.fd006f5.20260328 → 2.67.0-next.60b122b.20260330

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

@@ -0,0 +1,152 @@
+# ACP 协议集成
+
+> ACP (Agent Client Protocol) 是 Zed 编辑器推出的一种通用智能体协议，使智能体的核心功能（服务端）和用户界面（客户端）解耦，允许用户自由选择不同的智能体服务端和客户端进行搭配使用。
+
+CodeBuddy Code 原生支持 ACP 协议，可以作为智能体服务端与支持 ACP 的编辑器无缝集成。
+
+## 快速开始
+
+### 启动 ACP 模式
+
+使用 `--acp` 参数启动 CodeBuddy Code 的 ACP 服务器：
+
+```bash
+codebuddy --acp
+```
+
+## Zed 编辑器集成
+
+### 配置步骤
+
+打开 Zed 配置文件（`~/.config/zed/settings.json`），添加以下配置：
+
+```json
+{
+  "agent_servers": {
+    "CodeBuddy Code": {
+      "command": "codebuddy",
+      "args": ["--acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+随后即可在 Zed 侧边栏创建 CodeBuddy Code Thread，开始使用。
+
+### 配置说明
+
+- **command**：指定 CodeBuddy Code 的命令路径（确保 `codebuddy` 在 PATH 中可用）
+- **args**：使用 `["--acp"]` 启用 ACP 协议模式
+- **env**：可选的环境变量配置，例如：
+
+  ```json
+  {
+    "env": {
+      "CODEBUDDY_API_KEY": "your-api-key",
+      "CODEBUDDY_INTERNET_ENVIRONMENT": "internal"
+    }
+  }
+  ```
+
+  > **注意**：使用 `CODEBUDDY_API_KEY` 时，必须根据版本正确配置 `CODEBUDDY_INTERNET_ENVIRONMENT`：
+  > - 海外版：不设置（默认）
+  > - 中国版：`internal`
+  > - iOA 版：`ioa`
+  >
+  > 详见 [身份和访问管理文档](iam.md#个人用户获取-api-key)。
+
+## ACP 协议特性
+
+### 认证信息扩展
+
+CodeBuddy Code 在 `authenticate` 响应的 `_meta` 字段中返回用户信息：
+
+```json
+{
+  "_meta": {
+    "codebuddy.ai/userinfo": {
+      "userId": "用户 ID",
+      "userName": "用户名",
+      "userNickname": "用户昵称"
+    }
+  }
+}
+```
+
+客户端可以利用这些信息提供更好的用户体验，例如显示当前登录用户、个性化界面等。
+
+### 工具代理机制
+
+ACP 协议支持客户端代理部分工具操作，提升性能和安全性：
+
+- **文件操作代理**：基于客户端的 `fs.readTextFile` 和 `fs.writeTextFile` 能力
+- **终端操作代理**：基于客户端的 `terminal` 能力
+
+当客户端声明支持这些能力时，CodeBuddy Code 会自动将相关工具调用代理给客户端执行。
+
+### 命令列表推送
+
+CodeBuddy Code 会在创建新会话时自动向客户端推送可用的 Slash 命令列表（`available_commands_update`），让客户端能够：
+
+- 提供命令自动补全功能
+- 显示命令提示和帮助信息
+- 动态更新可用命令
+
+命令列表会自动过滤掉本地命令（如 `/clear`、`/exit`）和客户端专属命令（如 `/theme`、`/config`），只推送适用于 ACP 模式的命令。
+
+## 其他编辑器支持
+
+ACP 是开放协议，理论上任何支持 ACP 的编辑器都可以集成 CodeBuddy Code。配置方式与 Zed 类似：
+
+```json
+{
+  "agent_servers": {
+    "CodeBuddy": {
+      "command": "codebuddy",
+      "args": ["--acp"]
+    }
+  }
+}
+```
+
+## 故障排除
+
+### 连接失败
+
+**问题**: Zed 无法连接到 CodeBuddy
+
+**解决方法**:
+
+1. 确认 `codebuddy` 命令可用：
+
+   ```bash
+   which codebuddy
+   ```
+
+2. 测试 ACP 模式启动：
+
+   ```bash
+   codebuddy --acp
+   ```
+
+3. 检查配置文件 JSON 格式是否正确
+
+### 工具调用失败
+
+**问题**：文件操作或命令执行报错
+
+**解决方法**:
+
+1. 检查工作目录权限
+2. 查看 CodeBuddy 日志
+
+## 相关链接
+
+- [CLI 参考手册](./cli-reference.md) - 查看所有命令行参数
+- [IDE 集成说明](./ide-integrations.md) - 更多编辑器集成方式
+- [ACP 协议规范](https://github.com/agentclientprotocol/agent-client-protocol) - 协议详细文档
+
+---
+
+*通过 ACP 协议，让 CodeBuddy Code 融入您喜爱的编辑器 🚀*

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

@@ -0,0 +1,327 @@
+# Agent Teams：多智能体协作
+
+> Agent Teams 让你协调多个 CodeBuddy Code 实例组成团队协作，通过共享任务列表、成员间消息通信和集中式管理完成复杂任务。该功能目前存在[已知限制](#已知限制)。
+
+Agent Teams 让你协调多个 CodeBuddy Code 实例共同工作。一个会话作为团队领导（team-lead），负责协调工作、分配任务和汇总成果；其余成员（teammates）各自独立工作，拥有自己的上下文窗口，并通过消息系统直接相互沟通。
+
+与[子代理（Sub-agents）](sub-agents.md)不同的是，子代理在单一会话内运行、只能将结果报告给主代理；而 Agent Teams 的成员之间可以直接通信，你也可以绕过领导直接与任意成员对话。
+
+
+## 何时使用 Agent Teams
+
+Agent Teams 在**并行探索能创造真正价值**的任务中最为有效。典型场景包括：
+
+- **研究与评审**：多个成员同时调研问题的不同方面，然后共享和质疑彼此的发现
+- **新模块开发**：每个成员负责独立的模块，互不干扰
+- **竞争性假设调试**：成员并行测试不同假设，更快收敛到正确答案
+- **跨层协调**：前端、后端、测试各由不同成员负责，同步推进
+
+Agent Teams 会带来额外的协调开销，Token 消耗也显著高于单会话。当成员能独立工作时效果最好。对于顺序执行的任务、同文件编辑或依赖关系复杂的工作，单会话或子代理更合适。
+
+### 与子代理的对比
+
+| | 子代理 | Agent Teams |
+| :--- | :--- | :--- |
+| **上下文** | 独立上下文窗口，结果返回给调用者 | 独立上下文窗口，完全独立 |
+| **通信** | 只能向主代理报告结果 | 成员之间可直接发送消息 |
+| **协调** | 主代理管理所有工作 | 共享任务列表，成员自主认领 |
+| **适用场景** | 聚焦型任务，只关心最终结果 | 需要讨论和协作的复杂工作 |
+| **Token 消耗** | 较低：结果汇总回主上下文 | 较高：每个成员是独立实例 |
+
+简单来说：需要快速执行的独立子任务用子代理，需要成员之间相互沟通和协调的复杂任务用 Agent Teams。
+
+## 创建你的第一个团队
+
+用自然语言告诉 CodeBuddy 你想要什么样的团队。CodeBuddy 会根据你的描述自动创建团队、生成成员、分配任务。
+
+```
+我正在设计一个帮助开发者追踪代码中 TODO 注释的 CLI 工具。
+创建一个团队从不同角度探索这个问题：一个负责用户体验设计，
+一个负责技术架构，一个扮演"挑刺者"的角色提出质疑。
+```
+
+CodeBuddy 会：
+
+1. 创建团队和共享任务列表
+2. 为每个角色生成独立的成员
+3. 协调各成员的工作
+4. 汇总最终成果
+
+团队创建完成后，终端会显示所有成员及其当前状态。你可以通过 `@成员名` 的方式直接与任意成员对话。
+
+### 团队创建后的界面
+
+创建成功后，你会看到类似如下信息：
+
+```
+Team design-review created
+```
+
+随后领导通过 Agent 工具生成成员，每个成员以 `@成员名 · 描述` 的形式展示，并以不同颜色标识。
+
+## 控制你的团队
+
+用自然语言告诉领导你的意图，它会处理团队协调、任务分配和工作委派。
+
+### 与成员交互
+
+你可以直接与任何成员对话，无需通过领导中转。
+
+**@提及补全**：在输入框中输入 `@` 触发成员名称的 Tab 自动补全。支持模糊搜索，输入部分名称即可匹配。下拉菜单中会以成员各自的颜色显示名称，并标注状态（如 `✓ completed`）。选择成员后输入消息即可直接发送。
+
+**@all 广播**：输入 `@all` 可向所有成员同时发送消息，相当于广播。当成员数量大于 1 时，`@all` 选项会出现在补全列表的最前面。
+
+> **提示**：已完成任务的成员也会显示在 `@` 补全列表中。选择一个已完成的成员并发送消息，可以重新唤醒它继续工作。
+
+### 实时状态栏
+
+输入框下方会显示团队状态栏，展示各成员的工作状态：
+
+```
+Team (2 active) · @ux-designer ● @tech-architect ● @devils-advocate ✓
+```
+
+- `●` 表示正在工作
+- `✓` 表示已完成
+- `✗` 表示失败
+- `—` 表示已取消或被终止
+
+每个成员名称以其分配的颜色渲染，并实时显示 Token 消耗和工具调用次数。当打开补全下拉菜单时，状态栏会自动隐藏以避免遮挡。
+
+### 成员焦点导航
+
+在输入框为空时，按 `↓` 进入成员切换模式，使用方向键选择成员，回车确认切换：
+
+| 快捷键 | 功能 |
+| :--- | :--- |
+| **↓** | 进入成员切换模式 |
+| **←/→** | 在成员之间切换选择 |
+| **Enter** | 确认并切换到选中成员的视图 |
+| **Esc** | 取消选择，退出切换模式 |
+| **Ctrl+O** | 返回主视图（团队领导） |
+
+聚焦成员后：
+
+- 终端会显示该成员的完整对话历史、实时进度和 Token 消耗
+- 输入框自动切换为向该成员发送消息的模式，直接输入即可发送
+- 使用 `@main` 可将消息路由回主代理（团队领导）
+
+> **提示**：焦点导航是查看成员工作详情的最便捷方式。相比 `@成员名` 只能发送消息，焦点导航还能浏览成员的历史对话和当前工作状态。
+
+### 指定成员和模型
+
+CodeBuddy 会根据任务自动决定生成多少成员，也可以明确指定：
+
+```
+创建一个 4 人团队并行重构这些模块，每个成员使用 lite 模型。
+```
+
+### 要求成员在实施前提交计划
+
+对于复杂或高风险的任务，可以要求成员在实施前先提交计划：
+
+```
+生成一个架构师成员来重构认证模块，要求在修改代码前先提交计划等待审批。
+```
+
+成员完成计划后，会向领导发送计划审批请求。领导审核后批准或拒绝（附带反馈）。被拒绝的成员会保持计划模式，修改后重新提交。
+
+### 委派模式
+
+默认情况下，领导可能会自己动手实现任务，而不是等成员完成。按 `Shift+Tab` 可以切换到委派模式（Delegate Mode），限制领导只能使用协调工具（生成成员、发送消息、管理任务），不直接修改代码。
+
+适合你希望领导专注于任务拆分、分配和汇总的场景。
+
+### 任务分配与认领
+
+共享任务列表是团队协调的核心。任务有三种状态：待处理、进行中、已完成。任务还支持依赖关系：被依赖的任务完成后，下游任务自动解除阻塞。
+
+- **领导分配**：告诉领导把哪个任务分给哪个成员
+- **成员自主认领**：成员完成当前任务后，自动从列表中认领下一个未分配且未阻塞的任务
+
+按 `Ctrl+T` 可在终端中切换显示任务列表。
+
+### 关闭成员
+
+要优雅地结束某个成员的会话：
+
+```
+让研究员成员关闭
+```
+
+领导会发送关闭请求，成员可以接受（优雅退出）或拒绝（附带解释）。
+
+### 清理团队
+
+工作完成后，让领导清理团队资源：
+
+```
+清理团队
+```
+
+这会移除共享的团队资源目录。清理前需要先关闭所有活跃成员，否则会失败。
+
+> **重要**：始终通过领导来清理团队。成员不应执行清理操作，因为其团队上下文可能无法正确解析。
+
+## 工作原理
+
+### 团队架构
+
+一个 Agent Team 由以下组件构成：
+
+| 组件 | 作用 |
+| :--- | :--- |
+| **团队领导（Team Lead）** | 创建团队、生成成员、协调工作的主会话 |
+| **成员（Teammates）** | 独立的 CodeBuddy Code 实例，各自执行分配的任务 |
+| **任务列表（Task List）** | 所有成员共享的工作列表，支持认领和状态追踪 |
+| **消息系统（Mailbox）** | 成员间的通信机制，支持直接消息和广播 |
+
+### 执行模式
+
+成员以进程内（in-process）方式运行在主终端中。所有成员共享同一个终端窗口，通过 `@成员名` 的方式与指定成员交互。
+
+### 上下文与通信
+
+每个成员拥有独立的上下文窗口。生成时，成员会加载与普通会话相同的项目上下文（CODEBUDDY.md、MCP 服务器、技能等），并接收领导的初始 Prompt。领导的对话历史不会传递给成员。
+
+**消息类型**：
+
+| 类型 | 用途 |
+| :--- | :--- |
+| `message` | 向指定成员发送消息 |
+| `broadcast` | 向所有成员广播（谨慎使用，Token 消耗随成员数线性增长） |
+| `shutdown_request` | 请求成员关闭 |
+| `shutdown_response` | 成员响应关闭请求 |
+| `plan_approval_response` | 计划审批响应 |
+
+**自动重启机制**：已完成任务的成员在收到新消息时会自动重新启动，无需手动干预。这意味着你可以随时向任何成员发送消息，即使它已经完成工作。
+
+### 数据存储
+
+团队和任务数据存储在本地：
+
+- **团队配置**：`~/.codebuddy/teams/{team-name}/config.json`
+- **成员信箱**：`~/.codebuddy/teams/{team-name}/inboxes/{member}.json`
+- **任务列表**：`~/.codebuddy/tasks/{team-name}/`
+
+### 权限
+
+成员继承领导的权限设置。如果领导使用 `--dangerously-skip-permissions` 启动，所有成员也会如此。
+
+## 使用场景示例
+
+### 并行代码审查
+
+将审查标准拆分为独立的维度，每个成员专注一个方向：
+
+```
+创建一个团队审查 PR #142，生成三个审查员：
+- 一个关注安全影响
+- 一个检查性能瓶颈
+- 一个验证测试覆盖率
+让他们各自审查后汇报发现。
+```
+
+每个审查员从不同视角审查同一个 PR。领导在所有人完成后汇总发现。
+
+### 竞争性假设调试
+
+当根因不明确时，让多个成员并行验证不同假设：
+
+```
+用户反馈应用在发送一条消息后就断开了连接。
+生成 5 个成员分别调查不同的假设。让他们互相讨论，
+试图推翻对方的理论，像科学辩论一样。
+把最终共识更新到排查文档中。
+```
+
+这种"辩论"结构的关键在于克服锚定偏差：顺序调查容易被第一个找到的解释所主导，而多个独立调查者互相质疑时，最终存活的理论更可能是真正的根因。
+
+### 跨层功能开发
+
+前端、后端、测试各由不同成员负责：
+
+```
+我需要给用户管理模块添加批量导入功能。创建一个团队：
+- 一个负责后端 API 和数据库迁移
+- 一个负责前端界面和交互
+- 一个负责编写集成测试
+先让架构师成员设计接口规范，其他人基于规范并行开发。
+```
+
+## 最佳实践
+
+### 给成员提供充分的上下文
+
+成员会自动加载项目上下文，但不会继承领导的对话历史。在初始 Prompt 中包含任务需要的具体信息：
+
+```
+生成一个安全审查员，Prompt 如下：
+"审查 src/auth/ 目录的认证模块，重点关注 Token 处理、
+会话管理和输入验证。应用使用 JWT Token 存储在 httpOnly Cookie 中。
+对发现的问题按严重等级排序报告。"
+```
+
+### 合理划分任务粒度
+
+- **太小**：协调开销超过并行收益
+- **太大**：成员长时间不汇报，增加返工风险
+- **恰当**：自包含的工作单元，产出明确的交付物（一个函数、一个测试文件、一份审查报告）
+
+> **提示**：领导会自动将工作拆分为任务并分配。如果觉得任务拆得不够细，可以要求领导进一步拆分。每个成员保持 5-6 个任务可以让所有人保持高效，也方便领导在某人卡住时重新分配工作。
+
+### 等待成员完成
+
+有时领导会自己动手实现，而不是等成员完成。如果发现这种情况：
+
+```
+等你的成员完成各自的任务后再继续
+```
+
+或者直接切换到[委派模式](#委派模式)。
+
+### 避免文件冲突
+
+两个成员同时编辑同一个文件会导致互相覆盖。拆分工作时确保每个成员负责不同的文件集合。
+
+### 定期检查进度
+
+关注成员的工作进展，及时纠正方向偏差，随时汇总阶段性成果。长时间无人监管的团队更容易产生浪费。
+
+## 故障排除
+
+### 成员没有出现
+
+- 查看团队状态栏确认成员是否已生成并在运行中
+- 确认任务复杂度足以需要团队。CodeBuddy 会根据任务判断是否需要生成成员
+
+### 权限请求过多
+
+成员的权限请求会汇集到领导，这可能造成干扰。在生成成员前，先在[权限设置]中预先批准常见操作。
+
+### 成员遇到错误后停止
+
+成员可能在遇到错误后停止工作。通过 `@成员名` 直接给它发送额外指令，或让领导生成一个替代成员继续工作。
+
+### 领导过早结束
+
+领导可能在所有任务完成前就认为工作结束了。如果发生这种情况，告诉它继续等待，或使用委派模式限制其行为。
+
+## 已知限制
+
+Agent Teams 仍处于实验阶段，目前存在以下限制：
+
+- **无会话恢复**：`/resume` 和 `/rewind` 不会恢复成员。恢复会话后领导可能尝试向已不存在的成员发消息，这时让领导重新生成成员即可
+- **任务状态可能滞后**：成员有时未能及时标记任务为已完成，导致依赖任务被阻塞。如果发现任务卡住，手动检查工作是否已完成并更新状态
+- **关闭可能较慢**：成员会先完成当前的请求或工具调用再关闭
+- **每个会话只能管理一个团队**：清理当前团队后才能创建新团队
+- **不支持嵌套团队**：成员无法创建自己的子团队，只有领导可以管理团队
+- **领导角色固定**：创建团队的会话在整个生命周期中都是领导，不能转让
+- **权限在生成时确定**：所有成员继承领导的权限模式
+
+> **提示**：CODEBUDDY.md 正常工作 — 成员会从其工作目录读取 CODEBUDDY.md 文件。利用这一点可以为所有成员提供项目级的指导。
+
+## 相关功能
+
+- **轻量级委派**：[子代理](sub-agents.md)在会话内生成辅助代理，适合不需要成员间协调的聚焦型任务
+- **手动并行**：[Git worktrees](common-workflows.md) 允许手动运行多个 CodeBuddy Code 会话，无需自动化的团队协调