协调器模式：多代理任务协调

协调器模式是Claude Code的高级特性，它将AI助手从单一执行者转变为多代理任务编排者。在这种模式下，协调器不直接执行代码修改或文件操作，而是通过生成多个异步Worker代理来并行处理复杂任务，实现研究、实现、验证等阶段的智能分工与高效协作。这种架构特别适合大型重构、多文件修改、跨模块验证等需要并行处理的复杂软件工程任务。

架构概览

协调器模式的核心架构基于主从式多代理系统，其中协调器充当任务调度中心，Worker代理作为独立执行单元。协调器通过三个核心工具控制整个任务生命周期：Agent工具用于生成新的Worker代理，SendMessage工具用于向运行中的Worker发送后续指令，TaskStop工具用于终止走错方向的Worker。每个Worker代理拥有独立的对话上下文和工具集，可以异步执行文件读写、Shell命令、代码编辑等操作，而协调器则专注于任务分解、进度监控和结果综合。

graph TB
    User[用户] --> Coordinator[协调器 Coordinator]
    Coordinator -->|Agent Tool| W1[Worker 1<br/>研究任务]
    Coordinator -->|Agent Tool| W2[Worker 2<br/>实现任务]
    Coordinator -->|Agent Tool| W3[Worker 3<br/>验证任务]
    
    W1 -->|Task Notification| Coordinator
    W2 -->|Task Notification| Coordinator
    W3 -->|Task Notification| Coordinator
    
    Coordinator -->|SendMessage| W2
    Coordinator -->|TaskStop| W3
    
    W1 --> Scratchpad[共享Scratchpad]
    W2 --> Scratchpad
    W3 --> Scratchpad
    
    style Coordinator fill:#f9f,stroke:#333,stroke-width:4px
    style W1 fill:#bbf,stroke:#333,stroke-width:2px
    style W2 fill:#bbf,stroke:#333,stroke-width:2px
    style W3 fill:#bbf,stroke:#333,stroke-width:2px

Sources: coordinatorMode.ts, AgentTool.tsx

核心组件

协调器角色定义

协调器的系统提示明确定义了其作为编排者而非执行者的身份。协调器的主要职责包括：理解用户目标、将复杂任务分解为可并行的子任务、生成Worker代理执行具体工作、综合多个Worker的研究结果、以及向用户报告整体进度。关键原则是协调器永远不直接操作工具，而是通过Worker代理间接完成所有文件修改和代码执行。

协调器通过环境变量CLAUDE_CODE_COORDINATOR_MODE激活，系统会自动检测并切换到协调器模式。在会话恢复时，matchSessionMode函数会根据存储的会话模式自动调整环境变量，确保协调器行为的一致性。协调器的系统提示包含详细的任务工作流指导，强调并行性、任务合成的必要性，以及Worker失败时的处理策略。

Sources: coordinatorMode.ts, coordinatorMode.ts

Worker代理机制

Worker代理通过Agent工具生成，每个Worker获得独立的对话上下文和受限的工具集。Worker可用的工具包括文件操作（Read、Edit、Write）、搜索工具（Grep、Glob、WebSearch、WebFetch）、Shell命令（Bash、PowerShell）、代码编辑（NotebookEdit）、技能调用（Skill）等，但明确排除Agent工具本身以防止递归生成、TaskOutput工具以避免循环依赖、以及计划模式相关工具。

Worker的执行状态通过LocalAgentTask或RemoteAgentTask管理，任务状态包括pending、running、completed、failed、killed等。每个Worker维护独立的进度追踪器，记录工具使用次数、Token消耗、最近活动等元数据。Worker完成后通过<task-notification> XML格式向协调器报告结果，包含任务ID、状态、摘要、最终输出和使用统计。

Sources: AgentTool.tsx, tools.ts, LocalAgentTask.tsx

消息传递系统

协调器与Worker之间的通信通过异步消息传递机制实现。SendMessage工具允许协调器向特定Worker发送后续指令，支持通过Worker名称或Agent ID寻址。消息内容可以是纯文本指令，也可以是结构化消息如shutdown_request、shutdown_response、plan_approval_response等。这种设计使得协调器能够在Worker完成任务后继续利用其已加载的上下文，避免重复加载文件和重建理解。

消息路由系统支持多种寻址方式： teammate名称用于团队内通信，*通配符用于广播消息，uds:<socket-path>用于本地进程间通信，bridge:<session-id>用于远程控制场景。消息在接收端被加入Worker的pendingMessages队列，Worker在下一轮查询循环中处理这些消息。

Sources: SendMessageTool.ts, SendMessageTool.ts

任务控制与监控

