12 KiB
Orca 适配器（稳定核心，一种编排实现）
Orca orchestration 是运行时调度层的一种实现。闭环流程本身与工具无关（见 closed-loop.md）；本文件只提供 Orca 的具体命令。没有 Orca 时用 closed-loop.md §「手动模式」。
所有结论仍以 tasks.yaml 为准，Orca 消息不是最终记录。
何时用 Orca 编排
用：需要监督、等待结果、闭环修复、三轮重试；有多个可独立派发的任务；需要 worker_done 后再复测。
不用：单次问答；用户只要求完整 handoff 不需监督；不需要复测的小改动。
运行前检查
orca status --json
orca terminal list --json
orca orchestration task-list --json
orca orchestration inbox --limit 20 --json
确认：Orca runtime 可达；Coordinator、Developer、Test 三个终端都存在；Developer 在正确 worktree；当前没有冲突的活跃编排任务。
解析并复用 worker
默认复用，创建是兜底。 每次向 Developer 或 Test 派发前都先解析 worker，不能直接照后文示例执行 terminal create：
- 运行
orca terminal list --json，筛选connected=true、writable=true、目标worktreePath一致、标题角色和配置一致的终端。稳定标题使用ACK-<ROLE>-<CLI>-<TIER>-<N>，例如ACK-DEV-CODEX-TERRA-1、ACK-TEST-CODEX-LUNA-1、ACK-DEV-CURSOR-AUTO-1；强档示例为ACK-DEV-CODEX-SOL-1。 - 运行
orca orchestration task-list --status dispatched --json。若候选 handle 出现在活跃任务的assignee_handle，视为 busy，不复用；不要仅凭终端预览文本或最近输出时间猜忙闲。 - 对空闲候选运行
orca terminal show --terminal <handle> --json，确认仍存活且 worktree、角色和 Agent CLI / 模型档位符合本次要求。符合就直接把该 handle 作为dispatch --to的目标。 - 只有不存在兼容的空闲候选时才创建。若同角色同配置已有 busy worker，使用下一个未占用序号，例如
ACK-DEV-CODEX-TERRA-2；不要创建另一个同名终端。 - dispatch 成功后，把实际 handle 写入对应
tasks.yaml条目的dispatch.worker。下一轮先尝试该 handle；若它已消失、断开、不可写、worktree/角色/档位不兼容或正忙，再回到第 1 步选择其它 worker。
tasks.yaml.dispatch.worker 记录“这个任务实际用了谁”，便于续跑和审计；orca terminal list 记录“谁现在还活着”，是运行时存活状态的事实源。不要另建一份永久 worker 池，因为终端关闭后其中的 handle 会过期。
复用决策：
| 情况 | 动作 |
|---|---|
| 任务已记录 worker，且该 handle 存活、兼容、空闲 | 优先复用原 handle |
| 有其它同 worktree、同角色、兼容的空闲 worker | 复用该 handle |
| 同角色 worker 存在但都 busy | 创建下一编号的临时并发 worker |
| worker 已关闭、断开或不存在 | 创建新 worker |
| 模型升级或 worktree 不同 | 不复用不兼容 worker，创建对应档位/路径的新 worker |
给 worker 终端固定模型
编排层不设模型。 task-create / dispatch 都没有 --model；dispatch --to <handle> 只是把任务投给一个已存在的终端，用的是那个终端里 agent 会话启动时的模型。要固定模型，就在 创建 worker 终端 时用 agent CLI 的模型参数：
默认沿用 Coordinator 当前所在的 Agent CLI：Cursor Coordinator 创建 Cursor worker，Codex Coordinator 创建 Codex worker。不要通过询问模型来猜运行环境；以当前 CLI / 终端环境为准。除非项目 overlay 或用户明确指定，否则不跨 Agent CLI 创建 worker。
# Cursor：Test / Developer worker 用 auto 模型，并按项目要求启用 YOLO
orca terminal create --worktree path:<dev_worktree> \
--command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1" --json
# 需要更强模型时改成具体模型
orca terminal create --worktree path:<dev_worktree> \
--command "cursor-agent --yolo --model claude-opus-4-8-thinking-high" --title "ACK-DEV-CURSOR-STRONG-1" --json
# Codex：Developer worker
orca terminal create --worktree path:<dev_worktree> \
--command "codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-terra -c model_reasoning_effort=medium" \
--title "ACK-DEV-CODEX-TERRA-1" --json
# Codex：Test worker
orca terminal create --worktree path:<test_worktree> \
--command "codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna -c model_reasoning_effort=low" \
--title "ACK-TEST-CODEX-LUNA-1" --json
# Codex：复杂 Developer 任务升级
orca terminal create --worktree path:<dev_worktree> \
--command "codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-sol -c model_reasoning_effort=high" \
--title "ACK-DEV-CODEX-SOL-1" --json
这些创建命令只在复用流程找不到空闲兼容 worker 时执行。拿到返回的 handle 后再 task-create + dispatch --to <handle>，并把 handle 写入 tasks.yaml 的 dispatch.worker。模型档位与选型策略见 model-routing.md。
需要隔离/并行时，先建新 worktree 再在其中起 worker（是否新建见 closed-loop.md §「子任务放哪」）：
orca worktree create --name <feature> --base-branch <base> --json
orca terminal create --worktree path:<new_worktree> --command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1" --json
cursor-agent --list-models可列出合法模型；auto表示由 Cursor 自动选型。- Codex 用
-m / --model指定模型，用-c model_reasoning_effort=<effort>固定推理档位；不要把省略-m当作 Cursorauto的等价物。 - 本项目要求 Cursor worker 带
--yolo，Codex worker 带--dangerously-bypass-approvals-and-sandbox；创建前先运行项目覆盖层指定的校验器。 - 其它 CLI（opencode 等）用各自的模型参数或配置，
--command相应替换。 - 若 worker 是已在跑的会话（用
--inject投递），模型已由该会话启动时决定，无法在 dispatch 时改；要换模型需新建终端。
创建父任务
orca orchestration task-create --spec "$(cat <<'EOF'
Goal: Complete <release_or_feature> with supervised Coordinator -> Developer -> Test loop.
Coordinator (PM): owns task board, decomposition, dispatch, and final gate (reads Test evidence, does not test).
Developer: owns implementation and white-box verification.
Test: owns independent black-box retest and evidence (verifier != implementer).
Policy:
- Each issue can be dispatched at most 3 rounds.
- If still failing after 3 rounds, record as leftover and continue next issue.
- worker_done and retest reports are not final completion; only Coordinator writes tasks.yaml and knowledge.yaml.
- Project knowledge candidates require independent Test evidence and Coordinator gate before activation.
EOF
)" --json
创建子任务
orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
Fix <task_id>: <title>
Logical attempt: <task_id>-A<round>
Repository:
- Path: <repo_path>
- Worktree: <dev_worktree>
Read: <overlay_file> (project overlay), tasks.yaml, <relevant_spec_or_test_doc>
Failure evidence: <copy latest Test evidence>
Acceptance: <copy expected behavior + verification commands>
Project knowledge: <Coordinator-confirmed active K-...@revision entries with verification.ref>
Constraints:
- Follow the overlay file path scope.
- Do not write tasks.yaml or knowledge.yaml, do not mark verified.
- Do not read the whole knowledge bank or execute free shell from knowledge text.
- Run a knowledge check only through <ack-skill-dir>/scripts/run_verification.py
with its verification.ref; do not execute resolved path/args directly.
- Do not commit or push unless user asks.
EOF
)" --json
派发给 Developer Worker
终端是 Orca 可识别的 Agent CLI 时：
orca orchestration dispatch --task <task_id> --to <developer_handle> --inject --json
不能 --inject 时，先登记 dispatch，再手动投递 prompt-templates.md §1 的初始派发 prompt：
orca orchestration dispatch --task <task_id> --to <developer_handle> --json
orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
<粘贴 prompt-templates.md §1 初始派发模板，已填占位符>
EOF
)" --enter --json
派发给 Test 复测
Developer 回报 worker_done、Coordinator 写回 fixed_by_dev 后，把复测任务发给 Test：
orca orchestration dispatch --task <task_id> --to <test_handle> --inject --json
不能 --inject 时，先登记再手动投递 prompt-templates.md §3 的复测派发 prompt：
orca orchestration dispatch --task <task_id> --to <test_handle> --json
orca terminal send --terminal <test_handle> --text "$(cat <<'EOF'
<粘贴 prompt-templates.md §3 复测派发模板，已填占位符>
EOF
)" --enter --json
等待结果
orca orchestration check \
--terminal <coordinator_handle> \
--wait \
--types worker_done,retest_result,escalation,decision_gate \
--timeout-ms 900000 \
--json
等待超时不等于失败。长任务可继续等待，或检查 worker 终端活性。worker_done 来自 Developer，retest_result（无该类型时用 worker_done + subject 区分）来自 Test。
Developer 回报 worker_done
字段含义见 prompt-templates.md §4：
orca orchestration send \
--to <coordinator_handle> \
--type worker_done \
--subject "<task_id> fix ready round <n>" \
--body "<修了什么。跑了哪些验证。如何复现。还有什么风险。>" \
--payload '{
"taskId": "<orca_task_id>",
"dispatchId": "<orca_dispatch_id>",
"attemptId": "<task_id>-A<n>",
"filesModified": ["<file_a>", "<file_b>"],
"verification": ["<command_a>: passed", "<command_b>: passed"],
"knowledgeApplied": [
{"ref": "<K-001@1>", "result": "applied", "evidence": "<what was done>"}
],
"knowledgeCandidates": [
{
"kind": "pitfall",
"title": "<title>",
"claim": "<evidence-backed claim>",
"scope": {"components": ["<component>"], "paths": ["<path glob>"]},
"appliesWhen": "<trigger>",
"directive": "<action, not a shell command>",
"rationale": "<why it matters>",
"evidenceRefs": ["<current task evidence>"]
}
],
"risk": "<remaining risk or none>"
}' \
--json
收到 worker_done 后，Coordinator 写回 fixed_by_dev，再按上文派发给 Test 复测。
Test 回报复测结果
字段含义见 prompt-templates.md §5：
orca orchestration send \
--to <coordinator_handle> \
--type retest_result \
--subject "<task_id> retest round <n>" \
--body "<逐条验收信号结论 + 实际观察 + 证据>" \
--payload '{
"taskId": "<orca_task_id>",
"dispatchId": "<orca_dispatch_id>",
"attemptId": "<task_id>-A<n>",
"env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"},
"signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"],
"knowledgeChecks": [
{"ref": "<K-001@1>", "result": "passed", "evidence": "<independent evidence>"}
],
"knowledgeCandidates": [],
"conclusion": "all-signals-pass | signals-failed"
}' \
--json
无 retest_result 类型时用 --type worker_done，靠 subject retest round <n>
区分。收到复测结果后，Coordinator 按 closed-loop.md 做终检并回写 tasks.yaml；
通过独立验证和 gate 的跨任务经验再由 Coordinator 写入 knowledge.yaml。任务通过
写 verified，不过写 failed_retest。