laily
a15a046e4e
Promote ship to the user-facing delivery skill. Kind is short or long from an explicit mode, then self-judgment, then a question, defaulting to short. Old names remain deprecation stubs.
ACK
ACK 是显式调用的 Agent Skill，用三种独立角色跑工程协作闭环：
- Coordinator 拆解需求、派发任务并终检
- Developer 实现并做白盒验证
- Test 独立做黑盒复测
验证者不能等于实现者。每个任务最多修三轮，仍不过就记为 leftover，然后继续别的任务。
测试环境由 ACK 触发、内部调用 deployer。发版写在同一份 .pouch/ack/delivery.yaml。功能或 bug 验证通过后，黑盒用例收进 .pouch/ack/regression.yaml，之后可以单独跑回归。
只在你显式说 /ack 或 $ack 时运行。
什么时候使用
| 场景 | 怎么说 | 结果 |
|---|---|---|
| 初始化 | /ack 初始化 |
生成并补全 .pouch/ack/；缺项按统一格式列出 |
| 检查 | /ack 检查配置 |
只读校验，默认不改文件；测试环境缺 deployer 时转交 |
| 做需求 | /ack 处理这个需求：… |
先建 ship 记录；复杂需求走 specifier / ship long 模式，小改动走 ship |
| 修 bug | /ack 修这个 bug：… 或处理飞书收件 |
短描述 + 验收 → 你确认（飞书须你点「已确认」）→ 缺陷板闭环，交付链接 ship |
| 交付配置 | 说明怎么布测试环境 / 怎么发版 | 写入同一份 delivery.yaml；测试环境绑定 deployer |
| 运行测试环境 | /ack 重新布测试环境 |
内部加载 deployer，布 .pouch/deployer/<env> |
| 运行版本发布 | /ack 发布一个版本 |
按 intents.release；stable/生产仍要单独批准 |
| 回归 | /ack 回归 |
先布测试环境，再按 regression.yaml 用浏览器或 API 跑 |
做需求和修 bug 在 verified 之后，都要更新回归目录。
安装
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，并准备好 SSH 和目标机器的 Docker Compose。
- 飞书收 bug 是可选的，要在
project.md里配置bugIntake。 - 不要
pouch init builder或pouch init deployer。测试环境和发版直接对/ack说；缺 deployer 时 ACK 会转去它的初始化。
初始化项目
pouch init ack
pouch init ack --project ~/code/my-app
也可以直接说 /ack 初始化。初始化后项目只保存自己的状态：
.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。
任务状态追加示例：
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
使用示例
/ack 初始化
/ack 检查配置
/ack 处理这个需求：给后台加导出 CSV
/ack 修这个 bug：保存后列表不刷新。复现：… 期望：…
/ack 处理飞书里待整理的 bug
/ack 测试环境用项目里的 .pouch/deployer/test；发版方式以后再告诉你
/ack 重新布一下测试环境，我要测试
/ack 发布一个版本
/ack 回归
/ack 跑 full 回归
/ack 回归 REG-login-001
/ack 修这些回归失败
首次配发版也可以一次说清：
/ack 更新项目交付配置：用 make build-deb 构建 DEB，发布到 preview APT 仓库，
部署到 test-server 并跑健康检查；完成后创建 PR，停在 review_ready 给我审核。
之后做需求时只要在确认计划里选 profile：
/ack 处理这个需求：…。任务验证通过后执行 review profile。
临时调整角色启动方式时直接说明意图，例如：
/ack 让这个项目的 dev agent 用 pi 默认模型，test agent 用 cursor-agent auto 模型
ACK 会在 .pouch/ack/agents.yaml 保存结构化覆盖配置。它存在时优先于
tasks.yaml.project.orchestration；删除后自动回退。配置 hash 会绑定启动计划和 receipt，
修改后必须重新审阅并生成 plan。
Agent 会做什么
- 初始化或检查
.pouch/ack/，缺项按统一格式列出；不从 README/CI 猜测并启用交付或知识。 - 做需求：规格和任务写到
.pouch/ship/<id>/；修 bug 只写短说明、复现和验收，落缺陷板。你确认后再派 Developer 和独立 Test。 - 需要测试环境时加载 deployer，不自己编 compose，也不把本地
npm run dev当成测试环境。 - 任务
verified后提议把本轮黑盒路径写入回归目录，你确认后才写。 - 发版读同一份
delivery.yaml。默认最多停在validation_ready或review_ready；稳定发布或生产部署必须再经过对应批准。 - 回归失败只报告，不会自动开修。
- 未获授权不提交、不推送、不创建终端、不部署，也不改项目的
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。