/release-workflow

name: release-workflow
description: 本技能应在 GitHub 项目发布新版本时使用，覆盖版本号管理、CHANGELOG 同步、Release Notes 撰写、tag 创建、CI 构建监控、发布验证和历史清理全流程。适用于桌面应用、CLI 工具、Web 应用、库/SDK 等任何基于 GitHub 的软件项目。当用户提到"发布"、"release"、"打 tag"、"新版本"、"更新版本号"、"写 release notes"、"发布失败了"、"CI 挂了"、"Actions 配额告急"、"短时间内多次发版"、"monorepo"、"批量打包"、"多 skill 发布"、"skill zip"、"专家套件 zip"时触发。也用于拒绝把 release 当作 CI 验证机制（"打 tag 看一下"）的反模式场景。不要用于非 GitHub 项目（如纯 GitLab / Gitea 项目）或无需 CI 的手动发布场景。
version: "1.6.3"
license: MIT License - 详见 LICENSE.txt

Release Workflow

软件项目的全流程发布工作流。适用于 GitHub 上的任何类型项目。

适用场景

GitHub 项目的完整发布周期：从版本号确定到 CI 构建验证。CI 故障排查（`references/ci-troubleshooting.md`）和特定项目类型指南（`references/` 下各文档）作为发布流程的补充参考。

**与 git-workflow 的职责边界**：本技能只负责发版流程内的 CI 构建监控（第 4 步）与发布成本约束（配额红灯）。日常 Actions 配额治理——CI 分钟耗尽停挂止血、workflow 停挂/恢复、workflow_dispatch 化、仓级总闸——由 `git-workflow` §11 负责。发版中出现 CI 故障：构建产物/签名/发布链路问题读本技能；账号级配额治理问题转 git-workflow。

项目配置

`config/projects.yaml` 集中管理各项目的发布配置（仓库、平台、自动更新、排除产物等）。发布时先读取对应项目配置，按配置决定构建矩阵和预期产物。模板见 `config/projects.example.yaml`。

带应用内更新的桌面项目，还必须读取 [真实升级与热修门禁](references/updater-hotfix.md)：验签、旧客户端能力、进程回收、数据恢复和实际安装路径分别验收。

发布前检查

| 检查项 | 说明 | |--------|------| | 工作区干净 | `git status` 无未提交变更 | | 版本号一致 | 所有版本号文件（package.json / Cargo.toml / pyproject.toml 等）与 CHANGELOG.md 最新条目一致 | | CHANGELOG 已更新 | 包含目标版本的结构化条目 | | CI 工作流存在 | `.github/workflows/` 中有 release 相关工作流且 tag 触发配置正确 | | 本地测试门禁 | `npm test`（或项目对应单测命令）整体通过。**单条失败先重跑确认是否偶发**再定性：偶发 flaky（非本次改动引入的回归）修测试或单独跟进，不要因此阻塞发布；但若全量多次复现、指向真实回归，必须先修复再发版 |

任一条件不满足，先修复再继续。

⚠️ Release ≠ 测试 — 强制约束

**打 tag / 创建 GitHub Release 是把版本号给真实用户**，不是 CI 验证机制。**把 release workflow 当作"看 CI 跑没跑通"或"我下载个 artifact 自己测一下"是反模式，必须禁止。**

为什么是绝对规则

• **Actions 配额是有限共享资源**。单次跨平台 release（macOS × N + Windows + Linux）通常消耗 300-600 配额分钟，macOS runner 是 10× 费率，贡献最大。
• **错把 release 当测试的隐性成本**：
• GitHub Release 一旦创建（即使是 draft）就被计入资产历史，污染 release feed
• tag 推送后 commit 被人看到会误以为已发布
• 自动更新用户可能在升级检查时看到不稳定的版本
• 配额快速耗尽，真正紧急的 hotfix 反而跑不动 CI
• **过去能这么干不代表现在该这么干**。GitHub 免费配额调整、macOS runner 涨价都发生过，使用模式必须随成本变化更新。

