230 lines
4.6 KiB
Markdown
230 lines
4.6 KiB
Markdown
# Orca Closed Loop Workflow
|
||
|
||
Orca orchestration 是运行时调度层，`tasks.yaml` 是持久事实源。不要把 Orca 消息当成最终记录；所有结论都要回写任务板。
|
||
|
||
## 什么时候使用 Orca 编排
|
||
|
||
使用：
|
||
|
||
- 用户要求监督、等待结果、闭环修复、三轮重试。
|
||
- 有多个 bug 或多个可独立派发的任务。
|
||
- Product/Test 与 Developer 需要明确分工。
|
||
- 需要 `worker_done` 后再复测。
|
||
|
||
不使用：
|
||
|
||
- 单次问答。
|
||
- 用户只是要求完整 handoff，不需要你监督。
|
||
- 不需要测试和复测的小改动。
|
||
|
||
## 标准闭环
|
||
|
||
```text
|
||
Product/Test 发现或读取 open 任务
|
||
-> 写入/补全 tasks.yaml 验收标准
|
||
-> 创建 Orca task
|
||
-> dispatch 给 Developer Worker
|
||
-> 等待 worker_done / escalation / decision_gate
|
||
-> Product/Test 构建并复测
|
||
-> 通过：verified
|
||
-> 失败：failed_retest，追加证据，最多再派发两轮
|
||
-> 三轮失败：leftover，继续下一个任务
|
||
```
|
||
|
||
## 运行前检查
|
||
|
||
```bash
|
||
orca status --json
|
||
orca terminal list --json
|
||
orca orchestration task-list --json
|
||
orca orchestration inbox --limit 20 --json
|
||
```
|
||
|
||
确认：
|
||
|
||
- Orca runtime 可达。
|
||
- Coordinator 终端和 Developer Worker 终端都存在。
|
||
- Developer Worker 在正确 worktree。
|
||
- 当前没有会冲突的活跃编排任务。
|
||
|
||
## 创建父任务
|
||
|
||
```bash
|
||
orca orchestration task-create --spec "$(cat <<'EOF'
|
||
Goal: Complete <release_or_feature> with supervised Product/Test -> Developer loop.
|
||
|
||
Coordinator:
|
||
- Owns task board, black-box tests, retest, final verification.
|
||
|
||
Developer:
|
||
- Owns implementation and white-box verification.
|
||
|
||
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 is not final completion.
|
||
EOF
|
||
)" --json
|
||
```
|
||
|
||
## 创建子任务
|
||
|
||
```bash
|
||
orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
|
||
Fix <task_id>: <title>
|
||
|
||
Repository:
|
||
- Path: <repo_path>
|
||
- Worktree: <dev_worktree>
|
||
|
||
Read:
|
||
- AGENTS.md
|
||
- tasks.yaml
|
||
- <relevant_spec_or_test_doc>
|
||
|
||
Failure evidence:
|
||
- <copy latest Product/Test evidence>
|
||
|
||
Acceptance:
|
||
- <copy expected behavior>
|
||
- <copy verification commands>
|
||
|
||
Constraints:
|
||
- Follow AGENTS.md path scope.
|
||
- 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：
|
||
|
||
```bash
|
||
orca orchestration dispatch \
|
||
--task <task_id> \
|
||
--to <developer_handle> \
|
||
--json
|
||
```
|
||
|
||
```bash
|
||
orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
|
||
You are receiving a supervised Orca task.
|
||
|
||
taskId: <task_id>
|
||
dispatchId: <dispatch_id>
|
||
coordinator: <coordinator_handle>
|
||
|
||
Task:
|
||
- Fix <task_id>: <title>
|
||
|
||
Acceptance:
|
||
- <expected behavior>
|
||
|
||
Verification:
|
||
- <test_commands>
|
||
|
||
When done, send exactly one worker_done:
|
||
orca orchestration send --to <coordinator_handle> --type worker_done --subject "<task_id> fixed" --body "<summary>" --payload '{"taskId":"<task_id>","dispatchId":"<dispatch_id>","filesModified":["<paths>"],"verification":["<commands>"]}' --json
|
||
EOF
|
||
)" --enter --json
|
||
```
|
||
|
||
## 等待结果
|
||
|
||
```bash
|
||
orca orchestration check \
|
||
--terminal <coordinator_handle> \
|
||
--wait \
|
||
--types worker_done,escalation,decision_gate \
|
||
--timeout-ms 900000 \
|
||
--json
|
||
```
|
||
|
||
等待超时不等于失败。长任务可以继续等待，或检查 worker 终端活性。
|
||
|
||
## worker_done 后复测
|
||
|
||
Product/Test 必须自己验证：
|
||
|
||
```bash
|
||
git status --short
|
||
<test_commands>
|
||
curl -s <base_url>/health-or-summary
|
||
```
|
||
|
||
浏览器复测建议记录：
|
||
|
||
```text
|
||
BASE_URL:
|
||
page:
|
||
steps:
|
||
expected:
|
||
actual:
|
||
snapshot evidence:
|
||
```
|
||
|
||
## 服务与 worktree 对齐
|
||
|
||
复测前记录：
|
||
|
||
```bash
|
||
pwd
|
||
git rev-parse --abbrev-ref HEAD
|
||
git rev-parse --short HEAD
|
||
```
|
||
|
||
记录服务：
|
||
|
||
```text
|
||
serverPid:
|
||
serverCommand:
|
||
BASE_URL:
|
||
frontendDir:
|
||
worktreePath:
|
||
```
|
||
|
||
如果开发在 `<dev_worktree>` 修复，但服务跑的是另一个 worktree，必须停止并重启正确服务后再测。
|
||
|
||
## 结果回写
|
||
|
||
通过：
|
||
|
||
```yaml
|
||
status: verified
|
||
verifiedAt: "<timestamp>"
|
||
evidence:
|
||
verification: "<commands passed>"
|
||
browser: "<snapshot or API evidence>"
|
||
```
|
||
|
||
失败但未满三轮：
|
||
|
||
```yaml
|
||
status: failed_retest
|
||
attempts:
|
||
- round: 1
|
||
result: failed
|
||
evidence: "<latest evidence>"
|
||
```
|
||
|
||
三轮失败：
|
||
|
||
```yaml
|
||
status: leftover
|
||
leftoverReason: "failed after 3 supervised developer rounds"
|
||
evidence:
|
||
final: "<latest failing evidence>"
|
||
```
|