174 lines
8.2 KiB
Markdown
174 lines
8.2 KiB
Markdown
# 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
|
||
init-new-project.md # 给 Agent 的新项目初始化手册
|
||
adoption-checklist.md
|
||
core/ # 稳定核心：跨项目通用，随 kit 升级，尽量别改
|
||
kickoff.md # 如何开始一个需求（启动手册 + 开场指令模板）
|
||
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/` 内容。
|
||
|
||
---
|
||
|
||
## 快速接入
|
||
|
||
让 Agent 在新项目执行初始化时，优先给它 `init-new-project.md`。
|
||
|
||
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`。
|
||
|
||
---
|
||
|
||
## 常用使用方法
|
||
|
||
### 开一个新需求（最常用）
|
||
|
||
你（强模型会话）就是 Coordinator(PM)。完整手册见 `core/kickoff.md`，开场指令：
|
||
|
||
```text
|
||
我要做一个新需求：<一句话需求>。你作为 ack 的 Coordinator(PM)，按 docs/ack/kit/core 规范：
|
||
先读 project.md 与 core/*；写产品文档到 docs/ 并把需求拆成带可观测验收信号的任务写进 docs/ack/tasks.yaml；
|
||
先给我确认产品文档+任务拆分，再按 project.md 校验并启动 DEV/TEST worker，核对实际模型后循环派发/复测/终检；
|
||
每个任务最多三轮，三轮不过记 leftover。
|
||
```
|
||
|
||
### 校验并启动 worker
|
||
|
||
```bash
|
||
DEV_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-terra -c model_reasoning_effort=medium'
|
||
TEST_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna -c model_reasoning_effort=low'
|
||
python3 docs/ack/validate_worker_command.py --role developer --command "$DEV_CMD"
|
||
python3 docs/ack/validate_worker_command.py --role test --command "$TEST_CMD"
|
||
orca terminal create --worktree active --command "$DEV_CMD" --title "DEV" --json
|
||
orca terminal create --worktree active --command "$TEST_CMD" --title "TEST" --json
|
||
|
||
# Cursor worker 使用同一项目校验器
|
||
CURSOR_CMD='cursor-agent --yolo --model auto'
|
||
python3 docs/ack/validate_worker_command.py --role developer --command "$CURSOR_CMD"
|
||
```
|
||
|
||
需要隔离/并行时先建 worktree：`orca worktree create --name <feature> --base-branch <base> --json`（选择依据见 `core/closed-loop.md`）。
|
||
|
||
### 派发与等待（Orca）
|
||
|
||
```bash
|
||
orca orchestration task-create --spec "<任务与验收>" --json
|
||
orca orchestration dispatch --task <task_id> --to <dev_handle> --json
|
||
orca orchestration check --terminal <coordinator_handle> --wait \
|
||
--types worker_done,retest_result,escalation,decision_gate --timeout-ms 900000 --json
|
||
```
|
||
|
||
不能 `--inject` 时手动投递 `core/prompt-templates.md` 的模板；命令细节见 `core/orca-adapter.md`。
|
||
|
||
### 校验任务板结构
|
||
|
||
```bash
|
||
python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
|
||
```
|
||
|
||
### 只处理已有未通过项
|
||
|
||
用「默认口令」（见下）让 Coordinator 直接扫 `tasks.yaml` 里的 `open` / `failed_retest` 继续闭环。
|
||
|
||
### 速查：想做什么 → 看哪个文件
|
||
|
||
| 想做的事 | 文件 |
|
||
|----------|------|
|
||
| 开一个新需求怎么起步 | `core/kickoff.md` |
|
||
| 角色/权限/状态机/完成定义 | `core/roles-and-permissions.md` |
|
||
| 三角色各自该怎么做（规划/写测试/复测能力清单） | `core/roles-and-permissions.md` §三角色能力清单 |
|
||
| 用哪个模型、怎么固定、何时升级 | `core/model-routing.md` |
|
||
| 闭环步骤、手动模式、worktree 决策与对齐 | `core/closed-loop.md` |
|
||
| 验收信号写法、三轮失败策略 | `core/optimization-method.md` |
|
||
| 派发/复测/回报的 prompt 文案 | `core/prompt-templates.md` |
|
||
| Orca 具体命令 | `core/orca-adapter.md` |
|
||
| 让 Agent 在新项目初始化 ack | `init-new-project.md` |
|
||
| 新项目接入步骤 | `adoption-checklist.md` |
|
||
|
||
---
|
||
|
||
## 默认口令
|
||
|
||
```text
|
||
用三角色协作闭环处理 docs/ack/tasks.yaml 里的未通过项：Coordinator 派发给 Developer 修复，再交给 Test 独立复测并终检；每个问题最多修三轮，三轮仍不过就记录为遗留，然后继续下一个。
|
||
```
|