Skip to main content
Claude Code 里有很多看起来都叫“多 Agent”的东西:Agent 工具、fork agent、Coordinator Mode、Agent Teams / Swarm、remote agent、后台 runtime task、TaskCreate 任务白板。它们共享部分底层设施,但不是同一个抽象。 这篇文档解决的是跨机制理解问题:当你看到一个任务被“派出去”、一个 teammate 变成 idle、一个 <task-notification> 回到主线程、一个 team 目录还在但 teammate 不跑了,应该知道它属于哪套机制、状态放在哪里、通信走哪条路、哪些东西能恢复。

全局心智模型

最短心智模型是:
Agent 是派人干活。
TaskCreate 是往白板上贴任务卡。
Runtime Task 是正在跑的人或远端人影。
Coordinator 是星型编排器。
Swarm 是有成员、有邮箱、有任务白板的团队。
先把几个词压平:
概念本质入口状态位置结果回路
普通 sync subagent一次性前台 Agent tool callAgent({ subagent_type })foreground LocalAgentTask当前 turn 的 tool_result
普通 async subagent一次性后台 agentAgent({ subagent_type, async: true }) 或自动后台化AppState.tasks + sidechainasync_launched + <task-notification>
fork agent继承父上下文和 exact tools 的后台分支省略 subagent_type 且 fork gate 满足LocalAgentTask + .meta.json<task-notification>
coordinator workerCoordinator 派出的 worker async subagentCoordinator 调 Agent({ subagent_type: "worker" })LocalAgentTask<task-notification> + SendMessage(to: agentId)
swarm teammate长生命周期团队成员Agent({ name, team_name?, prompt })InProcessTeammateTask 或 pane membermailbox by name,可 idle 后继续
remote agent远端执行体的本地镜像Agent(..., isolation: "remote")RemoteAgentTask + remote sidecarCCR events / polling
work item task共享任务白板条目TaskCreate/Update/List/Get~/.claude/tasks/<taskListId>/*.jsonteammate / lead 认领和更新
runtime task正在运行或曾运行的后台执行体agent、shell、workflow、remote 等入口AppState.tasksUI、spinner、resume、kill

系统分层

多 Agent 系统可以看成五层,每层回答一个问题:
回答的问题典型对象
入口层用户或模型通过什么工具启动动作/coordinatorAgentToolTeamCreateSendMessageTaskUpdate
编排层谁负责拆解、派发、控制和综合Coordinator、Team Lead、AgentTool routing
运行层谁真正执行或代表执行状态LocalAgentTaskInProcessTeammateTaskRemoteAgentTask
通信层结果和控制信号如何回流tool_result<task-notification>、mailbox、CCR events
持久化层进程重启后还能看见什么session JSONL、sidechain、team config、task files、inbox、sidecar meta
这五层不是一一对应关系。Coordinator worker 在运行层是 LocalAgentTask,通信层靠 <task-notification>SendMessage(to: agentId);Swarm teammate 在运行层可能是 InProcessTeammateTask,通信层靠 mailbox;remote agent 在运行层是本地 RemoteAgentTask 镜像,真实执行状态来自 CCR。

什么时候用哪套机制

场景推荐机制为什么
需要一个主脑拆解、派发、综合、纠偏Coordinator Mode主线程被限制为编排器,减少直接上手乱改。
多个任务相对独立,需要长期队友持续领任务Agent Teams / Swarm有 team config、mailbox、shared task list。
只想派一个专家研究或修改普通 subagent成本低、模型路径短、结果直接回当前 turn 或后台通知。
想复制当前上下文做并行探索fork agent继承父上下文和 exact tools,适合分支探索。
想把工作放到远端环境执行remote agent本地只保留 RemoteAgentTask 镜像,执行在 CCR。
两个常见误判:
误判更好的选择
“我要并行,所以一定用 Swarm”如果只是一次性研究/验证,用 async subagent 或 Coordinator worker 更轻。
“我要团队,所以 Coordinator 就够了”如果需要成员持续认领共享任务、互相发消息、保留 team 状态,用 Swarm。

两种多 Agent 拓扑

Coordinator 和 Swarm 都是多 Agent,但控制权和状态模型完全不同。
维度Coordinator ModeAgent Teams / Swarm
拓扑星型:Coordinator 居中,worker 外围团队型:Team Lead + named teammates + mailbox + task list
主 Claude 角色只编排,不直接执行可以直接执行,也可以作为 team lead 管理团队
执行者built-in worker async subagentteammate,可能是 in-process,也可能是 pane-based
通信方式<task-notification>,必要时 SendMessage(to: agentId)mailbox by name,支持 P2P、broadcast、structured protocol
任务协作不以 TeamCreate/TaskList 为核心TeamFile + shared task list + mailbox
恢复模型mode 在主 transcript,worker 是 local agent sidechainteam/task/inbox 文件可保留;in-process runner 不完整恢复
Coordinator Mode 不是 Swarm 的特殊 Team Lead。它共享 AgentToolLocalAgentTaskSendMessage 等设施,但不使用 TeamCreate/TeamDelete/TaskList/TaskUpdate 作为核心团队协作机制。

Coordinator Mode 五段状态机

Coordinator Mode 的核心设计是把主 Claude 降级为编排器:主线程不直接 Read/Edit/Bash,而是拆任务、派 worker、综合结果、必要时停止或继续 worker。

1. 启用状态机

两层条件都满足才算进入 Coordinator:
条件作用
feature("COORDINATOR_MODE")构建/运行 feature gate。
CLAUDE_CODE_COORDINATOR_MODE=1当前进程实际进入 coordinator。

2. 恢复状态机

Coordinator mode 是会话属性,写在主 session JSONL 的 mode entry 中:
{"type":"mode","sessionId":"...","mode":"coordinator"}
resume 时会把当前环境和 transcript 中的 mode 对齐: 这避免用户在 normal 环境恢复 coordinator 会话,或反过来把普通会话误当 coordinator 运行。

3. Prompt 状态机

Coordinator prompt 不是只看 env。交互 REPL 侧大致优先级是:
优先级来源说明
1override system prompt最高优先级。
2coordinator promptisCoordinatorMode() 且没有 mainThreadAgentDefinition 时使用。
3main-thread agent prompt--agent / settings agent。
4custom/default prompt普通主线程 prompt。
5append prompt追加型补充。
风险点是 --agent 和 Coordinator 混用:可能出现工具池已经按 coordinator 过滤,但 system prompt 不是 coordinator 的不一致。 Headless 也要单独看。当前 headless 路径明确做了 coordinator 工具过滤,并注入 coordinator user context;但 system prompt 组装路径和交互 REPL 不完全相同,应把它当成需要复核的边界,而不是默认等同交互路径。

4. 工具过滤状态机

Coordinator 主线程和 worker 的工具池不同:
角色工具池设计目的
Coordinator 主线程AgentSendMessageTaskStopSyntheticOutput、PR activity 订阅类 MCP 工具只编排,不直接执行。
workerASYNC_AGENT_ALLOWED_TOOLS,排除 TeamCreateTeamDeleteSendMessageSyntheticOutput执行任务,但不能继续嵌套编排。
simple mode workerBashReadEdit降低工具面,适合简单执行路径。
MCP 工具按已连接 server 注入 worker context让 worker 能使用外部能力,但由工具池控制边界。
scratchpadgate 开启时提供 scratchpad 目录允许跨 worker 共享临时知识。
交互路径主要走 mergeAndFilterTools();headless 路径会在主入口直接应用 coordinator 工具过滤;worker 工具池由 AgentTool 独立组装,不继承主线程被过滤后的工具池。

5. Worker lifecycle

Coordinator 下 Agent(worker) 会被强制异步: <task-notification> 是 user-role message,但不是用户输入。Coordinator prompt 必须把它当成 worker 结果信号:
<task-notification>
  <task-id>agent-a1b</task-id>
  <status>completed|failed|killed</status>
  <summary>Agent "Investigate auth bug" completed</summary>
  <result>Found null pointer in src/auth/validate.ts:42...</result>
  <usage>
    <total_tokens>N</total_tokens>
    <tool_uses>N</tool_uses>
    <duration_ms>N</duration_ms>
  </usage>
</task-notification>
Coordinator 的关键约束是“综合而不是转发”。worker 看不到用户和 coordinator 的完整对话,所以 prompt 必须自包含:
Fix the null pointer in src/auth/validate.ts:42.
Session.user can be undefined when the session expires but the token remains cached.
Add a null check before user.id access; if null, return 401 with "Session expired".
Run validate.test.ts and report the commit hash.
反模式是:
Based on your findings, fix it.

Coordinator 边界与排错

现象可能原因处理方式
Coordinator 主线程不能读文件或跑命令工具池被过滤,这是预期行为worker,把文件、错误、验收标准写入 worker prompt。
--agent 后 coordinator 行为不一致agent prompt 优先级压过 coordinator prompt,但工具仍可能被过滤避免混用,或确认当前 system prompt 来源。
worker 还在跑但方向错runtime task 仍是 runningTaskStop 停止;会产生 killed notification。
worker 完成但结论不够已经结束的一次性 async agent更推荐 fresh worker;只有需要保留 sidechain 时才 SendMessage 续跑。
SendMessage 失败找不到 agent、缺 sidechain transcript、message 缺 summary查 agentId/name、sidechain .jsonl/.meta.json,plain text message 记得带 summary
coordinator 下没有 workernon-interactive 下禁用了 built-in agents检查 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS

Swarm 完整状态机

Swarm 的核心是团队,而不是一次 Agent 调用。TeamCreate 建 team,Agent({ name }) 加 teammate,TaskCreate/Update/List/Get 提供任务白板,SendMessage 和 mailbox 提供通信与控制。 当前实现默认启用 Agent Teams;设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS_DISABLED 才会关闭。

团队生命周期

关键不变量:
不变量含义
roster 扁平teammate 内禁止再 spawn teammate,避免团队嵌套。
mailbox 按 name 寻址inbox 路径是 teamName + agentName,不是 agentId。
task list 是共享白板TaskCreate 只写 pending task,不启动执行体。
shutdown 不是强杀shutdown request 会交给模型处理,approve 后才 graceful shutdown。
TeamFile 是跨进程事实源AppState.teamContext 是 leader UI 的投影。

存储拓扑

Swarm 的核心状态在 ~/.claude/teams~/.claude/tasks
~/.claude/
  teams/
    <team-name>/
      config.json
      inboxes/
        <agent-name>.json
  tasks/
    <team-name>/
      .highwatermark
      1.json
      2.json
      ...
文件或结构内容
TeamFilenameleadAgentIdleadSessionIdhiddenPaneIdsteamAllowedPathsmembers[]
TeamFile.members[]agentIdnameagentTypemodelcolorbackendTypeisActivemodeworktreePathsessionId
task JSONidsubjectdescriptionactiveFormownerstatusblocksblockedBymetadata
mailbox JSON普通消息、协议消息、已读状态、颜色和摘要等。

TeamCreate 到 teammate 的链路

TeamCreate 不只是写 config.json。它还会注册 session cleanup、重置 team 对应 task list、设置 leaderTeamName,并把 leader 投影到 AppState.teamContext AgentTool 遇到 team_name/current teamContext + name 时走 teammate spawn 分支,不走普通 runAgent()spawnTeammate() 会解析 team、唯一化 name、选择 backend、更新 AppState.teamContext.teammates,再追加 TeamFile.members

in-process vs pane-based teammate

维度in-process teammatepane-based teammate
运行位置leader 同进程独立终端 pane / CLI 进程
启动方式注册 InProcessTeammateTask,启动 runInProcessTeammate()创建 tmux / iTerm2 / Windows Terminal pane
消息消费runner 自己约 500ms poll mailboxleader / teammate 侧 useInboxPoller() 约 1s poll
输入路径teammate view 输入进入 pendingUserMessages普通 mailbox prompt 进入 teammate 进程
处理优先级shutdown > team-lead message > peer message > unowned task claimpoller 按消息类型路由,空闲时自动开一轮
UIspinner tree、footer pills、detail dialog、teammate transcript viewfooter TeamStatus、TeamsDialog、pane 状态
恢复runner、AbortController、pending queue 在内存,进程重启不能完整恢复pane 进程可能还在;leader 侧 backend map 不持久化,恢复是 best-effort
删除需要当前 AppState task / AbortController通过 backend 写 shutdown request,等待 teammate approve / cleanup

AgentTool 分流决策树

AgentTool.call() 是多 Agent 入口最复杂的分叉点。同一个 Agent 工具会根据参数和上下文走不同运行时:
路由触发条件结果
teammatename,且存在 team_name 或当前 teamContextspawnTeammate(),返回 teammate_spawned
remoteisolation: "remote"注册 RemoteAgentTask,本地保存 remote sidecar。
fork省略 subagent_type 且 fork gate/上下文允许强制后台 local agent,继承父上下文和 exact tools。
async local显式 async、Coordinator worker、或自动后台条件满足返回 async_launched,完成后注入 <task-notification>
sync local默认前台一次性 subagent当前 tool call 返回 tool_result
所以文档里不能把“Agent”写成一个单一概念:同一个工具入口下面至少有五条运行路径。

通信路径对照

多 Agent 的通信路径决定了结果是否进入当前 turn、是否持久化、能不能 resume。
通信路径发送者接收者用途持久化/恢复
tool_resultsync subagent当前 assistant turn一次性前台结果写入主 transcript。
<task-notification>async local agent / coordinator worker主线程下一 turn后台完成/失败/被杀通知来自 LocalAgentTask lifecycle 和 sidechain。
SendMessage(to: agentId)Coordinator 或用户local agent task继续 running/stopped workerrunning 时排队;stopped 时尝试 sidechain resume。
SendMessage(to: teammateName)lead / teammateteammate mailboxSwarm 普通通信写 inbox JSON,按 name 寻址。
SendMessage(to: "*")lead / teammateteam membersSwarm broadcast写多个 inbox;structured message 不能 broadcast。
structured mailbox protocollead / teammate / runtime特定 teammate 或 leadpermission、plan、shutdown、mode、task assignment保持 unread 给 poller 路由,不应被普通 attachment 吞掉。
CCR events / pollingremote runtimeRemoteAgentTaskremote agent 状态和结果本地 sidecar + 远端 session 状态。

SendMessage 路由

plain text SendMessage 要带 summary。structured message 不能 broadcast,也不能跨 uds/bridge/tcp session。单 session 下 teammate name 是裸 name,to 不应写成含 @ 的跨域地址。

Mailbox 协议表

Mailbox 路径是:
~/.claude/teams/<team-name>/inboxes/<agent-name>.json
它有 lock、原子 rename、大小上限和压缩策略:
限制
单条 text64KB
mailbox 文件4MB
retained bytes2MB
普通 message 保留最多 1000 条
read message 保留最多 200 条
unread protocol message 保留最多 2000 条
协议消息不只是“聊天”:
消息类型典型发送者典型接收者消费者是否应进入普通 LLM context
plain textlead / teammateteammate / leadmailbox attachment 或 prompt handler
broadcastlead / teammateteam membersmailbox attachment 或 prompt handler
task_assignmentTaskUpdatenew ownerteammate poller / runner通常作为任务触发,不应当成普通闲聊
permission_request/responseteammate / leadlead / teammateuseInboxPoller + permission UI queue
sandbox_permission_request/responseteammate / sandbox hostlead / teammatepermission sync
plan_approval_request/responseteammate / leadlead / teammateplan approval path
shutdown_request/approved/rejectedlead / teammateteammate / leadbackend / runner / poller
mode_set_requestleadteammatepermission mode sync
team_permission_updateleadteam memberspermission sync
idle notificationteammate runnerleadUI / lead poller通常否
一个重要边界:mailbox attachment 只消费非结构化消息;结构化协议消息应保持 unread,交给 useInboxPoller 或 in-process runner 路由。否则权限、plan、shutdown 可能被当成普通上下文吞掉。

Task 不是 Runtime Task

TaskCreate 的 task 和 LocalAgentTask 的 task 是两套模型。
名称源码类型存储状态谁消费
work item tasksrc/utils/tasks.tsTask~/.claude/tasks/<taskListId>/<id>.jsonpending/in_progress/completedTask tools、TaskList UI、teammate 认领
runtime taskTaskStateBase 子类型AppState.tasks,部分有 sidecar/outputrunning/completed/failed/killedUI、spinner、background selector、kill/resume
共享任务生命周期: TaskUpdate 在 Swarm 下有增强:
行为说明
teammate 标记 in_progress 且 owner 为空自动把 owner 设为当前 teammate name。
owner 变化task_assignment 到新 owner mailbox。
status -> completed执行 TaskCompleted hooks。
teammate 完成任务tool result 追加提示:立刻 TaskList 找下一项。
主线程完成 3+ 任务且没有 verification在 feature gate 下追加 verification nudge。
runtime task 类型包括:
类型运行位置典型场景
LocalAgentTask本地子 agent普通后台 agent、fork、coordinator worker。
InProcessTeammateTask同进程 runnerin-process teammate。
RemoteAgentTaskCCR remote sessionremote agent。
LocalShellTask本地 shell后台 shell。
LocalWorkflowTask本地 workflowworkflow 编排。
DreamTask后台静默memory dream。
MonitorMcpTask本地监控MCP monitor。

持久化与恢复矩阵

恢复能力取决于状态放在哪里。最重要的区别是:能看到状态不等于能继续运行。
机制持久化resume 后能看到resume 后能继续跑边界
main session主 session JSONL对话链、metadata、mode是,按主会话恢复受 compact/branch/leaf 影响。
coordinator mode主 session JSONL 的 mode entry当前会话模式是,matchSessionMode() 会切 envprompt/tool 状态仍受当前启动参数影响。
coordinator workerlocal agent sidechain + .meta.jsonagent task 身份和历史通常可 resumeAgentBackground()缺 sidechain/meta 或工具定义变化会失败。
ordinary/fork subagentlocal agent sidechain + .meta.jsonagent 历史可恢复,fork 依赖 agentType:"fork"fork 恢复需要 metadata 正确。
remote agentremote-agents/remote-agent-<taskId>.meta.json + CCRremote task 镜像取决于 CCR session 状态404/archive 会删除 sidecar。
team config~/.claude/teams/<team>/config.jsonteam/member roster不代表 teammate runner 还活TeamFile 是事实源,AppState 是投影。
mailbox~/.claude/teams/<team>/inboxes/*.json未读普通/协议消息可继续投递structured message 需要 poller/runner 正确消费。
shared tasks~/.claude/tasks/<team>/*.jsontask list / owner / status可继续认领/更新owner 可能指向已经不活跃的 teammate。
in-process teammate runnerleader 进程内存不能完整看到 runner 内态不能完整跨进程恢复AbortController、pending queue、recent messages 都在内存。
pane-based teammate外部 pane + transcript + team file可能仍可见best-effortleader 侧 backend map 不持久化,active/kill 依赖 pane 状态。
调试时可以按这个顺序问:
  1. 文件还在吗?
  2. AppState 投影还在吗?
  3. runtime task 还在 running 吗?
  4. 通信通道还可用吗?
  5. sidechain / inbox / remote sidecar 是否足够恢复?

用户可见状态如何投影

UI 展示的是不同状态源的投影,不是单一真相。
UI数据源能说明什么不能说明什么
TaskListV2task files + teamContextwork item task、owner、状态owner 对应 teammate 一定还活。
TeammateSpinnerTreerunning in-process teammates当前 leader 进程内的 teammate 活动pane-based teammate 或历史 teammate 全部状态。
TeammateSpinnerLineInProcessTeammateTaskStateidle、approval、stopping、tool/token、最近消息完整 transcript。
BackgroundAgentSelectorbackgrounded LocalAgentTask可选择的本地后台 agentremote/shell/workflow/in-process teammate。
agent transcript viewviewingAgentTaskIdlocal agent 或 in-process teammate 的可视化对话pane teammate 的完整外部进程状态。
TeamsDialog / TeamStatusAppState.teamContext + team file团队成员展示、管理、kill/shutdown/moderunner 一定可恢复。
pane-based team 主要通过 footer TeamStatus 和 TeamsDialog 管理:Enter 查看,k kill,s shutdown,p prune idle,Shift+Tab 切 permission mode。in-process teammate 的 transcript view 输入会进 pendingUserMessages,不是写 mailbox。

两条端到端场景

复杂 bug 用 Coordinator

步骤发生了什么运行体通信持久化
1用户提出复杂 bug主会话user messagemain JSONL
2Coordinator 拆成调查、实现、验证Coordinator 主线程Agent(worker)main JSONL + task state
3worker 异步执行LocalAgentTasktool callssidechain JSONL
4worker 完成LocalAgentTask<task-notification>notification queue / main turn
5Coordinator 综合 root cause主线程assistant reasoningmain JSONL
6需要修正方向同一个或新 workerSendMessage(to: agentId, summary, message) 或 fresh Agentsidechain / new sidechain
7汇总给用户主线程assistant messagemain JSONL
这个流程没有 TeamCreate,也不依赖 shared task list。

长期并行任务用 Swarm

步骤发生了什么状态源通信
1TeamCreate({ team_name })teams/<team>/config.json + tasks/<team>tool result
2TaskCreate 多个工作项task JSONTask tools
3Agent({ name: "researcher" })TeamFile member + backend task/paneinitial prompt
4teammate 认领任务task JSON owner/statusTaskUpdate
5lead 发消息inbox JSONSendMessage(to: teammateName)
6teammate 完成一轮runner/poller 状态idle notification
7teammate 继续领任务task listTaskList / claim
8TeamDelete({ wait_ms })team/task dirs cleanupshutdown request / response
这个流程里 team、task list 和 mailbox 是核心。teammate 输出不会自动给 lead;需要 SendMessage 或明确的协议消息。

失败与排障矩阵

现象先查什么常见原因处理
Coordinator worker 结果没回来AppState.tasks[agentId]、notification queue、sidechainworker 仍 running、failed、被 killed、notification 尚未进入下一 turn等下一 turn;或看 sidechain / task status。
SendMessage(to: agentId) 找不到 workeragentId/name、sidechain .jsonl/.meta.jsonagent 被 evict、metadata 缺失、传了 teammate name用正确 raw agentId;必要时新开 worker。
SendMessage(to: teammate) 失败teamContext、team file、inbox pathteammate name 拼错、当前 session 无 team、用了含 @ 地址用当前 team 内裸 teammate name。
plain text SendMessage 校验失败参数summarysummary
structured message 没生效inbox read 状态、poller被当普通 attachment 标 read,或 consumer 没跑确认 structured message 保持 unread,poller/runner 活着。
任务不显示leaderTeamNamegetTaskListId()、tasks dirlead/teammate 指向不同 task list查 env/teamName/sessionId 优先级。
task 被认领但没人执行task owner、team member active、runner/paneowner teammate 不活跃或 runner 丢失重新分配 owner,或重启 teammate。
TeamDelete 拒绝清理TeamFile.members[].isActive仍有 active teammate先 graceful shutdown,或确认后手动清理。
resume 后 team 在但 teammate 不跑team file、runner/pane 状态in-process runner 在旧进程内,不能恢复重新 spawn teammate 或用现有 mailbox/task 重新编排。
pane teammate 似乎还在但 UI 不准paneId、backendType、backend mapleader 侧 spawnedTeammates map 不持久化以 TeamFile + pane 实际状态为准,best-effort 管理。
permission/plan 卡住leader inbox、permission UI queue、protocol responseleader poller 没消费,或 response 没写回useInboxPoller 和对应 inbox。
remote agent resume 失败remote sidecar、CCR sessionsession 404 / archived接受 sidecar 清理,重新创建 remote agent。

常见误区

误区正确理解
Coordinator 就是 Swarm 的 Team Lead不是。Coordinator worker 是 async subagent,不是 teammate。
Swarm 必须设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1当前实现默认启用;用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS_DISABLED 关闭。
TaskCreate 创建了一个运行中的 agent它只创建 work item JSON;运行体是 LocalAgentTask / InProcessTeammateTask 等。
teammate 完成一轮后结果自动给 lead不一定。teammate 需要通过 SendMessage 沟通;runner 也会发送 idle notification。
mailbox 按 agentId 寻址Swarm mailbox 按 teammate name 寻址。
BackgroundAgentSelector 会列出所有后台任务它只列 backgrounded LocalAgentTask,不列 remote/shell/workflow/in-process teammate。
TeamUpdate 是一个工具当前源码没有独立 TeamUpdateTool;团队成员更新分散在 spawn、teamHelpers、dialogs 中。
SyntheticOutput 是 Swarm 内部通信工具它主要用于结构化输出,不是 Team 协作核心。
shutdown request 是强杀不是,它是模型处理的 graceful shutdown 协议。
in-process teammate 可以像 local agent 一样跨进程 resume不行,runner 运行态在内存中,进程重启后不能完整恢复。

延伸阅读

这篇文档是跨机制总览。需要深入某条链路时,优先看专题文档:
想深入阅读
AgentTool 参数、sync/async/fork、通知队列docs/agent/sub-agents.mdx
Task V2 数据模型、锁、高水位、owner、hooksdocs/tools/task-management.mdx
JSONL transcript、sidechain、compact、resume、remote sidecardocs/internals/session-transcript-persistence.md
Coordinator feature 的单独说明docs/features/coordinator-mode.md
worktree 隔离docs/agent/worktree-isolation.mdx

源码入口索引

问题从这里看
coordinator mode 检测、恢复、prompt、contextsrc/coordinator/coordinatorMode.ts
/coordinator 命令src/commands/coordinator.ts
coordinator worker 定义src/coordinator/workerAgent.ts
system prompt 选择src/utils/systemPrompt.ts
coordinator 工具过滤src/utils/toolPool.ts
coordinator mode 持久化src/utils/sessionStorage.tsmode entry / saveMode()
AgentTool 路由packages/builtin-tools/src/tools/AgentTool/AgentTool.tsx
subagent query looppackages/builtin-tools/src/tools/AgentTool/runAgent.ts
async local agent lifecyclepackages/builtin-tools/src/tools/AgentTool/agentToolUtils.ts
local agent runtime tasksrc/tasks/LocalAgentTask/LocalAgentTask.tsx
remote agent runtime tasksrc/tasks/RemoteAgentTask/RemoteAgentTask.tsx
agent resumepackages/builtin-tools/src/tools/AgentTool/resumeAgent.ts
task stoppackages/builtin-tools/src/tools/TaskStopTool/TaskStopTool.tssrc/tasks/stopTask.ts
team gatesrc/utils/agentSwarmsEnabled.ts
team file helperssrc/utils/swarm/teamHelpers.ts
TeamCreatepackages/builtin-tools/src/tools/TeamCreateTool/TeamCreateTool.ts
TeamDeletepackages/builtin-tools/src/tools/TeamDeleteTool/TeamDeleteTool.ts
spawn teammatepackages/builtin-tools/src/tools/shared/spawnMultiAgent.ts
in-process teammate spawnsrc/utils/swarm/spawnInProcess.ts
in-process teammate runnersrc/utils/swarm/inProcessRunner.ts
pane backendsrc/utils/swarm/backends/PaneBackendExecutor.ts
teammate AsyncLocalStorage identitysrc/utils/teammateContext.ts
mailboxsrc/utils/teammateMailbox.ts
permission syncsrc/utils/swarm/permissionSync.ts
SendMessage routingpackages/builtin-tools/src/tools/SendMessageTool/SendMessageTool.ts
shared task listsrc/utils/tasks.ts
Task toolspackages/builtin-tools/src/tools/TaskCreateToolTaskUpdateToolTaskListToolTaskGetTool
inbox pollingsrc/hooks/useInboxPoller.ts
swarm initializationsrc/hooks/useSwarmInitialization.ts
teammate viewsrc/state/teammateViewHelpers.tssrc/screens/REPL.tsx
teammate spinnersrc/components/Spinner/TeammateSpinnerTree.tsxTeammateSpinnerLine.tsx
team dialog/statussrc/components/teams/TeamsDialog.tsxsrc/components/teams/TeamStatus.tsx
background local agent selectorsrc/hooks/useBackgroundAgentTasks.tssrc/components/tasks/BackgroundAgentSelector.tsx