graphify 实战：将任意代码库变成可查询的知识图谱

中等难度 | 约 20 分钟 | 你将掌握用 graphify 把任意代码仓库转化为可查询知识图谱的全流程，告别盲目 grep，实现 71.5x Token 压缩的结构化代码理解。

项目简介

graphify 是一个 AI 编码助手技能（skill），由 Safi Shamsi 开发，GitHub 地址 safishamsi/graphify。它的核心定位很简单：把任意文件夹（代码、笔记、论文、图片甚至视频）压缩成一张可查询的知识图谱，让你和 AI 助手的每次对话都基于结构化的知识而非盲目的全文匹配。

它的特色在于三点：

• 多模态输入：代码（20 种语言）、文档、图片、PDF、音视频全支持，统一进同一张图谱
• 零 embedding 聚类：用 Leiden 社区发现算法直接基于图拓扑聚类，不需要向量数据库，不需要单独跑 embedding 模型
• 诚实置信度：每条关系边都标注了 EXTRACTED / INFERRED / AMBIGUOUS，你知道哪些是找到的、哪些是推断的

graphify 可以作为 Claude Code、OpenClaw、Codex、Cursor、Trae 等主流 AI 编码助手的 /graphify 命令使用，也可以通过 MCP Server 或 CLI 独立调用。

目标读者

你写过至少一个中型项目（上千行代码），日常在用 Claude Code / OpenClaw / Codex 或其他 AI 编码助手。遇到新代码库时，你习惯让它直接读源码——但随着文件增多，Token 消耗大、上下文碎片化的问题越来越明显。这篇文章就是来解决这个问题的。

核心依赖与环境

完整项目结构

my-project/
├── graphify-out/
│   ├── graph.json          # 持久化知识图谱，可跨会话查询
│   ├── GRAPH_REPORT.md     # 结构化分析报告（god nodes、意外连接、建议问题）
│   ├── graph.html          # 可交互图谱（vis.js，浏览器直接打开）
│   ├── cache/              # SHA256 缓存目录
│   └── transcripts/        # 音视频转录缓存（装了 video 依赖才有）
├── .graphifyignore         # 排除规则（语法同 .gitignore）
└── .git/hooks/            # graphify hook install 后自动生成

手把手步骤

步骤 1 — 安装 graphify

graphify 分为两步：安装 Python 包，然后为你的 AI 编码助手安装平台适配层。

# 第一步：装 PyPI 包
pip install graphifyy

# 第二步：为你的平台安装适配层
# 以 Claude Code 为例：
graphify install

# 如果你是其他平台，换成对应命令：
# graphify install --platform codex
# graphify install --platform opencode
# graphify install --platform claw        # OpenClaw
# graphify install --platform aider
# graphify install --platform droid       # Factory Droid
# graphify install --platform trae
# graphify install --platform cursor
# graphify install --platform gemini

# Windows 用户如果遇到问题，显式指定平台：
graphify install --platform windows

安装完成后，你的 AI 编码助手就认得了 /graphify 这个命令。

步骤 2 — 首次运行：生成知识图谱

进入任意一个你想分析的代码目录，运行：

# 分析当前目录
/graphify .

# 分析指定目录
/graphify ./src

# 分析指定目录并启用更激进的推断模式
/graphify ./src --mode deep

# 跳过 HTML 可视化，只生成报告和 JSON（更快）
/graphify ./src --no-viz

graphify 会分三步走：

1. AST 提取（无 LLM） — 用 tree-sitter 解析代码文件，提取类、函数、导入关系、调用图、docstring 和解释性注释
2. 语义提取（调用 LLM） — 对文档、论文、图片等内容调用 Claude，提取概念、关系和设计动机
3. 图构建与聚类 — 合并所有提取结果，用 Leiden 社区发现算法（基于边密度，不需要 embeddings）聚类

运行结束后，graphify-out/ 目录里会出现三个产物：

ls graphify-out/
# graph.json  GRAPH_REPORT.md  graph.html  cache/

步骤 3 — 理解三个产物的用法

graphify-out/graph.json — 持久化图谱本体

这是整个系统的核心。格式是一个标准 NetworkX JSON 导出：

{
  "nodes": [
    {
      "id": "DigestAuth",
      "label": "DigestAuth",
      "source_file": "src/auth.py",
      "source_location": "L42",
      "community": "auth"
    }
  ],
  "edges": [
    {
      "source": "DigestAuth",
      "target": "Response",
      "relation": "imports",
      "confidence": "EXTRACTED",
      "confidence_score": 1.0
    },
    {
      "source": "Attention",
      "target": "Adam",
      "relation": "semantically_similar_to",
      "confidence": "INFERRED",
      "confidence_score": 0.87
    }
  ]
}

每条边都有 confidence 标签：

