agents 插件市场的 agent-teams 通信协议：消息类型选择、计划审批与优雅停机实践

本文围绕 agent-teams 插件的 team-communication-protocols 技能 展开，讲解 Claude Code 实验性 Agent Teams 功能下，多 Agent 团队之间如何选择消息类型（message / broadcast / shutdown_request）、如何执行"计划先审批再开工"的工作流、以及如何在任务全部完成后优雅关闭团队。读完本篇，你可以为新组建的 Agent 团队制定一套可落地的通信规范，并掌握计划审批、优雅停机、死锁排查与队友发现等关键操作。

背景：Agent Teams 的通信工具集

agent-teams 是 agents 插件市场 中基于 Claude Code 实验性 Agent Teams 功能构建的多智能体编排插件，内置 team-lead、team-reviewer、team-debugger、team-implementer 四类角色。要让这些 Agent 真正"协作"而不是各干各的，前提是一套结构化的通信协议——这正是本技能（team-communication-protocols，版本 1.0.2）要解决的问题。

启用该功能的前提（以 插件 README 为准）：

1. 设置实验特性开关：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

2. 在 ~/.claude/settings.json 中配置队友展示模式：

{
  "teammateMode": "tmux"
}

可用展示模式有三种："tmux"（每个队友一个 tmux 窗格，推荐）、"iterm2"（macOS 专属）、"in-process"（默认，同进程运行）。

安装路径为：

/plugin marketplace add wshobson/agents
/plugin install agent-teams@claude-code-workflows

从源码结构看，整个插件的通信能力由一组工具支撑：SendMessage（发送消息）、TaskList / TaskGet / TaskUpdate（任务状态管理）、TeamCreate / TeamDelete（团队资源生命周期）、ExitPlanMode（退出计划模式并触发审批请求）。team-lead 角色定义 的 frontmatter 中就显式列出了这套工具：Read, Glob, Grep, Bash, Agent, TeamCreate, TeamDelete, TaskCreate, TaskList, TaskGet, TaskUpdate, SendMessage。

技能适用场景

原技能文档将"何时使用"归纳为五类场景：

• 为新组建的团队建立通信规范；
• 在消息类型（message、broadcast、shutdown_request）之间做选择；
• 处理计划审批（plan approval）工作流；
• 管理团队的优雅停机（graceful shutdown）；
• 发现队友的身份与能力（teammate discovery）。

下面按"发消息 → 定规矩 → 审计划 → 关团队 → 找队友"的脉络逐一展开。

消息类型选择

message（点对点消息）——默认选择

发送给单个指定队友，用于任务更新、协调、提问、集成点通知等日常沟通：

{
  "type": "message",
  "recipient": "implementer-1",
  "content": "Your API endpoint is ready. You can now build the frontend form.",
  "summary": "API endpoint ready for frontend"
}

这是插件各处实际使用的默认类型。例如 team-delegate 命令 在执行 --assign 和 --message 动作时，都是先用 TaskUpdate 设置任务归属，再用 SendMessage 且 type: "message" 通知对应成员；team-implementer 角色 的"集成点"一节也要求：自己的接口一侧就绪后，要发消息通知对端队友。

broadcast（广播）——务必克制使用

同时发送给所有队友：

{
  "type": "broadcast",
  "content": "Critical: shared types file has been updated. Pull latest before continuing.",
  "summary": "Shared types updated"
}

仅用于：影响所有人的关键阻塞，或共享资源发生重大变更。

为什么必须克制？因为每条广播实际会发出 N 条独立消息（每个队友一条），API 资源消耗与团队规模成正比。team-lead 角色的行为规范 也把它写成了一条硬性规则："Use broadcast only for critical team-wide announcements"（广播只用于影响全团队的关键通告）。

shutdown_request（优雅停机请求）

请求某个队友关闭：

{
  "type": "shutdown_request",
  "recipient": "reviewer-1",
  "content": "Review complete, shutting down team."
}

