Communitygithub.com

TheColliery/CoalLedger

文件健康度監控套件,適用於 AI 編碼代理。透過 6+1 個金絲雀檢查器,偵測文件中的腐化內容;選擇性修復,絕不自動套用。

CoalLedger 是什麼?

CoalLedger 是 TheColliery 專案中的文件健康度監控套件,專為 AI 編碼代理(如 Claude Code、Cursor 等)設計。它透過 6+1 個「金絲雀檢查器」來偵測文件中的腐化內容,採用零依賴的 CommonMark + GFM AST 引擎分析文件結構,根據上下文判斷嚴重程度,並提供選擇性的修復建議,絕不自動套用。當文件變更但 MEMORY.md 未更新時,它也會悄悄提示。支援 .md、.mdx、.markdown、.rst、.txt、.adoc、.asciidoc、.org 等格式。核心功能包括:版本字串、日期戳記、過時任務標記、停用徽章等機械式年齡標記的偵測;Quick 模式(僅機械標記,成本低廉)與 Full 模式(語意判斷,需付費)。最終報告僅列出 CONFIRMED 腐化,SUSPECTED 項目則以獨立清單呈現。修復模式需使用者確認,且僅限於安全修復(更新明確的值)。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add TheColliery/CoalLedger

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

文件腐化

以使用者的語言回答;保留技術術語、指令、路徑與檢查 ID 不動。

找出因時間推移而失效的文件內容。報告「已確認」的腐化內容;將僅是過時的內容歸類為「疑似」。

參數

  • 範圍: 指定檔案(預設,若有提供)| 本次階段中被觸及的文件檔案 | 整個儲存庫的文件 — .md/.mdx/.markdown/.rst/.txt/.adoc/.asciidoc/.org(若超過 20 個檔案,需先確認)。
  • 層級: 快速 = 僅機械式年齡標記(幾乎免費)· 完整 = 語意層級過時判斷(需付費)。預設值取自 .coalledger.json 的 quickVsFull;完整模式始終需另行取得同意。

年齡標記(機械層級 — 確定性偵測)

標記訊號
版本字串文件提及的版本早於專案目前版本(根據版本的權威來源比對,例如 manifest)
日期戳記「最後更新」/應重新驗證日期/已驗證日期,距今過久或已過期
過時任務標記TODO / FIXME /「即將推出」/「尚未完成」,且無任何活動跡象
停用徽章硬編碼的狀態/版本徽章,與儲存庫現狀矛盾

偵測是確定性的;但標記是否代表「腐化」則不一定是 — 歸檔文件上的舊日期無妨,安裝指南上的舊日期則有問題。

方法

  1. 快速: 依上表收集年齡標記。標記舊 ≠ 腐化:僅有標記歸類為「疑似」。
  2. 完整: 根據上下文判斷每個標記,並尋找「無日期」的過時內容 — 針對已變更的介面的操作說明、聲稱內容已被後續文件取代(文件間純粹的矛盾屬於文件一致性問題;腐化指的是時間軸上的問題)。
  3. 確認前需驗證: 僅當目前狀態與文件矛盾時(版本來源指出更新的版本;參照的介面已消失),才將發現歸類為「已確認」。任何推論而來的結果仍歸「疑似」。
  4. 根據上下文決定嚴重程度(絕非固定的對應表),然後遵循 severityFloor:腐化的安裝/安全步驟(讀者會遵循)為「高-嚴重」;過時的徽章或版本提及為「中」;歸檔文件中的舊日期為「低」。

升級邊界

某一主張是否曾經為真,是「文件基礎」的職責;高風險主張的形式驗證需升級到 CoalBoard(/coalboard,若該技能已安裝)。此金絲雀僅回答「時間是否已破壞它」。

輸出格式

| # | 路徑:行號 | 標記 | 證據(目前狀態) | 嚴重程度 | 修復 |

僅顯示「已確認」表格;「疑似」(僅是過時但未證實)作為獨立清單呈現,絕不放入主表格。

報告: 若可呼叫 ReportFindings,則使用 — file/line 必須是標記本身所在的行號,不得改寫;若行號無法確定,則提供最佳猜測,並在總結中標示為不精確,絕不捨棄。嚴重程度在 summary 中加上前綴(例如 [HIGH] …),依照上述的「根據上下文決定嚴重程度」規則,依嚴重程度最高者優先排序,SUSPECTED(僅是過時但未證實)的 verdict 為 PLAUSIBLE;後續對話僅包含總結行(數量 · SUSPECTED 清單 · 超過 32 項的溢位項目)+ 修復選單,絕不重述。若無法呼叫,則維持上方表格不變。點擊「套用修復」即表示同意以下「套用安全修復」類別(僅針對明確的當前值更新),會與修復模式組合使用,絕不繞過。在任一輪修復後,以 outcome: fixed/skipped/no_change_needed 針對相同的發現重新報告。

修復模式(需使用者選擇)

在互動階段中進行任何報告後,你必須透過提問工具呈現此選單(僅在無發現或無使用者存在時跳過)。絕不自動修復上線文件。

  • 套用安全修復: 僅更新當前值明確無歧義的項目(將版本字串更新為 manifest 中的版本、在使用者確認後重新整理日期、在使用者確認後刪除已過時的 TODO)。每個修復:建立檢查點(在 git 儲存庫中執行 git stash/commit;否則先複製檔案備份 — 絕不假設 git 存在)-> 套用 -> 重新讀取已變更的行。
  • 讓我挑選: 列出發現;由使用者選擇。
  • 僅報告: 退出,文件保持不變。

絕不自動修復:改寫已被取代的操作說明(涉及內容決策)、刪除段落、任何你未驗證當前真實性的項目。

多語言

年齡標記與語言無關(版本、日期和徽章在任何散文語言中看起來都一樣;日期格式則會變化 — 根據結構解析,而非仰賴英文月份名稱)。語言處理不佳時,語意判斷會降級為低可信度標記,絕不產生誤報。

問題回報

若此金絲雀行為異常,提供選項讓使用者前往 https://github.com/TheColliery/CoalLedger/issues 提交問題,並附上使用者審閱過的摘要 — 絕不自動提交。

相關技能