Claude Code 多 Agent 编排：Subagent → Coordinator → Swarm → Workflow

一句话定位：Claude Code 的多 Agent 系统是四层递进架构——从最简单的一次性子 agent 委派，到中央协调器，到去中心化团队协作，再到 JS 脚本编排的 Dynamic Workflow。

调研时间：2026-06-22
依据版本：泄露源码包（2026-03-31）+ 官方文档（2026-06）
核心文件：src/utils/swarm/（22 文件）、src/coordinator/、src/tasks.ts、src/Task.ts、src/utils/task/framework.ts

证据等级汇总

日常类比

把多 Agent 系统想象成建筑工地的组织形式：

类比边界：真实系统中 Coordinator 和 Swarm 可以混合使用，且 Workflow 是最新加入的模式，与前三者并非互斥。

四层递进架构

graph TB
    subgraph L1["Layer 1: Subagent（最简单）"]
        AgentTool[AgentTool] --> |"spawn"| Worker1[一次性 Worker]
        Worker1 --> |"结果返回"| AgentTool
    end

    subgraph L2["Layer 2: Coordinator（中央调度）"]
        Coord[Coordinator] --> |"AgentTool"| W2A[Research Worker]
        Coord --> |"AgentTool"| W2B[Impl Worker]
        Coord --> |"SendMessage"| W2A
        Coord --> |"TaskStop"| W2B
    end

    subgraph L3["Layer 3: Swarm（去中心化）"]
        Leader[Team Lead] <--> |"mailbox"| T1[Teammate 1]
        Leader <--> |"mailbox"| T2[Teammate 2]
        T1 <--> |"mailbox"| T2
    end

    subgraph L4["Layer 4: Dynamic Workflow（JS 编排）"]
        Script[workflow.js] --> |"orchestrate"| A1[Agent A]
        Script --> |"orchestrate"| A2[Agent B]
        Script --> |"orchestrate"| A3[Agent C]
        A1 --> |"结果"| Script
        A2 --> |"结果"| Script
    end

    L1 --> |"复杂度增加"| L2
    L2 --> |"持续协作"| L3
    L3 --> |"可预测流程"| L4

Layer 1：Subagent（AgentTool）

最基础的多 Agent 模式——主 agent 通过 AgentTool 派生一个子 agent 执行独立任务 [源码]。

执行流程：

主 Agent 调用 AgentTool:
  input: { prompt, allowedTools?, model? }
  
AgentTool 内部:
  1. 创建新的 ToolUseContext (独立 abortController)
  2. 注册为 TaskType='local_agent' (ID: a/xxxxxxxx)
  3. 运行独立的 queryLoop
  4. 子 agent 有自己的 system prompt + 工具集
  5. 完成后返回结果给主 agent

关键约束:
  - 子 agent 看不到主 agent 的对话历史
  - 子 agent 的 prompt 必须自包含
  - 子 agent 有独立的 token 预算
  - 子 agent 的权限由 PermissionHandler 决定

Task 生命周期 [源码]：

Layer 2：Coordinator Mode

通过 CLAUDE_CODE_COORDINATOR_MODE 环境变量激活 [源码]，主 agent 变为纯调度角色：

可用工具（仅 3 个）：

• AgentTool — 派生 worker
• SendMessageTool — 向已有 worker 发送后续指令
• TaskStopTool — 终止 worker

4 阶段工作流（Coordinator System Prompt 定义）[源码]：

graph LR
    R[1. Research<br>并行调研] --> S[2. Synthesis<br>协调器综合]
    S --> I[3. Implementation<br>并行实现]
    I --> V[4. Verification<br>并行验证]

设计原则：

• “Parallelism is your superpower” — 独立任务必须并行
• Coordinator 必须综合调研结果（不能说”based on your findings”直接委派）
• Worker 看不到对话 → prompt 必须自包含
• Continue vs. Spawn 决策：上下文重叠高 → SendMessage；新任务 → AgentTool
• Scratchpad 目录用于跨 worker 知识共享

与 CrewAI 对比：

Layer 3：Swarm / Teams

最复杂的多 Agent 模式——持续性团队协作 [源码]。

架构概览

graph TB
    subgraph "Team Lead (主进程)"
        Leader[Leader Agent]
        UI[Permission UI]
        TaskList[Task List]
    end

    subgraph "Backend: in-process"
        T1[Teammate 1<br>AsyncLocalStorage]
        T2[Teammate 2<br>AsyncLocalStorage]
    end

    subgraph "Backend: tmux"
        T3[Teammate 3<br>tmux pane]
    end

    Leader <-->|"file mailbox"| T1
    Leader <-->|"file mailbox"| T2
    Leader <-->|"file mailbox"| T3
    T1 -->|"permission bridge"| UI
    T2 -->|"permission bridge"| UI
    TaskList -->|"auto-claim"| T1
    TaskList -->|"auto-claim"| T2

