multi-agent 模式的演进

Claude Code 的 multi-agent 系统并非一蹴而就，而是经历了若干明确的阶段，每个阶段都解决了前一阶段的特定局限性。理解这一演进过程，有助于揭示塑造当前架构的设计压力。

五个阶段

graph LR
    S1[Stage 1<br/>Single Agent] --> S2[Stage 2<br/>Named Sub-agents]
    S2 --> S3[Stage 3<br/>Fork Mechanism]
    S3 --> S4[Stage 4<br/>Coordinator Pattern]
    S4 --> S5[Stage 5<br/>Team Swarm]

    style S1 fill:#e1f5fe
    style S2 fill:#b3e5fc
    style S3 fill:#81d4fa
    style S4 fill:#4fc3f7
    style S5 fill:#29b6f6

阶段一：Single Agent

基础阶段。一个 Claude 实例处理所有事情：读取代码、规划、编辑、运行测试以及与用户沟通。agentic loop（src/query.ts）驱动所有行为。

优势： 简单、可预测，对任务拥有完整 context。

局限： 长时间运行的任务会填满 context window。在 research 和实现之间切换浪费 token。没有并行性——用户等待 agent 逐个文件地搜索。

阶段二：Named Sub-agents

第一个 multi-agent 步骤。父 agent 可以通过 Agent tool 派生具有特定角色的 sub-agent：

// 六个内置 agent，各有明确职责
const agents = [
  GENERAL_PURPOSE_AGENT,  // 全部 tool，默认模型
  EXPLORE_AGENT,          // 只读，快速模型（haiku），omitClaudeMd
  PLAN_AGENT,             // 只读，继承模型，专注架构
  VERIFICATION_AGENT,     // 对抗性测试，后台执行
  CLAUDE_CODE_GUIDE_AGENT, // 文档查询，haiku 模型
  STATUSLINE_SETUP_AGENT,  // 状态栏配置，sonnet 模型
]

关键设计决策：

1. 模型分层。 并非每个 agent 都需要最强大的模型。Explore 使用 haiku 追求速度；Plan 使用 inherit 追求推理深度；Statusline 使用 sonnet 作为中间层平衡点。

2. Tool 限制。 只读 agent（Explore、Plan）通过 disallowedTools 实现 isolation——禁用 Edit、Write 和 Agent tool——而非独立的”只读模式”标志。

3. Token 优化。 对只读 agent 设置 omitClaudeMd: true，将 CLAUDE.md 层级从其 context 中移除。在规模化场景下（3400 万次以上 Explore 派生），这一优化效果显著。

4. 优先级覆盖系统。 来自 .claude/agents/ 的自定义 agent 可以覆盖内置 agent，支持项目级定制：

built-in → plugin → user → project → flag → managed (policy)

局限： 每个 sub-agent 从空白状态启动。Explore agent 的 research 发现被汇总回父级，父级必须向实现 agent 重新解释这些发现。context 在传递过程中损失。

阶段三：Fork Mechanism

fork 通过给予子进程父级的完整对话历史，解决了 context 损失问题：

// Fork：子进程继承一切
const FORK_AGENT = {
  tools: ['*'],           // 与父级相同的 tool
  model: 'inherit',       // 与父级相同的模型
  permissionMode: 'bubble', // permission 上浮至父级
  getSystemPrompt: () => '', // 父级已渲染的 prompt 直接透传
}

关键创新： 跨 fork 共享 prompt cache。同一父级 turn 的所有 fork 子进程共享完全相同的 API 请求前缀——只有每个子进程的专属指令不同：

[shared history + identical placeholder results... | per-child directive]
                                                     ↑ 只有这里变化

局限： fork 仍是临时的。它们执行一个任务后汇报结果。没有持久的 team 结构，agent 之间没有持续协作。

阶段四：Coordinator Pattern

coordinator 从根本上重构了交互模型。主实例不再是偶尔委托的强大 single agent，而是成为将所有实质性工作委托出去的编排者：

