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的博客