任务控制通过TaskStop工具实现，允许协调器终止走错方向的Worker。任务监控则通过CoordinatorAgentStatus组件实现，该组件在REPL界面底部显示所有后台Worker的状态，包括任务描述、运行时间、Token消耗、排队消息数等信息。任务面板支持键盘导航，用户可以通过方向键选择Worker，按Enter进入Worker视图查看详细进度，按X停止或清除已完成任务。

任务生命周期管理通过framework.ts中的registerTask、updateTaskState、evictTerminalTask等函数实现。任务状态存储在全局AppState.tasks中，支持任务的注册、更新和自动清理。已完成的任务在通知协调器后会被自动清理，但保留30秒的宽限期以便用户查看最终状态。

Sources: TaskStopTool.ts, CoordinatorAgentStatus.tsx, framework.ts

任务工作流

协调器模式的任务工作流遵循四阶段模型：研究、综合、实现和验证。研究阶段由多个Worker并行执行，探索代码库的不同方面；综合阶段由协调器整合所有研究发现，形成明确的实现规格；实现阶段由Worker根据规格执行代码修改；验证阶段由独立的Worker验证修改的正确性。这种分工确保了任务的系统性和可验证性。

阶段对比分析

阶段	执行者	目标	并行性	典型任务
Research	多个Worker并行	探索代码库，理解问题域	✅ 高度并行	查找相关文件、分析依赖关系、理解现有实现
Synthesis	协调器	整合发现，制定实现计划	❌ 单点	分析研究结果、识别关键路径、编写精确规格
Implementation	Worker（串行或并行）	根据规格修改代码	⚠️ 按文件集串行	修改函数、重构模块、添加新特性
Verification	独立Worker	证明代码正确性	✅ 可并行	运行测试、类型检查、边缘情况验证

Sources: coordinatorMode.ts

并行策略

协调器的核心优势在于智能并行化。只读任务（如研究）可以无限制并行，协调器会同时启动多个Worker探索不同角度；写任务（如实现）需要按文件集串行执行以避免冲突，但不同文件集可以并行处理；验证任务通常可以与实现任务并行，只要它们操作不同的文件区域。协调器会根据任务性质自动选择合适的并行策略。

关键并行化原则包括：独立任务立即并行，无需等待前一任务完成；相关任务按依赖串行，避免竞态条件；验证独立于实现，确保验证者不受实现者假设的影响。协调器在生成Worker时会明确指示任务目的，例如”这项研究将用于PR描述——关注面向用户的变更”或”这是合并前的快速检查——只验证主路径”。

Sources: coordinatorMode.ts, coordinatorMode.ts

Worker提示编写规范

协调器最重要的职责是综合研究发现并编写精确的Worker提示。由于Worker无法看到协调器的对话，每个提示必须自包含所有必要信息。协调器必须阅读Worker的研究结果，理解发现的内容，然后编写包含具体文件路径、行号、精确修改指令的提示。反模式包括”根据你的发现修复bug”或”Worker在auth模块发现问题，请修复”，这些短语将理解责任推给了Worker。

良好的提示示例：“修复src/auth/validate.ts:42处的空指针。Session的user字段在会话过期但令牌仍被缓存时为undefined。在访问user.id之前添加null检查——如果为null，返回401并附带’Session expired’消息。提交并报告哈希值。“这种提示包含了文件路径、行号、根本原因、修复方案和完成标准，Worker无需额外上下文即可执行。

Sources: coordinatorMode.ts

继续vs新生成策略

在综合研究发现后，协调器需要决定是继续现有Worker还是生成新Worker。决策基于上下文重叠度：如果Worker的研究正好覆盖了需要编辑的文件，继续该Worker可以复用已加载的上下文；如果研究很广泛但实现很窄，生成新Worker可以避免拖累无关的探索上下文；如果验证刚刚由另一个Worker编写的代码，生成新Worker确保验证者以新鲜视角审查代码。

情况	机制	原因
研究探索了需要编辑的文件	继续（SendMessage）	Worker已有文件上下文 + 清晰计划
研究广泛但实现窄	新生成（Agent工具）	避免探索噪音；专注上下文更清晰
修正失败或扩展近期工作	继续	Worker有错误上下文且知道刚尝试的内容
验证不同Worker刚编写的代码	新生成	验证者应以新鲜视角查看代码
首次尝试完全错误的方法	新生成	错误方法上下文污染重试；干净状态避免锚定失败路径
完全无关的任务	新生成	无有用上下文可复用

Sources: coordinatorMode.ts

高级特性

Scratchpad共享机制

