Swarm Mode 专题¶

重要性：⭐⭐⭐（多 agent 协调——teammate 模式、coordinator、inbox、mailbox） 真实位置：src/utils/swarm/ + src/coordinator/ + src/utils/teammate.ts + src/services/swarm/ 角色：多 agent 并行 / 协调 / 通信关联：topics/deep-dive-agent-tool.md、topics/architecture-history.md

1. Swarm Mode 是什么¶

Swarm Mode = 多 Claude agent 协同工作 - 1 个 leader + N 个 teammate - 通过 inbox / mailbox 通信 - Coordinator 调度任务 - 子 agent 用 tmux / in-process 启动

场景： - 复杂多任务分解 - 并行研究 - 团队式工作

2. 6 个核心目录¶

src/
├── coordinator/             ← 协调器（feature-gated COORDINATOR_MODE）
├── services/swarm/          ← swarm 服务
├── utils/swarm/             ← swarm 工具
├── hooks/useSwarm*.js       ← hooks
├── components/...           ← UI
├── utils/teammate.ts        ← teammate 工具
└── utils/swarm/reconnection.js

6 个核心位置。

3. 2 种 Teammate Mode¶

type TeammateMode = 'tmux' | 'in-process' | 'auto'

3 种（含 auto）： - tmux —— 在新 tmux 窗口启动 - in-process —— 在同进程 - auto —— 自动选

3.1 `tmux` mode¶

在新 tmux 窗口启动 teammate
用户可见 teammate
真实并行（不同 process）

3.2 `in-process` mode¶

在同 process 启动
抽象并行
性能更好

3.3 `auto`¶

根据情况自动选

4. 通信机制¶

4.1 Mailbox¶

// TeammateMailboxAttachment
type TeammateMailboxAttachment = {
  // 收件箱
}

mailbox —— teammate 间的"信"。

4.2 TeamContext¶

type TeamContextAttachment = {
  // 团队上下文
}

team_context —— 团队状态。

4.3 getTeammateMailboxAttachments¶

async function getTeammateMailboxAttachments(toolUseContext): Promise<Attachment[]>

获取来信。

4.4 getTeamContextAttachment¶

async function getTeamContextAttachment(messages): Promise<Attachment>

团队上下文。

5. 3 种 Teammate Identity Option¶

--agent-id <id>
--agent-name <name>
--team-name <name>

3 个 identity —— 必须同时提供。

5.1 验证¶

if (hasAnyTeammateOpt && !hasAllRequiredTeammateOpts) {
  process.stderr.write('Error: ...')
  process.exit(1)
}

校验。

5.2 setDynamicTeamContext¶

getTeammateUtils().setDynamicTeamContext?.({...})

设置动态 team 上下文。

6. Coordinator Mode¶

6.1 feature gate¶

if (feature('COORDINATOR_MODE')) { ... }

编译时门控 —— 商业版不打包。

6.2 coordinatorModeModule¶

// lazy require
const coordinatorModeModule = feature('COORDINATOR_MODE') 
  ? require('./coordinator/coordinatorMode.js') 
  : null;

lazy load。

6.3 推测功能¶

任务分发
状态聚合
错误恢复

7. Assistant Mode (KAIROS)¶

7.1 feature gate¶

if (feature('KAIROS') && assistantModule?.isAssistantMode()) { ... }

KAIROS —— assistant 模式。

7.2 assistantModule¶

const assistantModule = feature('KAIROS') 
  ? require('./assistant/index.js') 
  : null;
const kairosGate = feature('KAIROS') 
  ? require('./assistant/gate.js') 
  : null;

2 个 lazy 模块。

7.3 信任检查¶

if (!checkHasTrustDialogAccepted()) {
  console.warn('Assistant mode disabled: directory is not trusted...')
}

未信任目录 不启用。

7.4 Team 初始化¶

if (kairosEnabled) {
  // Pre-seed an in-process team
  // 让 Agent(name: "foo") spawn teammates without TeamCreate
}

