OpenClaw 更新日誌生成

OpenClaw 更新日誌生成 是做什麼的？

用於重新編寫更新日誌，並作為 GitHub 發布說明的原始文字。對於一般的 測試版/穩定版，請在最終原始碼資格認定（如可能的話）之前準備完整的說明；隨後程式碼 SHA 也可以是發布 SHA。編輯工作可能與程式碼驗證重疊。不要在每次驗證復原的回溯移植時重新執行；當回溯移植取代程式碼 SHA 時，在最終程式碼 SHA 變為綠色後，只重新執行一次，作為現有產品證據重用政策下一個真正的僅變更更新日誌的後代（時機）。對於延伸穩定版，在最終精確頭部驗證和標記之前執行。不要為工具重試、恢復發布或晉升而重新執行它。 與 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）和索引。初始生成保留以下章節格式。發布的文件鏡像遵循此技能末尾的獨立發布後路徑；初始生成絕不能覆蓋它們。

輸入

• 目標版本：對於測試版的差異更新，精確的 YYYY.M.PATCH-beta.N；對於累積的穩定版說明，則為 YYYY.M.PATCH。測試版條目和記錄是單獨的凍結產物，絕非穩定基礎章節的副本。
• 測試版基礎標籤：在發布之前，捕獲目前由公開 npm openclaw@beta 選擇的版本，而不是最後一個 GitHub 預發布版本或最高測試版後綴版本。選擇器可能命名一個也由 latest 選擇的穩定版本。使用精確的測試版版本時省略 --base（或使用 --base npm-beta）以解析一次；從生成的清單中保留解析出的標籤，並為編輯、驗證和恢復重用該顯式 --base。如果 npm 已經選擇了候選版本或更新版本，生成將拒絕猜測歷史選擇器狀態；請提供先前捕獲的標籤。當該標籤不是祖先（例如穩定的收尾向前移植）時，驗證器使用其可達的合併基礎，並通過 --shipped-ref 語義減去捕獲的已發送標籤的累積 PR 記錄。清單和記錄保留兩個邊界；使用捕獲的標籤重播以解析相同的範圍，永遠不要選擇較舊的 GitHub 測試版。
• 穩定基礎標籤：最後一個可達的已發送穩定發布標籤。它必須是目標的祖先；一個更新但不同的標籤不是有效的歷史邊界。僅在顯式的已發送/主分支收尾 SHA 也可從目標到達時才使用它。
• 目標參考：正在記錄的精確產品完成歷史。其貢獻記錄目標必須是最終發布目標的祖先；它不需要命名一個尚未創建的變更日誌提交。在最終確定說明之前包含任何後來的修復。最終說明可以在資格認定之前提交，或者之後作為綠色程式碼 SHA 的僅變更日誌後代提交。
• 規範主分支參考：在驗證之前獲取的當前 origin/main。當相同的工作由回溯移植攜帶時，發布說明引用原始的合併主分支 PR。僅在當前主分支上不存在向前移植時才使用發布分支 PR。

工作流程

