agents 仓库 agent-teams 插件 /team-shutdown 深度解析：Claude Code 多智能体团队的优雅关闭与资源清理

本文围绕 agents 插件市场（Multi-harness agentic plugin marketplace）中 agent-teams 插件的 /team-shutdown 命令展开，完整讲解其参数解析、三阶段关闭流程（预检、优雅停机、资源清理）、shutdown_request/shutdown_response 消息协议以及拒绝处理与强制关闭策略。读完后，你将能够规范地关闭一个运行中的 Claude Code Agent Team，正确收集各成员的最终结果，并避免进程被强杀导致的未保存工作丢失与残留任务目录。

1. 为什么需要“优雅关闭”：团队生命周期的最后一环

agent-teams 是 agents 仓库中基于 Claude Code 实验性 Agent Teams 特性构建的多智能体编排插件，提供 /team-spawn、/team-status、/team-shutdown、/team-review、/team-debug、/team-feature、/team-delegate 七条命令（见 README.md 的 Commands 表格）。一个团队的完整生命周期由 team-lead 智能体定义 中的 Team Lifecycle Protocol 描述：

1. Spawn — 用 TeamCreate 建队、用 Agent 工具生成队友
2. Assign — 用 TaskCreate/TaskUpdate 创建并分派任务
3. Monitor — 周期性 TaskList 检查、响应队友消息
4. Collect — 收集各队友的产出
5. Synthesize — 合并为统一结论
6. Shutdown — 向每个队友发送 shutdown_request 并等待响应
7. Cleanup — 调用 TeamDelete 移除团队资源

/team-shutdown 正是第 6、7 步的命令行入口。README 的 Best Practices 第 5 条也明确建议：始终使用 /team-shutdown 而不是手动 kill 进程，因为队友可能持有未保存的中间状态，且团队目录（~/.claude/teams/{team-name}/）与任务目录需要一并清理，手动终止既丢工作又留残骸。

2. 命令语法与参数解析

命令定义文件为 team-shutdown.md，其 frontmatter 声明了参数提示：

argument-hint: "[team-name] [--force] [--keep-tasks]"

即命令接受一个可选的团队名和两个可选开关。按文档 Phase 1 的要求，执行时的参数解析规则如下：

• 团队名（位置参数，可选）：若未提供，则执行“与 /team-status 相同的发现逻辑”——检查 ~/.claude/teams/ 目录下是否存在活动团队；若存在多个团队且未指定名称，则列出所有团队并请用户选择。这一发现逻辑在 team-status.md 中有完整对照说明；
• --force：跳过对优雅关闭响应的等待，即不再等队友确认，直接走清理；
• --keep-tasks：清理后保留任务列表，不清除 ~/.claude/tasks/{team-name}/。

典型的三种调用形态：

/team-shutdown                      # 自动发现活动团队并优雅关闭
/team-shutdown review-team           # 关闭指定团队
/team-shutdown review-team --force --keep-tasks   # 强制关闭并保留任务记录

3. Phase 1：预关闭检查（Pre-Shutdown）

预检阶段的目标是在发出任何关闭请求之前确认当前状态，避免在任务执行中途贸然停机。按 team-shutdown.md 的步骤：

1. 解析 $ARGUMENTS，得到团队名与 --force、--keep-tasks 标志；
2. 使用 Read 工具读取团队配置 ~/.claude/teams/{team-name}/config.json；
3. 调用 TaskList 检查是否存在进行中的任务；
4. 若存在进行中任务且未设置 --force，执行保护性确认：
   • 显示警告：Warning: {N} tasks are still in progress
   • 列出这些进行中的任务
   • 询问用户：Proceed with shutdown? In-progress work may be lost.

其中第 4 步是该命令最重要的安全闸门：它把“是否可能丢失工作”的判断权交给用户，只有显式 --force 或用户确认才会继续。这与 agent 侧的拒绝机制（见第 5 节）共同构成双保险。

3.1 config.json 的团队成员结构

config.json 是团队成员发现（Teammate Discovery）的唯一来源。team-communication-protocols 技能 给出了其结构：

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

一个直接影响关闭行为的关键约定：所有消息必须使用成员的 name 字段，而不是 agentId（UUID）。若队友因名称冲突被生成了带后缀的名字（如 team-lead-2），也必须使用带后缀的实际名字进行寻址（该约定同时出现在 team-lead.md 的 Communication Protocols 与 team-spawn.md 的 Phase 2 中）。/team-shutdown 在 Phase 2 逐一点名发送 shutdown_request 时，寻址正确性直接决定关闭请求能否送达。

4. Phase 2：优雅关闭协议（Graceful Shutdown）

预检通过后，命令对团队中的每一个队友执行如下序列（team-shutdown.md）：

1. 通过 SendMessage 发送 type: "shutdown_request" 的关闭请求，消息内容固定为：

   "Team shutdown requested. Please finish current work and save state."

2. 等待各队友的关闭响应：
   • approve — 标记该成员为已关闭；
   • reject — 连同拒绝原因一并报告给用户；
   • 若设置了 --force，则不等待任何响应，直接进入清理阶段。

这里的 shutdown_request 是 agent 间消息协议中的一等消息类型。team-communication-protocols 技能 给出了消息示例：

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

与之配套的完整 Shutdown Protocol（SKILL.md）共 5 步：

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

队友侧收到请求后，除了返回 shutdown_response，还可以按 messaging-patterns.md 中的 Shutdown Acknowledgment 模板发送一条最终状态消息，把收尾情况交代清楚：

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

Ready for shutdown.

这条“最终状态”正是命令描述中所说的 “collect final results” 的载体——它让主会话在清理前掌握每个成员改了哪些文件、还有哪些未完成的活。

