夜雨聆风
推荐直接网站在线阅读：https://aicoting.cn本文建议阅读时长：5分钟
所有相关文档、源码示例、流程图与面试八股，我也将持续更新在AIHub：https://github.com/aicoting/AIHub（复制到浏览器打开），欢迎关注收藏！
本文根据 src 目录中的源码整理 Claude Code 的 Multi-Agent 机制，但重点不放在逐个函数、字段和分支的复述上，而是解释这套机制背后的设计思想：Claude Code 并没有把多 Agent做成一组彼此平行的聊天窗口，而是把它拆成短生命周期的任务委派和长生命周期的团队协作两种形态，再用统一的任务状态、工具权限、消息路由、会话转录和隔离能力把它们连接起来。
从用户视角看，Multi-Agent 像是 Claude 把一个复杂问题拆给多个助手；从源码视角看，它更像是一套分层调度系统：主会话负责判断什么时候委派、委派给谁、是否需要隔离、是否要后台运行，而被委派的 agent 只在自己的上下文里完成任务，并通过受控的结果、通知或消息机制把信息交还给主会话。
1. 概览
=
这张图表达的是源码里的核心关系：主会话并不是把完整上下文随意复制给所有 agent，而是在合适的位置创建一个新的执行单元，并且通过工具集、权限、任务状态和隔离策略限制它能做什么、能看到什么、完成后如何回报。任务型 subagent 像一次可等待、可后台化、可恢复的委派；团队型 teammate 则更像一个有名字、有 inbox、有生命周期的协作者。
2. 两种 Agent 形态
=
源码里的 Multi-Agent 首先要区分两种形态，否则很多机制会显得混杂。
第一种是任务型 subagent，它通常由 AgentTool 启动，用来完成一个相对明确的子任务，例如搜索、分析、验证、规划或在隔离工作区里尝试修改；它可以同步返回，也可以转入后台，并且完成后通过结果文本、任务通知或输出文件把结论交还给主会话。
第二种是团队型 teammate，它通常从 TeamCreate 建立团队上下文开始，再由带有成员名称和团队名称的 agent 调用创建。teammate 的重点不是一次任务跑完就结束，而是以某个身份长期存在，它可以接收后续消息、进入空闲状态、等待新的指令、向 leader 请求权限、参与计划审批，最终通过受控的 shutdown 流程退出团队。
这两种形态共享很多底层能力，例如 agent 执行循环、工具解析、权限判断、任务状态、输出记录和消息转录；但它们在交互模型上明显不同：subagent 是一次委派，teammate 是持续协作。
源码通过这种区分避免了一个常见问题：如果所有 agent 都只是后台任务，长期沟通会很别扭；如果所有 agent 都是长期队友，简单委派又会过重。
3. 任务型 Subagent
=
任务型 subagent 的核心目标是减少主会话负担。主会话不需要亲自展开所有搜索、分析和验证，也不需要把每一步中间工具输出都塞进自己的上下文；它只需要把任务目标描述清楚，然后让 subagent 在独立上下文中完成工作，最后拿回一个浓缩后的结果。
这套设计让 subagent 可以在信息隔离和结果回传之间取得平衡。它不是完全脱离主会话的独立进程，因为主会话仍然决定它的任务、工具和权限；它也不是主会话的一段普通上下文扩展，因为它拥有自己的消息历史、文件状态、输出记录和取消逻辑。
源码里的 fork 型 subagent 进一步强化了这个思想：当主会话已经积累了重要上下文，但又不希望多个 worker 的中间结果污染主上下文时，可以让子 agent 继承相同的上文前缀，只在最后追加不同的指令。这样做的价值不是复制更多上下文，而是让多个并行 worker 站在同一个理解基线上工作，同时尽量降低对主会话窗口和缓存结构的破坏。
4. 团队型 Teammate
=
团队型 teammate 的核心目标不是减轻一次任务的上下文压力，而是组织多个长期协作者。一个 teammate 有名字、颜色、团队归属、当前活跃状态、权限模式和消息 inbox；它完成当前工作后不会自然消失，而是进入 idle 状态，等待新的消息或关闭请求。
这种设计把协作从隐式上下文共享改成了显式消息交换。leader 不是随时窥看每个 teammate 的内部思考过程，而是通过消息、通知、输出和状态了解它们的工作；teammate 之间也不是共享一整段会话历史，而是通过 inbox 发送结构化或普通消息。这样做让协作边界更清晰，也让跨进程、跨窗格甚至跨会话恢复成为可能。
in-process teammate 和 pane-backed teammate 的差异，主要是运行位置不同，而不是协作语义不同。前者在同一个 Node.js 进程里运行，便于复用主进程能力和 UI 权限确认；后者在 tmux、iTerm2 或独立 CLI 会话里运行，更接近真正的多进程协作。无论哪一种，它们都通过团队名册和消息系统维持我是团队成员的身份。
5. 消息路由
=
如果只看 agent 启动逻辑，会误以为 Multi-Agent 的重点是如何创建更多 agent；但从整体机制看，更关键的是创建之后如何继续沟通。
源码中的消息路由承担了两种任务：一是给后台 subagent 追加指令或恢复它继续工作，二是给 teammate 发送普通消息、广播消息或结构化控制消息。
这个路由层让主会话可以用同一个发送动作处理不同对象：目标如果是一个后台任务，就进入任务队列或恢复流程；目标如果是团队成员，就写入对应 inbox；目标如果是整个团队，就广播给除发送者之外的成员。这样的设计减少了调用方需要理解的底层差异，因为继续告诉某个 agent 一件事在用户和主模型眼里是统一动作，而底层再决定它究竟是任务续跑还是团队消息。
6. 权限与安全
=
多 agent 系统最容易失控的地方，是每个 agent 都能无限制地使用工具、请求权限、修改文件或生成新的 agent。Claude Code 的源码没有把 agent 看成完全自治实体，而是让它们在启动前获得受限工具集，在执行中接受权限模式约束，在需要高风险操作时回到主会话或 leader 的权限确认路径。
普通后台 subagent 通常不能随意弹出交互式权限请求，因为它已经离开了主会话的同步执行链路；team teammate 虽然长期运行，但高风险工具仍可以通过 leader 的确认界面或 mailbox 协议来请求批准。换句话说，Multi-Agent 不是把控制权平均分给所有 agent，而是把执行权分出去，把授权权收回来。
隔离机制也是这个思想的一部分。cwd、临时 worktree 和 remote 执行并不是为了制造复杂性，而是为了让 agent 的行动范围更可控：简单分析可以在当前目录完成，可能修改代码的并行尝试可以放进独立 worktree，远端运行则在满足条件时把长任务或特殊任务移出本地会话。
7. 状态与恢复
=
Multi-Agent 如果只会启动，不能观察和恢复，就很难成为可靠机制。源码把后台 agent、remote agent 和 in-process teammate 都接入任务状态系统，使它们拥有可查询的状态、进度、输出、错误和终止信息；同时，关键输出会写入文件或 transcript，使主会话不必把所有细节长期压在当前上下文里。
这种设计的意义在于，后台 agent 不只是扔出去等结果，而是可以被通知、读取、终止、追加消息，甚至在合适条件下从已有转录中恢复继续运行。团队 teammate 也不只是开了一个窗口，而是通过 team file、inbox 和任务状态表达自己是否活跃、是否空闲、是否等待审批或是否正在关闭。
8. 源码阅读导航
=
如果想从源码验证上述思想，可以到https://github.com/aicoting/claude-code按下面顺序阅读，而不必一开始陷进所有实现细节：
主题 | 主要文件 |
任务型 agent 如何启动 |
|
agent 执行循环如何复用 |
|
后台任务如何记录和通知 |
|
团队如何创建和清理 |
|
teammate 如何启动 |
|
in-process teammate 如何长期运行 |
|
agent 与 teammate 如何继续沟通 |
|
9. 总结
=
Claude Code 的 Multi-Agent 机制，本质上是在一个代码代理系统里引入受约束的并行协作。它不追求让每个 agent 都拥有完整自治权，而是让主会话保留任务分解、权限决策和结果整合的控制力；它也不把所有协作都塞进同一个上下文窗口，而是通过独立上下文、任务状态、输出文件、team file 和 inbox 把信息边界显式化。
这种架构的优点是层次清楚：短任务用 subagent，长期协作用 teammate，执行逻辑尽量复用，沟通和权限集中治理，隔离与恢复作为可靠性补充。理解这套机制时，与其记住每个函数名，不如抓住三个核心思想：委派时隔离上下文，协作时显式通信，授权时集中收束。
📚推荐阅读
1 | |
2 | |
3 | |
4 | |
5 | |
6 |
Agent面试题（更新中...）
源码解读Claude Code（更新中）
