Release Checklist

---
name: release-checklist
description: 生成上线检查清单与变更影响面报告。对比两个 Git 版本之间的改动，按可配置规则识别高风险变更（数据库迁移、配置变更、依赖升级、接口签名改动、文件删除、超大改动面），逐条生成带验证方式和回滚方案的检查项，并标出需要通知的上下游。当用户要发版、上线、发布、部署、提测、合版本、准备灰度，或问「这次上线要注意什么」「改了哪些东西」「有没有风险」「回滚怎么弄」「要通知谁」「出个上线清单」「发布评审材料」时使用。输出为可勾选清单，与 iteration-report 共享输出契约，生成的检查项可直接作为 incident-brief 排查时的核对依据。需要两个 Git 引用（标签、分支或 commit）；未指定时必须先问，不要猜。
author: Captain
version: 0.1.0
display_name: "上线检查清单"
display_name_en: "Release Checklist"
description_zh: "对比两个版本的实际改动，按可配置规则识别高风险变更，生成带验证方式与回滚方案的可勾选上线清单。"
description_en: "Diff two Git refs, flag high-risk changes via configurable rules, and produce a checkable release checklist with verification steps and rollback plans."
examples_zh:
  - "对比 v1.4.2 和 v1.5.0，生成上线检查清单"
  - "这次发布改了哪些高风险的东西，怎么验证、怎么回滚"
  - "上线前帮我过一遍检查项"
examples_en:
  - "Compare v1.4.2 and v1.5.0 and produce a release checklist"
  - "What high-risk changes are in this release, and how do I verify and roll back"
  - "Walk me through pre-release checks"
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["git", "python3"] },
        "os": ["darwin", "linux", "win32"],
        "emoji": "🚀"
      }
  }
---

# 上线检查清单生成器

上线前的检查清单，大多数团队要么每次重写，要么干脆不写。不写的代价会在出事时一次性付清。

这个技能从**实际改了什么**倒推**该检查什么**，而不是套一份万年不变的模板。

## 前置

必须明确两个 Git 引用：

```
基线（当前线上版本）→ 目标（准备发布的版本）
例：v1.4.2 → v1.5.0，或 origin/main → release/1.5
```

不确定线上是哪个版本，就去问，**不要拿 main 当线上版本**——这是清单失效最常见的原因。

## 执行流程

### 第 1 步：采集差异

```bash
python3 {baseDir}/scripts/collect_diff.py \
  --repo ~/your/repo --base v1.4.2 --head v1.5.0 --out out/diff.json
```

产出：改动文件全量清单、提交列表、参与作者、关联 PR/工单号、新增与删除的文件。

走本地 `git diff`，**不需要任何 token**。

### 第 2 步：规则匹配生成清单

```bash
python3 {baseDir}/scripts/render_checklist.py \
  --diff out/diff.json --rules {baseDir}/references/rules.example.yaml \
  --out out/checklist.md
```

规则把**文件路径模式**映射到**检查项**。内置规则覆盖：

| 触发 | 生成的检查项关注点 |
|---|---|
| 数据库迁移文件 | 回滚脚本、数据备份、锁表风险、大表 DDL 时长 |
| 配置文件 | 灰度方式、回滚路径、配置生效延迟 |
| 依赖清单 | 新增依赖的协议与体积、传递依赖变化 |
| 接口/协议定义 | 向后兼容、上下游通知、灰度期双版本共存 |
| 文件删除 | 确认无引用、确认无外部调用 |
| 定时任务 | 执行时间冲突、幂等性 |
| 权限/鉴权相关 | 最小权限、越权测试 |
| 改动面 > 阈值 | 是否拆分批次发布 |

**规则是项目相关的。** 把 `rules.example.yaml` 复制成项目自己的 `rules.yaml` 并按实际目录结构改路径模式——用默认规则跑出来的清单只能算及格。

### 第 3 步：补判断性内容（你来做）

脚本只能从**文件路径**推断风险。下面这些必须由你读 diff 后填写，脚本标了 `AGENT_FILL`：

1. **影响面**：这次改动影响哪些功能、哪些用户、哪些上下游服务
2. **规则外风险**：路径模式识别不出的逻辑风险，比如并发、幂等、状态机迁移
3. **回滚方案**：能否直接回滚？有数据迁移时回滚会不会丢数据？
4. **通知对象**：具体到人或组，不要写"相关方"

### 第 4 步：交付

清单是给人用的，不是给机器用的。每条必须**可勾选、可验证**：

- ❌ 「检查数据库变更」—— 没法执行
- ✅ 「在预发执行 `migrate up` 并确认 orders 表行数不变，回滚脚本 `migrate down` 已在预发验证通过」

## 输出契约

```markdown
# 上线检查清单　<repo>　<base> → <head>

## 变更概要
提交数 / 作者 / 改动文件数 / 增删行数 / 关联工单

## 影响面
<AGENT_FILL：功能、用户、上下游>

## 高风险项
### [风险类别]　命中文件：<file>
- 为什么有风险：
- **验证方式**：（可执行的具体动作）
- **回滚方案**：

## 常规检查项
- [ ] ...

## 需要通知
- <具体到人或组>

## 未覆盖
- 规则只按文件路径匹配，无法识别纯逻辑风险
- <其他缺口>
```

**硬约束**：
- "未覆盖"一节必须保留，写明规则的能力边界。**让人误以为清单是完备的，比没有清单更危险**
- 每个高风险项必须有回滚方案，写不出来的要显式写"无法回滚，需前滚修复"

## 与其他技能的衔接

- **上游**：`iteration-report` 的迭代范围可直接作为本技能的 base→head 区间
- **下游**：生成的高风险项，在 `incident-brief` 排查时作为「近期变更」的核对清单。上线时识别出的风险点，往往就是出事时的第一嫌疑人

## 额度控制

第 1、2 步脚本完成，不进模型。第 3 步只把 `checklist.md` 骨架和高风险文件的 diff 摘要喂进去，**不要把完整 diff 贴进对话**——大版本的 diff 轻松几万行，一次就能烧掉大半额度。