预播种 team。

8. 5 个 Swarm Hooks¶

useSwarmInitialization
useSwarmPermissionPoller
useTeammateViewAutoExit
useBackgroundTaskNavigation
useCoordinatorTaskCount

5 个 hooks。

8.1 `useSwarmPermissionPoller`¶

registerSandboxPermissionCallback(...)

Sandbox 权限轮询。

9. Coordinator 调度¶

9.1 任务分发¶

推测： - Leader 接收任务 - 拆分子任务 - 分给 teammate - 监控进度 - 聚合结果

9.2 状态管理¶

// coordinator/coordinatorMode.ts

协调器状态。

10. Inbox Poller¶

// hooks/useInboxPoller.js

轮询收件箱 —— 监听 teammate 消息。

10.1 推测机制¶

setInterval(() => {
  // 检查 inbox
  // 推送给用户
}, 5000)

5s 轮询（推测）。

11. Background Tasks¶

11.1 `useBackgroundTaskNavigation`¶

// 导航到 background task

后台任务 导航。

11.2 `useCoordinatorTaskCount`¶

// coordinator task 数量

任务计数。

12. Reconnection¶

// utils/swarm/reconnection.ts
computeInitialTeamContext(...)

重连 —— 恢复 team 状态。

13. 4 种 Teammate 选项（CLI）¶

--agent-id <id>           # 唯一 ID
--agent-name <name>       # 显示名
--team-name <name>        # 团队名
--agent-color <color>     # 颜色
--plan-mode-required      # 计划模式必选
--parent-session-id <id>  # 父 session
--teammate-mode <mode>    # tmux / in-process / auto
--agent-type <type>       # 自定义 agent 类型

8 个 —— 完整 identity。

14. 推测的工作流程¶

用户给 leader 任务
  ↓
Leader 拆分（用 LLM）
  ↓
Leader 决定开 N 个 teammate
  ↓
每个 teammate 启动（tmux / in-process）
  ↓
Teammate 各自工作
  ↓
通过 mailbox 通信
  ↓
完成 → 报告给 leader
  ↓
Leader 聚合 → 给用户

8 步。

15. 安全考虑¶

15.1 Teammate 沙箱¶

推测：无沙箱 —— teammate 跑在主进程或 tmux 进程。

15.2 通信¶

mailbox 内容可注入 —— 注意。

15.3 Resource¶

N 个 teammate = N x 资源 —— 用户控制。

15.4 信任¶

Teammate 共享 settings —— 信任设置。

16. 5 个 feature-gated 模块¶

Module	Feature	用途
coordinatorModeModule	COORDINATOR_MODE	协调器
assistantModule	KAIROS	assistant
kairosGate	KAIROS	门控
proactiveModule	PROACTIVE / KAIROS	proactive
useScheduledTasks	AGENT_TRIGGERS	触发

5 个 —— 全部 feature-gated。

17. 关键设计模式¶

17.1 3 种 Teammate Mode¶

tmux / in-process / auto —— 3 种部署。

17.2 Mailbox 通信¶

inbox/outbox 模式。

17.3 TeamContext¶

团队共享 state。

17.4 Identity 强制¶

3 个 ID 必填。

17.5 信任检查¶

未信任目录不启用。

17.6 5 feature-gated 模块¶

全部 feature 门控。

17.7 Hook 集成¶

5 个 swarm hook。

17.8 lazy require¶

循环依赖解。

18. 关键洞察¶

18.1 Swarm = 商业版特性¶

COORDINATOR_MODE feature-gated。

18.2 3 种 Teammate Mode¶

部署灵活。

18.3 Mailbox 是核心¶

通信机制。

18.4 TeamContext 共享¶

team 状态可见。

18.5 Identity 强制¶

3 个必填。

18.6 信任检查¶

安全。

18.7 5 feature-gated¶

控制商业版。

18.8 无沙箱¶

风险。

18.9 Hook 集成¶