Cline SDK 多智能体协作：Sub-Agents 与 Teams 两种协调模型的机制、配置与实战

本文基于 Cline SDK 的多智能体参考文档，系统讲解 SDK 提供的两种多智能体工作模式——会话内子代理（Sub-Agents，父子层级）与跨会话团队（Teams，对等协作）：包括各自的启用配置、协调工具集、共享状态与持久化布局，并对照仓库源码剖析工具的实际实现与调用链，帮助你为一次性委托或长期跨会话项目选择合适的协调方案。

两种多智能体模型：Sub-Agents 与 Teams

Cline SDK 支持两种多智能体工作模型：子代理（Sub-Agents） 采用父子层级，父代理在一次运行中派生子代理执行子任务；团队（Teams） 采用对等协作（peer-to-peer），通过任务板、邮箱与任务日志在多个会话之间持续协调。官方参考文档 Multi-Agent Coordination 给出的对比表如下：

特性	Sub-Agents	Teams
启用方式	enableSpawnAgent: true	enableAgentTeams: true
持久化	仅限会话作用域	跨会话持久
协调方式	父子层级	对等协作
共享状态	无	任务板（task board）、邮箱（mailbox）、任务日志（mission log）
适用场景	一次性委托	复杂的多会话项目

从源码结构看，两种模式都收敛于 @cline/core 的工具扩展层：子代理的创建入口在 spawn-agent-tool.ts，团队工具的构建函数与工具名清单在 team-tools.ts，配置项 enableSpawnAgent / enableAgentTeams 定义于 config.ts。

Sub-Agents：会话内的一次性委托

启用 Sub-Agents

子代理由父代理在运行过程中生成，它们独立执行任务并将结果汇报给父代理。启用方式是在会话配置中设置 enableSpawnAgent: true：

const cline = await ClineCore.create({ clientName: "my-app" })

await cline.start({
  prompt: "Refactor the auth module and update tests",
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    enableSpawnAgent: true,
    enableTools: true,
  },
})

子代理工具集

文档列出的子代理工具集如下：

工具	说明
start_subagent	派生一个带任务描述的后台代理
message_subagent	向运行中的子代理发送消息
handoff_to_agent	将当前任务完全移交给某个代理
submit_and_exit	发出完成信号

对照仓库源码可以看到子代理机制的落地细节：

• 实际的派生工具实现在 spawn-agent-tool.ts 中，工具名为 spawn_agent：它接收 systemPrompt 与 task 输入，内部通过 createDelegatedAgent({ kind: "subagent", ... }) 创建一个携带自定义系统提示词、工具集与 maxIterations 上限的委托代理，父代理传入 abortSignal 以在取消时联动终止子代理。
• 会话级的组装入口是 spawn-tool.ts 中的 createSessionSpawnTool：它把父会话的运行时配置（provider、模型、apiKey、hooks、telemetry 等）通过 configProvider 透传给子代理，实现“子代理继承父会话的连接与工具策略”。该文件还实现了 SessionSubAgentLifecycleCallbacks，在子代理 start/end 时分别触发遥测事件（captureSubagentExecution）与后端通知（handleSubAgentStart / handleSubAgentEnd），即子代理的生命周期对可观测体系是可见的。
• 值得注意的一个实现细节：createSubAgentTools 中当 config.enableSpawnAgent 为真时，子代理自身也会再获得一个 spawn 工具（递归 push createSessionSpawnTool），从源码结构看，这意味着 SDK 允许形成多层级代理树，而不只是单层父子关系。

子代理的工作流程

参考文档描述的调用流程为：

1. 父代理判断某个子任务可以委托出去；
2. 调用 start_subagent，传入角色（role）、任务描述，以及可选的预设（preset）；
3. 子代理在后台独立运行；
4. 父代理可查询其状态或发送后续消息；
5. 子代理完成后，其结果对父代理可用。

从 spawn-agent-tool.ts 的实现看，结果回传结构包含 text（输出文本）、iterations（迭代次数）、finishReason（结束原因）以及 usage（token 用量），与主代理的 AgentResult 结构对齐，方便父代理做结果归并。

Teams：跨会话的持久协作

团队为多个代理提供持久的、跨会话的协调能力，共享状态包括任务板、代理间消息与协作日志。

启用 Teams

await cline.start({
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    enableAgentTeams: true,
    teamName: "auth-sprint",
    enableTools: true,
  },
})

在官方指南 Multi-Agent Teams 中，启用团队时通常还会同时设置 enableSpawnAgent: true、systemPrompt（声明协调者角色）与 cwd / workspaceRoot，让协调者拥有完整的工具能力来分派工作。

团队工具集

参考文档列出协调者代理获得的四个核心工具：

工具	说明
team_spawn_teammate	创建带有角色与任务的新代理
team_delegate_task	将任务指派给已有队友
team_check_status	查看已委托任务的进度
team_get_result	获取队友已完成任务的结果

对照仓库源码，team-tools.ts 中导出的 TEAM_TOOL_NAMES 实际暴露了一组更完整的团队工具，可以理解为上述四个概念的当前实现形态：

