walidboulanouar/vault-organizer

Vault Organizer

將雜亂無章的 Markdown 筆記儲存庫轉換為乾淨、相互連結、已索引的知識庫，讓 LLM（或團隊成員）可以快速從中檢索資訊。建立在 Karpathy 的原則之上： 像對待程式碼一樣對待知識。 原始資料是原始檔，編譯後的 Wiki 是建置輸出，INDEX 是綱要，而這個技能是編譯器加程式碼檢查工具。

模型（三層）

層級	內容	位置
RAW	未處理的：逐字稿、剪輯、轉儲、螢幕截圖	00_Inbox/raw/，最接近的主題資料夾
COMPILED	已合成的頁面，透過 [[wikilinks]] 交叉引用	PARA 資料夾（01_–04_）
SCHEMA	INDEX 檔案、CLAUDE.md、規則	每個資料夾的 INDEX.md 加上一個主索引

每個檔案都攜帶 type: frontmatter（raw | compiled | reference | framework | client | index）。 請參閱 references/standards.md 以取得 frontmatter 和 INDEX 範本。

工作流程

按順序執行。先審計並提出建議，再進行任何變更。未經確認，切勿刪除或移動。建議使用 git 儲存庫，以便變更可復原。

1. 審計（唯讀）

# 整個儲存庫：
python3 scripts/audit.py <vault_root> --stale-days 120 --report /tmp/vault-audit.md
# 單個子資料夾，但針對整個儲存庫解析 [[wikilinks]]（避免錯誤的「斷裂」標記）：
python3 scripts/audit.py <subfolder> --link-root <vault_root> --report /tmp/vault-audit.md

回傳一份健康狀態報告：缺少的 frontmatter、斷裂/缺少的 wikilinks、孤立頁面、缺少的 Related 章節、重複項目、過時檔案、沒有 INDEX 的資料夾。讀取報告後，向使用者顯示 摘要表格和主要問題。（使用 --json 輸出機器可讀的結果。）

2. 分類

將發現分組，並詢問現在要修復哪些問題，以及哪些問題可以稍後再處理。預設優先順序：

1. 沒有 INDEX 的資料夾（影響檢索）
2. 缺少 frontmatter（影響搜尋和屬性）
3. 斷裂的 wikilinks（影響關係圖譜）
4. 缺少 Related 章節和孤立頁面（影響探索）
5. 過時/重複項目（清理）

3. 清理（逐個檔案）

對於每個被標記的檔案：

• 新增 YAML frontmatter（title, type, source, author, created, description, tags）——從內容推斷，若未知則使用今天的日期作為 created。
• 在儲存庫中其他地方存在的任何概念、工具、人物或檔案首次被提及時，新增 [[wikilinks]]。
• 在底部新增一個 ## Related 章節，包含 3–8 個指向最具關聯性頁面的 [[wikilinks]]。同時將該檔案新增回其中 2–3 個頁面的 Related 中（雙向連結）。
• 修復斷裂的 wikilinks：重新指向正確的 slug，或者如果該目標值得以後撰寫，則保留為意圖性的樁（stub）。 使用 references/standards.md 中的範本。不要移除現有的 frontmatter 或連結。

4. 組織（先提議）

• 將歸檔錯誤的項目移動到正確的層級/資料夾（raw → 00_Inbox/raw/，compiled → PARA）。
• 將檔名標準化為 kebab-case；合併或重新命名重複項目。
• 保持移動規模小且可復原。列出每一次移動，並在執行前取得同意。

5. 註冊（交付物）

• 對於每個內容資料夾，產生或更新 INDEX.md：每個檔案一行指標 （- [[file-name]] — short hook），按類型分組，最新或最重要的優先。
• 建立/重新整理一個主索引（例如根目錄的 INDEX.md，或一個 meta/ 綱要資料夾）， 連結到每個資料夾的 INDEX。
• 這個註冊表是使檢索快速且可供團隊成員使用的關鍵。

6. 程式碼檢查（確認）

重新執行 audit.py。顯示處理前後的計數。當 frontmatter、 INDEX 覆蓋率和斷裂連結數都歸零時，儲存庫即為「乾淨」（孤立頁面/過時項目可能依選擇保留）。

分享給團隊成員

當目標是將整理好的儲存庫分享給團隊成員時：確保主 INDEX 是最新的，每個資料夾都有 自己的 INDEX，並且根目錄有一個簡短的 README.md，解釋三層模型及其導覽方式。 README 加主 INDEX 就是入口點。

規則

• 首先進行唯讀審計，始終如此。呈現，不要造成意外。
• 未經明確確認，切勿刪除或大量移動；建議先提交變更。
• 不要觸碰 .obsidian/、.git/ 或 Claude Code 配置（settings.json、hooks）。
• 符合儲存庫現有的慣例（此慣例為：PARA 加上 references/standards.md 中的標準）。
• 分批處理；每批處理後報告變更內容。

檔案

• scripts/audit.py — 唯讀掃描器，引擎。首先和最後執行它。
• references/standards.md — frontmatter 規格、類型分類法、INDEX 和 README 範本。