Graphify 知识图谱实测：把代码库和资料转成 AI 可查询知识库的完整教程

Graphify 是什么？为什么你需要一个代码库知识图谱？

如果你经常用 AI 编程助手（比如 Claude Code 或 Codex），一定遇到过这种场景：项目文件夹里塞满了代码、PDF 论文、截图和笔记，想问一个问题，AI 得先把所有文件读一遍才能理解上下文。这个痛点被 Andrej Karpathy 在一个广为流传的工作流中描述过——你有一个 /raw 文件夹，里面什么都有，但关联全靠脑子记。Graphify 就是为了解决这个问题而生的。它本质上是一个 AI 编程助手的“技能插件”，能把任意文件夹中的代码、文档、论文、图片转成一个可查询的知识图谱。一次性构建之后，后续每次提问只需消耗原始 token 的约 1/71.5（数据来自源文章测试，实际节省效果可能因项目而异）。

Graphify 是 MIT 许可的开源项目，在 GitHub 上已经有 2.2k 左右的 star（数据来自撰写时的快照，建议查询最新数值）。它支持四款主流的 AI 编程平台：Claude Code、Codex、OpenCode 和 OpenClaw。下面我们就从核心机制开始，一步步拆解这个工具怎么用、好在哪、坑在哪里。

前置条件

在开始使用 Graphify 之前，确保你的环境满足以下条件：

• Python 版本：Graphify 需要 Python 3.8 或更高版本。可以用 python --version 确认。
• pip 包管理器：用于安装 Graphify 及其依赖。
• AI 编程平台：Claude Code、Codex、OpenCode 或 OpenClaw 之一已安装并可用。
• 项目文件夹：一个包含了代码、文档或图片的文件夹（即你想建立知识图谱的目标目录）。
• Git（可选）：如果启用 Git Hooks 自动更新，需要项目已初始化 Git 仓库。

不在源文件类型范围内的文件（如二进制文件、大视频）会被自动忽略，不会影响构建。

核心工作机制：双通道提取与置信度体系

Graphify 的提取引擎分为两个完全独立的通道，可以同时跑，互不干扰。

AST 提取：零 LLM 开销的代码分析

对于代码文件，Graphify 使用 tree-sitter 做抽象语法树分析。这一步不需要调用任何大模型，所以 token 消耗为零。它支持 15 种编程语言：Python、TypeScript、JavaScript、Go、Rust、Java、C/C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua。提取的内容包括类定义、函数签名、导入关系、调用图、文档字符串，以及代码注释中带有 # WHY:、# HACK:、# NOTE: 等标记的设计决策。AST 通道只有几毫秒到几秒的延迟，即使项目有上千个文件也能快速完成。

语义提取：用 LLM 分析文档和图片

对于非代码文件——Markdown、TXT、rST 文档、PDF 论文、PNG/JPG/WebP/GIF 图片——Graphify 会用 LLM 子代理进行概念抽取。图片会经过视觉模型分析，PDF 会做引用挖掘和概念提取。这个通道会产生 token 开销，所以只处理你真正需要建立语义关联的材料。如果你一次性扔进去几十篇 PDF，首次构建的 token 消耗可能不小，建议先筛选出最有价值的资料。

三级置信度标签

每条关系边（两个节点之间的连接）都会被标记为三种等级之一：

这套标签体系是 Graphify 的设计哲学——对自己“找到了什么”和“猜了什么”保持诚实。你能一眼看出哪些关系是铁证，哪些只是猜测。当你在 Code Review 时面对 INFERRED 边，就知道需要手动验证一下。

社区检测：Leiden 算法

Graphify 使用 Leiden 算法（基于 graspologic 库）做社区发现。它完全依赖于图的边密度拓扑，不需要任何嵌入向量或向量数据库。这意味着即使你只有几十个节点，也能清晰地看到模块边界。LLM 提取出的语义相似性边（标记为 INFERRED）也会参与社区检测，让非代码概念也能自动聚类。运行 --cluster-only 可以在不重新提取的前提下重新划分社区，适合迭代调整。