当启用tengu_scratch特性门控时，协调器模式提供Scratchpad目录作为Worker间的持久化共享存储。Worker可以在Scratchpad中读写文件而无需权限提示，这为跨Worker知识传递提供了基础设施。Scratchpad的结构由Worker自行决定，可以用于存储中间结果、共享配置、协调状态等。

Scratchpad路径通过getCoordinatorUserContext函数的scratchpadDir参数注入，该参数由QueryEngine.ts在更高层依赖图中提供。这种依赖注入设计避免了coordinatorMode.ts与filesystem.ts之间的循环依赖。协调器在系统提示中告知Worker Scratchpad的位置和用途，Worker根据任务需要自主决定如何使用这一共享空间。

Sources: coordinatorMode.ts

会话恢复与模式切换

协调器模式支持会话恢复，当用户恢复之前的协调器会话时，matchSessionMode函数会检测存储的会话模式并自动调整环境变量。如果当前模式与会话模式不匹配，函数会翻转CLAUDE_CODE_COORDINATOR_MODE环境变量并记录模式切换事件到分析系统。这确保了协调器行为在会话恢复后的一致性。

会话模式存储在会话元数据中，可能的值为coordinator或normal。对于没有存储模式的老会话，系统不做任何调整，保持当前环境设置。这种向后兼容设计允许平滑升级到协调器模式而不破坏现有会话。

Sources: coordinatorMode.ts

Worker隔离模式

Worker支持两种隔离模式：worktree隔离和remote隔离。Worktree隔离为Worker创建临时Git worktree，使其在仓库的隔离副本上工作，避免与主工作目录冲突。Remote隔离在远程CCR环境中启动Worker，适用于需要特殊环境或资源的任务。隔离模式通过Agent工具的isolation参数指定，与cwd参数互斥。

隔离模式特别适用于并行实现任务，多个Worker可以同时修改不同文件集而不会相互干扰。当Worker完成后，系统会自动清理worktree并合并变更回主分支。这种设计实现了真正的并行开发工作流，显著提高了复杂任务的执行效率。

Sources: AgentTool.tsx

实现细节

工具可用性控制

Worker的工具集通过ASYNC_AGENT_ALLOWED_TOOLS白名单控制，包括文件操作（Read、Edit、Write）、搜索（Grep、Glob、WebSearch、WebFetch）、Shell（Bash、PowerShell）、代码编辑（NotebookEdit）、技能调用（Skill）等。明确排除的工具包括Agent工具（防止递归）、TaskOutput工具（避免循环依赖）、计划模式工具（主线程抽象）等。

工具过滤在filterToolsForAgent函数中实现，该函数根据Worker类型（本地代理、远程代理、进程内队友）应用不同的过滤规则。进程内队友还额外获得任务管理工具（TaskCreate、TaskGet、TaskList、TaskUpdate）和定时任务工具（CronCreate、CronDelete、CronList），这些工具允许队友管理子任务和定时触发器。

Sources: tools.ts, coordinatorMode.ts

任务通知格式

Worker完成后通过<task-notification> XML格式向协调器报告结果。通知包含任务ID（用于SendMessage继续）、状态（completed/failed/killed）、人类可读摘要、最终输出（可选）和使用统计（可选）。协调器通过<task-notification>开标签区分Worker通知和真实用户消息。

<task-notification>
  <task-id>agent-a1b</task-id>
  <status>completed</status>
  <summary>Agent "Investigate auth bug" completed</summary>
  <result>Found null pointer in src/auth/validate.ts:42...</result>
  <usage>
    <total_tokens>15420</total_tokens>
    <tool_uses>12</tool_uses>
    <duration_ms>45320</duration_ms>
  </usage>
</task-notification>

Sources: coordinatorMode.ts, LocalAgentTask.tsx

进度追踪机制

每个Worker维护独立的ProgressTracker，记录工具使用计数、最新输入Token、累积输出Token和最近活动列表。进度更新通过updateProgressFromMessage函数实现，该函数解析助手消息中的工具使用和Token使用信息。最近活动列表限制为5个条目，通过FIFO策略自动淘汰旧条目。

进度信息通过AgentProgress接口暴露给UI，包括工具使用计数、Token计数、最后活动、最近活动列表和摘要。CoordinatorAgentStatus组件使用这些信息显示Worker的实时状态，包括当前正在执行的工具、Token消耗趋势（通过上下箭头指示）和排队消息数。

Sources: LocalAgentTask.tsx, CoordinatorAgentStatus.tsx

使用示例

典型协调器会话

以下示例展示协调器如何处理”auth模块有空指针异常”的用户请求。协调器首先并行启动两个研究Worker，一个调查bug本身，另一个研究auth测试套件；在收到研究结果后，协调器综合发现并向第一个Worker发送修复指令；Worker完成后报告提交哈希。

