diff --git a/kits/ack/README.md b/kits/ack/README.md new file mode 100644 index 0000000..2391b60 --- /dev/null +++ b/kits/ack/README.md @@ -0,0 +1,101 @@ +# ack — Agent Collaboration Kit + +`ack`(Agent Collaboration Kit)是一套可复用到其它项目的多 Agent 协作规范,默认三个独立角色:**Coordinator (PM) 拆解需求并调度闭环,Developer 实现与白盒验证,Test 独立黑盒复测**。关键属性是验证者 ≠ 实现者。角色默认按成本分层:Coordinator 用强模型(且不亲自跑测试),Test/Developer 用中低模型(见 `core/model-routing.md`)。 + +当前版本见 `VERSION`。这不是 Agent Skill(无 `SKILL.md`),不由 skiff 安装,而是复制/引用到目标项目。 + +--- + +## 适用场景 + +- 多个 Agent 分工协作,而非单个 Agent 从需求写到代码。 +- 需要区分规格、测试、实现、复测的责任边界(Coordinator / Test / Developer 三角色)。 +- 需要把失败项派发给 Developer,`worker_done` 后由独立的 Test 复测、Coordinator 终检。 +- 需要连续修复多个问题,并把三轮仍未修好的问题留档。 + +--- + +## 目录结构 + +```text +ack/ + VERSION # kit 版本,接入时记入项目 + README.md + adoption-checklist.md + core/ # 稳定核心:跨项目通用,随 kit 升级,尽量别改 + roles-and-permissions.md # 角色/权限/状态机/完成定义(SSOT) + model-routing.md # 三角色默认模型档位 + 升级规则(SSOT) + closed-loop.md # 编排无关闭环 + 手动模式 + worktree 对齐 + optimization-method.md # 验收信号 + 三轮失败策略(SSOT) + prompt-templates.md # 派发 prompt 模板 + orca-adapter.md # Orca 具体命令(一种编排实现,可选) + templates/ # 项目覆盖层:复制一次并填空 + project.template.md # 项目覆盖层模板(文件名可配置,默认不占用 AGENTS.md) + tasks.template.yaml + tasks.schema.json # 任务板权威结构(跨语言) + examples/ # 填好的最小可跑示例 + project.example.md + tasks.example.yaml + scripts/ + validate_tasks.py # 校验 tasks.yaml(参考实现) +``` + +**核心原则**:`core/` 是稳定核心,每个概念只定义一次;`templates/` 是项目覆盖层。二者分离,让 kit 升级和项目定制互不干扰。 + +--- + +## 项目目录布局(推荐) + +每个项目在 `docs/ack/` 下只放**一个软链接**加两个项目文件,稳定核心全部走软链接: + +```text +/docs/ack/ + kit -> <此框架目录> # 唯一软链接:core/templates/examples/scripts 全在里面 + project.md # 项目覆盖层(差异),可改名,见下 + tasks.yaml # 项目任务板 +``` + +引用稳定核心时统一走 `kit/` 前缀,例如 `docs/ack/kit/core/roles-and-permissions.md`。 +这样「一个项目一个软链接」,kit 升级自动生效,项目定制(`project.md` + `tasks.yaml`)互不干扰。 + +## 分发方式(二选一) + +### 方式 A:单软链接引用(推荐,可升级) + +把本框架目录整体 symlink 成项目的 `docs/ack/kit`: + +```bash +mkdir -p /docs/ack +ln -s <此框架绝对路径> /docs/ack/kit +``` + +也可用 git submodule / sparse checkout 达到同样效果。项目只维护 `project.md` 与 `tasks.yaml`。 + +### 方式 B:整份复制(简单,手动升级) + +把本框架整目录复制成 `docs/ack/kit/`(或直接铺平到 `docs/ack/`,此时引用去掉 `kit/` 前缀)。**务必**在 `project.md` 与 `tasks.yaml` 的 `kitVersion` 记录来源版本,日后照 `VERSION` diff 升级。 + +### 覆盖层文件名(重要) + +项目差异(路径、命令、handle、模型档位)写在**项目覆盖层文件**里,**默认 `docs/ack/project.md`,不占用 `AGENTS.md`**,以免与团队已有的 `AGENTS.md` 约定冲突。文件名可配置:想让 Agent 自动加载,可在 `AGENTS.md` 加一行指向它,或直接命名为 `AGENTS.md`。无论叫什么,都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。覆盖层只填差异,不复制 `core/` 内容。 + +--- + +## 快速接入 + +1. 建 `docs/ack/`,按方式 A 建单软链接 `kit`。 +2. 复制 `kit/templates/project.template.md` → `docs/ack/project.md`,填项目差异与模型档位,记 `kitVersion`。 +3. 复制 `kit/templates/tasks.template.yaml` → `docs/ack/tasks.yaml`,填 `project`(含 `overlayFile`)与首个任务。 +4. 跑 `python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml` 确认结构。 +5. 按 `kit/core/closed-loop.md` 跑闭环(Orca 见 `kit/core/orca-adapter.md`,无 Orca 用手动模式)。 +6. 逐项对照 `kit/adoption-checklist.md`。 + +参考 `examples/` 里填好的 `project.example.md` 与 `tasks.example.yaml`。 + +--- + +## 默认口令 + +```text +用三角色协作闭环处理 docs/ack/tasks.yaml 里的未通过项:Coordinator 派发给 Developer 修复,再交给 Test 独立复测并终检;每个问题最多修三轮,三轮仍不过就记录为遗留,然后继续下一个。 +``` diff --git a/kits/ack/VERSION b/kits/ack/VERSION new file mode 100644 index 0000000..a918a2a --- /dev/null +++ b/kits/ack/VERSION @@ -0,0 +1 @@ +0.6.0 diff --git a/kits/agent-collaboration-kit/adoption-checklist.md b/kits/ack/adoption-checklist.md similarity index 54% rename from kits/agent-collaboration-kit/adoption-checklist.md rename to kits/ack/adoption-checklist.md index 57e1256..fe64082 100644 --- a/kits/agent-collaboration-kit/adoption-checklist.md +++ b/kits/ack/adoption-checklist.md @@ -4,15 +4,23 @@ ## 1. 分发与版本 -- [ ] 选定分发方式(README §「分发方式」A 引用 / B 复制)。 -- [ ] kit 放到 `docs/agent-collaboration-kit/`。 -- [ ] 项目 `AGENTS.md` 与 `tasks.yaml` 记录 `kitVersion`(对齐 kit 根 `VERSION`)。 +- [ ] 选定分发方式(README §「分发方式」A 单软链接 / B 复制)。 +- [ ] 在 `docs/ack/` 下建单软链接 `kit`(指向本框架)。 +- [ ] 覆盖层文件与 `tasks.yaml` 记录 `kitVersion`(对齐 `kit/VERSION`)。 ## 2. 项目级规范(覆盖层) -- [ ] 由 `templates/AGENTS.template.md` 生成项目根 `AGENTS.md`。 -- [ ] `AGENTS.md` 引用 `docs/agent-collaboration-kit/core/`,不复制其内容。 +- [ ] 由 `kit/templates/project.template.md` 生成覆盖层文件(默认 `docs/ack/project.md`,**不占用 `AGENTS.md`**)。 +- [ ] 在 `tasks.yaml` 的 `project.overlayFile` 记录覆盖层实际路径。 +- [ ] 覆盖层引用 `docs/ack/kit/core/`,不复制其内容。 - [ ] 填清项目简介、技术栈、运行/构建/单测/集成测试命令。 +- [ ] 若要 Agent 自动加载覆盖层:在 `AGENTS.md` 加一行指向它,或直接命名为 `AGENTS.md`(可选)。 + +## 2b. 模型档位 + +- [ ] Coordinator 默认强模型且不亲自跑测试。 +- [ ] Test、Developer 默认中低模型。 +- [ ] 记录升级规则:三轮失败升级 Coordinator 复盘;复杂实现升级 Developer 档位(见 `kit/core/model-routing.md`)。 ## 3. 路径权限 @@ -20,18 +28,18 @@ - [ ] 填实际的 Test 可写路径(集成测试、复测记录)。 - [ ] 填实际的 Developer 可写路径(源码、单元测试、配置模板)。 - [ ] 本地私有配置标记只读或不提交。 -- [ ] 确认 `tasks.yaml` 只有 Coordinator 写(见 `core/roles-and-permissions.md`)。 +- [ ] 确认 `tasks.yaml` 只有 Coordinator 写(见 `kit/core/roles-and-permissions.md`)。 ## 4. 任务板 -- [ ] 由 `templates/tasks.template.yaml` 生成项目根 `tasks.yaml`。 -- [ ] 替换 ``、``、``、``。 -- [ ] 至少加一个真实任务,验收写成可观测信号(见 `core/optimization-method.md` §1)。 -- [ ] 跑 `scripts/validate_tasks.py tasks.yaml` 通过。 +- [ ] 由 `kit/templates/tasks.template.yaml` 生成 `docs/ack/tasks.yaml`。 +- [ ] 替换 ``、``、``、``、`overlayFile`。 +- [ ] 至少加一个真实任务,验收写成可观测信号(见 `kit/core/optimization-method.md` §1)。 +- [ ] 跑 `python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml` 通过。 ## 5. 编排 -- [ ] 决定用 Orca(`core/orca-adapter.md`)还是手动模式(`core/closed-loop.md`)。 +- [ ] 决定用 Orca(`kit/core/orca-adapter.md`)还是手动模式(`kit/core/closed-loop.md`)。 - [ ] Orca:`orca status`、`terminal list` 可用,Coordinator / Developer / Test 三个终端都在,回报能发回 Coordinator。 - [ ] 决定用当前 worktree 还是隔离 worktree。 @@ -58,4 +66,4 @@ - 任务板字段不够记录失败原因。 - 三轮失败策略没被执行。 -把发现的问题回写到项目 `AGENTS.md`;若属通用问题,回流到 kit 的 `core/` 并升 `VERSION`。 +把发现的问题回写到项目覆盖层文件;若属通用问题,回流到 kit 的 `kit/core/` 并升 `VERSION`。 diff --git a/kits/agent-collaboration-kit/core/closed-loop.md b/kits/ack/core/closed-loop.md similarity index 100% rename from kits/agent-collaboration-kit/core/closed-loop.md rename to kits/ack/core/closed-loop.md diff --git a/kits/ack/core/model-routing.md b/kits/ack/core/model-routing.md new file mode 100644 index 0000000..345ce0e --- /dev/null +++ b/kits/ack/core/model-routing.md @@ -0,0 +1,69 @@ +# 模型路由(稳定核心) + +本文件是**三角色默认模型档位**和**升级规则**的单一事实源(SSOT)。目标:在不牺牲质量的前提下降低 token 和模型成本——把昂贵的强模型留给需要判断的工作,把机械执行交给较弱模型。 + +角色定义见 `roles-and-permissions.md`(Coordinator 编排 / Test 验证 / Developer 实现)。本文件只补一层正交的「用哪个档位的模型」。 + +--- + +## 默认档位 + +| 角色 | 默认模型档位 | 理由 | +|------|--------------|------| +| Coordinator (PM) | 强模型 | 需求拆解、验收信号设计、优先级、终检对齐意图、三轮失败复盘都需要高质量推理 | +| Test | 中低模型 | 按既定验收信号执行浏览器/API/脚本,主要做观察、记录、逐条 pass/fail | +| Developer | 中低模型(按任务升级) | 多数实现可照规格执行;跨系统、数据迁移、重复失败时再升级 | + +关键点:Coordinator 用强模型但**不亲自跑测试**(测试由 Test 承担),所以强模型的 token 花在思考和终检上,而不是反复点击页面、跑 smoke、复制日志。这一分工天然省 token,同时保持「验证者 ≠ 实现者」。 + +--- + +## 什么时候用强模型 + +- 新需求理解、产品取舍、范围决策。 +- 架构与数据模型决策。 +- 把验收写成可观测信号(见 `optimization-method.md` §1)。 +- 需求含糊、规格与实现/测试冲突时的裁决。 +- Coordinator 终检:读证据、对齐原始意图。 +- 重复失败后的根因复盘与重新拆分。 + +## 什么时候用中低模型 + +- Test:跑浏览器用例、API smoke、逐条比对期望与实际、产出证据。 +- Developer:从清晰规格实现范围明确的任务、跑构建与单测、回报 worker_done。 + +--- + +## 升级规则 + +**升级到 Coordinator(强模型)复盘**,当: + +- 同一验收路径 Developer 连续失败三轮(见 `optimization-method.md` §4)。 +- Test 两次仍无法给出清晰失败证据。 +- 任务需要改动产品范围或验收标准。 +- 修复涉及持久化数据、破坏性文件操作、安全或回滚。 +- 规格、测试、实现三者出现冲突。 + +**升级 Developer 模型档位**,当: + +- 任务横跨多个子系统。 +- 改动涉及数据模型或迁移。 +- 需要设计新的抽象。 +- 低档位反复产出表面修复。 + +升级动作本身由 Coordinator 判断并记录(可写进 `tasks.yaml` 的 `dispatch` 备注或 `resolution`)。 + +--- + +## 成本原则 + +强模型产出高密度、可复用的产物:需求、架构决策、验收信号、任务拆分、失败复盘。 +中低模型消费这些产物,产出可核对的执行证据:测试结果、快照、API 响应、构建日志、改动文件清单。 + +这样把昂贵推理挡在重复执行之外。 + +--- + +## 一句话 + +Coordinator 是脑,Test 是眼,Developer 是手。脑用最强的模型且不做机械测试,眼和手用便宜模型,只有常规闭环卡住时才升级。 diff --git a/kits/agent-collaboration-kit/core/optimization-method.md b/kits/ack/core/optimization-method.md similarity index 100% rename from kits/agent-collaboration-kit/core/optimization-method.md rename to kits/ack/core/optimization-method.md diff --git a/kits/agent-collaboration-kit/core/orca-adapter.md b/kits/ack/core/orca-adapter.md similarity index 97% rename from kits/agent-collaboration-kit/core/orca-adapter.md rename to kits/ack/core/orca-adapter.md index 4177da4..cab9269 100644 --- a/kits/agent-collaboration-kit/core/orca-adapter.md +++ b/kits/ack/core/orca-adapter.md @@ -55,12 +55,12 @@ Repository: - Path: - Worktree: -Read: AGENTS.md, tasks.yaml, +Read: (project overlay), tasks.yaml, Failure evidence: Acceptance: Constraints: -- Follow AGENTS.md path scope. +- Follow the overlay file path scope. - Do not write tasks.yaml, do not mark verified. - Do not commit or push unless user asks. EOF diff --git a/kits/agent-collaboration-kit/core/prompt-templates.md b/kits/ack/core/prompt-templates.md similarity index 94% rename from kits/agent-collaboration-kit/core/prompt-templates.md rename to kits/ack/core/prompt-templates.md index 5fa6025..afe6cdb 100644 --- a/kits/agent-collaboration-kit/core/prompt-templates.md +++ b/kits/ack/core/prompt-templates.md @@ -15,7 +15,7 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发 - 修复 : 请先读取: -- AGENTS.md +- (项目覆盖层,路径见 tasks.yaml 的 project.overlayFile) - tasks.yaml - @@ -28,7 +28,7 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发 3. 约束: -- 只修改 Developer 可写路径(见 AGENTS.md 权限表)。 +- 只修改 Developer 可写路径(见覆盖层文件的权限表)。 - 不要修改产品规格和集成测试文件(分别由 Coordinator 与 Test 拥有),除非任务明确要求。 - 不要写 tasks.yaml,不要标记 verified。 - 不要提交或推送,除非用户明确要求。 @@ -78,7 +78,7 @@ Developer 回报 worker_done 后,Coordinator 把复测任务发给 Test。 请对 : 做独立黑盒复测。 请先读取: -- AGENTS.md +- (项目覆盖层,路径见 tasks.yaml 的 project.overlayFile) - tasks.yaml(该任务的验收信号) - diff --git a/kits/agent-collaboration-kit/core/roles-and-permissions.md b/kits/ack/core/roles-and-permissions.md similarity index 90% rename from kits/agent-collaboration-kit/core/roles-and-permissions.md rename to kits/ack/core/roles-and-permissions.md index 77d0c43..2ad8254 100644 --- a/kits/agent-collaboration-kit/core/roles-and-permissions.md +++ b/kits/ack/core/roles-and-permissions.md @@ -19,11 +19,13 @@ **独立验证权归 Test。** Coordinator 不亲自复测——它读 Test 的证据,并对照任务的原始意图做一次终检(见「完成定义」)。`worker_done` 不等于完成的原则同时适用于 Developer 和 Test:结论只有落到 `tasks.yaml` 才算数。 +**模型档位(正交层)。** 三角色默认按成本分层:Coordinator 用强模型,Test 与 Developer 用中低模型,必要时升级。完整档位表与升级规则见 `model-routing.md`。Coordinator 用强模型但不跑测试,这一分工天然省 token 又不破坏「验证者 ≠ 实现者」。 + --- ## 路径权限模板 -目标项目在自己的 `AGENTS.md` 中填入实际路径(见 `templates/AGENTS.template.md`)。 +目标项目在自己的**覆盖层文件**中填入实际路径(模板见 `templates/project.template.md`;覆盖层默认 `docs/ack/project.md`,路径记在 `tasks.yaml` 的 `project.overlayFile`)。 | 路径 | Coordinator | Test | Developer | 说明 | |------|:-----------:|:----:|:---------:|------| diff --git a/kits/agent-collaboration-kit/examples/AGENTS.example.md b/kits/ack/examples/project.example.md similarity index 56% rename from kits/agent-collaboration-kit/examples/AGENTS.example.md rename to kits/ack/examples/project.example.md index c0ef6a0..93c59ef 100644 --- a/kits/agent-collaboration-kit/examples/AGENTS.example.md +++ b/kits/ack/examples/project.example.md @@ -1,7 +1,9 @@ -# notes-web Agent 协作协议(示例) +# notes-web Agent 协作协议(示例,项目覆盖层) -> 本项目基于 agent-collaboration-kit v0.3.0。 -> 稳定规范引用 `docs/agent-collaboration-kit/core/`,本文件只填项目差异。 +> 本项目基于 ack v0.6.0。 +> 稳定规范引用 `docs/ack/kit/core/`,本文件只填项目差异。 +> 覆盖层文件放在 `docs/ack/project.md`,不占用 `AGENTS.md`。 +> 目录下只有一个软链接 `kit/` + `project.md` + `tasks.yaml`。 ## 项目概览 @@ -9,15 +11,25 @@ - 技术栈:`TypeScript + React (Vite) + Go` - 运行命令:`npm run dev`(前端)、`go run ./server`(后端) - Base URL:`http://localhost:5173` -- 任务板:`tasks.yaml` +- 任务板:`docs/ack/tasks.yaml` +- 覆盖层文件:`docs/ack/project.md` ## 稳定规范(引用,不重复) -- 角色 / 权限 / 状态机 / 完成定义:`docs/agent-collaboration-kit/core/roles-and-permissions.md` -- 闭环流程(含手动模式、worktree 对齐):`docs/agent-collaboration-kit/core/closed-loop.md` -- 优化方法(验收信号、三轮策略):`docs/agent-collaboration-kit/core/optimization-method.md` -- 派发 prompt 模板:`docs/agent-collaboration-kit/core/prompt-templates.md` -- Orca 编排命令:`docs/agent-collaboration-kit/core/orca-adapter.md` +- 角色 / 权限 / 状态机 / 完成定义:`docs/ack/kit/core/roles-and-permissions.md` +- 模型档位与升级规则:`docs/ack/kit/core/model-routing.md` +- 闭环流程(含手动模式、worktree 对齐):`docs/ack/kit/core/closed-loop.md` +- 优化方法(验收信号、三轮策略):`docs/ack/kit/core/optimization-method.md` +- 派发 prompt 模板:`docs/ack/kit/core/prompt-templates.md` +- Orca 编排命令:`docs/ack/kit/core/orca-adapter.md` + +## 模型档位 + +| 角色 | 默认档位 | 本项目实际 | +|------|----------|------------| +| Coordinator (PM) | 强模型 | claude-sonnet-5-thinking-high | +| Test | 中低模型 | 默认(中低) | +| Developer | 中低模型 | 默认(中低),架构任务临时升级 | ## 路径权限 @@ -53,12 +65,13 @@ curl -s -X POST http://localhost:5173/api/fix/preview -d @fixtures/preview.json 任务板校验: ```bash -python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml +python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml ``` -## 硬规则(其余见 core/) +## 硬规则(其余见 kit/core/) - 三角色独立:Coordinator 只编排、Test 只验证、Developer 只实现。 +- 模型分层:Coordinator 强模型不跑测试,Test/Developer 中低模型(见 kit/core/model-routing.md)。 - `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/ack/examples/tasks.example.yaml similarity index 100% rename from kits/agent-collaboration-kit/examples/tasks.example.yaml rename to kits/ack/examples/tasks.example.yaml diff --git a/kits/agent-collaboration-kit/scripts/validate_tasks.py b/kits/ack/scripts/validate_tasks.py similarity index 98% rename from kits/agent-collaboration-kit/scripts/validate_tasks.py rename to kits/ack/scripts/validate_tasks.py index 61fdef4..0ab7c92 100755 --- a/kits/agent-collaboration-kit/scripts/validate_tasks.py +++ b/kits/ack/scripts/validate_tasks.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""校验 tasks.yaml 是否符合 agent-collaboration-kit 任务板结构。 +"""校验 tasks.yaml 是否符合 ack 任务板结构。 权威结构是同目录上层的 templates/tasks.schema.json(跨语言可用)。 本脚本是参考实现: diff --git a/kits/ack/templates/project.template.md b/kits/ack/templates/project.template.md new file mode 100644 index 0000000..c2836a0 --- /dev/null +++ b/kits/ack/templates/project.template.md @@ -0,0 +1,83 @@ +# <项目名> Agent 协作协议(项目覆盖层) + +> 本项目基于 ack v(见 `docs/ack/kit/VERSION`)。 +> 稳定规范引用 `docs/ack/kit/core/`,不复制其内容;本文件只填项目自己的差异。 +> +> **本文件是「项目覆盖层」,文件名可配置。** 默认放 `docs/ack/project.md`, +> 不占用 `AGENTS.md`,避免与团队已有的 `AGENTS.md` 约定冲突。 +> 若希望 Agent 自动加载,可在项目 `AGENTS.md` 里加一行指向本文件,或直接把本文件命名为 `AGENTS.md`。 +> 无论叫什么,都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。 +> +> 目录约定:`docs/ack/` 下只有一个软链接 `kit/`(指向共享框架),加本项目 `project.md` + `tasks.yaml`。 + +## 项目概览 + +- 项目:`` +- 技术栈:`` +- 运行命令:`` +- Base URL:`` +- 任务板:`docs/ack/tasks.yaml` +- 覆盖层文件:``(默认 `docs/ack/project.md`) + +## 稳定规范(不在此重复,直接引用) + +- 角色模型 / 权限 / 状态机 / 完成定义:`docs/ack/kit/core/roles-and-permissions.md` +- 模型档位与升级规则:`docs/ack/kit/core/model-routing.md` +- 闭环流程(含手动模式、worktree 对齐):`docs/ack/kit/core/closed-loop.md` +- 优化方法(验收信号、三轮策略):`docs/ack/kit/core/optimization-method.md` +- 派发 prompt 模板:`docs/ack/kit/core/prompt-templates.md` +- Orca 编排命令(可选):`docs/ack/kit/core/orca-adapter.md` + +## 模型档位(项目可覆盖,默认见 core/model-routing.md) + +| 角色 | 默认档位 | 本项目实际 | +|------|----------|------------| +| Coordinator (PM) | 强模型 | `` | +| Test | 中低模型 | `` | +| Developer | 中低模型 | `` | + +## 路径权限(项目覆盖层,必须填实际路径) + +| 路径 | 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 写 | + +## 命令(项目覆盖层) + +Developer 白盒验证: + +```bash + + + +``` + +Test 黑盒复测: + +```bash + + + +``` + +任务板校验: + +```bash +python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml +``` + +## 硬规则(其余见 kit/core/) + +- 三角色独立:Coordinator 只编排、Test 只验证、Developer 只实现(验证者 ≠ 实现者)。 +- 模型分层:Coordinator 用强模型且不亲自跑测试,Test/Developer 用中低模型,必要时升级(见 kit/core/model-routing.md)。 +- `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/ack/templates/tasks.schema.json similarity index 91% rename from kits/agent-collaboration-kit/templates/tasks.schema.json rename to kits/ack/templates/tasks.schema.json index 3a9de36..ee8aacb 100644 --- a/kits/agent-collaboration-kit/templates/tasks.schema.json +++ b/kits/ack/templates/tasks.schema.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://git.yumee.top/laily/skills/kits/agent-collaboration-kit/tasks.schema.json", + "$id": "https://git.yumee.top/laily/skills/kits/ack/tasks.schema.json", "title": "Agent Collaboration Kit task board", "description": "tasks.yaml 的权威结构。跨语言可用;参考校验实现见 scripts/validate_tasks.py。", "type": "object", @@ -12,7 +12,7 @@ "source": { "type": "string" }, "kitVersion": { "type": "string", - "description": "接入时所基于的 agent-collaboration-kit 版本,便于日后 diff 升级" + "description": "接入时所基于的 ack 版本,便于日后 diff 升级" }, "project": { "type": "object", @@ -22,7 +22,11 @@ "name": { "type": "string" }, "repoPath": { "type": "string" }, "baseUrl": { "type": "string" }, - "devWorktree": { "type": "string" } + "devWorktree": { "type": "string" }, + "overlayFile": { + "type": "string", + "description": "项目覆盖层文件路径,默认 docs/ack/project.md,可自定义" + } } }, "summary": { diff --git a/kits/agent-collaboration-kit/templates/tasks.template.yaml b/kits/ack/templates/tasks.template.yaml similarity index 87% rename from kits/agent-collaboration-kit/templates/tasks.template.yaml rename to kits/ack/templates/tasks.template.yaml index 688c3b3..3490ee7 100644 --- a/kits/agent-collaboration-kit/templates/tasks.template.yaml +++ b/kits/ack/templates/tasks.template.yaml @@ -1,13 +1,14 @@ -# 复制到项目根目录为 tasks.yaml,替换占位符。结构见 templates/tasks.schema.json。 +# 复制为 docs/ack/tasks.yaml,替换占位符。结构见 templates/tasks.schema.json。 version: 1 updatedAt: "" source: "Coordinator (PM) Agent" -kitVersion: "<接入时的 agent-collaboration-kit 版本,见 kit 根 VERSION>" +kitVersion: "<接入时的 ack 版本,见 kit 根 VERSION>" project: name: "" repoPath: "" baseUrl: "" devWorktree: "" + overlayFile: "docs/ack/project.md" summary: verified: [] diff --git a/kits/agent-collaboration-kit/README.md b/kits/agent-collaboration-kit/README.md deleted file mode 100644 index 63798c0..0000000 --- a/kits/agent-collaboration-kit/README.md +++ /dev/null @@ -1,77 +0,0 @@ -# Agent Collaboration Kit - -一套可复用到其它项目的多 Agent 协作规范,默认三个独立角色:**Coordinator (PM) 拆解需求并调度闭环,Developer 实现与白盒验证,Test 独立黑盒复测**。关键属性是验证者 ≠ 实现者。 - -当前版本见 `VERSION`。这不是 Agent Skill(无 `SKILL.md`),不由 skiff 安装,而是复制/引用到目标项目。 - ---- - -## 适用场景 - -- 多个 Agent 分工协作,而非单个 Agent 从需求写到代码。 -- 需要区分规格、测试、实现、复测的责任边界(Coordinator / Test / Developer 三角色)。 -- 需要把失败项派发给 Developer,`worker_done` 后由独立的 Test 复测、Coordinator 终检。 -- 需要连续修复多个问题,并把三轮仍未修好的问题留档。 - ---- - -## 目录结构 - -```text -agent-collaboration-kit/ - VERSION # kit 版本,接入时记入项目 - README.md - adoption-checklist.md - core/ # 稳定核心:跨项目通用,随 kit 升级,尽量别改 - roles-and-permissions.md # 角色/权限/状态机/完成定义(SSOT) - closed-loop.md # 编排无关闭环 + 手动模式 + worktree 对齐 - optimization-method.md # 验收信号 + 三轮失败策略(SSOT) - prompt-templates.md # 派发 prompt 模板 - orca-adapter.md # Orca 具体命令(一种编排实现,可选) - templates/ # 项目覆盖层:复制一次并填空 - AGENTS.template.md - tasks.template.yaml - tasks.schema.json # 任务板权威结构(跨语言) - examples/ # 填好的最小可跑示例 - AGENTS.example.md - tasks.example.yaml - scripts/ - validate_tasks.py # 校验 tasks.yaml(参考实现) -``` - -**核心原则**:`core/` 是稳定核心,每个概念只定义一次;`templates/` 是项目覆盖层。二者分离,让 kit 升级和项目定制互不干扰。 - ---- - -## 分发方式(二选一) - -### 方式 A:引用稳定核心(推荐,可升级) - -`core/` + `scripts/` 通过 symlink / git submodule / sparse checkout 映射到项目 `docs/agent-collaboration-kit/`;项目只维护自己的 `AGENTS.md`、`tasks.yaml`。kit 升级时稳定核心自动生效,项目定制不受影响。 - -### 方式 B:整份复制(简单,手动升级) - -整目录复制到 `docs/agent-collaboration-kit/`。**务必**在项目 `AGENTS.md` 与 `tasks.yaml` 的 `kitVersion` 记录来源版本,日后照 `VERSION` diff 升级 `core/`。 - -无论哪种方式,项目的 `AGENTS.md` 只填差异(路径、命令、handle),不复制 `core/` 内容。 - ---- - -## 快速接入 - -1. 选定分发方式,把 kit 放到项目 `docs/agent-collaboration-kit/`。 -2. 复制 `templates/AGENTS.template.md` → 项目根 `AGENTS.md`,填项目差异,记 `kitVersion`。 -3. 复制 `templates/tasks.template.yaml` → 项目根 `tasks.yaml`,填 `project` 与首个任务。 -4. 跑 `python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml` 确认结构。 -5. 按 `core/closed-loop.md` 跑闭环(Orca 见 `core/orca-adapter.md`,无 Orca 用手动模式)。 -6. 逐项对照 `adoption-checklist.md`。 - -参考 `examples/` 里填好的 `AGENTS.example.md` 与 `tasks.example.yaml`。 - ---- - -## 默认口令 - -```text -用三角色协作闭环处理 tasks.yaml 里的未通过项:Coordinator 派发给 Developer 修复,再交给 Test 独立复测并终检;每个问题最多修三轮,三轮仍不过就记录为遗留,然后继续下一个。 -``` diff --git a/kits/agent-collaboration-kit/VERSION b/kits/agent-collaboration-kit/VERSION deleted file mode 100644 index 0d91a54..0000000 --- a/kits/agent-collaboration-kit/VERSION +++ /dev/null @@ -1 +0,0 @@ -0.3.0 diff --git a/kits/agent-collaboration-kit/templates/AGENTS.template.md b/kits/agent-collaboration-kit/templates/AGENTS.template.md deleted file mode 100644 index 428e1ee..0000000 --- a/kits/agent-collaboration-kit/templates/AGENTS.template.md +++ /dev/null @@ -1,65 +0,0 @@ -# <项目名> Agent 协作协议 - -> 本项目基于 agent-collaboration-kit v(见 kit 根 `VERSION`)。 -> 稳定规范引用 `docs/agent-collaboration-kit/core/`,不复制其内容;本文件只填项目自己的差异。 - -## 项目概览 - -- 项目:`` -- 技术栈:`` -- 运行命令:`` -- Base URL:`` -- 任务板:`tasks.yaml` - -## 稳定规范(不在此重复,直接引用) - -- 角色模型 / 权限 / 状态机 / 完成定义:`docs/agent-collaboration-kit/core/roles-and-permissions.md` -- 闭环流程(含手动模式、worktree 对齐):`docs/agent-collaboration-kit/core/closed-loop.md` -- 优化方法(验收信号、三轮策略):`docs/agent-collaboration-kit/core/optimization-method.md` -- 派发 prompt 模板:`docs/agent-collaboration-kit/core/prompt-templates.md` -- Orca 编排命令(可选):`docs/agent-collaboration-kit/core/orca-adapter.md` - -## 路径权限(项目覆盖层,必须填实际路径) - -| 路径 | 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 写 | - -## 命令(项目覆盖层) - -Developer 白盒验证: - -```bash - - - -``` - -Test 黑盒复测: - -```bash - - - -``` - -任务板校验: - -```bash -python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml -``` - -## 硬规则(其余见 core/) - -- 三角色独立:Coordinator 只编排、Test 只验证、Developer 只实现(验证者 ≠ 实现者)。 -- `worker_done` 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 `verified`。 -- 只有 Coordinator 写 `tasks.yaml`;Developer 与 Test 都只读,通过消息回报。 -- 每个任务最多派发 3 轮,仍不过标记 `leftover` 并继续下一个。 -- 不提交或推送,除非用户明确要求。