禁止的反模式

| 反模式 | 表现 | 为什么错 | |--------|------|----------| | **把 tag 当 smoke test** | "我改了一行，打个 tag 看看 CI 跑不跑得通" | 一次 release 吃掉 300+ 配额分钟，5 次测试 = 一月配额清零 | | **用 release 验证构建产物** | "我想看 .dmg 长什么样，必须跑 release" | 应该用专门的 preview / draft build workflow（见下） | | **同一天 / 24h 内发多个 patch** | v0.3.16 / 17 / 18 一天内连发，各是同一个 bug 的连续小修 | 全部攒到下次一起发，成本立省 60%+ | | **draft release 当"先跑一次试试"** | "我先 draft release 看 artifact 行不行" | draft 一样跑完整 CI，一样消耗配额，一样污染 release 历史 | | **单平台 dry-run 验构建** | "先跑 Linux dry-run 看看，不发全平台" | dry-run 一样消耗 CI 时间，开了口子就停不下来；改走 preview workflow | | **小改动发 patch** | "我改了 typo / 改了一行文档，必须 vX.Y.Z" | 纯 typo / 文档小改 / 单文件改动不构成发版理由，合并到下个有实质内容的版本 | | **"已经打 tag 了，跑都跑了"** | "v0.3.22 tag 已经推上去了，CI 反正也在跑" | "已经做了"不是继续做的理由；记录这次浪费并阻止下次重复 |

正确做法

**A. 想验证 CI 跑不跑得通 / 看构建产物长什么样？**

• 用 `pull_request` 触发的 preview workflow（可只跑 ubuntu / 单一平台，几十分钟完成）
• 或在 main 上用 `workflow_dispatch` 手动触发 dry build，**不**触发 release workflow
• 这两种都不消耗 macOS 高倍率配额，artifact 只对自己可见

**B. 真的有用户能拿到的修复要发？**

• 等攒到 3-5 个实质修复（bug fix / feature / 性能 / 兼容性改动）
• 一次性打 tag 发版，**只发一次**
• CHANGELOG 必须有结构化条目，不能空
• 常规发布距离上次 tag 至少 24 小时；真实用户的安装/更新阻断 hotfix 可按下方例外提前发布（防止把同一问题的试错拆成多个 patch）

打 tag 前强制自检（AI 不得跳过）

打 tag 之前，**必须回答下面 5 个问题**。AI 代理被请求发布新版本时，必须**主动**逐条打印最终候选自检结果；缺少该版本的明确发布授权时再请用户确认，不得跳过验证直接打 tag。

1. 这是给真实用户装的，还是只给自己看 artifact？ 2. CHANGELOG 已经有结构化的本版本条目（不是空、不是单行 typo）？ 3. 距上次 tag ≥ 24 小时？ 4. 本次累计有 ≥ 1 个实质修复 / 特性 / 改动（纯文档 / typo / 单行 README 修改不算）？ 5. 如果上述任一不满足：能合并到下次发版吗？

**第 1、2、4 问答“否”或关键证据未知：不要打 tag。第 3 问不足 24 小时，只有已复现的真实安装/更新阻断且用户明确授权的 hotfix 才可例外；说明原因、独立审查和完整候选验证结果，禁止用例外进行发行试错。**

**AI 代理实操规则**：打 tag 前显式列出五问答案，并绑定最终候选与验证。用户已明确授权该版本及 hotfix 范围时，沿用授权，不重复索取同一确认；未获授权时先完成可审阅候选再确认。授权不代替验证，禁止通过反复移动同一个 tag 排查问题。

借口反驳表

