Multi Agent Orchestration

Multi-Agent Orchestration

以当前主会话作为 PM，拆解、派工、巡检、验收和收口多个本地 Agent。日常 worktree 与 terminal/session 优先由 Orca 管理；Orca 不可用、用户明确要求或需要复现兼容路径时才使用 tmux。不要把“开了终端”误写成“建立了受监管任务”。

1. 适用边界与副作用

使用本 Skill：

• 同时推进两个以上边界独立、可分别验收的本地任务。
• 需要独立 worktree、分支、session、额度 lane 或可人工接管的长任务。
• PM 需要读取 worker 进度、纠偏、等待结构化完成事件并统一收口。
• 用户明确要求 Orca、tmux、独立 session、多个 worker、PM/orchestrator 或 Wave Autopilot。

不要使用：

• 单个短任务、一次性问答或无并行价值的单文件修改。
• 纯任务源、负责人和依赖状态同步：遵循项目任务源规则，不在本 Skill 扩展。
• branch/commit/push/PR/merge/冲突规则：使用 git-workflow。
• 宿主不能启动或控制本地 Agent CLI 时：使用宿主自己的 subagent 能力。

本 Skill 可能创建 Git/Orca worktree、分支、Session Context、终端、tmux session，以及 supervised Run/Task/Dispatch。它不自动安装依赖，也不自行扩张 push、merge、发布或外部调度授权。真实 provider 配置及备份不得进入 Git、日志或交付物。

交付成功后，pm-closeout.sh 默认清理一次性 worker 的远端 head、worktree 与本地分支；长期功能/集成分支及固定 worktree 必须声明 long-lived 并保留。事实未知、身份漂移或生命周期未结算时失败关闭。对已经确认合并、但未走标准 closeout 的单一遗留 worker，可使用 post-merge-cleanup.sh 做严格 dry-run/execute 清理；它不替代标准 closeout，也不得用于批量扫描。

2. 模式选择

同一 worker 只能有一个控制模式。terminal-managed 没有 Task/Dispatch，不得要求 worker_done；supervised 必须有 live Task/Dispatch，不得用 STATUS、UI 卡片、TUI idle、heartbeat 或 timeout 冒充完成。

3. 派发前合同与门禁

3.1 先完成任务建模

PM 在任何 worker 副作用前完成：

1. 读取项目规则和完整任务卡，确定目标、非目标、allowed/forbidden files、验证命令与完成条件。
2. 按根因、依赖链和文件范围分组；只有范围正交、验收独立、无共享锁文件/schema/迁移时才并行。
3. 为每个 worker 指定 branch、branch_lifecycle、integration target/base、worktree、session、角色、backend/profile/model、provider slot 和资源 owner。
4. 普通 worker 默认为 ephemeral-worker；只有项目任务合同明确声明的长期功能/集成基线才使用 --branch-lifecycle long-lived。源分支生命周期与合并目标是两个字段，不得混同。
5. 默认每波及全局活跃 worker 不超过 3；PM 待验收交付超过 2 个时停止扩波。项目可以收紧，只有用户明确、限期的探索窗口才可放宽。
6. 验证命令默认写 scoped：单 spec / 定向用例 / --bail 1 早停；整包全量套件（全量 test/build 链）不进 worker 自验合同，全量验证单一在飞（跨项目互斥），默认归宿是 PM 收口时串行复跑。本条约束验证类别，不约束 worker 数量（见 §5 验证负载纪律）。

Issue 分组读取 references/12-issue-grouping.md；并发边界与真实事故读取 references/10-parallel-lessons.md。

3.2 强制门禁顺序

以下四道门按阶段执行，任一非零退出均不得跳过：

1. 派发价值门：候选波次采用 templates/dispatch-value-gate.example.json 同构合同，运行 python3 scripts/dispatch-value-gate.py <spec.json>。只接受 implementation、reusable_verification 或绑定具名 PR/head 的 merge_gate；docs/research/纯调查/纯格式工作不可独立派发。
2. 交付价值后门：使用同一 spec 运行 worker-value-postflight.py，以真实 diff、声明资产、验证命令和 40 位 immutable head 证明交付。
3. 角色分离验收门：非平凡实现由不同 dispatch/session 的 implementer 与 reviewer 完成，运行 review-acceptance-gate.py。自审、head 漂移、纯叙述证据、失败验证或未清 blocker 均拒绝。
4. 失败恢复门：先用 acceptance-recovery.py 分类。internal_recoverable 在预算内修复并重新独立审查；external_dependency、safety_unknown 或预算耗尽才泊车。已具名 PR 的 docs-only 验收修复只能走 acceptance-repair-gate.py 的极窄 preflight/postflight 通道。

