📬 Claude Code Agent Teams Mailbox 机制深度解析

0. 先定位：Mailbox 在整体架构中的位置

Claude Code 的 Agent Teams 架构有三个核心支柱：

┌─────────────────────────────────────────────────────┐
│                  Agent Teams 架构                    │
│                                                      │
│  ┌───────────────┐  ┌──────────────┐  ┌───────────┐ │
│  │ Context       │  │ Task List    │  │ Mailbox   │ │
│  │ Isolation     │  │ (共享任务)   │  │ (消息通信)│ │
│  │ 上下文隔离    │  │              │  │           │ │
│  └───────────────┘  └──────────────┘  └───────────┘ │
└─────────────────────────────────────────────────────┘

Mailbox 就是 Agent 之间的"微信群"——让独立的 Agent 实例可以互相发消息、协调工作，而不是只能通过一个中心调度器中转。

---

1. 两种多 Agent 模式的本质区别

要理解 Mailbox 的价值，必须先理解它和 Subagent 模式的根本差异：

Subagent 模式（传统，Claude Code 之前就有）

                ┌─────────────┐
                │  主 Agent    │
                │ (Orchestrator)│
                └──────┬──────┘
                       │ 派发任务
          ┌────────────┼────────────┐
          ▼            ▼            ▼
     ┌────────┐   ┌────────┐   ┌────────┐
     │子Agent A│   │子Agent B│   │子Agent C│
     └───┬────┘   └───┬────┘   └───┬────┘
         │            │            │
         └────────────┼────────────┘
                      ▼ 汇报结果
              ┌─────────────┐
              │  主 Agent    │  ← 唯一的协调者
              └─────────────┘

• 中心化调度：主 Agent 是唯一的"大脑"，所有协调都经过它
• 子 Agent 不互相感知：A 不知道 B 在做什么，也不能直接问 B
• 适合：简单、明确的任务拆解（Bug fix、单功能开发）

Agent Teams + Mailbox 模式（新）

     ┌──────────┐
     │ Team Lead│  ← 架构师/项目经理，拥有最高权限
     └────┬─────┘
          │
    ┌─────┴──────────────────────────────┐
    │         Mailbox（消息总线）          │
    │   message（点对点）+ broadcast（广播）│
    └─────┬─────────┬─────────┬──────────┘
          ▼         ▼         ▼
     ┌────────┐┌────────┐┌────────┐
     │Teammate││Teammate││Teammate│
     │   A    │◄───►│   B    │◄───►│   C    │
     └────────┘└────────┘└────────┘
         ↕ 彼此可以直接通信、协商、挑战 ↕

• 去中心化通信：队友之间可以直接对话，不需要经过 Lead
• 共享任务列表：所有人都能看到任务板，自己认领任务
• 真正的协作：Agent 之间可以讨论、争论、互相 review

类比：Subagent 像"包工头带工人"——工人干完活汇报给包工头；Agent Teams 像"创业团队"——成员之间可以自由讨论、分工、挑战彼此的想法。

---

2. Mailbox 的技术实现

2.1 通信方式

所有 Members 之间通过 IPC（进程间通信）实现消息传递：

操作	方式	说明
message	点对点	向指定的某一个队友发送消息
broadcast	广播	同时向所有队友发送消息

2.2 消息触发场景（什么时候会自动发消息？）

Agent Teams 中的消息不是只有人手动触发，系统会在关键节点自动发消息：

触发场景	发送者	接收者	消息内容
队友完成子任务，进入空闲	Teammate → Lead	"我完成了 XXX，现在空闲"
前置依赖解锁	系统 → 等待中的队友	"你依赖的任务已就绪，可以开始了"
发现需要其他队友的成果	Teammate A → Teammate B	"我需要你那个模块的接口定义"
Lead 分配新任务	Lead → Teammate	"这是你的新任务：XXX"
队友遇到问题请求帮助	Teammate → Lead（或直接问队友）	"我在 XXX 卡住了"
对抗式讨论	Teammate A ↔ Teammate B	"你的假设有问题，我认为应该是 YYY"

2.3 持久化存储

Mailbox 的消息不是内存中的临时数据，而是持久化到文件系统的：

~/.claude/teams/{team-name}/
├── config.json          # 团队配置（每个队友的 model、prompt）
└── inboxes/             # 每个 Agent 的收件箱
    ├── lead.json        # Team Lead 的收件箱
    ├── teammate-a.json  # 队友 A 的收件箱
    └── teammate-b.json  # 队友 B 的收件箱

这种设计有几个好处：

• 跨进程可靠：即使 Claude Code 进程意外退出，消息不会丢失
• 可审计：可以回看所有 Agent 之间的通信历史
• 简单可靠：不需要额外的消息队列服务（如 Redis/RabbitMQ），纯文件系统就能搞定

2.4 共享任务列表

与 Mailbox 配套的是共享的任务板：

~/.claude/tasks/{team-name}/
├── task-001.json  # { status: "completed", subject: "...", deps: [] }
├── task-002.json  # { status: "in-progress", subject: "...", deps: ["task-001"] }
└── task-003.json  # { status: "pending", subject: "...", deps: ["task-001", "task-002"] }

• 三种状态：pending（待处理）→ in_progress（进行中）→ completed（已完成）
• 依赖管理：任务可设置前置依赖，依赖未解决时任务被锁定
• 文件锁防竞争：多个队友同时认领任务时，用文件锁机制防止冲突
• 自动解锁：当依赖任务完成后，被阻塞的任务自动变为可认领状态

