Graphify 解決 Claude Code 最大局限：把程式碼庫變成 AI 可查詢知識圖譜

Thu, 21 May 2026 08:02:32 +0800

safishamsi/graphify 是一個面向 AI 編程助手的知識圖譜工具。它的目標很直接：把一個專案目錄裡的程式碼、文件、SQL schema、腳本、論文、圖片、影片和音訊，整理成可查詢的知識圖譜，讓 AI 助手不再只靠 grep、全文閱讀或臨時搜尋來理解專案。

專案地址：safishamsi/graphify

截至本文整理時，GitHub 頁面顯示專案約有 50.2k stars、5.4k forks，授權為 MIT。README 對它的描述是：在 AI 編程助手裡輸入 /graphify，它就會把整個專案映射成一個可以查詢的知識圖譜。

它解決的核心問題

AI 編程助手越來越強，但在真實程式碼庫裡仍然經常遇到幾個問題：

不知道關鍵模組之間怎麼連接。
讀了很多檔案，但沒形成整體架構地圖。
搜尋命中了文字，卻不知道上下游依賴。
程式碼、資料庫 schema、文件和基礎設施設定分散在不同地方。
多人協作時，每個人對專案結構的理解不一致。

Graphify 想做的是給專案生成一層「記憶層」。它把程式碼實體、文件概念、資料庫表、設定、設計說明和跨檔案關係連接起來，讓 AI 助手可以按圖譜查詢，而不是每次從零開始掃檔案。

最小使用方式

Graphify 的最小用法非常簡單。安裝後，在 AI 編程助手裡輸入：

`1`	`/graphify .`

在 PowerShell 裡要注意，前導 / 會被當成路徑分隔符，所以 Windows PowerShell 下應使用：

`1`	`graphify .`

執行後會生成 graphify-out/ 目錄，核心檔案包括：

graphify-out/
├── graph.html
├── GRAPH_REPORT.md
└── graph.json

這三個檔案分工不同：

graph.html：瀏覽器裡打開的互動式圖譜，可以點擊節點、過濾和搜尋。
GRAPH_REPORT.md：專案亮點、關鍵概念、意外連接和推薦問題。
graph.json：完整圖譜，後續可以直接查詢，不必重新讀所有檔案。

如果想生成更可讀的架構頁面和 Mermaid 呼叫流程圖，可以執行：

`1`	`graphify export callflow-html`

安裝和平台支援

Graphify 的 PyPI 包名是 graphifyy，注意是雙 y。README 特別提醒，PyPI 上其他 graphify* 包並不屬於該專案，但 CLI 命令仍然叫 graphify。

推薦安裝方式是：

`1`	`uv tool install graphifyy`

也可以使用：

1
2

pipx install graphifyy
pip install graphifyy

安裝後註冊到 AI 助手：

`1`	`graphify install`

專案支援的平台很多，包括 Claude Code、Codex、OpenCode、GitHub Copilot CLI、VS Code Copilot Chat、Aider、Cursor、Gemini CLI、Kimi Code、Kiro、Google Antigravity 等。不同平台可以用不同安裝命令，例如：

graphify install --platform codex
graphify install --platform gemini
graphify cursor install
graphify antigravity install

Codex 使用者還需要在 ~/.codex/config.toml 的 [features] 下加入：

`1`	`multi_agent = true`

README 也說明，Codex 使用 $graphify，不是 /graphify。

它能處理哪些檔案

Graphify 覆蓋的輸入類型很廣。

程式碼方面，它支援 31 種語言，包括 Python、TypeScript、JavaScript、Go、Rust、Java、C/C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、SQL、Shell、JSON 等。

文件方面，它支援：

.md
.mdx
.qmd
.html
.txt
.rst
.yaml
.yml

還可以透過可選依賴擴展更多類型：

pip install "graphifyy[pdf]"
pip install "graphifyy[office]"
pip install "graphifyy[video]"
pip install "graphifyy[mcp]"
pip install "graphifyy[neo4j]"
pip install "graphifyy[sql]"
pip install "graphifyy[all]"

其中，pdf 用於 PDF 提取，office 用於 .docx 和 .xlsx，video 用於影片和音訊轉寫，mcp 用於 MCP stdio server，neo4j 用於推送到 Neo4j，sql 用於 SQL schema 提取。

生成的報告有什麼價值

GRAPH_REPORT.md 不是普通摘要，它會把專案裡更值得 AI 助手關注的關係挑出來。

README 裡提到的報告內容包括：

