Vault Inspector
將 Vault Inspector 用作 Obsidian 筆記庫維護的唯讀品質檢查關卡。此技能適用於終端機、CI 以及由 AI 代理管理的筆記庫工作流程，這些場景需要找出斷開的連結、孤立附件、空白筆記、外部連結、重複檔案、frontmatter 型別不一致、標籤使用問題以及大型檔案。
安全規則
- 將 CLI 視為唯讀。此技能不得修改、移動、刪除或改寫筆記庫檔案。
- 請勿提拱
--fix作為可用選項。該 CLI 目前對於執行修復操作會以錯誤退出。 - 請勿自動刪除孤立附件、重複候選檔案或大型檔案。應總結證據並建議手動審查。
- 請勿將
title、message、generatedAt或durationMs視為穩定的自動化識別碼。 - 用於自動化的穩定欄位：
schemaVersion、toolVersion、summary、scannerId、severity、primaryPath、relatedPaths、evidence、fingerprint、fixAction、isNew以及summary.newIssues。 - 使用
--progress將掃描進度保留在 stderr；保持 stdout 為機器可讀格式。
何時執行
在以下情況執行 Vault Inspector：
- 重新組織、發佈、匯出或歸檔筆記庫之前；
- 在產生或由 AI 代理管理的筆記變更之後；
- 在對連結、標籤、frontmatter 或附件進行大量編輯前後；
- 在 CI 中，當筆記庫或產生的文件儲存庫需要進行迴歸檢查時；
- 當使用者要求筆記庫衛生檢查、斷連結分析、孤立檔案分析、重複檔案分析或大型檔案分析時。
基本指令
在筆記庫目錄內執行：
vinspect . --format json
如需一次性使用而不全域安裝：
npx vault-inspector /path/to/vault --format json
產生人類可讀的報告：
vinspect . --format markdown --output report.md
執行選定的掃描器：
vinspect . --scanner broken-links,empty-notes,large-files --format json
僅在網路檢查可接受時執行選擇性加入的外部連結掃描器：
vinspect . --scanner external-links --format json
顯示進度而不會破壞 stdout：
vinspect . --format json --progress
基準線工作流程
建立基準線：
vinspect . --format json --output .vault-inspector-baseline.json --fail-on none
僅在發現新問題時失敗：
vinspect . --baseline .vault-inspector-baseline.json --fail-on new --format json
使用基準線時，請檢查 summary.newIssues 以及每個問題的 isNew 欄位。先報告新問題，再報告已知問題。
退出碼
0：掃描完成，且未達到設定的--fail-on閾值。1：掃描完成，且達到了設定的--fail-on閾值。2：CLI 用法無效或掃描設定失敗。
如果退出碼為 2，請回報 CLI 錯誤，並且不要將 stdout 解釋為成功的掃描結果。
結果解讀
按以下優先順序處理發現事項：
error嚴重性的斷開連結和缺失的附件連結。warning嚴重性的發現事項，包括缺失的標題、大型檔案、已確認的重複檔案以及較舊的孤立附件。info嚴重性的發現事項，包括使用率低的標籤、跳過或超時的外部檢查、最近的孤立附件以及重複候選檔案。
每個摘要應包含：
- 問題總數；
- 按嚴重性分類的計數；
- 執行的掃描器；
- 首先列出高信賴度的問題；
- 需要手動審查的檔案路徑和證據；
- 資料可用時的基準線新問題計數。
避免過度確定。當檔案被 CSS、Canvas、Dataview、發佈管線或外部工具參照時，孤立附件和重複候選檔案可能為誤報。
建議的代理回應
在報告掃描結果時使用以下格式：
Vault Inspector 發現 <N> 個問題：<E> 個錯誤，<W> 個警告，<I> 個資訊。
最高優先順序的發現事項：
- [<嚴重性>] <scannerId>: <primaryPath> - <簡短的基於證據的說明>
備註：
- 如果相關，請提供 <基準線/新問題說明>
- 如果相關，請提供 <關於孤立/重複候選檔案的手動審查注意事項>
如果掃描通過，請陳述執行的指令以及相關的零計數。請勿聲明筆記庫是完美的，而應說明 Vault Inspector 在選定的掃描器和篩選條件下未發現任何問題。