---
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` 前工作区必须干净（无未提交更改）。

---

## 发版流程（推荐顺序）

版本号由 `npm version` 产生，而更新日志需在之前提交，因此要**先定发版类型**，再按"即将产生的版本号"写日志，保证一致：

1. **确定发版类型并预览变更日志**：先运行 `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` 的完整条目（版本标题、一句话总结、分类列表），一并展示给用户预览确认。**用户确认后**再继续后续步骤。
2. **修复构建、检查与测试**：运行 `npm run verify`（并行执行类型检查、lint、构建、单元测试、CLI 回归测试），确保全部通过。
3. **更新更新日志**：用**步骤 1 确认的版本号**在 `CHANGELOG.md` 与 `CHANGELOG_CN.md` 中写入本版本条目（见下文格式），内容以步骤 1 用户确认的中文版为准，英文版对应翻译。
4. **检查 README 和网站是否需要更新**：对于 `minor` 或 `major` 版本，对比自上次发版以来的提交，检查以下文档是否需要同步更新（如新增功能/通道/文档链接等），若需要则一并修改：
   - `README.md` 和 `README_CN.md`（功能列表、描述、文档链接）
   - `website/src/i18n/translations.ts`（网站功能介绍、Hero 文案等）
5. **提交日志及文档变更**：`git add` 并 `git commit` 更新日志和可能的 README 变更。
6. **执行版本号更新**：执行与步骤 1 一致的 `npm_config_yes=true npm version <patch|minor|major>`，此时产生的版本号会与日志中一致。

   > ⚠️ AI 工具调用 / 脚本 / 任何无 TTY 场景**必须加 `npm_config_yes=true` 前缀**，否则 preversion 的交互式"确认继续? (y/N)"会挂死。preversion 已加非 TTY 检测，缺前缀时会快速失败并报错而非挂起。

---

## 1. 解决构建/类型错误

**不要**用关键词匹配来"猜"错误类型，必须依据实际命令输出定位问题。

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`）

2. 根据终端或 IDE 报错信息修复：
   - TypeScript/`vue-tsc`：按文件与行号修类型或实现。
   - ESLint：按规则修代码或配置。
   - Vite 构建错误：按报错模块与堆栈修复。

3. 修复后再次运行上述命令，直到全部通过。

---

## 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 以来的所有提交，作为写日志的素材：

```bash
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`）会：

1. 检查分支为 develop 或 main、工作区干净。
2. `git pull --ff-only`、`git fetch --tags`。
3. 保存当前分支状态（不切换分支，避免 npm 在错误分支上重复 bump）。

> 注意：preversion 不再重复运行验证。完整的代码验证（`npm run verify`）在发版流程步骤 2 已执行，之后只改文档不改代码，无需再跑。

**postversion**（`scripts/postversion.js`）会：

1. 若从 develop 发版：先推送 develop（含版本 commit），再切到 main、合并 develop、推送 main 和 tag，最后切回 develop。
2. 若从 main 发版：直接推送 main 和 tag。

发版前务必已**先提交 CHANGELOG 的修改**，再执行 `npm version`，否则 preversion 会因"工作区不干净"失败。

---

## 快速检查清单

- [ ] 中文变更日志已预览并经用户确认
- [ ] `npm run verify` 通过（类型检查 + lint + 构建 + 单元测试 + CLI 回归，并行执行）
- [ ] `CHANGELOG.md` 与 `CHANGELOG_CN.md` 已更新且版本号、日期、条目一致
- [ ] （minor/major）检查 `README.md`、`README_CN.md` 和 `website/src/i18n/translations.ts` 是否需要同步更新
- [ ] 更新日志及文档变更已提交
- [ ] 当前在 develop 或 main，无未提交更改
- [ ] 执行 `npm_config_yes=true npm version <patch|minor|major>` 完成发版（AI / 脚本场景必加前缀）