字段、命令、例外枚举、reviewer 证据预算与恢复语义统一读取 references/18-dispatch-acceptance-contracts.md；不要在项目 prompt 或别的脚本另造一套分类表。

3.3 运行时安全门

• spawn-worker.sh 从完整进程祖先链识别真实 PM harness，并对嵌套层白名单取交集。未知、冲突或不可证明的宿主失败关闭；--pm-harness 只做一致性声明，不能提权。
• Claude Code/Codex PM 可派 Claude Code、Codex、CodeBuddy、QoderWork CN；CodeBuddy、QoderWork CN PM 只能派自身。zcode 默认禁用，只有用户明确授权后修改 config/harness-backend-policy.json 才可开启。
• worktree 落盘后、任何 terminal/Task/worker-start/任务注入前，必须证明目录、预期分支和 HEAD 一致；Orca repoId 必须与已验证项目一致。失败只清理可精确证明归属的资源，PM 不得借机直接实现业务。
• Worker 只修改 allowed paths。reviewer 默认只可写自身 Session Context；修复被审分支必须显式 --review-repair-grant <授权来源>，且任何 config/*.local.yaml 都不可写。
• Shell 与安装均 fail-closed。验证命令不等于安装授权；只有精确 --allow-install-command 和可审计授权来源才允许安装。内置 sed 只放行 sed -n '<数字或 $>[,<数字或 $>]p' <单文件>，替换、写入、执行、多文件和其他形式仍需精确 allowlist。
• Worker 默认执行权限（v2.22.0，用户决策 2026-09-06）：worker 隔离在专属分支 worktree 内，push+PR 是必要交付路径，安全类按「分段校验」放宽——管道/;/&& 复合命令在每段都是安全读或安全交付命令时整体放行（git status/diff/log/show/fetch/add/commit/push/rebase、gh pr create/view、ls/grep/cat/jq/sort 等过滤器、node --version 类版本查询）；重定向仅限 /dev/null 与临时目录（拒绝 .. 穿越）。仍然 fail-closed：force push（--force/-f/--force-with-lease）、push 到 main/master、远端删除（git push origin :branch）、--mirror/--tags、子 shell、输入重定向、命令替换、gh api/gh repo sync、安装类命令。identity 四件套（--git-expected-name/--git-expected-email/--git-integration-base/--git-push-remote）仍推荐用于 PR 交付任务：绑定的 safe-push 会校验从远端 PR base 到 HEAD 的完整提交链后按不可变 OID 推送，是裸 push 的强化替代而非唯一通路。
• 派发价值合同已经声明 verification_commands 时，调用 spawn 必须同时传 --verification-contract <spec.json> --verification-task-id <ID>；无文件合同时逐条传 --verify-cmd。命令作为完整字符串原样进入 authority receipt、METADATA 与 allowed_shell_commands，不得拆开 cd <subdir> && <verify>。
• 要求 Worker 自验时传 --require-verification，或在项目 .claude/orchestration.config.json 设置 verification.required: true。命令解析为空、合同 task 不唯一、worker type 未声明、配置畸形、重复/空白、U+0000 或安装型命令时，必须在 terminal/Task/Dispatch/任务注入前失败。
• 验证命令只接受一个权威来源：无文件合同时使用 --verify-cmd，否则使用派发价值合同；两者互斥。都未提供时才读取项目配置，再回退根目录有界发现。Node/Make 既有发现不变；Python 只在根 manifest 与根 tests/ 同时存在时注入 python3 -m unittest discover -s tests -v。嵌套 Python/其他子项目必须在项目配置 verification.by_worker_type 显式写完整命令，不递归猜测。依赖行为读取 references/02-runtime-dependencies.md。

4. Orca-first 执行

4.1 每个新会话先读取运行时合同

orca skills get orca-cli
orca skills get orchestration   # supervised / DAG / ask-reply 时
orca status --json

以运行中 CLI 的指南和 --help 为准。spawn-worker.sh 只在当前 PROJECT_DIR 可被精确解析为同一 Orca worktree/repo 时进入 Orca；--no-orca-mode 显式走 tmux。

4.2 Wave 准备屏障

多 worker supervised Wave 必须先一次性写 manifest、创建一个 Run 并预建全部 Task，receipt 成功后才并行启动。不要让并发 spawn 各自创建/重绑 Run，也不要在 worker-start 注入任务后再次发送完整 prompt。

bash scripts/orca-wave-prepare.sh --manifest /tmp/wave.json --receipt /tmp/wave-receipt.json

bash scripts/spawn-worker.sh \
  --project "$PROJECT" --branch feat/worker-a --session worker-a \
  --branch-lifecycle ephemeral-worker --worker-backend claude-code \
  --verification-contract /tmp/dispatch-spec.json --verification-task-id TASK-A \
  --command "$AGENT_COMMAND" --orca-supervised \
  --orca-run-id "$RUN_ID" --orca-coordinator-handle "$COORDINATOR_HANDLE" \
  --orca-task-id "$TASK_A_ID"

完整 manifest、Terminal-managed、Dispatch 自检、cold-start 恢复、settle 与 metadata 合同读取 references/13-orca-cli-worker.md。PM 的 read/show/send/wait/reply/release/ack/settle/pr-audit/closeout 命令读取 references/14-pm-orchestrate.md。

4.3 Worker Prompt 与 Session Context

使用 templates/worker-prompt.md，至少写明：任务卡、范围、禁止项、验证命令、完成协议、branch lifecycle、integration target、资源 owner、安装授权和 Git identity。supervised 的 worker-start 是唯一任务注入器；长 prompt 可落到 WORKER_PROMPT.md，terminal 只发送短 Read 指令。

<worktree>/.claude/agent-sessions/<session>/
├── METADATA.json
├── STATUS.json
├── RESULT.md
├── PATCH_SUMMARY.md
└── WORKER_PROMPT.md

字段与 checkpoint 读取 references/03-checkpoint-files.md。supervised 中 STATUS 只辅助观察，完成权威仍是 worker_done → Delivery。

5. 巡检、介入与持续推进

按证据优先级巡检：

1. supervised：Delivery、worker-show、worker-read。
2. terminal-managed：terminal read + checkpoint。
3. tmux：checkpoint、Git status/log、bounded capture-pane。
4. 所有模式最终检查真实 diff、测试、产物与 PR 状态。

发现偏题、阻塞、越界或验证失败时，优先给原 worker 发送窄纠偏；需要独立审阅时另派 reviewer。运行时活性与业务进展必须分开判断：输出/cursor/CPU 前进只证明活性，文件、commit、测试和产物才证明业务进展。观察不确定时不得自动 Esc、Ctrl+C、stop、release 或按进程名批量 kill。

Wave Autopilot 只有用户明确授权并在项目任务源固定策略后才启用。L1 当前会话推进读取 references/15-wave-autopilot.md；跨会话 L2 controller 与尚未实现的 L3 scheduler 边界读取 references/16-autopilot-durability.md。不要把 session cron、Markdown 任务源或 provider lease 单独描述成持久控制器。

跨项目检查 Orca Worker 是否因 429/usage limit 停在 idle 时，运行 scripts/orca_rate_limit_recovery.py --manifest <私有清单>；默认只读，只有显式 --execute 才对高置信 RATE_LIMIT_IDLE 通过 terminal 输入通道发送一次固定“继续”。tmux、单关键词/陈旧 tail、未分组身份和状态不确定一律不处置；WAKE_ACCEPTED 不等于额度恢复或业务继续。完整 manifest、状态机、错峰、幂等、TOCTOU 与退出码读取 references/20-orca-rate-limit-recovery.md。

Worker node OOM 识别与退避（2026-09-05 事故：多 worker 长输出使会话内 node 进程 V8 堆耗尽 FatalProcessOutOfMemory → SIGABRT，PM 周期重拉形成崩溃循环并一度触发整机强制重启）。spawn-worker.sh v2.20.0 起默认给 worker 会话注入 NODE_OPTIONS=--max-old-space-size=2048（SPAWN_WORKER_NODE_MAX_OLD_SPACE_MB=0 可关），worker 到限自身退出而非拖垮系统。PM 巡检发现 worker node OOM（退出码 134 / SIGABRT / 日志含 FatalProcessOutOfMemory / 系统崩溃报告目录（DiagnosticReports）中 node OOM 报告新增且时间吻合）时：同任务不得立即重拉，至少等下一轮巡检并全局并发 -1，且重拉前必须重跑内存预算预检（probe 每次 spawn 都现场探测、不缓存；额度不足按 PARKED_FOR_MEMORY 排队，不得绕过）；同一任务连续 2 次 OOM 后停止重拉、泊车并向用户报告——这通常意味着任务本身产生超长输出（全量日志聚合、超大测试跑），需任务侧降输出或拆分，而不是更用力地重试。

物理内存预算排队（mem budget lane）：spawn-worker.sh 在任何 worktree/terminal/lease/dispatch 副作用之前运行 scripts/mem_budget_probe.py，按 per-worker 预算（默认 3 GiB；SPAWN_WORKER_MEM_BUDGET_BYTES 可调，=0 显式关闭整道门）把现场可用物理内存折算成可派发额度。额度不足或探测不可读时 spawn 以专用退出码 4 拒绝，输出 SPAWN_WORKER_MEM_BUDGET_DENIED 与 可用/预算/缺口 诊断；放行则在 PM 日志留下 SPAWN_WORKER_MEM_BUDGET: available=… budget=… slots=… 账本行。PM 收到该拒绝不得忙等、不得改走手动 spawn：本轮巡检把任务记 PARKED_FOR_MEMORY 并留存 probe 输出，下一轮巡检重试；同一任务连续 3 轮额度不足则正式泊车并向用户报告（附 probe JSON）。单进程堆顶（v2.20.0）管单个 worker 的失血点，本门管总量叠加承诺，也覆盖无堆顶可依赖的非 node runtime。数据源、预算推导、压力收紧与排队状态机读取 references/22-mem-budget-lane.md。

验证负载纪律（verification lane）：约束验证类别，不约束 worker 数量。worker 自验默认 scoped（单 spec / 定向用例 / --bail 1）；全量套件单一在飞、跨项目互斥——确需 worker 现场跑全量时，先探测既有全量测试进程（如 pgrep -fl 'vitest|pytest|jest|go test'），无法确认独占就退避等待或改 scoped。探测是尽力而为的现场信号，不建跨项目锁文件，宁可少并发不可误并发；PM 收口时的全量复跑天然串行，是全量验证的默认归宿。验证输出一律重定向日志文件、只把有界尾部（如 tail -50）带回 terminal/session——长输出无界刷屏正是会话侧 node 运行时 OOM 的喂食管。PM 巡检发现系统负载飙升且多个 worker 同时在跑验证时，纠偏为错峰排队（等在飞验证收尾再放下一批），不砍 worker 数量。本纪律与单进程堆顶、物理内存 lane 互补：堆顶管单进程失血点，mem lane 管总量承诺，本纪律管验证执行的并发类别与输出体量（2026-09-05/06 事故中三者缺最后一环：并发全量自验同时制造了负载尖峰与超长输出）。

6. 验收、Git 交付与资源收口

PM 依次完成：

1. 读取完整 Delivery、实际 diff 和 worker 证据；运行与产物类型匹配的验证。GUI/Web/桌面变化必须启动真实入口做代表性交互。
2. 核对 allowed files、敏感文件、安装授权、Git identity、commit/head、PR 范围，以及任务启动的服务/端口/子进程已按 owner 收口。
3. supervised worker 先 reuse/release/retain，再 ack；仍存活但漏发完成时先结构化提醒，确认已死才使用 settle。
4. 用户或项目已授权 Git 外部写入时，使用 pm-closeout.sh 的 PR-first 流程。PR 唯一性、冻结 head/diff/check/review、两阶段 mutation receipt、Monorepo integration path 与结果不确定恢复统一以 references/14-pm-orchestrate.md 为准。
5. 交付确认后立即取得资源终态；不得把清理留给 PM 记忆。
6. STATUS=done（或 PR 已合并）但进程仍存活的 worker——含跨会话遗留——当轮巡检即触发收口或上报：按 owner 通道 closeout / 释放 terminal / 结算 lifecycle，无法处置时向用户报告具体滞留对象。滞留进程持续挤占物理内存派发额度（references/22-mem-budget-lane.md），不收口就直接压缩下一波可派发 worker 数。

bash scripts/pm-cleanup-worker.sh \
  --project "$PROJECT" --worktree "$WT" --branch feat/worker-a --session worker-a \
  --branch-lifecycle ephemeral-worker --integration-target integration/feature-a \
  --pr "$PR" --expected-tip "$WORKER_TIP" \
  --delivery-mode remote-pr --delivery-commit "$MERGE_COMMIT"
# 手工接管时先预览，再以同一精确参数加 --execute；pm-closeout 成功路径默认自动执行。

清理必须区分源分支生命周期与合并目标：

• ephemeral-worker：只有 exact PR head/base、expected tip、delivery commit、干净 worktree 和 settled lifecycle 全部一致时才清理。
• long-lived，或源分支等于 integration target：保留远端 ref、本地 ref 与固定 worktree，输出 RETAINED_WITH_REASON reason=long-lived-branch。
• 调用参数不得把 metadata 的 long-lived 降级；短 Worker 合入长期分支时只清理 Worker head，绝不清理 integration target。
• 结果只允许 CLEANED、RETAINED_WITH_REASON、CLEANUP_PENDING。交付已确认后，清理失败作为独立债务继续处理，不重跑 push/merge；隐去 CLEANUP_PENDING 后声称完全闭环属于 Hard Fail。

Git 生命周期与批量 stale 分支清理由 git-workflow Skill 的“分支清理”入口负责；该 Skill 会按需加载自己的清理 reference。

7. Backend、额度与依赖

默认优先与 PM 同宿主，只有额度、模型能力或用户明确要求时跨工具。个人偏好写入 ignored 的 config/orchestration-personal.json，项目策略写入 .claude/orchestration.config.json；个人配置只能在 harness 白名单内选择 backend。

启用 quota_aware_routing 时，派单前必须用新鲜 summary 运行 route_suggest.py；summary 缺失、过期、lane 低于判停线、provider 不健康或未映射时，quota_preflight.py 在任何副作用前拒绝。显式 override 必须携带授权来源并写入 receipt。额度只为已经通过价值门的任务选路，不能生成 quota-burn 工作。模型与 lane 判断读取 references/01-model-selection-matrix.md 和 references/17-model-capability-profile.md。summary 合同的生产方不限；zcode lane 可用 scripts/quota_summary_zcode.py 把本机 zcode-quota 监测器的真实观测合并写入 summary（只更新 zcode lane、不改写其他 lane 的 generated_at，不接触凭证），数据流与合并语义读取 references/21-zcode-quota-producer.md。

系统依赖：Bash 4+、Git、jq、Python 3；PR 审计/收口需要 gh；tmux 仅回退路径需要；Orca 路径需要运行中的 Orca runtime 与版本匹配 CLI。按 backend 还需对应本地 CLI。检查命令：

bash scripts/check-dependencies.sh --backend claude-code --backend codex --check-gh

8. 按需读取地图

不要一次加载全部 references；只读取当前阶段与 backend 所需的文件。

9. Hard Fail

出现以下任一情形，停止派发、接受、合并或清理，并保留可复查证据：

• 用户要求 PM/worker 编排，启动门禁未过而 PM 直接写业务代码。
• worker cwd/worktree/branch/repo/head 与目标不一致，或宿主/backend 身份不可证明。
• 真实 provider settings、Token、备份或其他敏感信息进入 Git、日志或打包件。
• 未授权安装、全局环境写入、raw push、范围外修改，或把 verify 当安装授权。
• supervised worker 无 live Task/Dispatch，或用 STATUS/Sentinel/idle/timeout 代替 worker_done 与 settlement。
• 只凭 worker 自报、静态 lint、单次 UI 状态或未绑定 head 的证据声称业务完成。
• 未过派发价值、交付后、角色分离或失败恢复门禁；无授权 reviewer 越界写入，或把 PM 例外交付计为常规交付。
• PR create/push/merge 前未通过唯一性与冻结事实审计，或结果不确定时盲重试 mutation。
• worker 启动的服务/监听器没有 owner 与零净增量证据，或按进程名批量 kill。
• 清理 active/unknown/release pending worker；误删长期分支或 integration target；交付后没有记录三种资源终态之一。
• 仅凭单一 429 关键词、陈旧 tail 或 idle 状态注入；向身份未绑定、不可写、非 Orca 或仍在 retrying 的 terminal 发送“继续”；把 WAKE_ACCEPTED 声称为额度或业务恢复。

修改本 Skill 后，按 references/19-maintainer-validation.md 运行受影响测试和完整回归。只有真实启动受支持 Agent 并观察 worker_done → Delivery → release/精确外部终端结算 → ack，才能把该 backend 的 supervised 路径标记为已验证；其他 backend 不得类推。