loletranga/个人知识图谱

個人知識庫 × 知識圖譜（文件式，可迭代）

把一批 Markdown 文檔變成「可回憶、可追溯」的知識網絡：每篇文檔加一層 frontmatter 元數據，用三類關係連成圖譜，腳本重建蒸餾層（決策登記簿 + 圖譜鄰接表），供 Agent 在分析與決策前調取過往思路與歷史背景。

核心理念（先讀懂再動手）

1. 文檔本體是唯一事實源。圖譜不是獨立系統，frontmatter 和雙鏈就長在用戶的 md 檔案裡；graph/ 目錄是純生成物，刪掉可隨時重建。任何修改都只發生在源文檔上。
2. 寫入必須先確認。frontmatter 由你起草，但批量寫回前必須給用戶看樣本並確認；supersedes（誰推翻了誰）這類判斷性關係必須列清單確認，不允許靜默寫入。
3. 寧降級不硬寫。讀不出結論的文檔標 status: reference，不要編造 conclusion。一個錯誤的「一句話結論」會在決策時誤導用戶，比缺失危害大得多。

本技能目錄下有兩個隨行檔案（位於本 SKILL.md 所在目錄）：

• scripts/gen_kb_graph.py —— 圖譜生成腳本（純標準庫，離線可用）
• references/schema.md —— frontmatter 完整規範、三類邊語義、輸出模板、回憶輸出格式。首次建庫或對欄位拿不準時先讀它。

---

運行流程

第 0 步：確定範圍，向用戶說明將要發生什麼

• 用戶給的是資料夾 → 該資料夾即知識庫根目錄。
• 用戶給的是單個或幾個檔案 → 詢問：以這些檔案所在資料夾為知識庫根目錄（推薦，歷史文檔能互相連成圖譜），還是新建一個獨立知識庫資料夾存放它們。
• 用戶沒有任何檔案，想先建庫 → 走第 2 步「空庫骨架」。
• 開工前用兩三句話向用戶確認：根目錄是哪個、會修改哪些檔案（源文檔 frontmatter + 新增 graph/ 目錄）、不會動文檔正文。

第 1 步：檢測知識庫狀態

讀根目錄：

• 已存在 <根>/gen_kb_graph.py 或 <根>/graph/INDEX.md → 迭代模式（已有庫）
• 否則 → 建庫模式（新庫）

第 2 步 A：建庫模式（含空庫骨架）

1. 空庫骨架（用戶沒有歷史檔案時）：建立以下檔案後跳到第 3 步告知即可——
   • <根>/知識庫規範速覽.md：從 references/schema.md 摘取 frontmatter 模板與三條核心規則，方便用戶日常寫作時對照（自帶 status: reference）
   • <根>/模板-分析文檔.md：帶完整 frontmatter 的空白模板（同上自帶 frontmatter）
2. 安裝腳本：把技能目錄的 scripts/gen_kb_graph.py 複製為 <根>/gen_kb_graph.py（已存在則跳過）。裝進知識庫是為了它自包含——用戶或其他 Agent 不依賴本技能也能重建圖譜。
3. 試運行：python3 <根>/gen_kb_graph.py <根>。讀 <根>/graph/report.md 的總覽，向用戶報告規模（幾篇文檔、幾篇缺 frontmatter）。
4. 起草元數據（核心工作量）：先讀 references/schema.md，然後按子目錄或領域分批處理：
   • 逐篇讀文檔，起草 frontmatter：date（結論產生日）、domain、status（active/superseded/reference）、conclusion（一句話結論，只寫「這篇最終主張什麼」，不寫內容摘要）
   • 先給樣本：挑 2-3 篇有代表性的（一篇決策文檔、一篇資料），展示你將寫入的 frontmatter，用戶確認口徑後再批量
   • 識別演進關係：檔名含 v2/新版/副本/修訂、或內容上前後推翻的文檔對，建議 supersedes 指向，列成清單讓用戶確認後寫入
   • 每寫完一批報告進度；正文一個字都不動，只加 frontmatter
