changelog

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 和引导语？