實作案例

/worked 五個真實案例的產出展示——還有你可以直接玩的互動圖

大方向

worked/ 是 Graphify 的「真實產出收藏」。每個資料夾都有:README.md(語料說明 + 重現步驟)、GRAPH_REPORT.md(真實報告)、graph.jsonreview.md(誠實的成效評估——包括圖哪裡搞錯了)。README 的 contributing 章節也明說:worked examples 是最有用的貢獻

這頁從最大到最小展示,並放上 rsl-siege-manager 的互動知識圖譜——那是真正可操作的 graphify 產出,英文與中文界面兩版。

案例總覽

OpenCode anomalyco/opencode · packages/opencode · TypeScript · 3903 節點 本站的旗艦案例——我們用 graphify 分析「正在用 graphify 建站的工具」本身。opencode@1.18.15 核心 CLI 的 363 個 TypeScript 檔,含版本釘選。 版本釘選 1.18.15graph.html 可互動 rsl-siege-manager Python + TypeScript monorepo · 真實專案 · 1886 節點 真實網頁 app:FastAPI 後端 + React/Vite 前端 + Python Discord bot,全在一個 repo。三語言跨檔案解析、17 個 Alembic migration、三層架構的社群偵測。 graph.html 可互動tests included karpathy-repos 3 repos + 5 papers + 4 images · 52 檔 · 177 節點 nanoGPT / minGPT / micrograd 三 repo + 5 篇論文 + 圖片,跨 repo 與論文橋接。我們從上游 graph.json 重新分群:177 節點、16 社群,god nodes 含 Value、GPT。 圖資料沿用上游我們重新分群 httpx 合成 Python 函式庫 · 6 檔 · 193 節點(本站全跑) 仿照 httpx 架構的合成語料:exceptions → models → auth/transport → client 乾淨分層。我們從零到整跑完一次(純程式碼、零 API key)。 本站全跑零 API key mixed-corpus Python + markdown 論文 + 圖片 · 5 檔 · 22 節點 混合輸入:3 個 Python 模組 + 一篇帶 arXiv 引用的論文筆記 + 一張圖。圖資料沿用上游(含論文節點),我們重新分群產生互動圖。 小語料 example 小文件管線 · 程式碼 5 檔 · 73 節點 可重現的最小範例:parser → validator → processor → storage → api。我們以 --code-only 跑(文件部分需 LLM,標註略過)。新手建議從這裡跑起。 新手入門--code-only

🎮 互動知識圖譜:rsl-siege-manager

下面這個圖是 graphify 真實產出(上游 v8,commit 6085fd66)。1886 節點、3876 邊、141 社群。可以拖曳、滾輪縮放、搜尋節點、點節點看資訊、用社群圖例勾選隱藏。兩個版本:英文原版與中文界面版(節點名稱是程式識別符,兩版都保持英文)。

rsl-siege-manager 知識圖譜(中文界面) 開新分頁 ↗ 英文版 ↗

註:graph.html 為 1.8MB 自含檔(資料全部內嵌),首次載入需要一點時間。節點 label 為程式識別符,故兩版皆保留英文;僅 UI 界面中文化。


真實報告長什麼樣

以 httpx 案例的 GRAPH_REPORT.md 為例(這就是你的 AI 助手會讀的第一份東西):

展開英文原文:httpx GRAPH_REPORT.md(節錄)
# Graph Report - worked/httpx/raw  (2026-04-05)

## Corpus Check
- 6 files · ~2,047 words
- Verdict: corpus is large enough that graph structure adds value.

## Summary
- 144 nodes · 330 edges · 6 communities detected
- Extraction: 53% EXTRACTED · 47% INFERRED · 0% AMBIGUOUS
- Token cost: 0 input · 0 output

## God Nodes (most connected - your core abstractions)
1. `Client` - 26 edges
2. `AsyncClient` - 25 edges
3. `Response` - 24 edges
4. `Request` - 21 edges
5. `BaseClient` - 18 edges
...

## Surprising Connections
- `Timeout` --uses--> `URL`  [INFERRED]
  worked/httpx/raw/client.py → worked/httpx/raw/models.py
...

注意「Token cost: 0」——純程式碼語料零 LLM。而 --uses--> 邊帶 [INFERRED] 標籤,就是 信任標籤 在報告上的體現。

每個案例的「預期結果」

案例預期
exampleapi.py 是連到四模組的 hub;storage.py 是最高度數 god node;parser.py 呼叫 validator/storage;架構筆記連回程式碼;2 社群。
httpx144 節點 / 330 邊 / 6 社群;god nodes = ClientAsyncClientResponse…;驚喜連線:DigestAuth 連到 Response(auth.py 讀 Response 解析 WWW-Authenticate)。
karpathy-repos~285 節點 / ~340 邊 / ~17 社群;god nodes = Value(micrograd)、GPT(nanoGPT);驚喜:nanoGPT 與 minGPT 的 Block 跨 repo 相連、FlashAttention 論文橋進兩個 repo 的 CausalSelfAttention。
mixed-corpusAST 就有 ~20 節點 / ~19 邊 / 3 社群(Graph Analysis / Clustering / Graph Building);attention_notes.md 被歸類為 paper(arXiv heuristic 命中 1706.03762)。
rsl-siege-manager1886 節點 / 3876 邊 / 141 社群(89 shown);90% EXTRACTED;`built_at_commit: 6085fd66`。

