agents24 仓库 Agent Teams 插件实战:详解 /team-status 命令的团队成员、任务状态与进度监控

在 Agent Teams 插件 中,/team-status 是观察一个运行中多 Agent 团队的核心窗口:它解析团队名与过滤参数、从本地团队配置目录读取成员清单、调用 TaskList 拉取任务状态,并以成员表、任务表或原始 JSON 三种形式呈现团队进度。读完本文,你将掌握 /team-status 的完整参数用法与输出格式、它依赖的 ~/.claude/teams/{team-name}/config.json 配置结构,以及如何在 task-coordination-strategies 技能指导下基于状态输出做负载不均诊断与任务再平衡。

前置环境:Agent Teams 是实验特性

/team-status 依赖 Claude Code 的实验性 Agent Teams 功能,使用前必须完成 README 中列出的两项设置:

1. 启用实验特性标志:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

2. 在 ~/.claude/settings.json 中配置 teammate 显示模式:

{
  "teammateMode": "tmux"
}

可选显示模式有三种:"tmux"(每个 teammate 运行在一个 tmux 窗格中,推荐)、"iterm2"(每个 teammate 一个 iTerm2 标签页,仅 macOS)、"in-process"(teammate 与主会话同进程,默认)。插件本身通过 /plugin install agent-teams@claude-code-workflows 安装。

命令签名与参数:解析 $ARGUMENTS

命令文件 team-status.md 的 frontmatter 声明了参数提示:

argument-hint: "[team-name] [--tasks] [--members] [--json]"

Phase 1(Team Discovery)要求 Agent 先解析 $ARGUMENTS,规则如下:

• 团队名 — 若显式提供则直接使用;若未提供,检查 ~/.claude/teams/ 目录下的活跃团队;若存在多个团队且未指定名字,则列出全部团队并请用户选择;
• --tasks — 只显示任务详情;
• --members — 只显示成员详情;
• --json — 输出原始 JSON 而不是格式化表格。

解析完成后,状态收集分两步:

1. 使用 Read 工具读取 ~/.claude/teams/{team-name}/config.json 获取团队配置;
2. 调用 TaskList 工具获取当前任务状态。

这个「配置读文件 + 状态读工具」的两源设计值得注意:config.json 回答「团队由谁组成」,而 TaskList 回答「现在进行到哪一步」。前者是静态结构信息,后者是动态运行信息,两者合起来才构成完整的团队状态视图。

团队成员的发现机制:config.json 结构

config.json 是 Agent Teams 的持久化目录,/team-status 以及 /team-delegate、/team-shutdown 等命令都以它为成员发现的唯一入口。team-communication-protocols 技能 给出了它的结构:

