tderoussel/vault-doctor

Vault doctor

大多數 Obsidian 筆記庫沒有 git 也沒有復原機制，而且許多是透過 iCloud、OneDrive 或 Dropbox 即時同步的。將每次寫入都視為不可逆。在接觸任何內容之前，先確認筆記庫實際的備份狀況；在覆寫之前先讀取，偏好針對性編輯而非整份檔案重寫，並且絕對不要執行快速寫入循環——在同步的資料夾上，這會產生衝突副本。

掃描

走訪 .md 檔案，跳過 node_modules、.git、.obsidian 以及筆記庫中累積的任何建置或暫存目錄。從每一個檔案的基本名稱（包含附件，不僅是 .md）建立連結目標集合，然後提取 [[目標]]，去除 |別名、#標題 和 ^區塊 後綴。

記錄基準——筆記數量、不同的斷鏈目標、斷鏈引用總數、重複的基本名稱——以便後續執行可以顯示變化，而不是重複相同的普查。

在修復之前進行分類

原始的斷鏈計數並非缺陷清單。將每個命中結果歸入四個類別之一：

1. 跨系統引用——不要「修復」。 有些目標根本不是筆記庫中的筆記：代理記憶體 ID、工單金鑰，或其他工具中恰好使用 wikilink 語法編寫的識別碼。它們永遠無法解析。將它們轉換為純文字是合理的；但建立暫存筆記來滿足它們則不合理。

2. 斷鏈的文件記錄——永遠不要觸碰。 有些筆記故意引用一個斷鏈，作為範例或練習的真實情況（「如果你的工具找不到這個，那你的工具就錯了」）。編輯這些內容會破壞它們所教授的東西。以 prose 形式引用的 wikilink 語法也屬於同一類別。

3. 名稱漂移——修復目標，而非來源。 當許多引用指向一個短名稱，而筆記存檔在一個較長的名稱下時，優先考慮在目標的 frontmatter 中增加 aliases: [短名稱]，而不是編輯每個引用檔案。 一次編輯，一個原生 Obsidian 機制，沒有破壞周圍上下文的風險。

**4. 真正遺失的筆記。**目標從未存在過。報告它；不要自動建立。空的暫存筆記比斷鏈更糟糕，因為它看起來像是已回答了。

禁止尋找與取代

絕對不要使用無範圍的尋找與取代來修復連結。 在整個筆記庫中進行盲目取代，會破壞恰好包含搜尋字串的資料夾名稱、URL、程式碼區塊和標籤詞彙——而且由於沒有復原機制，損壞是永久的。逐檔修復，先讀取周圍的行。

其他檢查

• 重複的基本名稱會使連結在整個筆記庫中變得模糊，因為 Obsidian 會根據整個筆記庫的檔案名稱解析 [[連結]]。常見的罪魁禍首是存在於筆記庫中的程式碼專案或依賴樹，貢獻了數千個幽靈 .md 檔案。標記它；解決方法是將專案移出筆記庫或增加排除規則。未經詢問，不要刪除任何內容。

• Frontmatter 必須實際解析。 使用真正的 YAML 解析器處理每個區塊——不要用肉眼檢查。主要的失敗是未引用的純量包含 : （冒號空格），這會在那個字元處失敗，並將它下面的每個鍵都一起帶走，使整個區塊對 Obsidian 的屬性面板和 Dataview 都不可見。第二個常見的失敗：以 | 或 > 開頭的未引用值會開啟一個 YAML 區塊純量。

  修復意味著引用值，這在一個承載大量內容的筆記上可能會觸及數百個鍵——先提案，絕不擅自執行，而且要先備份檔案。在修復完成之前，請符合現有（已損壞）的慣例，而不是引入第二種風格；一個無效區塊中的孤立有效鍵毫無用處。

• 標籤應屬於 YAML 中的清單，而不是行內的主題標籤——根據筆記庫實際的詞彙進行檢查，而不是理想化的詞彙。報告漂移；不要單方面重新標籤。

• 過時的狀態——帶有 PAUSED/STALLED/TODO 標記的筆記，但其專案已經繼續推進。報告它們；不要自行解決。

• 冷卻的樞紐筆記——如果一個樞紐筆記最新的狀態區塊早於其專案的最新活動，則表示已過時。報告這個差距。

輸出

一份報告，按類別排序，包含計數和精確的 file:line 引用。提案修復；只執行使用者批准的修復。

清楚說明哪些發現是已驗證的，哪些是根據命名推斷的——一個看起來像漂移的目標，可能是使用者打算要寫的筆記。