发版 CHANGELOG 更新

适用范围

• 目标为库根目录（或子模块根目录）下的 CHANGELOG.md；若源码分布在多个子目录但共用同一份 CHANGELOG，则以该 CHANGELOG 所在目录为库根，git 范围覆盖所有属于该库的源码路径。
• 不得臆造版式：先 Read 目标文件顶部若干版本块，严格沿用该文件既有「Change Log」标题、下划线、Version 行、分隔线长度、条目前缀与历史语气。

文件版式（与现有一致）

Change Log
==========

Version <版本字符串> *(yyyy-MM-dd)*
----------------------------

* `[标签]` 中文说明（可含英文类名、方法名，与同文件历史条目一致）

• 标签：只使用该文件或同仓库其它 CHANGELOG 中已出现过的标签，例如 `[Add]`、`[Delete]`、`[Update]`、`[Refactor]`、`[Move]`、`[Feature]`、`[Build]`、`[Chore]`、`[Upgrade]`、`[Fix]`、`[Merge]`、`[Remove]`、`[Perf]`、`[Style]`、`[sync]` 等；禁止自造未在仓库中出现过的标签缩写。
• 一条一事：同类改动合并为一条；禁止把每个 commit 机械抄成一条；语义重复的条目合并后只保留一条表述。

新版本号

1. 默认以发版为准：新版本字符串以项目约定的发版版本源为准（如 Gradle/Maven/npm 等模块版本字段，与对外发布号一致）。用户或发版流程另有指定时以指定为准。
2. CHANGELOG 与发版配置不同步（例如 CHANGELOG 仍为 2.5.1-2 而版本配置已为 2.5.2）：写入 CHANGELOG 的 Version 必须与本次对外发布版本一致；若仅文档滞后，应对齐当前发版配置中的值并在同次提交中避免长期分叉。
3. 带连字符后缀的版本（如 2.5.1-2）：下一版以维护者与发版版本源为准，不臆造 semver；常见情况是下一正式补丁版为 2.5.2、2.5.3 等，以发版配置为准。
4. 日期：*(yyyy-MM-dd)* 使用写入当天（对话中 authoritative date）或用户指定的发版日。

变更时间窗与 git 范围

1. 时间基准：读取 CHANGELOG 最上方已发布版本的 Version … *(yyyy-MM-dd)*，取其中日期作为「上一版发布日」。
2. 收集区间：从该日期的 00:00 起至当前（以归纳时的仓库 HEAD 与对话日期为准），落在该库根目录下的改动；以 git 事实 为准，禁止写入未触及该路径的条目。
3. 当日边界：若上一版当日仍有后续提交、或与「更新 CHANGELOG 的 commit」重复，可改用 --after="yyyy-MM-dd" 或定位「写入上一版 CHANGELOG 的 commit」之后继续 git log，减少重复；默认 --since="yyyy-MM-dd" 与用户约定一致即可。

必须使用「完整」commit message（勿只看第一行）

禁止仅用 git log 的 subject（%s）作为唯一依据；正文（body）、多段落说明、列表同样参与归纳。

推荐在库根路径下执行（将日期、路径替换为实际值；PATH 为库目录，如 <库根>/）：

# 完整提交说明：%B = subject + body（含空行与多段）
git log --since="yyyy-MM-dd" --pretty=format:"%h%n%B%n----COMMIT----" -- PATH

# 需要作者日期辅助核对时（仍含完整 %B）
git log --since="yyyy-MM-dd" --pretty=format:"%h %ad%n%B%n----COMMIT----" --date=short -- PATH

• Merge commit：若 --no-merges 后信息量足够，可忽略 merge 噪声；若重要合并说明仅在 merge message 中，则保留并去重其与子提交的重复表述。
• 多路径库：-- 后写多个路径，或分路径 git log 后合并同一主题的 commit，条目仍按「一条一事」归纳。

归纳、去重与文案

1. 通读：按时间或逆序阅读每个 commit 的完整 %B（含 body、续行、列表）。
2. 去重：同一问题多次提交、revert 再修、相同类名/方法名反复出现 → 合并为一条用户向说明；忽略完全重复的句子或同一改动的 cherry-pick 副本。
3. 映射标签：按真实语义选 [Fix]/[Add]/[Refactor] 等，与同文件历史用法一致；不确定时优先与同库近期条目风格一致。
4. 专业准确：技术事实与类/方法/模块名与仓库一致；说明用简短中文，必要时保留英文标识符。
5. 插入位置：新版本块插在 ========== 之后、上一版 Version 块之前（全文从新到旧）。

变更很少或几乎无实质改动时

• 不得编造未发生的 API/功能说明。
• 参照该库 CHANGELOG 历史：许多子库在仅依赖升级或同步发版时会写 `[Chore]` 依赖 xxx 库同步升级（或对应依赖库名），句式与同文件历史保持一致。
• 若区间内确无落在该路径的提交：向用户说明「无新 commit 可记」；若发版流程仍需新版本号与日期，可仅更新 Version 行与一条与历史一致的 [Chore]（须与发版配置/实际依赖变更一致，不得虚构依赖升级）。

版本号来源（与库根对应）

1. 优先使用用户指定的版本字符串或发版版本配置文件中的对应模块字段（Gradle versionName/version、Maven version、npm version 等）。
2. 若用户未指明路径，在工作区内检索与目标模块/库名相关的版本声明（模块构建脚本、根版本清单、CI 发版变量等），不得臆造版本键名或版本号。
3. 写入 CHANGELOG 的 Version 必须与本次对外发布版本一致；多子模块各自 CHANGELOG 时，每条记录对其库根的版本源，勿混用其它模块版本。

执行清单

• Read 目标 CHANGELOG.md 顶部 2～3 个版本块，确认标题、标签、句式。
• 解析上一版 Version … *(yyyy-MM-dd)* 与即将写入的新版本（对照发版版本源或用户指定）。
• 对该库路径执行 git log，格式含完整 %B，必要时配合 git diff/git show 核对事实。
• 合并去重后撰写条目；少变更时对齐历史 [Chore] 等写法。
• 在文件顶部插入新版本块，不破坏下方历史结构。