12.3万星的Graphify把代码库变成知识图谱

摘要

接手一个几十万行的陌生项目，最痛苦的不是写代码，而是不知道从哪读起。Graphify 是一个已经拿下 12.3 万 star 的开源项目：在 AI 编程助手里输入一句 /graphify .，它就把整个项目（代码、文档、PDF、图片、视频）解析成一张可以查询的知识图谱，还会生成一张形似星云的交互式可视化图，让你一眼看清大型代码库的骨架。

它是什么

Graphify 是一个面向 AI 编程助手的技能（skill），用 Python 编写，Apache-2.0 协议开源，支持 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 等二十多种助手。

它做的事情可以用一句话概括：把“靠 grep 和猜”的代码阅读方式，换成“查一张图”。

跑完一次后，项目目录下会多出一个 graphify-out/ 文件夹，最核心的是这三个文件：

graph.html：浏览器直接打开的交互式图。节点是概念，颜色代表自动识别出的社区（也就是子系统），可以点击、筛选、搜索。成千上万个节点聚在一起，远看就是一团五彩的星云，近看每个点都能点开。
GRAPH_REPORT.md：精华报告，列出关键概念、意外的跨模块连接，以及图谱最适合回答的几个问题。
graph.json：完整的图数据，之后随时可以查询，不必重新读一遍源码。

核心优势

1. 代码解析完全本地，不花一分钱。 代码部分用 tree-sitter 做 AST 解析，过程是确定性的，不调用大模型，代码也不会离开你的电脑。只有文档、PDF、图片、视频这类非代码内容，才会用你的助手模型（或你配置的 API Key）做一轮语义提取。官方基准里“图谱构建消耗的 LLM 额度”一栏就是 0。

2. 每一条边都有出处。 图里每个连接都标注了置信度：EXTRACTED 表示源码里明明白白写着，INFERRED 表示由 Graphify 推断解析出来，另外还有 AMBIGUOUS 表示存在歧义。你永远知道哪些是读出来的，哪些是猜出来的，不会被“看起来很对”的幻觉带偏。

3. 不是向量库，是真正的图。 没有 embedding，没有向量数据库。你可以提问、追踪两个东西之间的路径、解释某个概念，所有操作都在 graph.json 上完成，结果可复现、可解释。

4. 读得懂代码之外的“为什么”。 代码里的 # NOTE:、# WHY:、# HACK: 注释，以及文档里引用的 ADR、RFC，会变成独立节点，并连到它们所解释的代码上。这类设计动机，通常是新人最难拿到的信息。

5. 覆盖面广。 代码侧支持 37 种 tree-sitter 语法，跨文件的调用、导入、继承关系可以跨约 40 种语言解析；此外还支持 Terraform、SQL 表结构、MCP 配置、各类包管理清单等。

面向人群

刚接手老项目的开发者：用 GRAPH_REPORT.md 加星云图，快速建立全局印象。
做代码评审或技术尽调的人：快速找出“上帝节点”（被最多东西依赖的核心概念）和意料之外的跨模块耦合。
重度使用 AI 编程助手的人：让助手先查图再读文件，少走弯路，也省 token。
维护多语言、多仓库混合项目的团队：一张图里同时看到代码、文档和配置。

快速上手

整个过程两步安装，一步运行。先确认 Python 版本在 3.10 以上，推荐用 uv 安装。注意 PyPI 上的官方包名是带两个 y 的 graphifyy，其他名字相近的包与官方无关，命令行入口仍然是 graphify。

# 安装命令行工具
uv tool install graphifyy

# 把技能注册到你的 AI 编程助手
graphify install

然后打开你的助手，在项目根目录输入：

/graphify .

等它跑完，用浏览器打开 graphify-out/graph.html，就能看到整个项目的星云图。Codex 用户需要把斜杠换成美元符号，即 $graphify；PowerShell 里则要写成 graphify .，因为开头的斜杠会被当成路径分隔符。

如果安装后提示找不到 graphify 命令，多半是工具目录还没进 PATH，执行 uv tool update-shell 再开一个新终端即可。

进阶用法

图建好之后，不用再去翻文件，直接查询：

# 解释某个概念：来源、所在社区、连接数和每条连接
graphify explain "APIRouter"

# 追踪两个概念之间的最短路径
graphify path "FastAPI" "ModelField"

# 用自然语言提问，返回一张相关的子图
graphify query "请求校验是怎么触发的"

官方在 FastAPI 代码库上的演示里，path 命令返回的是一条三跳的路径，每一跳都带着 EXTRACTED 或 INFERRED 标签。

想让助手“每次都先查图”，在项目里再跑一次对应平台的安装命令，例如 Claude Code 用 graphify claude install，Cursor 用 graphify cursor install。它会写入一小段配置，提示助手遇到代码库问题时优先使用 graphify query，而不是整份报告或逐个文件地读。如果你用的是 Claude Code、想要更强的约束，可以用 graphify install --project --strict：每次会话里，第一次直接读源码会被拦下并引导到图谱上，之后恢复为普通提示，不会卡死流程。

可选的扩展按需安装，比如 PDF 提取用 graphifyy[pdf]，视频和音频转写用 graphifyy[video]，MCP 服务用 graphifyy[mcp]，中文提问的分词用 graphifyy[chinese]，一次装全用 graphifyy[all]。安装方式和主包一样，例如 uv tool install "graphifyy[pdf]"。

我的看法

大项目读不懂，根源往往不是代码太复杂，而是缺少一张地图。Graphify 的取舍很克制：能用确定性的 AST 解决的就不交给大模型，能标注置信度的就不假装全知。这让它的结果可以被信任，也可以被验证。

当然也要说清楚，图谱本身只是读代码的起点。INFERRED 的边需要你抽查，社区划分也只是算法给出的参考。但作为接手陌生项目的第一步，先看星云图，再带着问题去读源码，效率确实会高不少。

项目地址：github.com/Graphify-Labs/graphify

123k-star-graphify-turns-codebase-into-knowledge-graph