5. 重建與交付：重跑腳本（自動生成 graph/kb-graph.html 可視化頁面），向用戶展示 INDEX.md 的前幾行和 report.md 剩餘缺口，並告知可用瀏覽器打開 kb-graph.html 查看互動式圖譜。

第 2 步 B：迭代模式（已有庫）

1. 運行已有的 <根>/gen_kb_graph.py（不在了就從技能目錄重新複製）
2. 讀 graph/report.md，只處理增量：缺 frontmatter 的新文檔、缺 date/conclusion 的文檔、斷鏈。起草 → 確認 → 寫回
3. 語義邊補充：對新增文檔，通讀後提議它與既有文檔的 related（「同一件事的兩個側面」）和 supersedes（「這篇修正了那篇」），附一句話理由，確認後寫入
4. 重建（含 kb-graph.html 可視化頁面重新整理），向用戶報告變化量（新增節點/邊數、剩餘缺口）

第 3 步：告知用戶如何使用

每次建庫/迭代結束時，提示用戶今後這樣用（原話可參考）：

以後做分析或決策前，直接對我說：「回憶一下我之前關於 XX 的思路和結論」，我會檢索圖譜、順演進鏈核對時效後給你參考報告。想直觀看圖譜，用瀏覽器打開 graph/kb-graph.html 即可（可搜尋、篩選、點節點看詳情）。文檔繼續按老習慣寫，寫完說一聲「更新知識庫」即可，新文檔我會自動補元數據、連關係。

---

回憶模式（決策前檢索）

用戶要求回憶過往思路時，且目標目錄已有 graph/ 生成物，按此流程執行，全程唯讀：

1. 讀 graph/INDEX.md，用主題關鍵詞匹配文檔標題與結論，初篩相關項（寧多勿漏）
2. 需要擴展時讀 graph/GRAPH.md：順初篩文檔的 supersedes 演進鏈、related 鄰居補齊背景
3. 精讀相關文檔的 frontmatter 與結論段（不必全文通讀）
4. 按固定格式輸出（完整範例見 references/schema.md）：
   • 相關思路清單：每條 = 日期 | 一句話結論 | 狀態 | 文檔連結
   • 演進鏈：該問題上的思路變化軌跡，註明何時應什麼被推翻/修正
   • 對當前問題的參考點：哪些結論可直接沿用、哪些已過時須注意
   • 無先例聲明：若圖譜中查不到該問題的歷史決策，明確說「這是全新決策，無過往先例可依」——這同樣是有價值的輸出

---

與用戶的確認檢查點（必須停下來）

1. 建庫前：根目錄範圍、忽略規則（可用 <根>/.kbignore 排除目錄，每行一個通配）
2. 批量寫 frontmatter 前：2-3 篇樣本確認
3. 寫入 supersedes 關係前：成對清單確認
4. 任何正文內容的修改：預設禁止，用戶明確要求才做

腳本用法

python3 gen_kb_graph.py <知識庫根目錄> [--output graph] [--ignore "books,old,*_old"] [--no-html]

預設忽略：隱藏目錄、.venv、venv、node_modules、pycache、.git、輸出目錄自身。冪等，隨時可重跑；輸出 5 個檔案（INDEX.md / GRAPH.md / kb-graph.json / report.md / kb-graph.html），格式見 references/schema.md。kb-graph.html 是零依賴的單檔案可視化頁面（力導向圖譜 + 決策清單表格，支援搜尋/篩選/點擊詳情/雙擊開啟原始檔），環境允許可直接用瀏覽器打開向用戶展示。

升級邊界

文檔超過約 500 篇、GRAPH.md 無法一次讀完、或需要頻繁多跳推理時，檔案式圖譜到達上限，建議用戶遷移 LightRAG（圖譜+向量混合檢索）——frontmatter 與雙鏈就是最好的遷移語料，遷移無損。在那之前不要引入資料庫或外部服務。