1. 確認發布分支和精確的歷史目標：

   • git fetch --tags origin
   • 確認乾淨的 git status -sb
   • 記錄 git rev-parse HEAD 作為歷史目標
   • 當資格認定已存在時，記錄完整發布驗證運行 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
   

   對於測試版生成，使用 --version YYYY.M.PATCH-beta.N，並在第一次庫存運行時省略 --base。使用共享寫入器以「亮點」、「變更」和「修復」開始一個精確版本章節；生成差異清單，然後僅為該範圍編寫散文。後續運行使用捕獲的 npm 基線標籤（不僅僅是不同範圍的合併基礎 SHA）。發布後不要再次查詢 npm 或覆蓋累積的穩定條目。在穩定版本準備期間重新生成累積的穩定說明。

   當發布提交無法攜帶來源元數據時，添加可重複的 --release-provenance '<40sha> -> #PR[, #PR]' 輸入。這些使用與提交主體標記相同的精確標記語法和當前主分支驗證。

   驗證器自動在工作樹的 git 元數據下，從精確基礎/目標 SHA 快照重用公共 GitHub GraphQL 響應。相同目標的迭代重寫避免重複的網絡發現。在可疑的 API 數據後使用 --refresh-github-snapshot，使用 --github-snapshot <path> 指定顯式產物，或使用 --no-github-snapshot 進行僅實時審計。GitHub 發布正文始終進行實時讀取。 活躍原始碼中的顯式 CI #、CI run #、Actions run # 和 workflow run # 引用僅在 issue/PR 解析失敗且同一倉庫的即時 Actions 查詢確認了確切運行 ID 時才被單獨分類。該數字在活躍原始碼、說明或貢獻記錄中的任何普通出現仍然是嚴格的 issue/PR 要求。已確認的運行在驗證輸出和清單中顯示為 workflowRuns，從不作為 PR 關聯或貢獻者信用。 只有限於上下文提交主體文字、不存在於主題、結束引用、來源和說明/記錄中，且低於最高解析數字的 GitHub NOT_FOUND 引用可以被省略，並在清單中報告為 unavailableReferences，不給予信用。

   • 清單是重寫所需的輸入，而非事後審計；它包含每個引用的 PR、合格的貢獻者信用、內聯 issue 上下文、每個直接提交，以及 PR 和直接提交的編輯合格性分類
   • schema 版本 3 是所需的臨時清單契約。重新生成舊清單；版本 2 不是受支持的下游讀取器邊界
   • 對於歷史回溯填充，添加一次 --seed-ref <pre-backfill-ref>，以便即使舊的合併提交省略了其 PR 編號，也能保留來自先前變更日誌的貢獻記錄；驗證器排除在基礎標籤之後被還原的工作記錄，包括在穩定發布之前被還原的測試版工作
   • 生成的來源報告將範圍內 PR 與僅保留的種子 PR 分開，然後說明唯一的行總數。同時存在於兩個庫存中的 PR 計為範圍內；永遠不要將包含種子的總數描述為在當前發布範圍內合併的工作
   • 當可達的主分支收尾不同於已發送標籤或後來的向前移植提交重新關聯已發布的 PR 時，添加可重複的 --shipped-ref <prior-shipped-tag>。每個標籤是一個累積的已發送邊界：驗證器從編號發布章節中的完整貢獻記錄中聯集顯式 PR 行，僅排除重疊的 PR，並忽略 Unreleased。永遠不要從基礎 SHA、目標散文或目標記錄推斷此邊界。清單和生成的來源保留每個標籤以及確切的排除 PR 庫存和計數，以進行確定性候選驗證
   • 來源 PR 發現將 GitHub 提交關聯限制在所選的目標歷史，或規範載體的凍結主分支歷史。僅當其合併提交在目標歷史中可達且其合併時間在目標範圍內時，上下文來源引用才成為貢獻。保持所有引用可解析，但不要僅僅因為它們在發布準備繼續時合併就提升不相關的 PR。顯式種子保留其歷史成員資格，並且仍然是僅種子，除非獨立證明在範圍內。解析每個關聯頁面；現有的規範、揀選和來源契約仍然權威。
   • 顯式的多提交還原需要一個還原主體和一個獨立的 Reverts <full SHA> and <full SHA>. 聲明（逗號分隔列表，最後帶有 and 也可以）。接受確切的結尾 to restore the previous behavior.。重複、縮寫、嵌入或重複的聲明不能建立反轉。每個命名的提交必須是單親祖先，並且反向應用所有命名的補丁必須重現完整的還原樹。未能通過此證明的公認聲明會停止驗證。證明使用私有 Git 索引/對象存儲，沒有鉤子或外部差異；規範的單一還原和還原之還原會計保持不變。
   • 將回溯移植規範化為 main 上的原始合併 PR：顯式的揀選來源獲勝，然後唯一規範化主體匹配需要相同的作者和重疊的更改路徑。每當相應的主分支 PR 存在於當前 origin/main 上時，壓制發布/回溯移植 PR。僅當該更改首先登陸發布分支且尚未向前移植到 main 時，才保留發布分支 PR
   • 在編輯 ### Highlights、### Changes 或 ### Fixes 之前閱讀清單；不要在沒有重新審計的情況下向前攜帶舊的分組散文
   • 檢查鏈接的 PR/Issue 或差異以解決不明確的提交。直接提交是編輯輸入，而不是公共分類帳行；從主題、正文、觸碰的文件、測試和附近提交推斷材料使用者結果

4. 僅重寫一個選定的發布章節：

   • 測試版：## YYYY.M.PATCH-beta.N，僅包含自捕獲的 npm 測試版基線以來的更改
   • 穩定版：## YYYY.M.PATCH，自先前穩定版基線以來的累積更改
   • 不要在目標發布上方留下過時的 ## Unreleased 章節
   • 如果 Unreleased 包含發布範圍的說明，將它們折疊到目標章節中而不是刪除它們

5. 章節形狀：

   • ### Highlights：穩定版 5-8 條，測試版差異 0-8 條；不要為小的熱修復測試版發明亮點
     • 僅包括清晰的使用者可見功能或工作流程解鎖、重要的可靠性/安全性修復、廣泛的跨表面改進，或定義發布的整合/相容性里程碑
     • 每個亮點必須用一句話說明使用者發生了什麼變化；每條一個使用者故事並分組其支援的 PR
     • 排除測試、CI、重構、文件、目錄變動和實作細節，除非結果是重要的安裝/更新、數據安全或廣泛可見的使用者改進
   • ### Changes：新功能和行為更改
   • ### Fixes：首先使用者面向的修復，按影響和表面分組
   • 按表面和使用者影響分組相關的更改/修復；當幾個提交講述一個使用者面向的故事時，避免每個微小提交一個條目
   • ### Complete contribution record：分組散文之後生成的 PR 優先記錄；它是詳盡的會計表面，而不是第二個發布摘要

6. 保留歸屬：

   • 保留 #issue、(#PR)、Fixes #... 和 Thanks @...
   • 每個由使用者面向條目代表的人工作者合併 PR 需要其 PR 參考和 Thanks @author，即使該 PR 沒有鏈接的 issue
   • 每個由使用者面向條目代表的 Fixes #... 或引用的錯誤 issue 的人工 issue 報告者需要 Thanks @reporter，除非同一用戶名已在該條目中獲得感謝
   • 在代表的使用者面向工作上，每個人工 Co-authored-by 貢獻者（如果已知 GitHub 用戶名）需要 Thanks @handle
   • 當將多個 PR/Issue 分組到一個條目中時，包括每個相關的 PR/Issue 參考和每個人類

…

[為翻譯而截斷]