我看 Graphify：给 AI 先画一张地图

今天早上，我在业界做 fullstack software engineer 的老朋友老刘（Mr. Liu）丢给我一个 repo 的链接，说”这个 tool 还不错，你看看”。我打开一看，是个叫 Graphify 的项目。

一开始我以为它大概是个本地 MCP 工具，或者说是个帮 AI 少读代码、少烧 token 的东西。看完之后，我觉得它跟这个方向确实有关，但不是我最初想象的那种”万能本地 AI 记忆层”。

它更像是——给 AI 看代码之前，先给它画一张地图。

Graphify 到底在做什么

Graphify 的核心逻辑其实不复杂：把你的项目目录扫一遍，把代码、文档、PDF、图片这些东西整理成一个 knowledge graph，输出到 graphify-out/ 目录里。主要产物是三个：

• graph.json：机器可查询的图结构
• GRAPH_REPORT.md：给人看的核心节点报告，包括”意外节点”和”推荐问题”
• graph.html：可交互的可视化图

然后它提供一个 MCP server（graphify serve），把这张图暴露给 Claude Code、Codex、Cursor、Gemini CLI 这些 AI 工具，让它们先查图，再决定去读哪些文件，而不是每次都从零开始扫整个 repo。

顺带一说：这个项目目前在 GitHub 上有 72k+ stars，是个相当活跃的开源项目，社区生态也已经形成了一定规模。

它解决的是一个很真实的问题

用 AI 写代码，有个很现实的困境是：AI 每次进来都要重新理解项目。哪怕是一个中等规模的项目，它要扫 README、目录结构、model、service、配置文件、SQL、XML，可能还没开始写代码，token 就已经消耗了一大截。

Graphify 想做的就是打破这个循环。第一次花时间建图，把项目结构提取出来；以后你问”认证流程在哪里”、“这个 model 跟哪些 view 有关系”、“这个 API 最终调到哪里”，AI 不需要全局搜一遍所有文件，而是先从图里找到相关节点，再去读具体文件。

思路是对的，但这里藏着一个关键问题：这张图到底准不准？

省 token 不是最终目标

如果省了 token，但理解变差了，那整个工具就失去了意义。

我们用 AI coding assistant 的目标，从来不是单纯省钱，而是让它更准确地理解代码、更少瞎改、更少编造不存在的文件。

Graphify 能比较确定地证明的是：它可以减少 context token 的消耗。它自己的 benchmark 主要测的是”完整 corpus 需要多少 token”对比”查询子图返回的结果需要多少 token”——大型项目里的差距相当可观。

但它没有严格证明另一个更重要的问题：

用了 Graphify 之后，AI 对代码的理解质量是否和直接读整个代码库一样好？

换句话说，它证明的是”少读了”，但没有严格证明”少读之后还一样准”。有没有测 patch success rate？有没有测 hallucination rate？有没有把它和 raw repo reading 的结果做对比？这些我目前没看到。

这是我觉得最值得注意的地方。省 token 是工程指标，准确性才是开发体验的核心指标。

Graphify 是地图，不是城市

这是我看完之后最核心的一个判断：Graphify 生成的是一张地图，不是城市本身。

地图告诉你大概哪里有路、哪里有桥、哪里是核心区域，但你真的要施工，还是要到现场看真实情况。对应到代码就是：Graphify 可以帮 AI 快速定位”应该看哪里”，但它不应该替代 AI 去读取真实源文件。

所以我觉得比较合理的使用姿势是三步走：先查图找方向，再读真实文件，最后再写代码。Graphify 应该是导航层，而不是最终事实来源。

关于图会不会过时

这是这类工具必须面对的问题。graph.json 本质上是某一刻的快照，如果代码改了，图没更新，AI 拿到的就是旧地图，可能反而会误导。

好消息是，Graphify 对这个问题已经有了内置答案：graphify hook install 会在每次 git commit 之后自动重建图，并且提供了 --if-stale 标志，让工具能知道自己的图是不是过时了。增量缓存也是内置的，改动的文件才会重新处理，不是每次全量重扫。

所以这个担忧是真实的，但 Graphify 本身已经给了一套机制来应对。当然，这套机制能不能覆盖你项目的实际工作流，还是要自己验证一下。

