Graphify 深读：把任意代码库变成可查询的知识图谱

它解决的是一类特定问题：Agent 反复重读原始文件的成本

Graphify 的核心场景是：你有一个包含代码、论文、截图、笔记的文件夹，每次让 AI Agent 理解项目全貌，它都要重新读一遍所有原始文件。文件少的时候无所谓，但文件一多，token 消耗和上下文窗口压力会迅速失控。

README 给出的数据是，在一个包含 Karpathy 仓库、5 篇论文和 4 张图片的 52 文件语料上，每次查询的 token 消耗比直接读原始文件低 71.5 倍。这个数字来自项目自带的 worked examples，不是第三方基准，但它指向的真实问题很明确：混合语料的结构化压缩。

Graphify 的做法是预先生成一张知识图谱，把文件内容变成节点和边，之后查询不再读原文，而是读图。图会持久化到 graph.json，几周后再查询也不需要重新解析。这个思路和 RAG 的向量检索不同，它不靠相似度匹配，而是靠显式的图结构导航。

缓存与增量更新：为什么 SHA256 缓存是设计的核心

Graphify 的输出目录里有一个 cache 文件夹，用 SHA256 哈希标记每个文件是否被处理过。这个设计决定了它的重复运行成本：只有变化的文件会被重新提取，没变的直接跳过。

--update 命令走的就是这条路径：重新提取变更文件，然后合并进现有图。--watch 模式更进一步，代码文件保存后立即触发 AST 重建，不经过 LLM；文档和图片变更则只通知用户，需要手动跑 --update 做 LLM 重新提取。这个区分很重要，因为 AST 解析是确定性的、本地的、几乎零成本，而 LLM 提取要花钱花时间。

Git commit hook 提供了另一种自动触发方式：每次提交后重建图，不需要后台进程。这对多 Agent 并行写代码的工作流有实际价值，图能在提交之间保持更新。但代价是每次提交都要跑一次图构建，提交频繁的仓库会积累不小的开销。

三种边标注：诚实地区分“找到的”和“猜的”

Graphify 的每条边都被标记为 EXTRACTED、INFERRED 或 AMBIGUOUS。这是它和很多知识图谱工具最大的区别。EXTRACTED 表示从 AST 或文档中直接提取到的关系，INFERRED 表示模型推断出来的关系，AMBIGUOUS 表示不确定。

这个设计直接回应了一个核心信任问题：用户怎么知道图里的哪条边是可靠的？README 里反复强调“honest about what it found vs guessed”，并把这一点作为项目的重要卖点。--mode deep 会启用更激进的 INFERRED 边提取，说明默认模式相对保守，用户可以选择提高召回率但降低精度。

这种标注体系对实际使用的影响很大。如果你要用图来回答架构问题，只信任 EXTRACTED 边就够了；如果要探索潜在关联，可以看 INFERRED 边，但要自己验证。没有这个区分，所有边混在一起，图的可靠性就无法评估。

多模态提取的不对称性：代码走 AST，图片走视觉模型

Graphify 对不同文件类型用了完全不同的提取路径。代码文件通过 tree-sitter 做 AST 解析，再跑 call-graph pass，这个过程是确定性的、本地的、不需要 LLM。文档和 PDF 则走 Claude 提取概念和关系。图片、截图、白板照片甚至其他语言的图片，全部交给 Claude vision。

这个不对称设计带来了一个重要的性能特征：代码文件的图构建可以完全本地完成，速度快且成本为零；文档和图片的提取则依赖 LLM API，速度慢且有 token 成本。README 没有说明代码和文档混合时 LLM 调用量如何控制，但从 cache 机制看，文档和图片的 LLM 提取结果会被缓存，避免重复调用。

这种分层的另一个好处是：代码图的结构精度高，因为 AST 不会猜，函数调用关系是确定的。而文档和图片提取的概念关系天然模糊，所以它们被归入 INFERRED 或 AMBIGUOUS 的概率更高。用户需要理解这个差异，否则会高估图在文档部分的可靠性。

输出形态的设计意图：从交互图到 Agent 可导航的 Wiki

Graphify 的输出不是单一格式，而是一组互补的文件。graph.html 是给人看的交互图，支持点击节点、搜索、按社区过滤。Obsidian 文件夹让用户可以在笔记工具里浏览图。wiki 模式生成 Wikipedia 风格的 markdown 文章，每个社区和 god node 一篇文章，入口是 index.md。

这个 wiki 输出特别值得注意。README 明确说它的目的是让 Agent 可以“通过读文件而不是解析 JSON 来导航知识库”。这意味着 Graphify 不仅给人用，也给下游 Agent 用。graph.json 是机器可读的持久化格式，wiki 则是 Agent 友好的中间层。

GRAPH_REPORT.md 里的 god nodes、surprising connections 和 suggested questions 是给人做快速概览用的。其中 surprising connections 的排序逻辑是：代码-论文边比代码-代码边排名更高，因为跨类型的关联更少见、更有信息量。每条结果附带自然语言解释，说明为什么这条边值得关注。

边界与判断

Graphify 的 token 压缩效果高度依赖语料规模。README 自己承认，6 个文件的情况压缩率接近 1x，因为文件本来就能塞进上下文窗口。图的真正价值在 52 文件级别才显现出来，是结构清晰度而非压缩率。

这个工具目前强绑定 Claude Code 生态。安装需要 Claude Code 和 Python 3.10+，PyPI 包名还是临时的 graphifyy，说明项目处于早期阶段。文档没有说明其他 LLM 的支持情况，也没有给出大规模代码库的性能数据。

对需要长期维护一个混合语料知识库、并且已经在用 Claude Code 的开发者，Graphify 的缓存机制和边标注体系值得一试。如果你只是想快速理解一个小项目，直接读文件可能更省事。建议先用它跑一个 50 文件左右的真实语料，对比 GRAPH_REPORT.md 的 god nodes 和 surprising connections 与你自己的判断，再决定是否纳入日常流程。

Graphify 值得关注，但它的价值兑现取决于你的语料规模和是否接受 Claude 生态绑定。