自己重現

每個案例的 README.md 都有重現步驟,共通流程:

# 例如 httpx
cd worked/httpx
graphify extract ./raw     # 純程式碼,不需 API key
# 或開你的 AI 助手輸入:
/graphify ./raw

跑完檢查 graphify-out/GRAPH_REPORT.md(報告)、graph.html(互動圖)、graph.json(資料)。用 graphify benchmark worked/httpx/graph.json 可以驗證 README 宣稱的數字。

進階練習:跑完 httpx 後,試 graphify path "DigestAuth" "Response"graphify explain "Client"——看輸出的路徑與 [EXTRACTED]/[INFERRED] 標籤,再對照 GRAPH_REPORT.md 的 Surprising Connections,你就實際體驗了「用圖取代 grep」。

教學解說

worked/ 是 Graphify 的「真實產出收藏」。每個資料夾都有 README.md(語料說明 + 重現步驟)、GRAPH_REPORT.md(真實報告)、graph.json、review.md(誠實的成效評估)。這反映了「可重現性」的開源精神。

案例從大到小展示:OpenCode(3903 節點)→ rsl-siege-manager(1886 節點)→ karpathy-repos(177 節點)→ httpx(193 節點)→ mixed-corpus(22 節點)→ example(73 節點)。這讓你可以根據自己的硬體與時間選擇合適的案例。

互動知識圖譜是真正的 graphify 產出——1.8MB 自含檔,所有資料內嵌,可以直接在瀏覽器中操作。

Worked Example:跑完 httpx 案例

  1. 進入目錄cd worked/httpx
  2. 執行抽取graphify extract ./raw(純程式碼,不需 API key)
  3. 檢查產出:查看 graphify-out/ 目錄下的三個檔案
  4. 驗證數字:執行 graphify benchmark worked/httpx/graph.json,確認 README 宣稱的數字
  5. 探索圖:執行 graphify path "DigestAuth" "Response",觀察路徑與標籤
預期結果:144 節點 / 330 邊 / 6 社群;god nodes = Client、AsyncClient、Response;驚喜連線:DigestAuth 連到 Response。

常見錯誤與診斷

錯誤訊息原因解決方式
graph.html: file too large互動圖超過 1MB這是正常的,大型圖的 graph.html 會很大
benchmark: number mismatch本地跑的結果與 README 不符檢查 graphify 版本是否與案例匹配
path: no path found兩個節點之間沒有路徑檢查節點名稱是否正確,或嘗試其他節點對

練習與驗收清單

① 進階真實情境 Worked Example:用 graphify 產出一份新接手 repo 的 onboarding 指南

前面是「跑完 httpx 案例」;這次換成真實的職場任務:你被指派接手一個陌生的大型開源 repo,要在三天內產出一份「架構 onboarding 指南」給團隊。

  1. Clone 與建圖graphify clone <github-url> 抓 repo,graphify extract . 建圖(程式碼零 LLM)。對大 repo 先注意 detect 的 warning——語料過大會提示成本。
  2. 先讀報告:直接打開 graphify-out/GRAPH_REPORT.md——god nodes 告訴你核心抽象(如 ClientRequest),社群清單告訴你子系統邊界。
  3. 追重要路徑:用 graphify path "入口" "核心元件" 還原「request 怎麼流進核心」;用 graphify explain <god-node> 理解單一抽象。
  4. 交叉驗證:對照報告的 Surprising Connections(跨社群耦合)與 Import Cycles(循環依賴,架構風險),在指南裡標註「這裡是技術債」。
  5. 寫進 onboarding:把「讀 GRAPH_REPORT → 追 path → 看 cycles」變成新人 SOP,附上互動 graph.html 連結。
為什麼選這條路徑:onboarding 的痛點是「原始碼太多、不知道從哪讀」。圖把「最有價值的 10% 結構」先攤開——god nodes 是閱讀優先序、社群是子系統地圖、cycles 是風險清單。三天內從零到指南,靠的就是「建圖一次、之後全讀圖」而不是逐檔看原始碼。

② 深入原理擴充:god nodes 的「排除藝術」與報告的稽核性質

「god node = 最高度數節點」看似簡單,但 analyze.py 的真正功夫在「排除誰」:

報告每一段都由圖資料計算出來,不是 LLM 生成的故事——god nodes 的 degree、EXTRACTED 比例、token 成本都可回溯。這就是「稽核軌跡」:報告可信,因為每個數字都有出處。而 review.md 的存在(每個案例誠實寫出「圖哪裡搞錯了」)是這份可信度的文化層補充——連官方都承認圖會錯,你更該養成「懷疑圖、回去查邊」的習慣。

