Files

T

laily 58de2650c2 docs: separate agent collaboration kit from skills

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-06 09:32:50 +08:00

4.6 KiB

Raw Blame History

Orca Closed Loop Workflow

Orca orchestration 是运行时调度层，tasks.yaml 是持久事实源。不要把 Orca 消息当成最终记录；所有结论都要回写任务板。

什么时候使用 Orca 编排

使用：

用户要求监督、等待结果、闭环修复、三轮重试。
有多个 bug 或多个可独立派发的任务。
Product/Test 与 Developer 需要明确分工。
需要 worker_done 后再复测。

不使用：

单次问答。
用户只是要求完整 handoff，不需要你监督。
不需要测试和复测的小改动。

标准闭环

Product/Test 发现或读取 open 任务
  -> 写入/补全 tasks.yaml 验收标准
  -> 创建 Orca task
  -> dispatch 给 Developer Worker
  -> 等待 worker_done / escalation / decision_gate
  -> Product/Test 构建并复测
  -> 通过：verified
  -> 失败：failed_retest，追加证据，最多再派发两轮
  -> 三轮失败：leftover，继续下一个任务

运行前检查

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。
当前没有会冲突的活跃编排任务。

创建父任务

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

创建子任务

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：

orca orchestration dispatch \
  --task <task_id> \
  --to <developer_handle> \
  --inject \
  --json

如果不能 --inject，先登记 dispatch，再手动发送带上下文的 prompt：

orca orchestration dispatch \
  --task <task_id> \
  --to <developer_handle> \
  --json

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

等待结果

orca orchestration check \
  --terminal <coordinator_handle> \
  --wait \
  --types worker_done,escalation,decision_gate \
  --timeout-ms 900000 \
  --json

等待超时不等于失败。长任务可以继续等待，或检查 worker 终端活性。

worker_done 后复测

Product/Test 必须自己验证：

git status --short
<test_commands>
curl -s <base_url>/health-or-summary

浏览器复测建议记录：

BASE_URL:
page:
steps:
expected:
actual:
snapshot evidence:

服务与 worktree 对齐

复测前记录：

pwd
git rev-parse --abbrev-ref HEAD
git rev-parse --short HEAD

记录服务：

serverPid:
serverCommand:
BASE_URL:
frontendDir:
worktreePath:

如果开发在 <dev_worktree> 修复，但服务跑的是另一个 worktree，必须停止并重启正确服务后再测。

结果回写

通过：

status: verified
verifiedAt: "<timestamp>"
evidence:
  verification: "<commands passed>"
  browser: "<snapshot or API evidence>"

失败但未满三轮：

status: failed_retest
attempts:
  - round: 1
    result: failed
    evidence: "<latest evidence>"

三轮失败：

status: leftover
leftoverReason: "failed after 3 supervised developer rounds"
evidence:
  final: "<latest failing evidence>"

4.6 KiB Raw Blame History Unescape Escape