feat: rename
This commit is contained in:
@@ -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
|
||||
<project>/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 <project>/docs/ack
|
||||
ln -s <此框架绝对路径> <project>/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 独立复测并终检；每个问题最多修三轮，三轮仍不过就记录为遗留，然后继续下一个。
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
0.6.0
|
||||
+20
-12
@@ -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`。
|
||||
- [ ] 替换 `<project_name>`、`<repo_path>`、`<base_url>`、`<dev_worktree>`。
|
||||
- [ ] 至少加一个真实任务，验收写成可观测信号（见 `core/optimization-method.md` §1）。
|
||||
- [ ] 跑 `scripts/validate_tasks.py tasks.yaml` 通过。
|
||||
- [ ] 由 `kit/templates/tasks.template.yaml` 生成 `docs/ack/tasks.yaml`。
|
||||
- [ ] 替换 `<project_name>`、`<repo_path>`、`<base_url>`、`<dev_worktree>`、`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`。
|
||||
@@ -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 是手。脑用最强的模型且不做机械测试，眼和手用便宜模型，只有常规闭环卡住时才升级。
|
||||
@@ -55,12 +55,12 @@ Repository:
|
||||
- Path: <repo_path>
|
||||
- Worktree: <dev_worktree>
|
||||
|
||||
Read: AGENTS.md, tasks.yaml, <relevant_spec_or_test_doc>
|
||||
Read: <overlay_file> (project overlay), tasks.yaml, <relevant_spec_or_test_doc>
|
||||
Failure evidence: <copy latest Test evidence>
|
||||
Acceptance: <copy expected behavior + verification commands>
|
||||
|
||||
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
|
||||
+3
-3
@@ -15,7 +15,7 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
|
||||
- 修复 <task_id>: <task_title>
|
||||
|
||||
请先读取：
|
||||
- AGENTS.md
|
||||
- <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
|
||||
- tasks.yaml
|
||||
- <relevant_spec_or_test_doc>
|
||||
|
||||
@@ -28,7 +28,7 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
|
||||
3. <expected behavior 3>
|
||||
|
||||
约束：
|
||||
- 只修改 Developer 可写路径（见 AGENTS.md 权限表）。
|
||||
- 只修改 Developer 可写路径（见覆盖层文件的权限表）。
|
||||
- 不要修改产品规格和集成测试文件（分别由 Coordinator 与 Test 拥有），除非任务明确要求。
|
||||
- 不要写 tasks.yaml，不要标记 verified。
|
||||
- 不要提交或推送，除非用户明确要求。
|
||||
@@ -78,7 +78,7 @@ Developer 回报 worker_done 后，Coordinator 把复测任务发给 Test。
|
||||
请对 <task_id>: <task_title> 做独立黑盒复测。
|
||||
|
||||
请先读取：
|
||||
- AGENTS.md
|
||||
- <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
|
||||
- tasks.yaml（该任务的验收信号）
|
||||
- <relevant_spec_or_test_doc>
|
||||
|
||||
+3
-1
@@ -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 | 说明 |
|
||||
|------|:-----------:|:----:|:---------:|------|
|
||||
+24
-11
@@ -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` 并继续。
|
||||
+1
-1
@@ -1,5 +1,5 @@
|
||||
#!/usr/bin/env python3
|
||||
"""校验 tasks.yaml 是否符合 agent-collaboration-kit 任务板结构。
|
||||
"""校验 tasks.yaml 是否符合 ack 任务板结构。
|
||||
|
||||
权威结构是同目录上层的 templates/tasks.schema.json（跨语言可用）。
|
||||
本脚本是参考实现：
|
||||
@@ -0,0 +1,83 @@
|
||||
# <项目名> Agent 协作协议（项目覆盖层）
|
||||
|
||||
> 本项目基于 ack v<kit_version>（见 `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`。
|
||||
|
||||
## 项目概览
|
||||
|
||||
- 项目：`<project_name>`
|
||||
- 技术栈：`<tech_stack>`
|
||||
- 运行命令：`<run_command>`
|
||||
- Base URL：`<base_url>`
|
||||
- 任务板：`docs/ack/tasks.yaml`
|
||||
- 覆盖层文件：`<overlay_file_path>`（默认 `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) | 强模型 | `<model_or_default>` |
|
||||
| Test | 中低模型 | `<model_or_default>` |
|
||||
| Developer | 中低模型 | `<model_or_default>` |
|
||||
|
||||
## 路径权限（项目覆盖层，必须填实际路径）
|
||||
|
||||
| 路径 | Coordinator | Test | Developer | 说明 |
|
||||
|------|:-----------:|:----:|:---------:|------|
|
||||
| `<spec_paths>` | R/W | Read-only | Read-only | 产品规格、API 文档、计划（PM 拥有） |
|
||||
| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器/API 回归（Test 拥有） |
|
||||
| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录 |
|
||||
| `<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_paths>` | Read-only | Read-only | Read-only | 本地私有配置 |
|
||||
| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
|
||||
|
||||
## 命令（项目覆盖层）
|
||||
|
||||
Developer 白盒验证：
|
||||
|
||||
```bash
|
||||
<unit_test_command>
|
||||
<build_command>
|
||||
<local_run_command>
|
||||
```
|
||||
|
||||
Test 黑盒复测：
|
||||
|
||||
```bash
|
||||
<preflight_command>
|
||||
<api_smoke_command>
|
||||
<browser_regression_command>
|
||||
```
|
||||
|
||||
任务板校验：
|
||||
|
||||
```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` 并继续下一个。
|
||||
- 不提交或推送，除非用户明确要求。
|
||||
+7
-3
@@ -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": {
|
||||
+3
-2
@@ -1,13 +1,14 @@
|
||||
# 复制到项目根目录为 tasks.yaml，替换占位符。结构见 templates/tasks.schema.json。
|
||||
# 复制为 docs/ack/tasks.yaml，替换占位符。结构见 templates/tasks.schema.json。
|
||||
version: 1
|
||||
updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
|
||||
source: "Coordinator (PM) Agent"
|
||||
kitVersion: "<接入时的 agent-collaboration-kit 版本，见 kit 根 VERSION>"
|
||||
kitVersion: "<接入时的 ack 版本，见 kit 根 VERSION>"
|
||||
project:
|
||||
name: "<project_name>"
|
||||
repoPath: "<repo_path>"
|
||||
baseUrl: "<base_url>"
|
||||
devWorktree: "<dev_worktree>"
|
||||
overlayFile: "docs/ack/project.md"
|
||||
|
||||
summary:
|
||||
verified: []
|
||||
@@ -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 独立复测并终检；每个问题最多修三轮，三轮仍不过就记录为遗留，然后继续下一个。
|
||||
```
|
||||
@@ -1 +0,0 @@
|
||||
0.3.0
|
||||
@@ -1,65 +0,0 @@
|
||||
# <项目名> Agent 协作协议
|
||||
|
||||
> 本项目基于 agent-collaboration-kit v<kit_version>（见 kit 根 `VERSION`）。
|
||||
> 稳定规范引用 `docs/agent-collaboration-kit/core/`，不复制其内容；本文件只填项目自己的差异。
|
||||
|
||||
## 项目概览
|
||||
|
||||
- 项目：`<project_name>`
|
||||
- 技术栈：`<tech_stack>`
|
||||
- 运行命令：`<run_command>`
|
||||
- Base URL：`<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 | 说明 |
|
||||
|------|:-----------:|:----:|:---------:|------|
|
||||
| `<spec_paths>` | R/W | Read-only | Read-only | 产品规格、API 文档、计划（PM 拥有） |
|
||||
| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器/API 回归（Test 拥有） |
|
||||
| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录 |
|
||||
| `<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_paths>` | Read-only | Read-only | Read-only | 本地私有配置 |
|
||||
| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
|
||||
|
||||
## 命令（项目覆盖层）
|
||||
|
||||
Developer 白盒验证：
|
||||
|
||||
```bash
|
||||
<unit_test_command>
|
||||
<build_command>
|
||||
<local_run_command>
|
||||
```
|
||||
|
||||
Test 黑盒复测：
|
||||
|
||||
```bash
|
||||
<preflight_command>
|
||||
<api_smoke_command>
|
||||
<browser_regression_command>
|
||||
```
|
||||
|
||||
任务板校验：
|
||||
|
||||
```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` 并继续下一个。
|
||||
- 不提交或推送，除非用户明确要求。
|
||||
Reference in New Issue
Block a user