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 终检。
需要连续修复多个问题，并把三轮仍未修好的问题留档。

目录结构

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/ 下只放一个软链接加两个项目文件，稳定核心全部走软链接：

<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：

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。

建 docs/ack/，按方式 A 建单软链接 kit。
复制 kit/templates/project.template.md → docs/ack/project.md，填项目差异与模型档位，记 kitVersion。
复制 kit/templates/tasks.template.yaml → docs/ack/tasks.yaml，填 project（含 overlayFile）与首个任务。
跑 python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml 确认结构。
按 kit/core/closed-loop.md 跑闭环（Orca 见 kit/core/orca-adapter.md，无 Orca 用手动模式）。
逐项对照 kit/adoption-checklist.md。

参考 examples/ 里填好的 project.example.md 与 tasks.example.yaml。

常用使用方法

开一个新需求（最常用）

你（强模型会话）就是 Coordinator(PM)。完整手册见 core/kickoff.md，开场指令：

我要做一个新需求：<一句话需求>。你作为 ack 的 Coordinator(PM)，按 docs/ack/kit/core 规范：
先读 project.md 与 core/*；写产品文档到 docs/ 并把需求拆成带可观测验收信号的任务写进 docs/ack/tasks.yaml；
先给我确认产品文档+任务拆分，再按 project.md 优先复用空闲 DEV/TEST worker，没有时才校验并创建，核对实际模型后循环派发/复测/终检；
每个任务最多三轮，三轮不过记 leftover。

复用或启动 worker

先按 core/orca-adapter.md §「解析并复用 worker」运行 terminal list 和活跃任务查询。只有没有同 worktree、同角色、配置兼容的空闲 worker 时，才执行下面的创建命令：

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 "ACK-DEV-CODEX-TERRA-1" --json
orca terminal create --worktree active --command "$TEST_CMD" --title "ACK-TEST-CODEX-LUNA-1" --json

# Cursor worker 使用同一项目校验器
CURSOR_CMD='cursor-agent --yolo --model auto'
python3 docs/ack/validate_worker_command.py --role developer --command "$CURSOR_CMD"

派发成功后把实际 handle 写入任务的 dispatch.worker，下次优先复用。需要隔离/并行时先建 worktree：orca worktree create --name <feature> --base-branch <base> --json（选择依据见 core/closed-loop.md）。

派发与等待（Orca）

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。

校验任务板结构

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`

默认口令

用三角色协作闭环处理 docs/ack/tasks.yaml 里的未通过项：Coordinator 派发给 Developer 修复，再交给 Test 独立复测并终检；每个问题最多修三轮，三轮仍不过就记录为遗留，然后继续下一个。

README.md Unescape Escape

ack — Agent Collaboration Kit