| name | release |
| description | Automates SailFish release workflow: fix build/type errors, update CHANGELOG (EN + CN), run npm version with pre/post hooks. Use when the user asks to release, 发版, 发布, bump version, or update changelog. |
SailFish 发版技能
本技能用于在本仓库内执行发版流程：解决构建/类型错误、更新更新日志、执行 npm version。
前置条件
- 必须在 develop 或 main 分支执行。
- 执行
npm version 前工作区必须干净（无未提交更改）。
发版节奏（提醒，不硬拦）
用户侧已有「软件更新太快」反馈。启动发版时根据上次 tag 日期主动提醒用户，不要擅自拒绝发版；用户确认继续则照常往下走。
| 类型 | 节奏 | 说明 |
|---|
| 常规（minor / 非紧急 patch） | 建议 每周最多 1 次 | 功能继续合 develop，凑窗口再发；避免同一自然周连发多个正式版 |
| 热修（紧急 patch） | 可破例 | 仅限启动崩溃、数据损坏、严重安全等必须立刻推给用户的问题 |
判断提示（写入步骤 1 预览里即可，一两句）：
- 读上一版 tag 的提交日期（如
git log -1 --format=%ci v<当前版本>）。
- 若距今 不足约 7 天，且本次不是上述热修：提醒「距上次发版仅 X 天，按周更节奏建议先攒着；若坚持发可确认后继续」。
- 若同一自然周内已发过正式版：额外提一句「本周已发过版，连发会加重更新打扰」。
发版流程（推荐顺序）
版本号由 npm version 产生，而更新日志需在之前提交，因此要先定发版类型，再按"即将产生的版本号"写日志，保证一致：
-
确定发版类型并预览变更日志：先运行 git log v<当前版本>..HEAD --oneline 查看自上次发版以来的提交，根据改动内容主动给出建议（参考下方规则），让用户确认即可，不要让用户自己判断。同时按上方「发版节奏」检查距上次发版间隔，必要时提醒用户。
- 含 breaking change / 大规模重构 → 建议
major
- 含新功能 / 新模块 → 建议
minor
- 仅修复、优化、文档 → 建议
patch
确认后，读取 package.json 的 version，按 semver 推算出下一版本号（如 8.19.4 → patch 为 8.19.5，minor 为 8.20.0）。同时根据提交记录拟定 CHANGELOG_CN.md 的完整条目（版本标题、一句话总结、分类列表），一并展示给用户预览确认。用户确认后再继续后续步骤。
-
修复构建、检查与测试：运行 npm run verify（并行执行类型检查、lint、构建、单元测试、CLI 回归测试），确保全部通过。
-
更新更新日志：用步骤 1 确认的版本号在 CHANGELOG.md 与 CHANGELOG_CN.md 中写入本版本条目（见下文格式），内容以步骤 1 用户确认的中文版为准，英文版对应翻译。
-
检查 README 和网站是否需要更新：对于 minor 或 major 版本，对比自上次发版以来的提交，检查以下文档是否需要同步更新（如新增功能/通道/文档链接等），若需要则一并修改：
README.md 和 README_CN.md（功能列表、描述、文档链接）website/src/i18n/translations.ts（网站功能介绍、Hero 文案等）
-
提交日志及文档变更：git add 并 git commit 更新日志和可能的 README 变更。
-
执行版本号更新：执行与步骤 1 一致的 npm_config_yes=true npm version <patch|minor|major>，此时产生的版本号会与日志中一致。
⚠️ AI 工具调用 / 脚本 / 任何无 TTY 场景必须加 npm_config_yes=true 前缀，否则 preversion 的交互式"确认继续? (y/N)"会挂死。preversion 已加非 TTY 检测，缺前缀时会快速失败并报错而非挂起。
1. 解决构建/类型错误
不要用关键词匹配来"猜"错误类型，必须依据实际命令输出定位问题。
-
运行 npm run verify 一次性并行执行所有检查，收集真实错误输出：
- 类型检查（
vue-tsc --noEmit）
- 静态检查（
eslint）
- 生产构建预检（
vite build --mode production）
- 单元测试（
vitest run）
- CLI 回归测试（
test-cli.sh --no-ai，参见 .cursor/rules/cli-testing.mdc）
-
根据终端或 IDE 报错信息修复：
- TypeScript/
vue-tsc：按文件与行号修类型或实现。
- ESLint：按规则修代码或配置。
- Vite 构建错误：按报错模块与堆栈修复。
-
修复后再次运行上述命令，直到全部通过。
2. 更新更新日志
写日志时使用的版本号必须是即将通过 npm version 产生的版本号（由当前 package.json 的 version + 已确定的 patch/minor/major 推算），这样先提交 changelog 再执行 npm version 时不会出现版本号不一致。
本项目有两个日志文件，需同时更新、内容对应：
| 文件 | 语言 |
|---|
CHANGELOG.md | 英文 |
CHANGELOG_CN.md | 中文 |
版本标题格式
每个版本标题都需要包含发布日期（YYYY-MM-DD 格式，取发版当天日期）：
- CHANGELOG.md：
## vX.Y.Z (YYYY-MM-DD) (Latest)（当前最新）或 ## vX.Y.Z (YYYY-MM-DD)（历史版本）。
- CHANGELOG_CN.md：
## vX.Y.Z (YYYY-MM-DD)（最新版本） 或 ## vX.Y.Z (YYYY-MM-DD)。
发版时把上一版的"(Latest)"/"（最新版本）"移到本版，上一版改为普通 ## vX.Y.Z (YYYY-MM-DD)。
版本一句话总结
每个版本标题下方、分类列表之前，需要写一段一句话总结（1-2 句），概括该版本的核心主题和亮点。总结应聚焦于"这个版本最重要的变化是什么"，而非罗列所有改动。中英文日志均需包含，内容对应。
分类与条目格式
CHANGELOG.md：
### New Features — 新功能### Improvements — 改进### Bug Fixes — 问题修复
CHANGELOG_CN.md：
每条目一行，列表项格式示例：
- 英文：
- 📝 **简短标题**：说明文字 或 - 📝 说明文字
- 中文：与英文一一对应翻译/改写
收集变更条目
用以下命令获取自上次发版 tag 以来的所有提交，作为写日志的素材：
git log v<当前版本>..HEAD --oneline
例如当前版本为 8.19.4：git log v8.19.4..HEAD --oneline。
根据提交记录归类到 New Features / Improvements / Bug Fixes，用户也可口述补充。不编造未发生的改动。
3. 执行 npm version
preversion 钩子带交互式确认（"确认继续? (y/N)"）。AI 工具调用 / 脚本 / CI / 任何无 TTY 场景必须加 npm_config_yes=true 前缀，否则 preversion 会快速失败（已加 TTY 检测，不再无限期挂起）。
- AI / 脚本（推荐）：
npm_config_yes=true npm version patch（或 minor / major）
- 仅人工终端：
npm version patch
- 仅改
package.json 不打 tag：追加 --no-git-tag-version（跳过钩子）
preversion（scripts/preversion.js）会：
- 检查分支为 develop 或 main、工作区干净。
git pull --ff-only、git fetch --tags。- 保存当前分支状态（不切换分支，避免 npm 在错误分支上重复 bump）。
注意：preversion 不再重复运行验证。完整的代码验证（npm run verify）在发版流程步骤 2 已执行，之后只改文档不改代码，无需再跑。
postversion（scripts/postversion.js）会：
- 若从 develop 发版：先推送 develop（含版本 commit），再切到 main、合并 develop、推送 main 和 tag，最后切回 develop。
- 若从 main 发版：直接推送 main 和 tag。
发版前务必已先提交 CHANGELOG 的修改，再执行 npm version，否则 preversion 会因"工作区不干净"失败。
快速检查清单
OSS 与自动更新布局
tag 推送后 CI 会上传 GitHub Releases + 阿里云 OSS。桶根目录（官网固定文件名）与 releases/（应用内更新、带版本号、blockmap 永久保留）勿混用。
详见 docs/auto-update-oss.md。
