项目地址：safishamsi/graphify（⭐ 27.6K）
版本：v4（截至 2026-04-16）
一句话总结：把代码、文档、论文、截图丢进去，生成一张可查询的知识图谱，让 AI 编码助手从"逐文件 grep"进化到"按图索骥"。

你有没有过这样的体验——在 Claude Code 里问一个架构问题，它花了 80% 的 token 在 Glob 和 Grep 上翻文件，最后给你一个似是而非的答案？

这不是 AI 不够聪明，而是它看不到全局。

Graphify 就是来解决这个问题的。它不是又一个 RAG 工具，不是又一个向量数据库，而是一个面向 AI 编码助手的知识图谱构建技能——用确定性的 AST 解析 + LLM 语义提取，把你的代码库压缩成一张结构化的图，然后让 AI 先看地图再找路。

它到底是什么

Graphify 是一个 Claude Code skill（现在也支持 Codex、OpenCode、OpenClaw、Factory Droid、Trae 等平台），核心做的事情只有一件：把任意文件夹变成一张可查询的知识图谱。

1
pip install graphifyy && graphify install

然后在你的 AI 编码助手里输入：

1
/graphify .

它会生成这样一组输出：

1
2
3
4
5
graphify-out/
├── graph.html       # 可交互图谱：点节点、搜索、按社区过滤
├── GRAPH_REPORT.md  # God nodes、意外连接、建议提问
├── graph.json       # 持久化图谱：数周后仍可查询，无需重新读原始文件
└── cache/           # SHA256 缓存：重复运行时只处理变更过的文件

注意 PyPI 包名暂时叫 graphifyy（graphify 这个名字还在回收中），但 CLI 命令和 skill 命令都是 graphify。

工作原理：两轮提取 + 图拓扑聚类

Graphify 的技术架构非常清晰，pipeline 分为 7 个阶段，每个阶段是一个独立模块：

1
detect() → extract() → build_graph() → cluster() → analyze() → report() → export()

第一轮：确定性 AST 提取（不消耗 token）

对代码文件，Graphify 使用 tree-sitter 做结构分析——类、函数、导入、调用图、docstring、解释性注释——这一轮完全在本地完成，不调用任何 LLM。支持 13 种语言：

类型 扩展名 提取方式
代码 .py .ts .js .go .rs .java .c .cpp .rb .cs .kt .scala .php tree-sitter AST + 调用图 + docstring/注释中的 rationale
文档 .md .txt .rst 通过 Claude 提取概念、关系和设计动机
论文 .pdf 引文挖掘 + 概念提取
图片 .png .jpg .webp .gif Claude vision——截图、图表、任意语言都可以

这是一个关键的设计决策：代码文件的结构信息完全通过确定性解析获得，不会把代码内容发送到外部 API。只有文档、论文和图片才需要 LLM 做语义提取。

第二轮：LLM 语义提取（并行子代理）

对文档、论文和图片，Graphify 会并行调用 Claude 子代理，从中提取概念、关系和设计动机。提取结果遵循统一的 schema：

1
2
3
4
5
6
7
8
9
{
  "nodes": [
    {"id": "unique_string", "label": "human name", "source_file": "path", "source_location": "L42"}
  ],
  "edges": [
    {"source": "id_a", "target": "id_b", "relation": "calls|imports|uses|...", 
     "confidence": "EXTRACTED|INFERRED|AMBIGUOUS"}
  ]
}

聚类：Leiden 算法，不依赖 embeddings

这是 Graphify 最反直觉的设计之一——聚类完全基于图拓扑，不使用任何 embedding。

它用的是 Leiden 社区发现算法（通过 graspologic 库），按边密度发现社区。Claude 抽取出的语义相似边（semantically_similar_to，标记为 INFERRED）本来就存在于图中，所以会直接影响社区划分。图结构本身就是相似性信号，不需要额外的 embedding 步骤，也不需要向量数据库。

这意味着什么？意味着 Graphify 的聚类结果是可解释的——你可以追溯到每一条边，看到它为什么被归入某个社区，而不是面对一个黑箱的向量空间。

三级置信度系统：诚实比聪明更重要

Graphify 最让我欣赏的设计是它的三级置信度标签：

标签 含义 置信度
EXTRACTED 直接在源材料中找到的关系（如 import 语句、直接调用） 恒为 1.0
INFERRED 合理推断的关系（如调用图二次分析、上下文共现） 0.0-1.0
AMBIGUOUS 有歧义的关系，需要人工复核 标记待确认

这解决了知识图谱领域一个长期痛点：你怎么知道图里的信息是真的？

大多数知识图谱工具要么全部标记为"确定"（过度自信），要么全部标记为"可能"（信息过载）。Graphify 选择了中间路线——明确区分"我看到了"和"我猜的"，并且告诉你它对猜测有多大把握。

在实际使用中，这意味着你的 AI 助手在基于图谱回答问题时，可以优先使用 EXTRACTED 边的信息，对 INFERRED 边保持谨慎，对 AMBIGUOUS 边主动提示不确定性。

你能得到什么

God Nodes（上帝节点）

度最高的概念节点——整个系统最容易汇聚到的地方。这些通常是你的核心抽象、关键接口、或者那些"改了就全炸"的模块。

意外连接

按综合得分排序的跨域连接。代码-论文之间的边会比代码-代码边权重更高（因为跨域连接通常更有洞察价值）。每条结果都附带一段人话解释。

"为什么"节点

这是 Graphify 独特的价值之一——它不只提取代码"做了什么"，还会从 docstring、行内注释（# NOTE:、# IMPORTANT:、# HACK:、# WHY:）以及文档里的设计动机中提取 rationale_for 节点。这让你能追溯架构决策背后的原因。

超边（Hyperedges）

用来表达 3 个以上节点的群组关系——这是普通两两边表达不出来的。比如：一组类共同实现一个协议、认证链路里的一组函数、同一篇论文某一节里的多个概念共同组成一个想法。

建议提问

图谱会自动生成 4-5 个它特别擅长回答的问题。这些问题通常是你自己想不到但确实有价值的——因为它们来自图的拓扑结构，而不是你的认知框架。

Token 压缩效果：规模越大越明显

这是 Graphify 最硬核的卖点——71.5 倍的 token 压缩。

语料 文件数 压缩比
Karpathy 的仓库 + 5 篇论文 + 4 张图片 52 71.5x
graphify 源码 + Transformer 论文 4 5.4x
httpx（合成 Python 库） 6 ~1x

规律很明显：文件越多，压缩效果越好。6 个文件本来就塞得进上下文窗口，graphify 在这种场景里的价值更多是结构清晰度而非 token 压缩。到了 52 个文件（代码 + 论文 + 图片）这种规模，就能做到 71x+。

换算成钱：有用户反馈，同样的任务、同样的模型、同样的 prompt，使用 Graphify 后从 $1.20 降到了 $0.50。80% 的 AI 编码预算花在了导航文件上，而不是写代码——Graphify 就是在砍这 80%。

当然，第一次运行需要先提取并建图，这一步会花 token；后续查询直接读取压缩后的图谱，节省会越来越明显。SHA256 缓存保证重复运行时只重新处理变更文件。

常驻模式 vs 显式触发：两种使用姿势

常驻模式（推荐日常使用）

1
2
3
graphify claude install    # Claude Code
graphify codex install     # Codex
graphify trae install      # Trae

这会做两件事：

  1. 在 CLAUDE.md（或 AGENTS.md）中写入规则，告诉 AI 在回答架构问题前先读 graphify-out/GRAPH_REPORT.md
  2. 安装 PreToolUse hook（Claude Code），在每次 Glob 和 Grep 前触发

效果是：AI 会先看到一张地图，然后按图导航，而不是一上来就 grep 整个项目。这已经能覆盖大部分日常问题。

显式查询（需要精确答案时）

1
2
3
4
/graphify query "what connects attention to the optimizer?"
/graphify query "what connects attention to the optimizer?" --dfs    # 追踪一条具体路径
/graphify path "DigestAuth" "Response"                               # 两点之间的精确路径
/graphify explain "SwinTransformer"                                  # 解释一个概念

这些命令会逐跳遍历底层 graph.json，追踪节点之间的精确路径，并展示边级别细节（关系类型、置信度、源位置）。

可以这样理解：常驻 hook 是先给助手一张地图，显式查询则是让它沿着地图精确导航。

高级用法：把 Graphify 用到极致

Deep 模式：更激进的推断

1
/graphify ./raw --mode deep

Deep 模式会更激进地抽取 INFERRED 边——比如跨文件的概念连接，即使结构上没有直接依赖也能建立关联。两个函数做的是同一类问题但彼此没有调用？某个代码类和某篇论文里的算法概念本质相同？Deep 模式会把这些关系挖出来。

代价是更多的 API 调用和 token 消耗，但对于需要深度理解的场景（比如接手一个陌生代码库），这个投入是值得的。

Watch 模式：图谱自动同步

1
/graphify ./raw --watch

在后台终端里跑着，代码库一变化，图谱就会跟着更新：

  • 代码文件保存 → 立刻触发重建（只走 AST，不用 LLM）
  • 文档/图片变更 → 提醒你跑 --update 进行 LLM 再提取

这对多 Agent 并行写代码的工作流特别有用——图谱在 Agent 之间自动保持同步。

Git Hooks：每次 commit 自动重建

1
graphify hook install

安装 post-commit 和 post-checkout hook。每次 commit 后、每次切分支后都会自动重建图谱，不需要额外开一个后台进程。

Wiki 模式：为 Agent 生成可导航的知识库

1
/graphify ./raw --wiki

为每个 community 和 god node 生成类似维基百科的 Markdown 文章，并提供 index.md 作为入口。任何 agent 只要读 index.md，就能通过普通文件导航整个知识库，而不必直接解析 JSON。

MCP Server：标准化集成

1
/graphify ./raw --mcp

启动一个 MCP stdio server，让任何支持 MCP 协议的工具都能查询图谱。

增量更新：只处理变更

1
/graphify ./raw --update

只重新提取变更文件，并合并到已有图谱。配合 SHA256 缓存，重复运行的成本极低。

多模态输入：不只是代码

1
2
3
/graphify add https://arxiv.org/abs/1706.03762        # 拉取论文
/graphify add https://x.com/karpathy/status/...       # 拉取推文
/graphify add https://... --author "Name"             # 标记原作者

Andrej Karpathy 会维护一个 /raw 文件夹，把论文、推文、截图和笔记都丢进去。Graphify 就是在解决这类问题——把这些异构信息统一到一张图里。

竞品对比：Graphify 做对了什么

vs Aider 的 Repo Map

Aider 的 repo-map 也用 tree-sitter 做 AST 解析，但它的目标是生成一个扁平的符号列表（文件名 + 类名 + 函数签名），然后用 PageRank 算法选择最相关的文件发送给 LLM。

关键差异：

  • Aider：符号列表 → PageRank 排序 → 发送最相关的文件片段。本质是"更聪明的文件选择器"
  • Graphify：知识图谱 → 社区发现 → 持久化查询。本质是"代码库的结构化记忆"

Aider 每次对话都要重新计算 repo-map，而 Graphify 的图谱是持久化的，可以跨会话复用。Aider 不处理非代码文件（论文、图片），Graphify 是完全多模态的。

vs Repomix

Repomix 的思路更简单粗暴——把整个代码库打包成一个 AI 友好的文本文件，直接塞进上下文窗口。

关键差异：

  • Repomix：全量打包 → 一次性塞入上下文。适合小项目，大项目会爆上下文
  • Graphify：结构化压缩 → 按需查询。规模越大优势越明显

Repomix 不做任何结构分析，它只是一个"格式化器"。Graphify 理解代码的结构关系。

vs Microsoft GraphRAG

GraphRAG 是微软提出的将知识图谱与 RAG 结合的方法论，主要面向通用文本理解。

关键差异：

  • GraphRAG：通用文本 → LLM 全量提取实体和关系 → 社区摘要 → 检索。API 调用成本极高
  • Graphify：代码优先 → AST 确定性提取 + LLM 语义补充 → 混合图。代码部分零 API 成本

GraphRAG 对代码的理解是"把代码当文本"，而 Graphify 对代码的理解是"先解析结构，再补充语义"。这个差异在实际效果上非常显著——AST 提取的调用关系、导入关系是 100% 准确的，而 LLM 从代码文本中提取的关系总会有噪声。

vs 传统代码搜索（Sourcegraph 等）

传统代码搜索工具做的是精确匹配——你知道要找什么，它帮你找到在哪。Graphify 做的是结构发现——你不知道代码库里有什么关系，它帮你发现。

这是两个完全不同的问题空间，互补而非替代。

用户遇到的真实问题

根据 GitHub Issues 和社区反馈，当前用户遇到的主要问题包括：

稳定性问题

  • --watch 模式崩溃（#394、#386）：v0.4.15 版本在 macOS 上 NameError: name 'sys' is not defined，这是一个回归 bug
  • 语义提取节点 ID 与 AST 节点 ID 不对齐（#390）：导致合并时丢边，这是一个架构层面的问题
  • .mjs 文件提取为空（#387）：新语言支持的不完整修复

平台兼容性

  • VSCode 安装失败（#374）：Graphify 原生是 Claude Code skill，在其他 IDE 中的集成还不够成熟
  • Windsurf、Hermes Agent、Qoder IDE 等平台的支持请求（#353、#346、#332）：说明社区需求旺盛但平台覆盖还在追赶

团队协作

  • 团队协作工作流不明确（#369）：图谱是否应该提交到 Git？多人同时修改怎么合并？这些问题还没有官方最佳实践

大项目的 Token 消耗

对于大 PR 审查，多个 Agent 同时运行时，一次 review 消耗的 token 可能比写代码本身还多。小 PR 体验良好，但大 PR 建议先拆分再审查。

我的判断：它解决了一个真实的结构性问题

Graphify 的核心洞察是：AI 编码助手的瓶颈不在生成能力，而在理解能力；理解能力的瓶颈不在模型智商，而在上下文质量。

当你的 AI 助手花 80% 的 token 在 grep 文件上时，它不是在"理解"你的代码库，它是在"翻找"你的代码库。Graphify 把"翻找"变成了"查图"，这是一个质的变化。

但它也有明确的局限：

  1. 首次构建成本不低：对大型代码库，第一次运行需要相当的时间和 token
  2. 图谱质量依赖 LLM 提取质量：INFERRED 边的准确性取决于底层模型的能力
  3. 团队协作场景还不成熟：图谱的版本控制和多人协作还没有成熟方案
  4. 平台覆盖还在扩展中：虽然已支持 7 个平台，但每个平台的集成深度不同

尽管如此，Graphify 代表了一个重要的方向：AI 编码助手需要的不是更大的上下文窗口，而是更好的上下文结构。知识图谱提供了一种比向量数据库更可解释、比全文搜索更有结构的中间表示。

如果你正在用 Claude Code 或 Codex 做日常开发，尤其是在中大型代码库上，Graphify 值得一试。它可能不会让你的 AI 助手变得更聪明，但会让它看得更清楚。

快速上手清单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 1. 安装
pip install graphifyy && graphify install

# 2. 对当前项目构建图谱
# 在 Claude Code / Codex / Trae 中输入：
/graphify .

# 3. 设置常驻模式（推荐）
graphify claude install    # 或 codex/trae/opencode 等

# 4. 安装 Git hooks（可选但推荐）
graphify hook install

# 5. 日常使用
# 直接提问，AI 会自动参考图谱
# 需要精确答案时：
/graphify query "这两个模块之间是什么关系？"
/graphify path "ModuleA" "ModuleB"
/graphify explain "CoreService"

参考资料