队友收到后会以 shutdown_response 应答——approve: true 表示保存状态并退出，approve: false 并附带理由表示继续工作。这个"请求—应答"的握手机制是后续停机协议的基础，详细流程见下文。

六类通信反模式

原技能文档用一张表总结了最常见的通信错误。这张表与 team-lead 的"Communication Protocols"规则 高度一致（例如"永远不要用结构化 JSON 状态消息——用 TaskUpdate 代替""用实际派生的 NAME 称呼队友，永远不用 UUID 或角色别名"），可以视为角色定义对技能协议的落地执行：

反模式	问题	更好的做法
广播例行更新	浪费资源、制造噪音	点对点消息发给相关队友
发送 JSON 状态消息	消息通道不是为结构化数据设计的	用 TaskUpdate 更新任务状态
集成点不沟通	队友基于过时的接口开发	你的接口就绪时立即发消息
用消息微观管理	淹没队友、拖慢工作	在里程碑处检查，而不是每一步都查
用 UUID 而不是名字	难以阅读、易出错	始终使用队友名字
忽视空闲队友	浪费算力	分配新任务或将其关闭

其中"用消息微观管理"这一条还与 team-lead 的行为特征 相呼应："Monitors progress without micromanaging — checks in at milestones, not every step"（监控进度但不微观管理——在里程碑处检查，而非每一步）。

常用消息模板

技能目录下附带了 references/messaging-patterns.md，提供 7 类即拿即用的消息模板，可直接套用到上述 type: "message" 的 content 字段中。

任务分派（Task Assignment）：

You've been assigned task #{id}: {subject}.

Owned files:
- {file1}
- {file2}

Key requirements:
- {requirement1}
- {requirement2}

Interface contract:
- Import {types} from {shared-file}
- Export {types} for {other-teammate}

Let me know if you have questions or blockers.

集成点就绪通知（Integration Point Notification）：

My side of the {interface-name} interface is complete.

Exported from {file}:
- {function/type 1}
- {function/type 2}

You can now import these in your owned files. The contract matches what we agreed on.

阻塞上报（Blocker Report）：

I'm blocked on task #{id}: {subject}.