什么东西是本地的，什么要走 LLM

这里有个细节值得单独说清楚，因为它直接影响隐私评估。

Graphify 的代码分析部分——class 在哪里、function 调用关系、import 链路、symbol 索引——这些走的是 tree-sitter 和 AST 分析，完全本地完成，原始代码不会发送给任何 LLM。

只有文档、PDF、图片这类语义内容才会走 LLM API（Claude、OpenAI，或者你本地配置的 Ollama / LM Studio 都行）。Graphify 本身不捆绑任何模型，它用的是你 AI 工具已经配置好的 API key。

所以说它”完全本地”不准确，说它”把代码发给云端”也不准确。准确的说法是：代码本地分析，语义内容按需走模型。

项目规模决定它值不值得用

我觉得这类工具最关键的判断条件就是项目大小。

不是”用了就一定更好”的工具，而是越大的项目、重复理解成本越高的场景，它的价值越突出。

不过反过来也成立：项目越大，图层出错之后的误导也越大。所以大项目更需要它，也更需要验证它的准确性。

它能演化出哪些形态

我觉得这类工具未来可能走向三种方向。

个人工具是目前 Graphify 最对口的形态。本地安装、本地扫描、本地生成图、本地跑 MCP server，供 Codex / Claude / Cursor 使用。部署极简，一个 CLI 加上 pip install graphifyy 就够了。优点是简单、隐私好、能处理未提交改动；缺点是团队之间不共享索引。

团队工具适合中大型团队。在 CI 里自动重建图，提交 graphify-out/ 目录让团队共享同一张地图，PR 里生成影响分析。这时候 container 才开始有意义，但也不一定要微服务化。

SaaS / 平台就是另一回事了。连接 GitHub/GitLab，后台 worker 扫 repo，存图，提供 web UI 和 MCP endpoint，做权限和审计。适合企业，但成本和隐私压力都大，离本地开发场景也更远。

这三种形态没有高下之分，部署方式要看它服务的对象是谁。个人 AI coding 用本地工具最好，企业代码智能才需要平台化。

如果让我来设计成熟版本

如果我来设计一个更成熟的版本，我会把它明确分成两层。

确定性核心负责文件扫描、代码解析、symbol 提取、import/call/reference 关系建立、增量更新、图查询。这一层尽量快、稳定、可重复，不依赖 LLM。

AI 语义层负责总结模块意图、解释业务流程、生成报告、处理文档/PDF/图片、回答更抽象的问题。这一层走模型，可以是云端，也可以是本地。

架构上大概是这样：

┌──────────────────────────┐
│ AI Coding Assistant       │
│ Codex / Claude / Cursor   │
└─────────────┬────────────┘
              │ MCP / CLI query
┌─────────────▼────────────┐
│ Graphify Adapter          │
│ CLI / MCP / report layer  │
└─────────────┬────────────┘
              │
┌─────────────▼────────────┐
│ Deterministic Index Core  │
│ scan / parse / graph      │
└─────────────┬────────────┘
              │
┌─────────────▼────────────┐
│ Local Graph Store         │
│ graphify-out/graph.json   │
└──────────────────────────┘

这个设计的重点是：AI 不直接扫整个世界；Graphify 先帮它找到方向；真正改代码前再读取真实文件。

最后的判断

我对 Graphify 的看法是：它是一个有意思的方向，尤其适合中大型项目，或者代码、文档、数据库 schema、配置文件混在一起的项目。

比如一个 Odoo 插件项目，里面有 Python model、XML view、CSV security、manifest、import wizard、数据库表设计——AI 每次从零开始读，确实浪费。Graphify 如果能先帮 AI 找到 model、view、access、menu、wizard 之间的关系，那是有价值的。

但我不会把它当成”可以替代 AI read repo”的东西。它最好的定位是帮 AI 少走弯路，而不是让 AI 不看真实代码。

最安全的规则是三句话：先查图，再读文件，再改代码。Graphify 负责告诉 AI 去哪里看，真实代码负责告诉 AI 现在到底是什么。

这样用，它可能是有价值的。只靠它省 token，而不验证质量，我觉得还不够。