59 lines
3.9 KiB
Markdown
59 lines
3.9 KiB
Markdown
# Delivery Loop 状态机
|
||
|
||
## 状态
|
||
|
||
```text
|
||
change_ready -> verified -> pr_opened -> merged -> regression_passed -> artifact_built -> published -> deployed
|
||
```
|
||
|
||
入口可以从已有状态开始，但不能跳过本次变更所需的验证。内部里程碑可以更细，但项目
|
||
ACK 配置必须使用以下 canonical `stopAt`：
|
||
|
||
- `verified`：只完成代码和验证。
|
||
- `validation_ready`：不可变产物已部署到开发/测试环境并通过健康检查，可交给用户验证。
|
||
- `review_ready`：PR/MR、预览产物和非生产验证证据已齐备，等待审核。
|
||
- `released`：经过本次 approval 后完成稳定发布或生产部署。
|
||
|
||
入口 skill 的自然语言停止点映射如下：
|
||
|
||
| 用户目标 | ACK stopAt | 必要内部里程碑 |
|
||
| --- | --- | --- |
|
||
| 只验证 | `verified` | `verified` |
|
||
| 发 PR | `review_ready` | `pr_opened`，必要时预览构建/测试 |
|
||
| 部署测试环境 | `validation_ready` | `artifact_built`、`deployed`、健康检查 |
|
||
| 合并后回归但不发布 | `review_ready` 或任务级中间状态 | `merged`、`regression_passed` |
|
||
| 完整正式部署 | `released` | `merged`、`regression_passed`、`artifact_built`、`published`、`deployed` |
|
||
|
||
## 每个阶段的要求
|
||
|
||
- `change_ready`：记录基线 commit、工作树、目标分支、任务范围和风险。
|
||
- `verified`：根因或需求验收明确；自动测试和必要的黑盒/真机验证通过。
|
||
- `pr_opened`：提交说明、测试证据、风险和回滚信息已写入 PR；不能把草稿 PR 当 `review_ready`。
|
||
- `merged`：目标分支的合并 commit 已确认，不能只确认源分支 commit。
|
||
- `regression_passed`：以合并 commit 执行项目规定的完整回归；失败则回到修复或停止。
|
||
回归 worker 必须先发现项目及其子项目的 tester catalog（使用
|
||
`catalog.py roots --root <project-root>`），逐个测试根执行并记录独立快照；父仓库
|
||
没有 catalog 不能遮蔽有 catalog 的 `app` 子项目。任一发现的测试根未执行或无证据，
|
||
不得把阶段标为 `regression_passed`。还必须执行项目 profile 或
|
||
`.pouch/ack/project.md` 声明的项目原生测试套件，并为每个套件记录命令和结果；任一
|
||
测试面缺少结果时都不能通过回归。
|
||
- `artifact_built`：对**合并后的精确 commit SHA** 调用 builder `obtain.sh`。`BUILD_VENUE=ci` 时监听该 SHA 的流水线并 inspect 产物，不在本机重新编译。无流水线、job 失败或 digest 对不上则本阶段失败，不得进入 `published`。项目若声明默认分支不构建，合进 `main` 会 `no_pipeline`：预览推 `dev/*`，正式打 tag。
|
||
- `published`：镜像/APK 等外部分发位置可复核，记录 digest 或文件校验和。`venue=ci` 且 CI 已经 push 到 registry 时，obtain 成功即同时满足本阶段，不要再本机 `publish_docker.sh`。
|
||
- `deployed`：目标服务运行在预期版本，健康检查和关键路径验证通过；生产部署还必须进入 `released`。
|
||
|
||
## 配置和授权
|
||
|
||
读取项目自己的 delivery 配置，不把命令、主机、秘密复制到通用 skill。优先使用 ACK
|
||
的 `delivery.yaml`、builder/deployer/tester 契约和项目版本策略；缺失时停止在最近的安全状态。
|
||
|
||
生产部署必须同时满足：项目 profile 允许、目标明确、构建来源已固定、回归证据完整、当前
|
||
请求覆盖生产部署。没有这些条件时只能报告，而不能用“用户之前说过发布”替代当前授权。
|
||
|
||
## 证据账本
|
||
|
||
至少记录：基线和最终 commit、工作树状态、测试命令及结果、黑盒/真机证据、PR/MR URL、
|
||
合并 commit、tag、产物路径与摘要、部署节点/服务、健康检查、失败项和回滚指针。
|
||
|
||
已绑定 ship 记录时，上述证据以指针写入该 ship 的 `current.yaml`，不要另建一份账本。
|
||
阶段与字段对应见 ship `references/record.md`。
|