ai: Changelog skill

.claude/skills/changelog/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: changelog
+description: 根据提交记录、PR、diff、现有 CHANGELOG 与历史 tag 内容，整理符合 MAA 发布规范的 changelog Markdown。用于修正工具自动生成的 changelog、合并同类改动、清理 bot 或 release 噪音，并产出可直接提交的最终版本。
+---
+
+# MAA Changelog Skill
+
+## Goal
+
+- 读取待发布范围内的 commit、PR、diff、现有 CHANGELOG 与对应 tag 内容，输出可直接写入 CHANGELOG.md 的最终 Markdown 片段。
+- 只输出最终 Markdown，不输出分析过程、分类理由、筛选记录、额外说明或 Markdown 代码围栏。
+- 以“最终用户看得懂、历史版本不断裂、同类改动不重复”为第一目标，不以保留原始 commit 标题为目标。
+
+## Scope
+
+- 适用于正式版、测试版、补丁版的 changelog 整理与重写。
+- 正式版的补丁版本不应该修改 Highlights 中的内容，除非确实有用户可感知的重要变化。
+- 当工具已经生成初稿时，初稿只可作为原始素材，不能直接信任其分类、版本归属、标题质量、去重结果与排序结果。
+- 如果 commit 标题含糊、口语化、玩梗、只写 review、typo、warning、日志顺序、调整坐标等，必须查看 diff 后改写为专业、完整、可独立理解的用户向描述。
+
+## Required Inputs
+
+- 目标版本号。
+- 待发布的提交范围，或可推导该范围的 PR、tag、分支信息。
+- 当前 CHANGELOG 内容。
+- 如果目标版本与已有正式版属于同一非 patch 版号，必须先读取对应正式版 tag 下的 changelog 内容，再决定如何合并与追加。
+
+## Non-Negotiable Rules
+
+### 1. 先看净变更，再写条目
+
+- 对同一功能、同一问题或逻辑相关的多条 commit，应合并为单条 changelog 项。
+- 合并后的描述必须简洁、专业、面向最终用户，避免堆实现细节。
+- 若 commit 标题不足以表达改动价值，必须结合 diff 重写标题。
+- Revert 不是 changelog 项。遇到 Revert 时，必须结合最终 diff 判断净效果：
+- 若原改动被完整撤销，则 Revert 与原始项都删除。
+- 若最终仍保留部分语义，则把原始项与 Revert 合并为一条准确描述最终结果的 changelog 项。
+- 不要把“review”“日志顺序”“调整坐标”“typo”“build warning”这类缺乏用户语义的提交原样保留为条目，除非 diff 证明它确实修复了用户可感知问题。
+
+### 2. 分类按用户价值，不按 commit 前缀
+
+- 改动必须放入正确模块：Highlights、新增 | New、改进 | Improved、修复 | Fix、文档 | Docs、其他 | Other。
+- 新功能、新支持、新入口、新导出能力、新兼容性，放“新增 | New”。
+- 现有能力增强、性能提升、稳定性提升、体验优化、识别优化、重构后带来的用户收益，放“改进 | Improved”。
+- 缺陷修正、兼容性修复、异常处理、回归修复，放“修复 | Fix”。
+- 纯文档变更放“文档 | Docs”。
+- 仅内部维护、CI、脚本、杂项且不适合省略时，才放“其他 | Other”。
+- 如果自动生成结果分类错误，必须移动到更合适的模块并同步调整描述。
+
+### 3. 模块内排序与文案规范
+
+- 中文条目放在前面，纯英文条目排在该模块最后。
+- 同一模块内按逻辑相关性或重要性排序：功能与接口变更优先，其次是兼容性或实现优化，最后是次要修复或杂项。
+- 列表统一使用 * 作为项目前缀。
+- 中英文数字混排时，在英文词与数字之间保留空格，例如：修复 3 个 bug、支持 3D 功能。
+- 统一常见术语大小写与写法，例如 WPF、Json、Markdown、CSV、Info。
+- 保留作者、PR、commit reference，例如 (#12345) @author；若多条相关提交被合并，可把相近引用合并到同一项后括注。
+
+### 4. 正式版与 patch 版的历史连续性
+
+- 正式版严禁只留下单独的 patch 版本内容。
+- 如果目标正式版与已有正式版属于同一非 patch 版号，必须对比对应 tag 下的 changelog，并把当前新增改动追加到原有内容之后，保持版本历史连续。
+- patch 版详细区块只能写“自上一发布版本之后新增的变化”，不能把更早正式版已经出现过的条目整段复制到当前 patch 版本下面。
+- 例如生成 v6.10.4 时，v6.10.4 区块只能写 v6.10.3 之后的新变化；v6.10.0、v6.10.1、v6.10.2、v6.10.3 的既有内容应保留在历史区块，而不是重新抄进 v6.10.4。
+- 若非 patch 版本不同，则直接根据现有内容组织该版本及其历史区块。
+### 5. patch 版本的 Highlights 复用规则
+
+- patch 版本（例如 v6.10.4 相对于 v6.10.3）如果没有用户可感知的重要新功能或重大变化，必须直接复用其正式版父版本（v6.10.3）的 Highlights 内容，不得自行重写或另起一套。
+- patch 版本复用 Highlights 时，只改顶部版本号标题（例如 `## v6.10.3` → `## v6.10.4`），Highlights 正文原样保留。
+- 当 patch 版本确实包含用户可感知的重要新变化时（例如新增了重大功能、改变了核心交互），可以为 Highlights 追加新段落，但必须保留原有 Highlights 内容，新段落追加在末尾。
+
+### 6. patch 版本编辑的完整结构
+
+- 输出文件的结构必须严格遵循以下层次，不得把 patch 版本的详细内容插入到父版本的 Highlights 与详细内容之间：
+  1. 顶部：`## vX.Y.Z`（patch 版本标题）
+  2. `### Highlights`（复用父版本内容，或在有必要时追加新段落）
+  3. `----`
+  4. 英文 Highlights
+  5. `----`
+  6. `以下是详细内容：`
+  7. `## vX.Y.Z`（patch 版本详细内容：改进、修复、文档等）
+  8. `## vX.Y.Z-1`（上一 patch 版本的详细内容，不包含 Highlights）
+  9. 更早版本的详细内容...
+  10. `## vX.Y.0`（正式版详细内容，不包含 Highlights）
+- 父版本及更早 patch 版本的历史区块只保留详细内容（改进、修复等），不重复 Highlights、不重复"以下是详细内容："引导语，因为这些已经在最顶部出现过。
+
+### 5. Highlights 必须中英双语且先中后英
+
+- 输出顶部必须包含当前目标版本，例如 ## vX.Y.Z。
+- 必须包含 ### Highlights。
+- Highlights 必须先完整写中文小结，再使用 ---- 分隔，再完整写英文小结。
+- 中文与英文都应按主题分段，标题简洁明确，正文面向最终用户，不是 commit 列表翻译。
+- Highlights 只总结本次版本中最值得强调的变化，不要把所有条目机械搬进去。
+
+### 6. 必须过滤的噪音项
+
+- 删除或忽略纯 bot 自动生成的 changelog、update、release 条目。
+- 删除显式的 Release 发布记录，例如 Release vX.Y.Z。
+- 删除或忽略 Generate、Auto Update、Auto Generate、Update CHANGELOG、Bump version 之类自动维护条目。
+- 删除“只是在更新 changelog”而没有真实产品变更的提交记录。
+- 删除已被历史版本覆盖或重复搬运的旧条目。
+
+## Workflow
+
+1. 先确定本次发布边界：目标版本、上一版本、对应 tag、待发布 commit 范围。
+2. 读取现有 CHANGELOG 与目标范围内的 diff，不要只根据 commit 标题下结论。
+3. 先过滤 bot、release、generate、update changelog、revert、重复历史条目等噪音。
+4. 按“净变更”合并同类提交，必要时从 diff 改写标题。
+5. 按用户价值重新分类到正确模块，而不是沿用自动生成结果。
+6. 在每个模块内完成排序、术语统一与中英文条目整理。
+7. 编写中英双语 Highlights，先中文，后英文，中间用 ---- 分隔。
+8. 输出完整 Markdown 片段，包含顶部版本、Highlights、以下是详细内容：、当前版本区块与历史版本区块。
+
+## Common Failure Patterns To Correct
+
+- 把旧版本已有条目整段复制到当前 patch 版本。
+- 把 Revert 原样保留成单独 changelog 项。
+- 把 Release vX.Y.Z、Auto Update Changelogs、Update CHANGELOG、Bump version 之类自动提交写进文档或其他模块。
+- 把同一功能拆成多条重复表述，例如同一个生息演算功能拆成多个相近新增或改进条目。
+- 保留玩梗、口语化、半成品标题，例如不会现在还有人选沙中遗火吧、特意删的 PNS 怎么又给加回来了。
+- 机械沿用 commit type 导致分类错误，例如把用户能感知的修复放进其他，把兼容性提升放进新增。
+- patch 版本没有用户可感知的重要新变化，却自行重写了独立的 Highlights，而非复用父版本内容。
+- 把 patch 版本的详细内容插入到父版本的 Highlights 与详细内容之间，破坏了文件结构。
+- patch 版本的历史区块中重复保留了 Highlights 和"以下是详细内容："引导语，这些应只在顶部出现一次。
+
+## Output Requirements
+
+- 输出完整 Markdown 文件片段。
+- 顶部必须包含当前版本标题，例如 ## vX.Y.Z。
+- 顶部必须包含 ### Highlights，并满足先中文、后英文、用 ---- 分隔的格式。
+- Highlights 之后必须接“以下是详细内容：”或等价的历史区块引导语。
+- 详细内容中的模块标题统一使用以下格式：
+- ### 新增 | New
+- ### 改进 | Improved
+- ### 修复 | Fix
+- ### 文档 | Docs
+- ### 其他 | Other
+- 列表项统一使用 *。
+- 仅保留有内容的模块；空模块省略。
+
+## Output Template
+
+```
+## vX.Y.Z
+
+### Highlights
+
+#### 中文小结标题 A
+
+中文小结正文。
+
+#### 中文小结标题 B
+
+中文小结正文。
+
+----
+
+#### English Summary Title A
+
+English summary paragraph.
+
+#### English Summary Title B
+
+English summary paragraph.
+
+----
+
+以下是详细内容：
+
+## vX.Y.Z
+
+### 改进 | Improved
+
+* 条目 A (#12345) @author
+
+### 修复 | Fix
+
+* 条目 B @author
+
+### 文档 | Docs
+
+* 条目 C @author
+
+## vX.Y.1
+
+### 改进 | Improved
+
+* 历史版本条目 @author
+
+### 修复 | Fix
+
+* 历史版本条目 @author
+
+## vX.Y.0
+
+### 新增 | New
+
+* 正式版条目 @author
+
+### 改进 | Improved
+
+* 正式版条目 @author
+
+### 修复 | Fix
+
+* 正式版条目 @author
+```
+
+## Final Checklist
+
+- 是否只保留最终有效的净变更，而不是机械罗列 commit？
+- 是否已经删除 bot、Release、Generate、Update CHANGELOG、Revert 等噪音项？
+- 是否避免把旧版本已发布内容重复抄进当前 patch 版本？
+- 是否所有条目都能被最终用户独立理解？
+- 是否已经按模块正确分类、排序，并保持中文在前、英文在后？
+- 是否已经输出完整 Markdown，而不是说明文字或代码块？
+- 如果是 patch 版本且没有用户可感知的重要新变化，是否复用了父版本的 Highlights 而非自行重写？
+- patch 版本的详细内容是否紧跟在"以下是详细内容："之后，而非插入到父版本的 Highlights 下方？
+- 历史版本区块中是否只保留详细内容，没有重复 Highlights 和引导语？