在 Claude Code 中完整使用 Graphify

下面是从零开始在 Claude Code 上部署 Graphify 的完整流程。

安装 Graphify

pip install graphifyy
graphify install --platform claude

第二条命令会把 skill-claude.md 文件复制到 ~/.claude/skills/graphify/SKILL.md，这就是 Claude Code 读取技能指令的标准路径。

构建初始图谱

在项目根目录打开 Claude Code，输入：

/graphify .

Graphify 会扫描整个文件夹，代码文件走 AST 提取（瞬时完成），文档/图片走语义提取（需要几秒到几分钟，取决于文件数量和大小）。完成后会输出四个核心产物：

• graph.html：交互式可视化图，可以在浏览器里点节点、搜索、按社区筛选。
• GRAPH_REPORT.md：审计报告，包含上帝节点、惊人连接、建议问题。
• graph.json：持久化图数据，可以跨会话查询。
• cache/ 目录：SHA256 缓存，用于后续增量更新。

验证方法

构建完成后，用以下方法快速验证图谱是否正常：

1. 打开 graph.html，查看是否有节点和边显示，节点是否按社区着色。
2. 阅读 GRAPH_REPORT.md，确认“上帝节点”和“惊人连接”是否与项目结构吻合。
3. 运行一个简单查询测试：/graphify query "项目中最重要的类是什么？"，看 Claude 是否基于图谱回答而非直接读文件。
4. 如果启用了 Git Hooks，修改一个代码文件后提交，检查图谱是否自动重建（观察 graphify-out/cache/ 的时间戳变化）。

如果以上都正常，说明集成成功。如果 graph.html 空白或查询返回“未找到相关节点”，可能是项目中没有受支持的文件类型，或者路径不对。

使用查询命令

构建完成后，你可以用这些命令交互式探索：

比如想知道修改 DigestAuth 后为什么 Response 的测试会挂，输入 /graphify path "DigestAuth" "Response"，返回类似：DigestAuth --calls--> AuthFlow --sharesdatawith--> RequestBuilder --implements--> Response，每一步都标明了关系类型和置信度。

启用自动维护

接着执行两条命令，让图谱永远和代码保持同步：

graphify claude install
graphify hook install

第一条会在项目的 CLAUDE.md 写入指令，让 Claude 每次回答架构问题前先查图谱，并注册 PreToolUse hook——在每次 Glob/Grep 操作前自动提醒它查看图谱。第二条会安装 Git post-commit 和 post-checkout 钩子，每次提交和切换分支后自动重建图谱（仅代码文件，零 LLM 开销）。如果重建失败，Git 会报错，你不会不知不觉地使用过期数据。

之后你正常提问、正常 commit，Graphify 就在后台悄悄工作。对于 Claude Code 的详细部署和安全配置，可以参考我们之前写的《Claude Code 云服务器部署与安全使用指南》。

增量更新

当你修改了一些文件后，只需运行：

/graphify . --update

Graphify 会对比 SHA256 缓存，只对变更的文件重新提取。如果只改了代码文件，它会自动跳过语义提取（零 LLM 开销），只跑 AST。更新完成后还会展示图谱 diff——新增了哪些节点、多少条边。

在 OpenClaw 中的集成与差异

OpenClaw 是另一款主流的 AI 编程平台，但它的集成方式和 Claude Code 有几个关键区别。

安装命令不同

pip install graphifyy && graphify install --platform claw

这会把 skill-claw.md 复制到 ~/.claw/skills/graphify/SKILL.md。

语义提取是顺序模式

OpenClaw 的多代理支持还处于早期阶段，所以语义提取是逐文件顺序执行的，而不是 Claude Code 那样的并行提取。这意味着首次构建会慢一些，但结果完全一致。AST 提取（代码文件）不受影响，仍然是瞬时完成的。如果你在 OpenClaw 上构建大型项目，建议先用纯代码文件夹测试，确认流程正常后再加入文档和图片。

