graphify 繁體中文指南：用 /graphify 技能把程式碼庫轉成可查詢的知識圖譜-编程实验室

graphify 繁體中文指南：用 /graphify 技能把程式碼庫轉成可查詢的知識圖譜

【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify

graphify 是一款 AI 程式碼助手的技能：在 Claude Code、Codex、Cursor、Gemini CLI 等工具中輸入/graphify，它會讀取你的檔案、建立知識圖譜，並返回你不知道存在的結構。本文基於倉庫中的繁體中文 README（docs/translations/README.zh-TW.md），結合 docs/how-it-works.md 的管線說明與graphify/目錄下的實際源碼，完整講解其輸出產物、三段式處理管線、邊緣置信度標記、安裝與常用命令，幫助你在 30 秒內完成安裝並對任意程式碼庫發起結構化查詢。

它解決什麼問題

graphify 的核心定位是**「查圖譜」取代「翻檔案」**。它的三個關鍵特性：

程式碼映射免費且完全本地：程式碼經 tree-sitter AST 解析，確定性提取，不使用 LLM，資料不出機器；
每條邊都有解釋：每條連接標記為EXTRACTED（源碼中明確存在）或INFERRED（由 graphify 解析推導），可直接讀取與推斷的內容可被區分；
不是向量索引：沒有 embeddings、沒有向量庫，是一個真正可以遍歷的圖譜——可以提問、追蹤兩個概念之間的路徑、解釋單個概念。

原文檔以 Karpathy 的/raw資料夾場景作為典型應用：在那裡放置論文、推文、截圖和筆記，graphify 從所有內容中提取概念和關係並連接成單一圖譜——每次查詢比讀取原始檔案少71.5 倍的 token，且在會話之間持久存在。

它是完全多模態的：可以添加程式碼、PDF、Markdown、截圖、圖表、白板照片、其他語言的圖片，以及視訊和音訊檔案（視訊使用 Whisper 在本地轉錄），原文檔提到透過 tree-sitter AST 支援 25 種程式語言（倉庫英文主 README.md 的當前版本已將此數量擴充到 37 種 tree-sitter 文法）。

你會得到什麼產物

執行/graphify .後，項目根目錄會生成graphify-out/：

graphify-out/ ├── graph.html 互動式圖譜 — 在任何瀏覽器中開啟 ├── GRAPH_REPORT.md 神級節點、令人驚訝的連接、建議問題 ├── graph.json 持久圖譜 — 幾週後仍可查詢 └── cache/ SHA256 快取 — 重複執行只處理已變更的檔案

神級節點（God nodes）——度數最高的概念，所有東西都流經它們；
令人驚訝的連接——按分數排名，跨檔案/模組之間出人意料的連結；
建議問題——4–5 個圖譜特別適合回答的問題；
「為什麼」——# NOTE:/# WHY:注釋、文件字串與設計理由被提取為獨立節點，連結到它們解釋的代碼；
Token 基準測試——在混合語料庫上少71.5 倍的 token。

graph.json採用 NetworkX 的 node-link 格式。可以通過倉庫中的真實樣例 worked/httpx/graph.json 觀察實際結構：每個節點包含id（穩定標識符）、label（人類可讀名稱）、file_type（code、document、paper、image、rationale等）、source_file與source_location；每條邊則包含source/target、動詞短語形式的relation（如calls、imports）、confidence標記與source_file。

運作原理：三段式管線

graphify 分三個階段工作：

Pass 1 — 程式碼結構（免費，無 API 調用）：tree-sitter 解析程式碼檔案，提取類、函數、匯入、調用圖和行內注釋，全程本地、無 LLM 參與。純程式碼語料庫會完全跳過 Pass 3。SQL 檔案有確定性的特殊處理（表、視圖、外鍵、JOIN 關係）；
Pass 2 — 視訊和音訊（本地，無 API 調用）：使用 faster-whisper 在本地轉錄，轉錄 prompt 以當前圖譜中的頂級神級節點作為種子，使轉錄內容聚焦於你的領域。結果被快取，重新執行跳過已處理檔案；
Pass 3 — 文件、論文、圖片（Claude 子代理，消耗 token）：Claude 子代理並行處理 markdown、PDF、圖片和轉錄文字，每個子代理讀取一批檔案並輸出 JSON 片段（節點、邊、群組關係），最終合併到單一圖譜。

