AI 每次都要把整个项目读一遍？这个工具先把代码变成图谱（14.6 万星）

2026-11-11silcano

你让 AI 改一个函数，它先 grep 了二十次，把五个文件读进来，花掉一半上下文。它不是在思考，是在找路。

graphify 的做法是提前把路修好：把整个项目（代码、文档、SQL、PDF、图片）建成一张知识图谱，让 agent 查图，而不是逐个文件翻。

14.6 万星，每天涨 657 星，Apache-2.0，Python 写的。关键数据：代码解析走 tree-sitter AST，不调 LLM，全本地，0 次模型调用。

一、先说结论：省的是"找"的时间

一个 agent 读代码库，时间花在三个地方：找文件、读文件、改代码。

第三个是正事，前两个是开销。而"找"这件事，用 grep 做效率极低——你知道函数名叫 validate，但它在哪个文件、被谁调用、跟哪个模块耦合，grep 只给你行号。

图谱解决的是关系：谁调用谁、谁依赖谁、这个概念在哪些文件里出现。有了关系，agent 一次查询就能定位。

二、它建的是什么图

按 README，输入是"any codebase, with its docs, SQL schemas, configs, and PDFs"——不只是代码。

注意第一行的措辞："deterministic, no LLM"。代码部分是纯静态解析，结果可复现，不花钱，不出本机。

其它类型（PDF、图片）需要模型参与，所以它会区分对待。这个设计很克制：能不用模型的地方绝不用。

三、装：两条命令

装 CLI：

包名是 graphifyy（两个 y），不是 graphify。这点容易踩坑。

注册到你的 AI 助手：

它支持 Claude Code、CodeBuddy、Codex、OpenCode、Cursor 等。install 的作用是"告诉助手有这个技能"，之后你才能用 /graphify。

前置依赖：Python 3.12 左右的环境，以及 uv 或 pipx。macOS 可以 brew install python@3.12 uv，Windows 用 winget install astral-sh.uv。

四、用：三条命令覆盖全部场景

建图（第一次）：

在当前项目里跑，产出物会落在 graphify-out/ 目录。

查询： 直接用自然语言问你的助手，它会调图谱；或者用 CLI：

输出长这样：

Degree: 47 是它的连接数——这个数比代码行数有用得多，连接多的节点是改动的风险点。

看可视化： 打开 graphify-out/graph.html，可以点节点、筛选、搜索。

五、四个产物文件，各有什么用

GRAPH_REPORT.md 是最被低估的一个。它不是图，是一份摘要报告：项目里的关键概念、你没意料到的连接、以及建议你问的问题。

新人接手项目，先读这份报告比读 README 有用——README 讲"是什么"，它讲"实际长什么样"。

六、为什么能省 80% token

这个数字来自它自己的宣传。机制不难推：

没有图谱时，agent 的典型行为是：grep 关键词 → 读五个文件的片段 → 再 grep → 再读。每次读取都进上下文，而且大部分是无关代码。

有图谱时：查询一次 → 拿到节点和邻居 → 只读必要的两三个文件。

省下的不是"读的量"，是"试错次数"。 试错是 token 消耗的真正大头。

README 里给的基准数：recall@10 = 0.497，0 LLM credits。前半句是检索质量（前 10 个结果里命中率约一半），后半句是建图不花模型钱。

七、六个坑

• 包名写错。 是 graphifyy（两个 y），拼成一个会装到别的东西；
• 没跑 graphify install。 助手不认识 /graphify；
• 在大仓库上直接跑。 几万个文件会很慢，先限定子目录；
• 以为图会自己更新。 代码改了要重建，它不是 daemon；
• 把图当源码。 图是索引，改代码还是要改文件；
• 提交了 graphify-out。 体积大且是派生产物，加进 gitignore。

第三条补充一句：正确做法是先 cd 到子目录再 /graphify .，需要时再合并。一次建整个 monorepo，你会等到放弃。

八、适合什么项目

判断标准很简单：如果你 grep 一个函数名会得到超过 20 个结果，就该建图了。

九、和"向量检索代码"的区别

另一个流派是把代码切片做 embedding，按语义检索。两者区别明显：

第一行是关键差异：向量检索擅长"像什么"，图谱擅长"连着谁"。改代码这件事，更依赖后者。

十、谁该用

十一、版本与地址

最后一句：这个工具的洞察是——AI 读代码慢，不是因为它读得慢，是因为它在找。把"找"这件事提前做完，剩下的才是它擅长的。