Graphify：把代码库转为知识图谱供AI助手查询

"AI coding assistants struggle to understand large codebases because they're grepping, not traversing. They find keywords, not relationships."

这是"一天一个开源项目"系列的第 146 篇文章。今天要介绍的项目是 Graphify —— 一个获得 Y Combinator 支持的开源工具，它将你的整个项目（代码、文档、PDF、图片、视频）构建成可查询的知识图谱，并作为 AI 编程助手的情境层来提供服务。

你问 Claude Code 或 Cursor："auth 模块是如何连接到数据库的？"——可能得到正确答案，也可能得到一个听起来合理、但实际是用几个关键词匹配的文件拼凑出来的答案，遗漏了关键的中层结构。根本问题在于：AI 助手依赖关键词搜索和向量相似度来"理解"代码库。两种方式都无法捕捉真实的结构关系。Graphify 替代了这两者：每个函数、类、模块和文档都成为节点，带有明确的类型化边——AI 通过遍历图来构建情境，而非靠猜测。

2.5 个月收获 73,000 Stars，220 万下载量，目前已达 101k Stars。Apache-2.0 + MIT 许可证。

Graphify 与 RAG 的核心区别：图遍历 vs 向量相似度

• tree-sitter AST 本地解析：代码分析零 API 调用，无任何数据离开你的机器
• Edge provenance：每条关系都打有 EXTRACTED / INFERRED / AMBIGUOUS 标签
• God Nodes：自动识别高影响力节点，爆炸半径可视化
• 增量更新：3 个文件变更补丁约 0.8 秒，无需全量重建
• 一条命令安装，在 Claude Code 中使用

前置要求

• 使用 Claude Code、Cursor 或类似 AI 编程工具的经验
• 对知识图谱概念（节点、边、关系）有基本了解
• 基本的 Python 环境使用能力

背景："项目盲区"问题

一个 500 文件的代码库。你问 Claude Code："auth 模块是如何连接到数据库的？"

它的处理过程大致如下：

1. 搜索与"auth"相关的文件
2. 将几个匹配的文件内容拉入上下文
3. 根据这些片段生成答案

问题出在第 1 步。搜索运行在关键词或向量相似度上——而非代码的实际结构关系。它可能：

• 找到三个包含"auth"字符串的文件，但遗漏了关键的中间件层
• 定位到 auth.py 和 db.py，但没有追踪连接它们的调用链
• 再次问同样的问题却得到不同答案

这不是模型能力问题，而是情境构建问题。

Graphify 的方案：在你提出任何问题之前，先将整个代码库解析成图。每个函数、类、模块和文档都是节点。调用关系、导入链和继承都是带类型的有向边。AI 助手查询这张图来构建上下文，而不是 grep。

核心架构：本地 AST + 可选 LLM

Graphify 将项目内容分为两类，分别处理：

代码文件
    → tree-sitter AST 本地解析
    → 零 API 调用，数据不离开机器
    → 提取函数/类/模块节点 + 调用/导入/继承边

文档 / PDF / 图片 / 视频
    → 配置的 LLM 后端（Anthropic / OpenAI / Gemini / Ollama 等）
    → 提取语义节点和关系

            ↓
    统一知识图谱

输出文件：
├── graph.html       ← 交互式浏览器可视化
├── GRAPH_REPORT.md  ← 人类可读的重点内容和推荐问题
└── graph.json       ← 完整可查询图数据

tree-sitter：确定性代码解析

tree-sitter 是行业标准的增量 AST 解析器，被 Neovim、GitHub 等众多工具使用。Graphify 用它来解析代码结构，而非让 LLM 去推断。

• 确定性：相同代码始终产生相同解析结果
• 零 API 成本：代码解析完全在本地，不调用 LLM
• 快速：AST 解析比 LLM 推理快几个数量级
• 私密：代码永不离开机器
• 支持 36+ 编程语言：Python、TypeScript/JavaScript、Go、Rust、Java、C/C++、Ruby、C#、Kotlin、Swift、Scala、PHP、Lua、Zig、SQL 等

这是 Graphify 最具特色的设计决策之一。图中的每条边都带有来源标签：

为什么重要：当 AI 助手遍历图路径来回答问题时，它知道哪些关系是"代码中的硬事实"与"模型推断"。这直接影响答案应该以多大信心来陈述。

用户问："login 函数是如何触发数据库写入的？"

AI 遍历图并找到路径：
login() --[EXTRACTED: calls]--> validate_user()
validate_user() --[EXTRACTED: calls]--> db.query()
db.query() --[INFERRED: writes_to]--> users_table

答案可以明确说明：前两跳是代码确认的；
最后一跳是推断的。

God Nodes：识别高风险点

Graphify 在整个图上自动计算介数中心性，识别"God Nodes"——即位于其他节点之间最多路径上的文件或函数。

在真实代码库中，God Nodes 通常是：

