Release Prep

发版准备（release-prep）

这个 skill 在做什么

cc-router 每个版本的更新内容写在仓库根目录 release-notes/<版本>/，编译期内嵌进 app（升级后自动弹窗展示，侧栏底部礼花可重开），CI 也用同一份文件生成 GitHub Release 正文。本 skill 把「升版本号 + 写三语更新内容 + 校验 + 本地提交」串起来，停在打 tag 之前。

完整设计见 docs/superpowers/specs/2026-09-27-release-notes-popup-design.md（本地文件，被 gitignore）。

铁律

• 绝不 git tag、绝不 git push、绝不 gh release …。结束时只打印用户要执行的命令。
• 写之前先问、不猜：拿不准的条目（是否对用户可见、属于哪一节、要不要写）列出来问用户。
• 中文是准绳，英日从中文译出；三份结构逐条对应。
• 提交说明里不提任何其他开源项目的名字，不写用户私有配置值（示例一律中性化），不写 OSS / 国内镜像源的运维细节（bucket、ACL、密钥之类）。

流程

Step 1：前置检查与版本号

git status --short          # 必须干净（允许的只有与本次发版无关、用户明确说不管的文件）
git rev-parse --abbrev-ref HEAD   # 应在 main；不在就问用户
git describe --tags --abbrev=0 --match 'v*'   # 上一个版本 tag，记为 PREV
node -p "require('./package.json').version"   # 当前版本号

• 用户给了版本号：确认它比 PREV 新（semver）。
• 没给：按 Step 2 的素材判断——有「新功能」→ 升 minor；只有修复 → 升 patch；有破坏性变化或用户说是大版本 → 升 major。给出建议版本号请用户确认后再继续。
• 预发布版本（含 -，如 6.1.0-beta.1）：先问用户要不要写更新内容。不写的话 CI 会放行，预发布说明本来也不会展示给正式版用户；这种情况跳过 Step 4–5。
• 顺便问一句版本代号（如 6.0.0 的 Sketchbook），可以不填。

Step 2：收集素材

git log --no-merges --reverse --format='--- %h %an%n%B' PREV..HEAD

默认只读提交信息（标题 + 正文）——这个仓库的提交正文大多写得很完整，够用。以下情况必须看改动本身：标题含糊（如 update providers、fix、wip）、没有正文、或正文与标题对不上。先 git show --stat <sha> 看动了哪些文件，再只看相关文件的 diff（git show <sha> -- <path>），弄清它实际包含几处用户可感知的变化。

整理规则：

0. 排除只动 release-notes/ 的提交：它们是在补写 / 修订已发布版本的说明（例如 PREV 打 tag 之后才补齐的上一版说明），不是本版本的变化。
1. 按用户可感知的变化归类，不按 conventional-commit 前缀机械归类：
   • ## 新功能：用户能用到的新能力、新界面、新入口、行为上的新选项。
   • ## 修复：上一个版本里已经存在的问题被修好。
   • ## 其他：用户能感知但不算功能 / 修复的变化（打包、日志、依赖升级带来的可见影响、文档）。