Blocker: {description of what's preventing progress}
Impact: {what can't be completed until this is resolved}

Options:
1. {option 1}
2. {option 2}

Waiting for your guidance.

任务完成报告（Task Completion Report）：

Task #{id} complete: {subject}

Changes made:
- {file1}: {what changed}
- {file2}: {what changed}

Integration notes:
- {any interface changes or considerations for other teammates}

Ready for next assignment.

评审结论摘要（Review Finding Summary）：

Review complete for {target} ({dimension} dimension).

Summary:
- Critical: {count}
- High: {count}
- Medium: {count}
- Low: {count}

Top finding: {brief description of most important finding}

Full findings attached to task #{id}.

调查结论摘要（Investigation Report Summary）：

Investigation complete for hypothesis: {hypothesis summary}

Verdict: {Confirmed | Falsified | Inconclusive}
Confidence: {High | Medium | Low}

Key evidence:
- {file:line}: {what was found}
- {file:line}: {what was found}

{If confirmed}: Recommended fix: {brief fix description}
{If falsified}: Contradicting evidence: {brief description}

Full report attached to task #{id}.

停机前的最终状态汇报（Shutdown Acknowledgment）：收到停机请求后应通过 shutdown_response 工具应答，但也可以先补发一条最终状态消息：

Wrapping up. Current status:
- Task #{id}: {completed/in-progress}
- Files modified: {list}
- Pending work: {none or description}

Ready for shutdown.

这些模板与角色的文件所有权协议是配套的：team-implementer 要求"只改自己名下的文件、接口契约不可擅自变更、有疑问先问 lead"，因此任务分派模板中才会同时写明 Owned files 与 Interface contract。

计划审批工作流

当队友以 plan_mode_required 参数派生（spawn）时，必须先出方案、获批后才能动手。完整流程如下：

1. 队友使用只读探索工具（Grep、Read 等）制定计划；
2. 队友调用 ExitPlanMode，系统向 lead 发送一条 plan_approval_request；
3. lead 审阅计划；
4. lead 回复 plan_approval_response：

批准：

{
  "type": "plan_approval_response",
  "request_id": "abc-123",
  "recipient": "implementer-1",
  "approve": true
}

驳回并附反馈：

{
  "type": "plan_approval_response",
  "request_id": "abc-123",
  "recipient": "implementer-1",
  "approve": false,
  "content": "Please add error handling for the API calls"
}

注意 request_id 的作用：它是审批请求与响应之间的关联键，由计划模式系统自动生成。技能文档的故障排查一节特别指出，如果收到的 plan_approval_request 缺少 request_id，说明队友调用 ExitPlanMode 时没有携带必要的请求上下文，应让队友重新进入计划模式、完成探索后再调用一次。

这套审批流程对应插件的 --plan-first 使用习惯：README 的快速上手 给出的并行开发示例即 /team-feature "Add user authentication with OAuth2" --team-size 3 --plan-first，先让 lead 拆解出带文件所有权边界的工作流并取得批准，再派生 implementer 并行开工。

停机协议：从 shutdown_request 到 TeamDelete

优雅停机五步序列

1. lead 向每个队友发送 shutdown_request；
2. 队友以 JSON 消息形式收到 type: "shutdown_request" 请求；
3. 队友回复 shutdown_response：
   • approve: true——队友保存状态并退出；
   • approve: false + 理由——队友继续工作；
4. lead 处理拒绝——等待队友完成当前工作后重试；
5. 所有队友退出后——调用 TeamDelete 移除团队资源。

如何处理拒绝

若队友拒绝停机：查看拒绝理由（通常是"仍在处理任务"）→ 等待其当前任务完成 → 重新发起停机请求；紧急情况下用户可强制关闭。

技能文档的故障排查一节补了一条安全底线："Never force-terminate a teammate that has unsaved work"——永远不要对尚有未保存工作的队友强制终止。

命令层实现：/team-shutdown

上述协议在插件中的具体实现是 team-shutdown 命令，参数签名为 [team-name] [--force] [--keep-tasks]，分三个阶段执行：

阶段 1：停机前检查

• 解析参数（无团队名时自动探测活动团队；--force 跳过等待优雅应答；--keep-tasks 在清理后保留任务列表）；
• 用 Read 工具读取 ~/.claude/teams/{team-name}/config.json；
• 调用 TaskList 检查是否存在进行中的任务；
• 若存在进行中任务且未加 --force，输出警告 "Warning: {N} tasks are still in progress"，列出任务并询问用户："Proceed with shutdown? In-progress work may be lost."

阶段 2：优雅停机

对团队中每个队友，使用 SendMessage 且 type: "shutdown_request" 请求优雅关闭，附带内容 "Team shutdown requested. Please finish current work and save state."，然后等待应答：批准则标记为已关闭；拒绝则把理由报告给用户；--force 时不等待应答。

阶段 3：清理

输出停机摘要（成员关闭数 N/total、任务完成数、剩余任务数），除非设置了 --keep-tasks，否则调用 TeamDelete 删除团队与任务目录；若设置了 --keep-tasks，则提示 "Task list preserved at ~/.claude/tasks/{team-name}/"。

可以看到，命令的三个阶段与技能文档的"五步序列 + 拒绝处理"是一一对应的：阶段 1 对应"停机前检查"，阶段 2 即请求—应答握手，阶段 3 对应最后一步 TeamDelete。README 的最佳实践 也强调：始终使用 /team-shutdown 而不是手动杀进程。

队友发现：读 config.json 而不是猜名字

要发消息或分派任务，先得知道队友叫什么。技能的规则是读取配置文件：

位置：~/.claude/teams/{team-name}/config.json

结构：

{
  "members": [
    {
      "name": "security-reviewer",
      "agentId": "uuid-here",
      "agentType": "team-reviewer"
    },
    {
      "name": "perf-reviewer",
      "agentId": "uuid-here",
      "agentType": "team-reviewer"
    }
  ]
}

关键纪律：发消息和分派任务一律使用 name，绝不使用 agentId、角色名或无后缀的别名。如果某队友因重名被派生为 team-lead-2，就必须发往 team-lead-2 而不是 team-lead。

这条规则在 team-spawn 命令 中有更完整的解释：团队创建可能保留形如角色名的名字，因此不得用 team-lead 这类角色名作为成员名，应使用唯一、有描述性的名字（如 "fullstack-lead"、"frontend-impl"），并始终以 Agent 工具返回的实际名字或 config.json 中列出的名字为准。派生时使用的 subagent_type 取值包括 agent-teams:team-lead、agent-teams:team-implementer、agent-teams:team-reviewer、agent-teams:team-debugger，研究场景则用 general-purpose。

team-status 命令 同样以"读取 config.json + 调用 TaskList"作为团队发现的标准路径，其成员表输出即按 Name / Role / Status 三列呈现——Role 一列展示的正是 config.json 中的 agentType。

故障排查

技能文档内置了六个高频故障的定位方法，均可直接用于线上排障：

1. 队友不回复消息。 先查该队友的任务状态。若处于 idle，可能已完成任务、在等待新工作或被关闭；若仍活跃，则可能正处于操作执行中，当前操作结束后会处理消息。

2. 队友表示看不到 SendMessage。 检查该队友 Agent 定义的 tools: frontmatter。当 Agent 使用受限工具白名单时，Agent Teams 的通信工具——SendMessage、TaskList、TaskGet、TaskUpdate——必须在白名单中显式列出。对照 team-lead 与 team-implementer 的 frontmatter 可见，两个角色都完整列出了这四个工具，这正是白名单写法应当达到的效果。

3. lead 对每次状态更新都发广播。 常见反模式。广播昂贵——每条广播实际发出 N 条消息。点对点更新一律使用 type: "message"，广播只留给共享资源的关键变更（例如接口契约更新）。

4. 队友意外拒绝了停机请求。 说明它还在干活。查看 shutdown_response 的 content 字段中的拒绝理由，等工作结束后重试，切勿对有未保存工作的队友强制终止。

5. 收到 plan_approval_request 但缺少 request_id。 队友调用 ExitPlanMode 时没有携带所需请求上下文。让队友重新进入计划模式、完成探索、再次调用 ExitPlanMode；request_id 由计划模式系统自动生成。

6. 两个队友互相等待、双双停滞。 这是死锁：双方都在等对方先完成。解法是由 lead 向其中一方发送点对点消息，提供一个 stub 或部分结果，使其解阻塞后继续推进。

与团队生命周期的衔接

把本篇协议放回 team-lead 定义的生命周期 中看，其位置非常清晰：

1. Spawn——TeamCreate 建队，Agent 工具派生队友（见 team-spawn 命令 的七种预设：review / debug / feature / fullstack / research / security / migration）；
2. Assign——TaskCreate 建任务、TaskUpdate 分派（配套模板即"任务分派"消息模板）；
3. Monitor——定期 TaskList、响应队友消息（配套 team-status、team-delegate 命令，后者支持 --rebalance 识别空闲/过载成员并给出再平衡建议）;
4. Collect / Synthesize——汇总各队友产出并生成合并报告；
5. Shutdown——逐个发送 shutdown_request 并等待应答；
6. Cleanup——调用 TeamDelete 释放资源。

通信协议贯穿其中：集成点就绪用 message 通知、任务状态用 TaskUpdate 更新、共享契约变更才用 broadcast、开工前的方案争议用计划审批、收尾用停机握手。

相关技能

• team-composition-patterns——在确立通信规范之前，先完成 Agent 类型与团队规模的选择；
• parallel-feature-development——利用上述通信协议协调并行 implementer 之间的集成交接。