{
  "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 这类角色名作为 spawn 出的成员名,团队创建过程可能占用角色化名称,应使用 Agent 工具实际返回的名字,并始终以 config.json 中列出的名字为准。

这意味着在 /team-status 的成员表中,看到的名字就是后续 /team-delegate --assign、SendMessage 应当使用的名字——状态输出实际上兼任了「身份注册表」的角色。

成员表输出:Name / Role / Status 三列

Phase 2(Members Table)要求为每个团队成员展示当前状态,格式如下(摘自 team-status.md):

Team: {team-name}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Members:
  Name              Role              Status
  ─────────────────────────────────────────
  security-rev      team-reviewer     working on task #2
  perf-rev          team-reviewer     idle
  arch-rev          team-reviewer     working on task #4

三列的语义:

列	来源	含义
Name	config.json 的 members[].name	成员唯一标识,后续消息/指派必须使用
Role	config.json 的 members[].agentType	该成员对应的 Agent 类型(如 team-reviewer)
Status	TaskList 实时推导	working on task #N 或 idle

Status 列是「计算」出来的字段:成员名下若有 in_progress 任务则标记为 working on task #N,否则标记为 idle。这与 task-coordination-strategies 技能 中的负载监控指标直接对应——「Teammate idle, others busy」即负载不均信号,「Teammate stuck on one task」即潜在阻塞信号。也就是说,/team-status 的成员表本身就是工作负载再平衡的判断依据。

插件提供的四种角色(team-lead、team-reviewer、team-debugger、team-implementer)分别对应编排者、多维度评审者、假设调查者和文件归属受限的并行实现者,详见 README 的 Agents 表。其中 team-reviewer 的 frontmatter 还展示了 tools: Read, Glob, Grep, Bash, TaskList, TaskGet, TaskUpdate, SendMessage 这样的受限工具白名单——这提醒我们,如果自定义 Agent 使用受限工具列表,TaskList、TaskGet、TaskUpdate、SendMessage 必须显式列入,否则成员既无法更新任务状态,也无法被 /team-status 的推导正确反映(该技能在 Troubleshooting 一节专门列出了这一故障模式)。

任务表输出:状态、负责人、依赖与进度百分比

任务表(Tasks Table)展示每个任务的状态、负责人与主题,示例如下:

Tasks:
  ID   Status        Owner           Subject
  ─────────────────────────────────────────────────
  #1   completed     security-rev    Review auth module
  #2   in_progress   security-rev    Review API endpoints
  #3   completed     perf-rev        Profile database queries
  #4   in_progress   arch-rev        Analyze module structure
  #5   pending       (unassigned)    Consolidate findings

Progress: 40% (2/5 completed)

任务状态的取值与 task-coordination-strategies 技能 中的 blockedBy/blocks 依赖体系一致,任务依赖用 TaskCreate + TaskUpdate: { taskId: "3", addBlockedBy: ["1", "2"] } 建立。从源码结构看,任务表还承载了依赖诊断职责:示例中 #5 Consolidate findings 处于 pending (unassigned) 状态,典型的阻塞场景——它需要等 #2、#4 两个 in_progress 任务完成。team-delegate 命令 的 Delegation Dashboard 也专门设有 "Blocked Tasks" 区块(如 #6 Blocked by #4 (in_progress, owner: implementer-1)),两者共用同一份 TaskList 数据源。

Progress 行的计算规则从示例可直接读出:Progress: 40% (2/5 completed) 即「completed 任务数 ÷ 总任务数」,向下取整到 10% 粒度。这个百分比只统计 completed,不含 in_progress,因此在任务收尾阶段会显得偏保守。

--json 模式:面向脚本与自动化的原始输出

设置 --json 时,命令不渲染表格,而是直接输出原始团队配置与任务列表的 JSON。这一模式的实际价值在于:

• 可被外部工具消费 — 状态解析不再依赖对表格对齐的脆弱正则,便于写 CI 步骤或本地脚本判断「团队是否卡住」;
• 字段保真 — config.json 中的 agentId、agentType 与 TaskList 的完整任务字段都原样保留,格式化表格会丢弃这些细节;
• 与其他命令串联 — /team-delegate --assign task-id=member-name 和 /team-shutdown 同样读取同一份 config 与 TaskList,JSON 输出可以作为它们的输入依据。

状态监控在团队工作流中的位置

/team-status 并非孤立命令,它是 team-lead Agent 的生命周期协议 中「Monitor」环节的用户侧入口。team-lead 的 Team Lifecycle Protocol 将团队生命周期分为七步:Spawn(TeamCreate + Agent 工具)→ Assign(TaskCreate/TaskUpdate)→ Monitor(定期 TaskList,响应成员消息) → Collect → Synthesize → Shutdown(逐个发送 shutdown_request)→ Cleanup(TeamDelete)。README 的最佳实践第 4 条明确建议「Monitor with /team-status — Check progress regularly and use /team-delegate --rebalance if work is uneven」,第 6 条建议保持 2–4 人的小规模团队。

基于 /team-status 输出,推荐的诊断—处置闭环是:

1. 运行 /team-status(或 /team-status <team> --json)读取成员与任务两表;
2. 对照负载不均信号表(idle、stuck、blocked、单成员 3 倍负载)识别问题;
3. 若存在不均,运行 /team-delegate --rebalance,它会统计每位成员的 in_progress + pending assigned 任务数,标记 0 任务为 idle、3+ 任务为 overloaded,并生成迁移建议(如 "Move task #5 from implementer-1 to implementer-3"),经用户确认后通过 TaskUpdate + SendMessage 执行;
4. 全部任务完成或需提前结束时,使用 /team-shutdown 优雅收尾,而不是手动杀进程;--force 可跳过等待、--keep-tasks 可在清理后保留 ~/.claude/tasks/{team-name}/ 下的任务清单供事后复盘。

小结

/team-status 的全部技术面可以归纳为一条数据流:解析 [team-name] [--tasks] [--members] [--json] → 读取 ~/.claude/teams/{team-name}/config.json 获得成员结构 → 调用 TaskList 获得任务动态 → 渲染成员表(Name/Role/Status)、任务表(ID/Status/Owner/Subject + Progress)或原始 JSON。它的关键约束在于:成员身份一律以 config.json 中的 name 为准(冲突时带后缀);状态字段由任务推导而来,因此任务白名单(TaskList/TaskGet/TaskUpdate 等)是否配置在 Agent 的 tools 里,直接决定了状态与协调链路的可用性。理解了这条数据流,再配合 /team-delegate --rebalance 与 /team-shutdown,即可覆盖从「观察」到「干预」再到「清理」的多 Agent 团队运维全链路。