Agent Team Orchestration - 多智能体团队编排与协作框架

生产手册：运行具有明确角色、结构化任务流程和质量门控的多智能体团队。

快速开始：最小 2‑Agent 团队

一个 Builder 和一个 Reviewer。最简单且实用的团队。

• 定义角色

- Orchestrator（你） — 路由任务、跟踪状态、报告结果 - Builder agent — 执行工作，生成工件

• 生成任务

1. 创建任务记录（文件、数据库或任务板） 2. 启动 Builder，提供： - 任务 ID 与描述 - 用于存放工件的输出路径 - 交接指令（产出什么、放在哪） 3. 完成后：审查工件、标记完成、报告结果

• 添加 Reviewer

- Builder 产出工件 → Reviewer 检查 → Orchestrator 决定交付或返回

这就是核心循环。下面的内容阐述如何将该模式扩展到更大的团队。

---

核心概念

角色

每个智能体只能承担一个主要角色。角色重叠会导致混乱。

Role	Purpose	Model guidance
Orchestrator	路由工作、跟踪状态、做优先级决策	高推理模型（处理判断）
Builder	产出代码、文档、配置等工件	可使用成本较低的模型完成机械性工作
Reviewer	验证质量、提出改进	高推理模型（捕捉 Builder 漏掉的细节）
Ops	定时任务、站会、健康检查、调度	可靠且最便宜的模型

→ 在定义新团队或添加智能体时，请阅读 references/team-setup.md。

任务状态

每个任务遵循明确的生命周期：

Inbox → Assigned → In Progress → Review → Done | Failed

规则：

• Orchestrator 负责状态转移——不要依赖智能体自行更新状态。
• 每一次转移都必须留下评论（谁、做了什么、为什么）。
• Failed 是合法的结束状态——记录原因后继续。

→ 设计任务流或调试卡住的任务时，请阅读 references/task-lifecycle.md。

交接（Handoffs）

工作在智能体之间传递时，交接信息必须包含：

• 已完成内容——变更或产出概要
• 工件位置——精确文件路径
• 验证方式——测试命令或验收准则
• 已知问题——未完成或有风险的部分
• 下一步——接收方的明确行动项

不佳交接："Done, check the files."

优秀交接："Built auth module at /shared/artifacts/auth/. Run npm test auth to verify. Known issue: rate limiting not implemented yet. Next: reviewer checks error handling edge cases."

审查（Reviews）

跨角色审查可防止质量漂移：

• Builder 审查规格 – “可行吗？缺少什么？”
• Reviewer 检查构建 – “是否符合规格？边界情况如何？”
• Orchestrator 审查优先级 – “现在做这件事是否合适？”

跳过审查会在 3‑5 次任务后导致质量显著下降。

→ 设置智能体通信渠道时，请阅读 references/communication.md。 → 了解多步工作流的成熟实现，请阅读 references/patterns.md。

---

参考文件

文件	何时阅读
team-setup.md	定义智能体、角色、模型、工作空间
task-lifecycle.md	设计任务状态、转移、评论
communication.md	设置异步/同步通信、工件路径
patterns.md	实现具体工作流（规格→构建→测试、并行研究、升级）

---

常见陷阱

• 未明确工件输出路径

- Builder 产出优秀，却找不到文件。务必在启动提示中指定精确的输出路径，使用结构化的共享目录。

• 缺失审查环节

- “改动很小，直接跳过审查。”三次后错误会累积。每个工件至少要有一次非产出者的审查。

• 智能体不留评论

- 沉默的智能体会制造盲点。要求在 开始、阻塞、交接、完成 四个关键点留下评论。如果智能体沉默，默认其已卡住。

• 未校验智能体能力即分配任务

- 将需要浏览器的测试任务分配给不具备浏览器的模型，或让只能处理文本的模型去做图像工作。路由前请检查能力匹配。

• Orchestrator 亲自执行工作

- Orchestrator 只负责路由和追踪，不应直接进行构建。若开始“顺手做一件事”，团队的全局视野会瞬间丢失。

---

何时不应使用此技能

• 单智能体场景——直接遵循标准 AGENTS.md 即可，团队编排会带来额外开销。
• 一次性任务委派——使用 sessions_spawn 直接生成即可。此技能面向需要多次交接的持续工作流。
• 简单问题路由——若仅是把问题转给专家，这属于消息转发，不是工作流。

此技能专为 持续的团队协作 设计，适用于需要多轮交互、工件共享和质量把关的复杂任务场景。