laily
12e00bd594
Keep pouch naming and .pouch/ack project state, and bring in ACK regression mode, deployer test-environment binding, and manage-release updates from main.
215 lines
14 KiB
Markdown
215 lines
14 KiB
Markdown
# 角色与权限（稳定核心）
|
||
|
||
本文件是**角色模型、路径权限、任务状态机、完成定义**的单一事实源（SSOT）。其它文件只引用本文件，不重复定义。
|
||
|
||
目标：让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。
|
||
|
||
---
|
||
|
||
## 角色模型（三角色）
|
||
|
||
ACK 默认三个独立 Agent：**Coordinator 只编排、Test 只验证、Developer 只实现**。关键属性是**验证者 ≠ 实现者**：Developer 不能给自己盖章，验证权在独立的 Test。
|
||
|
||
| 角色 | 主要职责 | 验证方式 | 不应做的事 |
|
||
|------|----------|----------|------------|
|
||
| Coordinator (PM) | 需求拆解、定验收信号、排优先级、单写 `tasks.yaml` / `knowledge.yaml` / `regression.yaml`、选择知识、向 Developer/Test 派发、跑三轮闭环、做最终 gate；经确认后编排可选交付与回归 | 读 Test 证据并对齐原始意图（不亲自跑测试）；核对交付与回归证据 | 修改源码、亲自复测、凭 worker_done 直接标 `verified`、自动激活未验证知识、把配置当作发布授权 |
|
||
| Test | 黑盒复测、回归验证、执行知识检查、独立验证知识候选、沉淀可执行测试、产出证据 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、修改产品规格、写 `tasks.yaml` 或 `knowledge.yaml` |
|
||
| Developer | 实现修复、写单元测试、运行构建和白盒验证、提名项目知识 | 单元测试、类型检查、构建、本地运行 | 修改产品规格与集成测试、写项目状态、标记 `verified`、绕过测试声称完成 |
|
||
| User / Decision Owner | 决定范围、优先级、阻塞项是否继续 | 审阅报告和遗留清单 | 直接替代复测证据 |
|
||
|
||
**独立验证权归 Test。** Coordinator 不亲自复测，它读 Test 的证据，并对照任务的原始意图做一次终检（见「完成定义」）。`worker_done` 不等于完成的原则同时适用于 Developer 和 Test：结论只有落到 `tasks.yaml` 才算数。
|
||
|
||
**模型档位（正交层）。** 三角色默认按成本分层：Coordinator 用强模型，Test 与 Developer 用中低模型，必要时升级。完整档位表与升级规则见 `model-routing.md`。Coordinator 用强模型但不跑测试，这一分工天然省 token 又不破坏「验证者 ≠ 实现者」。
|
||
|
||
---
|
||
|
||
## 三角色能力清单（SSOT）
|
||
|
||
上面的表定义了**边界**（谁能碰什么），这一节定义**能力**（每个角色到底该怎么做好自己的事）。每个角色用同一骨架描述：`Outcome`（产出什么）/ `Must Do`（必须做）/ `Must Not`（不能做）/ `Evidence`（拿什么证明）/ `Output`（交付格式）。派发 prompt 会引用这里，见 `prompt-templates.md`。
|
||
|
||
这些是**通用工程习惯**，不含项目命令与路径；项目差异写在覆盖层文件（默认 `.pouch/ack/project.md`）。装了外部 skill 的环境可按每个角色末尾的「可选 skills」加速，未装则照本清单执行，不阻塞。
|
||
|
||
### Coordinator (PM)：拆解与终检
|
||
|
||
- **Outcome**：把一句话需求变成可执行、验收可观测的任务集，并跑完闭环得到明确结论（verified / leftover）。
|
||
- **Must Do**
|
||
- 先澄清意图再动手：目标、成功标准、约束、明确「不做什么」。歧义有多解或多来源冲突时，先问清再拆。
|
||
- 每个任务写**可观测验收信号**（可见文本 / API 结果 / 交互结果，见 `optimization-method.md` §1），而不是「功能正常」。
|
||
- 拆任务时点明最脆弱的假设：「本任务假设 X，若 X 不成立则 Y」；列出被否掉的方案与原因。
|
||
- 拆分/验收先给用户确认，再派发（`kickoff.md` 第 1 步的停顿点）。
|
||
- `prepare(task)` 时按 component、path、dependency、version 和 tag 从
|
||
`knowledge.yaml` 推荐相关 `active` 知识；人工确认后把固定 revision 的
|
||
`knowledgeRefs` 写入当前任务上下文。
|
||
- 新逻辑轮次默认分配稳定的 `<task-id>-A<round>`，记录到
|
||
`dispatch.rounds[].attemptId`；旧轮次作为知识来源前再补齐，不要用编排工具的
|
||
`dispatchId` 代替。
|
||
- gate 时检查 Developer 的 `knowledgeApplied`、Test 的 `knowledgeChecks` 和
|
||
candidate 独立证据；只有证据充分时才由 Coordinator 激活、废弃或替代知识。
|
||
- 一次派发只针对一个明确问题（`optimization-method.md` §6）；每任务最多三轮有效
|
||
产品复验。环境失败单独记录、恢复和报告，不占轮次。
|
||
- 终检：读 Test 证据，逐条对齐原始意图后才落 `verified`，不亲自复测。
|
||
- **Must Not**：改源码、亲自跑测试、凭 `worker_done` 直接标 `verified`、把多个无关失败塞进一次派发、派发 `candidate` 或全量注入知识库、把知识正文当作 shell 执行。
|
||
- **Evidence**：产品文档、`tasks.yaml` 里的 `expected` + `verification`、Test 回传的复测证据。
|
||
- **Output**：确认前给「产品文档 + 任务拆分 + 验收信号」；闭环结束给最终报告（`prompt-templates.md` §6）。
|
||
- **可选 skills**：复杂需求可先用 `/think` 或 `superpowers:brainstorming` / `writing-plans` 收敛设计与计划。
|
||
|
||
### Developer：实现与白盒验证
|
||
|
||
- **Outcome**：在授权路径内做出满足验收信号的最小改动，并用白盒证据证明它可复现。
|
||
- **Must Do**
|
||
- 动手前先读覆盖层文件、`tasks.yaml` 对应任务、相关规格；复现失败现象或先写会失败的测试。
|
||
- 只使用 Coordinator 本轮显式派发的 `active` 知识，按固定 revision 回报
|
||
`knowledgeApplied`；发现跨任务可复用的项目经验时提交带当前观测证据的
|
||
`knowledgeCandidates`。
|
||
- 最小 diff，只改一个明确问题的根因，不顺手重构无关代码。
|
||
- 行为变更配单元测试；bug 修复先有一个能复现的失败用例再修。
|
||
- 完成前跑覆盖层里规定的命令（构建 / 单测 / 本地运行），亲自走一遍验收路径。
|
||
- **网站 / 常驻服务**：改完重启服务（或触发热更并确认生效），保证运行实例跑的是新代码，避免 Test 测到旧进程 / 旧构建。
|
||
- **Must Not**：改产品规格与集成测试、写 `tasks.yaml` 或 `knowledge.yaml`、标
|
||
`verified`、把 candidate 当作已生效规则、绕过测试声称完成、把 bug 修复扩成大
|
||
重构（需要就先停下说明并请示）。
|
||
- **Evidence**：改了哪些文件、跑了哪些命令及结果、如何复现验收路径、实际采用的
|
||
`knowledgeRefs`、新 candidate 的当前任务证据、残留风险。
|
||
- **Output**：一次 `worker_done`，字段见 `prompt-templates.md` §4（只报证据，不下最终结论）。
|
||
- **可选 skills**：排查用 `/hunt` 或 `superpowers:systematic-debugging`（先根因后修）；实现行为变更用 `superpowers:test-driven-development`。
|
||
|
||
### Test：独立黑盒复测
|
||
|
||
- **Outcome**：以独立视角复现验收路径，逐条给出通过/失败的可观测证据，供 Coordinator 终检。
|
||
- **Must Do**
|
||
- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 `closed-loop.md`），避免测错实例或旧构建；网站类先确认服务已按新代码重启。
|
||
- 逐条验证验收信号，验证交互后的真实状态，而不是只看静态文案。
|
||
- 对 Coordinator 派发的每条 `knowledgeRef` 执行适用的额外检查，回报
|
||
`knowledgeChecks`；对本轮 candidate 使用独立观测验证，不能复述 Developer
|
||
结论当作证据。
|
||
- **网站类任务优先用浏览器复测**真实交互（点击 / 跳转 / 渲染），其次才是 API / 脚本；纯后端 / CLI 则以 API smoke 或脚本为主。
|
||
- 把最容易反复误判的路径沉淀成可执行测试（`optimization-method.md` §8）。
|
||
- 只回传证据 + 逐条结论，最终判定留给 Coordinator。
|
||
- **Must Not**：改应用源码、改产品规格、写 `tasks.yaml` 或 `knowledge.yaml`、凭
|
||
Developer 的 `worker_done` 直接下结论、把 candidate 作为 active 知识执行。
|
||
- **Evidence**：运行环境快照、命令结果、每条信号 pass/fail + 证据
|
||
（snapshot / DOM / API 结果）、每条适用知识的
|
||
`passed` / `failed` / `not_applicable` + 证据。
|
||
- **Output**：一次复测报告，字段见 `prompt-templates.md` §5。
|
||
- **可选 skills**：合并 / 发版前检查可用 `/check` 或 `superpowers:verification-before-completion`（证据先于结论）。
|
||
|
||
---
|
||
|
||
## 路径权限模板
|
||
|
||
目标项目在自己的**覆盖层文件**中填入实际路径（模板见 `templates/project.template.md`；覆盖层默认 `.pouch/ack/project.md`，路径记在 `tasks.yaml` 的 `project.overlayFile`）。
|
||
|
||
| 路径 | Coordinator | Test | Developer | 说明 |
|
||
|------|:-----------:|:----:|:---------:|------|
|
||
| `<spec_paths>` | R/W | Read-only | Read-only | PRD、API spec、设计文档，Coordinator（PM）拥有 |
|
||
| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器用例、API smoke、回归清单，Test 拥有 |
|
||
| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录，通常可 gitignore |
|
||
| `<source_paths>` | Read-only | Read-only | R/W | 应用源码 |
|
||
| `<unit_test_paths>` | Read-only | Read-only | R/W | 单元测试 |
|
||
| `<shared_config_templates>` | Read-only | Read-only | R/W | 可提交配置模板 |
|
||
| `<local_config>` | Read-only | Read-only | Read-only | 本地私有配置，不提交 |
|
||
| `tasks.yaml` | R/W | Read-only | Read-only | 见下方「项目状态写入约定」 |
|
||
| `knowledge.yaml` | R/W | Read-only | Read-only | Coordinator 单写；Developer/Test 通过回报提名或验证 |
|
||
| `regression.yaml` | R/W | Read-only | Read-only | Coordinator 单写；Test 通过 `regressionCandidates` 提名 |
|
||
| `delivery.yaml` | 仅显式维护时 R/W | Read-only | Read-only | 声明项目交付能力，不保存凭据或执行授权 |
|
||
|
||
---
|
||
|
||
## 任务状态机（SSOT）
|
||
|
||
```text
|
||
open
|
||
-> dispatched （派发给 Developer）
|
||
-> fixed_by_dev （Developer 声称已修）
|
||
-> retesting （派发给 Test 复测）
|
||
-> verified （Test 通过 + Coordinator 终检）
|
||
```
|
||
|
||
失败分支：
|
||
|
||
```text
|
||
dispatched -> blocked
|
||
retesting -> failed_retest -> dispatched
|
||
failed_retest（累计 3 轮） -> leftover
|
||
```
|
||
|
||
环境分支不进入 `failed_retest`：
|
||
|
||
```text
|
||
launch / service / data / browser / tooling environment failure
|
||
-> dispatch.environmentIncidents
|
||
-> 有界恢复并告知用户下一步
|
||
-> fixed_by_dev（待恢复）或 blocked（需外部动作）
|
||
-> 环境恢复后 retesting
|
||
```
|
||
|
||
状态定义（所有状态都只由 Coordinator 写入 `tasks.yaml`，来源不同）：
|
||
|
||
| 状态 | 依据来源 | 含义 |
|
||
|------|----------|------|
|
||
| `open` | Coordinator 自己发现/记录 | 已发现，等待处理 |
|
||
| `dispatched` | Coordinator 派发动作 | 已派发给 Developer |
|
||
| `fixed_by_dev` | Developer 的 worker_done | 开发声称已修复并提供白盒验证 |
|
||
| `retesting` | Coordinator 派发动作 | 已派发给 Test，正在黑盒复测 |
|
||
| `failed_retest` | Test 的产品复测报告 | 环境对齐后观察到产品验收失败，可继续派发 Developer |
|
||
| `verified` | Test 通过 + Coordinator 终检 | 复测通过且符合原始意图 |
|
||
| `blocked` | Coordinator 判断 | 需要用户决策或外部条件 |
|
||
| `leftover` | Coordinator 判断 | 累计 3 轮仍未通过，留给人工或专项处理 |
|
||
|
||
有效复验与环境失败的处理细则见 `optimization-method.md` §4。
|
||
|
||
## 交付状态（与任务状态正交）
|
||
|
||
任务进入 `verified` 后不再改写为发布或部署状态。可选交付的每次执行单独记录在
|
||
`tasks.yaml.deliveryRuns`：
|
||
|
||
```text
|
||
planned -> running -> validation_ready | review_ready | released
|
||
-> blocked | failed
|
||
planned -> skipped
|
||
```
|
||
|
||
`validation_ready` 表示开发/测试环境已部署且健康检查通过，等待用户手工验证；
|
||
`review_ready` 表示 PR、preview 产物和已授权的非生产部署证据已经齐备，等待用户
|
||
审核；`released` 只用于用户明确批准后的 stable 发布或 production 部署。交付失败
|
||
不会否定已经独立验证的任务，但必须保留失败步骤、revision 与日志引用。完整顺序、
|
||
审批点和恢复规则见 `delivery.md`。
|
||
|
||
---
|
||
|
||
## 项目状态写入约定（并发安全）
|
||
|
||
`tasks.yaml` 是任务、交付运行与回归运行事实源，`knowledge.yaml` 是跨任务项目知识
|
||
事实源，`regression.yaml` 是黑盒回归用例事实源，`delivery.yaml` 是项目交付能力
|
||
事实源。为避免多 Agent 并发写冲突：
|
||
|
||
- **只有 Coordinator 写 `tasks.yaml`、`knowledge.yaml` 和 `regression.yaml`**。
|
||
Test 与 Developer 对它们都是只读的。
|
||
- Developer 的实现状态、Test 的复测证据都通过消息回传（`worker_done` / 复测报告），由 Coordinator 落盘。
|
||
- Developer 和 Test 只能通过 `knowledgeCandidates` 提名知识；candidate 保存在
|
||
当前任务证据中，在 Test 独立验证和 Coordinator gate 前不写成可派发的 active
|
||
知识。
|
||
- 每次写入前先读最新内容，写入后更新顶层 `updatedAt`。
|
||
- 单次写入应是一个任务的一次状态跃迁，避免整表批量重写。
|
||
- `delivery.yaml` 只在用户显式要求维护配置时修改；运行只写
|
||
`tasks.yaml.deliveryRuns`，不能反向改写能力定义。
|
||
|
||
全项目范围的 `must`、`never` 或权限类规则还需要 User / Decision Owner 确认。
|
||
关键约束应最终下沉为测试、lint、CI 或正式规范；知识条目保存触发条件、原因和
|
||
证据引用，不替代可执行控制。
|
||
|
||
---
|
||
|
||
## 完成定义（Definition of Done）
|
||
|
||
一个任务只有同时满足以下条件，才能标记 `verified`：
|
||
|
||
- Developer 已提供修改文件和白盒验证证据（`worker_done`）。
|
||
- Test 在正确 worktree 和正确服务实例上独立复测通过（对齐检查见 `closed-loop.md`），并产出可观测证据。
|
||
- 相关单元测试、构建、集成或浏览器检查通过。
|
||
- 当前任务显式 `knowledgeRefs` 对应的必需 `knowledgeChecks` 已由 Test 覆盖；
|
||
未覆盖或检查引用无法解析时不能标记 `verified`。
|
||
- **Coordinator 终检**：读 Test 的证据，确认它满足任务的原始意图与验收信号（不是重测，是审证据 + 对齐意图；避免"过了字面没过意图"）。
|
||
- `tasks.yaml` 中记录了复测证据与 `resolution.verifiedBy`。
|
||
- 用户可见行为符合验收标准。
|