| 借口 | 现实 | |------|------| | "我就看一眼，tag 一下马上回滚" | tag 推送已经触发了完整 CI，回滚 tag 不能退款 Actions 分钟 | | "用户催着要" | 用户不知道你的 Actions 配额，告诉 ta 合并到明天的成本和时间，让 ta 选 | | "反正之前都这么干" | 之前能用不等于现在合理，这正是 91% 配额的直接成因 | | "只有 release workflow 跑完整矩阵" | 加一个 preview workflow（成本是 release 的 10-20%），不要用 release 凑合 | | "draft release 不算正式发布" | draft 一样跑完整 CI、一样消耗配额、一样污染 release 历史 | | "小改动发 patch 很常见" | 纯 typo / 文档 / 单行不构成发版理由，合并到下个有实质内容的版本 | | "我已经打 tag 了，跑都跑了" | "已经做了"不是继续做的理由；记录这次浪费，阻止下次重复 | | "单平台先 dry-run 一下" | dry-run 一样消耗 CI 时间，开了口子就停不下来；改走 preview workflow | | "这次不一样，这次真的需要发" | SemVer 的 patch 版本本来就允许累积；下次发版不是更优解吗 |

红灯（看到任一就停）

• 同一工作日内想发第二次 tag
• 距上次 tag < 24 小时
• CHANGELOG 没有本版本的结构化条目就想发
• 想用 "draft release" 当测试
• 想用 `workflow_dispatch` 触发 release workflow 当测试（应该触发独立的 preview workflow）
• 本次只有 typo / 文档 / 单行修改
• macOS 10× 配额当月累计用量已 > 70%

**出现红灯先停止发行副作用并核对原因。真实 hotfix 频率例外见上文；保留失败证据，不自动删除或移动 tag，已公开版本不得覆写。**

🔥 修复 hotfix 与 CI retry 边界（关键）

patch 版本（X.Y.Z+1）可以是 **新功能累积**，也可以是 **hotfix 单一修复**。区分清楚才能避免「把 release 当测试」反模式。

何时属于「hotfix 真实修复」（发布新的 patch 版本）

• 第一次 release 后用户**实际收到 broken build**（自动更新坏 / 安装失败 / 启动崩溃）
• 根因明确指向**代码或配置 bug**，已有可复现失败和修复验证；只有 CI 构建失败但尚无用户收到的版本，不以 hotfix 理由对外发行
• 每个新版本都**有可验证的 commit 推进**（修一行、改一个配置、新增测试）

判定信号：`gh run view --log-failed` 输出包含具体 error line（不是单纯的 `Timeout` / `Resource exhausted` 这种 transient 错误）。

何时属于「把 release 当测试」（禁止发行试错）

• 单纯想看 CI 跑没跑通、看 artifact 长什么样
• 上一次 build 失败但**没看失败原因**就直接重打
• 第三次以上重打同一个版本号（按成本曲线，超过 3 次几乎都在反复折腾 transient）

transient vs 真实 bug 的快速判定

build job 失败：
  - 输出含 E0599 / Cargo compile error / 链接错误 → 真实代码 bug，修代码再重打
  - 输出含 "Timeout" / "Resource exceeded" / "Killed" → transient，可直接重试

publish job 失败：
  - 输出 "Missing signatures" + 产物清单缺 sig → 检查 includeUpdaterJson + bundle.targets（详见 tauri-release.md 红线 8）
  - 输出 "Signature not found for the updater JSON. Skipping upload..." → tauri-action 跳过整批 updater，检查 build 产物目录
  - 输出 "Unable to download" / "rate limit" → transient

本地单测（vitest / jest）失败，发布前门禁：
  - 单条 "Timed out waiting for condition" 超时失败 → 大概率 flaky（轮询式 waitUntil + 动态 import 的异步链在测试环境下偶发跑不完），先重跑该文件确认；连跑仍偶发则修测试（轮询预算给足），不属于本次改动引入的回归，不阻塞发布
  - 多条/全量复现、或错误指向具体代码行为 → 真实回归，先修代码再发版

最佳实践：先 `gh release view <tag> --json assets,isDraft,targetC