Hugging Face's logo

chenbhao
/
codev

English
codev
code-assistant
terminal
ai
Model card Files
xet
 Community
codev / docs /coordinator /multi-agent.md
chenbhao's picture
chenbhao
chore: rename VersperClaw to Codev, update org to chenbhao
96f34e3
preview code
|
Raw
History Blame Contribute Delete
11.5 kB

Coordinator 多代理模式

概述

Coordinator 模式是 Codev 的一种高级执行模式，允许一个协调者（Coordinator）LLM 通过 AgentTool 派生子代理（Worker）并行执行任务。通过 CLAUDE_CODE_COORDINATOR_MODE 环境变量激活。

激活方式 

export CLAUDE_CODE_COORDINATOR_MODE=1

检测逻辑位于 src/coordinator/coordinatorMode.ts：

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：

<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 的使用 

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 示例 

// 好的 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 示例（反模式） 

// 坏的 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 继续。

Agent Teams（Swarm 拓扑）

概述

Agent Teams（Swarm 模式）是 Codev 的多 Agent 拓扑模型，通过 feature('AGENT_SWARMS') 编译期标记门控。与 Coordinator/Worker 模式不同，Teams 采用文件系统邮箱通信，每个 Agent 在独立进程中运行（tmux split-pane / in-process）。

激活方式 

export CLAUDE_CODE_AGENT_SWARMS=1

核心架构 

Team Lead (AgentTool team_name="my-team" name="lead")
    │
    ├── AgentTool(name="researcher", team_name="my-team") → tmux pane / in-process
    │     └── 邮箱: ~/.claude/teams/my-team/mailbox/researcher/
    │
    ├── AgentTool(name="coder", team_name="my-team") → tmux pane / in-process
    │     └── 邮箱: ~/.claude/teams/my-team/mailbox/coder/
    │
    └── AgentTool(name="reviewer", team_name="my-team") → tmux pane / in-process
          └── 邮箱: ~/.claude/teams/my-team/mailbox/reviewer/

与 Coordinator/Worker 的区别

维度 Coordinator/Worker Agent Teams (Swarm)
通信 <task-notification> XML 消息 文件系统邮箱（mailbox）
进程 同进程 独立 OS 进程（tmux / in-process）
生命周期 单次任务 持久化团队
隔离度 共享上下文 AsyncLocalStorage（in-process）或完全隔离
工具白名单 统一限制 可配置 agent_type → 自定义工具集
嵌套 Coordinator 可 spawn worker 禁止团队成员 spawn 子代（仅 team lead 可）

团队创建流程

  1. 创建团队: TeamCreateTool({ name: "my-team" }) → 生成 ~/.claude/teams/my-team/config.json
  2. 设置 Leader: 当前会话自动成为 team-lead
  3. 派发成员: AgentTool({ name: "researcher", team_name: "my-team", prompt: "..." })
  4. 后台抉择:
    • In-process（启用时）→ 同一进程 AsyncLocalStorage 隔离
    • tmux split-pane（默认）→ 新 tmux 窗格
    • tmux separate-window → 新 tmux 窗口
    • iTerm2 native → macOS 原生分屏
  5. 通信: 成员写入 mailbox/{agent-name}/，lead 轮询读取

邮箱通信格式 

{
  "from": "researcher",
  "text": "研究发现...",
  "timestamp": 1712345678000
}

团队成员配置

自定义 Agent 定义（~/.claude/agents/）：

{
  "name": "researcher",
  "tools": ["BashTool", "ReadTool", "GrepTool", "GlobTool"],
  "model": "claude-sonnet-4-20250514"
}

关键文件

文件 职责
src/tools/AgentTool/AgentTool.tsx 统一调度入口（Line 262-316 为团队路径）
src/tools/shared/spawnMultiAgent.ts 三种 spawn 后端实现（1105 行）
src/tools/TeamCreateTool/TeamCreateTool.ts 团队创建 + 任务列表重置
src/tools/TeamDeleteTool/TeamDeleteTool.ts 团队清理 + 活跃成员验证
src/utils/swarm/teamHelpers.ts TeamFile 类型、文件锁、清理
src/utils/swarm/inProcessRunner.ts 同进程 teammate 生命周期（1553 行）
src/utils/swarm/teammateInit.ts Stop hook、路径白名单
src/utils/swarm/constants.ts TEAM_LEAD_NAME, SWARM_SESSION_NAME

Spawn 后端对比

后端 隔离 优点 缺点
tmux split-pane 完整进程隔离 可视化管理，可独立 kill 需要 tmux
tmux separate-window 完整进程隔离 传统方式 UI 不够紧凑
iTerm2 native 完整进程隔离 macOS 原生集成 仅 macOS
In-process AsyncLocalStorage 无需终端，快速 共享进程，有限隔离

清理机制

  • cleanupSessionTeams() 在 SIGINT/SIGTERM 时自动执行
  • 终止所有团队成员窗格
  • 清理团队目录和任务目录
  • 文件锁防止并发竞争

Forbidden 规则

Agent 工具过滤（filterToolsForAgent()）：

  1. MCP 工具（mcp__*）始终保留
  2. ALL_AGENT_DISALLOWED_TOOLS 从所有 Agent 移除
  3. CUSTOM_AGENT_DISALLOWED_TOOLS 额外从非内置 Agent 移除
  4. ASYNC_AGENT_ALLOWED_TOOLS 异步 Agent 仅允许白名单工具

Fork Subagent（实验性）

概述

通过 feature('FORK_SUBAGENT') 门控，提供另一种 Agent 拓扑：子 Agent 继承父会话的全部上下文。

关键特性

  • 上下文继承: 子 Agent 从父会话的完整历史开始
  • 字节级缓存优化: 所有 fork 共享相同 API 前缀（字节一致），提高 prompt 缓存命中
  • 权限冒泡: permissionMode: 'bubble' — 权限提示冒泡到父终端
  • 强制异步: 所有 fork spawn 必须异步执行

适用场景

  • 需要子 Agent 拥有完整对话上下文时
  • 希望复用父会话的 prompt 缓存

核心文件

文件 职责
src/tools/AgentTool/forkSubagent.ts buildForkedMessages() 构建字节相同前缀