350 lines
14 KiB
Markdown
350 lines
14 KiB
Markdown
# 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 可达并取得本次 `runtimeId`；Coordinator 终端存在；当前没有冲突
|
||
的活跃编排任务。Developer/Test worker 先按下节检查安全复用候选；当前 Orca 无可信
|
||
历史清理能力时必须通过本次 launcher 新建。
|
||
|
||
---
|
||
|
||
## 既有 worker 的处理
|
||
|
||
先找同一轮 ACK 内可复用的空闲 worker，再决定是否创建。候选必须同时满足：
|
||
|
||
- Orca 明确报告终端存活且空闲；不得复用仍在工作、等待 `worker_done` / 复测报告 /
|
||
escalation，或运行状态不明的 worker；
|
||
- 没有关联 `blocked`、`failed_retest`、`leftover`、未解决环境事件或其它未完成任务；
|
||
- 角色、profile、worktree、runtime/incarnation 与本次目标完全匹配，Developer 与 Test
|
||
永不互相复用；
|
||
- 受信后端能够清理历史消息，并返回可核对的新 conversation/session identity 和本次
|
||
task/attempt 绑定；只有看到成功回执后才把 worker 视为已重置。
|
||
|
||
`receiptHash` 是无密钥 checksum，标题、preview、分支名、worker 自报或普通 Orca
|
||
terminal metadata 都不能证明历史上下文已清理。任何条件不符、清理接口不存在、清理
|
||
失败或结果无法确认时，都重新 `plan`/`launch` fresh worker。
|
||
|
||
| 情况 | 动作 |
|
||
|------|------|
|
||
| 同轮空闲，身份完全匹配，历史消息清理得到可信回执 | 生成新的 task/attempt 绑定后复用 |
|
||
| worker 正在工作、等待回报、状态不明或关联未完成任务 | 不复用；保留原终端并重新 launch |
|
||
| profile、角色、worktree、runtime/incarnation 任一不匹配 | 不复用；重新 launch |
|
||
| 无历史消息清理能力，或无法确认清理成功 | 不复用；重新 launch |
|
||
| 需要并发 worker | 使用下一 `slot` 重新 launch |
|
||
| Developer 升级模型档位 | 选择强档安全 profile，重新 plan/launch |
|
||
|
||
当前 Orca terminal API 没有返回新会话身份的可信历史消息清理操作，因此当前适配器
|
||
不会复用 Orca worker；仍只使用刚刚成功返回的 `launch` fresh handle。以后后端补齐
|
||
reset/attestation 后才能启用上述复用路径，不能用项目文档声明跳过条件。
|
||
|
||
---
|
||
|
||
## 通过 launcher 创建 worker
|
||
|
||
**模型不由 Orca dispatch 设置。** `task-create` / `dispatch` 只投递任务；Agent CLI、
|
||
模型、reasoning effort 和权限由 `tasks.yaml.project.orchestration` 的结构化 profile
|
||
决定，并且只能由 ACK launcher 构造。
|
||
|
||
先只读生成计划：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/launch_worker.py plan \
|
||
--project-root <project-root> --task-id <task-id> \
|
||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||
--profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99>
|
||
```
|
||
|
||
确认计划中的任务、attempt、角色、profile hash、绝对 worktree 和安全权限模式后，再
|
||
执行唯一启动入口：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/launch_worker.py launch \
|
||
--project-root <project-root> --task-id <task-id> \
|
||
--attempt-id <task-id>-A<round> --role <developer-or-test> \
|
||
--profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99> \
|
||
--expected-launch-fingerprint <plan 中的 sha256:...>
|
||
```
|
||
|
||
`launch` 必须携带刚才审阅的 `plan.launchFingerprint`；若 profile、任务/attempt、
|
||
worktree、CLI identity/version 或精确 argv 漂移，创建前就失败。它内部调用当前
|
||
Orca 后端并完成终端绑定；Coordinator 不自行执行或拼装 Orca 的底层终端创建文本，
|
||
也不直接调用 launcher 的私有 bootstrap。
|
||
若 launcher 报告 `indeterminate` 或 `reconcile required`，说明终端可能已经创建且
|
||
持久关闭尚未得到可信确认；此时先按返回的 launch ID/record 和 Orca live state
|
||
人工核对，禁止直接重复执行 `launch`。
|
||
标准输出是单一 JSON。成功后：
|
||
|
||
1. 校验返回 receipt 的 `receiptHash`；
|
||
2. 把 receipt 原样追加到 `tasks.yaml.workerReceipts`；
|
||
3. 把 `receipt.id` 写入当前任务 `dispatch.<role>.receiptId`，把 `profileId` 写入
|
||
`dispatch.<role>.profileId`，把本轮 `<task-id>-A<round>` 写入
|
||
`dispatch.<role>.attemptId`；校验器会要求 receipt 的 task/role/profile/attempt
|
||
与当前 ACK 任务完全一致；
|
||
4. 再用 receipt binding 中的 handle 创建/派发 Orca 子任务。
|
||
|
||
profile 只允许 `read-only` 或 `workspace-write`。v0.10 不提供可信的 full-access 授权
|
||
通道；bypass、YOLO/force、关闭 sandbox 及其它 full-access 请求必须由 schema 和
|
||
launcher fail closed，不能改用手写命令兜底。模型档位与升级规则见
|
||
`model-routing.md`。
|
||
|
||
需要隔离/并行时，可以先用 Orca 创建 worktree（须与项目根同一 Git 仓库）。
|
||
v0.19 起不再登记 `allowedWorktrees`，直接在该路径上走 `plan` -> 带 expected
|
||
fingerprint 的 `launch`，并把 receipt 留作审计。
|
||
既有会话可以由用户直接操作，但不能进入 ACK v0.10 的自动派发信任路径。
|
||
|
||
---
|
||
|
||
## 创建父任务
|
||
|
||
```bash
|
||
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 have at most 3 valid product-retest rounds.
|
||
- Environment failures are recorded in dispatch.environmentIncidents, reported with the next action, and do not consume a product-retest round.
|
||
- If still failing after 3 valid product 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
|
||
```
|
||
|
||
## 创建子任务
|
||
|
||
```bash
|
||
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 时：
|
||
|
||
```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
|
||
```
|
||
|
||
---
|
||
|
||
## 等待结果：派发后的活性监督
|
||
|
||
派发或手动投递后**不能只依赖 `check --wait` 盲等**：卡在审批提示、投递后未回车、
|
||
命中额度限制的 worker 不会自己发 `worker_done`。先确认 worker 真的开始执行，等待
|
||
期间周期性探测活性。
|
||
|
||
1. 投递后立即确认开始执行：
|
||
- `--inject` 路径：`orca terminal read --terminal <handle>`，确认 TASK 段已出现
|
||
且终端进入工作指示（Working / Running）。
|
||
- 手动投递路径：`orca terminal send` 必须带 `--enter`；投递后同样 read 确认。
|
||
- 确认失败或终端仍停在欢迎提示：按「消息未投递」记录环境失败，不消耗产品轮次。
|
||
2. 等待期间滚动 probe（每 60–120 秒一次）：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/worker_probe.py \
|
||
--task-id <task_id> --terminal <worker_handle>
|
||
```
|
||
|
||
输出 JSON `status`：`running` / `progress` / `stall` / `not-started` / `unknown`。
|
||
3. 探测结果处理：
|
||
- `stall`：读 terminal tail 确认原因（审批 / 模型切换 / 额度限制），按环境失败
|
||
记录 `environmentIncidents` 并做有界恢复；需要用户决定时立即报告。
|
||
- `not-started`：检查是否漏投递或未回车；重新投递或记录环境失败，不占轮次。
|
||
- `running` / `progress`：继续滚动 wait。
|
||
- `unknown`：按 `dispatch-show` 与 Orca live state 人工核对，不自动重试。
|
||
4. `check --wait` 使用短窗口（60–90 秒）而不是 15 分钟：窗口超时是检查点，先 probe
|
||
再决定继续等待、恢复或上报。
|
||
|
||
```bash
|
||
orca orchestration check \
|
||
--terminal <coordinator_handle> \
|
||
--wait \
|
||
--types worker_done,retest_result,escalation,decision_gate \
|
||
--timeout-ms 90000 \
|
||
--json
|
||
```
|
||
|
||
`worker_done` 来自 Developer，`retest_result`（无该类型时用 `worker_done` + subject
|
||
区分）来自 Test。
|
||
|
||
---
|
||
|
||
## Developer 回报 worker_done
|
||
|
||
字段含义见 `prompt-templates.md` §4：
|
||
|
||
```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>",
|
||
"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：
|
||
|
||
```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>",
|
||
"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`；环境无法完成则写
|
||
`dispatch.environmentIncidents`，保持或恢复为 `fixed_by_dev`，不占复验轮次。
|
||
|
||
---
|
||
|
||
## 整轮结束时回收 worker
|
||
|
||
只有 Coordinator 已把本轮最终结论写入 `tasks.yaml` 后才开始回收。统一使用回收脚本，
|
||
不要手工逐个 close：
|
||
|
||
```bash
|
||
# 第一步：dry-run 审阅决策（不关闭任何终端）
|
||
python3 <ack-skill-dir>/scripts/reclaim_workers.py --project-root <project-root>
|
||
|
||
# 第二步：审阅输出后真正回收
|
||
python3 <ack-skill-dir>/scripts/reclaim_workers.py \
|
||
--project-root <project-root> --apply
|
||
```
|
||
|
||
脚本按 receipt 的 `binding.handle` 聚合任务引用，规则固定：
|
||
|
||
- **关闭**：handle 关联的全部任务都为 `verified`，且没有未解决环境事件。
|
||
- **保留（不设置 TTL）**：任一关联任务处于 `open`、`dispatched`、`fixed_by_dev`、
|
||
`retesting`、`blocked`、`failed_retest`、`leftover`，或存在未解决
|
||
`environmentIncidents`，或 receipt 引用未知任务。失败三次的 worker（
|
||
`failed_retest` / `leftover` / `blocked`）按此保留。
|
||
- **不触碰**：`workerReceipts` 之外的 handle（Coordinator 终端、用户 Shell）。
|
||
|
||
`--apply` 时脚本对每个待关闭 handle 执行 `orca terminal show` 核对身份 →
|
||
`orca terminal close --tab` → 重新 `terminal list` 确认 handle 已消失；任何一步
|
||
不确定都保留并标记 `uncertain`，禁止盲目重试。关闭终端不删除 `workerReceipts`、
|
||
dispatch 证据或测试记录；这些仍是审计事实。保留下来的 blocked/failed worker 只在
|
||
后续任务得到验证或用户明确要求清理时回收。
|