feat: add agent-collaboration-kit

2026-07-06 09:24:22 +08:00
parent f1ed320991
commit c4c68572c3
8 changed files with 970 additions and 0 deletions
@@ -0,0 +1,229 @@
+# 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>"
+```