team_spawn_teammate / team_shutdown_teammate / team_status / team_task
team_run_task / team_cancel_run / team_list_runs / team_await_runs
team_send_message / team_broadcast / team_read_mailbox / team_mission_log
team_cleanup / team_create_outcome / team_attach_outcome_fragment
team_review_outcome_fragment / team_finalize_outcome / team_list_outcomes

源码中有几个与文档表格直接对应的实现事实：

• team_spawn_teammate 要求 agentId 与 rolePrompt 必填，且仅当调用者角色为 lead 时才能创建队友（getMemberRole(requesterId) !== "lead" 会抛出 “Only the lead agent can manage teammates.”），返回值是 { agentId, status: "spawned" }；
• 文档中 team_delegate_task / team_check_status / team_get_result 的“分派、查状态、取结果”职责，在源码中由 team_task（按 action 支持 create / list / claim / complete / block 等任务操作）、team_status（返回成员、任务计数、邮箱与任务日志统计的快照）、team_run_task / team_await_runs / team_list_runs（运行并等待/查询任务）等工具承担；
• team_spawn_teammate 内部调用 spawnTeamTeammate，队友的工具集通过 buildDelegatedAgentConfig({ kind: "teammate", ... }) 构建，且源码注释明确说明“Spawn is lead-only”——不会把 spawn 工具暴露给队友，避免队友在“只有 lead 能管理队友”的拒绝上浪费轮次；
• 团队成员、任务与结果的状态机（租约 leaseOwner、心跳 heartbeatAt、重试计数、进度快照等）由 TeamRunRecord 结构描述，是团队协作状态可恢复、可审计的基础。

团队持久化

参考文档描述团队共享状态的存储布局：

~/.cline/data/teams/[team-name]/
  task-board.json    # 任务分配与状态
  mailbox.json       # 代理间消息
  mission-log.json   # 协作日志

该状态跨会话保留，团队成员可以在新会话中“接着上次继续做”。仓库中团队持久化的构建路径由 runtime-builder.ts 负责（enableAgentTeams / teamName 在此参与运行时组装），并有专门的测试 runtime-builder.team-persistence.test.ts 验证团队状态在会话之间恢复的行为；团队运行时与 AgentTeamsRuntime 相关实现位于 extensions/tools/team 目录内。

通过 CLI 接入团队

cline --team-name auth-sprint "Continue the auth refactor"

CLI 侧对 --team-name 的支持见 team-command.ts，main.ts 会将团队配置传入运行时。官方指南中给出的完整 CLI 用法示例：

# 启动新团队
cline --team-name auth-sprint "Plan and implement user auth with tests"

# 恢复工作
cline --team-name auth-sprint "What's the status? Continue with unfinished tasks."

# 用另一个团队承载不同工作流
cline --team-name perf-sprint "Profile the API endpoints and optimize the slowest 3"

如何选择 Sub-Agents 与 Teams

参考文档给出的选型准则：

使用子代理的场景：

• 需要在单个会话内做一次性并行执行；
• 任务相互独立、彼此不需要通信；
• 结果只对父代理有意义。

使用团队的场景：

• 工作跨越多个会话、持续较长时间；
• 代理之间需要协调并共享进度；
• 任务之间存在依赖关系；
• 希望保留一份多智能体协作的持久记录。

补充一点：官方指南 multi-agent-teams.mdx 同时提醒，团队是有开销的，只有当任务可自然分解为独立子任务、不同子任务需要不同的系统提示词或专业能力、工作跨多个会话或数天时才值得启用；简单场景下单代理加好工具通常更高效。

实战模式

模式一：用子代理做并行研究

父代理同时派生多个子代理研究不同主题，最后汇总结论：

await cline.start({
  prompt: `Research these three topics in parallel:
    1. Current best practices for JWT auth
    2. OAuth 2.0 provider comparison
    3. Session management patterns
    Spawn a sub-agent for each topic, then synthesize the results.`,
  config: {
    enableSpawnAgent: true,
    enableTools: true,
    // ...
  },
})

模式二：团队 Sprint

协调者管理一个跨会话的项目，每次启动时审阅任务板、分派最高优先级任务并跟进在途任务：

await cline.start({
  prompt: `You are the coordinator for the auth-sprint team.
    Review the task board and delegate the next highest-priority task
    to a teammate. Check status on any in-progress tasks.`,
  config: {
    enableAgentTeams: true,
    teamName: "auth-sprint",
    enableTools: true,
    // ...
  },
})

仓库内的 agents-squad 插件示例同时启用了 enableSpawnAgent 与团队能力，可以作为“协调者 + 专职队友”的完整参考实现；SDK 示例总览见 sdk/examples/README.md。

关键源码与延伸阅读

内容	路径
本文对应的参考文档	REFERENCE.md
团队工具实现与工具名清单	team-tools.ts
子代理派生工具	spawn-agent-tool.ts
会话级 spawn 工具与子代理生命周期	spawn-tool.ts
团队持久化测试	runtime-builder.team-persistence.test.ts
CLI 团队命令	team-command.ts
团队官方指南	multi-agent-teams.mdx

延伸阅读（参考文档 See Also 一节，路径已转为仓库根相对路径）：

• ClineCore 运行时 —— 运行时总览
• ClineCore API —— 团队相关的会话配置
• 工具系统
• 插件系统