Always-on 通过 AGENTS.md 实现

当你在 OpenClaw 中执行 graphify claw install，它会在项目根目录写入一个 AGENTS.md 文件，而不是 Claude Code 用的 CLAUDE.md。内容包含一个 ## graphify 段落，指示 OpenClaw 在回答架构问题前先读 GRAPH_REPORT.md，如果存在 wiki 目录则优先导航 wiki，修改代码后自动触发重建。

要注意，OpenClaw 没有 PreToolUse hook 机制——它不能像 Claude Code 那样在每次 Glob/Grep 前自动提醒。AGENTS.md 是唯一的 always-on 手段。所以你在 OpenClaw 中需要更主动地触发查询。

查询和卸载

查询命令与 Claude Code 完全一样（/graphify query、/graphify path、/graphify explain）。卸载命令是：

graphify claw uninstall

这会从 AGENTS.md 中移除 graphify 段落；如果文件变空，会直接删除它。

对比 Claude Code 和 OpenClaw 的差异，如果你在做跨平台选择，也可以看看《2026年AI编程工具深度解析：OpenCode、Claude Code与GitHub Copilot全面对比》。

输出格式与外部工具集成

Graphify 的一次运行能同时产出多种格式，适应不同的使用场景。

核心输出（始终生成）

• graph.html：交互式可视化图，节点按社区着色，支持搜索和点击查看邻居。
• GRAPH_REPORT.md：审计报告，包含“上帝节点”（被最多节点连接的核心概念）、“惊人连接”（意想不到的跨模块关联）和“建议问题”（图谱最擅长回答的架构问题）。
• graph.json：持久化图数据，可用于跨会话查询或二次开发。
• cache/：SHA256 缓存目录，支持增量更新。

可选输出（通过参数启用）

MCP 服务器模式详解

--mcp 模式启动一个 MCP 服务器，暴露 querygraph、getnode、getneighbors、shortestpath 等工具接口。你可以把它加入 Claude Desktop 的 MCP 配置，让其他 agent 也能实时查询这张图谱。这对于团队协作或跨工具集成特别有用。

实战用例：从快速理解代码库到永久自动维护

下面精选几个最实用的场景，每个都配有具体命令和预期结果。

用例 1：5 分钟吃透一个陌生项目

你刚接手一个几十个文件的 Python 项目，完全不知道从哪里看起。运行 /graphify .，几分钟后你就能看到：

直接看 GRAPH_REPORT.md 就行了，不需要读一行代码。

• 上帝节点：比如某个 BaseHandler 类被 15 个模块依赖。
• 惊人连接：日志模块和认证模块共享同一个配置解析器。
• 建议问题：图谱最擅长回答的 4-5 个架构问题。

用例 2：追踪两个模块之间的依赖链路

Code review 时你发现改了 DigestAuth 后 Response 的测试挂了，但不知道它们之间怎么关联的。输入：

/graphify path "DigestAuth" "Response"

返回类似 DigestAuth --calls--> AuthFlow --sharesdatawith--> RequestBuilder --implements--> Response，每一跳都标注了关系类型、置信度和源码位置。你立刻知道中间经过了 AuthFlow 和 RequestBuilder，而且 AuthFlow 到 RequestBuilder 是推断出来的（置信度 0.82）。

用例 3：深度理解一个核心模块

想知道项目中最重要的 Gateway 模块到底做了什么？输入：

/graphify explain "Gateway"

返回该节点度数、所有邻居节点、关系类型和源码位置。Claude 会基于这些图数据写一段结构化解释，每个论断都有 source_location 引用。

用例 4：往图谱里加外部资料

你读到一篇和项目相关的论文，想让它自动融入图谱：

/graphify add https://arxiv.org/abs/1706.03762

