前言¶
用大模型寫代碼，上下文窗口一直是繞不開的瓶頸。Claude Code、Cursor、Codex 這類 Agent 每次開新會話，往往要重新掃一遍倉庫：grep 文件、讀 README、翻 SQL 遷移腳本，Token 燒得飛快，理解還不一定連貫。
向量 RAG 是常見解法，但 embedding 檢索對「誰調用了誰」「模塊之間怎麼串起來」這類結構化關係並不擅長。2026 年 8 月初，GitHub Trending 上快速走紅的開源項目 Graphify（Graphify-Labs/graphify）換了一條路：把代碼、文檔、Schema、PDF 等本地素材，確定性解析成可遍歷的知識圖譜，再通過 /graphify Skill 交給 Agent 查詢——不建向量庫，也不靠 embedding 猜相似度。
據 findarepo.com 2026-08-01 榜單，Graphify 以約 10 萬 Star、7 日 +4300 的增速排在當日 Trending 第 14 位；Trending8 同日也將 Graphify-Labs/graphify 列入「今日增速」榜單。下文基於官方倉庫 README 與文檔覈實功能細節，並給出可復現的上手步驟。
Graphify 是什麼¶
Graphify 是一個面向 AI 編程助手的 Agent Skill，核心承諾可以概括爲三句話：
- 代碼本地解析：用 tree-sitter 做 AST 靜態分析，提取函數、調用、導入、繼承等關係，過程確定性、不調用 LLM，源碼不離開本機。
- 多模態併入同一圖：Markdown、PDF、SQL Schema、配置文件，以及圖片/音視頻（需額外依賴）經語義抽取後，與代碼節點合併進同一張 NetworkX 圖。
- 可查詢、可解釋：生成
graph.json持久化圖譜，支持自然語言 query、兩點 path 追蹤、單節點 explain；每條邊標註EXTRACTED（源碼顯式）或INFERRED（工具推斷），便於審計。
項目在 GitHub 上約 2026-04-03 創建，維護者爲 Safi Shamsi 主導的 Graphify-Labs；PyPI 包名爲 graphifyy（雙 y，官方強調其它 graphify* 包無關聯），CLI 命令仍爲 graphify。許可證以倉庫元數據爲準爲 Apache-2.0。
爲什麼現在火：上下文工程的新選項¶
Agent 編程工具普及後，「上下文工程」成了顯學：怎麼在有限 Token 裏塞下足夠準確的項目記憶？常見痛點包括：
- 大倉庫反覆全文檢索，延遲高、成本高；
- 純 RAG 返回片段，缺少跨文件調用鏈；
- 文檔、Schema、代碼分屬不同來源，Agent 難以建立統一心智模型。
Graphify 的定位是 RAG 的互補而非簡單替代：它不做 embedding 索引，而是構建顯式圖結構，用 Leiden 算法做社區劃分，標出「上帝節點」（高度數樞紐）和跨模塊的意外連邊。官方 README 稱在 Karpathy 混合語料（代碼 + 論文 + 圖）上，圖查詢平均約 1.7k Token，對比 naive 全文約 123k Token——具體數值因項目而異，但思路清晰：索引一次，多次查詢。
這與 Andrej Karpathy 曾提出的「爲 LLM 建結構化知識庫、讓模型查詢而非重讀原文」一脈相承；DEV Community 上也有開發者用 FastAPI 等真實倉庫驗證 query / path / explain 工作流的實踐文章。
核心原理：AST + 圖，而非向量¶
代碼層：tree-sitter 確定性抽取¶
Graphify 對源碼走 tree-sitter 管道，官方稱支持約 40 種語言 的 calls / imports / inherits / mixes_in 等跨文件邊。註釋裏的 # NOTE:、# WHY: 以及 ADR/RFC 引用會被提升爲節點，與設計 rationale 關聯——這對「改代碼前先理解爲什麼這樣寫」很有幫助。
要點：代碼解析階段零 LLM 調用、零外發。
文檔與 Schema：可選語義通道¶
PDF、Office、圖片等無法純語法解析的內容，Graphify 會走語義抽取；此時使用你在 Claude Code / Cursor / Codex 等助手裏 已配置的模型 API，官方說明只發送文檔的語義描述，不發送原始源碼。SQL Schema 可通過 graphifyy[sql] 或 graphifyy[postgres] 等 extra 接入。
建圖與聚類¶
各階段產出節點/邊後，合併爲 NetworkX 圖，用 Leiden 做社區檢測（無需向量 embedding）。最終導出三件套：
graphify-out/
├── graph.html # 瀏覽器交互可視化
├── GRAPH_REPORT.md # 核心概念、意外連邊、建議提問
└── graph.json # 可編程查詢的全量圖
安裝與註冊 Skill¶
環境要求：Python 3.10+，推薦用 uv 隔離安裝。
1. 安裝 CLI
uv tool install graphifyy
# 或：pipx install graphifyy
若提示找不到命令，執行 uv tool update-shell 後重開終端。
2. 向 AI 助手註冊 Skill
graphify install # 默認 Claude Code
graphify cursor install # Cursor
graphify install --platform codex
graphify install --platform gemini
graphify install --project # 寫入當前倉庫，便於團隊共享
官方支持 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 等 20+ 平臺；Codex 用戶需在 ~/.codex/config.toml 開啓 multi_agent = true 以並行抽取。
3. 在助手對話中構建圖譜
在 Claude Code / Cursor 等支持 Slash Command 的環境：
/graphify .
PowerShell 下勿寫前導 /，應使用 graphify .。
首次運行完成後，項目根目錄會出現 graphify-out/。可用 --update 做增量更新，避免全量重建。
查詢圖譜：替代反覆 grep¶
圖譜建好後，在終端或讓 Agent 調用 CLI 即可，無需重讀全庫。官方 FastAPI 示例輸出如下（摘自 README）：
$ graphify explain "APIRouter"
Node: APIRouter
Source: routing.py L2210
Community: 2
Degree: 47
Connections (47):
--> RequestValidationError [uses] [INFERRED]
--> .get() [method] [EXTRACTED]
<-- __init__.py [imports] [EXTRACTED]
$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField
常用命令：
| 命令 | 作用 |
|---|---|
graphify query "認證流程怎麼走？" |
按自然語言取子圖並回答 |
graphify path "AdminPanel" "Database" |
兩概念間最短路徑 |
graphify explain "RateLimiter" |
單節點及鄰域解釋 |
中文查詢可安裝 graphifyy[chinese] 以啓用 jieba 分詞。若希望 Agent 優先查圖再讀文件，可對 Claude Code 執行 graphify install --project --strict，首讀源碼會被重定向到圖譜查詢（每會話最多攔截一次，避免卡死）。
與 Claude Code、Cursor 的集成方式¶
Graphify 以 Skill 形態嵌入工作流：安裝後在對話裏 /graphify 觸發構建，後續任務中 Agent 可調 graphify query 等命令拉上下文。對 Cursor，運行 graphify cursor install 即可寫入對應 Skill 目錄。
這與「每次 @ 整個文件夾」或「讓模型自己 glob 全倉庫」形成對比：前者是靜態快照 + 結構化檢索，後者是重複 IO。對於 monorepo、含大量 PDF/Schema 的全棧項目，把 應用代碼 + 數據庫 Schema + 基礎設施配置 放進同一張圖，能減輕 Agent 在多層之間「迷路」的概率。
可選能力還包括：graphifyy[mcp] 暴露 MCP 服務；graphifyy[neo4j] / [falkordb] 推送到外部圖數據庫；graphify hook install 在 git commit 後自動增量更新圖譜。
和向量 RAG 怎麼選¶
| 維度 | 向量 RAG | Graphify 知識圖譜 |
|---|---|---|
| 索引方式 | embedding 相似度 | AST + 顯式邊 + 可選語義節點 |
| 擅長 | 模糊語義、長文檔片段召回 | 調用鏈、模塊邊界、跨文件依賴 |
| 存儲 | 向量庫 | 本地 graph.json，無 embedding |
| 成本結構 | 建庫與檢索均消耗 Token | 代碼解析零 LLM；文檔語義按配置模型計費 |
| 可解釋性 | 相似度分數 | 邊類型 + EXTRACTED/INFERRED 標籤 |
實踐上二者可並存：RAG 兜文檔長尾問答，Graphify 兜「從入口到數據庫經過哪些層」這類拓撲問題。官方 BENCHMARKS.md 在 LOCOMO、LongMemEval-S 等設定下給出了與 mem0、supermemory 等的對比表，感興趣的讀者可在倉庫內復現實驗，不宜脫離具體語料盲目照搬分數。
使用注意¶
- 包名是 graphifyy，
pip install graphify可能裝到無關項目。 - 文檔/多媒體語義抽取依賴已配置的模型 Key；純代碼圖譜可完全離線完成。
- 超大倉庫首次構建耗時與文件量線性相關；善用
cache/與--update。 - Graphify-Labs 同時運營 graphify.com 平臺（持續後臺更新圖譜），開源 CLI Skill 與雲服務是兩條產品線，本文僅討論開源 Skill 路徑。
小結¶
Graphify 把「代碼理解」從反覆全文掃描，推進到 一次建圖、多次遍歷：tree-sitter 本地 AST、Leiden 社區、可解釋的 EXTRACTED/INFERRED 邊，加上與 Claude Code、Cursor、Codex 等深度集成的 /graphify Skill——正好切中 2026 年開發者工具鏈裏「Agent 需要一張項目地圖」的熱點。
若你正在維護萬行級倉庫、或文檔與 Schema 分散在多處，不妨花半分鐘安裝 graphifyy，在項目根執行一次 /graphify .，打開 graphify-out/graph.html 看社區着色與上帝節點，再用 graphify path 問一個你平時要翻十幾個文件才能答的問題——這比 Star 數字更能說明它值不值得進你的工具箱。
