# ACK

ACK 是显式调用的 Agent Skill，用三种独立角色跑工程协作闭环：

- Coordinator 拆解需求、派发任务并终检
- Developer 实现并做白盒验证
- Test 独立做黑盒复测

验证者不能等于实现者。每个任务最多修三轮，仍不过就记为 `leftover`，然后继续别的任务。

测试环境由 ACK 触发、内部调用 [deployer](../deployer/README.md)。发版写在同一份 `.pouch/ack/delivery.yaml`。功能或 bug 验证通过后，黑盒用例收进 `.pouch/ack/regression.yaml`，之后可以单独跑回归。

只在你显式说 `/ack` 或 `$ack` 时运行。

## 什么时候使用

| 场景 | 怎么说 | 结果 |
| --- | --- | --- |
| 初始化 | `/ack 初始化` | 生成并补全 `.pouch/ack/`；缺项按统一格式列出 |
| 检查 | `/ack 检查配置` | 只读校验，默认不改文件；测试环境缺 deployer 时转交 |
| 做需求 | `/ack 处理这个需求：…` | 产品文档 + 拆任务 → 你确认 → 三角色闭环 |
| 修 bug | `/ack 修这个 bug：…` 或处理飞书收件 | 短描述 + 验收 → 你确认（飞书须你点「已确认」）→ 同一闭环 |
| 交付配置 | 说明怎么布测试环境 / 怎么发版 | 写入同一份 `delivery.yaml`；测试环境绑定 deployer |
| 运行测试环境 | `/ack 重新布测试环境` | 内部加载 deployer，布 `.pouch/deployer/<env>` |
| 运行版本发布 | `/ack 发布一个版本` | 按 `intents.release`；stable/生产仍要单独批准 |
| 回归 | `/ack 回归` | 先布测试环境，再按 `regression.yaml` 用浏览器或 API 跑 |

做需求和修 bug 在 `verified` 之后，都要更新回归目录。

## 安装

```bash
pouch add ack          # 当前项目
pouch add ack -g       # 全局
```

## 使用前准备

- 项目是 Git 仓库。
- 自动拉起 Developer / Test worker 时需要 Orca，以及项目里配置好的 Codex、Cursor、Grok、OMP 或 Pi。
- 使用 Pi 时需安装 `pi`；默认模型用 `agents.yaml` 中 `cli: pi`、`model: null` 表示。
- 布测试环境需要同时安装 [deployer](../deployer/README.md)，并准备好 SSH 和目标机器的 Docker Compose。
- 飞书收 bug 是可选的，要在 `project.md` 里配置 `bugIntake`。
- 不要 `pouch init builder` 或 `pouch init deployer`。测试环境和发版直接对 `/ack` 说；缺 deployer 时 ACK 会转去它的初始化。

## 初始化项目

```bash
pouch init ack
pouch init ack --project ~/code/my-app
```

也可以直接说 `/ack 初始化`。初始化后项目只保存自己的状态：

```text
.pouch/ack/
├── project.md
├── tasks.yaml
├── knowledge.yaml
├── delivery.yaml       # 默认 enabled: false
├── regression.yaml     # 默认 cases: []
└── agents.yaml         # 可选：临时覆盖 Developer/Test 的 CLI、模型和权限
```

不会把 ACK Skill 复制进项目。规范、模板和脚本始终从已安装的 Skill 目录读取。

旧项目如果只有 `project.md` 和 `tasks.yaml`，不要重跑初始化。说 `/ack 检查配置`，授权后再补空的 `knowledge.yaml` 等缺件。

## 使用示例

```text
/ack 初始化
/ack 检查配置
/ack 处理这个需求：给后台加导出 CSV
/ack 修这个 bug：保存后列表不刷新。复现：… 期望：…
/ack 处理飞书里待整理的 bug
/ack 测试环境用项目里的 .pouch/deployer/test；发版方式以后再告诉你
/ack 重新布一下测试环境，我要测试
/ack 发布一个版本
/ack 回归
/ack 跑 full 回归
/ack 回归 REG-login-001
/ack 修这些回归失败
```

首次配发版也可以一次说清：

```text
/ack 更新项目交付配置：用 make build-deb 构建 DEB，发布到 preview APT 仓库，
部署到 test-server 并跑健康检查；完成后创建 PR，停在 review_ready 给我审核。
```

之后做需求时只要在确认计划里选 profile：

```text
/ack 处理这个需求：…。任务验证通过后执行 review profile。
```

临时调整角色启动方式时直接说明意图，例如：

```text
/ack 让这个项目的 dev agent 用 pi 默认模型，test agent 用 cursor-agent auto 模型
```

ACK 会在 `.pouch/ack/agents.yaml` 保存结构化覆盖配置。它存在时优先于
`tasks.yaml.project.orchestration`；删除后自动回退。配置 hash 会绑定启动计划和 receipt，
修改后必须重新审阅并生成 plan。

## Agent 会做什么

1. 初始化或检查 `.pouch/ack/`，缺项按统一格式列出；不从 README/CI 猜测并启用交付或知识。
2. 做需求：先写产品文档、任务拆分和可观测验收；修 bug 只写短说明、复现和验收。你确认后再派 Developer 和独立 Test。
3. 需要测试环境时加载 deployer，不自己编 compose，也不把本地 `npm run dev` 当成测试环境。
4. 任务 `verified` 后提议把本轮黑盒路径写入回归目录，你确认后才写。
5. 发版读同一份 `delivery.yaml`。默认最多停在 `validation_ready` 或 `review_ready`；稳定发布或生产部署必须再经过对应批准。
6. 回归失败只报告，不会自动开修。
7. 未获授权不提交、不推送、不创建终端、不部署，也不改项目的 `AGENTS.md` / `CLAUDE.md`。

飞书收件时，你维护标题、详细描述和附件。Coordinator 整理问题说明、期望和验收并写回飞书。你针对当前 revision 审核通过，并亲自把状态改成「已确认」之前，不创建任务、不派 worker。

## 如何判断完成

- 初始化：五个状态文件齐，报告为完成，或列出待配置项和下一步。
- 需求 / bug：任务变为 `verified`，或三轮后记为 `leftover`；回归目录有本轮用例，或明确「无回归」。
- 测试环境：目标环境容器 Up，健康检查通过。
- 发版：停在约定档位；stable / 生产有单独批准记录。
- 回归：列出通过和失败的用例；失败不会被自动拿去修。

## 版本

当前 Skill 版本见 `VERSION`。新项目在 `tasks.yaml` 里记 `ackVersion`。

从 0.19.0 起，测试环境写成 `{via: deployer, env: <env>}`，回归目录是 `.pouch/ack/regression.yaml`。旧的测试环境 profile ID 字符串不再执行，需要迁过去。旧项目可以不迁回归目录，继续用原来的闭环。旧的 `kitVersion` 仍可读，建议改成 `ackVersion`。