介绍
# Agent Team Orchestration
运行多智能体团队的生产级手册，包含明确的角色、结构化的任务流和质量关卡。
## 快速开始：最小的 2 智能体团队
一个构建者 和一个审查者。最简单且实用的团队。
### 1. 定义角色
``` Orchestrator (you) — Route tasks, track state, report results Builder agent — Execute work, produce artifacts ```
### 2. 生成任务
``` 1. Create task record (file, DB, or task board) 2. Spawn builder with: - Task ID and description - Output path for artifacts - Handoff instructions (what to produce, where to put it) 3. On completion: review artifacts, mark done, report ```
### 3. 添加审查者
``` Builder produces artifact → Reviewer checks it → Orchestrator ships or returns ```
这就是核心循环。下文的所有内容都是基于此模式的扩展。
## 核心概念
### 角色
每个智能体都有一个主要角色。角色重叠会导致混乱。
| 角色 | 目的 | 模型建议 | |------|---------|---------------| | **Orchestrator (编排者)** | 分发工作、跟踪状态、进行优先级决策 | 高推理能力模型（负责判断） | | **Builder (构建者)** | 产出制品 —— 代码、文档、配置 | 可以使用性价比高的模型处理机械性工作 | | **Reviewer (审查者)** | 验证质量、针对不足提出反馈 | 高推理能力模型（发现构建者遗漏的问题） | | **Ops (运维)** | 定时任务、站会、健康检查、分发 | 只要可靠的低成本模型 |
→ *在定义新团队或添加智能体时，请阅读 [references/team-setup.md](references/team-setup.md)。*
### 任务状态
每个任务都会经历一个定义好的生命周期：
``` Inbox → Assigned → In Progress → Review → Done | Failed ```
**规则：** - 编排者 负责状态转换 —— 不要依赖智能体自己更新状态 - 每次转换都要附带注释（谁、做了什么、为什么） - 失败 是一个有效的最终状态 —— 记录原因并继续前进
→ *在设计任务流或调试卡住的任务时，请阅读 [references/task-lifecycle.md](references/task-lifecycle.md)。*
### 移交
当工作在智能体之间流转时，移交消息必须包含：
1. **完成了什么** —— 变更/产出的摘要 2. **制品在哪里** —— 确切的文件路径 3. **如何验证** —— 测试命令或验收标准 4. **已知问题** —— 任何未完成或有风险的部分 5. **下一步做什么** —— 给接收智能体的明确下一步行动
坏的移交：*“做完了，查一下文件。”*
好的移交：*“在 `/shared/artifacts/auth/` 构建了认证模块。运行 `npm test auth` 进行验证。已知问题：速率限制尚未实现。下一步：审查者检查错误处理的边缘情况。”*
### 审查
跨角色审查可以防止质量下滑：
- **构建者审查规格** —— “这可行吗？缺了什么？” - **审查者检查构建产物** —— “这符合规格吗？有边缘情况吗？” - **编排者审查优先级** —— “这是当前最该做的工作吗？”
跳过审查步骤，质量会在 3-5 个任务内下降。每次都是如此。
→ *设置智能体通信渠道时，请阅读 [references/communication.md](references/communication.md)。* → *寻找经过验证的多步骤工作流时，请阅读 [references/patterns.md](references/patterns.md)。*
## 参考文件
| 文件 | 何时阅读... | |------|-------------| | [team-setup.md](references/team-setup.md) | 定义智能体、角色、模型、工作区 | | [task-lifecycle.md](references/task-lifecycle.md) | 设计任务状态、转换、注释 | | [communication.md](references/communication.md) | 设置异步/同步通信、制品路径 | | [patterns.md](references/patterns.md) | 实现特定工作流（规格→构建→测试、并行研究、升级处理） |
## 常见陷阱
### 未指定清晰的制品输出路径
智能体产出了很好的工作成果，但你却找不到它。在生成 任务的提示词中始终指定确切的输出路径。使用结构可预测的共享制品目录。
### 没有审查步骤 = 质量下滑
“只是个小改动，跳过审查吧。”这样做三次，错误就会累积。每个制品至少需要经过一双未参与其生产的眼睛来检查。
### 智能体未对任务进度进行注释
沉默的智能体会造成协调盲区。要求在以下环节进行注释：开始、遇到阻塞、移交、完成。如果智能体保持沉默，可以假定它卡住了。
### 分配任务前未验证智能体能力
将基于浏览器的测试分配给没有浏览器访问权限的智能体。将图像处理工作分配给仅限文本的模型。在路由之前检查能力。
### 编排者执行执行类工作
编排者负责路由和跟踪 —— 它不负责构建。当你开始“顺手做这一件事”的那一刻，你就失去了对团队其余部分的监督。
## 何时不使用此技能
- **单智能体设置** —— 直接遵循标准的 AGENTS.md 约定。团队编排会给单智能体增加不必要的开销。 - **一次性任务委派** —— 直接使用 `sessions_spawn`。此技能适用于包含多次移交的持续性工作流。 - **简单问题路由** —— 如果你只是把一个问题转发给专家，那是一条消息，而不是一个工作流。
此技能适用于 **持续性团队工作流** —— 即智能体在多个任务中相互依赖彼此产出的协作模式。