10万星的graphify：把代码库变成知识图谱，一条命令干掉向量检索
10万星的graphify：把代码库变成知识图谱，一条命令干掉向量检索
先收藏，回头一定用得上。
Andrej Karpathy 有个习惯：他在电脑里维护一个 /raw 文件夹，往里面随手扔论文、推文、截图、笔记。时间一长，这个文件夹变成一个黑洞--东西都在，但谁也找不到什么在哪。
graphify 就是冲着这个问题来的。它在 Claude Code 里输入 /graphify .，读取你的整个目录--代码、文档、PDF、截图、白板照片、甚至其他语言的图片--把这些东西解析成一张知识图谱。每条边都标注是"发现的"还是"推测的"，每个节点都可以点击溯源到原始文件。
这个项目 4 月份上线，到现在 10 万+ star，Apache 2.0 开源。它做了一件很具体的事：用确定性 AST 解析替代向量检索，用知识图谱替代 embedding 数据库，让 AI Agent 查代码库时不用再"猜"。
本文提纲
- 核心问题：为什么向量检索查代码不靠谱
- graphify 是什么：一条命令，一张图
- 技术架构：tree-sitter + Leiden + Claude vision
- 四种文件类型，四种提取策略
- 边的诚实标注：EXTRACTED / INFERRED / AMBIGUOUS
- Token 压缩实测：71.5 倍是怎么来的
- Agent 集成：Claude Code、Cursor、Codex、Gemini CLI
- 实际用起来什么样
核心问题：为什么向量检索查代码不靠谱
当前 AI 编码助手查代码库的主流方案是 RAG（检索增强生成）：把代码切块、做 embedding、存进向量数据库，查询时用相似度检索找相关的块喂给 LLM。
这个方案在文档检索上还行，但在代码上有几个结构性问题：
语义相似不等于结构相关。 UserAuth 类和 loginHandler 函数在向量空间里可能很近，但它们的调用关系、依赖链、数据流向才是真正重要的连接。向量检索按文本相似度排序，抓不到这些结构关系。
切块破坏了上下文。 一个函数被切成两半，一个类的定义和实现被分到不同的 chunk，embedding 之后就丢失了它们之间的结构关系。代码的本质是图结构--调用关系、继承关系、导入关系--不是线性文本。
结果不可溯源。 向量检索返回的是"最相似的 N 个块"，但不告诉你为什么相似，也不告诉你这些块之间有什么关系。LLM 拿到一堆碎片化的代码块，很容易产生幻觉。
graphify 的思路是：别把代码当文本检索，把它当图遍历。代码的结构关系是确定性的--谁调用了谁、谁继承了谁、谁导入了谁--这些可以通过 AST 精确提取，不需要猜。
graphify 是什么：一条命令，一张图
graphify 是一个 Claude Code Skill。安装后在任何目录输入 /graphify .，它会：
- 扫描目录下所有支持的文件
- 对代码文件用 tree-sitter 做 AST 解析，提取函数、类、调用关系
- 对文档和论文用 Claude 做概念提取和关系推断
- 对图片用 Claude vision 做内容识别
- 把所有节点和边合并成一张知识图谱
- 运行 Leiden 社区发现算法，把节点聚类成主题社区
- 输出一组可交互的文件
graphify-out/
├── graph.html 可交互图谱 - 点击节点、搜索、按社区过滤
├── obsidian/ 可直接用 Obsidian 打开的 vault
├── wiki/ Wikipedia 风格的文章（--wiki 参数）
├── GRAPH_REPORT.md God 节点、意外连接、建议问题
├── graph.json 持久化图谱 - 几周后查询不用重新读文件
└── cache/ SHA256 缓存 - 重新运行只处理变更的文件最关键的产出是 graph.json。这是一个持久化的图谱数据结构，Agent 可以在后续会话中直接查询，不需要重新读取原始文件。这就是 71.5 倍 Token 压缩的来源--原始文件可能几十 MB，graph.json 可能就几百 KB。
技术架构：tree-sitter + Leiden + Claude vision
graph TB
subgraph "Input"
A["Code Files"]
B["Docs / Markdown"]
C["PDFs"]
D["Images / Screenshots"]
end
subgraph "Extraction Layer"
E["tree-sitter AST
+ call-graph pass"]
F["Claude concept
+ relationship extraction"]
G["Citation mining
+ concept extraction"]
H["Claude vision
multilingual OCR"]
end
subgraph "Graph Engine"
I["NetworkX
graph construction"]
J["Leiden algorithm
community detection"]
end
subgraph "Output"
K["graph.json
graph.html
GRAPH_REPORT.md"]
end
A --> E
B --> F
C --> G
D --> H
E --> I
F --> I
G --> I
H --> I
I --> J
J --> K
style A fill:#FF6B6B,color:#000000
style B fill:#4ECDC4,color:#000000
style C fill:#45B7D1,color:#000000
style D fill:#96CEB4,color:#000000
style E fill:#FFEAA7,color:#000000
style F fill:#FFEAA7,color:#000000
style G fill:#FFEAA7,color:#000000
style H fill:#FFEAA7,color:#000000
style I fill:#DDA0DD,color:#000000
style J fill:#DDA0DD,color:#000000
style K fill:#98D8C8,color:#000000技术栈拆开看：
tree-sitter 做代码解析。 tree-sitter 是 GitHub 开源的增量解析库，支持 50+ 编程语言。graphify 用它做 AST 解析，提取函数定义、类定义、函数调用、类继承、模块导入等结构信息。这些边是 EXTRACTED--确定性的，不是猜的。
NetworkX 做图存储。 Python 的图处理库，节点是代码实体（函数、类、概念），边是关系（调用、继承、导入、引用）。不需要 Neo4j，不需要数据库服务器，纯内存计算。
Leiden 算法做社区发现。 Leiden 是 Louvain 算法的改进版，用来在图中发现"社区"--紧密连接的节点群。在代码库里，一个社区通常对应一个功能模块或主题领域。这让 graphify 能告诉你"你的代码库可以分成这几个主题"。
Claude vision 做多模态提取。 PDF 做引用挖掘和概念提取，图片做内容识别--截图、架构图、白板照片、甚至其他语言的图片都能处理。这是 graphify 区别于纯代码分析工具的地方：它不只是分析代码，它把整个工作目录当成一个多模态知识库。
vis.js 做交互式可视化。 生成的 graph.html 可以在浏览器里打开，点击节点、搜索、按社区过滤。不需要安装任何额外软件。
整个技术栈完全本地运行。官网原话："no account, no API keys, no telemetry。"除了调用 Claude API 做概念提取和 vision 之外，不需要任何云服务。
四种文件类型，四种提取策略
graphify 不是一刀切地处理所有文件，而是按文件类型用不同的策略：
| 文件类型 | 扩展名 | 提取策略 |
|---|---|---|
| 代码 | .py .ts .js .go .rs .java .c .cpp .rb .cs .kt .scala .php |
tree-sitter AST + call-graph pass |
| 文档 | .md .txt .rst |
Claude 概念和关系提取 |
| 论文 | .pdf |
引用挖掘 + 概念提取 |
| 图片 | .png .jpg .webp .gif |
Claude vision - 截图、图表、任何语言 |
这种分策略的设计很关键。代码的结构关系是确定性的，用 AST 精确提取，标注为 EXTRACTED。文档和图片的语义关系需要 LLM 推断，标注为 INFERRED 或 AMBIGUOUS。不同来源的边有不同的可信度，用户和 Agent 都能据此判断信息的可靠性。
--mode deep 参数可以让 LLM 做更激进的推断边提取。默认模式偏保守，只提取高置信度的关系；deep 模式会尝试连接更多"可能相关"的节点，适合探索性分析。
边的诚实标注：EXTRACTED / INFERRED / AMBIGUOUS
这是 graphify 最打动我的设计。
每条边都带一个标签：
- EXTRACTED：从文件中确定性提取的。比如
loginHandler调用了validateToken--这是 AST 解析出来的，100% 准确 - INFERRED：LLM 推断的。比如一篇论文里的"attention mechanism"概念和代码里的
MultiHeadAttention类--LLM 认为它们相关，但不是代码层面的直接调用 - AMBIGUOUS：LLM 不确定的。标注出来让用户或 Agent 自己判断
这个设计解决了 RAG 方案的一个根本问题：不可溯源。向量检索返回结果时不告诉你"为什么这个块相关"，graphify 明确告诉你每条边的来源和可信度。
对 Agent 来说这特别重要。Agent 在做决策时需要知道哪些信息是确定的、哪些是推测的。如果一条调用关系是 EXTRACTED，Agent 可以放心依赖；如果是 INFERRED，Agent 知道需要验证。这种元信息让 Agent 的推理更可靠。
Token 压缩实测：71.5 倍是怎么来的
graphify 在 README 里给出了实测数据：
| 语料 | 文件数 | Token 压缩倍数 |
|---|---|---|
| Karpathy 仓库 + 5 篇论文 + 4 张图片 | 52 | 71.5x |
| graphify 源码 + Transformer 论文 | 4 | 5.4x |
| httpx（合成 Python 库） | 6 | ~1x |
几个关键观察：
压缩倍数和语料规模正相关。 6 个文件时压缩只有 1 倍--因为 6 个文件本身就能塞进上下文窗口，图谱的价值在于结构清晰而非压缩。52 个文件时达到 71.5 倍--因为 graph.json 的体积远小于原始文件总和，而且 Agent 查询时只需要遍历相关子图，不用读全部文件。
混合语料效果最好。 纯代码的压缩效果不如"代码+论文+图片"的混合语料。原因是跨类型的连接（比如代码和论文之间的概念映射）是图谱独有的价值--向量检索很难跨模态匹配，但图谱可以用概念节点桥接不同类型的文件。
每个 worked example 都可复现。 graphify 在仓库的 worked/ 目录下放了原始输入文件和实际输出（GRAPH_REPORT.md、graph.json），你可以自己跑一遍验证数字。这种透明度在开源项目里不多见。
Token 压缩的意义不只是省钱。对 Agent 来说，上下文窗口是有限的--如果一个 52 文件的代码库要占用大部分上下文，Agent 就没有空间做推理了。图谱压缩释放了上下文空间，让 Agent 能处理更大的代码库。
Agent 集成：Claude Code、Cursor、Codex、Gemini CLI
graphify 不仅仅是一个独立的 CLI 工具，它的核心定位是 AI 编码助手的 Skill。当前支持的平台：
安装方式：
pip install graphifyy && graphify installPyPI 包名暂时叫
graphifyy（正在回收graphify这个名字），CLI 命令和 Skill 名称仍然是graphify。
安装后在任何目录打开 Claude Code 输入：
/graphify .常用命令一览：
/graphify . # 在当前目录构建图谱
/graphify ./raw --mode deep # 更激进的推断边提取
/graphify ./raw --update # 只重新提取变更文件，合并到已有图谱
/graphify query "what connects attention to the optimizer?"
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"
/graphify ./raw --watch # 文件变更时自动同步图谱
/graphify ./raw --wiki # 生成 Agent 可导航的 wiki
/graphify ./raw --mcp # 启动 MCP stdio server
graphify hook install # 安装 git post-commit hook，每次提交自动重建图谱几个值得注意的集成设计：
--update 增量更新。 graphify 用 SHA256 缓存每个文件的解析结果。重新运行时只处理变更的文件，合并到已有图谱。对大型代码库来说，第一次构建可能要几分钟，后续更新只需要几秒。
--watch 实时同步。 在后台终端运行，代码文件保存时触发即时重建（只走 AST，不调 LLM）。文档和图片变更时通知你运行 --update 做 LLM 重新提取。这对多 Agent 并行写代码的场景特别有用--图谱在各轮之间自动保持最新。
--mcp MCP Server。 启动一个 MCP stdio server，任何支持 MCP 的客户端都可以查询图谱。这意味着 Cursor、Codex、Gemini CLI 等不支持 Claude Code Skill 的工具也能用 graphify。
--wiki Agent 可导航 wiki。 生成 Wikipedia 风格的 markdown 文章，每个社区一篇，配一个 index.md 入口。Agent 可以通过读文件来导航知识库，不需要解析 JSON。这个设计很巧妙--对不支持图谱查询的 Agent 来说，markdown 文件是最通用的接口。
Git hook 集成。 graphify hook install 安装一个 post-commit hook，每次 git commit 后自动重建图谱。不需要后台进程，适合不想开 --watch 的场景。
实际用起来什么样
graphify 的输出报告 GRAPH_REPORT.md 包含三个部分：
God 节点。 度数最高的概念节点--也就是所有东西都连到它的"枢纽"。在一个代码库里，God 节点通常是核心数据结构或基础工具函数。找到 God 节点等于找到了代码库的"重心"。
意外连接。 按综合分数排序，代码-论文的边排名高于代码-代码的边。每条结果都附带一段英文解释"为什么这条连接是意外的"。这是图谱分析最有价值的产出--它帮你发现你自己都没意识到的跨模块、跨文件类型的联系。
建议问题。 4-5 个图谱特别擅长回答的问题。不是泛泛的"你想了解什么"，而是基于图谱结构生成的具体问题--比如"attention 机制和优化器之间有什么联系？"
整个流程完全透明：每个节点可溯源到原始文件，每条边标注了提取方式和可信度，缓存机制让重新运行成本很低。你可以在 graph.html 里可视化探索，也可以用 graphify query 命令行查询，还可以通过 MCP server 让 Agent 自动查询。
一个实际建议：先用 worked/ 目录下的示例跑一遍，看看 52 个文件的 Karpathy 语料生成什么样的图谱和报告，理解了再在自己的项目上跑。直接在大项目上跑第一次会等比较久，而且如果结果不符合预期你不知道是工具的问题还是你项目的问题。
10 万 star 不是没原因的。graphify 做对了一件难而正确的事：用确定性方法替代概率性方法，用图结构替代向量空间，用诚实标注替代黑盒检索。如果你在用 Claude Code 或 Cursor 做大型代码库的开发，这个 Skill 值得试一下。
参考文档与链接
- GitHub: Graphify-Labs/graphify - 105497 star，Apache 2.0，Python，核心仓库
- graphify 官网 - 产品介绍，"the code knowledge graph for AI coding assistants"
- graphify README - 安装指南、命令参考、worked examples
- graphify ARCHITECTURE.md - 模块职责和如何添加新语言支持
- tree-sitter - graphify 使用的增量解析库，支持 50+ 编程语言
- Leiden 算法 - graspologic - graphify 使用的社区发现算法实现
- NetworkX - Python 图处理库，graphify 的图存储引擎
- worked/karpathy-repos/ - 52 文件混合语料的完整示例，含原始输入和图谱输出
- Claude Code Skills 文档 - graphify 作为 Skill 的运行机制
- MCP (Model Context Protocol) - graphify
--mcp模式启动的 MCP server 协议
你的代码库多大？查代码用grep还是RAG？评论区聊聊。觉得有用点个赞让更多人看到。
作者: itech001 来源: 公众号：AI人工智能时代 网站: https://www.theaiera.cn/ 每日分享最前沿的AI新闻资讯和技术研究。
本文首发于 AI人工智能时代，转载请注明出处。
