運作原理

三遍處理、社群偵測、信任標籤、token 經濟學——Graphify 是怎麼工作的

來源：docs/how-it-works.md

開場：一件事先講清楚

Graphify 之所以省 token，是因為「建一次圖，之後都讀圖」。建圖的第一次要花 token（文件那部分），之後每一次查詢都讀壓縮過的 graph.json，而不是掃原始檔。在一個 52 檔案的混合語料上，每次查詢比直接讀原始檔省 71.5 倍 token。

1. 三遍處理（The three passes）

Graphify 把輸入分成三類，用三種不同的方式處理：

Pass 1 — 程式碼結構（免費、不呼叫 API）

用 tree-sitter 在本機解析程式碼，抽出類別、函數、import、呼叫圖與行內註解。
全程沒有 LLM，支援 25+ 種語言（README 說是 36 種文法）。
SQL 檔特別處理：表格、view、外鍵、JOIN 關係都用確定性方式抽出。
如果語料只有程式碼，Pass 3 整個跳過——不需要 API key。

Pass 2 — 影音轉錄（本機、不呼叫 API）

影片與音訊用 faster-whisper 在本機轉錄。
轉錄 prompt 會用目前圖裡的 top god nodes 當種子，聚焦在你的領域。
轉錄有快取，重跑會跳過已處理的檔案。

Pass 3 — 文件、論文、圖片（Claude 子代理、花 token）

Claude 平行處理 markdown、PDF、圖片與轉錄稿。
每個子代理讀一批檔案，輸出一個 JSON fragment（nodes、edges、群組關係），最後合併成單一圖。
支援的 pointer/binary 格式會先轉成 graphify-out/converted/ 下的 Markdown sidecar（Office 檔用 [office] extra；Google Workspace 需 --google-workspace）。

展開英文原文：The three passes

**Pass 1 — Code structure (free, no API calls)**
Tree-sitter parses your code files and extracts classes, functions, imports,
call graphs, and inline comments. This runs locally with no LLM involved.
25 languages supported. SQL files get special treatment: tables, views,
foreign keys, and JOIN relationships are extracted deterministically.

**Pass 2 — Video and audio (local, no API calls)**
Video and audio files are transcribed with faster-whisper. Transcripts are
cached — re-runs skip already-processed files.

**Pass 3 — Docs, papers, images (Claude subagents, costs tokens)**
Claude runs in parallel over markdown, PDFs, images, and transcripts. Each
subagent reads a batch of files and outputs a JSON fragment: nodes, edges,
and any group relationships. The fragments are merged into a single graph.

2. 社群偵測（Leiden 演算法）

社群是用 Leiden 演算法找出來的——一種「把節點依邊密度分群」的圖分群方法。彼此連線很多的節點會落進同一個社群。

不需要 embedding。Claude 抽出的語意相似邊（semantically_similar_to）本來就在圖裡，直接影響社群形狀——圖的結構本身就是相似度訊號，沒有獨立的 embedding 步驟、也沒有向量資料庫。這是 Graphify「不是向量索引」的核心主張。

展開英文原文：How community detection works

Communities are found using the Leiden algorithm — a graph-clustering method
that groups nodes by edge density. Nodes with many connections between them
end up in the same community.

**No embeddings needed.** The semantic similarity edges that Claude extracts
(semantically_similar_to) are already in the graph, so they influence
community shape directly. The graph structure is the similarity signal —
there's no separate embedding step or vector database.

3. 信任標籤（Confidence tagging）

每一條關係都貼三種標籤之一：

標籤	意義
`EXTRACTED`	直接在原始碼找到（例如一個函數呼叫、一個 import）——confidence 固定 1.0
`INFERRED`	Claude 做的合理推論，帶 `confidence_score`（0.0–1.0）
`AMBIGUOUS`	不確定，在報告中標記供人工檢視

INFERRED 用離散級距：0.95 近乎確定（明確跨檔引用）→ 0.85 強證據 → 0.75 合理 → 0.65 弱 → 0.55 臆測。

展開英文原文：Confidence tagging

| Tag        | Meaning                                          |
|------------|--------------------------------------------------|
| EXTRACTED  | Found directly in the source (e.g. a call, import)|
| INFERRED   | A reasonable inference, with confidence_score      |
| AMBIGUOUS  | Uncertain — flagged in the report for review       |

EXTRACTED edges always have confidence 1.0. INFERRED edges use a discrete
rubric: 0.95 / 0.85 / 0.75 / 0.65 / 0.55.

4. Token 基準（Token benchmark）

省 token 的幅度取決於語料大小——圖越大，省得越多：

