diff --git a/kits/agent-collaboration-kit/README.md b/kits/agent-collaboration-kit/README.md index a78900c..63798c0 100644 --- a/kits/agent-collaboration-kit/README.md +++ b/kits/agent-collaboration-kit/README.md @@ -1,6 +1,6 @@ # Agent Collaboration Kit -一套可复用到其它项目的多 Agent 协作规范:**产品/测试负责定义与验收,开发负责实现与白盒验证,协调者做闭环调度**。 +一套可复用到其它项目的多 Agent 协作规范,默认三个独立角色:**Coordinator (PM) 拆解需求并调度闭环,Developer 实现与白盒验证,Test 独立黑盒复测**。关键属性是验证者 ≠ 实现者。 当前版本见 `VERSION`。这不是 Agent Skill(无 `SKILL.md`),不由 skiff 安装,而是复制/引用到目标项目。 @@ -9,8 +9,8 @@ ## 适用场景 - 多个 Agent 分工协作,而非单个 Agent 从需求写到代码。 -- 需要区分规格、测试、实现、复测的责任边界。 -- 需要把失败项派发给开发 Agent,`worker_done` 后由测试 Agent 复测。 +- 需要区分规格、测试、实现、复测的责任边界(Coordinator / Test / Developer 三角色)。 +- 需要把失败项派发给 Developer,`worker_done` 后由独立的 Test 复测、Coordinator 终检。 - 需要连续修复多个问题,并把三轮仍未修好的问题留档。 --- @@ -73,5 +73,5 @@ agent-collaboration-kit/ ## 默认口令 ```text -用 Agent 协作闭环处理 tasks.yaml 里的未通过项;每个问题最多派发开发 Agent 修三轮,三轮仍不过就记录为遗留,然后继续下一个。 +用三角色协作闭环处理 tasks.yaml 里的未通过项:Coordinator 派发给 Developer 修复,再交给 Test 独立复测并终检;每个问题最多修三轮,三轮仍不过就记录为遗留,然后继续下一个。 ``` diff --git a/kits/agent-collaboration-kit/VERSION b/kits/agent-collaboration-kit/VERSION index 0ea3a94..0d91a54 100644 --- a/kits/agent-collaboration-kit/VERSION +++ b/kits/agent-collaboration-kit/VERSION @@ -1 +1 @@ -0.2.0 +0.3.0 diff --git a/kits/agent-collaboration-kit/adoption-checklist.md b/kits/agent-collaboration-kit/adoption-checklist.md index 30ec76b..57e1256 100644 --- a/kits/agent-collaboration-kit/adoption-checklist.md +++ b/kits/agent-collaboration-kit/adoption-checklist.md @@ -16,7 +16,8 @@ ## 3. 路径权限 -- [ ] 填实际的 Product/Test 可写路径(规格、集成测试、复测记录)。 +- [ ] 填实际的 Coordinator (PM) 可写路径(规格)。 +- [ ] 填实际的 Test 可写路径(集成测试、复测记录)。 - [ ] 填实际的 Developer 可写路径(源码、单元测试、配置模板)。 - [ ] 本地私有配置标记只读或不提交。 - [ ] 确认 `tasks.yaml` 只有 Coordinator 写(见 `core/roles-and-permissions.md`)。 @@ -31,12 +32,12 @@ ## 5. 编排 - [ ] 决定用 Orca(`core/orca-adapter.md`)还是手动模式(`core/closed-loop.md`)。 -- [ ] Orca:`orca status`、`terminal list` 可用,`worker_done` 能发回 Coordinator。 +- [ ] Orca:`orca status`、`terminal list` 可用,Coordinator / Developer / Test 三个终端都在,回报能发回 Coordinator。 - [ ] 决定用当前 worktree 还是隔离 worktree。 ## 6. 验证命令 -- [ ] Product/Test 有黑盒验证命令,Developer 有白盒验证命令。 +- [ ] Test 有黑盒复测命令,Developer 有白盒验证命令。 - [ ] 构建产物与服务启动命令写清。 - [ ] 浏览器测试 `BASE_URL` 写清,复测前能确认服务来自正确 worktree。 @@ -50,9 +51,10 @@ 选一个低风险 bug 跑完整闭环,结束后检查是否出现: -- Developer 修改了越权路径。 -- worker_done 没有验证证据。 -- Product/Test 复测到了旧服务。 +- Developer 修改了越权路径,或 Test 改了源码。 +- worker_done 或复测报告没有验证证据。 +- Test 复测到了旧服务。 +- Coordinator 没做终检就直接 verified。 - 任务板字段不够记录失败原因。 - 三轮失败策略没被执行。 diff --git a/kits/agent-collaboration-kit/core/closed-loop.md b/kits/agent-collaboration-kit/core/closed-loop.md index a4dd71c..5cbdff8 100644 --- a/kits/agent-collaboration-kit/core/closed-loop.md +++ b/kits/agent-collaboration-kit/core/closed-loop.md @@ -1,37 +1,42 @@ # 闭环流程(稳定核心,编排无关) -本文件定义**与具体编排工具无关**的协作闭环。运行时调度可以用 Orca(见 `orca-adapter.md`),也可以手动跑(见下方「手动模式」)。 +本文件定义**与具体编排工具无关**的三角色协作闭环。运行时调度可以用 Orca(见 `orca-adapter.md`),也可以手动跑(见下方「手动模式」)。 -原则:调度消息只是运行时载体,**所有结论都必须回写到 `tasks.yaml`**(事实源),不要把消息当最终记录。 +原则:调度消息只是运行时载体,**所有结论都必须回写到 `tasks.yaml`**(事实源),不要把消息当最终记录。角色定义见 `roles-and-permissions.md`:Coordinator 只编排、Test 只验证、Developer 只实现。 --- ## 编排抽象 -无论用什么工具,闭环都由这几个能力组成: +无论用什么工具,闭环都由这几个能力组成。注意 `dispatch` 有两个目标(Developer 与 Test): | 抽象动作 | 含义 | Orca 实现 | 手动实现 | |----------|------|-----------|----------| -| `prepare(task)` | 把任务和验收标准写进 `tasks.yaml` | 同左 | 同左 | -| `dispatch(task, worker)` | 把任务连同上下文交给 Developer | `orca orchestration dispatch` | 复制 prompt 到 Developer 终端/会话 | -| `wait()` | 等待 `worker_done` / `escalation` / `decision_gate` | `orca orchestration check --wait` | 人工等待 Developer 回报 | -| `retest(task)` | Coordinator 独立黑盒复测 | 同左 | 同左 | -| `writeback(task, result)` | 把复测结果写回 `tasks.yaml` | 同左 | 同左 | +| `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` §「任务状态机」。 +派发用的 prompt 见 `prompt-templates.md`。状态流转见 `roles-and-permissions.md` §「任务状态机」。**独立复测由 Test 执行,不是 Coordinator**;Coordinator 只做读证据的终检。 --- ## 标准闭环 ```text -Product/Test 发现或读取 open 任务 - -> prepare:写/补全 tasks.yaml 验收标准 - -> dispatch 给 Developer Worker - -> wait:worker_done / escalation / decision_gate - -> retest:Coordinator 构建并独立复测 - -> 通过:writeback verified - -> 失败:writeback failed_retest,追加证据,最多再派发两轮 +Coordinator 发现或读取 open 任务 + -> prepare:写/补全 tasks.yaml 验收信号 + -> dispatch 给 Developer + -> 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,继续下一个任务 ``` @@ -43,19 +48,21 @@ Product/Test 发现或读取 open 任务 没有编排工具时,闭环不变,只是 `dispatch` / `wait` 由人工承担: -1. Coordinator 在 `tasks.yaml` 写好任务和验收标准。 -2. 用 `prompt-templates.md` 的初始派发模板生成 prompt,手动发给 Developer(另一个会话/终端/人)。 -3. Developer 完成后按 worker_done 模板回报(可直接贴回 Coordinator 会话)。 -4. Coordinator 独立复测,回写 `tasks.yaml`。 -5. 失败则用「复测失败再派发模板」继续,最多三轮。 +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`、三轮失败留档。 +手动模式下同样遵守:worker_done / 复测报告都不等于最终结论、只有 Coordinator 写 `tasks.yaml`、三轮失败留档。 --- -## worker_done 后复测(编排无关) +## Test 复测(编排无关) -即使 worker_done 写了"全部通过",Coordinator 仍必须独立复测: +即使 Developer 的 worker_done 写了"全部通过",Test 仍必须独立复测: ```bash git status --short @@ -74,11 +81,25 @@ actual: snapshot evidence: ``` +Test 只回传证据,不写 `tasks.yaml`;由 Coordinator 落盘。 + +--- + +## Coordinator 终检(gate) + +Test 报通过后,Coordinator 不重测,而是做一次读证据的终检: + +- Test 证据是否覆盖了任务的**每一条**验收信号(见 `optimization-method.md` §1)。 +- 结果是否符合任务的**原始意图**,而不只是通过了字面文案。 +- 运行环境是否对齐(见下方「服务与 worktree 对齐」)。 + +终检不通过(例如意图漂移、验收信号写漏)时,回写 `failed_retest` 并把意图差异带给下一轮 Developer,必要时先补全验收信号。 + --- ## 服务与 worktree 对齐(防假通过/假失败) -复测前记录运行环境: +Test 复测前记录运行环境: ```bash pwd @@ -100,13 +121,14 @@ worktreePath: ## 结果回写 -回写 `tasks.yaml` 时按状态填写(字段结构见 `templates/tasks.schema.json`): +Coordinator 回写 `tasks.yaml` 时按状态填写(字段结构见 `templates/tasks.schema.json`): ```yaml -# 通过 +# 通过(Test 复测 + Coordinator 终检) status: verified resolution: verifiedAt: "" + verifiedBy: "test" evidence: verification: "" browser: "" @@ -119,7 +141,7 @@ dispatch: rounds: - round: 1 result: failed - evidence: "" + evidence: "" ``` ```yaml diff --git a/kits/agent-collaboration-kit/core/optimization-method.md b/kits/agent-collaboration-kit/core/optimization-method.md index 24bf03c..9893ba9 100644 --- a/kits/agent-collaboration-kit/core/optimization-method.md +++ b/kits/agent-collaboration-kit/core/optimization-method.md @@ -2,7 +2,7 @@ 减少"开发声称完成但复测不过"的循环成本。本文件是**验收信号写法**和**三轮失败策略**的 SSOT,其它文件引用这里。 -复测步骤与环境对齐见 `closed-loop.md`;状态机与完成定义见 `roles-and-permissions.md`。 +三角色分工(Coordinator 编排 / Test 验证 / Developer 实现)见 `roles-and-permissions.md`;复测步骤、Coordinator 终检与环境对齐见 `closed-loop.md`。 --- @@ -34,9 +34,9 @@ --- -## 2. worker_done 必须带证据,不带结论 +## 2. 回报必须带证据,不带结论 -Developer Worker 的 `worker_done` 应报告:改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。 +Developer 的 `worker_done` 应报告:改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。Test 的复测报告同理:跑了哪些命令、命中/缺失了哪些验收信号、实际观察到什么、证据(snapshot / API 结果)。两者的"结论"都不作数,只有 Coordinator 落盘的 `tasks.yaml` 才是事实。 不要写: @@ -54,9 +54,11 @@ Developer Worker 的 `worker_done` 应报告:改了哪些文件、跑了哪些 --- -## 3. Product/Test 只信自己的复测 +## 3. 验证权在 Test,Coordinator 只信证据 -即使 worker_done 写了"全部通过",Coordinator 仍必须独立复测。完整复测步骤与 worktree/服务对齐见 `closed-loop.md`。这可避免三类假通过:测错服务实例、测到旧构建产物、开发只验证静态文本没验证真实交互。 +即使 Developer 的 worker_done 写了"全部通过",也必须由独立的 Test 复测(验证者 ≠ 实现者)。完整复测步骤与 worktree/服务对齐见 `closed-loop.md`。独立复测可避免三类假通过:测错服务实例、测到旧构建产物、开发只验证静态文本没验证真实交互。 + +Coordinator 不亲自复测,但要做终检:读 Test 的证据,确认它覆盖了每条验收信号且符合原始意图,避免"过了字面没过意图"。终检不通过就回写 `failed_retest`。 --- @@ -125,7 +127,7 @@ one dispatch = one bug = one acceptance path ## 8. 优先让测试可执行化 -如果某个问题需要多轮修复,说明它值得沉淀成自动化检查。优先级: +如果某个问题需要多轮修复,说明它值得沉淀成自动化检查。这类可执行测试由 Test 拥有并维护(见 `roles-and-permissions.md` 权限表的 ``)。优先级: 1. API smoke。 2. 浏览器脚本或 case 文档。 diff --git a/kits/agent-collaboration-kit/core/orca-adapter.md b/kits/agent-collaboration-kit/core/orca-adapter.md index ea09996..4177da4 100644 --- a/kits/agent-collaboration-kit/core/orca-adapter.md +++ b/kits/agent-collaboration-kit/core/orca-adapter.md @@ -23,7 +23,7 @@ orca orchestration task-list --json orca orchestration inbox --limit 20 --json ``` -确认:Orca runtime 可达;Coordinator 与 Developer Worker 终端都存在;Developer 在正确 worktree;当前没有冲突的活跃编排任务。 +确认:Orca runtime 可达;Coordinator、Developer、Test 三个终端都存在;Developer 在正确 worktree;当前没有冲突的活跃编排任务。 --- @@ -31,15 +31,16 @@ orca orchestration inbox --limit 20 --json ```bash orca orchestration task-create --spec "$(cat <<'EOF' -Goal: Complete with supervised Product/Test -> Developer loop. +Goal: Complete with supervised Coordinator -> Developer -> Test loop. -Coordinator: owns task board, black-box tests, retest, final verification. +Coordinator (PM): owns task board, decomposition, dispatch, and final gate (reads Test evidence, does not test). Developer: owns implementation and white-box verification. +Test: owns independent black-box retest and evidence (verifier != implementer). 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. +- worker_done and retest reports are not final completion; only Coordinator writes tasks.yaml. EOF )" --json ``` @@ -55,7 +56,7 @@ Repository: - Worktree: Read: AGENTS.md, tasks.yaml, -Failure evidence: +Failure evidence: Acceptance: Constraints: @@ -88,18 +89,38 @@ EOF --- +## 派发给 Test 复测 + +Developer 回报 worker_done、Coordinator 写回 `fixed_by_dev` 后,把复测任务发给 Test: + +```bash +orca orchestration dispatch --task --to --inject --json +``` + +不能 `--inject` 时,先登记再手动投递 `prompt-templates.md` §3 的复测派发 prompt: + +```bash +orca orchestration dispatch --task --to --json +orca terminal send --terminal --text "$(cat <<'EOF' +<粘贴 prompt-templates.md §3 复测派发模板,已填占位符> +EOF +)" --enter --json +``` + +--- + ## 等待结果 ```bash orca orchestration check \ --terminal \ --wait \ - --types worker_done,escalation,decision_gate \ + --types worker_done,retest_result,escalation,decision_gate \ --timeout-ms 900000 \ --json ``` -等待超时不等于失败。长任务可继续等待,或检查 worker 终端活性。 +等待超时不等于失败。长任务可继续等待,或检查 worker 终端活性。`worker_done` 来自 Developer,`retest_result`(无该类型时用 `worker_done` + subject 区分)来自 Test。 --- @@ -123,4 +144,28 @@ orca orchestration send \ --json ``` -收到 worker_done 后,Coordinator 按 `closed-loop.md` 独立复测并回写 `tasks.yaml`。 +收到 worker_done 后,Coordinator 写回 `fixed_by_dev`,再按上文派发给 Test 复测。 + +--- + +## Test 回报复测结果 + +字段含义见 `prompt-templates.md` §5: + +```bash +orca orchestration send \ + --to \ + --type retest_result \ + --subject " retest round " \ + --body "<逐条验收信号结论 + 实际观察 + 证据>" \ + --payload '{ + "taskId": "", + "dispatchId": "", + "env": {"worktree": "", "branch": "", "commit": "", "baseUrl": ""}, + "signals": [": pass", ": fail ()"], + "conclusion": "all-signals-pass | signals-failed" + }' \ + --json +``` + +无 `retest_result` 类型时用 `--type worker_done`,靠 subject `retest round ` 区分。收到复测结果后,Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`:通过 `verified`,不过 `failed_retest`。 diff --git a/kits/agent-collaboration-kit/core/prompt-templates.md b/kits/agent-collaboration-kit/core/prompt-templates.md index 33eccf1..5fa6025 100644 --- a/kits/agent-collaboration-kit/core/prompt-templates.md +++ b/kits/agent-collaboration-kit/core/prompt-templates.md @@ -1,10 +1,12 @@ # 派发 Prompt 模板(稳定核心) -用于 Coordinator 给 Developer Worker 派发任务。复制时替换尖括号占位符。这些模板与编排工具无关:Orca 模式用 `orca-adapter.md` 的命令投递,手动模式直接把文本发给 Developer。 +Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发复测。复制时替换尖括号占位符。模板与编排工具无关:Orca 模式用 `orca-adapter.md` 的命令投递,手动模式直接把文本发给对应 Agent。 + +角色分工见 `roles-and-permissions.md`;闭环顺序见 `closed-loop.md`。 --- -## 1. 初始派发模板 +## 1. 初始派发给 Developer ```text 你现在接到一个受监督的协作任务。请在 开发工作树内完成。 @@ -18,7 +20,7 @@ - 当前失败证据: - + 验收标准(可观测信号,见 optimization-method.md §1): 1. @@ -27,7 +29,7 @@ 约束: - 只修改 Developer 可写路径(见 AGENTS.md 权限表)。 -- 不要修改 Product/Test 负责的规格和集成测试文件,除非任务明确要求。 +- 不要修改产品规格和集成测试文件(分别由 Coordinator 与 Test 拥有),除非任务明确要求。 - 不要写 tasks.yaml,不要标记 verified。 - 不要提交或推送,除非用户明确要求。 - 最小 diff,避免无关重构。 @@ -41,7 +43,7 @@ --- -## 2. 复测失败再派发模板 +## 2. 复测失败再派发给 Developer ```text 第 轮复测未通过,请继续修 。 @@ -49,7 +51,7 @@ 上一轮开发声称: -Product/Test 独立复测结果: +Test 独立复测结果: - 运行命令: - 失败页面/API: - 仍缺失: @@ -58,7 +60,7 @@ Product/Test 独立复测结果: 关键提示: - 不要只满足静态文案,必须满足交互后的真实状态。 - 如果后端/API 正常而 UI 不更新,请优先排查事件链、状态重置、异步请求、构建产物和服务 worktree。 -- 修复后请自己用浏览器或脚本复现 Product/Test 的完整步骤。 +- 修复后请自己用浏览器或脚本复现 Test 的完整步骤。 验收不变: @@ -68,7 +70,40 @@ Product/Test 独立复测结果: --- -## 3. Developer Worker worker_done 回报格式(通用) +## 3. 派发给 Test 复测 + +Developer 回报 worker_done 后,Coordinator 把复测任务发给 Test。 + +```text +请对 : 做独立黑盒复测。 + +请先读取: +- AGENTS.md +- tasks.yaml(该任务的验收信号) +- + +Developer 本轮声称(仅供参考,不作数): +- 改动文件: +- 自测命令: + +复测要求: +- 先对齐运行环境(pwd / 分支 / commit / 服务 worktree,见 closed-loop.md)。 +- 逐条验证下列验收信号,不要只看静态文案,要验证交互后的真实状态: + 1. + 2. + 3. +- 需要时把易反复误判的路径沉淀成可执行测试(见 optimization-method.md §8)。 + +约束: +- 只读源码,不修改应用代码,不写 tasks.yaml。 +- 只回传证据和逐条结论,最终判定由 Coordinator 终检后落盘。 + +完成后回报一次复测报告(格式见 §5),subject:" retest round "。 +``` + +--- + +## 4. Developer worker_done 回报格式 无论 Orca 还是手动,回报都应包含以下字段: @@ -86,12 +121,37 @@ Orca 模式下用 `orca-adapter.md` §「Developer 回报 worker_done」的命 --- -## 4. Coordinator 最终报告模板 +## 5. Test 复测报告格式 + +Test 只回传证据和逐条结论,不下最终判定: + +```text +subject: retest round +env: + worktree: + branch: + commit: + baseUrl: +commands: + - : passed/failed +signals: + - : pass/fail () + - : pass/fail () +browser: +conclusion: all-signals-pass / signals-failed +notes: +``` + +Orca 模式下用 `orca-adapter.md` §「Test 回报复测结果」的命令发送同样的字段。 + +--- + +## 6. Coordinator 最终报告模板 ```text 本轮闭环完成。 -已验证: +已验证(Test 复测通过 + 终检): - : 遗留: diff --git a/kits/agent-collaboration-kit/core/roles-and-permissions.md b/kits/agent-collaboration-kit/core/roles-and-permissions.md index 847e519..77d0c43 100644 --- a/kits/agent-collaboration-kit/core/roles-and-permissions.md +++ b/kits/agent-collaboration-kit/core/roles-and-permissions.md @@ -6,30 +6,35 @@ --- -## 角色模型 +## 角色模型(三角色) + +本 kit 默认三个独立 Agent:**Coordinator 只编排、Test 只验证、Developer 只实现**。关键属性是**验证者 ≠ 实现者**:Developer 不能给自己盖章,验证权在独立的 Test。 | 角色 | 主要职责 | 验证方式 | 不应做的事 | |------|----------|----------|------------| -| Product/Test Coordinator | 需求拆解、任务记录、黑盒测试、复测验收、调度开发 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、凭 worker_done 直接标记完成 | -| Developer Worker | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格、标记 verified、绕过测试声称完成 | +| Coordinator (PM) | 需求拆解、定验收信号、排优先级、写 `tasks.yaml`、向 Developer/Test 派发、跑三轮闭环、做最终 gate | 读 Test 证据并对齐原始意图(不亲自跑测试) | 修改源码、亲自复测、凭 worker_done 直接标 `verified` | +| Test | 黑盒复测、回归验证、沉淀可执行测试、产出证据 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、修改产品规格、写 `tasks.yaml` | +| Developer | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格与集成测试、标记 `verified`、绕过测试声称完成 | | User / Decision Owner | 决定范围、优先级、阻塞项是否继续 | 审阅报告和遗留清单 | 直接替代复测证据 | +**独立验证权归 Test。** Coordinator 不亲自复测——它读 Test 的证据,并对照任务的原始意图做一次终检(见「完成定义」)。`worker_done` 不等于完成的原则同时适用于 Developer 和 Test:结论只有落到 `tasks.yaml` 才算数。 + --- ## 路径权限模板 目标项目在自己的 `AGENTS.md` 中填入实际路径(见 `templates/AGENTS.template.md`)。 -| 路径 | Product/Test | Developer | 说明 | -|------|:------------:|:---------:|------| -| `` | R/W | Read-only | PRD、API spec、设计文档 | -| `` | R/W | Read-only | 浏览器用例、API smoke、回归清单 | -| `` | R/W | Read-only | 复测记录,通常可 gitignore | -| `` | Read-only | R/W | 应用源码 | -| `` | Read-only | R/W | 单元测试 | -| `` | Read-only | R/W | 可提交配置模板 | -| `` | Read-only | Read-only | 本地私有配置,不提交 | -| `tasks.yaml` | R/W | Read-only | 见下方「任务板写入约定」 | +| 路径 | Coordinator | Test | Developer | 说明 | +|------|:-----------:|:----:|:---------:|------| +| `` | R/W | Read-only | Read-only | PRD、API spec、设计文档,Coordinator(PM)拥有 | +| `` | Read-only | R/W | Read-only | 浏览器用例、API smoke、回归清单,Test 拥有 | +| `` | Read-only | R/W | Read-only | 复测记录,通常可 gitignore | +| `` | Read-only | Read-only | R/W | 应用源码 | +| `` | Read-only | Read-only | R/W | 单元测试 | +| `` | Read-only | Read-only | R/W | 可提交配置模板 | +| `` | Read-only | Read-only | Read-only | 本地私有配置,不提交 | +| `tasks.yaml` | R/W | Read-only | Read-only | 见下方「任务板写入约定」 | --- @@ -37,32 +42,32 @@ ```text open - -> dispatched - -> fixed_by_dev - -> retesting - -> verified + -> dispatched (派发给 Developer) + -> fixed_by_dev (Developer 声称已修) + -> retesting (派发给 Test 复测) + -> verified (Test 通过 + Coordinator 终检) ``` 失败分支: ```text dispatched -> blocked -fixed_by_dev -> failed_retest -> dispatched +retesting -> failed_retest -> dispatched failed_retest(累计 3 轮) -> leftover ``` -状态定义: +状态定义(所有状态都只由 Coordinator 写入 `tasks.yaml`,来源不同): -| 状态 | 写入者 | 含义 | -|------|--------|------| -| `open` | Product/Test | 已发现,等待处理 | -| `dispatched` | Product/Test | 已派发给开发 Agent | -| `fixed_by_dev` | Product/Test(据 worker_done 回写) | 开发声称已修复并提供验证 | -| `retesting` | Product/Test | 正在复测 | -| `failed_retest` | Product/Test | 复测失败,可继续派发 | -| `verified` | Product/Test | 复测通过 | -| `blocked` | Product/Test | 需要用户决策或外部条件 | -| `leftover` | Product/Test | 累计 3 轮仍未通过,留给人工或专项处理 | +| 状态 | 依据来源 | 含义 | +|------|----------|------| +| `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` §「三轮失败策略」。 @@ -70,10 +75,10 @@ failed_retest(累计 3 轮) -> leftover ## 任务板写入约定(并发安全) -`tasks.yaml` 是持久事实源,为避免多 Worker 并发写冲突: +`tasks.yaml` 是持久事实源,为避免多 Agent 并发写冲突: -- **只有 Coordinator 写 `tasks.yaml`**。Developer Worker 对它是只读的。 -- Developer 的实现状态、证据通过 `worker_done` 消息回传,由 Coordinator 落盘。 +- **只有 Coordinator 写 `tasks.yaml`**。Test 与 Developer 对它都是只读的。 +- Developer 的实现状态、Test 的复测证据都通过消息回传(`worker_done` / 复测报告),由 Coordinator 落盘。 - 每次写入前先读最新内容,写入后更新顶层 `updatedAt`。 - 单次写入应是一个任务的一次状态跃迁,避免整表批量重写。 @@ -83,8 +88,9 @@ failed_retest(累计 3 轮) -> leftover 一个任务只有同时满足以下条件,才能标记 `verified`: -- Developer 已提供修改文件和验证证据。 -- Product/Test 在正确 worktree 和正确服务实例上复测(对齐检查见 `closed-loop.md`)。 +- Developer 已提供修改文件和白盒验证证据(`worker_done`)。 +- Test 在正确 worktree 和正确服务实例上独立复测通过(对齐检查见 `closed-loop.md`),并产出可观测证据。 - 相关单元测试、构建、集成或浏览器检查通过。 -- `tasks.yaml` 中记录了复测证据。 +- **Coordinator 终检**:读 Test 的证据,确认它满足任务的原始意图与验收信号(不是重测,是审证据 + 对齐意图;避免"过了字面没过意图")。 +- `tasks.yaml` 中记录了复测证据与 `resolution.verifiedBy`。 - 用户可见行为符合验收标准。 diff --git a/kits/agent-collaboration-kit/examples/AGENTS.example.md b/kits/agent-collaboration-kit/examples/AGENTS.example.md index 377d38a..c0ef6a0 100644 --- a/kits/agent-collaboration-kit/examples/AGENTS.example.md +++ b/kits/agent-collaboration-kit/examples/AGENTS.example.md @@ -1,6 +1,6 @@ # notes-web Agent 协作协议(示例) -> 本项目基于 agent-collaboration-kit v0.2.0。 +> 本项目基于 agent-collaboration-kit v0.3.0。 > 稳定规范引用 `docs/agent-collaboration-kit/core/`,本文件只填项目差异。 ## 项目概览 @@ -21,16 +21,16 @@ ## 路径权限 -| 路径 | Product/Test | Developer | 说明 | -|------|:------------:|:---------:|------| -| `docs/spec/**` | R/W | Read-only | 产品规格 | -| `tests/browser/**` | R/W | Read-only | 浏览器回归用例 | -| `.qa-records/**` | R/W | Read-only | 复测记录(gitignore) | -| `web/**`、`server/**` | Read-only | R/W | 应用源码 | -| `**/*_test.go`、`web/**/*.test.tsx` | Read-only | R/W | 单元测试 | -| `config/*.example.*` | Read-only | R/W | 可提交配置模板 | -| `.env`、`config/local.*` | Read-only | Read-only | 本地私有配置 | -| `tasks.yaml` | R/W | Read-only | 只有 Coordinator 写 | +| 路径 | Coordinator | Test | Developer | 说明 | +|------|:-----------:|:----:|:---------:|------| +| `docs/spec/**` | R/W | Read-only | Read-only | 产品规格(PM 拥有) | +| `tests/browser/**` | Read-only | R/W | Read-only | 浏览器回归用例(Test 拥有) | +| `.qa-records/**` | Read-only | R/W | Read-only | 复测记录(gitignore) | +| `web/**`、`server/**` | Read-only | Read-only | R/W | 应用源码 | +| `**/*_test.go`、`web/**/*.test.tsx` | Read-only | Read-only | R/W | 单元测试 | +| `config/*.example.*` | Read-only | Read-only | R/W | 可提交配置模板 | +| `.env`、`config/local.*` | Read-only | Read-only | Read-only | 本地私有配置 | +| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 | ## 命令 @@ -42,7 +42,7 @@ go test ./... npm run dev # 本地起前端 ``` -Product/Test 黑盒验证: +Test 黑盒复测: ```bash curl -s http://localhost:5173/api/health @@ -58,7 +58,8 @@ python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml ## 硬规则(其余见 core/) -- `worker_done` 不等于完成,必须独立复测后才能 `verified`。 -- 只有 Coordinator 写 `tasks.yaml`。 +- 三角色独立:Coordinator 只编排、Test 只验证、Developer 只实现。 +- `worker_done` 与复测报告都不等于完成,必须 Test 独立复测 + Coordinator 终检后才能 `verified`。 +- 只有 Coordinator 写 `tasks.yaml`;Test 与 Developer 只读。 - 每个任务最多派发 3 轮,仍不过标记 `leftover` 并继续。 - 不提交或推送,除非用户明确要求。 diff --git a/kits/agent-collaboration-kit/examples/tasks.example.yaml b/kits/agent-collaboration-kit/examples/tasks.example.yaml index 58677cc..fe8327f 100644 --- a/kits/agent-collaboration-kit/examples/tasks.example.yaml +++ b/kits/agent-collaboration-kit/examples/tasks.example.yaml @@ -1,8 +1,8 @@ # 填好的最小示例(虚构的 notes-web 项目)。可用 scripts/validate_tasks.py 校验通过。 version: 1 updatedAt: "2026-07-06T09:40:00+08:00" -source: "Product/Test Agent" -kitVersion: "0.2.0" +source: "Coordinator (PM) Agent" +kitVersion: "0.3.0" project: name: "notes-web" repoPath: "/home/dev/notes-web" @@ -62,6 +62,7 @@ tasks: evidence: "复测 4 行 diff 全部出现,取消不触发写入" resolution: fixedBy: "dev-worker-1" + verifiedBy: "test-worker-1" verifiedAt: "2026-07-06T09:38:00+08:00" leftoverReason: null @@ -109,5 +110,6 @@ tasks: evidence: "乐观锁与前端重试逻辑冲突,需重新设计" resolution: fixedBy: null + verifiedBy: null verifiedAt: null leftoverReason: "failed after 3 supervised developer rounds; 需重新设计并发模型" diff --git a/kits/agent-collaboration-kit/templates/AGENTS.template.md b/kits/agent-collaboration-kit/templates/AGENTS.template.md index 7b9ef35..428e1ee 100644 --- a/kits/agent-collaboration-kit/templates/AGENTS.template.md +++ b/kits/agent-collaboration-kit/templates/AGENTS.template.md @@ -21,16 +21,16 @@ ## 路径权限(项目覆盖层,必须填实际路径) -| 路径 | Product/Test | Developer | 说明 | -|------|:------------:|:---------:|------| -| `` | R/W | Read-only | 产品规格、API 文档、计划 | -| `` | R/W | Read-only | 浏览器/API 回归 | -| `` | R/W | Read-only | 复测记录 | -| `` | Read-only | R/W | 应用源码 | -| `` | Read-only | R/W | 单元测试 | -| `` | Read-only | R/W | 可提交配置模板 | -| `` | Read-only | Read-only | 本地私有配置 | -| `tasks.yaml` | R/W | Read-only | 只有 Coordinator 写 | +| 路径 | Coordinator | Test | Developer | 说明 | +|------|:-----------:|:----:|:---------:|------| +| `` | R/W | Read-only | Read-only | 产品规格、API 文档、计划(PM 拥有) | +| `` | Read-only | R/W | Read-only | 浏览器/API 回归(Test 拥有) | +| `` | Read-only | R/W | Read-only | 复测记录 | +| `` | Read-only | Read-only | R/W | 应用源码 | +| `` | Read-only | Read-only | R/W | 单元测试 | +| `` | Read-only | Read-only | R/W | 可提交配置模板 | +| `` | Read-only | Read-only | Read-only | 本地私有配置 | +| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 | ## 命令(项目覆盖层) @@ -42,7 +42,7 @@ Developer 白盒验证: ``` -Product/Test 黑盒验证: +Test 黑盒复测: ```bash @@ -58,7 +58,8 @@ python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml ## 硬规则(其余见 core/) -- `worker_done` 不等于完成。Product/Test 必须独立复测后才能 `verified`。 -- 只有 Coordinator 写 `tasks.yaml`;Developer 通过 worker_done 回报。 +- 三角色独立:Coordinator 只编排、Test 只验证、Developer 只实现(验证者 ≠ 实现者)。 +- `worker_done` 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 `verified`。 +- 只有 Coordinator 写 `tasks.yaml`;Developer 与 Test 都只读,通过消息回报。 - 每个任务最多派发 3 轮,仍不过标记 `leftover` 并继续下一个。 - 不提交或推送,除非用户明确要求。 diff --git a/kits/agent-collaboration-kit/templates/tasks.schema.json b/kits/agent-collaboration-kit/templates/tasks.schema.json index 1941fe8..3a9de36 100644 --- a/kits/agent-collaboration-kit/templates/tasks.schema.json +++ b/kits/agent-collaboration-kit/templates/tasks.schema.json @@ -103,6 +103,7 @@ "additionalProperties": true, "properties": { "fixedBy": { "type": ["string", "null"] }, + "verifiedBy": { "type": ["string", "null"] }, "verifiedAt": { "type": ["string", "null"] }, "leftoverReason": { "type": ["string", "null"] }, "evidence": { "type": "object" } diff --git a/kits/agent-collaboration-kit/templates/tasks.template.yaml b/kits/agent-collaboration-kit/templates/tasks.template.yaml index 72f2af9..688c3b3 100644 --- a/kits/agent-collaboration-kit/templates/tasks.template.yaml +++ b/kits/agent-collaboration-kit/templates/tasks.template.yaml @@ -1,7 +1,7 @@ # 复制到项目根目录为 tasks.yaml,替换占位符。结构见 templates/tasks.schema.json。 version: 1 updatedAt: "" -source: "Product/Test Agent" +source: "Coordinator (PM) Agent" kitVersion: "<接入时的 agent-collaboration-kit 版本,见 kit 根 VERSION>" project: name: "" @@ -39,7 +39,7 @@ tasks: actual: > - + evidence: browser: "" @@ -63,5 +63,6 @@ tasks: resolution: fixedBy: null + verifiedBy: null verifiedAt: null leftoverReason: null