Release New Version

Release Skill

给定版本号，自动完成完整发布流程：更新版本文件 → 提交 → 生成 release notes → 打 annotated git tag（附带完整变更日志）→ push。

工作流

接收版本号（如 0.17.0 或 v0.17.0），可选接收对比基准版本（如 from v0.15.0、base=v0.15.0、对比 v0.15.0）。若未提供基准，自动取前一个 SemVer tag。按顺序执行以下步骤：

步骤 0：前置条件——切换到 main 分支

发布必须在 main 分支上执行（版本 bump 提交与 tag 都落在 main），不要在 dev 或功能分支上发版。

git fetch origin --tags
git rev-parse --abbrev-ref HEAD          # 当前分支
git status --short                        # 工作区是否干净
git rev-list --count main..origin/main    # 本地 main 是否落后远端

处理规则：

• 工作区必须干净（git status --short 为空）；有无关改动先提示用户处理，不要裹挟进发布提交。
• 切到 main 并与远端对齐：git checkout main && git merge --ff-only origin/main。
• 确认 main 已包含本次要发布的内容：发布内容通常通过 PR 合入 main。若内容仍在 dev/功能分支未合入（git rev-list --count main..<分支> > 0），先提示用户走 PR 或 fast-forward 合并，不要在 main 上直接拉取未评审代码。
• 若已在 dev/功能分支误建了 bump 提交、且其父提交正是 main 当前位置，可 git checkout main && git merge --ff-only <分支> 把 bump 并入 main，保持两分支一致（避免分叉）。

⏸️ 用户确认点（当前不在 main、main 落后远端、或发布内容尚未合入 main 时）：展示上述分支状态，说明将如何对齐，用户确认后再切换/合并。

步骤 1：确定并规范化版本号

1a. 解析用户输入

• 用户提供了版本号（如 0.17.0 或 v0.17.0）→ 去掉前缀 v，使用纯 semver 格式。
• 用户未提供版本号 → 进入自动推断。

1b. 自动推断版本号（当用户未提供时）

# 同步远程 tags，确保基于最新数据推断
git fetch --tags

# 取最新 tag
LATEST=$(git tag --sort=-v:refname | head -1)
# 若无历史 tag，提示用户手动输入版本号

推断规则：minor + 1，patch 重置为 0。例如：

• v0.16.0 → 0.17.0
• v1.0.0 → 1.1.0
• v1.2.3 → 1.3.0

若无历史 tag，提示用户手动输入版本号。

步骤 2：更新版本文件

⏸️ 用户确认点：展示推断或用户指定的版本号，提示用户确认。用户确认后再执行。

用 Edit 工具依次更新以下三个文件：

1. src-tauri/tauri.conf.json — 顶层 version 字段
2. package.json — 顶层 version 字段
3. src-tauri/Cargo.toml — [package] 段的第一个 version = "..." 行

步骤 3：同步 Cargo.lock

执行以下命令更新锁文件：

cargo update --manifest-path src-tauri/Cargo.toml --package code-manager

如命令失败（包名不匹配等），跳过并记录。

步骤 4：提交版本变更

⏸️ 用户确认点：展示将要提交的文件列表和 commit message，提示用户确认。用户确认后再执行。

仅暂存版本相关文件，提交：

git add src-tauri/tauri.conf.json package.json src-tauri/Cargo.toml src-tauri/Cargo.lock
git commit -m "chore(release): bump version to {VERSION}"

步骤 5：确定对比基准 tag

确定用于生成 release notes 的基准版本，规则如下：

1. 用户显式指定优先：若用户消息中包含基准版本（如 from v0.15.0、base=v0.15.0、对比 v0.15.0），将其规范化为 vX.Y.Z 格式后直接使用。
2. 自动推断：否则执行以下命令获取上一个 tag：

   git tag --sort=-v:refname | grep -v "^v{VERSION}$" | head -1
   

3. 首次发布：若仓库无任何历史 tag，将基准设为 INITIAL，release notes 标题写 "Initial release"。

校验基准 tag 是否真实存在（git rev-parse {BASE_TAG} 不报错）；不存在则中止并询问用户。

⏸️ 用户确认点：展示确定的版本号和对比基准 tag，提示用户确认。用户确认后再继续。

步骤 6：生成 release notes 并写入临时文件

执行以下流程生成结构化变更日志：

6.1 收集 commits

git log --pretty=format:'%h %s' {BASE_TAG}..HEAD

