AI 代码知识图谱教程（二）| Graphify（代码+文档）

一、你的项目不只代码
[二、为什么纯 AST 工具不够](#二、为什么纯 AST 工具不够)
- 一张对比表看清区别
- [核心区别：EXTRACTED vs INFERRED](#核心区别：EXTRACTED vs INFERRED)
[三、Graphify 是什么](#三、Graphify 是什么)
- 核心能力
- 使用前需要知道的几件事
[四、Graphify 实战教学](#四、Graphify 实战教学)
- [4.1 安装（两步）](#4.1 安装（两步）)
- [4.2 扩展安装（终端命令）](#4.2 扩展安装（终端命令）)
- [4.3 配 hook（自动保持图谱新鲜）](#4.3 配 hook（自动保持图谱新鲜）)
- [4.4 建图](#4.4 建图)
- - [情况一：工作目录本身就是 git 仓库（`.git/` 直接在工作目录下）](#情况一：工作目录本身就是 git 仓库（.git/ 直接在工作目录下）)
  - [情况二：工作目录不是 git 仓库，`.git/` 在它的子目录里](#情况二：工作目录不是 git 仓库，.git/ 在它的子目录里)
- [4.5 日常使用](#4.5 日常使用)
- [4.6 不要把图谱产物提交到仓库](#4.6 不要把图谱产物提交到仓库)
- [4.7 卸载](#4.7 卸载)
五、日常三个最高频场景
- [场景 1：改模块前，查图谱看关联的决策](#场景 1：改模块前，查图谱看关联的决策)
- [场景 2：理解一个模块为什么存在](#场景 2：理解一个模块为什么存在)
- [场景 3：跨文档发现隐藏关联](#场景 3：跨文档发现隐藏关联)
六、怎么看懂图谱输出
- GRAPH_REPORT.md
- graph.html
- [INFERRED 边怎么用](#INFERRED 边怎么用)
七、避坑清单
- 成本说明
[八、能不能和 Codegraph 一起装？](#八、能不能和 Codegraph 一起装？)
九、总结

本文是「AI 图谱系列」专栏二。如果你的项目有架构文档、ADR、编码规范，这篇文章是写给你的。

一、你的项目不只代码

你的项目里有这些东西：

复制代码

blog-server/
├── src/                     ← 代码
├── docs/
│   ├── 架构设计.md           ← 为什么选 Session 不选 JWT
│   ├── 项目决策记录.md        ← 13 个 ADR
│   └── 编码规范.md            ← 阿里巴巴 Java 手册
└── CLAUDE.md                ← AI 协作规则

纯编译器工具（Codegraph）看到的是：

复制代码

SecurityConfig.java   ← 一个配置文件
LoginController.java  ← 一个控制器
SessionService.java   ← 一个服务类

Graphify 看到的是：

复制代码

SecurityConfig.java   ← 实现了《认证架构设计.md》里的 Session 方案
LoginController.java  ← 限流策略来自《认证架构设计.md》第 4 节
SessionService.java   ← 决策依据：ADR-003 "为什么选 Session 不选 JWT"

编译器只能看到"有什么"，Graphify 能看到"为什么"。

二、为什么纯 AST 工具不够

一张对比表看清区别

	Codegraph（编译器派）	Graphify（LLM 派）
怎么读代码	tree-sitter AST 解析	AST（代码结构）+ LLM（语义理解）
能读什么	只有代码	代码 + 文档 + PDF + 图片
读到什么	谁调了谁	为什么这么调
文档关联	❌ 不读文档	✅ 文档里的决策关联到代码
跨文档隐藏关联	❌	✅ 发现两个模块做同一件事
永远不出错	✅	❌ INFERRED 边可能不准确
成本	零	代码变更免费（走 AST），文档变更走 LLM

核心区别：EXTRACTED vs INFERRED

Graphify 每条边都有置信度标签：

标签	含义	可信度
EXTRACTED	AST 直接解析到的（import、调用、引用）	100% 真实
INFERRED	LLM 推断的（语义相似、隐含关联）	0.55~0.95，看置信度
AMBIGUOUS	不确定，需要你自行判断	存疑

实线 = 真的，虚线 = 猜的。打开 graph.html 一眼分辨。

三、Graphify 是什么

Graphify 是 LLM 派知识图谱的代表。分两步工作：

复制代码

① AST 解析（免费）→ 提取 import、调用、继承等确定性关系 → EXTRACTED 边
② LLM 语义提取（烧 token）→ 读代码+文档，理解语义 → INFERRED 边

核心能力

55.6K 星，MIT 许可证，58 贡献者
输出：HTML 交互图、GRAPH_REPORT.md、graph.json、SVG、GraphML（Gephi）、Cypher（Neo4j）、Obsidian 文库、Markdown Wiki
支持 20 个 AI 平台、33 种语言
内置社区检测、god nodes、意外关联发现

使用前需要知道的几件事

Graphify 不是完美的。下面有些是架构层面的固有取舍，有些是装完必须做的配置，分清楚才能用好。

架构层面的取舍（有对策但无法根除）：

取舍	意味着什么	怎么应对
无持久化图数据库	基于内存 NetworkX + JSON 文件存储，10K+ 节点后查询变慢，不支持 Cypher 原生查询	中小项目直接用 JSON 就够了。大项目分模块建图，或 `--neo4j` 导出到 Neo4j（见 4.2 节）。社区有 Rust 重写版 graphify-rs（24ms / 1MB vs Python 204ms / 48MB），但非官方维护
Pass 3 跨块断裂	LLM 语义提取按文件分批处理，跨批次之间的概念关系可能被遗漏	`--mode deep` 激进提取；大项目分模块建图而非一次性全库
初始构建慢	大型代码库首建 10-30 分钟（含 LLM 语义提取）	`/graphify ./src` 先从小范围开始；`--no-viz` 跳过 HTML 加速
推断边不一定可靠	`INFERRED` 和 `AMBIGUOUS` 边是 LLM 推理结果，存在幻觉可能	关注置信度标签：`EXTRACTED`（AST 确定）可信，`INFERRED` 和 `AMBIGUOUS` 让 AI 标注引用来源供你核对

装完必须做的配置（不做才是问题）：

配置项	为什么必须做	怎么做
配 Git hook 自动增量更新	不配的话图谱不会自己更新，逐渐过时变成幽灵节点	`graphify hook install`（免费，纯 AST，无 API 调用），之后每次 `git commit` 自动触发
升级到最新版	v0.4.29 之前存在 Windows CJK 路径乱码、盘符大小写不一致导致 MCP 失败等问题	`uv tool upgrade graphifyy`，当前最新版已修复

四、Graphify 实战教学

开始之前先确认：你的项目超过 200 个文件吗？没超过就别往下看了，建图开销大于收益。

下面直接从零开始。

4.1 安装（两步）

前提： Python ≥ 3.10

Step 1 --- 安装到系统（首选 uv，装不上再用 pip）：

以下命令在 系统终端（CMD / PowerShell / Terminal） 中执行：

bash 复制代码

# Mac / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows（PowerShell）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

装完 uv 后：

bash 复制代码

uv tool install graphifyy

如果 uv 装不上，直接用 pip：

bash 复制代码

pip install graphifyy

验证：

bash 复制代码

graphify --version

注意：PyPI 包名是 graphifyy（两个 y），CLI 命令是 graphify（一个 y）。装包和敲命令用的名字不一样，别搞混。

Step 2 --- 注册到 AI 助手（在终端执行，选你用的那个就行）：

AI 工具	注册命令
Claude Code（Mac/Linux）	`graphify install`
Claude Code（Windows）	`graphify install --platform windows`
Cursor	`graphify cursor install`
Codex CLI	`graphify install --platform codex`
GitHub Copilot CLI	`graphify install --platform copilot`
Gemini CLI	`graphify install --platform gemini`
Aider	`graphify install --platform aider`
VS Code Copilot Chat	`graphify vscode install`
Trae / Trae CN / Kimi Code / OpenCode / Hermes / Pi	`graphify install --platform <工具名>`
OpenClaw / Factory Droid / Amp / Kiro / Devin CLI / Google Antigravity	见官方 README `graphify <工具名> install` 格式

Codex CLI 用户特别注意： 除了上面的注册命令，还需要在 ~/.codex/config.toml 中添加 [features] 段落并设置 multi_agent = true，否则 Graphify 的子代理无法并行工作。

4.2 扩展安装（终端命令）

扩展装多了会慢，装少了功能受限。标准答案：

你的项目类型	需要装的扩展
纯代码项目（Java/Python/Go 等）	什么都不用装，继续往下走
项目里有 PDF 文档	`pip install "graphifyy[pdf]"`
项目里有 Word/Excel	`pip install "graphifyy[office]"`
需要视频/音频转录（含 YouTube）	`pip install "graphifyy[video]"`
需要 MCP 独立服务模式（让其他 MCP 客户端查询图谱）	`pip install "graphifyy[mcp]"`
想导出到 Neo4j	`pip install "graphifyy[neo4j]"`
不确定	`pip install "graphifyy[all]"`

4.3 配 hook（自动保持图谱新鲜）

代码每天都在改，图谱必须跟着更新，否则就过时了。graphify hook install 做的事就是把这个"跟着更新"自动化------往 git 仓库里写入一个脚本，之后每次 git commit，图谱自动增量重建。

bash 复制代码

graphify hook install

这条命令操作的是 git，所以必须在有 .git/ 的目录下执行。 不管你的仓库里是一个项目还是多个子项目，只要这个目录下面有 .git/，就在这里执行。有几个独立的 git 仓库就执行几次。

bash 复制代码

cd your-project      # 先进到你的 git 仓库
graphify hook install  # 给它装上自动更新

为什么放在建图前面？ 反过来想：如果你先建图、三天后才配 hook，这三天里的 commit 都不会触发更新，图谱从第一天就是旧的。先配好 hook，建图后的每一次 commit 都自动追上。

hook 只做 AST 静态解析，不调 LLM，完全免费。

4.4 建图

/graphify . 扫描当前目录生成图谱，在 AI 对话框 （不是终端）输入。产物固定落在当前目录的 graphify-out/ 下。

先确定你的工作目录------就是你平时启动 AI 搞开发的那个目录。 然后看这个目录和 .git/ 的关系，选对应的做法。

情况一：工作目录本身就是 git 仓库（`.git/` 直接在工作目录下）

不管工作目录下是一个项目还是多个子项目，只要 .git/ 就在这里，那图直接建在这里。hook 自动更新，AI 自动读取，一条命令完事。

bash 复制代码

cd workspace         # 终端：进到工作目录
claude               # 终端：启动 AI
/graphify .          # AI 对话框：建图

产物落在工作目录下：

复制代码

workspace/           ← 工作目录（你启动 AI 的地方，.git/ 也在这）
├── project-a/
├── project-b/
├── graphify-out/    ← 图在这
├── .git/
└── README.md

全链路自动化：commit → hook 自动增量更新 → AI 下次对话自动读到最新图。

情况二：工作目录不是 git 仓库，`.git/` 在它的子目录里

比如工作目录下放了 frontend/ 和 backend/ 两个独立仓库，各有自己的 .git/，但工作目录本身没有 .git/。

hook 必须跟着 .git/ 走，所以进各自目录建图：

bash 复制代码

cd frontend && claude      # 终端：进到 frontend
/graphify .                # AI 对话框：产出 → frontend/graphify-out/

cd backend && claude       # 终端：进到 backend
/graphify .                # AI 对话框：产出 → backend/graphify-out/

各自的 hook 自动更新各自的图------前端改了前端图更新，后端改了后端图更新。

此时目录结构：

复制代码

workspace/               ← 工作目录（你启动 AI 的地方，没有 .git/）
├── frontend/
│   ├── src/
│   ├── graphify-out/    ← 前端的图
│   └── .git/
├── backend/
│   ├── src/
│   ├── graphify-out/    ← 后端的图
│   └── .git/
└── README.md

但你在工作目录启动 AI 时，AI 只看工作目录下的 graphify-out/，工作目录没有就什么都读不到。所以需要把子图谱合并到工作目录：

bash 复制代码

# 终端，工作目录执行
graphify merge-graphs \
  ./frontend/graphify-out/graph.json \
  ./backend/graphify-out/graph.json \
  --out graphify-out/graph.json

合并后：

复制代码

workspace/
├── frontend/
│   ├── graphify-out/    ← 前端的图（保留）
│   └── .git/
├── backend/
│   ├── graphify-out/    ← 后端的图（保留）
│   └── .git/
├── graphify-out/        ← 合并后的总图（新增）
│   └── graph.json
└── README.md

合并后工作目录有了总图，AI 能同时看到所有子项目（节点带 repo 属性标明来源）。合并是全量重拼，子项目有改动后手动重跑。

如果你不在工作目录启动 AI，而是分别进子目录启动，那不需要合并------各自目录下已经有图了。

4.5 日常使用

建完图后，AI 还不会主动查图------你需要先在终端执行一条命令，告诉它"遇到代码问题先查图谱"：

你的 AI 工具	让 AI 自动查阅图谱的命令
Claude Code	`graphify claude install`
Codex CLI	`graphify codex install`
Cursor	`graphify cursor install`
OpenCode	`graphify opencode install`
Gemini CLI	`graphify gemini install`
其他平台	参考 4.1 Step 2 表格，将 `install --platform <名>` 换为 `<名> install`（如 `aider install`）

执行完后关掉 AI 重新打开，新指令才会生效。

原理：向项目的 CLAUDE.md / AGENTS.md 等文件写入指令。

配好之后，大多数时候不需要手动敲命令------直接在对话里问，AI 自动查图。以下两种情况例外：

精确追踪调用路径：

bash 复制代码

/graphify path "UserService" "DatabasePool"

比自然语言更精确，AI 会严格沿图的边追踪。

代码改了但还没 commit，想立刻刷新图谱：

bash 复制代码

/graphify . --update

回忆一下 4.3 节配的 hook：每次 git commit 后图谱自动增量更新。--update 只是在 commit 之前临时想刷新时用的，日常不需要。

4.6 不要把图谱产物提交到仓库

不管是个人还是团队，不要提交 graphify-out/。 官方虽然建议提交，但社区 ISSUE #722、#313 证实了跨机器路径不兼容的问题，两个 ISSUE 至今未修复。最稳妥的做法是在 .gitignore 里加上：

复制代码

graphify-out/

每个人拉下项目后自己跑一次 /graphify .，之后 hook 自动更新，互不干扰。

4.7 卸载

在终端执行以下命令：

bash 复制代码

graphify uninstall              # 移除所有 AI 平台的注册
graphify uninstall --purge       # 同时删除 graphify-out/ 目录
# 最后卸载软件包
uv tool remove graphifyy         # 如果你用 uv 安装的
# 或：pip uninstall graphifyy    # 如果你用 pip 安装的

五、日常三个最高频场景

场景 1：改模块前，查图谱看关联的决策

复制代码

你准备改认证模块。

无 Graphify：翻代码 + 翻文档，靠人脑关联
有 Graphify：AI 查图谱 → "认证模块关联了 ADR-003（Session 选型）、
               ADR-006（CSRF 策略）、以及《认证架构设计.md》"
             → 你知道这个模块有哪些约束，改起来心里有数

场景 2：理解一个模块为什么存在

复制代码

你看到一个从未见过的模块："blog-module-site"

无 Graphify：看代码 → "这是一个站点配置模块"
有 Graphify：查图谱 → 代码关联到《决策记录.md》ADR-011：
              "站点配置独立成模块，因为未来可能支持多站点"
             → 你知道了这个模块的业务意图

场景 3：跨文档发现隐藏关联

复制代码

你维护时发现两个文件从不互相 import，但做的是同一件事。

Graphify 通过 LLM 语义理解发现了它们，标记 INFERRED 边。
你打开 graph.html，看到一条虚线，点进去 → "这两个都是做权限校验的"
→ 你可以考虑合并或统一，消除重复逻辑

六、怎么看懂图谱输出

GRAPH_REPORT.md

打开 graphify-out/GRAPH_REPORT.md，关键数据在第 9 行：

复制代码

Extraction: 92% EXTRACTED · 8% INFERRED · 0% AMBIGUOUS

92% EXTRACTED → 代码里真实存在的，可以放心信
8% INFERRED → LLM 推断的，平均置信度 0.8，基本可靠但需验证

graph.html

打开浏览器，节点按社区着色，边有两种：

边	外观	含义
EXTRACTED	实线，粗，不透明	真实存在
INFERRED	虚线，细，半透明	推断，需验证

鼠标悬停可以看到边的类型和置信度。

INFERRED 边怎么用

置信度 ≥ 0.85 → 基本可靠，可以信
置信度 0.65~0.85 → 参考，结合代码验证
置信度 < 0.65 → 仅当提示，别当真

七、避坑清单

坑	后果	解法
不配 hook	图谱逐渐过时，AI 查到幽灵节点	`graphify hook install`
INFERRED 边当真理	AI 给出的结论可能基于推断	关注置信度，实线可信，虚线验证
graphify-out/ 提交到仓库	跨机器路径不兼容	`.gitignore` 加 `graphify-out/`
每次全量重建	越跑越慢	第二次开始用 `/graphify . --update`
小项目硬上	建图时间 > 节省的 token	<200 文件别用

成本说明

复制代码

代码变更 → hook 触发 → 只跑 AST → 免费
文档变更 → 需要手动 /graphify . --update → LLM 语义提取 → 烧 token

日常代码提交不会花钱。只有你加了新文档或想刷新语义理解时才消耗 token。

八、能不能和 Codegraph 一起装？

可以，这是推荐组合。

复制代码

Codegraph   → 日常导航（调用链、影响分析）→ 零成本、实时
Graphify    → 阶段性架构审计（文档关联、隐藏关联）→ 有成本、更深入

两个工具各自独立目录，互不冲突。绝大多数时候 Codegraph 够了，偶尔想深入理解时再跑一次 Graphify。

九、总结

你的情况	选什么
有架构文档/ADR/编码规范	Graphify
纯代码项目（没文档）	看专栏一：纯代码篇
做新人入职引导	看专栏三：可视化篇

一句话：Graphify 是聊过天的人------他读了你的文档，理解了你的设计意图，能告诉你"为什么"。Codegraph 是查户口本的------精准但没人情味。你的项目有文档，就值得让人来聊一次。

AI 代码知识图谱 教程（二）| Graphify（代码+文档）

AI 代码知识图谱 教程（二）| Graphify（代码+文档）

一、你的项目不只代码

二、为什么纯 AST 工具不够

一张对比表看清区别

核心区别：EXTRACTED vs INFERRED

三、Graphify 是什么

核心能力

使用前需要知道的几件事

四、Graphify 实战教学

4.1 安装（两步）

4.2 扩展安装（终端命令）

4.3 配 hook（自动保持图谱新鲜）

4.4 建图

情况一：工作目录本身就是 git 仓库（.git/ 直接在工作目录下）

情况二：工作目录不是 git 仓库，.git/ 在它的子目录里

4.5 日常使用

4.6 不要把图谱产物提交到仓库

4.7 卸载

五、日常三个最高频场景

场景 1：改模块前，查图谱看关联的决策

场景 2：理解一个模块为什么存在

场景 3：跨文档发现隐藏关联

六、怎么看懂图谱输出

GRAPH_REPORT.md

graph.html

INFERRED 边怎么用

七、避坑清单

成本说明

八、能不能和 Codegraph 一起装？

九、总结

AI 代码知识图谱教程（二）| Graphify（代码+文档）

AI 代码知识图谱教程（二）| Graphify（代码+文档）

情况一：工作目录本身就是 git 仓库（`.git/` 直接在工作目录下）

情况二：工作目录不是 git 仓库，`.git/` 在它的子目录里