前言¶
2026 年 8 月初，GitHub Trending 上持續出現一個叫 Graphify 的開源項目（Graphify-Labs/graphify）。據 Trending8 在 2026-08-05 的榜單，該項目單日 star 增量在 600～900 量級，與 Claude Code Skill、GraphRAG 等標籤一起被大量開發者討論。
它的賣點很直接：在 Claude Code、Cursor、Codex、Gemini CLI 等 AI 編程助手裏輸入 /graphify，就能把當前項目的代碼、文檔、SQL Schema、PDF 等統一建成一張可查詢的知識圖譜，後續用 query、path、explain 查關係，而不是反覆 grep 或走 embedding 向量檢索。
本文基於官方倉庫 README、graphify.net 文檔以及 Trending 榜單信息整理，重點說明它如何把「代碼庫理解」從傳統向量 RAG 推向結構化 GraphRAG，以及本地如何快速試用。
Graphify 是什麼¶
Graphify 是一個面向 AI 編程助手的 Skill / CLI 工具，由 Graphify-Labs 維護，PyPI 包名爲 graphifyy（注意雙 y），命令行仍叫 graphify。
官方描述可以概括爲三句話：
- 多模態輸入：源碼、Markdown、PDF、圖片、視頻，以及 SQL Schema（需安裝
[sql]擴展）都能進同一張圖。 - 代碼本地解析：源碼通過 tree-sitter 做確定性 AST 提取，不調用 LLM，數據不出本機。
- 圖譜而非向量庫：輸出
graph.json供遍歷查詢，明確聲明不使用 embedding、不依賴向量存儲。
構建完成後，默認在 graphify-out/ 生成三個文件：
graphify-out/
├── graph.html # 瀏覽器可交互瀏覽
├── GRAPH_REPORT.md # 核心節點、意外連接、建議問題
└── graph.json # 持久化圖譜，可反覆查詢而無需重讀源碼
爲什麼有人把它看作「向量 RAG 的替代」¶
傳統代碼 RAG 的常見路徑是：切分文件 → 向量化 → 相似度檢索 → 把若干 chunk 塞給模型。問題在於：
- 檢索結果是片段，跨文件調用鏈、繼承關係容易被截斷。
- embedding 相似不等於結構相關，「誰調用誰」這類問題很難靠餘弦距離回答。
- 每次會話往往重新讀文件或重新檢索，上下文 token 開銷大。
Graphify 走的是 GraphRAG / 知識圖譜 路線。官方 README 給出的 FastAPI 示例中，可以直接執行：
$ 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
每條邊帶 EXTRACTED（源碼中明確存在）或 INFERRED（工具推斷）標籤，查詢者能區分「讀到的」和「猜的」。這與向量檢索返回「若干相似段落」在可解釋性上差異很大。
官方 BENCHMARKS.md 還公佈了 LOCOMO、LongMemEval-S 等對比數據（例如 LOCOMO recall@10 報 0.497），並強調圖譜構建階段對代碼零 LLM 額度。第三方文章（如 Augment Code 對 v0.9.9 的介紹）也提到混合語料查詢 token 可從十萬級降到千級量級——具體數值因倉庫規模而異，但「先建圖、再子圖查詢」的思路是確定的。
核心機制：tree-sitter AST + 圖譜聚類¶
1. 代碼層：tree-sitter 本地提取¶
Graphify 對代碼的第一遍處理是 tree-sitter 遍歷 AST，官方 tree-sitter 說明頁 稱此階段無 LLM、無 embedding、無網絡請求。
README 列出的能力包括：
| 能力 | 說明 |
|---|---|
| 跨文件鏈接 | calls / imports / inherits / mixes_in，覆蓋約 40 種語言 |
| 設計 rationale | # NOTE:、# WHY: 等註釋提升爲一等節點 |
| 社區劃分 | 對 NetworkX 圖跑 Leiden 算法，子系統聚類不依賴向量 |
| God nodes | 高度數樞紐節點，幫助快速定位架構中心 |
純代碼倉庫可用 --code-only 完全離線索引，無需 API Key：
graphify extract ./raw --code-only
2. 文檔與 SQL：語義補充¶
文檔、PDF、圖片等需要 AI 助手已配置的模型做語義抽取；官方強調發送的是語義描述而非原始源碼。SQL Schema 需額外安裝：
uv tool install "graphifyy[sql]"
# 或直連 PostgreSQL
uv tool install "graphifyy[postgres]"
graphify extract --postgres "postgresql://user:pass@host/db"
這樣應用代碼、數據庫表結構、基礎設施配置可以落在同一張圖裏，回答「認證模塊連哪張表」類問題時不必人工拼 grep 結果。
3. 輸出與查詢命令¶
常用 Skill 命令（在助手內）：
/graphify . # 構建當前目錄圖譜
/graphify query "what connects auth to the database?" # 自然語言子圖查詢
/graphify path "UserService" "DatabasePool" # 兩節點最短路徑
/graphify explain "RateLimiter" # 單節點鄰接解釋
CLI 等價示例：
graphify query "show the auth flow"
graphify path "DigestAuth" "Response"
安裝與接入 Claude Code、Cursor¶
環境要求：Python 3.10+，推薦用 uv 或 pipx 隔離安裝。
Step 1 — 安裝 CLI（PyPI 官方包爲 graphifyy，勿與其它同名包混淆）：
uv tool install graphifyy
# 或：pipx install graphifyy
Step 2 — 註冊 Skill：
graphify install
Step 3 — 在助手內構建圖譜：
/graphify .
各平臺專用命令（摘自官方 README）：
| 平臺 | 安裝命令 |
|---|---|
| Claude Code | graphify install |
| Cursor | graphify cursor install |
| Codex | graphify install --platform codex |
| Gemini CLI | graphify install --platform gemini |
Cursor 會在 .cursor/rules/graphify.mdc 寫入 alwaysApply: true 規則，引導助手優先 graphify query 而非整文件 grep。Claude Code 還可選 strict 模式（graphify install --project --strict），在會話開始時阻止首次裸讀源碼，強制先查圖譜。
團隊可提交 graphify-out/graph.json 與 GRAPH_REPORT.md，他人 clone 後助手直接讀圖，無需每人重建。配合 graphify hook install 可在 git commit 後自動增量更新。
適用場景與使用注意¶
更適合：
- 接手陌生單體/微服務，需要理清模塊邊界與調用鏈。
- 代碼 + SQL + 文檔 + ADR 混在一起，要問「設計原因」而不只是「定義在哪」。
- 希望降低 AI 助手反覆 Read/Grep 帶來的 token 消耗。
需要留意的點：
- 文檔/多媒體仍要模型：純
--code-only離線；全量多模態需配置助手已有 API。 - 圖譜需維護：結構大變後應
/graphify . --update或依賴 hook 重建。 - INFERRED 邊需人工判斷：高價值在於 EXTRACTED 的結構邊，推斷邊應交叉驗證。
- Trending 熱度與 star 數：榜單看的是近期增速；評估項目仍建議看 release、issue 與本地試跑，而非只看 star。
小結¶
Graphify 把 2026 年 AI 編程助手領域的一個清晰方向做成了可安裝 Skill：用 tree-sitter 在本地確定性抽取代碼結構，用知識圖譜承載跨文件關係，用可解釋邊替代黑盒向量相似度。它並不取消 LLM，而是讓 LLM 在已有「地圖」上做子圖查詢與推理，代表代碼智能從「embedding 檢索」向「結構化 GraphRAG」演進的一股實用力量。
若你已在用 Claude Code 或 Cursor，30 秒安裝後跑一遍 /graphify .，打開 graphify-out/graph.html 看社區着色與 God nodes，比讀十頁 README 更直觀。
參考來源
- 官方倉庫：https://github.com/Graphify-Labs/graphify
- 項目站點：https://graphify.net/
- GitHub Trending 聚合：https://trending8.vercel.app/