結果使用Leiden 演算法聚類——從源碼 graphify/cluster.py 可以看到，其文檔字符串明確說明「Uses Leiden (graspologic) if available, falls back to Louvain (networkx)」，即優先調用 graspologic 的 Leiden，不可用時降級到 networkx 的 Louvain，並返回凝聚力分數。最終匯出為互動式 HTML、可查詢 JSON 和審計報告。

SHA256 快取是增量更新的基礎：每個已提取檔案以內容雜湊做指紋，重複執行完全跳過未變更檔案，快取存放在graphify-out/cache/。源碼 graphify/cache.py 中可使用hashlib.sha256確認指紋生成邏輯。

並行提取：程式碼檔案使用ProcessPoolExecutor並行提取（繞過 GIL 實現真多進程）；文件/論文/圖片批次作為並行 Claude 子代理調度。docs/how-it-works.md 記錄的數據：84 個程式碼檔案的並行 AST 提取比順序執行快約 1.66 倍。

邊緣置信度標記

每個關係都標記為三類之一：

標記	含義
`EXTRACTED`	直接發現於源碼（例如函數調用、匯入語句），置信度恆為 1.0
`INFERRED`	合理的推斷，帶有`confidence_score`（0.0–1.0）
`AMBIGUOUS`	不確定——在報告中被標記以供人工復核

INFERRED邊使用離散評分尺度（見 docs/how-it-works.md）：

0.95— 幾乎確定（顯式的跨檔案引用，唯一合理目標）
0.85— 強證據（命名 + 上下文吻合）
0.75— 合理（有上下文但非顯式）
0.65— 弱（僅命名相似性）
0.55— 投機性

在實際圖譜輸出中可以看到這個標記體系的工作樣本，例如--> RequestValidationError [uses] [INFERRED]與--> .get() [method] [EXTRACTED]——前者由解析推導，後者直接來自源碼。

安裝

需求：Python 3.10+ 以及一個 AI 程式碼助手（Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Hermes、Kiro 或 Google Antigravity 等）。

uv tool install graphifyy && graphify install # 或使用 pipx pipx install graphifyy && graphify install # 或 pip pip install graphifyy && graphify install

官方套件說明：PyPI 套件名稱為graphifyy（雙 y）。其他graphify*套件與官方無關；CLI 命令仍是graphify。

使用方式

/graphify . /graphify ./raw --update /graphify query "什麼將 Attention 與 optimizer 連接起來？" /graphify path "DigestAuth" "Response" graphify hook install graphify update ./src

/graphify .— 對當前目錄建圖；
/graphify ./raw --update— 只重新提取已變更的檔案；
/graphify query "..."— 用自然語言提問，返回作用域子圖譜；
/graphify path A B— 追蹤兩件事物如何相連（最短路徑，逐跳輸出）；
graphify hook install— 安裝 post-commit / post-checkout git hooks，提交與切換分支時自動重建圖譜（純 AST，無 API 成本）；
graphify update ./src— 在git pull/ merge 後手動同步圖譜。

graphify hook install還會安裝 git merge driver，對graph.json自動做 union-merge，避免兩個開發者同時提交時出現衝突標記。團隊場景下建議把graphify-out/提交到 git，讓每個人都從一份現成的地圖開始。

隱私與本地優先

程式碼檔案：透過 tree-sitter AST 在本地處理，沒有任何資料離開你的機器；純程式碼語料庫完全離線可跑，無需 API key；
視訊/音訊：使用 faster-whisper 在本地轉錄，同樣不出機器；
文件、PDF、圖片：發送至你的 AI 助手進行語義提取（透過 IDE 會話的模型）；無頭graphify extract則需要配置對應後端（Gemini / Kimi / Claude / OpenAI / DeepSeek / Ollama / Bedrock / claude CLI）的 API key 或憑證；
無遙測、無使用追蹤、無分析。

Token 基準測試

首次執行會提取並建圖（消耗 token），此後的每次查詢讀取緊湊圖譜而非原始檔案，節省隨語料庫規模複利累積。docs/how-it-works.md 記錄的基準：

語料庫	檔案數	縮減倍數
Karpathy repos + 5 篇論文 + 4 張圖片	52	71.5x
graphify 源碼 + Transformer 論文	4	5.4x
httpx（合成 Python 庫）	6	~1x

Token 縮減隨語料庫規模放大：6 個檔案本身就放得進上下文窗口，圖譜在該規模下的價值是結構清晰度而非壓縮；到 52 個檔案時節省快速複利。倉庫中每個worked/資料夾（如 worked/httpx/）都保留了原始輸入檔案與實際輸出（GRAPH_REPORT.md、graph.json），可自行重跑驗證。