Knowledge Extraction Skill

Knowledge Extraction 是 graphify 最核心的能力。graphify 不是「LLM + Neo4j」這種傳統知識圖譜工具——它的提取分兩層：

1. AST 層（程式碼）：tree-sitter 本地解析 36+ 種程式語言，輸出六類邊關係。零 LLM、零 token、零網路。
2. LLM 語意層（非程式碼）：docs、PDF、圖片、video 才會用 LLM 提取 rationale / concept / 章節結構。

何時使用

✅ 適合的情境：

• 想理解一個 codebase 的結構（呼叫關係、import 鏈、繼承樹）
• 把 docs/ADR/PDF 整進同一個圖譜，讓助理回答「為什麼這樣設計」
• 處理大 monorepo（AST 層使得建圖即使在沒 API key 時也可跑）

❌ 不適合的情境：

• 已經有 graph database schema 等結構化資料
• 只想做 keyword 搜尋（用 grep 即可）
• 想用 embeddings 做 vector search（graphify 是 graph 不是 vector index）

程式碼：六類邊關係

graphify 對程式碼 AST 解析出六類邊：

每條邊都帶：

• source_file：來自哪個檔
• source_location：行號
• 信心標籤：EXTRACTED（原始碼直接出現）/ INFERRED（graphify 解析出來）/ AMBIGUOUS

提取流程

程式碼：tree-sitter 本地

graphify 對每個檔案：

1. 偵測副檔名（.py、.ts、.go、.rs 等 36+ 語法）
2. 用 tree-sitter 解析成 AST
3. 從 AST 抽取 symbols（function / class / method）與 references
4. 跨檔案解析 references → 變成 calls / imports / inherits 邊
5. 標 EXTRACTED（直接命中）或 INFERRED（解析後才知道）

過程完全本地，不發任何網路請求。

提取行為修正（v0.9.42 / v0.9.43）

• JS/TS for...of / for...in loop binding 會被 shadow，不再產生假的 indirect_call 邊（v0.9.42，#2685）。
• Python 相對子套件 import（from ..pkg.sub import x）解析到套件 __init__；tree 中的 FIFO/device 等 non-regular file 直接跳過，不再卡住 extraction（v0.9.42）。
• 巢狀具名 function declaration 會建立 node 且呼叫可解析；跨檔 INFERRED uses 邊只綁到真正參考 import 的 symbol（v0.9.43，#2653/#2652）。
• v0.9.43 新增 OCaml（.ml / .mli）tree-sitter 提取，需安裝 optional [ocaml] extra。

非程式碼：LLM 語意層

對 .md、.pdf、.png、.mp4 等：

1. chunking
2. 呼叫 LLM backend（你自己 IDE session 的 model，或 --backend claude/openai/gemini/kimi/ollama/bedrock）
3. 提取 concept、rationale、document、paper、image 節點
4. 與程式碼節點用 references 連結

⚠️ graphify 不會把所有內容都丟給 LLM。code 用 AST，只有 non-code 才 LLM。

排除 / 包含控制

.graphifyignore

node_modules/
dist/
*.generated.ts
!src/**

跟 .gitignore 語法 100% 相同。

--no-gitignore

graphify extract . --no-gitignore

把 .gitignore 排除的 generated code 納入圖譜，但 .graphifyignore 與敏感檔過濾仍生效。

--code-only

graphify extract . --code-only

只 AST，不呼叫 LLM。CI / 大 monorepo 友善。

敏感檔自動過濾

.ssh、.aws、.gnupg 等會自動排除；ambiguous secrets/、credentials/ 目錄保留程式碼但 drop 資料檔。¹

品質旗標

graphify 對未驗證節點會標 verification: "unverified"（v0.9.18+），這些是 LLM surface 但 source 沒明確對應的節點。可用 graphify diagnose 檢視。

範例

# 純 AST 建圖
graphify extract . --code-only

# 深度 + Gemini backend
graphify extract . --mode deep --backend gemini

# 跳過 docs，觀察 graph node 數變化
jq '.nodes | length' graphify-out/graph.json
# 加 docs 前：1200（純 code）
# 加 docs 後：1850（多了 rationale / concept）

內部連結

• graphify build 指令詳解
• Semantic Query Skill
• Source Tracking Skill

下一步

1. Semantic Query Skill：自然語言查詢機制
2. Source Tracking Skill：每個節點的來源追溯
3. graphify build 指令詳解