开发工具

Graphify 解决 Claude Code 最大局限：把代码库变成 AI 可查询知识图谱

介绍 safishamsi/graphify：一个面向 Claude Code、Codex、Cursor、Gemini CLI、Antigravity 等 AI 编程助手的知识图谱工具，可把代码、数据库 schema、文档、PDF、图片、视频和音频整理成可查询图谱。

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/ 目录，核心文件包括：

1
2
3
4

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 等。不同平台可以用不同安装命令，例如：

1
2
3
4

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

还可以通过可选依赖扩展更多类型：

1
2
3
4
5
6
7

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 的常见命令包括：

1
2
3
4
5
6
7
8
9

/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 辅助分析，还可以使用：

1
2
3
4

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，可能需要设置这些环境变量：

1
2
3
4
5
6
7

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 工具继续普及，这类“项目图谱层”会越来越有用。

参考来源：

© 2022 - 2026 KnightLi的博客
记录并分享
使用 Hugo 构建
主题 Stack 由 Jimmy 设计