Changelog

MAA Changelog Skill

读取待发布范围内的 commit、diff、现有 CHANGELOG 与 tag，输出可直接写入 CHANGELOG.md 的最终 Markdown。只输出最终 Markdown，不输出分析过程或代码围栏。

必要输入：目标版本号、提交范围（由 tag/PR/分支推导）、当前 CHANGELOG 内容。

⚠️ 版本号必须从用户/CI 提供的来源获取，禁止从 git tag 自行推测。 若获取新版本号失败，必须通过 PR URL（如 https://github.com/MaaAssistantArknights/MaaAssistantArknights/pull/17248）直接访问网页提取标题中的版本号，不得 fallback 到 git tag 推测。推测版本号会导致版本号全错（如 v6.14.0-beta.1 被错推为 v6.13.1-alpha.1），进而连锁触发折叠块处理错误。

1. 净变更优先

• 同一功能/问题的多条相关 commit 合并为单条，描述最终效果。
• 首次对用户可见的功能只留功能本体条目：功能在本版本第一次开放/出现时，其开发过程中的全部中间条目（内部修复、打磨、布局调整、参数默认值变化等）一律并入功能本体，只描述最终形态。用户没见过旧版本，｢修复 XX 功能的问题｣ 对他们无从谈起；逐条罗列只会稀释本体条目。注意区分：对已发布功能的修复仍照常写修复条目。
• commit 标题含糊/口语化时必须查看 diff 后改写为专业描述。作者刻意整活/玩梗的标题保留原文，仅在含糊到读者无法理解实际内容时括注补充（如 我是小猪（修正识别替换规则中半角括号的正则转义））；若玩梗提交与其余净变更同链、合并会洗掉原文，则该提交单列保留。
• Revert：完整撤销则删除；部分保留则合并为一条准确描述最终结果的条目。
• "review""typo""日志顺序""调整坐标""build warning" 等不单独保留，除非 diff 证明修复了用户可感知问题。
• 多服合并：按单项改动拆分（而非 commit/PR 整体），每项再跨服合并。服务器名用 / 连接（如 YostarEN/JP/KR），多位作者依次排列。
  • 示例：某 PR 为 JP 更新主题+新增章节导航，EN/KR 只更新主题 → 拆为 YostarEN/JP/KR 更新主题 + YostarJP 新增章节导航。

2. 分类

仅保留有内容的模块，空模块省略。

MaaMacGui 区块的判定：本地子模块目录 src/MaaMacGui 通常未 clone（空目录，git -C src/MaaMacGui log 不可用），且主仓库的 submodule 指针更新提交都带 [skip changelog]，看不出实际内容。判断版本范围内 MaaMacGui 是否有合并 PR，用 gh pr list --repo MaaAssistantArknights/MaaMacGui --state merged 按 mergedAt 对照版本 tag 日期，不要依赖本地子模块历史。

3. 排序与文案

