team-communication-protocols

用途

本技能提供智能体队友之间有效通信的协议，包括消息类型选择、计划审批工作流、关闭流程以及需要避免的常见反模式。适用于以下场景：为新团队建立通信规范；在消息类型之间做出选择（message、shutdown_request；broadcast 已于 2026 年移除）；处理计划审批工作流；管理团队的优雅关闭；发现队友的身份与能力。

消息类型选择

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"
}

用于：任务更新、协调、提问、集成通知。

broadcast——已于 2026 年移除

broadcast 已于 2026 年从 SendMessageTool 中移除，不再有内置的扇出功能。

要触达多个队友，需按名称逐个发送消息。对于影响所有人的关键共享资源变更（例如更新接口契约），需遍历 ~/.claude/teams/{team-name}/config.json 中的团队配置，并针对每个队友名称发送一条定向消息。

这与旧版 broadcast 的网络开销相同（broadcast 内部本就会展开为 N 条消息），但现在变为显式操作，使协调逻辑可审计。

shutdown_request——优雅终止

请求队友关闭：

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

队友以 shutdown_response 回应（批准，或附带理由拒绝）。

通信反模式

反模式	问题	更好的做法
尝试使用已移除的 broadcast	2026 年起工具会返回错误	每个收件人发送一条消息
发送 JSON 状态消息	并非为结构化数据设计	使用 TaskUpdate 更新任务状态
在集成点不沟通	队友基于过时接口开发	接口就绪时发送消息
通过消息进行微观管理	使队友不堪重负，拖慢工作	在里程碑处检查，而非每一步
使用 UUID 而非名称	难以阅读，容易出错	始终使用队友名称
忽视空闲队友	浪费容量	分配新工作或将其关闭

计划审批工作流

当队友以 plan_mode_required 生成时：

队友使用只读探索工具创建计划
队友调用 ExitPlanMode，向负责人发送 plan_approval_request
负责人审查计划
负责人以 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"
}

关闭协议

优雅关闭序列

负责人向每个队友发送 shutdown_request
队友收到类型为 "shutdown_request" 的 JSON 消息
队友以 shutdown_response 回应：
- approve: true——队友保存状态并退出
- approve: false + 理由——队友继续工作
负责人处理拒绝——等待队友完成，然后重试
所有队友关闭后——调用 TeamDelete 移除团队资源

处理拒绝

如果队友拒绝关闭：

检查其理由（通常是“仍在处理任务”）
等待其当前任务完成
重试关闭请求
如情况紧急，用户可强制关闭

队友发现

通过读取配置文件查找团队成员：

位置：~/.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。

故障排查

队友不回应消息。 检查队友的任务状态。如果处于空闲，可能已完成任务，正在等待分配新工作或被关闭。如果仍处于活动状态，可能正在执行中，会在当前操作完成后处理消息。

队友说看不到 SendMessage。 检查队友 agent 的 tools: frontmatter。当 agent 使用受限工具允许列表时，必须显式列出 SendMessage、TaskList、TaskGet、TaskUpdate 等 Agent Teams 通信工具。

负责人尝试使用 broadcast 并收到工具错误。 broadcast 已于 2026 年从 SendMessageTool 中移除。更新负责人的指令，改为逐个寻址收件人。对于共享资源更新，遍历团队配置并为每个队友名称发送一条消息。

队友意外拒绝了关闭请求。 队友仍在工作。检查 shutdown_response 的 content 字段中的拒绝理由，等待工作完成，然后重试。切勿强制终止有未保存工作的队友。

收到 plan_approval_request 但缺少 request_id。 队友调用 ExitPlanMode 时缺少必需的请求上下文。让队友重新进入计划模式，完成探索，再次调用 ExitPlanMode。request_id 由计划模式系统自动生成。

两个队友互相等待，都没有进展。 这是死锁：双方都阻塞等待对方先完成。负责人应向其中一个队友发送直接消息，附上桩或部分结果，使其解除阻塞并继续。

技能介绍

用途