发布变更日志自动化生成技能

1. 历史清单生成（Manifest Generation）

技能通过 verify-release-notes.mjs 脚本，基于 --base（上一个已发布的 tag）、--target（当前发布的 ref）和 --main-ref（origin/main）生成完整的贡献记录清单：

• 清单包含每个被引用的 PR、符合条件的贡献者署名、内联 Issue 上下文、每个直接提交（direct commit）以及 PR/直接提交的编辑资格分类。

• 验证器会自动复用 GitHub GraphQL 响应，同一目标的迭代重写可避免重复的网络发现。

2. 分组变更日志重写

技能按以下结构重写一个版本章节（## YYYY.M.PATCH）：

• 相关变更/修复按表面和用户影响分组，避免为每个小提交单独列一条。

• 直接提交是编辑输入，而非公共记录行——从提交信息、变更文件、测试和相邻提交中推断对用户的影响。

3. 贡献者归属自动保留

技能强制保留所有人工贡献者的署名：

• 每个面向用户的 PR 必须包含 PR 引用和 Thanks @作者

• 每个被 Fixes #... 引用的 Issue 报告者必须被感谢（除非已在同一条目中感谢）

• 每个 Co-authored-by 贡献者必须被感谢

• 多条 Thanks @... 在同一条目中是预期的，不能省略或折叠

• 绝不感谢机器人（如 @claude、@openclaw、@clawsweeper、@steipete）

4. 自动验证与检查

verify-release-notes.mjs 脚本会在提交前执行多项验证：

• 任何 #NNN 引用必须能解析

• 已回退的工作不能呈现为已发布

• 源 PR 必须出现在贡献记录中

• 直接提交不能以公共记录转储形式呈现

• 非编辑性 PR 不能出现在分组正文中

• 符合条件的 PR 作者/共同作者必须在 Thanks 中被提及

• ### Highlights 必须包含 5-8 条顶级要点

• --base 必须是 --target 的祖先

5. GitHub Release 正文渲染与校验

• scripts/render-github-release-notes.mjs 是规范的 release body 渲染器

• 当完整章节不超过 GitHub 的 125,000 字符限制时，body 必须包含该完整章节

• 超限时，保留完整的编辑笔记至 ### Complete contribution record 之前，然后输出该标题并链接到 tag 固定的 CHANGELOG.md

• 绝不截断任何条目或部分记录，也绝不手写不同的精简形式

三、主要用途

1. 发布前的变更日志生成
   在每次 beta 版、稳定版发布或重新发布之前，强制使用此技能重新生成变更日志。它确保发布说明基于完整的 Git 历史，而非过时的手写草稿。

2. 回溯移植（Backport）的 PR 规范化

   • 显式 cherry-pick 来源优先，然后是唯一规范化主题匹配（要求相同作者和重叠的变更路径）

   • 当对应 main PR 存在于当前 origin/main 时，抑制 release/backport PR

   • 仅当变更首先落地 release 分支且尚未被 forward-port 到 main 时，才保留 release-branch PR

3. 发布后校验
   GitHub release 或 prerelease 发布后，使用 --release-tag 和 --check-github 验证每个匹配的 release 页面与源章节一致

4. API 配额耗尽时的降级工作
   当 GitHub API 配额耗尽时，不闲置等待，继续执行不依赖 GitHub API 的工作：

   • 本地 changelog 重写和 release-note 提取

   • 本地 pretag 检查和包/构建健全性检查

   • git push/tag 检查

   • npm registry 检查

   • workflow-dispatch 命令准备

四、标准工作流程

1. git fetch --tags origin && git pull --ff-only
2. git log 审核历史（含直接提交）
3. node verify-release-notes.mjs --base <tag> --target <ref> --version <ver> --manifest <json>
4. 基于清单重写 CHANGELOG.md 的对应版本章节
5. node verify-release-notes.mjs --write-ledger（再次验证）
6. git diff --check
7. scripts/committer "docs(changelog): refresh YYYY.M.PATCH notes" CHANGELOG.md
8. git push，然后从最新 main 分支/rebase release
9. 发布后：node verify-release-notes.mjs --release-tag v<ver> --check-github

五、重要原则与注意事项

1. 清单是重写的必要输入：清单在重写之前生成，包含所有 PR、贡献者信用、Issue 上下文和编辑资格分类，而非事后审计。

2. 不要携带旧的正文：在编辑前读取清单，不要将旧的分组正文未经重新审计就向前携带。

3. 不要创建 beta 专属标题：重写一个稳定版章节（## YYYY.M.PATCH），不创建 beta 专属标题。

4. Unreleased 处理：如果 ## Unreleased 包含发布相关笔记，将其合并到目标章节而非删除。

5. 排除内部工作：docs、test、refactor、ci、build、chore、style 类 PR 不出现在 Highlights/Changes/Fixes 中。

6. 不要添加 GHSA 引用：除非明确要求，否则不添加安全公告 ID 或 advisory slugs。

7. 跨仓库引用保持不变：如 openclaw/imsg#141 保持字面文本，不重写为本地 Issue 链接。

六、总结

OpenClaw Changelog Update 是一个发布流程强制性的变更日志自动化技能，通过从 Git 历史生成完整的贡献清单，自动重写结构化的、面向用户的发布说明，并严格保留每位人工贡献者的署名。它适用于 OpenClaw 项目的 beta/stable 发布周期，确保变更日志的完整性、准确性和一致性，同时通过自动验证机制防止格式错误、归属遗漏和引用解析失败等问题。