若基准为 INITIAL，改用 git log --pretty=format:'%h %s'（取全部历史）。

若 {BASE_TAG}..HEAD 区间无 commit（少见，如重打 tag），release notes 为空，需提示用户确认是否继续。

6.2 过滤噪音 commit

移除匹配 chore(release): bump version to 的行（版本升级 commit 本身）。

6.3 按 Conventional Commits 类型归类

将剩余 commit 按以下前缀分组，无对应类型则省略该段：

同类型内按原始 commit 顺序排列（即时间从早到晚）。

6.4 解析 GitHub compare URL

git remote get-url origin

同时兼容两种格式：

• git@github.com:owner/repo.git → https://github.com/owner/repo/compare/{BASE_TAG}...v{VERSION}
• https://github.com/owner/repo.git → 同上

无法解析则省略 compare 链接行。

6.5 生成版本总结

在 commit 分类列表之前，生成一段版本总结。规则：

• 通读本版本所有 commit，识别最重要的功能（feat）和修复（fix）
• 用中文写 3-5 句话，面向终端用户，不暴露技术细节（不提 commit hash、不提变量名）
• 优先介绍新功能，其次重要修复，最后性能优化
• 若无显著变更（只有 docs/chore），写"本次为维护性更新，无功能变更"

6.6 写入临时文件

将生成的 release notes 写入临时文件，模板如下（当基准为 INITIAL 时省略「对比基准」和「完整变更」行）：

Release v{VERSION} ({YYYY-MM-DD})

对比基准：{BASE_TAG}

**版本总结**：{本版本重要变更的总结，3-5 句话}

## 新功能
- feat(xxx): ... ({short_sha})

## 缺陷修复
- fix(xxx): ... ({short_sha})

（其他类型按需出现，无该类型则省略整段）

完整变更：https://github.com/{owner}/{repo}/compare/{BASE_TAG}...v{VERSION}

⏸️ 用户确认点：展示生成的完整 release notes 内容（含版本总结），提示用户审核。用户确认后才写入临时文件。

使用 mktemp 创建临时文件，将上述内容写入其中，记录文件路径为 $NOTES_FILE。

步骤 7：打 annotated tag 并推送

⏸️ 用户确认点：提示用户即将执行不可逆操作（打 tag + push），展示即将执行的命令摘要，请求最终确认。用户确认后才执行 push。

在 main 上（见步骤 0）执行：

git tag -a v{VERSION} -F "$NOTES_FILE"
git push origin main
git push origin v{VERSION}
# 如需保持 dev 与 main 一致（bump 已并入 main），一并推送：git push origin dev
rm -f "$NOTES_FILE"

tag 必须用 annotated（-a）：lightweight tag 不保存 message，git show v{VERSION} 将看不到变更内容。

步骤 8：完成确认

• 汇报已完成的步骤，展示生成的 release notes 内容（供用户确认）。
• 提示用户：tag 推送后 GitHub Actions 的 release 工作流将自动触发，构建产物文件名将使用正确的版本号。
• 提示：GitHub Release 页面的默认 body 仍是 release.yml 中的占位文案「查看 Assets 下载并安装此版本」。若希望 Release 页直接展示此 notes，可后续修改 release.yml 的 releaseBody 改为从 tag message 读取。
• 提醒用户手动发布草稿 Release：workflow 以 releaseDraft: true 创建的是草稿，不会发出 published 事件。构建完成后需用户在 GitHub Releases 页面 review 产物，点击 Publish release 发布为正式版。只有发布后才会触发：① 应用自更新（latest.json 对用户可见）；② update-homebrew-cask.yml（监听 release: published）自动 bump cask。停在草稿态则二者都不触发（cask 仅能靠 workflow_dispatch 手动补跑）。

注意事项

跨步骤的约定与环境依赖（单步内的规则已就近写在对应步骤里）：

• 版本文件中始终使用纯 semver（如 0.17.0），只有 git tag 才加 v 前缀（v0.17.0）。
• 不手动修改 pnpm-lock.yaml，不手动编辑 Cargo.lock（步骤 3 用 cargo update 同步）。
• 应用自更新依赖签名与发布：release workflow 需配置 TAURI_SIGNING_PRIVATE_KEY 与 TAURI_SIGNING_PRIVATE_KEY_PASSWORD 两个 GitHub secret，否则不会生成 .sig 与 latest.json，自更新不可用；src-tauri/tauri.conf.json 的 plugins.updater.pubkey 必须是对应公钥，不能留占位符。