• 中文在前，纯英文条目排最后；按重要性排序：功能/接口变更 > 兼容性/优化 > 次要修复/杂项。
• PC 端条目统一放所在分类的中文区末尾、其他语言条目之前（带 ｢PC 端｣ 前缀的直连/Win32 专属功能）：主流用户使用模拟器连接，PC 直连功能对他们不可用，靠后集中便于快速跳过；中文在前、其他语言在最后的规则优先级更高。
• 列表前缀统一 *；中英文与数字间留空格（如"修复 3 个 bug"）。
• 术语统一大小写：WPF、Json、Markdown、CSV、Info。
• 保留作者与 PR 引用，格式 ([#12345](https://github.com/MaaAssistantArknights/MaaAssistantArknights/pull/12345)) @author；多条合并时引用合并括注。
• 作者归属：从 commit 的 %an（author）字段获取，不要用 %cn（committer）——squash merge 的 committer 通常是 GitHub 或执行合并的人，而非贡献者。对于多贡献者 PR（squash 后协作者信息丢失），需访问 PR 页面确认发起人与协作者，全部列出（用空格分隔，如 @author1 @author2）。
• 显示名 → GitHub login 映射：条目里的 @作者 必须是 GitHub login，而 %an 给出的常是显示名。已确认的映射：墨染 → @moranfanhua、Ziyi Huang → @yali-hzy、uye → @ABA2396、status102 / Status102 → @status102、Rin → @ZiyinLin、HY → @momomochi987、H2O_MERO → @H2O-MERO、Zian Wen → @wzacolemak；Constrat、youzibigg 与 login 同名。表外名字用 gh pr view <N> --json author 核实；gh 间歇性 TLS handshake timeout 时，用 commit 的 %ae 邮箱前缀、Co-authored-by trailer、以及历史 CHANGELOG 中同一 PR 的既有归属相互印证。
• 条件生效的功能把限定写进条目：功能若依赖输入方式、截图方式、连接类型、服务器等条件才生效（如仅在 PC 端 win32 连接下生效、仅特定截图方式下行为不同），条目必须写明限定，不能只写笼统效果；拿不准时查 squash commit 信息与最终代码里的实际分支逻辑再落笔。
• 功能与机制名称用 UI 正式名称，不用开发者别称：条目里出现的功能名、界面项、游戏机制名，以本地化资源 key 的实际值或游戏内 UI 术语为准（如任务 OperProgress 的 UI 名是 ｢干员培养｣ 就不写 ｢培养计划｣；训练室协助专精的干员游戏内叫 ｢协助者｣，就不沿用代码注释/PR 描述里的 ｢导师｣｢助教｣）。拿不准时查 src/MaaWpfGui/Res/Localizations/zh-cn.xaml 或问作者，不从 Sourcery 总结、代码注释脑补。
• Sourcery 总结仅作线索，不作事实依据：PR body 里的 ｢## Sourcery 摘要 / Summary by Sourcery｣ 是低思考等级的 AI 生成内容，常见术语俗称、界面归属错乱、行为概括失真。它只用于快速定位 PR 改动范围；条目事实必须落到 diff、作者手写的 PR 正文、issue 标题或作者口述上，Sourcery 与 diff 冲突时一律以 diff 为准。

4. 版本历史与折叠块

版本类型：不带 -beta/-alpha 后缀为正式版（含首个 X.Y.0 与 patch X.Y.1+）；带后缀为测试版。

• 跨次版本号（正式版或新次版本的第一个测试版，如 v6.12.x → v6.13.0、v6.13.0 → v6.14.0-beta.1）：删除上一个次版本号的所有历史折叠块。
• 同次版本号内（patch、beta 之间）：当前版本用 <details open>，历史版本各自 <details> 收起，紧跟其后。
• 当前版本只写增量变化，不得复制更早版本已发布条目。
• 发布正式版时：将所有前置测试版条目按模块合并为正式版单一 <details open> 区块，跨测试版去重，只保留最终有效版本。其后不再保留 beta 折叠块（除非有更早正式版）。

正式版详细内容：合并已有测试版 changelog，禁止全量重分析

禁止在发布正式版时从 git 历史全量重新分析提交/阅读 diff。正式版详细内容直接合并已发布各测试版 changelog 的条目：

1. 读取同次版本号所有测试版区块（beta.1 … beta.N），按模块汇总去重——同一条目只保留最新表述，被覆盖的保留修正后结果。
2. 唯一增量：「最后一个测试版 tag → HEAD」的小段提交，逐一检查后补充（有用户可感知效果才补）。
3. 合并后统一排序、统一文案。

5. Highlights

• 中英双语，先中后英。中文直接展示，英文放入 <details><summary><b>English</b></summary> 折叠块。
• 累计性质：同一次版本号（X.Y.0）下，顶层 ### Highlights 是整个次版本号至今的累计亮点——应涵盖所有已发布测试版的亮点 + 当前增量，而非仅当前测试版的增量亮点。
• 精简原则：只保留最值得强调的变化（通常 3-4 条），不要机械搬运所有条目。宁可少不可多——同时出现 4 条以上说明没有做好筛选，需要合并同类项或删减次要条目。
• 新次版本的第一个测试版（如 v6.14.0-beta.1，跨次版本号）：前驱版本属于旧次版本号，所有旧历史折叠块已被删除，Highlights 从零编写（总结本提交范围内最值得强调的变化）。此时不存在可复用的前驱版本 Highlights。
• 同次版本号后续版本（patch、beta.2+、由测试版晋升的正式版）：相对直接前驱版本（patch 的父正式版 / 测试版的上一测试版 / 正式版晋升时的最后一个测试版）：
  • 无用户可感知重大变化 → 直接复用前驱版本 Highlights，仅改顶部版本号标题，不改写内容。
  • 有重大新变化 → 以前驱版本 Highlights 为基础，补充新亮点后重新审视、合并或替换。具体规则：
    1. 先完整保留前驱版本的所有段落。
    2. 判断新增内容是否值得进入 Highlights；值得的在末尾追加新段落。
    3. 追加后若总数偏多（通常 >4 条），逐条审视：可合并同类项，也可将前驱版本中相对凑数/次要的条目直接替换为更重要新亮点（替换 ≠ 整体丢弃，而是逐条权衡）。
    4. 绝对禁止整体丢弃前驱版本 curation——即不可仅保留当前版本增量亮点、删除全部前驱亮点。但逐条替换凑数条目是允许的。
• 由测试版晋升的正式版：判定基准是最后一个测试版。若最后一个测试版到正式版之间只有 CI、chore、内部维护等，Highlights 一字不改复用，只更新顶部版本号标题。
• 测试/实验性功能条目注明性质并引导反馈入口：标注 ｢测试功能｣ 并可能存在未发现问题时，附上反馈路径（中文 ｢设置 - 问题反馈｣、英文 Settings - Issue Report，以界面实际文案为准），避免用户遇到问题后到处询问。

6. 噪音过滤与内部内容收录

删除：bot 自动生成（Auto Update Game Resources、Auto Templates Optimization 及其附带的产物重生成）、Release vX.Y.Z、Auto Update/Generate Changelog、Update CHANGELOG、Bump version、带 [skip changelog] 标记的提交。

收录进 ｢其他 | Other｣：其余内部维护改动——工具链约定、工程化开关（如 TreatWarningsAsErrors）、开发规范更新、CI 依赖升级、构建/资源同步脚本机制、格式统一、版权年份等。两个受众分层：Highlights 是面向用户的精选层，从用户价值出发筛选；详细内容的读者也包括开发者与集成者，内部维护改动对他们有参考价值，按 Other 收录而不是按 ｢用户可感知性｣ 扔掉。仅真正的噪音（上述删除项）不入文档。

7. 翻译判断

判断依据是「该条目的目标读者是谁」。

用中文（默认）：国服（CN）、繁中服（txwy）、跨服/全服通用改动、行为描述（add support for X → 「新增支持 X」）、含糊/玩梗的英文 commit 标题改写。

整条保留英文——仅针对 YostarEN/JP/KR 等外服且不涉及国服的改动。整条描述（含动词）均保留英文，不要只保留专有名词而把描述译成中文。原因：外服条目目标读者是玩该外服的用户，能看懂英文；外服关卡/活动/主题名（如 lone trail、JieGarden）在中服可能不存在或译名不同，翻译会误导。

• ✅ YostarEN preload lone trail + fix JieGarden themes
• ❌ YostarEN/JP/KR 更新落叶逐火与界园主题（整条译成中文，且「落叶逐火」是中服译名）

混合：同一 commit/PR 同时含国服与外服改动 → 按 §1 拆为多条，国服用中文，外服保留英文。

代码/技术标识始终保留原文（不分中外服）：任务名（Stage、Roguelike、Depot）、配置项、接口名、文件名，以及 WPF、Json、Markdown、CSV、onnx、ADB、minitouch 等（大小写见 §3）。

8. git 历史编码（Windows PowerShell）

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; git -c core.quotepath=false -c i18n.logoutputencoding=utf-8 -c i18n.commitencoding=utf-8 log --encoding=utf-8 --format="%H %s" RANGE | ForEach-Object { [System.Text.Encoding]::UTF8.GetString([System.Text.Encoding]::Default.GetBytes($_)) }

如仍乱码：| Out-File -Encoding utf8 -FilePath "$env:TEMP\commits.txt" 后用 read_file 读取。