大家以為建圖正確、但其實有誤的案例:以為「節點數 = 檔案數 × 平均抽象數,所以 3903 節點代表 3903 個真實概念」。實際上節點數受抽取粒度與去重結果影響:一個類別 + 它的每個方法都是節點,rationale(docstring)也是節點,檔案節點也計入;而 dedup 可能把幾個 label 併成一個。不同 repo 的節點數不能直接比大小。看案例時要比「god nodes 是否合理、社群是否對應子系統」,而不是比誰的節點多。

③ 診斷式疑難排解表

症狀可能原因解決方案
互動圖載入很慢或瀏覽器卡死graph.html 太大(rsl-siege-manager 已 1.8MB;節點破萬)_viz_node_limit 防護先確認上限;縮小語料或改用 graph.json + 其他視覺化工具
報告數字與 README 宣稱不符graphify 版本不同(上游 v8 vs 本地新版)或跑了 --code-only對齊版本(案例標註 built_at_commit);確認是否跳過 Pass 3
graphify path A B 找不到路徑節點名是檔案節點而非抽象節點、或兩個節點真的不相連先用 graphify query 確認節點存在與正確 label;換同社群內節點對試
god nodes 出現 str/int 之類用的是舊版 graphify(0.8.33 前的 builtin noise bug)升級 graphify 重跑 analyze;確認 _BUILTIN_NOISE_LABELS 生效
自己重現的社群數對不上案例上游 v8 的圖由特定 commit 建出(6085fd66),社群編號含隨機性固定 seed(確定性)重跑;比「社群是否對應子系統」而非比編號

④ 進階挑戰題

  1. 用「排除後的最高度數」定義 god node。請設計一個反例:一個真正的核心抽象,可能被哪一種排除規則誤殺?如果要加一條「救回」規則,你的判據是什麼?
  2. 案例的 review.md「誠實寫出圖哪裡搞錯」。請瀏覽任一案例的 review.md,挑出一個錯誤類型,並推測它在哪個 pipeline 階段(抽取/解析/去重/分群)被引入。
  3. 「節點數不能跨 repo 比」。請定義一個「可跨 repo 比的架構指標」(如 god node 集中度、社群凝聚力分佈),並說明它的計算方式與可能的偏誤。

① 專案級端到端 Worked Example:用圖驅動的專案重構——從「看不懂」到「重構計畫」

前面是跑完案例和產出 onboarding 指南。這次是用圖驅動重構決策:你接手一個 1500 節點的 legacy 專案,要用 graphify 識別「哪些模組該拆、哪些耦合該解、重構優先序」。

  1. 建圖與初步分析graphify extract . 建圖後,先讀 GRAPH_REPORT.md——找 god nodes(核心抽象)和 Surprising Connections(意外耦合)。
  2. 社群分析:用 graphify query 查「哪些社群最大?」→ 過大社群(>25% 節點)代表模組邊界模糊。用 graphify explain <god-node> 理解每個核心抽象的職責。
  3. 循環依賴偵測:用 graphify path "ModuleA" "ModuleB"graphify path "ModuleB" "ModuleA" 找雙向路徑——循環依賴是重構的首要目標。
  4. 跨社群邊分析:從 graph.json 找出跨社群的 import/calls 邊——這些是「該解耦的介面」。用 graphify explain 確認每條跨社群邊的語義。
  5. 產出重構計畫:把分析結果整理成「重構優先序清單」:先解耦循環依賴 → 再拆過大社群 → 最後處理 Surprising Connections。附上互動 graph.html 連結讓團隊能視覺化驗證。
關鍵觀察:重構計畫的價值在於「基於圖結構而非主觀判斷」——god nodes 告訴你「哪些是核心抽象」、社群邊界告訴你「模組該怎麼拆」、循環依賴告訴你「哪裡耦合太深」。這是「用圖取代 grep」在重構場景的具體體現。

② 效能/品質/安全深度

面向考量實務建議
效能互動圖(graph.html)在節點破萬時可能 >1.8MB,瀏覽器載入慢_viz_node_limit 防護先確認上限;超大圖改用 graph.json + D3.js 自訂視覺化
品質god nodes 的定義是「排除後的最高度數」,不是「最高度數」——排除了檔案節點、概念節點、內建型別檢查 _BUILTIN_NOISE_LABELS 是否包含你的語言的內建型別;用 review.md 記錄已知的圖錯誤
安全互動圖的節點 label 可能含 XSS 攻擊向量確認所有 exporter 走 sanitize_label() 的 HTML-escape;測 <script> 作為 label 跑 export

③ 文件間比較對照表

面向本文(實作案例)相關文差異說明
案例產出五個案例的 GRAPH_REPORT + 互動圖 + review.md運作原理運作原理頁講三遍處理的理論;實作案例頁展示真實產出
God nodes排除後的最高度數 + review.md 的「圖哪裡搞錯」架構總覽架構頁只列 analyze.py 的職責;實作案例頁展示 god nodes 的實際含義
互動圖rsl-siege-manager 的 1.8MB 自含檔,可拖曳/縮放/搜尋程式碼對照 · export程式碼對照頁講 export.py 的 pyvis/HTML 生成邏輯
重現步驟每個案例的 README.md 含完整重現步驟效能基準效能基準頁講 harness 的重現方式;實作案例頁講單一案例的重現

④ 互動式檢核清單