来源：DeepHub IMBA
本文约3000字，建议阅读5分钟
那些 agent 真正需要的，是对代码库的结构化理解，而不只是文件搜索。
Graphify 是一个 Python 工具，同时也是一个 Claude Code skill。它把分析工作一次性做完，把所有内容压缩成一张可查询的知识图谱，放到磁盘上。后续查询走图谱遍历，不再重新读取原始文件。项目简介的数字是：在混合语料库上每次查询的 token 量降低 71.5 倍。虽然这个数字是项目方自己测的是否站得住脚还要验证，但是他的底层架构思路比同类工具普遍要更细致一些。


大型代码库的 Token 税

上下文窗口一直在在变大——Claude Sonnet 4.6 支持 200K，GPT-5.4 已经到 1M——但麻烦的从来不是窗口大小而是成本和延迟。如果每次查询都把 200 个文件喂进去不仅贵而且慢；而且对任何一个具体问题来说，那 200 个文件里的绝大多数信息都是无关的。等于为了找一个段落把整座图书馆搬过来。
业界的标准答案是 RAG：把文件切块、嵌入、丢进向量库，查询时取 top-K 块。对散文类文档，RAG 工作得很好——语义相似度本身就是一个靠谱的检索信号。但对代码就不一样了：函数和它的调用者之间的关系是结构性的，不是语义性的。"process_payment 调用 validate_card"这种事实不存在于嵌入空间里，它存在于调用图里。
Graphify 的方法不一样，他不嵌入文件、不靠相似度检索，而是把实体和关系建成一张显式图谱，查询时在图上做遍历。这种方式其实更接近一个资深工程师摸陌生代码库的方式——先在脑子里搭起系统的结构，再顺着结构走，而不是对源代码做一次模糊搜索。
Graphify 产出什么

在某个目录下跑一次 /graphify，会在 graphify-out/ 目录里生成几样东西：一个用 vis.js 渲染的交互式 HTML 图谱，节点是实体（函数、类、概念、文档章节），边是关系（调用、import、引用、推断出来的依赖）；一份用于程序化查询的持久化 JSON 图谱；一份 Markdown 报告，标出度数高的节点和社区聚类。可选输出还包括 Obsidian vault、Neo4j 数据库、SVG、GraphML 文件，以及把整张图谱作为 LLM 可调用工具暴露出来的 MCP server。
聚类用的是 Leiden 社区检测算法。一个同时包含 auth、billing 和 infra 模块的 monorepo，Graphify 会自动把这三块识别成不同的社区，并把它们之间的桥接节点显式标出来。


三套不同的数据处理逻辑

理解 Graphify 最关键的部分就是，它不会用同一种方式对待所有文件类型——三个 pass 各跑各的，每一个的数据驻留策略也完全不一样。
Pass 1：确定性 AST 提取（代码不出本机）

源代码文件交给 tree-sitter，一个基于规则的确定性解析器。可以把它理解为编译器的前端：读文件、套形式语法、吐出语法树。整个过程没有语言模型介入，没有任何网络调用，源代码不会离开你的机器。
tree-sitter 支持 23 种语言，Python、TypeScript、JavaScript、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP 都在内。输出是一组节点和边的字典，把源文本中显式存在的每一个函数、类、import 和调用关系都编码出来。
这一步重要在两点。一是免费，没有 API 成本；二是精确——AST 提取出的关系会带上 EXTRACTED 置信度标签，意味着它们是事实，不是猜测。
Pass 2：本地音频转录（录音也不出本机）

把 Graphify 指向一个含有音频或视频的目录，它会用 faster-whisper 在本机完成转录，音频不上传到任何地方。这个 pass 是可选的，需要装 graphifyy： pip install "graphifyy"
faster-whisper 是 OpenAI Whisper 模型的 CTranslate2 加速实现。在一台普通笔记本上，转录一小时的会议音频只要几分钟。生成的转录文本会作为文档节点喂进图谱，和别的文本一视同仁。
Pass 3：语义提取（文档和图像会发到你的 AI API）

文档（Markdown、PDF、RST）和图像（PNG、JPG、WebP、GIF）没法用语法解析——它们的结构是语义层面的，不是句法层面的。要从一张白板照片或一份研究 PDF 里提取实体和关系，Graphify 会调用你已经配好的 AI 平台，可能是 Anthropic、OpenAI 或别的。
关键词是"你的"。Graphify 用的是你 AI 平台环境里已经配好的凭证，没有中央中继服务器。流量从你的机器直接发到 Anthropic（或者 OpenAI 等等），用的就是你日常给编码助手用的那把 API key。
Graphify 自己什么都不收。SECURITY.md 写得很直白："在图谱分析期间不发起任何网络调用。"项目同时声明：没有遥测、没有使用追踪、没有任何形式的分析。Graphify 也不存凭证。
完整的数据流大致如下：

需要点出的细节：你的 AI 提供商（Anthropic、OpenAI）确实会看到你的文档和图像内容，约束条件是你和它们之间的 API 协议。如果文档里有敏感信息，跑 Pass 3 之前先翻一遍提供商的数据处理政策。也可以把 Graphify 限制成仅代码模式，把 Pass 3 整个跳过。
置信度系统：知道图谱"知道"到什么程度

图谱里的每条边都带一个置信度标签，三选一。这是一个看起来很小的设计决定，落到使用上影响很大。
EXTRACTED 表示这条关系在源代码里是显式存在的。validate_card 被 process_payment 调用，这写在 AST 里，可以直接信任。
INFERRED 表示这条关系是模型从上下文推理出来的。语义提取器看到 PaymentService 和 FraudDetector 在文档里总是一起出现，于是推断出一条依赖。可能对，也可能只是巧合。
AMBIGUOUS 表示模型自己也拿不准。这类边会留在图谱里，但没有人工复核就不应该被拿去做判断依据。
打个比方：EXTRACTED 像带页码的引文，INFERRED 像一句"另见某处"的脚注，AMBIGUOUS 像贴了张"再核实一下"的便签。Graphify 的做法是把三种都给你，并打好标签；它没有把所有东西包装成一副笃定的样子。
上手

这个包需要Python 3.10+，安装好 Claude Code。 # 安装包pip install graphifyy# 把 skill 注册到你的 AI 平台graphify install
graphify install 会探测你已配置的平台，把 skill 定义注入到对应的配置文件里——比如 Claude Code 的 ~/.claude/CLAUDE.md。
可选依赖按需装： # 本地音频/视频转录pip install "graphifyy"# Microsoft Office 文件支持（.docx、.xlsx）pip install "graphifyy"# MCP server（把图谱作为 LLM 工具暴露）pip install "graphifyy"# 一次装全pip install "graphifyy"
运行命令： # 在 AI 助手里对当前目录做标准分析/graphify# 深度模式：更激进的关系推断/graphify --deep# 处理特定子目录/graphify ./src/auth# Watch 模式：文件变化时重建图谱/graphify --watch# 查询已有图谱/graphify query "how does user authentication flow through the system?"# 查找两个实体之间的最短路径/graphify path "UserService" "DatabasePool"# 用自然语言解释某个实体/graphify explain "PaymentProcessor"
后续运行时，Graphify 会比对 SHA256 哈希——只有改动过的文件会被重新处理。第一次导入是贵的那一次，重复查询很便宜。
也可以让它接管 git hook，每次提交都自动重建图谱： # 在仓库内，Graphify 可以安装自己的 git hooks/graphify --install-hooks
之后