• 被 20 个不同模块导入的工具函数
• 桥接前端和后端的 API 层文件
• 持有所有数据库连接逻辑的单一服务类

这些节点有一个共同属性：它们中的 bug 影响范围最广。Graphify 的可视化会突出显示 God Nodes。当审查 AI 生成的代码变更时，你可以立即看到变更的文件是否是这些高中心性节点之一。

社区检测：发现隐藏的子系统边界

Graphify 在图上运行 Leiden 算法，自动将代码库聚类为功能子系统——独立于目录结构。

• 一个 utils/ 文件夹可能包含实际属于三个不同子系统的代码
• Leiden 聚类基于真实的调用和导入关系，展示哪些文件真正协同工作
• 结果在 graph.html 中以不同颜色编码显示各社区

这对于大型代码库的架构理解和重构规划特别有用。

增量更新：无需全量重建

传统 RAG 的常见痛点：代码变更时，你要重新嵌入整个索引。数百个文件可能需要数分钟。

Graphify 只打补丁变更的文件，保持其他所有节点完好。

官方数据：50 万节点图，3 个文件变更，补丁时间：0.8 秒。

# 自然语言查询
graphify query "how does the login form connect to the users table?"
# → 返回从 UI 到 API 层再到 DB 的完整路径，带有边来源标签

# 两个节点之间的最短路径
graphify path auth.login db.users

# 让 AI 用图作为上下文解释一个函数
graphify explain src/auth/handler.py:validate_token

支持的数据源

Graphify 摄取完整项目，不仅仅是代码：

代码（本地 AST，零 LLM）

36+ 语言：Python、TS/JS、Go、Rust、Java、C/C++、Ruby、Kotlin、Swift 等

文档

Markdown、HTML、RST、YAML、TXT .docx、.xlsx（可选扩展）

图片

PNG、JPG、WebP、GIF（视觉提取）

视频/音频

MP4、MOV、MP3、WAV（通过 faster-whisper 本地转录）

配置文件

MCP 配置文件 包清单：pyproject.toml、go.mod、pom.xml

Google Workspace

Docs、Sheets、Slides（通过 gws CLI）

安装和快速开始

# 安装 CLI（推荐使用 uv）
uv tool install graphifyy   # 注意：PyPI 包名是 graphifyy（双 y）

# 向 AI 助手注册 skill
graphify install

# 在 Claude Code 中运行：
/graphify .              # 为当前目录构建图

# 然后自然地提问——
# AI 遍历图而非 grep

graphify-out/
├── graph.html       ← 在浏览器中打开交互式可视化
├── GRAPH_REPORT.md  ← 重点内容、意外发现的关系、推荐问题
└── graph.json       ← 用于程序化查询的完整图数据

# 启动为 MCP 服务器
graphify mcp --transport stdio   # stdio 传输
graphify mcp --transport http    # HTTP 模式

任何兼容 MCP 的 AI 工具都可以通过工具调用直接访问你的代码图。

可选图数据库后端

# 推送到 Neo4j
graphify push --backend neo4j --uri bolt://localhost:7687

# FalkorDB
graphify push --backend falkordb

根据官方 BENCHMARKS.md，与流行的 memory/RAG 系统对比：

在 LongMemEval-S 上，Graphify 以 76% 准确率与 dense RAG 持平——代码部分的图构建零 LLM 成本。

支持的 AI 助手

一条命令即可在所有工具中注册 skill：

Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot、Aider、Kilo Code、OpenCode、Factory Droid、Trae、Amp、Kiro、Devin CLI，以及任何其他兼容 skill 的工具。

🌟 GitHub：Graphify-Labs/graphify

🌐 网站：graphify.com

📦 PyPI：graphifyy（pip install graphifyy）

🏢 支持方：Y Combinator

Graphify 的核心洞察：情境质量比模型能力更能决定答案质量。

同样的 Claude Sonnet，给它几个 grep 匹配的文件片段 vs 追踪实际代码关系的路径，产生的答案在深度和准确性上有明显差异。Graphify 构建的是后者：tree-sitter 提取精确的代码结构，Leiden 识别子系统边界，介数中心性发现风险节点，所有这一切汇聚成一张可审计的知识图谱，每条边都带有来源标签。

边来源设计（EXTRACTED vs INFERRED）尤其值得关注。在大型代码库中，"这条关系是代码确认的还是模型推断的"这个问题，会改变你接下来的行动。能将 AI 答案追溯到图路径——并知道每一跳的置信度——这决定了它是一个有用的工具还是一个你需要反复质疑的工具。

2.5 个月 73,000 Stars 说明这个痛点是真实存在的。"grep 然后祈祷"式的代码库上下文方法已经流行得够久了。

Explore PrimeSkills — A marketplace for handpicked AI Agents and skills. Each is validated in real enterprise workflows, stripping away hype and keeping only what truly works.

Welcome to my Homepage for more useful insights and interesting products.

For further actions, you may consider blocking this person and/or reporting abuse