laily
10d8800f07
Give ack, builder, and deployer an explicit init/check mode that reports missing project config instead of failing mid-work. Point builder at makefile.builder so its contract targets do not collide with an existing Makefile.
162 lines
10 KiB
Markdown
162 lines
10 KiB
Markdown
# ACK 交付阶段
|
||
|
||
本文件定义可选的 `verified -> validation_ready/review_ready/released` 交付阶段。开发、独立复测和
|
||
Coordinator 终检仍由 ACK 原有闭环负责；只有选中的任务全部 `verified` 后才能进入
|
||
交付。项目配置位于 `.pouch/ack/delivery.yaml`，运行证据写入
|
||
`.pouch/ack/tasks.yaml.deliveryRuns`。
|
||
|
||
## 1. 配置与授权不是一回事
|
||
|
||
`delivery.yaml` 描述项目能怎样构建、上传和部署，不能单独授予远端写权限。启用交付
|
||
时，ACK 在 kickoff 的既有用户确认点默认展示 `defaultProfile`、remote、产物目标、环境
|
||
和停止点，不得静默省略；用户
|
||
确认该任务计划后，才允许执行计划中准确列出的 `review_ready` 步骤。目标、remote、
|
||
channel、environment 或 source revision 漂移时重新确认。
|
||
|
||
`approval` 步骤始终是运行时硬门。`stable` 发布和 `production` 部署不能由 kickoff
|
||
的一般确认代替，必须在该步骤取得本次明确授权。配置、历史 approval 或项目文档不能
|
||
替用户授权合并 PR、创建正式 tag、覆盖版本、删除分支或生产发布。
|
||
|
||
## 2. 配置快照与变更生效
|
||
|
||
普通任务在 kickoff 时从可信 base commit 读取交付契约并记录 `configRevision`。本次
|
||
分支对 `delivery.yaml`、引用的部署入口、CI 或 Agent 指令文件的修改不能扩大当前运行
|
||
权限；这些改动经审核合并后从下一次任务生效。
|
||
|
||
用户明确要求维护交付配置时：
|
||
|
||
1. 读取现有配置、项目构建入口、CI、打包和部署事实。
|
||
2. 用自然语言总结将新增、删除或改变的 artifact、destination、environment、profile
|
||
和权限边界。
|
||
3. 只做最小配置修改，不把项目脚本复制进 ACK。
|
||
4. 运行 `validate_delivery.py`；可安全执行的本地入口使用 dry-run 或无凭据环境检查。
|
||
5. 把配置或入口变更作为待审核变更交付。本轮不使用新配置执行 publish/deploy。
|
||
|
||
普通功能任务中若发现配置漂移，记录 `contract_drift` 并停止受影响的交付步骤，不为了
|
||
通过流程而静默修改配置或跳过步骤。
|
||
|
||
## 3. 交付契约结构
|
||
|
||
- `entrypoints`：项目已有的 Make、Just、Task、Dagger 或仓库内可执行脚本入口。
|
||
- `artifacts`：`deb`、`oci-image` 或 `file`，引用一个 build entrypoint。
|
||
- `destinations`：APT、OCI registry 或 CI artifact；`channel` 区分 preview、staging、
|
||
stable。
|
||
- `environments`：SSH host、Docker Compose、Kubernetes 或 custom；必须声明环境等级、
|
||
deploy 和 health check，production 还必须声明 rollback。
|
||
- `profiles`：按顺序执行的步骤和停止点。默认 profile 必须停在 `validation_ready` 或
|
||
`review_ready`，不能发布 stable 或部署 production。`validation_ready` profile 必须
|
||
至少部署一个 development/staging 环境，并对每个部署目标执行健康检查。
|
||
|
||
配置不允许 `shell`、自由 `command`、`env`、外部 executable、token、密码、私钥路径
|
||
或凭据 URL。entrypoint 的 `requiredSecrets` 只能列大写 secret 名称，值必须由外部
|
||
凭据系统或执行环境注入。复杂逻辑放在受版本控制的项目入口中。entrypoint 使用 argv
|
||
语义执行，不能拼成 `sh -c` 字符串。
|
||
|
||
## 3.1 测试环境与发版写在同一份契约
|
||
|
||
`.pouch/ack/delivery.yaml` 是测试环境绑定和版本发布的唯一文档。不要另写操作手册，
|
||
也不要把其中一项写进 `project.md`。用户用自然语言说明「怎么布测试环境」或
|
||
「怎么发版」时，Coordinator 把两者都维护进这份文件的 `intents`。
|
||
|
||
```yaml
|
||
intents:
|
||
testEnvironment:
|
||
via: deployer
|
||
env: test # 项目 .pouch/deployer/test；尚未说明时为 null
|
||
release: null # profile ID，或 null
|
||
```
|
||
|
||
- `testEnvironment` 绑定 deployer skill 的项目环境目录。用户说「重新布测试环境」
|
||
「我要测试」时，ACK 加载 deployer 的 `SKILL.md`，对 `.pouch/deployer/<env>`
|
||
按服务执行 sync + up 和健康检查。环境目录不存在或 deployer `check.py` 未通过
|
||
时，加载 deployer skill 的「初始化」，不要在 ACK 里复制 compose 命令。派发
|
||
Test 复测或跑回归前，若该 intent 已配置且 `enabled: true`，Coordinator 也先
|
||
执行它。不要求当前有 `verified` 任务。Test 不对这个 intent 发明编译或启动
|
||
命令。旧的 profile ID 字符串不再执行，必须迁到 `{via: deployer, env: <env>}`。
|
||
本地进程启动写在 `project.md`，不算这个 intent。
|
||
- `release` 指向 `stopAt: released` 的 profile。用户说「发布一个版本」时执行它。
|
||
口头「发版」不能代替 stable/production 的 `approval` 步骤。
|
||
- 对应 intent 为 `null` 或交付未启用：停止，请用户说明怎么做，按「交付配置维护」
|
||
写入同一文件后再执行。不猜测 Makefile、镜像仓库或发布通道。
|
||
- 用户触发的 intent 运行写入 `tasks.yaml.deliveryRuns`，`intent` 填
|
||
`testEnvironment` 或 `release`，`taskIds` 可为空。测试环境 run 的 `profile` 记
|
||
`deployer-<env>`。绑定任务的常规交付 run 不填 `intent`，仍只能引用
|
||
`verified` 任务。
|
||
|
||
## 4. 运行前检查
|
||
|
||
1. 从 `tasks.yaml.project.deliveryFile` 解析文件；未引用或 `enabled=false` 时保持旧 ACK
|
||
行为，收尾停在 `verified`。
|
||
2. 运行：
|
||
|
||
```bash
|
||
python3 <ack-skill-dir>/scripts/validate_delivery.py \
|
||
.pouch/ack/delivery.yaml --tasks .pouch/ack/tasks.yaml \
|
||
--project-root <project-root>
|
||
```
|
||
|
||
3. 确认选中 profile 是 kickoff 已确认的 profile，所有 task 已是 `verified`，工作区与
|
||
服务对应正确 source revision。
|
||
4. 检查 referenced entrypoint、delivery config、CI 和凭据边界是否在本次变更中被
|
||
修改；被修改时禁止用它们执行带远端写权限或 secret 的步骤。
|
||
5. 检查本次步骤引用的 `requiredSecrets` 是否由外部环境提供，只报告名称和是否存在，
|
||
不读取、打印或持久化值。缺失时在第一次相关写操作前标记 blocked。
|
||
6. 将已确认工作树固化为本地 source revision，再创建 `deliveryRuns` 的 `planned`
|
||
记录，绑定 task IDs、profile、source revision 和 config revision；推送仍等到对应
|
||
`pull-request` 步骤。
|
||
|
||
## 5. 步骤语义
|
||
|
||
按 profile 中的顺序执行，不自行插入或省略步骤：
|
||
|
||
- `verify`：运行指定 entrypoint，失败即停止。
|
||
- `pull-request`：在精确 source revision 上提交、推送任务分支并创建或复用 Draft
|
||
PR/MR。普通任务使用项目已确认的 Forge 流程；只有本次是版本发布生命周期且用户
|
||
明确要求时才调用独立的 `manage-release`。没有对应能力或认证时标记 blocked，不用
|
||
带 token 的临时 curl 兜底。remote 与 base branch 必须来自该步骤，不能临时猜测。
|
||
- `build`：调用 artifact 的 build entrypoint。DEB 必须记录包名、版本、架构和
|
||
SHA-256；OCI image 必须记录完整引用、platform 和 digest。产物必须绑定当前 source
|
||
revision，不能在目标机器重新拉源码构建。
|
||
- `publish`：验证 artifact/destination 类型兼容，上传精确产物。DEB 与 Docker 均可使用
|
||
已安装的 `builder`；Docker 轨道保持显式触发——只有用户明确点名（builder / 发布镜像）
|
||
时才加载，否则必须走契约中已审查的 upload entrypoint。项目入口只接受
|
||
刚校验的精确 artifact。preview/staging 使用不可覆盖的 commit/PR 标识，不隐式使用
|
||
`latest`。既没有可用 skill 也没有 upload 入口时标记 blocked。
|
||
- `deploy`：把同一不可变 artifact 交给 environment 的 deploy entrypoint；获取目标
|
||
mutex 后执行，不能并发部署同一目标。
|
||
- `health-check`：在对应 deploy 成功后运行环境 health check，记录可观测证据。失败时
|
||
按项目入口执行 rollback；rollback 未证明成功时不得声称恢复。
|
||
- `approval`：停止并展示准确 artifact、destination/environment、source revision 和
|
||
回滚计划，等待用户本次确认。
|
||
- `mark-ready`：所有前序步骤成功后将 Draft PR/MR 标为 ready，并写入最终证据。
|
||
|
||
## 6. 状态与恢复
|
||
|
||
`task.status=verified` 表示代码正确性通过；交付状态单独记录为 `planned`、`running`、
|
||
`blocked`、`failed`、`validation_ready`、`review_ready`、`released` 或 `skipped`。
|
||
`validation_ready` 表示已把不可变产物部署到开发/测试环境并通过健康检查，可以交给
|
||
用户手工验证，不要求存在 PR/MR。部署或 Forge 暂时失败不把
|
||
任务改回 `failed_retest`。
|
||
|
||
重复运行先核对已有 branch、PR/MR、artifact 和部署目标，复用身份匹配的资源。相同
|
||
ID 指向不同 commit、digest 或目标时停止，不覆盖或另建伪装成同一运行的资源。
|
||
|
||
若恢复过程中修改了任何 tracked file，原 source revision 和交付证据失效：回到 ACK
|
||
验证闭环，Test 重新复测后才能创建新的 delivery run。只有外部瞬时失败且 Git 内容未变
|
||
时，才可从失败步骤继续。
|
||
|
||
`validation_ready` 至少记录：source/config revision、所有产物引用与 digest、部署环境、
|
||
访问地址和用户下一步，以及健康检查证据。`review_ready` 至少记录：source/config revision、PR/MR URL、所有产物引用与 digest、
|
||
部署环境和健康检查证据。最终回复分别报告代码验证、PR、产物、部署和未完成项，不能用
|
||
“完成”掩盖其中某一阶段失败或待审批。
|
||
|
||
## 7. 与低层 Skill 的边界
|
||
|
||
ACK 只负责读取项目交付契约、编排顺序、守住审批点并汇总证据，不复制低层 skill 的
|
||
上传、镜像、Git 发布或远程 Compose 实现。`builder`、`manage-release` 和
|
||
`deployer` 仍是可独立使用、独立安装的能力。运行测试环境时 ACK 必须加载
|
||
deployer skill，不能把 compose/rsync/远程 docker 命令写进 ACK。发版步骤缺失
|
||
builder 或 manage-release 时，ACK 使用契约中已审查的项目 entrypoint，二者都不可用
|
||
时把对应步骤标为 `blocked`。低层 skill 自身要求显式调用时，ACK 不能绕过它的
|
||
触发与授权边界；ACK 内部调用 deployer 布测试环境是该 skill 的合法调用路径。
|