graph TD
    subgraph "Stage 2: Parent dispatches"
        P1[Parent Agent] -->|occasional delegation| S1[Sub-agent]
        P1 -->|does most work itself| P1
    end

    subgraph "Stage 4: Coordinator orchestrates"
        C[Coordinator] -->|all work delegated| W1[Worker 1]
        C -->|all work delegated| W2[Worker 2]
        C -->|all work delegated| W3[Worker 3]
        C -.->|synthesize & direct| C
    end

关键演进： coordinator 的主要职责是 synthesis，而非执行。它读取 worker 的发现，理解问题，并撰写精确的实现规格。prompt 中明确禁止懒惰委托（“Based on your findings, fix it”）。

与 fork 互斥。 coordinator 模式和 fork 模式互斥（isForkSubagentEnabled 在 coordinator 模式下返回 false）。它们代表不同的编排哲学：

• Fork： “以完整 context 克隆自己，让克隆体处理一部分”
• Coordinator： “我指挥专家。我理解全局。他们负责执行。“

阶段五：Team Swarm

swarm 以持久性和多种执行后端扩展了 coordinator 概念：

特性	Coordinator	Team Swarm
成员	临时 worker	持久队友
后端	同进程	InProcess / Tmux / iTerm2
Isolation	共享文件系统	每个成员独立 git worktree
身份	任务 ID	持久的 name@team ID
状态	worker 执行完毕即终止	队友 idle 后等待
通信	task notification	双向消息

Swarm 新增了：

1. 持久身份。 队友拥有稳定的 agentId（格式：name@team），跨交互持久存在。coordinator 可以通过 SendMessage 继续与队友交互，无需重新派生。

2. 多种后端。 in-process 队友通过 AsyncLocalStorage isolation 与 Node.js 进程共享。Tmux 和 iTerm2 后端在独立终端 pane 中派生完全独立的进程。

3. Git worktree isolation。 每个队友可以拥有自己的 worktree——仓库的轻量级副本，可以自由修改文件而不影响其他 agent。

4. Team 文件持久化。 team 配置在 session 重启后仍然存在，支持长期运行的协作工作。

Feature Flag 架构

每个阶段都受 feature flag 控制，支持逐步发布和 A/B 测试：

阶段	Feature Flag	控制方式
Named sub-agents	BUILTIN_EXPLORE_PLAN_AGENTS	GrowthBook tengu_amber_stoat
Verification agent	VERIFICATION_AGENT	GrowthBook tengu_hive_evidence
Fork mechanism	FORK_SUBAGENT	Feature flag + 非 coordinator + 非 SDK
Coordinator	COORDINATOR_MODE	Feature flag + 环境变量

GrowthBook 集成使 Anthropic 能够：

• 独立对每种 agent 模式进行 A/B 测试
• 衡量对 token 使用量、任务完成率和用户满意度的影响
• 在不影响其他功能的情况下回滚单个特性

设计张力：Context 与 Isolation

贯穿所有阶段的根本张力：

graph LR
    subgraph "More Context"
        A[Fork: Full parent history]
        B[Continue via SendMessage]
    end
    subgraph "More Isolation"
        C[Fresh spawn: Clean slate]
        D[Worktree: Separate filesystem]
    end
    A ---|tradeoff| C
    B ---|tradeoff| D

• 更多 context 意味着更好的理解，但消耗更多 token，且可能包含过时信息
• 更强的 isolation 意味着更干净的执行，但需要显式传递 context

coordinator 的”continue vs. spawn”决策表将这一权衡编码为实用的启发式规则：

与下一个任务的 context 重叠度高 → 继续现有 worker

context 重叠度低 → 派生新 worker

演进的每个阶段都为应对这一根本张力提供了更成熟的工具。这一演进并非替代关系——所有阶段共存。用户可以对简单任务使用 single agent 模式，对复杂功能使用 coordinator 模式，对长期项目使用 team swarm。该架构支持这全部范围的使用场景。