Graphify 自动抓取摘要和元数据，保存为 Markdown 到 ./raw 目录，然后触发 --update，只处理新文件。论文中的概念会和代码中的已有节点自动建立跨模态关联。同样支持推文、任意网页和图片 URL。

用例 5：实现永久自动维护

执行这两条命令后就可以忘掉 Graphify 了：

graphify claude install
graphify hook install

你正常提问，Claude 自动查图谱；你正常 commit，图谱自动更新。偶尔想调整社区划分，可以运行 /graphify . --cluster-only，重新跑一次 Leiden 检测，零 token 开销。

用例 6：激进关系发现（--mode deep）

如果你在做架构审计或准备重构，想发现更多潜在关联，可以用 deep 模式：

/graphify . --mode deep

语义提取的子代理会更激进地推断 INFERRED 边——间接依赖、共享假设、潜在耦合都会被标注出来。不确定的用 AMBIGUOUS 标记而不是省略。

核心功能与使用建议

Graphify 的主要功能可以概括为：

• 双通道知识提取：AST 通道零 token 消耗分析代码结构，语义通道按需分析文档和图片。
• 置信度标签：每条关系都标注可靠性，让你区分事实与推断。
• 多平台技能插件：深度集成 Claude Code、Codex、OpenCode、OpenClaw。
• 多种输出格式：交互式可视化、Obsidian 知识库、Neo4j 图数据库、Wiki 风格文档等。
• 自动化维护：Git Hooks 和文件监听实现增量更新。

价格与限制：Graphify 是完全免费的开源 MIT 项目，无需付费。但使用过程中需要消耗您自己的 LLM token（语义提取时），以及运行 Graphify 所在机器（可以是本地或 VPS）的 CPU/内存资源。对于特别大的项目（几十万行代码 + 数百个文档），首次语义构建可能需要大量 token，建议分批添加。

替代工具：目前市场上没有直接替代品。如果你只需要代码依赖图，可以用 pydeps（Python）或 dependency-cruiser（JavaScript）；如果你需要纯文档知识图谱，可以用 Obsidian 配合 Graph View 插件。但将代码和文档同时打通并配套 AI 编程助手的，Graphify 是独一份。

适合谁、不适合谁

适合：

• 经常使用 AI 编程助手（Claude Code、Codex、OpenCode、OpenClaw）的开发者。
• 维护大型项目、需要快速理解架构的团队。
• 做个人知识库管理，想把论文、截图、代码笔记互相关联的研究者。
• 负责团队 onboarding，希望自动化生成架构文档的 tech lead。

不适合：

• 项目只有零散的几个文件，手动维护就够用的场景。
• 不使用上述 AI 编程平台，只想要图谱可视化工具（可以只用输出格式中的 --svg 或 --graphml，但体验不如专用图工具）。
• 对 token 消耗敏感的离线开发者（语义提取需要联网调用 LLM）。
• 项目文件夹中有大量无法被 tree-sitter 或 LLM 理解的自定义 DSL 文件（需要额外配置或忽略）。

什么时候用、什么时候不用

• 用 Graphify 的场景：接手新项目、做架构重构、写技术文档时，它能帮你快速建立全景认知。
• 不必用的场景：项目只有 5 个文件且你已经烂熟于心；临时用一下 AI 助手写代码但不关心长期知识积累。

另外提醒：文中提到的 2.2k stars、1/71.5 的 token 节省比例，均来自源文章撰写时的测试，实际数据以项目主页为准。最新代码请访问 Graphify GitHub 仓库（需人工核实该地址是否准确，如无法访问请直接搜索“graphifyy”）。

如果你经常需要理解新项目、管理个人知识库，或者做团队架构文档自动化，Graphify 值得一试。先从一个小的 Python 项目开始，运行 /graphify . 看看生成的 report 和可视化图，你能马上感受到差距。更多 AI 编程工具的实战方法，可以参考我们之前整理的《AI 编程工具推荐 2026：从代码补全到 Coding Agent，VPS 远程开发实战》。