feat: rename

2026-07-07 01:33:48 +08:00
parent 6bd03c2f6d
commit f33992a0aa
18 changed files with 317 additions and 178 deletions
@@ -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 独立复测并终检；每个问题最多修三轮，三轮仍不过就记录为遗留，然后继续下一个。
+```