# Release Notes

> 生成清风输入法（WindInput）的版本发布说明 / Release Note / 升级说明。当用户要求「写 0.xxx 的说明」「生成 release note」「发版说明」「更新日志」时使用。跨仓采集提交、按四类归纳、按用户视角压缩措辞。

- Skill: `huanfeng/release-notes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add huanfeng/release-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/huanfeng/release-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: huanfeng (https://skillmd.com/u/huanfeng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/huanfeng/release-notes

---


# 版本发布说明生成

把一个版本周期内的提交，翻译成**用户视角**的升级说明。产物是 GitHub Release
正文里 `<!-- user-facing:start -->` 与 `<!-- user-facing:end -->` 之间的部分，
header（下载表）与 footer（文档链接）由 `docs/release-notes/` 模板自动拼接，**不要生成**。

---

## 一、采集

### 1. 确定版本区间

```bash
cat docs/VERSION                        # 本次版本号
git tag --list 'v0.*' --sort=-v:refname | head -3
git log -1 --format='%ci' v<上一版>     # 拿到上一版 tag 的时间戳，供跨仓过滤
```

### 2. 主仓提交

```bash
git log --oneline v<上一版>..HEAD
```

### 3. 相邻仓（必查，说明要融合设置界面的改动）

用上一步的时间戳过滤：

| 仓库 | 路径 | 产出什么条目 |
| --- | --- | --- |
| 设置界面 | `../wind-setting` | 设置页/词库窗的功能与修复，**分量与主仓相当** |
| GUI 框架 | `../wind-ui-rust` | 只挑设置窗可感知的（渲染性能、窗口行为），通常 1–2 条 |

```bash
git -C ../wind-setting log --oneline --since='<上一版时间戳>'
git -C ../wind-ui-rust  log --oneline --since='<上一版时间戳>'
```

### 4. 参考上一版的风格

```bash
gh release view v<上一版> --repo huanfeng/WindInput
```

### 5. 读关键提交的正文

`git log --oneline` 的标题写给开发者看，判断不出用户影响面。对候选进入
「新功能」的提交，逐个 `git log -1 --format='%s%n%b' <sha>` 读 body，
确认：出厂默认值、入口位置、是否实验性、是否有行为变更。

---

## 二、分类：只有四类，不许新增

```markdown
## ✨ 新功能
## ⚡ 优化改进
## 🐛 问题修复
## 📌 其他说明
```

重构（`refactor`）按用户感知拆进「优化改进」或「其他说明」，**不单开一类**。

### 归类判据

| 情况 | 落点 |
| --- | --- |
| 用户能主动去「用」的新能力 | 新功能 |
| 标着 `feat` 但用户用不到（内部旁路字段、抽象层、为未来铺路） | 优化改进，或直接删 |
| 已有功能变得更好用/更快/更好看 | 优化改进 |
| 已发布版本里存在的缺陷 | 问题修复 |
| 社区致谢、格式版本兼容性、次要变更 | 其他说明 |

### 同一块工作可以跨两类

按键系统这类大改动，**能力进新功能，形态/体验进优化**：

- 新功能：`增加全局按键自定义/优化方案级按键自定义，重构按键对话框`
- 优化：`按键配置改为行式编辑，支持组合键，功能改由分类对话框选择`

---

## 三、先删再写

写之前先把这些整批扔掉，不要犹豫：

1. **`docs` / `test` / `build` / `ci` / `chore` 提交** —— 一条都不写。
2. **本周期内引入、又在本周期内修掉的 bug** —— 用户从没见过它。
   例：新写的设置窗第二次打开崩溃、新加的「恢复默认」清空引导键。
3. **用户感知不到的性能优化** —— 例：去掉按键热路径上的整表 clone、
   推送去重。除非能说出用户能察觉的结果（延迟、CPU、卡顿）。
4. **安全加固与校验** —— 多条合并成一条，不逐条列。
   例：`修正方案包导入时越界路径与超大文件的校验问题`。
5. **内部实现细节** —— 数据结构、trait、模块名、判据、常量名一律不出现。

一个版本周期 90+ 提交，最终大约 35–40 条，每类 10–15 条。

---

## 四、写作规约

### 新功能：说「有什么 + 在哪开」，不说「怎么工作」

```
增加 <功能名>（<出厂状态/默认值>，<入口路径>，详见文档）
```

- 机制、原理、适用场景**全部交给文档**，正文只留一句。
- 入口路径要**完整且穷举**：`设置 → 高级 → 导入与导出 或 设置左栏/下栏处右键菜单`。
- 出厂关闭、实验性要**显式标注**：`（实验性！出厂关闭，在「方案设置 → 拼音」中开启）`。
- 行为变更类要标默认值与可配置性：`空码时按标点键清空编码（默认开，可配置）`。

### 优化改进：说结果，不说手段

手段（去掉了哪把锁、改了哪个数据结构）是提交信息的事。

### 问题修复：唯一可以写具体的一类

固定句式 **`修正 xxx 的问题`**。这里要**保留触发条件**，用户得能对上自己遇到的现象：

> 修正切换方案的热键**在英文半角、大写锁定状态下**不生效的问题

### 术语：用用户的词，不用内部代号

| 内部说法 | 写进说明 |
| --- | --- |
| 短语分发格式 `wind:p1` | 短语快捷导入格式 |
| 音节边界求解 | 拼音的切分处理 |
| 词库层 demotion / override 折叠 | （不写，或说收益） |

**例外**：用户真正要输入或看到的标识符保留反引号原样 —— `calc.percent`、
`key.type`、`.wpkg`、`Tab`、`inf%`。

---

## 五、压缩对照表（这一节是本 skill 的核心）

左列是「写得像 AI」的典型，右列是实际发布的版本。改写时逐条对照。

| ❌ 初稿 | ✅ 发布版 | 规律 |
| --- | --- | --- |
| 增加辅助码筛选：拼音打完后按触发键（双拼默认 `` ` ``）进入辅助码态，用笔画、小鹤形码等字形码对当前候选二次收窄，重码多时不必翻页（出厂关闭，在「方案设置 → 拼音」中开启） | 增加辅助码筛选（实验性！出厂关闭，在「方案设置 → 拼音」中开启，详见文档） | 教学交给文档 |
| 增加短语分发格式：几条短语导出成一段纯文本（首行 `wind:p1`），可直接贴进聊天窗口分享，导入前逐条预览落点 | 增加短语快捷导入格式（详见文档） | 同上 + 换用户词汇 |
| 词库管理独立成窗，左栏平铺词库类型，右侧整幅让给表格 | 词库管理独立成窗口，更方便操作 | 不描述 UI 布局，说收益 |
| 空码时按标点键可丢弃废码（出厂开启）：打错字根后按句号，不再把一串废码跟着送上屏 | 空码时按标点键清空编码（默认开，可配置） | 砍掉场景故事，留行为+默认值 |
| 优化 TSF 端日志写入，去掉输入线程上的跨进程锁，降低输入延迟；日志被外部删除后一秒内自动重建 | 优化 TSF 端日志写入 | 内部手段全砍 |
| 候选窗宽度受控：超长候选按像素截断并显示省略号，不再探出屏幕或盖掉圆角；主题的宽度上限出厂改为不限 | 候选窗宽度受控优化，默认主题不再限制纵排宽度 | 只留用户会注意到的那一处变化 |
| 临时英文复用英文方案的词频与候选调整，选过的词会记住，右键菜单也可用 | 临时英文复用英文方案的词频与候选调整 | 派生效果不展开 |
| 词库导入支持自动求解拼音音节边界，导入的词简拼、混合简拼也能召回 | 词库导入支持自动拼音的切分处理 | 术语降级，效果不展开 |
| 方案设置页改为 TAB 布局，码表配置内联为「总开关 + 折叠区」 | 方案设置页改为 TAB 布局 | 次级细节删掉 |
| `.wpkg` 有了独立的文件图标，不再与程序图标同款 | `.wpkg` 有了独立的文件图标 | 对比句删掉 |
| 增加统一配置导入：…导入前逐键预览「当前值 → 新值」（设置 → 高级 → 导入与导出） | 增加统一配置导入：…（设置 → 高级 → 导入与导出 或 设置左栏/下栏处右键菜单） | **机制换成更多入口** |

**修复类条目基本原样保留** —— 说明「修正 xxx 的问题」这个句式一次就能写对，
不需要压缩。压缩压力全在新功能和优化两类。

---

## 六、开头的警告行

TSF 端、按键转发表、驱动层有改动时，第一行给一条独立警告：

```markdown
## ⚠️ 此版本修改了 TSF 端与按键转发表，升级后部分按键相关功能需要重启系统才会生效。
```

判据：本周期是否动过 `wind_tsf` / TSF 转发表 / 按键注册。没动就不写这行。

---

## 七、交付

1. 输出完整 markdown 原文（四个分类，不含 header/footer），供用户直接润色。
2. 正文之后附**几点取舍说明**：哪些条目合并了、哪些是行为变更值得单独确认、
   哪些分类归属可以调整。不要把这些混进 markdown 正文。
3. 破坏性变更（配置键删除/重命名、格式版本升级）必须在「其他说明」里点名，
   由用户决定留不留。