laily/.pouch

Fork 0

Files

T

laily 076d87e303 refactor: fold ack kit into skill

2026-07-30 11:54:02 +08:00

10 KiB

Raw Blame History

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 当作 Cursor auto 的等价物。
本项目要求 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.
EOF
)" --json

创建子任务

orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
Fix <task_id>: <title>

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 时：

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 §3：

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：

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。

10 KiB Raw Blame History Unescape Escape