稀饭

graphify：把整个代码库变成一张知识图谱——不再 grep,直接查询

10.4 万 star、YC S26 出品。用 tree-sitter AST 把代码、文档、PDF 解析成可查询的知识图谱：确定性、本地免费、无向量库，每条连接都标注 EXTRACTED/INFERRED——给 AI 代理一张代码库地图。

  • AI
  • Agent
  • Claude Code
  • 知识图谱
  • 代码理解
  • GraphRAG
  • 开源项目

前面几篇写了各种"给编码代理装技能"的项目——Superpowers(纪律)、ECC(体系)、mattpocock/skills(手艺)、gstack(团队)、UI UX Pro Max(审美)。 这些解决的都是"代理怎么干活"。今天这篇解决一个更基础的问题:代理怎么理解一个陌生的大代码库。

答案是 graphify—— 一个 10.4 万 star、YC S26 公司(Graphify Labs)出品的开源项目。 它把整个代码库(代码、文档、PDF、甚至图片视频)变成一张可查询的知识图谱, 让 AI 代理"查询图谱"而不是"grep 文件"。

一、它是什么:代码库的"地图"

官方定义:

把任何代码库(连同它的文档、SQL schema、配置、PDF)变成一张可查询的知识图谱。本地确定性的 AST 解析，每条连接都有解释，不需要向量库。

用法极简——装好后在你的 AI 助手(Claude Code、Cursor、Codex、Gemini 等 20+ 平台)里敲一句:

/graphify .

然后得到三个文件:

graphify-out/
├── graph.html       浏览器里打开,点节点、筛选、搜索
├── GRAPH_REPORT.md  亮点:核心概念、意外连接、建议问题
└── graph.json       完整图谱——之后查询它,不用重读文件

举个例子,这是它对 FastAPI 代码库的查询输出:

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

Connections (47):
  --> RequestValidationError [uses] [INFERRED]
  --> Dependant [uses] [INFERRED]
  --> .get() [method] [EXTRACTED]
  <-- __init__.py [imports] [EXTRACTED]
  ...

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references-- ModelField

二、它和 RAG / 向量检索的根本不同

graphify 最有意思的地方,是它明确反对主流的向量检索方案。官方反复强调:

不是向量索引。没有 embedding,没有向量库——是一张真正的图,你可以遍历它。

两者的差别很本质:

  • 向量检索(RAG)——把代码切块、embedding 成向量、相似度匹配。 快,但没有结构:它不知道 A 函数调用了 B,不知道 C 继承了 D, 只能"找出语义相近的片段";
  • 知识图谱(graphify)——用 tree-sitter AST 解析代码,确定性地提取出真实的连接:calls、imports、inherits、mixes_in,横跨约 40 种语言。

"确定性"是关键:代码解析用 AST 而非 LLM——本地运行、零 API 调用、不消耗 token、数据不出机器。 只有处理文档/PDF/图片时,才用你的模型做语义分析(且可选)。

另一个独特设计是 置信标签:每条连接都标注它是EXTRACTED(源码里明确写的)、INFERRED(graphify 解析推断的)、 还是 AMBIGUOUS(有歧义)。你永远知道哪些是"读到的"、 哪些是"推出来的"。

三、它能干什么:三个核心查询 + 图谱洞察

graph 建好后,你不必再读文件,直接问:

  • graphify query "什么问题连接了 auth 和数据库?"——用自然语言问,返回聚焦的子图;
  • graphify path "UserService" "DatabasePool"——追踪任意两个东西怎么连接;
  • graphify explain "RateLimiter"——解释一个概念:它的源码位置、连接、社区。

生成的报告里还有几类"图谱独有的洞察":

  • God nodes(枢纽节点)——全项目连接最多的概念,看"一切流经什么";
  • Communities(社区)——用 Leiden 算法把图切成子系统,并自动给每个子系统一个标签;
  • 跨文件连接——散落在不同文件/模块间的"意外连接",按有多意外排序;
  • 设计依据节点——# NOTE:、# WHY: 注释和 ADR/RFC 引用, 会变成链接到代码的一等节点。

它甚至能处理超出代码的东西——/graphify add <arxiv 论文 URL> 拉论文,/graphify add <YouTube URL> 转录视频,把 PDF、图片、办公文档都并进同一张图。

四、效果如何:基准测试

官方在 BENCHMARKS.md 里贴了对比(所有系统用同一 harness、同一模型、同一预算,双盲评审 90.6% 一致):

基准指标graphify对照
LOCOMO (n=300)recall@100.497mem0 0.048、supermemory 0.149
LOCOMO (n=300)QA 准确率45.3%supermemory 49.7%、mem0 27.3%
LongMemEval-S (n=50)QA 准确率76%与密集 RAG 持平
图谱构建LLM 成本0多数系统按 token 计费

它在代码检索上大幅领先 mem0 / supermemory,且构建图谱零 LLM 成本—— 因为代码解析根本不调模型。

五、怎么用:30 秒开始

# 安装 CLI
uv tool install graphifyy      # 或 pipx install graphifyy

# 注册到你的 AI 助手
graphify install

然后在 AI 助手里输入 /graphify . 即可。支持 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 等 20+ 平台。 一个值得提的细节:安装有 strict 模式(graphify install --project --strict)—— 默认只是"建议"代理先查图再读文件,strict 模式会强制会话里的第一次源码读取先走图谱,防止代理一上来就盲目读文件。

六、诚实的提醒

  • 是开源 + 商业模式——核心开源(Apache-2.0),但有个 graphify Enterprise( 常驻后台、覆盖会议/文档/代码的持续更新版)在 graphify.com 等早期体验;
  • 代码解析免费,文档/媒体要花 token——代码用 AST 免费解析,但 PDF、图片、视频要调模型。想"全免费"就只解析代码;
  • 图谱是一次性快照——默认按需生成;要常驻更新得用 enterprise,或装 git hook(graphify hook install)在每次 commit 后自动重建;
  • 包名容易踩坑——PyPI 包名是 graphifyy(双 y),命令是 graphify。别的 graphify* 包都不是官方的。

我的收获

  1. RAG 不是代码理解的唯一答案——对"代码"这种强结构化的东西,确定性 AST 解析 + 真实连接, 比"语义相似的文本块"更接近本质。向量检索擅长模糊语义,图谱擅长精确结构。
  2. "每条连接都有解释"是稀缺的信任设计——EXTRACTED/INFERRED 标签让代理(和人)都知道 什么是从源码读到的、什么是被推断的。这在 AI 输出里极其罕见。
  3. 给代理"地图"比给代理"更多上下文"更有效——面对陌生代码库, 与其塞进去几百万行 token,不如先让它看一眼地图:枢纽在哪、模块怎么连、哪里意外相关。
  4. 系列拼图又补一块——纪律、体系、手艺、团队、审美之外,还有理解。 而"理解"恰恰是其他一切的前提:一个不认识代码库的代理,再守纪律也白搭。

想深入了解,推荐GitHub 仓库、graphify.com,以及作者 Safi Shamsi 的《The Memory Layer》(讲这套图思想的架构书)。 下次你或你的代理面对一个陌生代码库时,试试先 /graphify .—— 有一张地图再开始探索,和你闷头 grep 完全是两种体验。