文件腐化
以使用者的語言回答;保留技術術語、指令、路徑與檢查 ID 不動。
找出因時間推移而失效的文件內容。報告「已確認」的腐化內容;將僅是過時的內容歸類為「疑似」。
參數
- 範圍: 指定檔案(預設,若有提供)| 本次階段中被觸及的文件檔案 | 整個儲存庫的文件 —
.md/.mdx/.markdown/.rst/.txt/.adoc/.asciidoc/.org(若超過 20 個檔案,需先確認)。 - 層級: 快速 = 僅機械式年齡標記(幾乎免費)· 完整 = 語意層級過時判斷(需付費)。預設值取自
.coalledger.json的quickVsFull;完整模式始終需另行取得同意。
年齡標記(機械層級 — 確定性偵測)
| 標記 | 訊號 |
|---|---|
| 版本字串 | 文件提及的版本早於專案目前版本(根據版本的權威來源比對,例如 manifest) |
| 日期戳記 | 「最後更新」/應重新驗證日期/已驗證日期,距今過久或已過期 |
| 過時任務標記 | TODO / FIXME /「即將推出」/「尚未完成」,且無任何活動跡象 |
| 停用徽章 | 硬編碼的狀態/版本徽章,與儲存庫現狀矛盾 |
偵測是確定性的;但標記是否代表「腐化」則不一定是 — 歸檔文件上的舊日期無妨,安裝指南上的舊日期則有問題。
方法
- 快速: 依上表收集年齡標記。標記舊 ≠ 腐化:僅有標記歸類為「疑似」。
- 完整: 根據上下文判斷每個標記,並尋找「無日期」的過時內容 — 針對已變更的介面的操作說明、聲稱內容已被後續文件取代(文件間純粹的矛盾屬於文件一致性問題;腐化指的是時間軸上的問題)。
- 確認前需驗證: 僅當目前狀態與文件矛盾時(版本來源指出更新的版本;參照的介面已消失),才將發現歸類為「已確認」。任何推論而來的結果仍歸「疑似」。
- 根據上下文決定嚴重程度(絕非固定的對應表),然後遵循
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 提交問題,並附上使用者審閱過的摘要 — 絕不自動提交。