feat(ack): shard task records for merge-safe workspaces
This commit is contained in:
@@ -2,7 +2,8 @@
|
||||
|
||||
本文件定义**与具体编排工具无关**的三角色协作闭环。运行时调度可以用 Orca（见 `orca-adapter.md`），也可以手动跑（见下方「手动模式」）。
|
||||
|
||||
原则：调度消息只是运行时载体，任务结论必须回写到 `tasks.yaml`；已经验证且可跨
|
||||
原则：调度消息只是运行时载体，任务结论必须追加到 `task-records/`（由读取层
|
||||
materialize 成任务视图）；已经验证且可跨
|
||||
任务使用的项目经验必须由 Coordinator 回写到 `knowledge.yaml`。不要把消息当最终记录。
|
||||
角色定义见 `roles-and-permissions.md`：Coordinator 只编排、Test 只验证、
|
||||
Developer 只实现。
|
||||
@@ -15,12 +16,12 @@ Developer 只实现。
|
||||
|
||||
| 抽象动作 | 含义 | Orca 实现 | 手动实现 |
|
||||
|----------|------|-----------|----------|
|
||||
| `prepare(task)` | Coordinator 把任务和验收信号写进 `tasks.yaml`，按 scope 推荐知识并确认显式 `knowledgeRefs` | 同左 | 同左 |
|
||||
| `prepare(task)` | Coordinator 把任务和验收信号写进 `task-records/`，按 scope 推荐知识并确认显式 `knowledgeRefs` | 同左 | 同左 |
|
||||
| `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 证据、`knowledgeChecks` 并对齐原始意图（不重测） | 同左 | 同左 |
|
||||
| `writeback(task, result)` | Coordinator 把任务结果写回 `tasks.yaml`，把验证通过的跨任务经验按权限写入 `knowledge.yaml` | 同左 | 同左 |
|
||||
| `writeback(task, result)` | Coordinator 把任务结果追加到 `task-records/`，把验证通过的跨任务经验按权限写入 `knowledge.yaml` | 同左 | 同左 |
|
||||
|
||||
派发用的 prompt 见 `prompt-templates.md`。状态流转见 `roles-and-permissions.md` §「任务状态机」。**独立复测由 Test 执行，不是 Coordinator**；Coordinator 只做读证据的终检。
|
||||
|
||||
@@ -30,14 +31,14 @@ Developer 只实现。
|
||||
|
||||
```text
|
||||
Coordinator 发现或读取 open 任务
|
||||
-> prepare：写/补全 tasks.yaml 验收信号
|
||||
-> prepare：写/补全 task-records/ 中的任务验收信号
|
||||
-> 从 knowledge.yaml 按 scope 推荐 active 知识，Coordinator 确认固定 revision 的 knowledgeRefs
|
||||
-> 为新轮次生成稳定 attemptId（<task-id>-A<round>），Developer 与 Test 共用
|
||||
-> 决定 worktree：当前 worktree 起子 agent，还是新建隔离 worktree（见下节「子任务放哪」）
|
||||
-> 解析安全 profile：机器配置只读 agents.yaml（存在时），否则读取 tasks.yaml.project.orchestration
|
||||
-> 运行 launcher plan 并审阅 launchFingerprint
|
||||
-> 检查同轮空闲 worker；可信清理历史消息成功才复用，否则带 expected fingerprint 启动 fresh worker
|
||||
-> 把本次 task/attempt receipt 写回 tasks.yaml（见 orca-adapter.md）
|
||||
-> 把本次 task/attempt receipt 追加到 task-records/（见 orca-adapter.md）
|
||||
-> dispatch 给 Developer（--to <worker handle>）
|
||||
-> 确认 Developer 已开始执行（terminal read 确认任务注入；未开始按环境失败处理）
|
||||
-> wait：滚动 check --wait + 定期 worker_probe（识别审批/未回车/额度停滞）
|
||||
@@ -133,7 +134,7 @@ python3 <ack-skill-dir>/scripts/launch_worker.py launch \
|
||||
- 适合：串行闭环、一次一个 Developer 任务、小改动、Test 要复测的正是 Developer 改的那棵树。
|
||||
- 优点：单一服务实例、无跨 worktree 对齐困扰、开销小。
|
||||
- 风险：多个 agent 同时改同一棵树会互相踩（半构建状态、git 冲突）。
|
||||
- 记录：`launch` 成功后把 receipt 追加到权威 `tasks.yaml.workerReceipts`，并把
|
||||
- 记录：`launch` 成功后把 receipt 追加到当前任务记录的 `workerReceipts`，并把
|
||||
`receipt.id` 写入 `dispatch.<role>.receiptId`、把 `profileId` 写入
|
||||
`dispatch.<role>.profileId`、把本轮稳定 ID 写入 `dispatch.<role>.attemptId`；
|
||||
receipt 的 task/role/profile/attempt 必须与当前 dispatch 完全一致，不能只记录
|
||||
@@ -173,9 +174,10 @@ python3 <ack-skill-dir>/scripts/launch_worker.py launch \
|
||||
| 要保持基线分支干净 | 新 worktree（feature 分支）|
|
||||
| 小改动、追求快 | 当前 worktree |
|
||||
|
||||
**项目状态（SSOT）只落一处**：无论开几个 worktree，`tasks.yaml`、
|
||||
**项目配置 SSOT 只落一处**：无论开几个 worktree，`tasks.yaml`、
|
||||
`knowledge.yaml`、可选 `delivery.yaml` 和可选 `regression.yaml` 都只认一个权威
|
||||
副本（通常在基线/协调所在 worktree）。Coordinator 单写任务、知识、回归目录、
|
||||
副本（通常在基线/协调所在 worktree）。任务执行状态追加到
|
||||
`.pouch/ack/task-records/<recordId>.yaml`；Coordinator 单写任务记录、知识、回归目录、
|
||||
`deliveryRuns` 与 `regressionRuns`；交付能力只在显式配置维护时修改。`project.orchestration`、顶层 `workerReceipts` 和任务 dispatch 也只写入这个
|
||||
副本；不要每个 worktree 各留一份会分叉的项目状态。profile 解析、launcher 与
|
||||
receipt 规则见 `model-routing.md` 和 `orca-adapter.md`。
|
||||
@@ -190,20 +192,20 @@ v0.10 的 full-access 授权与撤销机制仍是 Deferred；launcher 遇到 ful
|
||||
|
||||
没有编排工具时，闭环不变，只是 `dispatch` / `wait` 由人工承担：
|
||||
|
||||
1. Coordinator 在 `tasks.yaml` 写好任务和验收信号。
|
||||
1. Coordinator 在 `task-records/` 写入包含完整任务快照的初始记录和验收信号。
|
||||
2. 从 `knowledge.yaml` 推荐相关 active 知识，Coordinator 确认固定 revision 的
|
||||
`knowledgeRefs`；用 `prompt-templates.md` §1 的初始派发模板生成 prompt，
|
||||
手动发给 Developer（另一个会话/终端/人）。
|
||||
3. Developer 完成后按 worker_done 模板回报。
|
||||
4. Coordinator 写回 `fixed_by_dev`，用 `prompt-templates.md` §3 的复测派发模板把任务发给 Test。
|
||||
5. Test 独立复测后按复测报告模板回报证据和 `knowledgeChecks`。
|
||||
6. Coordinator 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed_retest`。
|
||||
6. Coordinator 做终检并追加新记录：通过 `verified`，不过 `failed_retest`。
|
||||
7. 产品失败则用「复测失败再派发模板」重新发给 Developer，最多累计三轮有效产品
|
||||
复验；环境失败写入 `dispatch.environmentIncidents`，恢复环境后重新派发 Test，
|
||||
不派 Developer、不消耗产品轮次。
|
||||
|
||||
手动模式下同样遵守：worker_done / 复测报告都不等于最终结论、只有 Coordinator
|
||||
写 `tasks.yaml` 和 `knowledge.yaml`、三轮失败留档。若本次确认计划还包含交付，所有
|
||||
写 `task-records/` 和 `knowledge.yaml`、三轮失败留档。若本次确认计划还包含交付，所有
|
||||
选中任务 `verified` 后由 Coordinator 继续按 `delivery.md` 执行并写 `deliveryRuns`。
|
||||
|
||||
手动交给用户已打开的会话不等于产生 ACK receipt。该会话可以完成本次显式 handoff，
|
||||
@@ -233,7 +235,7 @@ actual:
|
||||
snapshot evidence:
|
||||
```
|
||||
|
||||
Test 只回传证据，不写 `tasks.yaml` 或 `knowledge.yaml`；由 Coordinator 落盘。
|
||||
Test 只回传证据，不写 `task-records/` 或 `knowledge.yaml`；由 Coordinator 追加落盘。
|
||||
每条适用的显式 `knowledgeRef` 还应报告 `passed`、`failed` 或
|
||||
`not_applicable` 及证据。
|
||||
|
||||
@@ -277,7 +279,8 @@ worktreePath:
|
||||
|
||||
## 结果回写
|
||||
|
||||
Coordinator 回写 `tasks.yaml` 时按状态填写（字段结构见 `templates/tasks.schema.json`）：
|
||||
Coordinator 追加任务记录时按状态填写（记录内的 `task` 字段结构见
|
||||
`templates/tasks.schema.json`）：
|
||||
|
||||
```yaml
|
||||
# 通过（Test 复测 + Coordinator 终检）
|
||||
|
||||
Reference in New Issue
Block a user