God nodes：專案裡連接最多的核心概念。
Surprising connections：跨檔案、跨模組的意外連接。
The why：從註解、docstring、設計文件裡提取出的設計理由。
Suggested questions：圖譜特別適合回答的問題。
Confidence tags：關係會標記為 EXTRACTED、INFERRED 或 AMBIGUOUS。

這點很關鍵。普通搜尋只能告訴你「哪裡出現了這個詞」，而圖譜可以回答「這個概念和哪些模組、設定、表、文件有關」。對大型程式碼庫來說，這比單純全文檢索更接近架構理解。

常用命令

Graphify 的常見命令包括：

/graphify .
/graphify ./docs --update
/graphify . --cluster-only
/graphify . --no-viz
/graphify . --wiki
graphify export callflow-html
/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

也可以把論文或影片加入圖譜：

1
2

/graphify add https://arxiv.org/abs/1706.03762
/graphify add <youtube-url>

如果要做 PR 輔助分析，還可以使用：

graphify prs
graphify prs 42
graphify prs --triage
graphify prs --conflicts

這類命令適合程式碼評審場景：看 PR 影響了哪些圖譜社群、是否和其他 PR 有衝突風險、哪些 review queue 更值得優先處理。

和 MCP、Neo4j、CI 的關係

Graphify 不只是生成 HTML 圖。它也可以把圖譜暴露給 AI 助手反覆呼叫。

例如可以啟動 MCP server：

`1`	`python -m graphify.serve graphify-out/graph.json`

MCP server 提供的能力包括 query_graph、get_node、get_neighbors、shortest_path、list_prs、get_pr_impact、triage_prs 等。

它也支援 Neo4j 匯出或推送：

1
2

/graphify ./raw --neo4j
/graphify ./raw --neo4j-push bolt://localhost:7687

團隊協作上，README 建議可以提交 graphify-out/，讓團隊每個人拉取後都能共享同一份專案地圖。還可以執行：

`1`	`graphify hook install`

這樣每次 git commit 後自動重建圖譜，並設定 merge driver，避免 graph.json 在多人並行提交時留下衝突標記。

隱私和成本要怎麼看

Graphify 的 README 對隱私邊界寫得比較清楚。

程式碼檔案會透過 tree-sitter 在本地解析，不會發出 API 呼叫。影片和音訊可以透過 faster-whisper 本地轉寫。文件、PDF、圖片這類語義提取內容，則會透過你的 AI 助手模型 API 處理。

如果用 headless graphify extract，可能需要設定這些環境變數：

ANTHROPIC_API_KEY
GEMINI_API_KEY
GOOGLE_API_KEY
OPENAI_API_KEY
DEEPSEEK_API_KEY
MOONSHOT_API_KEY
OLLAMA_BASE_URL

本地 Ollama、AWS Bedrock、Claude Code CLI 等也可以作為 backend。README 還寫明專案沒有 telemetry、usage tracking 和 analytics。

實際使用時要注意：程式碼本地解析不等於所有內容都不出網。涉及文件、PDF、圖片或雲端模型時，仍然要看 backend、API key、企業合規和資料邊界。

適合哪些場景

Graphify 適合幾類使用者：

想讓 Claude Code、Codex、Cursor、Gemini CLI 更懂專案結構的開發者。
需要快速理解大型陌生程式碼庫的人。
需要把程式碼、SQL schema、文件、設定放在一起分析的團隊。
做架構審查、PR review、重構影響分析的人。
希望把專案知識暴露成 MCP 工具給 Agent 使用的人。
想為團隊保留「專案地圖」的技術負責人。

它不一定適合所有專案。小型腳本、一次性 demo、結構非常簡單的倉庫，用普通搜尋和 README 可能已經夠用。Graphify 的價值更容易出現在模組多、文件多、團隊協作多、AI 助手頻繁參與開發的大專案裡。

小結

Graphify 的意義在於，它把 AI 編程助手的上下文從「臨時讀取檔案」推進到「長期可查詢的專案知識圖譜」。

對開發者來說，它不是替代 IDE、搜尋或 LSP，而是給 AI 助手補一層結構化記憶：哪些模組重要、哪些概念連接緊密、哪些文件解釋了設計理由、某個 PR 會影響哪些社群。隨著 Codex、Claude Code、Gemini CLI、Antigravity 這類 Agent 工具繼續普及，這類「專案圖譜層」會越來越有用。

參考來源：

GitHub：safishamsi/graphify

Graphify on KnightLi的博客