← 回首頁

程式碼對照

/graphify 主程式、/tools、/scripts、/tests 逐函數講解——中文解說配英文原始碼

這區是本站最深的章節。每個函數一個預設收縮的 <details> 塊：點開看 signature + 中文講解，核心函數附逐行註解。行數很短的工具函數則用段落式說明帶過。

怎麼讀：先從 主線 pipeline 開始——那是 detect → extract → build → cluster 的資料流主幹。看懂後再往 分析與報告、輸出、維運與安全 延伸。語言抽取器放 extractors 專頁。

主線 pipeline

detect + extract + build + cluster 收集檔案 → tree-sitter AST 抽取 → 併入 NetworkX 圖 → Leiden 社群偵測。
檔案：detect.py（1996 行）· extract.py（5993 行）· build.py（1943 行）· cluster.py（320 行） extractors/ 語言抽取器 extractor 骨架：models / engine / resolution / registry，加語言抽取的共通模式。
檔案：graphify/extractors/

分析與輸出

analyze + report god nodes、surprising connections、suggested questions，以及 GRAPH_REPORT.md 的生成。
檔案：analyze.py（749 行）· report.py（300 行） export + exporters 圖 → graph.json / graph.html / Obsidian vault / SVG / callflow HTML。
檔案：export.py · exporters/html.py · tree_html.py · callflow_html.py

指令層與維運

cli.py 指令層 所有 subcommand 的入口——install / extract / query / path / explain / serve / watch…
檔案：cli.py（~5000 行）· __main__.py ops 維運與安全 cache / dedup / ingest / watch / serve / security / validate。
檔案：cache.py · dedup.py · ingest.py · watch.py · serve.py · security.py · validate.py

工具 / 腳本 / 測試

skillgen + gen-demo-path 技能檔怎麼從 fragments 產出（platforms.toml + 模板渲染 + expected/ 校驗），與 README 首圖 SVG 的動畫生成器。
檔案：tools/skillgen/ · scripts/gen_demo_path.py tests 測試策略 140 個測試檔 + fixtures 設計——30+ 語言各一份 sample.*，怎麼測跨語言解析。
檔案：tests/ + tests/fixtures/

對照指南：每頁頂部標示對應的原始檔與行數。程式碼引用自 Apache-2.0 上游，僅用於教學。

教學解說

程式碼對照區是本站最深的章節。每個函數一個預設收縮的 <details> 塊：點開看 signature + 中文講解，核心函數附逐行註解。這反映了「從文檔到原始碼」的學習路徑。

建議的學習順序：先從主線 pipeline（detect→extract→build→cluster）開始，那是資料流主幹。看懂後再往分析與報告、輸出、維運與安全延伸。

程式碼引用自 Apache-2.0 上游，僅用於教學。這是開源專案「合理使用」的範例。

Worked Example：追蹤一個函數的完整流程

  1. 選擇函數：選擇 detect.py 中的 collect_files() 函數。
  2. 查看實作：在 code/pipeline.html 中找到 collect_files 的講解，展開 details 塊。
  3. 追蹤呼叫者：找出誰呼叫 collect_files（在 extract.py 中）。
  4. 追蹤被呼叫者：找出 collect_files 呼叫了什麼（例如 os.walk、CODE_EXTENSIONS）。
  5. 畫出流程：畫出 collect_files 的呼叫流程圖。
關鍵觀察：每個函數都有明確的輸入/輸出，這是「純函數」設計的體現。

常見錯誤與診斷

錯誤訊息原因解決方式
code: file not found程式碼對照頁面找不到對應的原始檔檢查 repo 版本是否與教學站對齊
line number mismatch行數與實際檔案不符這是正常的，原始檔會持續演進

練習與驗收清單

① 進階真實情境 Worked Example：用 graphify 產生「graphify 自己的開發地圖」

前面是「追蹤單一函數」；這次是自舉（dogfooding）：graphify 官方就用自己管理自己——AGENTS.md 規定「先讀 graph.json、改完程式碼跑 graphify update .」。你要親手複製這個閉環。

  1. 在 repo 根建圖：graphify extract . 掃自己整個 repo——detect 會過濾 graphify-out/、node_modules 等 noise；確認程式碼走 AST、文件走 Pass 3。
  2. 讀 GRAPH_REPORT 驗證理解：對照 god nodes 是否就是你想的「核心模組」；看社群數是否對應「pipeline / ops / tools」的實際分界。
  3. 寫進 AGENTS.md：照官方規則加入「先讀圖再回答 + 修改後 update」，讓未來協作者（含 AI agent）也走同一條路。
  4. 用圖回答真實問題：找一個「要改 dedup.py 影響誰」的假設問題，用 graphify affected dedup 或 path 走一遍，對照自己 grep 的結果。
  5. 檢討差異：圖答的與你預期的差在哪？那正是 review.md 精神——紀錄「圖哪邊誤導了你」。
為什麼選這條路徑：用「正在分析的工具」分析自己，是最嚴格的真實性測試——它強迫你面對圖的錯誤、快取的失效、以及「圖過期」的問題，比任何範例語料都有說服力。官方 AGENTS.md 直接示範：這個 workflow 不是玩具，是團隊日常。

② 深入原理擴充：為什麼 5993 行的 extract.py 值得讀、以及「純函數」的界線在哪

程式碼對照頁的規模很嚇人（extract.py 5993 行、cli.py 4044 行），但真正的結構不在行數：

大家以為建圖正確、但其實有誤的案例：以為「extract_<lang> 存在，就代表該語言抽取得很完整」。實際上許多語言只做「結構抽取」（class/function/import），跨檔 calls 解析（Phase 2）需要 resolution 支援——冷門語言（Pascal、Terraform、Apex、Bash 的 source）沒有同等的跨檔解析深度。看到 extract_bash 只代表 Bash 有抽取器，不代表 Bash 的呼叫圖跨檔連得起來。判斷「這個語言支援到多深」要看 tests/fixtures 與 test_languages.py 有沒有對應的跨檔測例。

③ 診斷式疑難排解表

症狀可能原因解決方案
某語言抽取器存在但節點極少該語言只有結構抽取、無跨檔解析；或語法太新 tree-sitter grammar 沒涵蓋看 test_languages.py 有沒有該語言的測例；用 fixture 跑 extract 比對預期節點數
trace 到一半找不到函數定義函數在別的模組（extractors/engine.py、install.py 被 re-export）用 grep "def " 全 repo 找；注意 __main__.py 的 re-export 連到 install.py
改了純函數，測試卻失敗在「意外副作用」函數偷偷寫了 graphify-out/ 或快取，測試 mock 不完整檢查 tmp_path 是否被寫入；用 monkeypatch 隔離 cache/輸出路徑
行數對不上教學頁上游在 v8 後持續演進，badge-line 是快照以 github 上的 blob URL 為準；行號只是定位輔助

④ 進階挑戰題

  1. 「extract.py 5993 行」與「語言邏輯在 extractors/」兩件事並存。請在 repo 裡實測：以 Python 為例，畫出 extract_python → _extract_generic → LanguageConfig 的呼叫鏈，指出「引擎 vs 語言設定」真正的分界線在哪一行。
  2. 「沒有共享狀態」有兩個例外（graphify-out/、cache）。如果要把 cache 也改成純函數（輸入輸出全由參數傳遞），函數簽名會變多複雜？值不值得？
  3. AGENTS.md 規定「先讀圖再回答」。請設計一個機制，當圖過期（graph.json 的 built_at_commit 落後 HEAD）時自動警示，避免 agent 用舊圖回答新問題。