前言¶
2026 年 8 月初，GitHub Trending 上持续出现一个叫 Graphify 的开源项目（Graphify-Labs/graphify）。据 Trending8 在 2026-08-05 的榜单，该项目单日 star 增量在 600～900 量级，与 Claude Code Skill、GraphRAG 等标签一起被大量开发者讨论。
它的卖点很直接：在 Claude Code、Cursor、Codex、Gemini CLI 等 AI 编程助手里输入 /graphify，就能把当前项目的代码、文档、SQL Schema、PDF 等统一建成一张可查询的知识图谱，后续用 query、path、explain 查关系，而不是反复 grep 或走 embedding 向量检索。
本文基于官方仓库 README、graphify.net 文档以及 Trending 榜单信息整理，重点说明它如何把「代码库理解」从传统向量 RAG 推向结构化 GraphRAG，以及本地如何快速试用。
Graphify 是什么¶
Graphify 是一个面向 AI 编程助手的 Skill / CLI 工具，由 Graphify-Labs 维护，PyPI 包名为 graphifyy（注意双 y），命令行仍叫 graphify。
官方描述可以概括为三句话：
- 多模态输入：源码、Markdown、PDF、图片、视频，以及 SQL Schema（需安装
[sql]扩展）都能进同一张图。 - 代码本地解析：源码通过 tree-sitter 做确定性 AST 提取，不调用 LLM，数据不出本机。
- 图谱而非向量库：输出
graph.json供遍历查询，明确声明不使用 embedding、不依赖向量存储。
构建完成后，默认在 graphify-out/ 生成三个文件：
graphify-out/
├── graph.html # 浏览器可交互浏览
├── GRAPH_REPORT.md # 核心节点、意外连接、建议问题
└── graph.json # 持久化图谱，可反复查询而无需重读源码
为什么有人把它看作「向量 RAG 的替代」¶
传统代码 RAG 的常见路径是：切分文件 → 向量化 → 相似度检索 → 把若干 chunk 塞给模型。问题在于：
- 检索结果是片段，跨文件调用链、继承关系容易被截断。
- embedding 相似不等于结构相关，「谁调用谁」这类问题很难靠余弦距离回答。
- 每次会话往往重新读文件或重新检索，上下文 token 开销大。
Graphify 走的是 GraphRAG / 知识图谱 路线。官方 README 给出的 FastAPI 示例中，可以直接执行：
$ graphify explain "APIRouter"
Node: APIRouter
Source: routing.py L2210
Community: 2
Degree: 47
Connections (47):
--> RequestValidationError [uses] [INFERRED]
--> .get() [method] [EXTRACTED]
<-- __init__.py [imports] [EXTRACTED]
...
$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField
每条边带 EXTRACTED（源码中明确存在）或 INFERRED（工具推断）标签，查询者能区分「读到的」和「猜的」。这与向量检索返回「若干相似段落」在可解释性上差异很大。
官方 BENCHMARKS.md 还公布了 LOCOMO、LongMemEval-S 等对比数据（例如 LOCOMO recall@10 报 0.497），并强调图谱构建阶段对代码零 LLM 额度。第三方文章（如 Augment Code 对 v0.9.9 的介绍）也提到混合语料查询 token 可从十万级降到千级量级——具体数值因仓库规模而异，但「先建图、再子图查询」的思路是确定的。
核心机制：tree-sitter AST + 图谱聚类¶
1. 代码层：tree-sitter 本地提取¶
Graphify 对代码的第一遍处理是 tree-sitter 遍历 AST，官方 tree-sitter 说明页 称此阶段无 LLM、无 embedding、无网络请求。
README 列出的能力包括：
| 能力 | 说明 |
|---|---|
| 跨文件链接 | calls / imports / inherits / mixes_in，覆盖约 40 种语言 |
| 设计 rationale | # NOTE:、# WHY: 等注释提升为一等节点 |
| 社区划分 | 对 NetworkX 图跑 Leiden 算法，子系统聚类不依赖向量 |
| God nodes | 高度数枢纽节点，帮助快速定位架构中心 |
纯代码仓库可用 --code-only 完全离线索引，无需 API Key：
graphify extract ./raw --code-only
2. 文档与 SQL：语义补充¶
文档、PDF、图片等需要 AI 助手已配置的模型做语义抽取；官方强调发送的是语义描述而非原始源码。SQL Schema 需额外安装：
uv tool install "graphifyy[sql]"
# 或直连 PostgreSQL
uv tool install "graphifyy[postgres]"
graphify extract --postgres "postgresql://user:pass@host/db"
这样应用代码、数据库表结构、基础设施配置可以落在同一张图里，回答「认证模块连哪张表」类问题时不必人工拼 grep 结果。
3. 输出与查询命令¶
常用 Skill 命令（在助手内）：
/graphify . # 构建当前目录图谱
/graphify query "what connects auth to the database?" # 自然语言子图查询
/graphify path "UserService" "DatabasePool" # 两节点最短路径
/graphify explain "RateLimiter" # 单节点邻接解释
CLI 等价示例：
graphify query "show the auth flow"
graphify path "DigestAuth" "Response"
安装与接入 Claude Code、Cursor¶
环境要求：Python 3.10+，推荐用 uv 或 pipx 隔离安装。
Step 1 — 安装 CLI（PyPI 官方包为 graphifyy，勿与其它同名包混淆）：
uv tool install graphifyy
# 或：pipx install graphifyy
Step 2 — 注册 Skill：
graphify install
Step 3 — 在助手内构建图谱：
/graphify .
各平台专用命令（摘自官方 README）：
| 平台 | 安装命令 |
|---|---|
| Claude Code | graphify install |
| Cursor | graphify cursor install |
| Codex | graphify install --platform codex |
| Gemini CLI | graphify install --platform gemini |
Cursor 会在 .cursor/rules/graphify.mdc 写入 alwaysApply: true 规则，引导助手优先 graphify query 而非整文件 grep。Claude Code 还可选 strict 模式（graphify install --project --strict），在会话开始时阻止首次裸读源码，强制先查图谱。
团队可提交 graphify-out/graph.json 与 GRAPH_REPORT.md，他人 clone 后助手直接读图，无需每人重建。配合 graphify hook install 可在 git commit 后自动增量更新。
适用场景与使用注意¶
更适合：
- 接手陌生单体/微服务，需要理清模块边界与调用链。
- 代码 + SQL + 文档 + ADR 混在一起，要问「设计原因」而不只是「定义在哪」。
- 希望降低 AI 助手反复 Read/Grep 带来的 token 消耗。
需要留意的点：
- 文档/多媒体仍要模型：纯
--code-only离线；全量多模态需配置助手已有 API。 - 图谱需维护：结构大变后应
/graphify . --update或依赖 hook 重建。 - INFERRED 边需人工判断：高价值在于 EXTRACTED 的结构边，推断边应交叉验证。
- Trending 热度与 star 数：榜单看的是近期增速；评估项目仍建议看 release、issue 与本地试跑，而非只看 star。
小结¶
Graphify 把 2026 年 AI 编程助手领域的一个清晰方向做成了可安装 Skill：用 tree-sitter 在本地确定性抽取代码结构，用知识图谱承载跨文件关系，用可解释边替代黑盒向量相似度。它并不取消 LLM，而是让 LLM 在已有「地图」上做子图查询与推理，代表代码智能从「embedding 检索」向「结构化 GraphRAG」演进的一股实用力量。
若你已在用 Claude Code 或 Cursor，30 秒安装后跑一遍 /graphify .，打开 graphify-out/graph.html 看社区着色与 God nodes，比读十页 README 更直观。
参考来源
- 官方仓库：https://github.com/Graphify-Labs/graphify
- 项目站点：https://graphify.net/
- GitHub Trending 聚合：https://trending8.vercel.app/