三种执行后端 [源码]

通信机制：文件邮箱 [源码]

通信协议:
  writeToMailbox(targetId, message) → 写入 JSON 文件
  readMailbox(selfId) → 读取并消费消息

消息优先级:
  leader 消息 > peer 消息 > shutdown 请求

消息类型:
  - prompt: 新任务指令
  - task-notification: 任务完成/失败通知
  - shutdown: 终止信号

进程内队友执行循环 [源码]

spawnInProcessTeammate(config):
  1. 注册 TaskType='in_process_teammate' (ID: t/xxxxxxxx)
  2. 创建独立 ToolUseContext
  3. 进入 runInProcessTeammate 循环:
     while (!shutdown):
       a. 执行当前 prompt (queryLoop)
       b. 进入 idle 状态
       c. 等待: 新邮件 / task-list 认领 / shutdown
       d. 收到新任务 → 回到 a
  4. 支持 auto-compact (token 超阈值时)
  5. 支持 per-turn abort (Escape 停当前工作)

上下文隔离:
  runWithTeammateContext() 使用 AsyncLocalStorage
  每个 teammate 有独立的:
    - agentId
    - abortController
    - readFileState (文件缓存)
    - 颜色标识 (UI 区分)

权限委托 [源码]

Worker 需要权限时的处理：

1. UI Bridge 可用：通过 leaderPermissionBridge 将权限请求转发到 leader 的 UI，显示 “worker badge” 标识哪个 agent 在请求
2. UI Bridge 不可用：通过 mailbox 发送权限请求，leader 处理后回复
3. 后台 worker：shouldAvoidPermissionPrompts=true，自动拒绝所有权限请求

Layer 4：Dynamic Workflow

编排逻辑从 model context 外置到 JS 脚本 [文档][引用]。

源码中的痕迹 [引用]

// src/tasks.ts — 条件加载
const LocalWorkflowTask = feature('WORKFLOW_SCRIPTS')
  ? require('./tasks/LocalWorkflowTask.js')
  : null

// src/Task.ts — 类型定义
type TaskType = '...' | 'local_workflow'  // ID 前缀: w/

泄露包中 LocalWorkflowTask 的实现文件缺失——被 WORKFLOW_SCRIPTS feature flag 守护，外部 build 中被 DCE 剔除。

官方文档描述 [文档]

Dynamic Workflow 是 2026-05-28 发布的功能，核心设计：

• 编排脚本：用户编写 .js 文件定义工作流
• 并行执行：脚本可以同时启动多个 agent 任务
• 结果聚合：脚本收集各 agent 结果后决定下一步
• 与 turn-loop 的区别：传统模式下编排逻辑在 model context 内（消耗 token），Workflow 将其外置到确定性代码

Ultracode [文档]

Ultracode 不是独立功能，而是一个设置组合：

• effort = xhigh（最高推理强度）
• 自动 workflow 决策：模型判断任务是否适合用 Dynamic Workflow，适合则自动生成并执行编排脚本

用户视角:
  claude --model opus --effort xhigh  (即 "ultracode" 模式)

内部行为:
  1. 模型收到任务
  2. 判断: 这个任务适合 workflow 吗?
     - 是 → 生成 workflow.js → 执行
     - 否 → 正常 turn-loop
  3. xhigh effort 让模型在每步都深度思考

Task 框架：统一管理

src/utils/task/framework.ts（309 行）提供任务的统一生命周期管理 [源码]：

Task 通知格式：

<task-notification task_id="a/x7k2m9p1" status="completed">
  Worker completed: Implemented authentication module.
  Files changed: src/auth.ts, src/middleware.ts
</task-notification>

编排模式对比矩阵

与开源框架对比

vs LangGraph

vs tRPC-Agent

局限性

• LocalWorkflowTask 实现缺失：泄露包中仅有类型引用和 feature flag 守护，无法分析具体实现 [引用]
• Swarm 的 tmux/iTerm2 后端：源码完整但未实测，不确定当前版本是否仍支持
• Coordinator 的 system prompt：源码中有完整定义，但可能已被官方更新
• Dynamic Workflow 的 JS API：仅有官方文档描述，无法验证内部实现细节
• 团队记忆（TEAMMEM flag）：源码中有引用但实现细节分散

下一步

• System Prompt 分层 — Coordinator/Swarm 的 prompt 如何组装
• Dynamic Workflow + Ultracode — JS 编排脚本的详细机制
• Claude Code 全景 — 在 Agent 生态中的定位