[Unreleased]

[Unreleased]

<一段有力的开场段：这个 release 的主题是什么、为什么重要。 必须锚定到已交付的具体变更，禁止空泛吹捧。>

<一段关于重大技术转向的段落（如适用）。>

<Feature/Theme Group>

• 带具体细节的条目
• 有 PR 时引用 PR（如 [#123]，链接参考定义在文件底部）

• ...

Bug Fixes

• ...

对照仓库中真实的历史章节，这个骨架是被严格执行的：

- **开场叙事段**：`## [0.5.0]` 以 "**The Capture release.** Voicebox stops being just a voice-cloning studio and becomes a full AI voice studio." 开篇——一句话点题，随后直接落到"按住全局热键说话、松手文本落入焦点输入框"等具体功能；
- **主题分组**：同一版本下按 `### Dictation`、`### Personality`、`### Agents`、`### Refinement`、`### Stories` 等业务主题分组，而不是按 commit 顺序罗列；
- **PR 可追溯**：修复类条目普遍标注 PR/Issue 编号，如 0.4.5 章节中的 "(#530, fixes #526)"。

### 风格指南（Style Guidelines）

Skill 原文列出的六条风格规则，逐条值得展开：

| 规则 | 含义与仓库实证 |
| --- | --- |
| **Factual and specific（事实、具体）** | 每个论断都能追溯到真实 commit 或 PR。例如 0.4.3 章节对 DMG 公证的修复精确到 "the release workflow now submits each DMG to notarytool, staples the ticket, verifies with spctl"，这是从 commit/PR 实现细节提炼的，而非泛泛的"修复了公证问题"。 |
| **Narrative over list（叙事优先于列表）** | 先写讲故事的问题引入段落，再用 bullet 支撑。0.5.0 用两段话讲清"从克隆工具到声音工作室"的定位变化，才进入功能列表。 |
| **Group by theme, not by commit（按主题分组，不按 commit）** | 分组标题是描述性业务名（"Frozen-Binary Reliability"、"Voice Profile UX"），而非 commit hash 或模块路径。 |
| **Reference PRs where they exist, but don't fabricate them（有 PR 就引用，绝不编造）** | 与"禁止编造"的全局事实约束一致；草稿阶段拿不准编号时宁可不写。 |
| **Skip trivial chores（跳过琐碎事务）** | 错别字修复、CI 微调等，除非它们构成整个 release 的主体，否则不写入。 |
| **Match the voice of existing releases（对齐既有语气）** | Skill 明确要求参考 [CHANGELOG.md](https://gitcode.com/GitHub_Trending/voicebox1/voicebox/blob/51f49dea198384b4eb6087b72c17057c6eb1c1cd/CHANGELOG.md?utm_source=gitcode_repo_files) 中的 v0.2.1 和 v0.2.3 条目作为语气基准——前者是"引擎总览 + 表格"式的里程碑叙事，后者是"it works in dev but not in prod"式的幽默自嘲开场。两者展示了该项目 changelog 允许的语气光谱：技术里程碑可以宏大叙事，hotfix 可以用口语化标题。 |

## 五、边界情况：没有变更时怎么办

Skill 专门规定了空场景的处理：

> If `git log "$LAST_TAG"..HEAD` is empty, leave the `[Unreleased]` section empty (just the heading) and tell the user there's nothing to draft.

即：如果最近 tag 以来没有任何 commit，就**保留空章节（只有标题）**并明确告知用户"没有可起草的内容"，而不是用历史内容填充或跳过更新。这与第 3 步的"章节必须存在"不变式一致——`[Unreleased]` 永远在，但内容可以为空。

## 六、仓库佐证：草稿如何流入定稿、CI 与 UI

草稿 skill 不是孤立存在的，仓库中的三个环节印证了它的上下游：

### 6.1 下游定稿：release-bump skill

[.agents/skills/release-bump/SKILL.md](https://gitcode.com/GitHub_Trending/voicebox1/voicebox/blob/51f49dea198384b4eb6087b72c17057c6eb1c1cd/.agents/skills/release-bump/SKILL.md?utm_source=gitcode_repo_files) 在 Prerequisites 中写明："[Unreleased] section should already contain the release narrative. If it's empty or stale, run the draft-release-notes skill first."（若草稿为空或过期，先跑 draft-release-notes）。其定稿流程为：

1. 校验工作树干净（除 `CHANGELOG.md` 外不应有未提交变更）；
2. 读取 `.bumpversion.cfg` 中 `current_version`（当前仓库为 `0.5.0`），确定 patch/minor/major；
3. 把 `[Unreleased]` 正文"盖章"为 `## [X.Y.Z] - YYYY-MM-DD`，并更新文件底部的 compare 链接参考；
4. `git add CHANGELOG.md` 后运行 `bumpversion --allow-dirty <level>`，由 [.bumpversion.cfg](https://gitcode.com/GitHub_Trending/voicebox1/voicebox/blob/51f49dea198384b4eb6087b72c17057c6eb1c1cd/.bumpversion.cfg?utm_source=gitcode_repo_files) 驱动同时更新 9 个版本载体文件（两个 `package.json` 家族共 5 处、`tauri.conf.json`、`Cargo.toml`、`backend/__init__.py` 等），创建 `Bump version: X.Y.Z → A.B.C` 提交并打 tag `vA.B.C`。

`.bumpversion.cfg` 的内容与 skill 描述完全吻合：`commit = True`、`tag = True`、`tag_name = v{new_version}`，且列出的每个 `bumpversion:file` 条目都对应定稿 commit 中应出现的文件。

### 6.2 CI 自动消费：tag 推送后提取 CHANGELOG 作为 Release 正文

[.github/workflows/release.yml](https://gitcode.com/GitHub_Trending/voicebox1/voicebox/blob/51f49dea198384b4eb6087b72c17057c6eb1c1cd/.github/workflows/release.yml?utm_source=gitcode_repo_files#L178-L198) 中有一个 "Extract release notes from CHANGELOG.md" 步骤，用 sed 按章节边界精确截取对应版本区间：

```bash
NOTES=$(sed -n "/^## \[${VERSION}\]/,/^## \[/{/^## \[${VERSION}\]/d;/^## \[/d;p;}" CHANGELOG.md)