• EXTRACTED：源码中直接存在的关系（置信度 1.0）
• INFERRED：合理推断，带 confidence_score（0.0-1.0）
• AMBIGUOUS：不确定的关系，会在报告中标记出来供人工审核

graphify-out/GRAPH_REPORT.md — 结构化分析报告

这是给 AI 助手看的摘要，包含：

• God Nodes：度最高的核心概念（其他所有节点都要经过它）
• Surprising Connections：出人意料的跨文件/跨类型连接，配有"为什么"的解释
• Suggested Questions：图谱能独特回答的 4-5 个问题
• Design Rationale：从 docstring 和注释（# NOTE:、# WHY:、# HACK:）中提取的设计动机

graphify-out/graph.html — 可交互图谱

直接用浏览器打开，支持点击节点、搜索、按社区过滤。适合人肉探索代码结构。

步骤 4 — 查询图谱：三大命令

光有图谱不够，得能查。graphify 内置了三个查询命令：

query — 语义查询

# 最常用：从图谱中找跟问题相关的节点和路径
graphify query "what connects Attention to the optimizer?"

# 限制 Token 预算
graphify query "show the auth flow" --budget 1500

# 使用 DFS 追踪具体路径（而非随机采样）
graphify query "what connects DigestAuth to Response?" --dfs

# 指定非默认图谱路径
graphify query "..." --graph path/to/another-graph.json

输出包含节点标签、边类型、置信度、源文件和源位置。你可以直接把这段输出贴给 AI 助手让它回答问题：

Use this graph query output to answer the question. Prefer the graph
structure over guessing, and cite the source files when possible.

path — 找两个节点之间的路径

# 追溯节点 A 到节点 B 的完整路径
graphify path "DigestAuth" "Response"

explain — 解释单个节点的上下文

# 展示一个节点的邻居、社区、相关边
graphify explain "SwinTransformer"

步骤 5 — 集成 Always-On Hook（推荐配置）

每次手动敲 /graphify 还是有点麻烦。graphify 支持把图谱知识自动注入到 AI 助手的对话上下文中，让你每次提问时它都优先看图谱而不是盲搜文件。

Claude Code

graphify claude install

做了两件事：往 CLAUDE.md 写一段规则（让 Claude 读 GRAPH_REPORT.md），以及在 settings.json 安装一个 PreToolUse hook，在每次 Glob 和 Grep 调用前注入图谱提示：

graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes
and community structure before searching raw files.

OpenClaw / Aider / Trae 等

这些平台不支持 tool hooks，改用 AGENTS.md：

graphify claw install   # OpenClaw
graphify aider install  # Aider
graphify trae install   # Trae

Cursor

graphify cursor install

写入 .cursor/rules/graphify.mdc 并设置 alwaysApply: true，Cursor 会在每个对话中自动加载。

卸载用对应的 uninstall 命令：

graphify claude uninstall
graphify cursor uninstall
# ...

步骤 6 — 增量更新：不再每次全量重建

代码库每天都在变，全量重建太慢。graphify 有两套增量机制：

--update：基于 SHA256 cache 的增量提取

# 只处理变更过的文件，合并到已有图谱
/graphify ./src --update

cache 目录里按文件内容哈希记录了上次处理结果。graphify 比对文件哈希，只对变化的文件重新走 AST 和 LLM 提取流程。

--watch：自动监控文件变化

# 后台运行，代码文件保存后立即触发 AST 重建
/graphify ./src --watch

# 文档/图片变更后，会提示你手动跑 --update

代码变更触发的 --watch 重建是纯 AST，速度很快，不需要调用 LLM。文档和图片变更仍需要 LLM 重新提取，所以 watch 会通知你手动跑一次 --update。

步骤 7 — git Hooks：每次 Commit 自动重建图谱

不想手动跑，也不想开后台进程？那就把图谱重建交给 git 本身：

graphify hook install

会往 .git/hooks/ 写入 post-commit 和 post-checkout 两个钩子。每次你 commit 或切换分支，git 自动触发图谱重建。如果重建失败（AST 解析报错、LLM 超时等），钩子会以非零退出码中断 git 操作，防止静默失败。

查看状态和卸载：

graphify hook status
graphify hook uninstall

步骤 8 — 高级用法

MCP Server：AI 原生访问图谱

如果你的 AI 助手支持 MCP 协议，把图谱暴露为 MCP 工具：

python -m graphify.serve graphify-out/graph.json

输出是一段 MCP stdio 配置，粘贴到你的 AI 助手的 MCP 配置里即可。暴露的工具包括：

• query_graph：语义查询子图
• get_node：获取节点详情
• get_neighbors：获取邻居节点
• shortest_path：找两节点间的最短路径

Neo4j 导出

想把图谱导入 Neo4j 做更专业的图分析？