語料	檔案數	節省倍數
Karpathy repos + 論文 + 圖片	52	71.5×
graphify 源碼 + Transformer 論文	4	5.4×
httpx（合成 Python 函式庫）	6	~1×

6 個檔案還在 context window 內，圖的價值是「結構清晰」而不是「壓縮」；到 52 個檔案，省下的 token 就快速累積。repo 裡每個 worked/ 資料夾都有原始輸入與真實產出，可以自己跑來驗證。

5. 平行抽取與 SHA256 快取

平行抽取：程式碼檔用 ProcessPoolExecutor 平行抽取（繞過 GIL 的真多處理）；文件/論文/圖片用平行 Claude 子代理。84 個程式碼檔的語料，平行 AST 抽取比循序快約 1.66 倍。
SHA256 快取：每個抽取過的檔案用內容雜湊指紋。重跑時未變的檔案整個跳過，只重新抽取新增或修改的檔案。快取放在 graphify-out/cache/。

6. 圖的格式

輸出 graph.json 用 NetworkX 的 node-link 格式。每個節點有：

id — 穩定識別符
label — 人可讀名稱
file_type — code / document / paper / image / rationale
source_file — 來自哪個檔案

每條邊有：source、target、relation（動詞片語，如 calls、imports、semantically_similar_to）、confidence、confidence_score（僅 INFERRED）、source_file。連接 3+ 節點的群組關係（hyperedges）放在 G.graph["hyperedges"]。

展開英文原文：The graph format

The output graph.json uses NetworkX's node-link format. Each node has:
- id — stable identifier
- label — human-readable name
- file_type — code, document, paper, image, rationale
- source_file — where it came from

Each edge has:
- source, target — node IDs
- relation — verb phrase (e.g. calls, imports, implements, semantically_similar_to)
- confidence — EXTRACTED, INFERRED, or AMBIGUOUS
- confidence_score — float (INFERRED only)
- source_file — where the relationship was found

Hyperedges (group relationships connecting 3+ nodes) live in G.graph["hyperedges"].

一句話總結

本機確定性抽取（程式碼）＋可選 LLM 語意抽取（文件）→ 一張圖 → 用 query/path/explain 讀圖而非掃檔。程式碼永遠不離開你的機器；只有文件類語料會呼叫你設定的模型。

延伸：架構總覽 · 效能基準 · 概念地圖

教學解說

Graphify 的核心理念是「建一次圖，之後都讀圖」。三遍處理是理解整個系統的鑰匙：

Pass 1（AST）：tree-sitter 在本機解析，不需要 API key。這是「免費」的部分，處理所有程式碼檔案。
Pass 2（影音）：faster-whisper 本機轉錄，也不需要 API key。轉錄 prompt 會用目前圖的 top god nodes 當種子。
Pass 3（語意）：Claude 子代理處理文件/論文/圖片。這是唯一花 token 的部分。

社群偵測用 Leiden 演算法，不需要 embedding。信任標籤（EXTRACTED/INFERRED/AMBIGUOUS）讓你知道每一條關係的可信度。

Worked Example：觀察三遍處理的差異

純程式碼語料：用 httpx 案例（6 個 Python 檔），執行 graphify extract worked/httpx/raw。觀察輸出：Pass 1 處理所有檔案，Pass 3 被跳過，token cost = 0。
混合語料：用 mixed-corpus 案例（3 Python + 1 markdown + 1 圖片），執行 graphify extract worked/mixed-corpus/raw。觀察 Pass 3 被觸發，token cost > 0。
比較結果：查看兩份 GRAPH_REPORT.md，比較 nodes/edges 數量與社群分佈。

關鍵觀察：純程式碼語料的邊主要是 EXTRACTED（確定性），混合語料的邊有更多 INFERRED（語意推論）。信任標籤比例反映了語料類型。

常見錯誤與診斷

錯誤訊息	原因	解決方式
`faster-whisper not found`	未安裝影音轉錄依賴	執行 `pip install graphify[audio]`
`Pass 3: no LLM provider configured`	語料有文件但未設定 API key	設定 `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY` 環境變數
`Leiden: empty communities`	圖中沒有邊或節點太少	檢查 extract 階段是否正確產生 edges
`SHA256 cache: stale entries`	快取與實際檔案不同步	執行 `graphify extract --no-cache` 清除快取重跑

練習與驗收清單

[ ] 能解釋三遍處理（Pass 1/2/3）各自的職責與差異
[ ] 能說出哪些處理階段是「免費的」（不需要 API key）
[ ] 能解釋 Leiden 社群偵測如何運作，以及為什麼不需要 embedding
[ ] 能說明三種信任標籤的意義與 confidence score 的離散級距
[ ] 能比較不同大小語料的 token 節省倍數
[ ] 能解釋 SHA256 快取的運作原理與快取失效時機

