用途
Orchestrate 用于协调一组并行智能体，执行任务计划中的某个阶段。它管理任务分配、监控、范围约束，以及波次切换时的质量门禁。
主要能力
- 任务分配与波次排序：将任务分派给并行智能体，并按波次推进。
- 心跳监控：交互模式下按计时器逐级升级停滞处理——60 秒发送状态询问，120 秒发出警告，180 秒重新分配并生成替代智能体。
- git 安全：要求所有并行智能体在提交时使用 flock 锁，避免并发写入导致暂存文件在提交间混入。
- 范围约束与文件重叠检查：在计划阶段检测文件重叠，将冲突任务串行化。
- 波次切换质量门禁：每个波次切换时执行前置/进行中/后置检查清单。
- 失败升级：无头模式下先带上下文重试（最多 2 次），再升级模型（haiku→sonnet，sonnet→opus，预算 ×1.5），最后请求用户介入（跳过/手动修复/中止）。
使用方式
模式
- 交互模式（默认）：通过 TeamCreate/Task/SendMessage 在会话内协调智能体，适合需要智能体间协调的复杂任务。
- 无头模式（--headless）：使用独立的 claude -p 进程，适合边界清晰的可并行任务，协调开销约减少 54%。
模式选择决策树
- 任务数 > 10 且文件边界清晰 → 无头模式。
- 否则 → 交互模式。
- 任务共享文件超过 50% 重叠 → 使用 git worktrees 或串行化为顺序波次。
- 否则 → 使用 flock 的标准并行执行。
资源加载（强制）
- 生成任何智能体前：读取 agent-roles.md 获取角色分配与模型选择。
- 无头模式下每个任务提示前：读取 prompt-templates/{role}.md。
- 每次波次切换时：读取 wave-template.md 获取前置/进行中/后置检查清单。
- 需要 claude -p 标志细节或错误分类时：读取 headless-runner.md。
- 交互模式不要加载提示模板——交互智能体直接调用 /quality-commit 和 /tdd。
脚本
bash scripts/setup-session-dir.sh
node scripts/check-file-overlap.js "apps/api/src/a.ts,apps/api/src/b.ts" "apps/api/src/b.ts,apps/web/src/c.ts"
参数
$ARGUMENTS 接受：阶段 ID、计划文件路径或内联任务列表。
关键标志：--headless、--interactive、--dry-run、--wave N、--max-agents N、--budget-per-task N、--timeout-multiplier N、--no-qa、--verbose。
示例
/orchestrate A # Phase A, interactive
/orchestrate A --headless # Phase A, headless
/orchestrate A --headless --dry-run # Preview prompts without spawning
/orchestrate A --wave 2 # Resume from wave 2
/orchestrate docs/plans/custom.md # Custom plan file
/orchestrate "add auth; write tests" # Inline task list
适用场景
- 已有书面计划、任务可拆分为多个独立工作流的多任务实现。
- 任务数量较多且文件边界清晰，适合无头并行执行。
- 需要智能体间协调、跨任务决策的复杂任务，适合交互模式。
限制与禁止事项
- 不要加载：任务小到单个智能体可直接完成；没有书面计划或没有可拆分工作流；并行执行造成的重叠多于提速。
- 绝不让并行智能体在没有 flock 的情况下执行 git add && git commit——git 索引是进程全局的，并发写入会静默混合暂存文件。每个智能体系统提示必须包含 flock /tmp/orchestrate/{session-id}/git.lock。症状：提交 A 包含任务 B 的文件。
- 绝不跳过文件重叠检查——两个智能体编辑同一文件会产生双方都无法解决的合并冲突。
- 绝不仅凭 is_error 字段判断失败——预算耗尽会设置 is_error: false 且 subtype: "error_max_budget_usd"。始终检查 subtype.startsWith("error_")。
- 绝不跨波次复用 PID 文件——操作系统会回收进程 ID。波次之间必须清理 /tmp/orchestrate/{session-id}/task-*.pid。
- 绝不在无 --no-session-persistence 的情况下生成无头智能体——每个 claude -p 会写入会话文件到 ~/.claude/。
- 绝不在没有 --allowedTools 的情况下使用 --dangerously-skip-permissions——该标志单独使用会授予不受限的工具访问权限（包括递归智能体）。始终搭配 --allowedTools "Bash Edit Write Read Glob Grep"。
- 绝不通过重新生成同一智能体并附加错误来重试失败智能体——应生成全新的修复子智能体并给出针对性指令。
- 绝不在规格合规通过前运行代码质量审查——先规格合规，始终如此。
- 绝不在未运行完整验证链的情况下认为无头任务完成——即使 subtype: "success" 也不保证分支正确、文件在范围内、构建通过。始终执行：提交存在 → 范围检查 → 验证命令。
集成映射
| 文件 | 加载时机 |
|---|---|
| agent-roles.md | 为任务分配角色时（步骤 2） |
| prompt-templates/{role}.md | 构建无头智能体提示时 |
| wave-template.md | 运行波次切换门禁时 |
| headless-runner.md | 调试 claude -p 标志或输出格式时 |
| execution-steps.md | 完整分步执行参考（3H/3I） |