197 lines
7.5 KiB
Markdown
197 lines
7.5 KiB
Markdown
# 闭环流程（稳定核心，编排无关）
|
||
|
||
本文件定义**与具体编排工具无关**的三角色协作闭环。运行时调度可以用 Orca（见 `orca-adapter.md`），也可以手动跑（见下方「手动模式」）。
|
||
|
||
原则：调度消息只是运行时载体，**所有结论都必须回写到 `tasks.yaml`**（事实源），不要把消息当最终记录。角色定义见 `roles-and-permissions.md`：Coordinator 只编排、Test 只验证、Developer 只实现。
|
||
|
||
---
|
||
|
||
## 编排抽象
|
||
|
||
无论用什么工具，闭环都由这几个能力组成。注意 `dispatch` 有两个目标（Developer 与 Test）：
|
||
|
||
| 抽象动作 | 含义 | Orca 实现 | 手动实现 |
|
||
|----------|------|-----------|----------|
|
||
| `prepare(task)` | Coordinator 把任务和验收信号写进 `tasks.yaml` | 同左 | 同左 |
|
||
| `dispatch(task, developer)` | 把修复任务连同上下文交给 Developer | `orca orchestration dispatch` | 复制 prompt 到 Developer 终端/会话 |
|
||
| `dispatch(task, test)` | 把复测任务连同验收信号交给 Test | `orca orchestration dispatch` | 复制 prompt 到 Test 终端/会话 |
|
||
| `wait()` | 等待 `worker_done` / `retest_result` / `escalation` / `decision_gate` | `orca orchestration check --wait` | 人工等待回报 |
|
||
| `gate(task)` | Coordinator 读 Test 证据并对齐原始意图（不重测） | 同左 | 同左 |
|
||
| `writeback(task, result)` | Coordinator 把结果写回 `tasks.yaml` | 同左 | 同左 |
|
||
|
||
派发用的 prompt 见 `prompt-templates.md`。状态流转见 `roles-and-permissions.md` §「任务状态机」。**独立复测由 Test 执行，不是 Coordinator**；Coordinator 只做读证据的终检。
|
||
|
||
---
|
||
|
||
## 标准闭环
|
||
|
||
```text
|
||
Coordinator 发现或读取 open 任务
|
||
-> prepare：写/补全 tasks.yaml 验收信号
|
||
-> 决定 worktree：当前 worktree 起子 agent，还是新建隔离 worktree（见下节「子任务放哪」）
|
||
-> 起 worker：按档位建 worker 终端（如 cursor-agent --model auto，见 model-routing.md）
|
||
-> dispatch 给 Developer（--to <worker handle>）
|
||
-> wait：Developer 的 worker_done / escalation
|
||
-> writeback fixed_by_dev
|
||
-> dispatch 给 Test（retesting）
|
||
-> wait：Test 的 retest_result
|
||
-> Test 通过：gate（Coordinator 读证据对齐意图）
|
||
-> 通过 gate：writeback verified
|
||
-> gate 不满足意图：writeback failed_retest，带意图差异再派发 Developer
|
||
-> Test 失败：writeback failed_retest，追加证据，再派发 Developer（最多累计三轮）
|
||
-> 累计三轮失败：writeback leftover，继续下一个任务
|
||
```
|
||
|
||
一次派发只修一个明确问题（细则见 `optimization-method.md` §「每轮派发只修一个明确问题」）。
|
||
「决定 worktree」「起 worker」两步的决策见下节与 `model-routing.md` / `orca-adapter.md`。
|
||
|
||
---
|
||
|
||
## 子任务放哪：新 worktree 还是当前 worktree
|
||
|
||
Coordinator 派发前先决定 Developer/Test 在哪工作。两种方式：
|
||
|
||
**方式 1：当前 worktree 起子 agent（终端）**
|
||
|
||
```bash
|
||
orca terminal create --worktree active --command "cursor-agent --model auto" --json
|
||
```
|
||
|
||
- 适合：串行闭环、一次一个 Developer 任务、小改动、Test 要复测的正是 Developer 改的那棵树。
|
||
- 优点：单一服务实例、无跨 worktree 对齐困扰、开销小。
|
||
- 风险：多个 agent 同时改同一棵树会互相踩（半构建状态、git 冲突）。
|
||
|
||
**方式 2：新建隔离 worktree，再在其中起子 agent**
|
||
|
||
```bash
|
||
orca worktree create --name <feature> --base-branch <base> --json
|
||
# 然后在新 worktree 内 orca terminal create --worktree path:<new> --command "cursor-agent --model auto"
|
||
```
|
||
|
||
- 适合：并行多个互不依赖的子任务、大/高风险/实验性改动、要保持基线分支干净（如 prod 不动、feature 走独立分支）、要独立 build 或跑独立服务实例、best-of-N 尝试。
|
||
- 优点：隔离 + 并行 + 易回滚（删 worktree 即可）。
|
||
- 成本：各自 build/依赖、服务要用不同端口、必须处理下节的 worktree/服务对齐。
|
||
|
||
**决策速查：**
|
||
|
||
| 情况 | 选择 |
|
||
|------|------|
|
||
| 一次一个任务、串行修复 | 当前 worktree 子 agent |
|
||
| 多个任务并行、互不依赖 | 每个任务一个新 worktree |
|
||
| 高风险 / 实验 / 可能整体丢弃 | 新 worktree |
|
||
| 要保持基线分支干净 | 新 worktree（feature 分支）|
|
||
| 小改动、追求快 | 当前 worktree |
|
||
|
||
**任务板（SSOT）只落一处**：无论开几个 worktree，`tasks.yaml` 只认一个权威副本（通常在基线/协调所在 worktree），由 Coordinator 单写。不要每个 worktree 各留一份会分叉的任务板。模型固定方式见 `model-routing.md` 与 `orca-adapter.md`。
|
||
|
||
---
|
||
|
||
## 手动模式（无 Orca）
|
||
|
||
没有编排工具时，闭环不变，只是 `dispatch` / `wait` 由人工承担：
|
||
|
||
1. Coordinator 在 `tasks.yaml` 写好任务和验收信号。
|
||
2. 用 `prompt-templates.md` §1 的初始派发模板生成 prompt，手动发给 Developer（另一个会话/终端/人）。
|
||
3. Developer 完成后按 worker_done 模板回报。
|
||
4. Coordinator 写回 `fixed_by_dev`，用 `prompt-templates.md` §3 的复测派发模板把任务发给 Test。
|
||
5. Test 独立复测后按复测报告模板回报证据。
|
||
6. Coordinator 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed_retest`。
|
||
7. 失败则用「复测失败再派发模板」重新发给 Developer，最多累计三轮。
|
||
|
||
手动模式下同样遵守：worker_done / 复测报告都不等于最终结论、只有 Coordinator 写 `tasks.yaml`、三轮失败留档。
|
||
|
||
---
|
||
|
||
## Test 复测（编排无关）
|
||
|
||
即使 Developer 的 worker_done 写了"全部通过"，Test 仍必须独立复测：
|
||
|
||
```bash
|
||
git status --short
|
||
<test_commands>
|
||
curl -s <base_url>/health-or-summary
|
||
```
|
||
|
||
浏览器复测建议记录：
|
||
|
||
```text
|
||
BASE_URL:
|
||
page:
|
||
steps:
|
||
expected:
|
||
actual:
|
||
snapshot evidence:
|
||
```
|
||
|
||
Test 只回传证据，不写 `tasks.yaml`；由 Coordinator 落盘。
|
||
|
||
---
|
||
|
||
## Coordinator 终检（gate）
|
||
|
||
Test 报通过后，Coordinator 不重测，而是做一次读证据的终检：
|
||
|
||
- Test 证据是否覆盖了任务的**每一条**验收信号（见 `optimization-method.md` §1）。
|
||
- 结果是否符合任务的**原始意图**，而不只是通过了字面文案。
|
||
- 运行环境是否对齐（见下方「服务与 worktree 对齐」）。
|
||
|
||
终检不通过（例如意图漂移、验收信号写漏）时，回写 `failed_retest` 并把意图差异带给下一轮 Developer，必要时先补全验收信号。
|
||
|
||
---
|
||
|
||
## 服务与 worktree 对齐（防假通过/假失败）
|
||
|
||
Test 复测前记录运行环境：
|
||
|
||
```bash
|
||
pwd
|
||
git rev-parse --abbrev-ref HEAD
|
||
git rev-parse --short HEAD
|
||
```
|
||
|
||
```text
|
||
serverPid:
|
||
serverCommand:
|
||
BASE_URL:
|
||
frontendDir:
|
||
worktreePath:
|
||
```
|
||
|
||
如果开发在 `<dev_worktree>` 修复，但服务跑的是另一个 worktree，必须**停止并重启正确服务**后再测。长跑服务或静态前端尤其要确认加载的是最新构建产物。
|
||
|
||
---
|
||
|
||
## 结果回写
|
||
|
||
Coordinator 回写 `tasks.yaml` 时按状态填写（字段结构见 `templates/tasks.schema.json`）：
|
||
|
||
```yaml
|
||
# 通过（Test 复测 + Coordinator 终检）
|
||
status: verified
|
||
resolution:
|
||
verifiedAt: "<timestamp>"
|
||
verifiedBy: "test"
|
||
evidence:
|
||
verification: "<commands passed>"
|
||
browser: "<snapshot or API evidence>"
|
||
```
|
||
|
||
```yaml
|
||
# 失败但未满三轮
|
||
status: failed_retest
|
||
dispatch:
|
||
rounds:
|
||
- round: 1
|
||
result: failed
|
||
evidence: "<latest evidence from Test or gate>"
|
||
```
|
||
|
||
```yaml
|
||
# 累计三轮失败
|
||
status: leftover
|
||
resolution:
|
||
leftoverReason: "failed after 3 supervised developer rounds"
|
||
evidence:
|
||
final: "<latest failing evidence>"
|
||
```
|