① 進階真實情境 Worked Example：對 15 年歷史程式庫做「架構考古」

前面的 Worked Example 比較兩份語料的抽取差異；這次是同一份程式庫、時間軸上的差異：你要分析一個跑了 15 年的 ERP 系統（如 benchmarks 頁的 ERPNext 場景），回答「核心抽象這 15 年怎麼演化」。

多 checkpoint 建圖：對每週/每季的 checkout 各跑一次 graphify extract .（AST-only，零 LLM），產生多份 graph.json——15 年 × 52 週 = 780 份。
逐版分析：每份圖跑 graphify report 取 god nodes（Client、Request 這類核心抽象）與社群數。
跨版比較：用 graphify diff old-graph.json new-graph.json（graph_diff 的 CLI）看節點/邊的增減——「2020 年多了 payment 社群、2023 年 gateway 社群大漲」。
規模 vs 結構分開看：對照節點成長（7×）與邊成長（17×）——邊漲得比節點快，代表耦合度上升，這是純詞彙檢索看不到的訊號。
產出報告：把「關鍵里程碑 + god node 變遷」寫成架構演化 memo，進新人的 onboarding 文件。

為什麼選這條路徑：歷史性問題需要「可重現、可比較」的圖——AST-only 建圖零成本、確定性，讓 780 次建圖完全自動化；而 graph_diff 給的是「結構層的差異」，補足 git log 只有文字 diff 的盲點。這是把 graphify 從「單次快照工具」升級成「長期演進儀表板」的用法。

② 深入原理擴充：Leiden 社群偵測到底做了什麼、以及確定性從哪來

文裡說「Leiden 依邊密度分群」，但實作上「把社群偵測弄到可用」的是圍繞它的工程：

演算法：graspologic 的 leiden()（比 Louvain 多了 refinement phase，社群更凝聚）；缺套件時退回 networkx Louvain。
確定性：分群前先把節點/邊排序後重組成 stable 圖、固定 random_seed=42、trials=1——否則同樣的圖每次跑社群編號會亂跳。
實用化：hub 排除（超集線器不參與分群，避免把無關子系統拉進同群）、isolate 自成一群、過大社群（>25% 節點）與低凝聚力社群（<0.05 且 ≥50 節點）再拆分、社群依大小重新編號穩定 ID。
不需要 embedding 的真正含義：相似度訊號由 semantically_similar_to 邊承載（Claude 抽取），圖結構本身就是相似度——沒有向量資料庫，也無法做 cosine 檢索。社群形狀 = 「邊密度」，不是「向量距離」。

大家以為建圖正確、但其實有誤的案例：「不需要 embedding」常被誤解成「語意相似性偵測完全靠 LLM、與圖無關」。實際上社群形狀會被抽取品質綁定：如果語意子代理漏抽 semantically_similar_to 邊，或抽取的 relation 標錯，社群就會歪掉——而且歪得很自然，看不出來。最常見的案例是「兩個 repo 的 Block class 被分進不同社群」：這不是 bug，是「該邊的抽取沒成功或 confidence 太低」的結果。看到奇怪的社群分界，先查邊，再質疑演算法。

③ 診斷式疑難排解表

症狀	可能原因	解決方案
同一個 repo 重跑兩次，社群成員變了	分群輸入不確定（節點順序被 dict 順序影響）或隨機種子被改	確認走的 `_partition` 有排序重組 + seed 固定；不要手動改 `G.nodes()` 順序
整個 repo 幾乎一個大社群	檔案級 hub（如 CLAUDE.md 連到全部）把大家拉在一起	檢查是否有 doc-hub 節點；用 `exclude_hubs_percentile` 排除超集線器
社群數比上次少很多	抽取失敗導致邊變少（語意子代理超時、文件缺）	看 GRAPH_REPORT 的 EXTRACTED/INFERRED 比例；對比 token 統計，找出哪類檔案沒抽到
token 成本異常高	Pass 3 把不該送 LLM 的檔送出去（分類錯：如 `.apm.yml` 被當文件）	檢查 `classify_file` 結果；套件 manifest 應被導向 CODE
社群命名讀起來很怪	用了預設命名（最高度數成員），沒跑 LLM 命名	設定 LLM 後端跑 Step 5；或接受「預設名 = 結構真相」並手動覆寫

④ 進階挑戰題

