team-agents

用途

team-agents 是一个用于在 Claude Code 中启动「协调型智能体团队」的技能框架，基于可复用的 TeamCreate / SendMessage / TaskList 模式。当用户输入 /team-agents 时，框架会创建一个团队，拆分带依赖关系的任务，并行派生多个队友智能体，并在结束时汇总报告。

主要能力

团队创建与任务编排：通过 TeamCreate 建立团队，用 TaskCreate 创建任务，并用 TaskUpdate 设置任务依赖（addBlockedBy），实现任务先后顺序。
多层级生成回退：优先使用 Tier 1（tmux 分屏 + 团队框架），其次 Tier 2（进程内团队），仅当预检失败时退回 Tier 3（普通并行子智能体调用）。
心跳协议：要求队友在每次 Bash 调用后，紧接着向 lead 发送 SendMessage，维持 1:1 的 Bash:SendMessage 交替，否则视为协议中断并自中止。
结构化消息与邮箱：提供 10 种结构化消息类型、邮箱（JSON + 文件锁）、权限升级（worker→leader→user）、对已停止智能体发消息可自动恢复、空闲智能体自领任务、确定性 ID（name@team）、计划自动批准、会话恢复等。
状态可见性：通过 /team-agents who 显示存在点（● 活跃、◐ 空闲、◌ 进行中、⊘ 卡住、✓ 完成、✗ 中止、· 静默），并可扫描 tmux 窗格。
生命周期管理：包含创建、派生、等待编译、关闭策略（全量关闭、滚动关闭、定时检查、TeammateIdle 钩子）以及关闭后的邮箱归档、临时技能归档、工作树清扫脚本。

使用方式

基础调用：

/team-agents "review this PR for security, perf, and tests"
/team-agents "refactor auth module" --roles 3
/team-agents "research X" --model haiku
/team-agents "implement feature Y" --plan
/team-agents --manual "build feature Z"
/team-agents --manual "build feature" --worktree

子命令：

/team-agents who                    # presence dots + task state
/team-agents --panes                # tmux pane scan
/team-agents zoom scout             # toggle zoom on agent's pane
/team-agents sync                   # git sync all worktrees to main
/team-agents merge scout            # merge agent's branch to main
/team-agents compile                # gather all reports
/team-agents shutdown               # graceful shutdown
/team-agents cleanup                # kill idle orphan panes
/team-agents killshot               # kill ALL non-lead panes
/team-agents doctor [--fix]         # detect ghosts + orphans

常用标志：--manual（人工通过 lead 中继控制智能体）、--worktree（每个智能体获得独立 git worktree 和分支）、--panes（查看 tmux 窗格）、--plan（计划由 lead 的收件箱轮询器自动批准，是生成门槛而非人工审核）、--roles N（覆盖智能体数量）、--model X（覆盖模型）。

配置要求（Claude Code v2.1.32+）：

// ~/.claude/settings.json — required
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

// ~/.claude.json — display mode (default: "auto")
{ "teammateMode": "in-process" }
{ "teammateMode": "tmux" }

claude --teammate-mode in-process

若环境变量未设置，TeamCreate / SendMessage / TaskList 工具不存在，会退回并行子智能体。进程内模式按键：Shift+Down 循环切换队友，Enter 查看，Escape 中断，Ctrl+T 切换任务。

适用场景

多维度 PR 审查（安全、性能、测试等角色并行）
模块重构
调研任务
功能实现
需要观察到多个智能体同时工作的场景

限制

需要 Claude Code v2.1.32+ 并设置实验性环境变量，否则功能不可用。
无会话恢复：/resume 不会恢复进程内队友。
单会话仅一个团队，嵌套团队不支持，lead 固定不可提升或转移。
权限在派生时设定，所有队友继承 lead 的模式。
分屏窗格需要 tmux/iTerm2，不支持 VS Code/Ghostty。
token 消耗约为单智能体的 3-7 倍。
同一文件会被覆盖，各智能体必须拥有不同文件。
关闭较慢，智能体会先完成当前请求。
结构化消息不能广播，需逐个发送，或用 scripts/broadcast-shutdown.sh $TEAM 自动生成逐智能体消息块。

技能介绍

用途

主要能力

使用方式

适用场景

限制