openclaw-changelog-update

OpenClaw 更新日志更新

用于重写更新日志和编写 GitHub 发布说明源文本。对于常规 beta/stable，尽可能在最终源文本资格确认前准备完整说明；此时 Code SHA 也可以是 Release SHA。编辑工作可以与 Code 验证并行进行。验证恢复回移时不要重新运行；如果回移替换了 Code SHA，则在最终 Code SHA 通过验证后重新运行一次，作为真正的 CHANGELOG-only 后代，并遵循现有的产品证据复用政策（时间安排）。对于 extended-stable，在最终精确提交验证和打标签前运行。不要因工具重试、恢复发布或晋级而重新运行。 与 release-openclaw-maintainer 配合使用；此技能负责更新日志内容、排序、分组和署名规范。

目标

根据完整的生成历史清单，重建目标 CHANGELOG/<version>.md 发布章节，而不是沿用过时的草稿说明。生成按用户关注度排序的分组用户说明，同时保留所有相关 issue/PR 引用以及所有人工添加的 Thanks @... 致谢。

CHANGELOG.md 是生成的发布索引。共享所有者 scripts/lib/release-changelog.mjs 可从工作树或固定的 Git 引用解析发布章节和贡献记录，包括仍包含单体文件的历史引用。使用 node scripts/release-changelog.mjs read --version <version> [--ref <sha-or-tag>] 读取章节，或添加 --record 读取其贡献记录。缺失的拆分文件不得回退到根索引。没有记录的历史发布不得虚构来源信息。生成的 CHANGELOG/** 文件保留完全一致的迁移或镜像字节，并像根更新日志一样排除在通用格式化之外。通过其所有者使用 pnpm changelog:check 验证。

当前写入采用拆分布局。要保存完整的初始章节，请使用 node scripts/release-changelog.mjs write --version <version> --file <section.md>；它会同时更新发布条目、对应的 CHANGELOG/records/<version>.md（如存在）和索引。初始生成保留以下章节格式。已发布文档的镜像需遵循此技能末尾单独说明的发布后流程；初始生成绝不能覆盖这些镜像。

输入

• 目标版本：Beta 增量说明使用精确版本 YYYY.M.PATCH-beta.N；累计稳定版说明使用 YYYY.M.PATCH。 Beta 条目和记录是彼此独立的冻结产物，绝不是稳定版基准部分的副本。
• Beta 基准标签：发布前，记录公共 npm 上当前由 openclaw@beta 选中的版本，而不是最后一个 GitHub 预发布版本或 最高的带 Beta 后缀版本。该选择器也可能指向同时由 latest 选中的稳定版。 使用精确 Beta 版本时，省略 --base（或使用 --base npm-beta）以解析一次； 保留生成清单中解析出的标签，并在编辑、验证和恢复时复用该显式 --base。 如果 npm 已选中候选版本或更新版本，生成器会拒绝猜测历史选择器状态；请提供之前记录的标签。 如果该标签不是祖先（例如稳定版收尾的前向移植），验证器会使用其可达的合并基点， 并通过 --shipped-ref 语义减去已记录标签的累计 PR 记录。清单和记录会保留两个边界； 使用记录的标签重放以解析相同范围，绝不要改选更旧的 GitHub Beta 版本。
• 稳定版基准标签：最近一个可达的已发布稳定版标签。它必须是目标的祖先； 更新但分叉的标签不是有效的历史边界。仅当显式指定的已发布版本/主线收尾 SHA 也可从目标到达时，才可使用它。
• 目标引用：要记录的完整产品历史。其贡献记录目标必须是最终发布目标的祖先； 不必指向尚未创建的变更日志提交。定稿说明前，请纳入所有后续修复。最终说明可在资格验证前提交， 也可在通过验证的 Code SHA 之后，作为仅包含 CHANGELOG 的后续提交。
• 规范主线引用：当前的 origin/main，须在验证前获取。同一工作由回移植携带时，发布说明引用 原始合并到主线的 PR。只有当前主线上还没有前向移植时，才使用发布分支 PR。

工作流

1. 确认发布分支和精确历史目标：

   • git fetch --tags origin
   • 确认 git status -sb 工作区干净
   • 记录 git rev-parse HEAD 作为历史目标
   • 如果已有资格验证，记录 Full Release Validation 运行 ID 和尝试次数
   • 在冻结最终源之前完成待处理的产品/版本/回移植更改；实际更改后刷新清单

2. 审核历史，包括直接提交：

   • git log --topo-order --date=iso-strict --pretty=format:'%h%x09%ad%x09%s' <base-tag>..<target-ref>
   • git log --topo-order --grep='(#' --date=short --pretty=format:'%h%x09%ad%x09%s' <base-tag>..<target-ref>
   • 纳入目标可达但基准不可达的每个提交，包括已合并的旁支。先解析 PR 关联，再去重并减去已发布记录；保留现有的回退排除项。
   • 如果发布期间主线有更新，也检查 --since='24 hours ago'。

3. 撰写分组说明前，先生成完整的贡献记录和编辑清单：

   node --import tsx .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
     --base <base-tag> \
     --target <target-ref> \
     --main-ref origin/main \
     --version <YYYY.M.PATCH> \
     --manifest /tmp/openclaw-release-<YYYY.M.PATCH>.json \
     --write-ledger
   

   生成 Beta 版本时，使用 --version YYYY.M.PATCH-beta.N，并在首次清点时省略 --base。 使用共享写入器为精确版本的条目创建包含 Highlights、Changes 和 Fixes 的章节； 生成增量清单，然后仅为该范围撰写说明。后续运行使用记录的 npm 基准标签（而不只是分叉范围的合并基点 SHA）。 发布后不要再次查询 npm，也不要覆盖累计稳定版条目。准备稳定版时重新生成累计稳定版说明。

   如果发布提交无法携带来源元数据，可添加可重复的 --release-provenance '<40sha> -> #PR[, #PR]' 输入。 这些输入使用与提交正文标记相同的精确标记语法，并通过针对当前主线的验证。 验证器会在工作树的 Git 元数据下，自动复用来自精确 base/target SHA 快照的公开 GitHub GraphQL 响应。在同一 target 上反复改写可避免重复进行网络发现。遇到可疑的 API 数据时，使用 --refresh-github-snapshot；使用 --github-snapshot <path> 指定明确的制品，或使用 --no-github-snapshot 仅进行实时审计。GitHub 发布说明始终实时读取。 只有当 issue/PR 解析失败，且实时的同仓库 Actions 查询确认了确切的 run ID 时，活动源中的显式 CI #、CI run #、Actions run # 和 workflow run # 引用才会单独分类。活动源、备注或贡献记录中该数字的任何普通出现，仍须严格对应 issue/PR。已确认的运行会在验证输出和清单中显示为 workflowRuns，绝不会作为 PR 关联或贡献者致谢。 只有在上下文提交正文中出现、但未出现在主题、关闭引用、来源信息及备注/记录中的 GitHub NOT_FOUND 引用，且其编号低于最高已解析编号时，才可以省略，并在清单中报告为 unavailableReferences，不予致谢。

   • 清单是改写的必需输入，不是事后审计；它包含每个被引用的 PR、符合条件的贡献者致谢、行内 issue 上下文、每个直接提交，以及 PR 和直接提交的编辑资格分类
   • 架构版本 3 是必需的临时清单契约。请重新生成旧版清单；版本 2 不受下游读取器支持
   • 进行历史回填时，添加一次 --seed-ref <pre-backfill-ref>，以保留先前变更日志中的贡献记录，即使较早合并的提交遗漏了 PR 编号也不例外；验证器会排除在 base 标签之后被撤销的记录，包括在稳定版发布前被撤销的 beta 工作
   • 生成的来源报告会分别列出范围内 PR 和保留的仅种子 PR，然后说明唯一行总数。同时出现在两份清单中的 PR 计为范围内；绝不要将包含种子的总数描述为当前发布范围内合并的工作
   • 当可达的 main 收尾版本与已发布标签不一致，或后续前向移植提交重新关联了已发布的 PR 时，请添加可重复使用的 --shipped-ref <prior-shipped-tag>。每个标签都是累积的已发布边界：验证器会合并编号发布章节中完整贡献记录里的显式 PR 行，仅排除重叠 PR，并忽略 Unreleased。切勿根据 base SHA、target 文本或 target 记录推断此边界。清单和生成的来源信息会保留每个标签，以及精确的排除 PR 清单和数量，以便确定性地验证候选项
   • 源 PR 发现会将 GitHub 提交关联范围限制在所选 target 历史记录，或规范载体所用的冻结 main 历史记录内。只有当上下文源引用所对应的合并提交可在 target 历史记录中到达，且其合并时间位于 target 范围内时，该引用才会成为贡献。确保所有引用都可解析，但不要仅仅因为发布准备期间合并了无关 PR，就将其纳入。显式种子保留其历史成员资格，除非独立证明其处于范围内，否则仍仅作为种子。解析每一页关联数据；现有的规范、拣选提交和来源信息契约仍具权威性。
   • 显式的多提交撤销需要有撤销主题，以及一个独立成行的 Reverts <full SHA> and <full SHA>. 声明（以逗号分隔并在最后使用 and 的列表也有效）。末尾精确为 to restore the previous behavior. 的内容也可接受。重复、缩写、嵌入或重复出现的声明均不能证明撤销成立。每个指定提交都必须是单父提交祖先，并且反向应用所有指定补丁后必须还原完整的撤销树。识别出的声明若未能通过此证明，验证就会停止。证明过程使用私有 Git 索引/对象存储，不运行钩子或外部差异工具；规范的单次撤销和撤销的撤销计数方式保持不变。
   • 将回移植规范化为 main 上原始合并的 PR：首先采用显式的拣选来源；否则，唯一的规范化主题匹配还必须满足作者相同且更改路径有重叠。如果当前 origin/main 上存在对应的 main PR，则抑制发布分支/回移植 PR。只有当某项更改先合入发布分支、且尚未前向移植到 main 时，才保留发布分支 PR
   • 编辑 ### Highlights、### Changes 或 ### Fixes 之前，请先阅读清单；未经重新审计，不要沿用旧的分组文案
   • 对有歧义的提交，检查其关联 PR/issue 或差异。直接提交属于编辑素材，而非公开记录条目；请根据主题、正文、涉及文件、测试和相邻提交，推断对用户有实际影响的结果

4. 仅重写一个选定的版本章节：

   • beta：## YYYY.M.PATCH-beta.N，仅包含自记录的 npm beta 基线以来的变更
   • stable：## YYYY.M.PATCH，汇总自上一稳定版基线以来的所有变更
   • 不要在目标版本章节上方保留过时的 ## Unreleased 章节
   • 如果 Unreleased 中包含与版本发布相关的说明，将其并入目标 章节，不要删除

5. 章节结构：

   • ### Highlights：稳定版列出 5-8 条，beta 增量列出 0-8 条；小型热修复 beta 不要虚构亮点
     • 仅纳入明确面向用户的能力或工作流解锁、实质性的可靠性／安全修复、跨多个表面的广泛改进，或定义版本的集成／兼容性里程碑
     • 每条亮点都必须用一句话说明用户体验有何变化；每条只讲述一个用户故事，并将相关 PR 归为一组
     • 排除测试、CI、重构、文档、目录变动和实现细节，除非其结果对安装／更新、数据安全或广泛可见的用户体验有实质影响
   • ### Changes：新增能力和行为变更
   • ### Fixes：优先列出面向用户的修复，并按影响和涉及的表面归组
   • 按涉及的表面和用户影响归组相关变更／修复；当多个提交共同描述一个面向用户的故事时，避免每个细小提交单独列一条
   • ### Complete contribution record：在归组后的说明之后生成以 PR 为先的记录；这是详尽的核算部分，不是第二份版本摘要

6. 保留署名信息：

   • 保留 #issue、(#PR)、Fixes #... 和 Thanks @...
   • 每个由人工编写且已合并的 PR，只要出现在面向用户的条目中，就必须包含其 PR 引用和 Thanks @author，即使该 PR 没有关联 issue
   • 对于面向用户的条目中以 Fixes #... 或作为相关问题提及的 bug issue，每位人工报告者都需要获得 Thanks @reporter 致谢，除非该 bullet 中已致谢同一用户名
   • 对于所涉及面向用户的工作，所有已知 GitHub 用户名的人类 Co-authored-by 贡献者都需要获得 Thanks @handle 致谢
   • 将多个 PR／issue 合并到同一 bullet 时，在该 bullet 中包含所有相关 PR／issue 引用和所有人工贡献者用户名
   • 同一 bullet 中出现多个 Thanks @... 用户名是正常的；不要仅仅因为说明经过归组就删除或合并贡献者署名
   • 如果一个归组后的 bullet 同时涵盖直接提交和 PR，保留所有 PR 引用和致谢，并包含直接工作涉及的所有 issue 引用及人工署名
   • issue 仍以普通的行内 #NNN 引用形式呈现。不要另设关联 issue 清单。生成的 PR 记录在对应 PR 下以 Related #NNN 行内标注来源 issue
   • 回填较早版本中的关联 issue 清单时，对每一条经 GitHub 确认的关闭 PR 关联，均须保留行内报告者署名。不要根据普通交叉引用事件推断 PR 关联，不要为独立报告虚构无关的 PR 链接，也不要重建已废弃的清单
   • 完整贡献记录必须将所有经验证的范围内 PR 和明确保留的仅种子 PR 各列出一次，格式为 **PR #NNN**。发现流程须保留规范提交／cherry-pick 来源信息，并要求上下文引用属于冻结历史；仅有行内上下文不能创建贡献记录。保留作者／共同作者署名和原始标题中的所有 issue 引用
   • 来源数量计算和唯一总数必须与实际呈现的 PR 条目完全一致；候选验证会拒绝格式错误或伪造的计数
   • 清单中保留直接提交，并附带经 GitHub 核实的作者、共同作者、issue 和编辑资格信息。它们可用于归组后的说明，但绝不能以公开的 #### Direct commits 列表形式呈现。只有当直接提交与 PR 共享明确的关闭 issue 引用，或至少两个有辨识度的主题词时，才在归组后的 bullet 中添加直接提交署名
   • 验证器会拒绝在 Highlights、Changes 或 Fixes 中列出普通的 docs、test、refactor、ci、build、chore 和 style PR。明确的 Conventional Commits ! 标记会使任何类型具备编辑资格；应包含经验证的、面向用户的破坏性变更及迁移指南，并保留原始 PR 引用和署名。其他内部贡献只保留在完整 PR 记录中
   • 按声明的类型和范围对 Conventional Commits 标题分类，不要依据描述中偶然出现的 doc 或 build 等词分类。对于未声明类型的标题，保留 QA、test、docs、refactor、lint 或 CI 等内部工作信号；资格判定不能取代用于确认用户可见结果的源内容审查
   • 除非明确要求，否则不要在变更日志条目或 GitHub 版本发布说明中添加 GHSA 引用、安全公告 ID 或安全公告代号
   • 初始版本生成沿用现有署名政策：绝不致谢机器人、@claude、@codex、@openclaw、@clawsweeper 或 @steipete。另行批准的文档发布后 GitHub 正文应采用完整且经验证的人工贡献者名单，其中包括获得署名的 @steipete
   • 不要以 GitHub 的版本贡献者计数作为事实依据；变更日志本身必须包含完整的人工贡献者署名集合

7. 排序优先级：

   • 安全／数据丢失和内容边界修复
   • 对话记录／重放／回复投递正确性
   • 频道和移动端集成
   • 提供商／Codex／本地模型可靠性
   • 安装／更新／发布流程可靠性
   • 性能和可观测性
   • 文档和仅面向贡献者／内部的细节放在最后或省略

8. 除非现有文件风格要求，否则每条 bullet 保持单行。避免加入内部发布流程噪声，除非它会影响用户安装／更新安全。

9. 检查版本说明的附加条件：

   • 检查 src/plugins/compat/registry.ts
   • 检查 src/commands/doctor/shared/deprecation-compat.ts
   • 如果某条已弃用的兼容性记录已达到 removeAfter，在确认可安全移除后将其删除；否则将其移至 removal-pending 并记录阻碍因素。对于已到期的 removal-pending 记录，仅在满足其文档所列条件之前保留

10. 验证并发布：

• manifest 驱动的重写完成后，在提交前重新生成并验证完整的贡献记录：

  node --import tsx .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
    --base <base-tag> \
    --target <target-ref> \
    --main-ref origin/main \
    --version <YYYY.M.PATCH> \
    --manifest /tmp/openclaw-release-<YYYY.M.PATCH>.json \
    --write-ledger
  

• 当发布历史或渲染后的发布部分中的任何 #NNN 引用无法解析、已撤销的工作被列为已发布、源 PR 不在贡献记录中、直接提交被渲染成公开记录转储、非编辑类 PR 出现在分组说明中，或符合条件的 PR 作者或已知共同作者未出现在该 PR 的 Thanks @... 致谢中时，命令会失败。如果 --base 不是 --target 的祖先（beta 发布标签会规范化为 merge-base，并减去已发布记录的情况除外）、### Highlights 未符合所选 stable（5-8）或 beta（0-8）顶层项目符号数量限制，或现有说明/记录中提到了源范围之外的 PR，命令也会在收集历史记录前失败。只有显式指定 --seed-ref 才能添加历史 PR 清单；显式且可重复指定的 --shipped-ref 可减去经证实已存在于先前已发布标签中的 PR
• 分组说明提及某个 PR 时，该项目符号必须保留其生成的 PR 记录中的所有贡献者和关联报告者致谢
• 未限定的 #NNN 引用会解析到 openclaw/openclaw；openclaw/imsg#141 等跨仓库引用会保留为原文，不得改写为本地问题链接
• GitHub 发布或预发布上线后，根据同一源部分验证每个匹配的发布页面：

  node --import tsx .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
    --base <base-tag> \
    --target <target-ref> \
    --version <YYYY.M.PATCH> \
    --release-tag v<YYYY.M.PATCH> \
    --check-github
  

• 使用各 beta 页面的确切 beta 版本、已记录的 base 和 target 进行验证；stable 和 extended-stable 则使用各自的源部分和范围进行验证。切勿将多个 beta 页面与一个累计的 stable 部分进行比较。允许出现 ### Release verification 尾部；正文的其他差异均视为失败。
• scripts/render-github-release-notes.mts 是候选版本验证、发布和核验所用的规范发布正文渲染器。当所选版本的完整部分同时符合 GitHub 的 125,000 字符限制和渲染器匹配的 125,000 字节安全上限时，正文必须包含该完整部分，包括其标题
• 当完整源部分超出任一限制时，渲染器会保留截至 ### Complete contribution record 前一行的精确分组编辑说明，然后输出该标题，并附上指向标签固定版本的完整贡献记录的稳定链接，路径为 CHANGELOG/records/<version>.md（历史上的单体标签仍保留原始 CHANGELOG.md 记录链接）。 切勿截断项目符号或部分记录，也不得手工编写不同的精简版本
• 仅当 ### Release verification 可在规范的完整正文或精简正文之后放入时才追加。如果放不下，则省略正文尾部，并保留不可变的已附加发布证据；切勿仅为保留可选尾部而精简原本放得下的完整贡献记录
• pnpm release:candidate 会根据精确的 target 执行此确定性渲染检查，然后才会启动 Full Release Validation，即使明确跳过本地生成检查也不例外
• git diff --check
• pnpm changelog:check 会验证拆分后的索引、记录和带标记的文档镜像
• 对于仅涉及文档/变更日志的改动，不要求运行广泛测试
• 暂存目标发布条目、其生成的记录和已更改的索引；使用 git commit -m "docs(changelog): refresh YYYY.M.PATCH notes" 提交
• 推送发布分支，不要将其变基到持续变动的 main 上
• 如果所有修复和最终说明都在新一轮完整资格验证前提交，则将该提交同时记录为 Code SHA 和 Release SHA；两个角色使用同一个成功的完整父级/尝试及其精确发布字节
• 仅当 Code 资格验证后说明发生变化时，才要求 git diff --name-only <code-sha>..<release-sha> 包含 CHANGELOG/<version>.md，且仅包含该条目、对应记录和 CHANGELOG.md，之后才可选择使用 split-changelog-release-v1。允许新增或修改所选条目/记录；不允许重命名、删除、其他发布内容或文档源文件改动。历史上仅包含根目录文件的回执仍使用 changelog-only-release-v1。拆分路径保留绿色 Code 证明，并对新的 Release SHA 软件包字节进行资格验证。任何其他路径发生变化，都需要重新进行产品资格验证

发布后文档镜像

在明确批准文档发布后，在同一个源 PR 中发布已批准的文档源文件及其机械展平后的变更日志。 这与初始版本生成分开；不要在版本准备或发布期间自动进行编辑性改写。

将有序文档源文件渲染为一个完整的 Markdown 文件，即使版本较大或涵盖多个文档页面也如此：

pnpm changelog:from-docs --version YYYY.M.PATCH \
  --source docs/releases/YYYY.M.PATCH.md \
  --output CHANGELOG/YYYY.M.PATCH.md
pnpm changelog:check

对于包含多个部分的版本，按批准的阅读顺序重复使用 --source。转换器会移除展示用包装，将折叠面板标题转换为标题，展开文档链接，并保留源文本、署名、代码、表格和图片。不支持的标记会导致失败，而不会被静默丢弃。其首行标记会绑定有序源文件路径和精确的源文件摘要。检查只会将带标记的镜像与其源文件进行比较；未修改的历史原件会保留其初始格式。替换面向读者的文案时，请将 CHANGELOG/records/YYYY.M.PATCH.md 保留为冻结的记录凭据；文档源文件变更时，也要在同一个 PR 中重新生成镜像。

经批准的发布包会将源文件合并、已验证的文档部署，以及之后更新 GitHub Release 正文分别作为独立步骤记录。部署后，先重新读取现有 Release，再仅更新其正文，内容包括版本/统计数据、Raw 变更日志和文档链接、一份按字母顺序去重且经过验证的人类致谢名单，以及保持不变的版本验证部分。纳入经过验证的 PR、直接提交、共同作者和 issue 致谢，包括 @steipete；排除机器人。确保内容不超过 125,000 个字符和 125,000 字节，且不要截断致谢或证明材料。GitHub 负责原生头像和资源。验证正文回读结果，只继续未完成的步骤；绝不要重新打标签、重新构建、重新发布资源，或重新运行初始发布流程来替换此正文。初始历史验证器会拒绝文档镜像；请使用文档发布工作流进行验证。

Extended-Stable 变体

Extended-stable 只有一个发布提交和一个规范的 GitHub Release 正文。完成版本准备和已批准的回移植后，使用常规清单和原始主 PR 溯源规则重新生成 CHANGELOG/YYYY.M.P.md。通过 PR 合并，然后在打标签前验证最终分支头。发布收尾流程会将该标签所属的部分渲染到共享草稿中，随后由上级流水线发布非 Latest 版本页面。产品回移植后要重新审核；仅工具方面的修复无需添加变更日志条目。绝不要改写已发布的标签或变更日志。

配额 / API 中断规则

如果 GitHub API 配额耗尽，不要停滞不前。继续进行不需要 GitHub API 的工作：

• 本地重写变更日志并提取发布说明
• 本地打标签前检查以及软件包/构建健全性检查
• 通过 git 协议进行 git 推送/标签检查
• npm registry npm view 检查
• 准确准备工作流分发命令

只有创建 GitHub Release、分发工作流、轮询运行状态、下载构建产物，以及修改 issue/PR 需要 API 配额。