圖的文宣宣稱「不需要 embedding、沒有向量資料庫」。請設計一個實驗證明這個宣稱的邊界——是否存在「圖檢索一定輸給向量檢索」的查詢類型？
Leiden 的 resolution 參數控制「傾向細分還是不分」。解釋調整 resolution 對「過大社群拆分」步驟的交互影響。
「邊漲得比節點快（17× vs 7×）」被解讀為耦合度上升。這個解讀忽略了哪個混淆因子（confounder）？如何設計對照才能確認是「真的耦合」而非「抽取變好」？

① 專案級端到端 Worked Example：混合語料知識庫——從三遍抽取到長期演進追蹤

前面的 Worked Example 比較兩份語料、做架構考古。這次是同一個專案的完整生命週期：你有一個 500 檔的混合語料（200 Python + 150 Markdown + 50 PDF + 60 SQL + 40 圖片），要從零建圖、跑多次增量、追蹤社群演化、最後產出一份「專案知識演進報告」。

首次建圖：graphify extract corpus/——Pass 1 處理 260 個程式碼/SQL 檔（零 LLM），Pass 2 跳過（無影音），Pass 3 處理 240 個文件/圖片（花 token）。記下 spend ledger 與 EXTRACTED/INFERRED 比例。
三次增量：每週修改 ~30 個檔案後跑 graphify extract corpus/——觀察 manifest.json 的 changed/cached 數字，確認增量模式生效。追蹤圖的 nodes/edges/社群數變化。
社群演化追蹤：每次建圖後記錄社群數與 god nodes——用 graphify report 取 god nodes 清單，比較三次增量後的變化。「核心抽象有沒有變？新增的社群代表什麼子系統？」
SQL 分析：把最終 graph.json 倒進 SQLite，跑「社群大小分佈」「EXTRACTED vs INFERRED 邊比例」「跨社群邊（import cycles）」查詢，產出一份「圖健康度儀表板」。
季度重建：graphify extract corpus/ --no-cache——全量重建消除增量累積的去重偏差，比較重建前後的圖差異。

關鍵觀察：混合語料的 INFERRED 邊比例會比純程式碼語料高得多——這是正常的。追蹤這個比例的變化比追蹤絕對數字更有意義：如果 INFERRED 比例突然升高，代表新增的文件語料抽取品質可能有問題。

② 效能/品質/安全深度

面向	考量	實務建議
效能	三遍處理中 Pass 3（LLM）是瓶頸；SHA256 快取在增量模式下跳過未變檔案	純程式碼語料完全跳過 Pass 3；用 `--code-only` 強制跳過；監控 `graphify-out/cache/` 大小避免快取膨脹
品質	Leiden 社群偵測的確定性依賴排序重組 + 固定 seed；語意抽取品質影響社群形狀	不要手動改 `G.nodes()` 順序；用 `graphify extract --verbose` 監控每檔案的抽取結果；定期跑 `graphify report` 檢查 god nodes
安全	Pass 3 的 LLM 處理攻擊者可控的文件內容	`<untrusted_source>` 雜湊戳記包覆 + `_neutralise_injection_sentinels()` 解除 jailbreak 記號；這是 table-stakes 防禦，不是無敵

③ 文件間比較對照表

面向	本文（運作原理）	相關文	差異說明
三遍處理	Pass 1/2/3 的概覽與 token 節省數字	架構總覽	架構頁列模組職責表，不深入三遍處理的內部機制
社群偵測	Leiden 演算法 + 確定性 + hub 排除	程式碼對照 · analysis	程式碼對照頁逐函數講 `_partition()`、`exclude_hubs_percentile`、relabel
信任標籤	EXTRACTED/INFERRED/AMBIGUOUS + 離散級距	增量更新	增量頁的去重步驟也使用信任標籤做合併決策
Token 經濟	省 token 倍數表（52 檔 71.5×）	效能基準	效能基準用 LOCOMO/LongMemEval 做跨系統比較；運作原理頁只做內部基準

④ 互動式檢核清單

- [ ] 能畫出三遍處理的流程圖，標出「哪些步驟花 LLM token、哪些不花」
- [ ] 能解釋為什麼「52 檔省 71.5×、6 檔只省 ~1×」——圖的壓縮效益與語料大小的關係
- [ ] 能手動計算一個 5 節點圖的 Leiden 分群結果（給定邊列表），並解釋 hub 排除的效果
- [ ] 能解釋 EXTRACTED 固定 1.0、INFERRED 用離散級距（0.95/0.85/0.75/0.65/0.55）的設計理由
- [ ] 能用 graphify extract --verbose 監控一次完整建圖的 Pass 1/2/3 分佈，並判斷哪個 Pass 是瓶頸
- [ ] 能解釋 SHA256 快取的失效條件（檔案內容變、prompt fingerprint 變、--no-cache）