Graphify-Labs/graphify · 上手攻略

  • 仓库：Graphify-Labs/graphify
  • 链接：https://github.com/Graphify-Labs/graphify
  • 分类：ai
  • 作者：Jay
  • 更新：2026-07-12

是什么

Graphify 是一个让 AI 编程助手（Claude Code、Cursor、Codex 等）把任意代码仓库转化为可查询知识图谱的工具。本质是一个 Claude Code / AI Coding Agent 的 /graphify 技能（Skill）：输入 /graphify .，它便将项目代码、文档、图片、视频全部映射为一张节点-边图谱，之后你可以用自然语言问它问题，而不是让模型反复重新读文件。

核心特点： - 不是向量检索：基于真实图谱遍历，节点之间的每条边都标注了 EXTRACTED（代码中显式存在）或 INFERRED（通过类型/引用解析推断），可溯源。 - 本地优先：代码解析用 tree-sitter AST，完全本地化，无 LLM 调用、无数据外传；文档/图片/视频的语义理解才需要模型 API（可选）。 - 跨文件引用解析：支持 ~40 种编程语言的 AST 解析，跨文件调用、import、继承等引用关系全部resolve。 - Benchmark 亮眼：在 LOCOMO（n=300）recall@10 达 0.497，远超 mem0（0.048）和 supermemory（0.149）；LongMemEval QA 准确率 76%，与 Dense RAG 持平，但构建图谱 LLM 消耗为 0。

解决什么问题

让 AI 编程助手真正"懂"你的代码库，而不是每次都靠 prompt 塞上下文。当你想知道「这个模块依赖谁」「两段代码之间有什么关联路径」「APIRouter 关联哪些概念」时，Graphify 直接在图谱上查，告诉你精确的代码位置和关联路径，避免 LLM 幻觉或遗漏文件。

典型场景： - 大型代码库（几千行以上）里快速定位任意概念 - 理解一个陌生项目的架构和依赖关系 - 追踪一段功能涉及哪些文件 - 替代反复用 grep + 多次对话的繁琐操作

快速安装

前置要求

组件 最低版本 说明
Python 3.10+ python --version 检查
uv 任意版本 推荐，隔离环境安装
pipx 任意版本 备选

macOS（Homebrew）：

brew install python@3.12 uv

Linux（Ubuntu/Debian）：

sudo apt install python3.12 python3-pip pipx
# 或安装 uv：
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows：

winget install astral-sh.uv

安装 graphify CLI

⚠️ 注意：官方 PyPI 包名是 graphifyy（双 y），CLI 命令名仍是 graphify。其他 graphify* 开头的包均无关。

# 推荐（隔离环境，自动 PATH）：
uv tool install graphifyy

# 备选：
pipx install graphifyy
pip install graphifyy

安装后如果提示 graphify: command not found，运行：

uv tool update-shell   # 然后开一个新终端

注册到 AI 编程助手

graphify install       # 注册到用户级（所有项目可用）
# 或
graphify install --project   # 仅当前目录（可提交到 git）

不同 AI 助手的注册方式：

graphify claude install          # Claude Code
graphify cursor install          # Cursor
graphify codex install          # Codex CLI
graphify opencode install        # OpenCode

PowerShell 用户注意：使用 graphify .（无前导斜杠），因为 / 在 PowerShell 里是路径分隔符。

核心用法

构建图谱

在 AI 编程助手的对话里输入：

/graphify .

等待完成后，得到三个文件（默认在 graphify-out/ 目录）：

graphify-out/
├── graph.html          # 可交互图谱，在浏览器打开
├── GRAPH_REPORT.md     # 关键概念、高亮连接、推荐问题
└── graph.json          # 完整图谱，随时可查

查询图谱

构建完成后，直接在对话中用自然语言提问：

/graphify query "RequestValidationError 和 APIRouter 之间有什么关系？"

解释某个节点

graphify explain "APIRouter"

输出该节点的详细信息：所在文件、行号、关联的 47 条边（每个连接的来源和关系类型）。

查两点间路径

graphify path "FastAPI" "ModelField"

返回最短路径，例如：FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

交互式图谱

直接打开 graphify-out/graph.html，在浏览器里点击节点、筛选、搜索，不依赖任何服务器。

典型适用场景

场景 为什么用 Graphify
接手陌生大型代码库 输入 /graphify . 后直接用自然语言问「这个项目的数据流是什么」，比读 README 更精准
调试跨文件引用 bug 用 graphify path 追踪变量如何在多个模块间传递
Code Review 让模型基于图谱回答「这个 PR 改动了哪些子系统」，比 diff 更系统
文档生成 graph.html 可以直接嵌入内部文档站点
AI 编程助手（Claude Code/Cursor）用户 安装一次，之后每个项目都能用，零额外 prompt

坑与注意

  1. PowerShell 前导斜杠：/graphify . 在 PowerShell 里会报错，用 graphify .。
  2. PATH 找不到命令：安装后立刻用需要先 uv tool update-shell 或重开终端。
  3. 包名是 graphifyy 不是 graphify：pip install 时输错包名会装到其他人的无关包。
  4. 文档/媒体需要 API Key：代码解析完全本地，但 PDF/图片/视频的语义理解需要配置模型 API（graphify install 时可选）。
  5. Python 版本：最低 3.10，macOS 系统自带 Python 可能低于此版本，需单独安装。
  6. 项目级安装 vs 用户级：--project 安装写入 .claude/skills/ 或 .agents/skills/，可提交到 git，适合团队共享；用户级安装每个项目自动继承。
  7. 图谱重建：代码改动后需重新运行 /graphify . 重建图谱，不会自动增量更新。

与同类对比

方案 索引类型 本地化 LLM 依赖 适用场景
Graphify 知识图谱（tree-sitter AST） ✅ 代码完全本地 可选（仅媒体） 大型代码库理解、跨文件追踪
mem0 向量嵌入 ❌ 必需 长期记忆、对话上下文
supermemory 向量嵌入 ❌ 必需 个人知识管理
Dense RAG 向量嵌入 ❌ 必需 文档问答
sourROUND 依赖 LLM 重读文件 ❌ 必需 快速简单场景

Graphify 的核心优势：不是向量库，是真实图谱，边有语义标签（EXTRACTED/INFERRED），可查路径、可解释推理过程。Benchmark 在 recall@10 远超竞品（0.497 vs 0.048~0.149）。

一句话推荐结论

如果你用 Claude Code / Cursor 等 AI 编程助手处理过百行以上的代码项目，装上 Graphify 就能让它"全局理解"你的代码——不是靠塞更多上下文，而是靠一张可查询的图谱。

周增 +3752 | Stars 76856 | 语言 Python | 许可 Apache-2.0