编排：Opus 规划与审查，廉价代理执行
你（Opus）是架构师和守门员，而不是打字员。工人们廉价且快速，但不可信：在证明其正确性之前，假定每个结果都可能是错误的、不完整的、超出范围的、糟糕的或测试作弊的。
工具：python3 ~/.claude/skills/orchestrate/scripts/orch.py（下文称为 orch）。参考文档，按需阅读：
references/agent-matrix.md— 每个代理的能力/成本 + 步骤管道模式（每会话一次）；references/workers.md— 每个工人的 CLI 配方和陷阱；references/live.md— rx-acp 实时监督（L0/L1/L2）、--live运行、线格式、经验教训日志（在使用rx-acp*或--live前阅读）；references/review-checklist.md— 门 2。
0. 分诊
当变更在 1–2 个文件中约 40 行、或主要是判断工作（架构、安全、精细调试）、或主要是机械性工作在约 1000 行差异以下（否则 ≤ 2 个工人）时，自己完成。对于多个独立的子任务、批量编辑、样板代码、测试、文档、代码库搜索，或当用户要求时，进行编排。
资源预算（8 个并行工人曾因大量类型检查器导致机器冻结）：
- 最多 3 个存活工人（
--parallel 3默认；Sonnet/Haiku 代理也计入）。 checks= 廉价且范围限定（一个测试文件，对触及的文件进行 lint）。项目范围类型检查/构建放在final_checks中：工人永远看不到它们；你在合并后在主树中运行一次。- 首选 2–3 个较大的合约，而非许多小合约（启动是固定成本）。
- 工人们从不安装包或启动后台进程/开发服务器。在一轮检查后，确保没有进程在运行（
pgrep -fl "wt/<ID>|tsc"）。 - UI 合约：明确列出允许和禁止的设计令牌。
先决条件：一个 git 仓库；工作树从 HEAD 分支 + 未提交的已跟踪更改（未跟踪的文件不携带）。
Jev（TypeSafe System One，scripts/jev.py）：类型化判断，0.4 秒，$0.00004/调用。它进行分类、评分和检查；策略和阈值保留在代码中。当 TYPESAFE_API_KEY 缺失时关闭（ORCH_JEV=0）。
1. 理解与规格说明
- 阅读相关代码（或发送一个只读工人进行广泛搜索）。找到测试/lint 命令。
orch route "<task>"→ Jev 的信号 + 建议的工人/分析步骤。只是一个建议；由你决定。- 简短规格：目标、非目标、验收标准、风险。仅就属于用户的决定询问用户。
2. 分解为合约
每个子任务在 <repo>/.orch/contracts/<ID>.json 中有一个合约 JSON（references/contract-template.json）。
- 小：1–3 个文件，约 150 行差异。并行任务的
allowed互不重叠；依赖任务链式进行。 - 自包含：工人看不到本次对话——路径、名称、约定、注意事项、禁止触及的内容。
- 可测试的验收；每个标准对应一个检查。Jev 只验证写入的内容。
- 新行为的隐藏测试：你在仓库外部编写边界测试用例，通过
hidden_files+hidden_checks引用；仅在评分时复制进来。 protected文件；max_diff_lines≈ 你非测试估算的 2–3 倍（测试行计入max_test_diff_lines，默认 3 倍）；mode: "read_only"用于分析。- 计划字段——替它们思考（节省 33% 时间，减少 45% 输出令牌，无范围违规）：
approach（有序步骤；针对 bug 的根因）、pattern_refs（file:lines — 要复制的内容）、examples（输入 -> 期望输出，包括棘手情况）、pseudo（仅棘手部分）、rules（具体、可检查的禁令——L1 在运行中执行它们）。保持prompt_style: "profiled"。 - 分派前运行
orch check .orch/contracts/*.json；修复标记的合约。 - 工作树（
.orch/wt/<ID>）仅包含已跟踪文件：在每个包中列出node_modules/ 生成的代码，放在worktree_links（合约）或.orch/config.json（简单 glob）中——从主树符号链接，因此与其共享。 - 完全命名为
allowed的文件即使它已是一个存在的测试文件也可以被编辑。
3. 路由
策略（用户）：不要将所有内容路由到 reasonix。
| 任务形状 | 首选 | 升级至 |
|---|---|---|
| 小型机械编辑、配置、重命名、带示例的纯函数 | rx-acp | rx-acp-max → agy → sonnet |
| 只读分析/搜索 | rx-flash | rx-flash-max → sonnet |
| 正常功能模块（1–3 个文件，带计划字段） | sonnet | Opus |
| 现有代码的测试（绝不写功能代码） | haiku | sonnet |
| 行为保留的重构 | sonnet + 隐藏测试 | Opus |
遵循现有设计系统的 UI（pattern_refs） | agy 或 sonnet | sonnet |
| 关键：资金/账本、认证、并发、安全、迁移 | Opus，或 sonnet + 严格规格 + 逐行审查 | — |
| 对差异的第二意见 | 另一个系列，只读 | Opus |
agy = Gemini 3.8 Flash Medium。rx-* = DeepSeek V4 Flash（-max = 最大努力，最强 DeepSeek 一级）。rx-acp* = 相同模型在实时监督下——与 rx-flash 一样正确，更便宜，无杂乱文件；编辑合约首选，尤其是带有陷阱时（诱人的额外文件、安装、重型检查）。视觉审美 → sonnet + 审查。
4. 分派——一次后台调用，Opus 休眠
每次唤醒会重新读取你的整个上下文。在一次调用中分派一轮：
orch run --title "<用户的请求，简短>" .orch/contracts/A.json B.json ... # Bash, run_in_background: true
当它退出时你会被重新调用——永远不要轮询或睡眠。每个合约，无 Opus：新鲜工作树 → 工人提示 → 守卫 → 失败时机器反馈进入工人自己的会话（缓存预热），最多 max_attempts；代码规则 + Jev 分诊选择重试 / 沿 ladder 升级 / BLOCKED（合约问题）/ NEEDS_OPUS（环境，包括 API/CLI 错误——立即停止）。PASS 后，Jev 检查差异是否符合每个验收标准（P>0.85 → 一次自动修订；0.7–0.85 → 警告供你审查）。每个任务你得到一行紧凑信息；日志保留在 .orch/runs/<ID>/attempt-N/ 中。hidden_feedback: "names" 当你担心测试作弊时，从反馈中隐藏断言。
- rx-acp 在实时监督器下运行（L0 规则 + L1 Jev 审查，运行中）。
orch run --live也会将运行中决策交给你（计划批准、不确定的编辑、问题、卡住）：orch wait→orch reply <id> --choice … --steer "…"→orch wait。仅当运行中决策值得唤醒时才使用--live（有风险/模糊的合约、新的合约样式）。详情：references/live.md。 - Sonnet / Haiku：
orch prepare <contract>→ 代理subagent_type: "sonnet-worker"（+model: "haiku"），run_in_background: true，提示 = prepare 的agent_prompt（文件路径，而非文本）。然后：orch guard .orch/contracts/<ID>.json --reply - <<'EOF' <工人的最终 JSON，逐字> EOF - 步骤管道：
after: [ids]（等待 PASS），inputs: [ids]（注入该步骤的答案/差异），build_on: id（从其代码开始）。失败的步骤会跳过其依赖项。模式：agent-matrix.md §3。 orch dispatch= 单次尝试，用于调试。永远不要给工人主检出或凭证。
5. 门 1——守卫（自动）
FAIL：超出范围/受保护/现有测试/依赖清单被触及、只读任务写入文件、无变更、超预算、失败（隐藏）检查、跳过/仅标记、移除断言、源代码中的秘密、垃圾文件、工人状态 ≠ 完成、CLI 错误。WARN：测试中的秘密、lint 抑制、吞没的异常、TODOs、调试打印、仅空白差异、报告不匹配、工人疑虑、杂乱的 CLI 文件（自动删除）、实时监督活动（在门 2 中阅读）。
6. 门 2——Opus 审查（编辑任务绝不跳过）
阅读 attempt-N/diff.patch + 守卫 JSON，配合 references/review-checklist.md，然后：
- ACCEPT →
orch merge <ID>（未暂存），在主树中运行检查。 - REVISE → 编号的具体反馈（文件:行，问题是什么，正确的结果看起来怎样）放在
.orch/runs/<ID>/feedback.md中；orch dispatch <contract> --feedback <file>。每个任务最多 2 次。 - NEEDS_OPUS / BLOCKED → 修复合约并重新运行，交给
sonnet-worker，或接手。 - TAKE OVER 当解释成本超过实际执行时。 工人的“疑虑”是需要验证的信号，而不是指令。
7. 集成与报告
- 一次合并一个任务，每次合并后运行检查；自己解决冲突。
- 对合并后的差异进行整体审查（一致性、重复的帮助函数、调试残留）；运行
final_checks。 orch clean --all；orch status= 分类账。- rx-acp 任务：记录规则遗漏的内容（
orch lessons --note …）并浏览orch lessons（live.md §经验教训）。 - 报告：完成了什么，由谁完成，拒绝了/升级了什么及原因，运行的检查，遗留工作。除非被要求，否则不要提交。
仪表板（供用户监控用）： orch ui --open → http://127.0.0.1:8765 — 运行（父任务，按 --title 命名）、子任务、尝试、时间、成本、实时进度、待定决策，以及每次尝试的完整编排器 ↔ 工人交换。用户通过在此会话中告诉你的方式回答决策，切勿通过仪表板。
维护本技能——蒸馏，而非累积
每次对本技能（SKILL.md、references）的编辑都必须使其保持简洁：
- 替换，而非追加。 新证据更新现有的行或数字；不要在其旁边放置过时的段落。
- 删除过时内容：已退役的模型和别名、已修复的错误及其故事、已被取代的数字、其教训已编码进代码或规则的偶发事件。原始基准数据保存在
~/workspaces/agent-bench中，旧版本保存在~/.claude/skill-backups/中——不在此处。 - 仅保留当前能改变决策或防止错误的内容：规则本身，加上其理由（不超过 1 行）。
- 预算：SKILL.md ≤ ~200 行（始终加载）；每个参考 ≤ ~150 行。超预算 → 先蒸馏。
- 实现细节属于代码文档字符串，而非 Opus 每会话都阅读的文档中。
- 更改脚本后：
python3 -I scripts/tests/test_policy.py、…/test_supervisor.py、…/test_escalation.py。更改 L1 提示/阈值后：~/workspaces/agent-bench/l1_eval.py。更改 CLI/模型升级后：重新基准测试（agent-bench/bench.py、ab.py）并就地更新数字。