feat(ack): add project delivery workflow
This commit is contained in:
@@ -0,0 +1,123 @@
|
||||
# ACK 交付阶段
|
||||
|
||||
本文件定义可选的 `verified -> review_ready/released` 交付阶段。开发、独立复测和
|
||||
Coordinator 终检仍由 ACK 原有闭环负责；只有选中的任务全部 `verified` 后才能进入
|
||||
交付。项目配置位于 `docs/ack/delivery.yaml`，运行证据写入
|
||||
`docs/ack/tasks.yaml.deliveryRuns`。
|
||||
|
||||
## 1. 配置与授权不是一回事
|
||||
|
||||
`delivery.yaml` 描述项目能怎样构建、上传和部署，不能单独授予远端写权限。ACK 在
|
||||
kickoff 的既有用户确认点同时展示本次 profile、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 必须停在 `review_ready`，不能
|
||||
发布 stable 或部署 production。
|
||||
|
||||
配置不允许 `shell`、自由 `command`、`env`、外部 executable、token、密码、私钥路径
|
||||
或凭据 URL。entrypoint 的 `requiredSecrets` 只能列大写 secret 名称，值必须由外部
|
||||
凭据系统或执行环境注入。复杂逻辑放在受版本控制的项目入口中。entrypoint 使用 argv
|
||||
语义执行，不能拼成 `sh -c` 字符串。
|
||||
|
||||
## 4. 运行前检查
|
||||
|
||||
1. 从 `tasks.yaml.project.deliveryFile` 解析文件；未引用或 `enabled=false` 时保持旧 ACK
|
||||
行为，收尾停在 `verified`。
|
||||
2. 运行：
|
||||
|
||||
```bash
|
||||
python3 <ack-skill-dir>/scripts/validate_delivery.py \
|
||||
docs/ack/delivery.yaml --tasks docs/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 可使用已安装的
|
||||
`deb-publisher`；Docker 只有在用户明确指定 `$publish-docker-image` 时才加载该
|
||||
explicit-only skill，否则必须走契约中已审查的 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`、`review_ready`、`released` 或 `skipped`。部署或 Forge 暂时失败不把
|
||||
任务改回 `failed_retest`。
|
||||
|
||||
重复运行先核对已有 branch、PR/MR、artifact 和部署目标，复用身份匹配的资源。相同
|
||||
ID 指向不同 commit、digest 或目标时停止，不覆盖或另建伪装成同一运行的资源。
|
||||
|
||||
若恢复过程中修改了任何 tracked file，原 source revision 和交付证据失效：回到 ACK
|
||||
验证闭环，Test 重新复测后才能创建新的 delivery run。只有外部瞬时失败且 Git 内容未变
|
||||
时，才可从失败步骤继续。
|
||||
|
||||
`review_ready` 至少记录：source/config revision、PR/MR URL、所有产物引用与 digest、
|
||||
部署环境和健康检查证据。最终回复分别报告代码验证、PR、产物、部署和未完成项，不能用
|
||||
“完成”掩盖其中某一阶段失败或待审批。
|
||||
|
||||
## 7. 与低层 Skill 的边界
|
||||
|
||||
ACK 只负责读取项目交付契约、编排顺序、守住审批点并汇总证据，不复制低层 skill 的
|
||||
上传、镜像或 Git 发布实现。`deb-publisher`、`publish-docker-image` 和
|
||||
`manage-release` 仍是可独立使用、独立安装的能力；缺失时 ACK 使用契约中已审查的
|
||||
项目 entrypoint，二者都不可用时把对应步骤标为 `blocked`。低层 skill 自身要求显式
|
||||
调用时，ACK 不能绕过它的触发与授权边界。
|
||||
Reference in New Issue
Block a user