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> Constraints: - Follow the overlay file path scope. - Do not write tasks.yaml, do not mark verified. - Do not commit or push unless user asks. EOF )" --json ``` --- ## 派发给 Developer Worker 终端是 Orca 可识别的 Agent CLI 时： ```bash orca orchestration dispatch --task <task_id> --to <developer_handle> --inject --json ``` 不能 `--inject` 时，先登记 dispatch，再手动投递 `prompt-templates.md` §1 的初始派发 prompt： ```bash 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： ```bash orca orchestration dispatch --task <task_id> --to <test_handle> --inject --json ``` 不能 `--inject` 时，先登记再手动投递 `prompt-templates.md` §3 的复测派发 prompt： ```bash 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 ``` --- ## 等待结果 ```bash 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` §3： ```bash 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>", "filesModified": ["<file_a>", "<file_b>"], "verification": ["<command_a>: passed", "<command_b>: passed"], "risk": "<remaining risk or none>" }' \ --json ``` 收到 worker_done 后，Coordinator 写回 `fixed_by_dev`，再按上文派发给 Test 复测。 --- ## Test 回报复测结果字段含义见 `prompt-templates.md` §5： ```bash 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>", "env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"}, "signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"], "conclusion": "all-signals-pass | signals-failed" }' \ --json ``` 无 `retest_result` 类型时用 `--type worker_done`，靠 subject `retest round <n>` 区分。收到复测结果后，Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed

# Orca 适配器（稳定核心，一种编排实现） Orca orchestration 是运行时调度层的一种实现。闭环流程本身与工具无关（见 `closed-loop.md`）；本文件只提供 Orca 的具体命令。没有 Orca 时用 `closed-loop.md` §「手动模式」。所有结论仍以 `tasks.yaml` 为准，Orca 消息不是最终记录。 --- ## 何时用 Orca 编排用：需要监督、等待结果、闭环修复、三轮重试；有多个可独立派发的任务；需要 `worker_done` 后再复测。不用：单次问答；用户只要求完整 handoff 不需监督；不需要复测的小改动。 --- ## 运行前检查 ```bash 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`： 1. 运行 `orca terminal list --json`，筛选 `connected=true`、`writable=true`、目标 `worktreePath` 一致、标题角色和配置一致的终端。稳定标题使用 `ACK----`，例如 `ACK-DEV-CODEX-TERRA-1`、`ACK-TEST-CODEX-LUNA-1`、`ACK-DEV-CURSOR-AUTO-1`；强档示例为 `ACK-DEV-CODEX-SOL-1`。 2. 运行 `orca orchestration task-list --status dispatched --json`。若候选 handle 出现在活跃任务的 `assignee_handle`，视为 busy，不复用；不要仅凭终端预览文本或最近输出时间猜忙闲。 3. 对空闲候选运行 `orca terminal show --terminal --json`，确认仍存活且 worktree、角色和 Agent CLI / 模型档位符合本次要求。符合就直接把该 handle 作为 `dispatch --to` 的目标。 4. 只有不存在兼容的空闲候选时才创建。若同角色同配置已有 busy worker，使用下一个未占用序号，例如 `ACK-DEV-CODEX-TERRA-2`；不要创建另一个同名终端。 5. 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 ` 只是把任务投给一个已存在的终端，用的是那个终端里 agent 会话启动时的模型。要固定模型，就在 **创建 worker 终端** 时用 agent CLI 的模型参数：默认沿用 Coordinator 当前所在的 Agent CLI：Cursor Coordinator 创建 Cursor worker，Codex Coordinator 创建 Codex worker。不要通过询问模型来猜运行环境；以当前 CLI / 终端环境为准。除非项目 overlay 或用户明确指定，否则不跨 Agent CLI 创建 worker。 ```bash # Cursor：Test / Developer worker 用 auto 模型，并按项目要求启用 YOLO orca terminal create --worktree path: \ --command "cursor-agent --yolo --model auto" --title "ACK-DEV-CURSOR-AUTO-1" --json # 需要更强模型时改成具体模型 orca terminal create --worktree path: \ --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: \ --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: \ --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: \ --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 写入 `tasks.yaml` 的 `dispatch.worker`。模型档位与选型策略见 `model-routing.md`。需要隔离/并行时，先建新 worktree 再在其中起 worker（是否新建见 `closed-loop.md` §「子任务放哪」）： ```bash orca worktree create --name --base-branch --json orca terminal create --worktree path: --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=` 固定推理档位；不要把省略 `-m` 当作 Cursor `auto` 的等价物。 - 本项目要求 Cursor worker 带 `--yolo`，Codex worker 带 `--dangerously-bypass-approvals-and-sandbox`；创建前先运行项目覆盖层指定的校验器。 - 其它 CLI（opencode 等）用各自的模型参数或配置，`--command` 相应替换。 - 若 worker 是已在跑的会话（用 `--inject` 投递），模型已由该会话启动时决定，无法在 dispatch 时改；要换模型需新建终端。 --- ## 创建父任务 ```bash orca orchestration task-create --spec "$(cat <<'EOF' Goal: Complete 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. EOF )" --json ``` ## 创建子任务 ```bash orca orchestration task-create --parent --spec "$(cat <<'EOF' Fix : 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> Constraints: - Follow the overlay file path scope. - Do not write tasks.yaml, do not mark verified. - Do not commit or push unless user asks. EOF )" --json ``` --- ## 派发给 Developer Worker 终端是 Orca 可识别的 Agent CLI 时： ```bash orca orchestration dispatch --task <task_id> --to <developer_handle> --inject --json ``` 不能 `--inject` 时，先登记 dispatch，再手动投递 `prompt-templates.md` §1 的初始派发 prompt： ```bash 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： ```bash orca orchestration dispatch --task <task_id> --to <test_handle> --inject --json ``` 不能 `--inject` 时，先登记再手动投递 `prompt-templates.md` §3 的复测派发 prompt： ```bash 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 ``` --- ## 等待结果 ```bash 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` §3： ```bash 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>", "filesModified": ["<file_a>", "<file_b>"], "verification": ["<command_a>: passed", "<command_b>: passed"], "risk": "<remaining risk or none>" }' \ --json ``` 收到 worker_done 后，Coordinator 写回 `fixed_by_dev`，再按上文派发给 Test 复测。 --- ## Test 回报复测结果字段含义见 `prompt-templates.md` §5： ```bash 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>", "env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"}, "signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"], "conclusion": "all-signals-pass | signals-failed" }' \ --json ``` 无 `retest_result` 类型时用 `--type worker_done`，靠 subject `retest round <n>` 区分。收到复测结果后，Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed_retest`。