142 lines
6.6 KiB
Markdown
142 lines
6.6 KiB
Markdown
# 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 # 项目配置与 taskStore 指针
|
||
├── task-records/ # 追加式任务/执行记录
|
||
├── knowledge.yaml
|
||
├── delivery.yaml # 默认 enabled: false
|
||
├── regression.yaml # 默认 cases: []
|
||
└── agents.yaml # 可选：临时覆盖 Developer/Test 的 CLI、模型和权限
|
||
```
|
||
|
||
不会把 ACK Skill 复制进项目。规范、模板和脚本始终从已安装的 Skill 目录读取。
|
||
|
||
旧项目如果只有 `project.md` 和 `tasks.yaml`，不要重跑初始化。说 `/ack 检查配置`，授权后再补空的 `knowledge.yaml` 等缺件；需要消除单文件冲突时，先运行 `scripts/migrate_tasks.py` 的 dry-run。
|
||
|
||
任务状态追加示例：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/record_task.py .pouch/ack/tasks.yaml \
|
||
--task-id T-001 --task-json /tmp/T-001.json --parent EV-T-001-initial
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
```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`。
|