2. 同一版本里新功能的修补提交并进那条新功能，不单列进「修复」。判断方法：修的东西是在 PREV 之后才加的（同一 scope、提交时间在 PREV 之后）。
3. 默认不写：纯重构、测试、CI 流程、内部文档、代码风格、只影响开发者的改动。例外：它带来了用户可见的影响（例如「安装目录不再附带 yaml 文件」）。
4. 合并同类、拆分混装：同一功能的多个提交写成一条，子要点用二级列表；反过来，一个提交里混了几处不相干的变化（常见于标题含糊的提交，比如一个「修复 + 新端点 + 改名」的厂商更新），按变化拆到各自的分节里。
5. 外部贡献者的 PR（提交作者不是维护者）：问用户要不要致谢，不要自己决定。PR 编号从合并提交的标题找（Merge pull request #48 from …），找不到再用只读命令 gh pr list --state merged --search <sha>。用户同意的话，写在要点名后面的编号里：
   • zh：**新增 Requesty 服务商**（#48，感谢 @作者）：…
   • en：**Requesty provider** (#48, thanks @author): …
   • ja：**Requesty プロバイダーを追加**（#48、@author さんに感謝）：…
6. 拿不准的条目汇总成一个列表问用户（一次问完，不要一条一条问）。

Step 3：升版本号

pnpm version:set X.Y.Z

它同步 package.json / tauri.conf.json / 两个 Cargo.toml / Cargo.lock，并在 release-notes/X.Y.Z/ 下生成 meta.json（日期是今天）和只有分节标题的 zh.md 骨架。有代号就把 "codename": "…" 加进 meta.json。

Step 4：写三份说明

路径：release-notes/X.Y.Z/zh.md、en.md、ja.md（覆盖骨架）。

允许的 Markdown 子集（严格，写错 release 构建会失败）

禁止：图片、HTML（< 后面紧跟字母）、# / ### 标题、有序列表、表格、引用、* / + 列表符号、三层嵌套、空分节。

分节标题（固定）

某一节没有内容就整节删掉（空分节会被解析器拒绝）。

文风（照 release-notes/6.0.0/zh.md）

• 摘要：大版本 / 功能较多的版本写一段摘要，说清这一版的主题和「升级后默认行为是否变化、新功能默认开还是关」。纯修复的小版本可以不写摘要。
• 列表项：- **要点名**：说明。——要点名是用户在界面上能认出来的功能名，说明写「做了什么、在哪里打开、有什么限制」。
• 不写指向弹窗本身的话（如「也就是你现在看到的这份说明」）——同一份正文也会原样出现在 GitHub Release 页面上。
• 写事实，不写营销话术（不用「全新」「极致」「强大」）；不写实现细节（函数名、文件名、crate 名），除非用户要用到它（命令行参数、环境变量、配置字段）。
• 需要重启 app 才生效、默认关闭、只在某个平台生效——都要写明。
• issue 编号写在要点名后面：**自定义厂商自动获取模型列表**（#44）：…（英日同样位置用半角 (#44)）。
• 界面上的名称与设置路径从 locale 文件里取原词：中文查 src/i18n/locales/zh.json，英文查 en.json，日文查 ja.json（例：「设置 → 安全与访问 → 终端界面」对应的 en / ja 路径）。找不到对应词再自己译。

参考片段（6.0.0 真实内容的节选）：

这是一个大版本：桌面端换上与官网一致的「手绘速写本」外观；新增终端界面 cc-router-tui，不开窗口也能管理 cc-router。升级后默认行为不变，终端界面默认关闭。

## 新功能
- **终端界面 cc-router-tui**（默认关闭）：在终端里管理正在运行的 cc-router。打开方式：设置 → 安全与访问 → 终端界面，打开「启用终端界面」。
  - 共五个标签：总览、订阅、虚拟模型、实时路由、请求日志。
  - 只接受本机连接，不需要打开网页界面。

## 修复
- **数据库体积上限真正生效**：这个设置以前不起作用。现在超过上限（默认 500 MB）会从最旧的请求日志和事件开始删除；设为 0 表示关闭。

英日翻译要求

• 结构与 zh.md 逐条对应：摘要段数、列表项与二级项的数量和顺序、加粗位置、#44 编号、反引号用法都一致。
• 英文：简洁的产品说明语气，句首大写，要点名用 Sentence case。
• 日文：です・ます体，全角标点（：「」）；括号不要全半角混用；数字与英文单词两侧的空格按日文习惯处理（3 言語、500 MB）。

Step 5：校验

node scripts/release-body.mjs --check vX.Y.Z          # CI 第一个 job 用的同一条检查
cd src-tauri && cargo test every_embedded_release_note_is_valid   # 与 app 同一个解析器
cd .. && node scripts/release-body.mjs vX.Y.Z         # 预览 GitHub Release 正文

守卫测试报错会给出文件和行号，按上面的子集改格式后重跑。三份都过了再进 Step 6。

Step 6：给用户审

把三份全文贴给用户（不要只贴摘要），附上：

• Step 2 里决定不写的提交清单（一行一个，写原因），方便用户捞回。
• 仍未确认的问题（代号、致谢、拿不准的条目）。

用户改了中文 → 把改动同步到 en / ja（保持逐条对应）→ 重跑 Step 5。 用户直接改了英文或日文 → 只改那一份，不要反向改中文。 反复到用户明确说「可以 / 提交」为止。

Step 7：本地提交并停下

git add -u && git add release-notes/X.Y.Z
git commit -m "Bump version to X.Y.Z"   # 按当前环境要求附上 Co-Authored-By 尾行
git status -sb                          # 报告领先 origin 几个提交

然后停下，告诉用户接下来由他本人执行：

git tag vX.Y.Z

git push && git push --tags

并提醒：推 tag 后 CI 会先检查 zh.md，构建通过后用这三份文件生成 Release 正文并自动发布。

常见坑

• 忘了删空分节：只有「修复」的小版本，## 新功能 / ## 其他 骨架没删 → 解析器报「分节下没有列表项」，release 构建失败。
• 分节里写了段落：分节里的每一行都必须是 - 或两空格 - 。想补充说明就写成二级列表项。
• 把同版本新功能的修补写进了「修复」：用户会看到「修复了一个自己从没见过的功能」。
• 英日漏条 / 多条：审之前逐节数一遍条目数。
• 行内出现 <：比如 <版本>、<token> 会被当成 HTML 拒绝，改成「版本号」这类文字或放进反引号。
• 在 pnpm tauri dev 里关掉了弹窗：dev 与生产共用数据目录，会把「已看过」写成新版本，你自己的生产版之后就不会再弹这一版。想在本机看效果，先备份 ~/Library/Application Support/com.cc-router.desktop/settings.json。