# 生成 Cypher 脚本（手动导入）
/graphify ./src --neo4j

# 或直接推送到运行中的 Neo4j 实例
/graphify ./src --neo4j-push bolt://localhost:7687

生成 Agent 可读的 Wiki

# 导出为 Markdown 维基，AI Agent 可以通过读取文件来导航知识库
/graphify ./src --wiki

生成 graphify-out/wiki/index.md（入口） + 每个社区和 god node 对应一篇 Markdown 文章。

支持的文件类型一览

指定其他 LLM 提供者

graphify 默认使用你平台内置的模型（Claude Code 用 Anthropic，Codex 用 OpenAI）。如果你想强制使用其他模型，可以通过环境变量指定（参考对应 skill.md 文件）。

常见问题排查

1. 安装后 graphify 命令找不到

通常是 Python 环境或 PATH 问题：

# 确认包安装位置
pip show graphifyy

# 用 python -m 调用（不依赖 PATH）
python -m graphify --help

# 或者用 pipx 隔离安装（推荐）
pip install pipx && pipx install graphifyy

2. 图谱节点极少或几乎为空

检查 .graphifyignore 是否误排了目标文件：

# 查看 graphify 实际扫描了哪些文件
/graphify ./src --no-viz  # 加上 --no-viz 只跑 AST，不调 LLM，速度快

# 检查 .graphifyignore 语法（和 .gitignore 完全相同）
cat .graphifyignore

也可能是文件类型不在支持列表里——确认你的代码文件扩展名在上面的「支持的文件类型」表中。

3. LLM 提取阶段超时或报 API 错误

网络问题或 API Key 配置问题：

# 确认 API Key 存在（Claude Code 用户通常是自动配置的）
# 其他平台用户检查对应平台的 API Key 环境变量

# 用 --budget 限制 Token，避免单次请求过大
/graphify ./src --budget 2000

# 超时后强制跳过，继续处理其他文件（不阻塞整次运行）

4. cache 导致增量更新后图谱不一致

SHA256 cache 损坏或文件被外部修改：

# 清除 cache，强制全量重建
rm -rf graphify-out/cache
/graphify ./src

# 或者只清除特定文件的 cache
rm graphify-out/cache/<对应哈希>.json
/graphify ./src --update

5. Claude Code PreToolUse Hook 不生效

通常是 settings.json 路径或格式问题：

# 检查 hooks 是否写入成功
cat ~/.claude/settings.json | grep graphify

# 如果格式被 IDE 改动过，手动补回 graphify hook 部分
# 参考 graphify skill.md 中的 PreToolUse hook 格式

6. --watch 报 watchdog 缺失

watchdog 是可选依赖：

pip install graphifyy[watch]

扩展阅读 / 进阶方向

1. 自定义 Extractor：添加新语言支持

如果你的代码库里用到了 graphify 暂不支持的语言（比如 Racket、Nim），可以在 extract.py 里添加一个新的 extract_<lang> 函数，基于 tree-sitter 解析 AST，遵循步骤参考 ARCHITECTURE.md 中的「Adding a new language extractor」部分。流程很清晰：写函数 → 注册后缀 → 加依赖 → 写测试。

2. GraphRAG Pipeline：将图谱查询接入 RAG

graphify 的核心价值在于：每次查询不需要重新读原始文件，Token 消耗从 O(n×文件大小) 降到 O(子图大小)。结合 RAG Pipeline 时，建议的接入方式：

import json

# 1. 先用 GRAPH_REPORT.md 做高层意图判断
# 2. 再用 graphify query 拉取相关子图
# 3. 把子图作为上下文喂给 LLM

with open("graphify-out/graph.json") as f:
    graph = json.load(f)

# graph["nodes"] 和 graph["edges"] 就是上下文

3. Penpax：graphify 作者的端侧数字孪生愿景

graphify 的长期路线图是 Penpax——一个端侧数字孪生项目，把会议记录、浏览器历史、文件、邮件和代码全部连成一张持续更新的知识图谱，不上云、不用你的数据训练模型。

4. 多模态扩展：把视频课程转成图谱

如果你有技术讲座、Conference 视频或播客音频，可以用 --video 依赖把它们也纳入知识图谱：

pip install 'graphifyy[video]'
/graphify ./corpus --whisper-model medium

Whisper 在本地运行，音频不离开你的机器。转录结果缓存在 graphify-out/transcripts/，重复运行直接读缓存。

5. 图谱协作：团队共享知识结构

graphify 的产物（graph.json、GRAPH_REPORT.md）是纯文本，可以 committed 到 git 里。团队成员 pull 后，graphify hook install 会自动复用同一份图谱。这意味着架构知识可以版本化、code review 时可以引用图谱节点、PR 描述里可以直接引用 god nodes——团队的知识理解从此不再依赖「谁来问谁」。