---

3. Mailbox 的工作流示例

以一个真实场景说明 Mailbox 如何运作：

需求：为项目添加用户认证模块，创建一个 Agent Team

Step 1：Lead 拆解任务并创建团队

用户: "创建一个团队开发用户认证模块：前端登录、后端 API、测试"

Lead（自动）:
  → 创建 Teammate A（前端，model: Sonnet）
  → 创建 Teammate B（后端，model: Opus）
  → 创建 Teammate C（测试，model: Haiku）
  → 生成 Task List，设置依赖关系
  → 通过 Mailbox 给每个队友分配初始任务

Step 2：队友并行工作 + 互相通信

Teammate B（后端）:
  → 开发 Auth API
  → 完成后 message → Lead: "Auth API 已完成，接口定义在 auth/routes.ts"
  → broadcast → 全员: "API 接口已更新，请同步"

Teammate A（前端）:
  → 收到 broadcast，知道 API 已就绪
  → 直接 message → B: "登录接口的请求格式是什么？"
  → B reply → A: "POST /api/auth/login, body: { email, password }"
  → 开始对接前端

Teammate C（测试）:
  → 等待依赖解锁（task-001, task-002 completed）
  → 自动收到系统消息: "你的前置任务已完成，开始执行"
  → 写测试用例

Step 3：对抗式调试（高级用法）

场景：结账接口 5% 请求返回 500 错误

Lead → 创建 5 个队友，每个调查一个假说:
  - 队友 1: 数据库连接池耗尽？
  - 队友 2: 竞态条件？
  - 队友 3: 第三方 API 超时？
  - 队友 4: GC 暂停？
  - 队友 5: 网络抖动？

队友之间通过 Mailbox:
  - 队友 1 → 队友 2: "你说的竞态条件不成立，我查了日志没有并发异常"
  - 队友 3 → 全员: "找到了！支付 API 的 timeout 设置是 5s，但高负载下 P99 延迟 8s"
  → 最终存活的假说指向根本原因

---

4. 为什么 Mailbox 是比 Coordinator 更高级的范式？

4.1 从"星型拓扑"到"网状拓扑"

Coordinator（星型）:           Mailbox（网状）:
     Lead                         Lead
    / | \                        / | \
   A  B  C                      A - B - C
   ↑  ↑  ↑                     ↓ ↕ ↑ ↕ ↓
   └──┴──┘ ← 只能通过 Lead      A ↔ C  ← 可以直接通信

Coordinator 的瓶颈在于 Lead：所有信息都要经过它，它成了单点瓶颈

Mailbox 让 Agent 之间直接通信，Lead 只管宏观调度，不用做"传话筒"

4.2 关键优势总结

维度	Coordinator/Subagent	Agent Teams + Mailbox
通信路径	必须经过主 Agent	Agent 之间直连
信息效率	信息在主 Agent 处汇聚/分发的开销	减少中转，实时同步
灵活性	主 Agent 控制一切	Agent 可以自主协商
容错性	主 Agent 挂了全挂	去中心化，单点故障影响小
协作深度	任务级别协作	可以讨论、争论、review
适合场景	简单明确的任务	复杂功能、调试、重构
资源消耗	较低（串行或简单并行）	较高（3~5 个并行实例，Token 消耗数倍）

---

5. 两种运行模式的区别

5.1 进程内模式（in-process）

• 所有队友运行在同一个终端里
• 一次只能看到一个队友的输出
• 用 Shift+上/下 键切换查看不同队友
• 不需要额外工具

5.2 分屏模式（split-pane，基于 tmux）

• 需要 tmux + iTerm2
• 每个 Agent 有独立的终端窗口
• 可以同时看到所有 Agent 的输出
• 可以直接点击进入某个 Agent 的窗格进行交互
• 体验类似一个"多人编程的终端 IDE"

5.3 Delegate Mode（委托模式）

按 Shift+Tab 开启，让 Lead 只做指挥不做编码：

• ✅ 拉起/关闭队友
• ✅ 给队友发消息、对齐方向
• ✅ 管理任务列表、跟进进度
• ❌ 不再改代码、跑命令、直接实现功能

5.4 Plan Approval 模式

队友在写代码前先提交计划给 Lead 审查：

• Lead 批准 → 队友开始实施
• Lead 拒绝 + 反馈 → 队友修改计划重新提交

---

6. 面试怎么讲？（一句话 + 三段论）

一句话版本

"Claude Code 的 Mailbox 机制实现了从'主从调度'到'去中心化协作'的范式升级——Agent 之间通过 IPC 消息总线直接通信，配合共享任务列表和文件锁，实现了真正的多 Agent 自主协调。"

三段论版本（如果面试官追问）

是什么：Mailbox 是 Agent Teams 中的消息通信系统，支持点对点（message）和广播（broadcast）两种方式，通过文件系统持久化收件箱，让多个独立 Claude Code 实例可以在同一任务下互相通信。

为什么更好：相比传统 Subagent 的星型拓扑（所有信息必须经过主 Agent），Mailbox 实现了网状拓扑（Agent 之间直连），减少了信息中转开销，让 Agent 可以自主协商、讨论甚至对抗式调试，而不是被动等待指令。

本质洞察：这反映了多 Agent 系统从"编排"（Orchestration）到"协作"（Collaboration）的演进。前者是中心化的、确定性的；后者是去中心化的、涌现性的。Claude Code 的 Mailbox 是目前主流 AI Coding 工具中最接近"真正的多 Agent 协作"的实现。