字
字节笔记本
2026年2月22日
Multi-Agent Orchestration Workflow 多智能体编排工作流指南
本文档描述了协调器代理（orchestrator agent）如何将大型任务分解为子任务、委派给工作代理并协调工作直至完成的工作流程。
概述
text
┌─────────────────────────────────────────────────────────────────┐
│ Orchestrator Agent │
│ │
│ 1. Create umbrella issue │
│ 2. Analyze task & plan breakdown │
│ 3. Create sub-issues │
│ 4. Create umbrella branch │
│ 5. Spawn worker agents (parallel where possible) │
│ 6. Monitor progress, merge PRs │
│ 7. Open final PR to main │
└─────────────────────────────────────────────────────────────────┘
│ ▲
│ spawn │ report back
▼ │
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Worker Agent │ │ Worker Agent │ │ Worker Agent │
│ │ │ │ │ │
│ - Create branch│ │ - Create branch│ │ - Create branch│
│ - Implement │ │ - Implement │ │ - Implement │
│ - Open PR │ │ - Open PR │ │ - Open PR │
│ - Report back │ │ - Report back │ │ - Report back │
└─────────────────┘ └─────────────────┘ └─────────────────┘第一阶段：规划
1.1 创建 Umbrella Issue
创建一个描述整体功能/变更的 GitHub Issue，作为所有子工作的跟踪点。
Umbrella Issue 应包含：
- 变更的高级描述
- 目标和非目标
- 设计文档链接（如适用）
- 子问题跟踪部分（创建时更新）
1.2 分析和规划分解
在创建子问题之前，分析工作以确定：
- 文件范围：哪些文件/模块将被修改？
- 依赖关系：哪些变更依赖于其他变更？
- 并行化：哪些变更可以同时进行而不会产生合并冲突？
关键原则：最小化并行任务之间的文件重叠，以避免复杂的合并。
1.3 创建子问题
为每个子任务创建单独的问题。每个子问题应包括：
- 具体工作的清晰描述
- 相关文件路径
- 对其他子问题的依赖（如有）
- 引用 umbrella issue（"Part of #X"）
在生成任何代理之前创建所有子问题，这提供了对完整计划的可见性。
1.4 更新 Umbrella Issue
向 umbrella issue 添加跟踪表：
markdown
## Sub-Issues
| Issue | Title | Status | Blocked By |
|-------|-------|--------|------------|
| #101 | Backend API changes | Open | - |
| #102 | Database schema | Open | - |
| #103 | Frontend components | Open | #101 |
| #104 | Integration tests | Open | #101, #102 |1.5 创建 Umbrella Branch
bash
git checkout -b issue/<umbrella-id>
git push -u origin issue/<umbrella-id>此分支是所有子任务 PR 的合并目标。
第二阶段：执行
2.1 可视化依赖关系
在生成代理之前，显示依赖结构：
依赖树：
text
#100 (Umbrella: Feature X)
├── #101 (Backend API) ─────────────┐
│ ├── #103 (Frontend)
├── #102 (Database schema) ────────┤
│ └── #104 (Integration tests)并行轨道：
- #101 和 #102 → 可以并行运行（无文件重叠）
- #103 和 #104 → 在依赖项合并后可以并行运行
执行顺序：
text
#101 ──┬──► #103
│
#102 ──┴──► #1042.2 生成工作代理
为准备就绪的任务（无未满足依赖项）生成代理。
生成工作代理时，提供：
- Issue ID：子问题编号
- 目标分支：umbrella 分支（例如
issue/100） - 实现摘要：要实现的清晰描述
工作代理的指令：
- 从目标分支创建分支
issue/<sub-issue-id> - 实现分配的任务
- 打开针对 umbrella 分支的 PR（不是
main） - 完成后报告
2.3 跟踪进度
随着工作进展维护状态显示：
问题状态：
| Issue | Title | Status | Agent Session | PR |
|---|---|---|---|---|
| #100 | Feature X (umbrella) | Open | - | - |
| #101 | Backend API | In Progress | abc123... | - |
| #102 | Database schema | In Progress | def456... | - |
| #103 | Frontend components | Blocked by #101 | - | - |
| #104 | Integration tests | Blocked by #101, #102 | - | - |
已生成代理：
| Agent Session | Issue | Task |
|---|---|---|
abc123-... | #101 | Backend API changes |
def456-... | #102 | Database schema |
分支结构：
issue/100– Umbrella 分支（合并目标）issue/101– 由工作器创建，目标issue/100issue/102– 由工作器创建，目标issue/100
2.4 处理代理完成
当工作代理报告回来时：
- 验证 PR - 检查它是否针对 umbrella 分支并通过了代码审查
- 合并 PR 到 umbrella 分支
- 更新跟踪 - 将问题标记为完成
- 检查未阻塞的任务 - 为新解锁的工作生成代理
注意：工作代理负责请求和处理与单独审查代理的代码审查。协调器不执行代码审查。
2.5 处理冲突
如果 PR 有合并冲突（由于之前合并的工作）：
- 要求工作代理在更新的 umbrella 分支上变基他们的分支
- 等待代理强制推送变基后的分支
- 重试合并
2.6 继续直到完成
重复生成 → 等待 → 合并循环，直到所有子问题完成。
在每个重要事件后更新状态表。
第三阶段：完成
3.1 最终验证
一旦所有子问题完成并合并到 umbrella 分支：
- 验证 umbrella 分支构建/测试成功
- 审查合并后的变更
- 用完成摘要更新 umbrella issue
3.2 打开最终 PR
从 umbrella 分支创建到 main 的 PR：
bash
gh pr create --base main --head issue/<umbrella-id> --title "Feature X" --body "..."PR 描述应：
- 引用 umbrella issue（"Closes #100"）
- 总结所有变更
- 列出所有完成的子问题
3.3 移交
保持最终 PR 开放供人工审查和合并。
最佳实践
上下文保留
协调器应最小化文件读取以保留协调任务的上下文窗口：
- 不要直接审查代码 - 工作代理使用单独的审查代理处理代码审查
- 要在需要解决合并冲突时读取文件
- 要在回答工作代理的具体问题时读取文件
- 要依靠 PR 描述和代理报告来理解变更
任务分解
- 适当大小的任务：每个子任务应在单个代理会话中可完成
- 最小化重叠：避免多个代理修改同一文件
- 清晰的边界：每个任务应有明确定义的范围和成功标准
并行化
- 先独立：从没有依赖项的任务开始
- 最大化并行性：同时生成所有未阻塞的任务
- 流水线：任务完成时，立即生成新解锁的工作
沟通
- 清晰的交接：生成代理时提供完整的上下文
- 跟踪一切：保持状态表更新
- 记录决策：记录与原始计划的任何偏差
错误处理
- 冲突：要求代理变基，不要试图自己解决
- 失败的任务：可以为同一问题重新生成新代理
- 阻塞的代理：检查依赖项是否真的阻塞或可以绕过
模板：工作代理指令
生成工作代理时，包括：
text
You are implementing issue #<sub-issue-id> (<title>) for the <repo> repository.
## Task
<clear description of what to implement>
## Files
<relevant file paths>
## Branch Instructions
1. Create your branch from `issue/<umbrella-id>`: `git checkout -b issue/<sub-issue-id> origin/issue/<umbrella-id>`
2. Implement the changes
3. Open a PR targeting `issue/<umbrella-id>` (not main)
4. Request code review from a review agent
5. Address any review feedback
6. Report back when complete and review is approved
## Context
<any additional context, links to related issues, design docs, etc.>分享: