前言¶
用大模型写代码，上下文窗口一直是绕不开的瓶颈。Claude Code、Cursor、Codex 这类 Agent 每次开新会话，往往要重新扫一遍仓库：grep 文件、读 README、翻 SQL 迁移脚本，Token 烧得飞快，理解还不一定连贯。
向量 RAG 是常见解法，但 embedding 检索对「谁调用了谁」「模块之间怎么串起来」这类结构化关系并不擅长。2026 年 8 月初，GitHub Trending 上快速走红的开源项目 Graphify（Graphify-Labs/graphify）换了一条路：把代码、文档、Schema、PDF 等本地素材，确定性解析成可遍历的知识图谱，再通过 /graphify Skill 交给 Agent 查询——不建向量库，也不靠 embedding 猜相似度。
据 findarepo.com 2026-08-01 榜单，Graphify 以约 10 万 Star、7 日 +4300 的增速排在当日 Trending 第 14 位；Trending8 同日也将 Graphify-Labs/graphify 列入「今日增速」榜单。下文基于官方仓库 README 与文档核实功能细节，并给出可复现的上手步骤。
Graphify 是什么¶
Graphify 是一个面向 AI 编程助手的 Agent Skill，核心承诺可以概括为三句话：
- 代码本地解析：用 tree-sitter 做 AST 静态分析，提取函数、调用、导入、继承等关系，过程确定性、不调用 LLM，源码不离开本机。
- 多模态并入同一图：Markdown、PDF、SQL Schema、配置文件，以及图片/音视频（需额外依赖）经语义抽取后，与代码节点合并进同一张 NetworkX 图。
- 可查询、可解释：生成
graph.json持久化图谱，支持自然语言 query、两点 path 追踪、单节点 explain；每条边标注EXTRACTED（源码显式）或INFERRED（工具推断），便于审计。
项目在 GitHub 上约 2026-04-03 创建，维护者为 Safi Shamsi 主导的 Graphify-Labs；PyPI 包名为 graphifyy（双 y，官方强调其它 graphify* 包无关联），CLI 命令仍为 graphify。许可证以仓库元数据为准为 Apache-2.0。
为什么现在火：上下文工程的新选项¶
Agent 编程工具普及后，「上下文工程」成了显学：怎么在有限 Token 里塞下足够准确的项目记忆？常见痛点包括：
- 大仓库反复全文检索，延迟高、成本高；
- 纯 RAG 返回片段，缺少跨文件调用链；
- 文档、Schema、代码分属不同来源，Agent 难以建立统一心智模型。
Graphify 的定位是 RAG 的互补而非简单替代：它不做 embedding 索引，而是构建显式图结构，用 Leiden 算法做社区划分，标出「上帝节点」（高度数枢纽）和跨模块的意外连边。官方 README 称在 Karpathy 混合语料（代码 + 论文 + 图）上，图查询平均约 1.7k Token，对比 naive 全文约 123k Token——具体数值因项目而异，但思路清晰：索引一次，多次查询。
这与 Andrej Karpathy 曾提出的「为 LLM 建结构化知识库、让模型查询而非重读原文」一脉相承；DEV Community 上也有开发者用 FastAPI 等真实仓库验证 query / path / explain 工作流的实践文章。
核心原理：AST + 图，而非向量¶
代码层：tree-sitter 确定性抽取¶
Graphify 对源码走 tree-sitter 管道，官方称支持约 40 种语言 的 calls / imports / inherits / mixes_in 等跨文件边。注释里的 # NOTE:、# WHY: 以及 ADR/RFC 引用会被提升为节点，与设计 rationale 关联——这对「改代码前先理解为什么这样写」很有帮助。
要点：代码解析阶段零 LLM 调用、零外发。
文档与 Schema：可选语义通道¶
PDF、Office、图片等无法纯语法解析的内容，Graphify 会走语义抽取；此时使用你在 Claude Code / Cursor / Codex 等助手里 已配置的模型 API，官方说明只发送文档的语义描述，不发送原始源码。SQL Schema 可通过 graphifyy[sql] 或 graphifyy[postgres] 等 extra 接入。
建图与聚类¶
各阶段产出节点/边后，合并为 NetworkX 图，用 Leiden 做社区检测（无需向量 embedding）。最终导出三件套：
graphify-out/
├── graph.html # 浏览器交互可视化
├── GRAPH_REPORT.md # 核心概念、意外连边、建议提问
└── graph.json # 可编程查询的全量图
安装与注册 Skill¶
环境要求：Python 3.10+，推荐用 uv 隔离安装。
1. 安装 CLI
uv tool install graphifyy
# 或：pipx install graphifyy
若提示找不到命令，执行 uv tool update-shell 后重开终端。
2. 向 AI 助手注册 Skill
graphify install # 默认 Claude Code
graphify cursor install # Cursor
graphify install --platform codex
graphify install --platform gemini
graphify install --project # 写入当前仓库，便于团队共享
官方支持 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 等 20+ 平台；Codex 用户需在 ~/.codex/config.toml 开启 multi_agent = true 以并行抽取。
3. 在助手对话中构建图谱
在 Claude Code / Cursor 等支持 Slash Command 的环境：
/graphify .
PowerShell 下勿写前导 /，应使用 graphify .。
首次运行完成后，项目根目录会出现 graphify-out/。可用 --update 做增量更新，避免全量重建。
查询图谱：替代反复 grep¶
图谱建好后，在终端或让 Agent 调用 CLI 即可，无需重读全库。官方 FastAPI 示例输出如下（摘自 README）：
$ 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
常用命令：
| 命令 | 作用 |
|---|---|
graphify query "认证流程怎么走？" |
按自然语言取子图并回答 |
graphify path "AdminPanel" "Database" |
两概念间最短路径 |
graphify explain "RateLimiter" |
单节点及邻域解释 |
中文查询可安装 graphifyy[chinese] 以启用 jieba 分词。若希望 Agent 优先查图再读文件，可对 Claude Code 执行 graphify install --project --strict，首读源码会被重定向到图谱查询（每会话最多拦截一次，避免卡死）。
与 Claude Code、Cursor 的集成方式¶
Graphify 以 Skill 形态嵌入工作流：安装后在对话里 /graphify 触发构建，后续任务中 Agent 可调 graphify query 等命令拉上下文。对 Cursor，运行 graphify cursor install 即可写入对应 Skill 目录。
这与「每次 @ 整个文件夹」或「让模型自己 glob 全仓库」形成对比：前者是静态快照 + 结构化检索，后者是重复 IO。对于 monorepo、含大量 PDF/Schema 的全栈项目，把 应用代码 + 数据库 Schema + 基础设施配置 放进同一张图，能减轻 Agent 在多层之间「迷路」的概率。
可选能力还包括：graphifyy[mcp] 暴露 MCP 服务；graphifyy[neo4j] / [falkordb] 推送到外部图数据库；graphify hook install 在 git commit 后自动增量更新图谱。
和向量 RAG 怎么选¶
| 维度 | 向量 RAG | Graphify 知识图谱 |
|---|---|---|
| 索引方式 | embedding 相似度 | AST + 显式边 + 可选语义节点 |
| 擅长 | 模糊语义、长文档片段召回 | 调用链、模块边界、跨文件依赖 |
| 存储 | 向量库 | 本地 graph.json，无 embedding |
| 成本结构 | 建库与检索均消耗 Token | 代码解析零 LLM；文档语义按配置模型计费 |
| 可解释性 | 相似度分数 | 边类型 + EXTRACTED/INFERRED 标签 |
实践上二者可并存：RAG 兜文档长尾问答，Graphify 兜「从入口到数据库经过哪些层」这类拓扑问题。官方 BENCHMARKS.md 在 LOCOMO、LongMemEval-S 等设定下给出了与 mem0、supermemory 等的对比表，感兴趣的读者可在仓库内复现实验，不宜脱离具体语料盲目照搬分数。
使用注意¶
- 包名是 graphifyy，
pip install graphify可能装到无关项目。 - 文档/多媒体语义抽取依赖已配置的模型 Key；纯代码图谱可完全离线完成。
- 超大仓库首次构建耗时与文件量线性相关；善用
cache/与--update。 - Graphify-Labs 同时运营 graphify.com 平台（持续后台更新图谱），开源 CLI Skill 与云服务是两条产品线，本文仅讨论开源 Skill 路径。
小结¶
Graphify 把「代码理解」从反复全文扫描，推进到 一次建图、多次遍历：tree-sitter 本地 AST、Leiden 社区、可解释的 EXTRACTED/INFERRED 边，加上与 Claude Code、Cursor、Codex 等深度集成的 /graphify Skill——正好切中 2026 年开发者工具链里「Agent 需要一张项目地图」的热点。
若你正在维护万行级仓库、或文档与 Schema 分散在多处，不妨花半分钟安装 graphifyy，在项目根执行一次 /graphify .，打开 graphify-out/graph.html 看社区着色与上帝节点，再用 graphify path 问一个你平时要翻十几个文件才能答的问题——这比 Star 数字更能说明它值不值得进你的工具箱。