5. 拒绝处理与 --force 的边界

当某个队友拒绝关闭（approve: false）时，协议给出的处理路径是（SKILL.md）：

• 查看拒绝原因（通常是 "still working on task"）；
• 等待其当前任务完成；
• 重试关闭请求；
• 若情况紧急，用户可改用强制关闭（对应命令的 --force 标志）。

技能的 Troubleshooting 部分对此还有一句强约束：永远不要强制终止持有未保存工作的队友（"Never force-terminate a teammate that has unsaved work"，见 SKILL.md）。因此 --force 的正确使用场景是：队友已拒绝但工作已确认收尾、或队友失联且用户确认可以放弃其未保存状态——由用户在 Phase 1 的确认提示中显式承担这一风险。

6. Phase 3：清理与关闭摘要（Cleanup）

清理阶段（team-shutdown.md）包含三个动作：

（1）显示关闭摘要，格式固定为：

Team "{team-name}" shutdown complete.

Members shut down: {N}/{total}
Tasks completed: {completed}/{total}
Tasks remaining: {remaining}

三行数字分别回答：成员关闭是否完整、任务完成了多少、还剩多少任务。若 Members shut down 小于总数（例如被强制关闭），或 Tasks remaining 大于 0，用户即可从摘要中判断本次关闭是完整收尾还是带损停机。

（2）删除团队资源：除非设置了 --keep-tasks，否则调用 TeamDelete 移除团队与任务目录。

（3）--keep-tasks 分支：若设置了该标志，则提示用户任务列表已保留在 ~/.claude/tasks/{team-name}/。这对需要事后审计“团队到底做到哪一步”的场景很有用——团队本身销毁了，但任务清单（含状态、负责人、依赖）仍可回溯。

7. 故障排查：关闭流程中常见的三类问题

技能文档的 Troubleshooting 一节（SKILL.md）列出了与关闭直接相关的两类，外加一条工具可用性前提：

现象	原因与处理
队友不响应关闭请求	先查其任务状态。若处于 idle，可能已完成任务、正等待新任务或关闭指令；若仍在活动，可能正处于操作执行中段，会在当前操作结束后处理消息。不要立即断定其失联。
队友意外拒绝关闭请求	说明它仍在工作。读取 shutdown_response 的 content 字段确认原因，等其完成后重试。技能明确要求：对有未保存工作的队友不得强制终止。
队友表示看不到 SendMessage	检查该 agent 定义 frontmatter 中的 tools: 白名单。Agent Teams 的通信工具（SendMessage、TaskList、TaskGet、TaskUpdate）在受限制的工具列表下必须显式列出——否则该成员既收不到关闭请求，也无法回报 shutdown_response。本插件的 team-lead.md 与 team-reviewer.md 都已在 frontmatter 中显式声明这些工具，可作为对照。

8. 与团队生命周期其他命令的衔接

/team-shutdown 不是孤立动作，它和另外两条命令构成完整的监控—收尾闭环：

• /team-status：共享同一套团队发现逻辑（检查 ~/.claude/teams/、读取 config.json、调用 TaskList），输出成员表与任务表。在关闭前先跑一次 /team-status，可以提前确认哪些任务处于 in_progress，从而判断是否需要 --force 或先等任务收尾。--keep-tasks 保留的任务目录也正是 TaskList 的数据来源。
• /team-spawn：其输出末尾明确指引了收尾方式——"Use /team-shutdown to clean up"（见 team-spawn.md），保证团队从创建到销毁都经由插件的受控协议而非手工操作。

另外提醒适用前提：整个 agent-teams 插件依赖 Claude Code 的实验特性，需要设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，并在 ~/.claude/settings.json 中配置 teammateMode（tmux / iterm2 / in-process，详见 README.md 的 Setup 一节）。/team-spawn 的 Pre-flight Checks 会先校验该标志；同理，若团队根本尚未创建，/team-shutdown 的发现阶段也找不到任何 ~/.claude/teams/ 条目。

9. 实战要点小结

• 默认走优雅路径：不带标志的 /team-shutdown 会逐成员请求确认并等待响应，是日常首选；
• --force 是有代价的开关：它跳过后，摘要中的 Members shut down 可能小于总数，未保存状态不保证保留，仅在用户确认接受该风险时使用；
• --keep-tasks 服务于事后审计：关闭后保留 ~/.claude/tasks/{team-name}/，便于核对 Tasks remaining 对应的具体任务；
• 关闭前先 /team-status：用共享的发现逻辑确认进行中任务与成员状态，比盲发关闭请求更可控；
• 寻址只用 name：从 config.json 的 members 列表取实际（可能带后缀的）名字，不用 UUID、不用角色别名——这是 shutdown_request 能被正确送达的前提；
• 保持小团队：README 建议 2–4 名队友为宜，成员越多，优雅关闭需要等待确认的往返越多，收尾时间也越长。

综上，/team-shutdown 把一个看似简单的“关掉团队”动作拆解为预检、协商、清理三个阶段，用 shutdown_request/shutdown_response 协议保证每个成员有机会保存状态，用 Phase 1 的用户确认与 Phase 3 的关闭摘要保证结果可核验，并通过 --force 与 --keep-tasks 两个开关覆盖紧急停机与事后审计两类特殊场景。

关键文件索引：team-shutdown.md（命令定义）、team-status.md（团队发现与状态输出）、team-spawn.md（团队创建与收尾指引）、team-communication-protocols/SKILL.md（关闭协议与故障排查）、messaging-patterns.md（关闭确认消息模板）、team-lead.md（生命周期协议）、README.md（插件总览与最佳实践）。