// 用户："auth模块有空指针，能修复吗？"

// 协调器第一轮：并行研究
Agent({ description: "Investigate auth bug", subagent_type: "worker", 
        prompt: "Investigate the auth module in src/auth/. Find where null pointer exceptions could occur..." })
Agent({ description: "Research auth tests", subagent_type: "worker",
        prompt: "Find all test files related to src/auth/. Report the test structure..." })

// 协调器："从两个角度调查中——我会报告发现。"

// Worker通知到达
<task-notification>
  <task-id>agent-a1b</task-id>
  <status>completed</status>
  <result>Found null pointer in src/auth/validate.ts:42...</result>
</task-notification>

// 协调器第二轮：综合并继续
SendMessage({ to: "agent-a1b", 
              message: "Fix the null pointer in src/auth/validate.ts:42. Add a null check before accessing user.id..." })

Sources: coordinatorMode.ts

错误处理模式

当Worker报告失败（测试失败、构建错误、文件未找到）时，协调器应使用SendMessage继续该Worker，因为它拥有完整的错误上下文。如果修正尝试再次失败，协调器应尝试不同方法或向用户报告。对于完全错误的方法，协调器应使用TaskStop停止Worker并生成新Worker，避免错误上下文污染重试。

// Worker报告测试失败
<task-notification>
  <task-id>agent-x7q</task-id>
  <status>failed</status>
  <summary>Tests failed after changes</summary>
  <result>Two tests failing at validate.test.ts:58 and :72...</result>
</task-notification>

// 协调器：继续同一Worker（有错误上下文）
SendMessage({ to: "agent-x7q",
              message: "Two tests still failing at lines 58 and 72 — update the assertions to match the new error message." })

// 用户改变需求
// 用户："其实，保留session——只修复空指针"

// 协调器：停止错误方向的Worker
TaskStop({ task_id: "agent-x7q" })
SendMessage({ to: "agent-x7q",
              message: "Stop the JWT refactor. Instead, fix the null pointer in src/auth/validate.ts:42..." })

Sources: coordinatorMode.ts

性能与限制

并发控制

协调器模式没有硬编码的Worker数量限制，但实际并发受系统资源（内存、CPU、API限流）约束。每个Worker维护独立的对话上下文和工具池，内存消耗与上下文大小成正比。建议对于I/O密集型任务（如研究、搜索）可以高度并行，对于CPU密集型任务（如大型重构）应适度控制并发数。

自动后台任务功能通过tengu_auto_background_agents特性门控或CLAUDE_AUTO_BACKGROUND_TASKS环境变量启用，默认在120秒后将长时间运行的Worker移至后台。后台Worker继续执行但不会阻塞用户输入，用户可以通过任务面板随时查看进度或进入Worker视图。

Sources: AgentTool.tsx, framework.ts

工具限制影响

Worker无法使用某些工具带来了特定限制：无法使用Agent工具意味着Worker不能生成子Worker（防止递归爆炸）；无法使用计划模式工具意味着Worker不能进入交互式计划审批流程；无法使用MCP工具（当前限制）意味着Worker不能访问外部MCP服务器资源。这些限制是为了保证系统稳定性和避免复杂依赖。

对于需要MCP资源的任务，协调器应直接执行或生成具有特殊权限的Worker。对于需要计划审批的任务，协调器应在生成Worker前完成计划阶段，或将计划作为Worker提示的一部分。

Sources: tools.ts

与其他系统集成

协调器模式与Claude Code的其他系统深度集成：与权限系统集成，Worker继承协调器的权限模式但可以独立演进；与压缩服务集成，Worker的上下文可以独立压缩以节省Token；与会话管理集成，Worker的对话记录存储在独立文件中支持恢复；与MCP服务集成，Worker可以访问协调器连接的MCP服务器（通过workerToolsContext注入）。

协调器还可以与团队系统集成，通过TeamCreate工具创建多代理团队，生成具有特定角色和权限的队友。队友通过SendMessage工具相互通信，通过共享任务列表协调工作。这种集成使得协调器模式可以扩展到更复杂的多代理协作场景。

Sources: coordinatorMode.ts, TeamCreateTool.ts

扩展阅读

AgentTool：子代理与多代理协作 - 深入了解Worker代理的生成机制和工具池管理
整体架构：从CLI入口到QueryEngine - 理解协调器在整体架构中的位置
状态管理：AppState与React Context体系 - 掌握任务状态在全局状态中的存储和更新
API服务：认证、限流与Anthropic API客户端 - 了解Worker如何与API交互及限流影响
权限服务：PermissionMode与动态权限验证 - 理解Worker的权限继承和隔离机制