feat(ack): bind test env to deployer and add regression mode

ACK 0.19.0 hands test-environment deploys to the deployer skill,
documents bug-fix as a first-class scenario, and adds
docs/ack/regression.yaml harvest plus a /ack regression run.
This commit is contained in:
2026-08-25 14:41:05 +08:00
parent ee31278947
commit ad6695245b
39 changed files with 1919 additions and 206 deletions
+87 -25
View File
@@ -9,10 +9,26 @@ ACK 是一个显式调用的 Agent Skill,用三种独立角色运行工程协
关键约束是验证者不等于实现者。每个任务最多修复三轮,仍未通过时记录为
`leftover`,然后继续处理其它任务。
项目还可以在同一份 `docs/ack/delivery.yaml` 里声明测试环境部署和版本发布。
用户告诉 ACK 这两件事怎么做之后,再说「重新布测试环境」或「发布一个版本」,
ACK 按对应 intent 执行。任务全部验证后仍可按 profile 做常规交付。配置默认关闭,
稳定发布与生产部署始终保留人工批准点。
测试环境部署由 ACK 触发、**内部调用 deployer** 执行。发版仍写在同一份
`docs/ack/delivery.yaml`。功能或 bug 验证通过后,把黑盒用例收进
`docs/ack/regression.yaml`;之后可以单独跑回归。
ACK 只在用户显式调用 `/ack``$ack` 时运行。
## 使用场景
| 场景 | 怎么说 | 结果 |
| --- | --- | --- |
| 初始化 | `/ack 初始化` | 生成并补全 `docs/ack/` |
| 检查 | `/ack 检查配置` | 只读校验,默认不改文件 |
| 做需求 | `/ack 处理这个需求:…` | 产品文档 + 拆任务 → 确认 → 三角色闭环 |
| 修 bug | `/ack 修这个 bug:…` 或处理飞书收件 | 短描述 + 验收 → 确认(飞书须你点「已确认」)→ 同一闭环 |
| 交付配置 | 说明怎么布测试环境 / 怎么发版 | 写入同一份 `delivery.yaml`;测试环境绑定 deployer |
| 运行测试环境 | `/ack 重新布测试环境` | 内部加载 deployer,布 `.skiff/deployer/<env>` |
| 运行版本发布 | `/ack 发布一个版本` | 按 `intents.release`stable/生产仍要单独批准 |
| 回归 | `/ack 回归` | 先布测试环境,再按 `regression.yaml` 用浏览器或 API 跑 |
做需求和修 bug 在 `verified` 之后,都要更新回归目录。
## 安装
@@ -28,8 +44,6 @@ skiff add ack -g
skiff add ack
```
ACK 只在用户显式调用 `/ack``$ack` 时运行。
## 初始化项目
```bash
@@ -44,7 +58,8 @@ docs/ack/
├── project.md
├── tasks.yaml
├── knowledge.yaml
── delivery.yaml # 默认 enabled: false
── delivery.yaml # 默认 enabled: false
└── regression.yaml # 默认 cases: []
```
不会在项目中复制或链接 ACK Skill。通用规范、模板和脚本始终从已安装的 Skill
@@ -62,17 +77,19 @@ skills/ack/
├── README.md
├── VERSION
├── references/ # 三角色规范、闭环流程和初始化说明
├── templates/ # project.md、tasks.yaml、knowledge.yaml、delivery.yaml 模板和 schema
├── templates/ # project.md、tasks.yaml、knowledge.yaml、delivery.yaml、regression.yaml 模板和 schema
├── examples/ # 完整示例
└── scripts/ # 状态校验、任务/知识选择、安全验证执行与结构化 worker launcher
└── scripts/ # 状态校验、任务/知识/回归选择、安全验证执行与结构化 worker launcher
```
`SKILL.md` 是 Agent 的工作流入口。`references/` 是按需读取的稳定规范;
`docs/ack/project.md` 只保存当前项目的命令、路径和权限差异;
`docs/ack/tasks.yaml` 保存当前任务状态;`docs/ack/knowledge.yaml` 保存跨任务复用、
已经独立验证的项目知识护栏。
`docs/ack/delivery.yaml` 是测试环境部署和版本发布的唯一契约,也声明常规构建、
发布和部署能力;每次执行结果另记在 `tasks.yaml.deliveryRuns`
`docs/ack/delivery.yaml` 是测试环境绑定和版本发布的唯一契约;测试环境由 ACK
内部调用 deployer,运行证据记在 `tasks.yaml.deliveryRuns`
`docs/ack/regression.yaml` 是黑盒回归用例目录,运行证据记在
`tasks.yaml.regressionRuns`
## 检查项目状态
@@ -84,6 +101,8 @@ python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml \
--tasks docs/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_delivery.py docs/ack/delivery.yaml \
--tasks docs/ack/tasks.yaml --project-root <project-root>
python3 <ack-skill-dir>/scripts/validate_regression.py docs/ack/regression.yaml \
--tasks docs/ack/tasks.yaml
```
Coordinator 可以按当前任务上下文做确定性推荐:
@@ -95,6 +114,10 @@ python3 <ack-skill-dir>/scripts/select_tasks.py docs/ack/tasks.yaml \
python3 <ack-skill-dir>/scripts/select_knowledge.py docs/ack/knowledge.yaml \
--component web --path web/app.py --tag long-running-service --limit 10
python3 <ack-skill-dir>/scripts/select_regression.py docs/ack/regression.yaml
python3 <ack-skill-dir>/scripts/select_regression.py docs/ack/regression.yaml \
--suite full --case-id REG-login-001
```
任务选择器会解析并执行完整任务板的内置语义校验,但只输出 `project``summary`
@@ -134,30 +157,31 @@ python3 <ack-skill-dir>/scripts/run_verification.py \
状态,获得用户授权后补一个空的 `knowledge.yaml`;如果任务板尚未声明知识库,
同时只补 `project.knowledgeFile: docs/ack/knowledge.yaml`,再运行跨文件校验。
只有 Coordinator 写 `tasks.yaml``knowledge.yaml`。知识正文不能作为自由 shell
执行;关键约束应继续下沉到测试、lint、CI 或正式规范。ACK 不自动修改项目的
`AGENTS.md``CLAUDE.md` 或其它 Agent 指令文件。
只有 Coordinator 写 `tasks.yaml``knowledge.yaml``regression.yaml`。知识正文
不能作为自由 shell 执行;关键约束应继续下沉到测试、lint、CI 或正式规范。ACK
不自动修改项目的 `AGENTS.md``CLAUDE.md` 或其它 Agent 指令文件。
## 配置与运行交付
用户可以直接向 `/ack` 说明两件独立操作,并写进同一份契约:
测试环境走 deployer 的项目内布局(通常是 `.skiff/deployer/test`),发版仍用
delivery profile。可以直接说:
```text
/ack 测试时先 go build -o garden ./cmd/garden,再启动这个二进制;
发版方式以后再告诉你。
/ack 测试环境用项目里的 .skiff/deployer/test;发版方式以后再告诉你。
```
ACK 把它维护成 `docs/ack/delivery.yaml` `intents.testEnvironment` /
`intents.release`、entrypoint、artifact、environment 和 profile。首次配置保持
关闭,确认后才启用。之后用户可以说:
ACK 把测试环境写成 `intents.testEnvironment.via: deployer`,把发版写成
`intents.release` 指向的 profile。首次配置保持关闭,确认后才启用。之后可以说:
```text
/ack 重新布一下测试环境,我要测试
/ack 发布一个版本
```
对应 intent 未配置时先问清楚并写回同一文件,不猜测。intent 运行不要求当前有
`verified` 任务;`deliveryRuns.intent` 记录是测试环境还是发版。
对应 intent 未配置时先问清楚并写回同一文件,不猜测。运行测试环境时 ACK 加载
deployer skill,不复制 compose 命令。本地进程启动写在 `project.md`,不算这个
模式。intent 运行不要求当前有 `verified` 任务;`deliveryRuns.intent` 记录是
测试环境还是发版。
交付配置只允许声明式工具 target 或仓库内可执行脚本,不接受自由 shell,也不保存
凭据值。任务进入 `verified` 后的常规交付仍按确认过的 profile 执行。默认
@@ -235,7 +259,42 @@ Coordinator 最后标记整轮任务完成后,会关闭所有只关联 `verifi
```
Coordinator 会先读取项目状态和 `references/kickoff.md`,生成产品文档、任务拆分与
可观测验收信号;用户确认后才派发实现和复测。
可观测验收信号;用户确认后才派发实现和复测。任务 `verified` 后会把本轮黑盒路径
收进 `docs/ack/regression.yaml`,确认后才写入。
## 修复 bug
可以直接说:
```text
/ack 修这个 bug<现象、复现、期望>
```
Coordinator 写短问题说明、复现步骤和可观测验收,不写大 PRD;你确认后再派发。
Developer 先补会失败的用例再修,后续闭环与做需求相同。
配了飞书 `bugIntake` 时,飞书是审核前的唯一协作区。你只需维护标题、详细描述和
附件;Coordinator 整理问题说明、期望效果和验收标准并写回飞书。你针对当前
revision 审核通过,并亲自把状态改成「已确认」之前,不创建任务、不派 worker。
```text
/ack 处理飞书里待整理的 bug
```
## 运行回归
平时做需求和修 bug 结束后,ACK 按本轮内容更新 `docs/ack/regression.yaml`
之后可以单独跑:
```text
/ack 回归
/ack 跑 full 回归
/ack 回归 REG-login-001
```
ACK 先按 deployer 布测试环境,再派独立 Test 按用例用浏览器或 API 执行。失败只
报告,不会自动开修;要修再说 `/ack 修这些回归失败`。默认跑 smoke。细则见
`references/regression.md`
首次配置交付可以说:
@@ -264,5 +323,8 @@ ACK 会自动读取 `delivery.yaml`,无需再逐步提醒它构建、上传、
版本发布写成用户可单独触发的操作;从 `0.17.0` 起,结构化 worker 路由支持
`cli: grok`(与 Codex、Cursor 并列);从 `0.18.0` 起支持 OMP 的
`cli: omp` profile(精确 provider/model、thinking 与 approval-mode);从 `0.17.1` 起 Grok worker argv 固定带
`--always-approve`sandbox 仍必开。旧项目可以不迁移而继续使用原闭环。旧项目的
`kitVersion` 可以继续读取,但建议迁移为 `ackVersion`
`--always-approve`sandbox 仍必开;从 `0.19.0``intents.testEnvironment` 改为
deployer 绑定,ACK 内部调用 deployer skill 布测试环境,并增加
`docs/ack/regression.yaml` 与「运行回归」模式。旧的测试环境 profile ID 字符串不再
执行,需要迁到 `{via: deployer, env: <env>}`。旧项目可以不迁移回归目录而继续使用
原闭环。旧项目的 `kitVersion` 可以继续读取,但建议迁移为 `ackVersion`