| # Coordinator 多代理模式 |
|
|
| ## 概述 |
|
|
| Coordinator 模式是 VersperClaw 的一种高级执行模式，允许一个协调者（Coordinator）LLM 通过 `AgentTool` 派生子代理（Worker）并行执行任务。通过 `CLAUDE_CODE_COORDINATOR_MODE` 环境变量激活。 |
|
|
| ### 激活方式 |
|
|
| ```bash |
| export CLAUDE_CODE_COORDINATOR_MODE=1 |
| ``` |
|
|
| 检测逻辑位于 `src/coordinator/coordinatorMode.ts`： |
|
|
| ```typescript |
| export function isCoordinatorMode(): boolean { |
| if (feature('COORDINATOR_MODE')) { |
| return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE) |
| } |
| return false |
| } |
| ``` |
|
|
| ### 会话模式匹配 |
|
|
| `matchSessionMode()` 确保恢复的会话与当前 coordinator 模式一致。如果环境变量与会话存储的模式不匹配（例如在 coordinator 模式下创建会话，然后在 normal 模式下恢复），会自动翻转环境变量并记录事件。 |
|
|
| --- |
|
|
| ## 工作模式 |
|
|
| ### 核心架构 |
|
|
| ``` |
| User → Coordinator LLM → AgentTool → Worker 1 |
| → Worker 2 |
| → Worker 3 (并行) |
| ``` |
|
|
| - **Coordinator LLM**：接收用户请求，制定计划，派发任务，综合结果 |
| - **Worker**：通过 `AgentTool` 派生的子代理，执行具体任务 |
| - **通信**：Worker 结果通过 `<task-notification>` XML 格式返回 |
|
|
| ### Worker 通信格式 |
|
|
| Worker 完成时，结果以 `user-role` 消息形式送达 Coordinator： |
|
|
| ```xml |
| <task-notification> |
| <task-id>{agentId}</task-id> |
| <status>completed|failed|killed</status> |
| <summary>{human-readable status summary}</summary> |
| <result>{agent's final text response}</result> |
| <usage> |
| <total_tokens>N</total_tokens> |
| <tool_uses>N</tool_uses> |
| <duration_ms>N</duration_ms> |
| </usage> |
| </task-notification> |
| ``` |
|
|
| Coordinator 必须区分工作结果消息和真实用户消息：工作结果包含 `<task-notification>` 标签。 |
|
|
| --- |
|
|
| ## 工作流：四阶段模型 |
|
|
| ### Phase 1: Research（研究） |
| - Coordinator 并行启动多个 Worker 进行独立研究 |
| - 每个 Worker 负责调查代码库的不同方面 |
| - 只读任务，可自由并行 |
|
|
| ### Phase 2: Synthesis（综合） |
| - Coordinator **亲自**阅读所有研究发现 |
| - 理解问题本质，编写具体的实现规格 |
| - **关键原则**：Coordinator 必须理解研究发现再分配任务，不能将理解工作委托给 Worker |
|
|
| ### Phase 3: Implementation（实现） |
| - 根据综合后的规格派发实现任务 |
| - 按文件集串行处理写操作，避免冲突 |
|
|
| ### Phase 4: Verification（验证） |
| - 独立的 Worker 验证实现结果 |
| - 真正的验证意味着证明代码工作，而非确认代码存在 |
| - 测试、类型检查和边缘用例 |
|
|
| --- |
|
|
| ## 并行策略 |
|
|
| ### 只读任务全并行 |
| 研究阶段的所有 Worker 可同时启动，互不影响。 |
|
|
| ### 写任务按文件集串行 |
| 实现阶段的写操作需谨慎：同一组文件的操作需要串行执行。 |
|
|
| ### 验证与实现可部分并行 |
| 实现的不同文件区域可同时进行验证。 |
|
|
| --- |
|
|
| ## 工具集 |
|
|
| Coordinator 拥有以下专用工具（定义于 `src/tools/AgentTool/AgentTool.tsx`）： |
|
|
| | 工具 | 用途 | |
| |------|------| |
| | `AgentTool`（`Agent`） | 创建新的 Worker | |
| | `SendMessageTool` | 向已存在的 Worker 发送后续指令 | |
| | `TaskStopTool` | 停止正在运行的 Worker | |
| | `subscribe_pr_activity` | 订阅 GitHub PR 事件 | |
|
|
| ### AgentTool 的使用 |
|
|
| ```typescript |
| AgentTool({ |
| description: "Investigate auth bug", |
| subagent_type: "worker", |
| prompt: "..." |
| }) |
| ``` |
|
|
| 重要规则： |
| - 不要用一个 Worker 去检查另一个 Worker 的状态——Worker 完成时会自动通知 |
| - 不要为简单的文件读取或命令执行创建 Worker |
| - 不要设置 model 参数——Worker 使用默认模型 |
| - 已完成工作的 Worker 应通过 `SendMessageTool` 继续使用其加载的上下文 |
|
|
| --- |
|
|
| ## Prompt 编写规则 |
|
|
| ### Worker 看不到 Coordinator 的对话 |
|
|
| 每个 Worker prompt 必须**自包含**，包含执行任务所需的全部信息。Coordinator 不能假设 Worker 知道对话中发生过什么。 |
|
|
| ### 好的 Prompt 示例 |
|
|
| ```typescript |
| // 好的 prompt：包含具体路径、行号和精确指令 |
| AgentTool({ |
| prompt: "Fix the null pointer in src/auth/validate.ts:42. " + |
| "The user field can be undefined when the session expires. " + |
| "Add a null check and return early with an appropriate error. " + |
| "Commit and report the hash." |
| }) |
| ``` |
|
|
| ### 坏的 Prompt 示例（反模式） |
|
|
| ```typescript |
| // 坏的 prompt：模糊、依赖上下文 |
| AgentTool({ prompt: "Fix the bug we discussed" }) // 错误：Worker 看不到讨论 |
| AgentTool({ prompt: "Based on your findings, implement the fix" }) // 错误：懒惰的委托 |
| ``` |
|
|
| ### 目的陈述 |
|
|
| 为 Prompt 添加目的说明，帮助 Worker 校准深度和重点： |
|
|
| - "This research will inform a PR description — focus on user-facing changes." |
| - "I need this to plan an implementation — report file paths, line numbers, and type signatures." |
|
|
| ### continue vs spawn 的选择 |
|
|
| | 场景 | 策略 | 原因 | |
| |------|------|------| |
| | 研究恰好覆盖了需编辑的文件 | **Continue**（SendMessageTool） | Worker 已有文件在上下文中 | |
| | 研究范围广，实现范围窄 | **Spawn fresh**（AgentTool） | 避免携带探索噪音 | |
| | 纠正错误或扩展近期工作 | **Continue** | Worker 有错误上下文 | |
| | 验证其他 Worker 的代码 | **Spawn fresh** | 验证者需以新视角查看代码 | |
| | 完全不同的任务 | **Spawn fresh** | 无有用上下文可复用 | |
|
|
| --- |
|
|
| ## 实现细节 |
|
|
| ### 核心文件 |
|
|
| | 文件 | 路径 | 用途 | |
| |------|------|------| |
| | coordinatorMode.ts | `src/coordinator/coordinatorMode.ts` | Coordinator 模式检测、会话匹配、用户上下文构建 | |
| | AgentTool.tsx | `src/tools/AgentTool/AgentTool.tsx` | Agent 工具的实现 | |
| | builtInAgents.ts | `src/tools/AgentTool/builtInAgents.ts` | 内置 Agent 定义 | |
|
|
| ### Worker 工具白名单 |
|
|
| 内部 Worker 工具（由 `INTERNAL_WORKER_TOOLS` 定义的集合）对 Worker 不可见： |
|
|
| - `TeamCreateTool` |
| - `TeamDeleteTool` |
| - `SendMessageTool` |
| - `SyntheticOutputTool` |
|
|
| 在简单模式（`CLAUDE_CODE_SIMPLE`）下，Worker 仅有权访问：Bash、Read、Edit 工具，外加 MCP 工具。 |
|
|
| ### Worker 错误处理 |
|
|
| 当 Worker 报告失败时： |
| - 使用 `SendMessageTool` 继续同一 Worker——它保留完整的错误上下文 |
| - 如果纠正尝试也失败，尝试不同方法或报告用户 |
|
|
| ### 停止 Worker |
|
|
| 使用 `TaskStopTool` 停止方向错误的 Worker。已停止的 Worker 可通过 `SendMessageTool` 继续。 |
|
|
