graphify
把任意代码文件夹、数据库 schema、文档、图片甚至视频转化为可查询的知识图谱，AI 编程助手（Claude Code、Cursor 等）通过此图谱理解项目结构，替代传统的 grep 或向量检索。亮点在于代码解析完全本地化（tree-sitter AST，零 LLM 调用），图谱边带有 EXTRACTED/INFERRED 置信标签，支持跨文件依赖追踪和自然语言查询。benchmark 显示在代码检索和 QA 上表现优于 mem0 等方法，且不消耗 LLM token。
README
🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇮🇳 हिन्दी | 🇧🇷 Português | 🇷🇺 Русский | 🇸🇦 العربية | 🇮🇷 فارسی | 🇮🇹 Italiano | 🇵🇱 Polski | 🇳🇱 Nederlands | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇻🇳 Tiếng Việt | 🇮🇩 Bahasa Indonesia | 🇸🇪 Svenska | 🇬🇷 Ελληνικά | 🇷🇴 Română | 🇨🇿 Čeština | 🇫🇮 Suomi | 🇩🇰 Dansk | 🇳🇴 Norsk | 🇭🇺 Magyar | 🇹🇭 ภาษาไทย | 🇺🇿 Oʻzbekcha | 🇹🇼 繁體中文 | 🇵🇭 Filipino | 🇮🇱 עברית
在你的 AI 编码助手中输入 /graphify，它会将整个项目（代码、文档、PDF、图片、视频）映射成一个知识图谱，你可以通过查询而非 grep 文件来理解项目。
- 免费生成代码图，完全本地运行。 代码通过 tree-sitter AST 解析：确定性，不依赖 LLM，数据不会离开你的机器。（文档、PDF、图片和视频使用你助手的模型，或配置的 API key，进行语义分析。）
- 每条边都有解释。 每个连接被标记为
EXTRACTED（源中显式）或INFERRED（由 graphify 解析），这样你就知道哪些是直接读取的，哪些是推断的。 - 不是向量索引。 没有 embedding，没有向量存储：是一个真正的图，你可以遍历它。问一个问题，追踪两个事物之间的路径，或解释一个概念。
graphify 映射的 FastAPI 代码库。每个节点是一个概念，颜色表示检测到的社区，整个图在 graph.html 中可点击。
快速开始（30 秒）：
uv tool install graphifyy # 安装 CLI（或：pipx install graphifyy）
graphify install # 将技能注册到你的 AI 助手
然后，在你的 AI 助手中：
/graphify .
这就行了。你会得到三个文件：
graphify-out/
├── graph.html 在任意浏览器中打开 — 点击节点、过滤、搜索
├── GRAPH_REPORT.md 亮点：关键概念、出人意料的连接、建议的问题
└── graph.json 完整图 — 随时查询，无需重新读取文件
支持 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 等 15 个以上平台 — 请查看你的平台。
实际效果
图构建好后，你通过查询而不是阅读文件来理解代码。以下是真实输出，graphify 运行在上方展示的 FastAPI 代码库上：
$ graphify explain "APIRouter"
Node: APIRouter
Source: routing.py L2210
Community: 2
Degree: 47
Connections (47):
--> RequestValidationError [uses] [INFERRED]
--> Dependant [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 = 通过解析推导），因此你可以区分直接读取的内容和推断的内容。graphify query "<question>" 会为自然语言问题返回一个子图，graphify path A B 可追踪任意两个事物之间的连接路径。
它能做什么
开箱即用的能力：
| 能力 | 你得到什么 |
|---|---|
| 核心节点 | 连接最多的概念，展示所有事物如何流通 |
| 社区 | 图被拆分为子系统（Leiden 算法），并带有 LLM 无关的标签 |
| 跨文件链接 | calls / imports / inherits / mixes_in 通过 tree-sitter AST 在约 40 种语言中解析 |
| 查询、路径、解释 | 问问题、追踪两个事物之间的路径、或解释一个概念，都基于 graph.json |
| 设计理由 + 文档引用 | # NOTE: / # WHY: 注释和 ADR/RFC 引用成为一等节点，链接到它们解释的代码 |
| 超越代码 | 文档、PDF、图片、视频/音频都映射到同一个图 |
| 本地优先 | 代码通过 tree-sitter 在本地解析（无 LLM，数据不离开机器）；只有文档/媒体的语义分析需要调用后端，且仅在你配置时进行 |
基准测试
| 基准 | 指标 | graphify | 其他系统 |
|---|---|---|---|
| LOCOMO (n=300) | recall@10 | 0.497 | mem0 0.048, supermemory 0.149 |
| LOCOMO (n=300) | QA 准确率 | 45.3% | supermemory 49.7%, mem0 27.3% |
| LongMemEval-S (n=50) | QA 准确率 | 76% | 与密集 RAG 并列 |
| 图构建 | LLM 信用点 | 0 | 大多数系统按 token 计费 |
每个系统在相同测试框架下使用相同的模型和预算运行，由一位验证者（与第二位验证者盲校，一致性 90.6%，Cohen's kappa 0.81）评分。完整的系统表格、代码智能结果和复现命令：BENCHMARKS.md。
先决条件
| 要求 | 最低版本 | 检查 | 安装 |
|---|---|---|---|
| Python | 3.10+ | python --version |
python.org |
| uv (推荐) | 任意 | uv --version |
curl -LsSf https://astral.sh/uv/install.sh | sh |
| pipx (替代) | 任意 | pipx --version |
pip install pipx |
macOS 快速安装（Homebrew）：
brew install python@3.12 uv
Windows 快速安装：
winget install astral-sh.uv
Ubuntu/Debian：
sudo apt install python3.12 python3-pip pipx
# 或安装 uv：
curl -LsSf https://astral.sh/uv/install.sh | sh
安装
官方包： PyPI 包名是
graphifyy（双 y）。PyPI 上其他graphify*包不是官方的。CLI 命令仍然是graphify。
第 1 步 — 安装包：
# 推荐（隔离环境；如果之后找不到 'graphify'，运行：uv tool update-shell）：
uv tool install graphifyy
# 备选：
pipx install graphifyy
pip install graphifyy # 可能需要设置 PATH — 见下方说明
第 2 步 — 将技能注册到你的 AI 助手：
graphify install
这就行了。打开你的 AI 助手并输入 /graphify .
如果你想将助手技能安装到当前仓库而非用户配置文件中，添加 --project：
graphify install --project
graphify install --project --platform codex
项目范围安装会把文件写到当前目录下，例如 .claude/skills/graphify/SKILL.md 或 .agents/skills/graphify/SKILL.md（以及一个按需加载的 references/ 侧载文件），并打印一条 git add 提示，告诉你可以提交哪些文件。支持项目范围安装的各个平台命令也接受同样的标志，例如 graphify claude install --project 或 graphify codex install --project。
PowerShell 注意： 使用
graphify .而不是/graphify .— 前导斜杠在 PowerShell 中是路径分隔符。
graphify: command not found？uv tool install/pipx install将graphify命令放到它们的工具 bin 目录（~/.local/bin）。如果你安装后 shell 立刻找不到它——在全新的 macOS + zsh 设置中常见——说明该目录尚未加入你的PATH：运行uv tool update-shell（或pipx ensurepath），然后打开一个新的终端。如果使用纯pip，请将~/.local/bin（Linux）或~/Library/Python/3.x/bin（Mac）添加到你的 PATH，或者运行python -m graphify。
使用
uvx/uv tool run而不是安装？ 请指定包名而不是命令：uvx --from graphifyy graphify install。单纯的uvx graphify …会失败（No solution found … no versions of graphify），因为uv tool run将第一个单词视为包名，而包名是graphifyy—graphify命令在它里面。
Mac/Windows 上尽量避免使用
pip install。 技能在运行时从graphify-out/.graphify_python解析 Python 路径；如果该路径指向一个与pip安装包的环境不同的环境，你会得到ModuleNotFoundError: No module named 'graphify'。uv tool install和pipx install将包隔离在自己的环境中，完全避免了这个问题。
选择你的平台（20+ 助手，点击展开）Git hooks 和 uv tool / pipx：
graphify hook install在安装时将当前解释器路径直接嵌入到 hook 脚本中，因此 post-commit hook 即使在 GUI git 客户端和 CI 运行器中也能正确触发，这些场景下~/.local/bin不在 PATH 中。如果你重新安装或升级 graphify，请重新运行graphify hook install以刷新嵌入的路径。
| 平台 | 安装命令 |
|---|---|
| Claude Code（Linux/Mac） | graphify install |
| Claude Code（Windows） | graphify install（自动检测）或 graphify install --platform windows |
| CodeBuddy | graphify install --platform codebuddy |
| Codex | graphify install --platform codex |
| OpenCode | graphify install --platform opencode |
| Kilo Code | graphify install --platform kilo |
| GitHub Copilot CLI | graphify install --platform copilot |
| VS Code Copilot Chat | graphify vscode install |
| Aider | graphify install --platform aider |
| OpenClaw | graphify install --platform claw |
| Factory Droid | graphify install --platform droid |
| Trae | graphify install --platform trae |
| Trae CN | graphify install --platform trae-cn |
| Gemini CLI | graphify install --platform gemini |
| Hermes | graphify install --platform hermes |
| Kimi Code | graphify install --platform kimi |
| Amp | graphify amp install |
| Agent Skills（跨框架） | graphify install --platform agents（别名 --platform skills） |
| Kiro IDE/CLI | graphify kiro install |
| Pi coding agent | graphify install --platform pi |
| Cursor | graphify cursor install |
| Devin CLI | graphify devin install |
| Google Antigravity | graphify antigravity install |
Codex 用户还需要在 ~/.codex/config.toml 的 [features] 下设置 multi_agent = true 以启用并行提取。CodeBuddy 使用与 Claude Code 相同的 Agent tool 和 PreToolUse hook 机制。Factory Droid 使用 Task 工具进行并行子代理调度。OpenClaw 和 Aider 使用顺序提取（这些平台上并行代理支持尚处于早期）。Trae 使用 Agent 工具进行并行子代理调度，并且不支持 PreToolUse hooks，因此 AGENTS.md 是常驻机制。
--platform agents（别名 --platform skills）针对通用跨框架 Agent-Skills 规范的位置：用户全局安装写 ~/.agents/skills/（npx skills 和符合规范的框架都会读取该目录），项目安装（--project）写 ./.agents/skills/。裸的 graphify install 保持单平台（Claude Code）设计——当你希望技能能被任何读取 .agents/skills 的框架发现时，请使用 agents 平台名称。
可选扩展（只安装你需要的）Codex 使用
$graphify而不是/graphify。
| 扩展 | 添加内容 | 安装命令 |
|---|---|---|
pdf |
PDF 提取 | uv tool install "graphifyy[pdf]" |
office |
.docx 和 .xlsx 支持 |
uv tool install "graphifyy[office]" |
google |
Google Sheets 渲染 | uv tool install "graphifyy[google]" |
video |
视频/音频转录（faster-whisper + yt-dlp） | uv tool install "graphifyy[video]" |
mcp |
MCP stdio 服务器 | uv tool install "graphifyy[mcp]" |
neo4j |
Neo4j 推送支持 | uv tool install "graphifyy[neo4j]" |
falkordb |
FalkorDB 推送支持 | uv tool install "graphifyy[falkordb]" |
svg |
SVG 图导出 | uv tool install "graphifyy[svg]" |
leiden |
Leiden 社区检测（仅 Python < 3.13） | uv tool install "graphifyy[leiden]" |
ollama |
Ollama 本地推理 | uv tool install "graphifyy[ollama]" |
openai |
OpenAI / OpenAI 兼容 API | uv tool install "graphifyy[openai]" |
gemini |
Google Gemini API | uv tool install "graphifyy[gemini]" |
anthropic |
Anthropic Claude API（--backend claude，使用 ANTHROPIC_API_KEY） |
uv tool install "graphifyy[anthropic]" |
bedrock |
AWS Bedrock（使用 IAM，无需 API key） | uv tool install "graphifyy[bedrock]" |
azure |
Azure OpenAI 服务（--backend azure，使用 AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT） |
uv tool install "graphifyy[openai]" |
sql |
SQL 架构提取 | uv tool install "graphifyy[sql]" |
postgres |
实时 PostgreSQL 内省（--postgres DSN） |
uv tool install "graphifyy[postgres]" |
dm |
BYOND DreamMaker .dm/.dme AST 提取（可能需要 C 编译器和 python3-dev 如果没有匹配你平台的 wheel） |
uv tool install "graphifyy[dm]" |
terraform |
Terraform / HCL .tf/.tfvars/.hcl AST 提取 |
uv tool install "graphifyy[terraform]" |
pascal |
Pascal / Delphi .pas/.dpr/.dpk/.inc AST 提取（更准确的 calls/inherits 边；缺少时退回到正则提取器） |
uv tool install "graphifyy[pascal]" |
chinese |
中文查询分词（jieba） | uv tool install "graphifyy[chinese]" |
all |
以上所有 | uv tool install "graphifyy[all]" |
让你的助手始终使用图
在构建图之后，在你的项目中运行一次以下命令：
| 平台 | 命令 |
|---|---|
| Claude Code | graphify claude install |
| CodeBuddy | graphify codebuddy install |
| Codex | graphify codex install |
| OpenCode | graphify opencode install |
| Kilo Code | graphify kilo install |
| GitHub Copilot CLI | graphify copilot install |
| VS Code Copilot Chat | graphify vscode install |
| Aider | graphify aider install |
| OpenClaw | graphify claw install |
| Factory Droid | graphify droid install |
| Trae | graphify trae install |
| Trae CN | graphify trae-cn install |
| Cursor | graphify cursor install |
| Gemini CLI | graphify gemini install |
| Hermes | graphify hermes install |
| Kimi Code | graphify install --platform kimi |
| Amp | graphify amp install |
| Agent Skills（跨框架） | graphify agents install（别名 graphify skills install） |
| Kiro IDE/CLI | graphify kiro install |
| Pi coding agent | graphify pi install |
| Devin CLI | graphify devin install |
| Google Antigravity | graphify antigravity install |
这会写入一个小配置文件，告诉你的助手在回答代码库问题时查阅知识图，优先使用范围查询如 graphify query "<question>"，而不是阅读完整报告或直接 grep 原始文件。
- Hook 平台（Claude Code、Gemini CLI）：在搜索类工具调用之前自动触发一个 hook（在 Claude Code 上，还在通过 Read/Glob 工具逐个读取源文件之前触发），引导你的助手走图的路径。
- 指令文件平台（Codex、OpenCode、Cursor 等）：持久化的指令文件（
AGENTS.md、.cursor/rules/等）提供同样的先查询后阅读的指导。
GRAPH_REPORT.md 仍然可用于宏观架构审查。
CodeBuddy 做两件事，与 Claude Code 类似：写一个 CODEBUDDY.md 部分告诉 CodeBuddy 在回答架构问题之前先读取 graphify-out/GRAPH_REPORT.md，并安装 PreToolUse hooks（.codebuddy/settings.json），在 Bash 搜索命令和文件读取之前触发，引导使用 graphify query 而不是直接搜索。
Codex 写 AGENTS.md，还在 .codex/hooks.json 中安装一个 PreToolUse hook，在每次 Bash 工具调用前触发，与 Claude Code 的常驻机制相同。
Kilo Code 将 Graphify 技能安装到 ~/.config/kilo/skills/graphify/SKILL.md 以及一个原生的 /graphify 命令到 ~/.config/kilo/command/graphify.md。graphify kilo install 还会写入 AGENTS.md 以及一个原生的 tool.execute.before 插件（.kilo/plugins/graphify.js + .kilo/kilo.json 或 .kilo/kilo.jsonc 注册），这样 Kilo 也能通过原生的 .kilo 配置获得常驻的图提醒行为。
Cursor 写入 .cursor/rules/graphify.mdc，设置 alwaysApply: true，因此 Cursor 会在每次对话中自动包含它，无需 hook。
要一次性从所有平台移除 graphify：graphify uninstall（添加 --purge 可同时删除 graphify-out/）。或者使用特定平台的命令（例如 graphify claude uninstall）。
报告包含什么
- 核心节点 — 项目中连接最多的概念。所有东西都流经这些节点。
- 出人意料的连接 — 位于不同文件或模块中的事物之间的链接。按意外程度排序。
- "为什么" — 内联注释（
# NOTE:、# WHY:、# HACK:）、文档字符串和设计理由被提取为单独的节点，链接到它们解释的代码。 - 建议问题 — 4-5 个该图特别适合回答的问题。
- 置信度标签 — 每个推断的关系被标记为
EXTRACTED、INFERRED或AMBIGUOUS。你始终知道哪些是发现到的，哪些是猜测的。
支持的文件类型
| 类型 | 扩展名 |
|---|---|
| 代码（36 种 tree-sitter 语法） | .py .ts .mts .cts .js .jsx .tsx .mjs .go .rs .java .c .cpp .cc .cxx .h .hpp .cu .cuh .metal .rb .cs .kt .kts .scala .php .swift .lua .luau .toc .zig .ps1 .psm1 .psd1 .ex .exs .m .mm .jl .vue .svelte .astro .groovy .gradle .dart .v .sv .svh .sql .f .f90 .f95 .f03 .f08 .pas .pp .dpr .dpk .lpr .inc .dfm .lfm .lpk .sh .bash .json .dm .dme .dmi .dmm .dmf .sln .slnx .csproj .fsproj .vbproj .xaml .razor .cshtml (.dm/.dme 需要 uv tool install graphifyy[dm]；.mts/.cts 复用 TypeScript 语法，.cc/.cxx 和 CUDA .cu/.cuh 以及 Metal .metal 复用 C++ 语法) |
| Salesforce Apex | .cls .trigger（基于正则表达式；类、接口、枚举、方法、触发器、SOQL/DML 边） |
| Terraform / HCL | .tf .tfvars .hcl（需要 uv tool install graphifyy[terraform]） |
| MCP 配置 | .mcp.json mcp.json mcp_servers.json claude_desktop_config.json — 提取服务节点、包引用、环境变量要求 |
| 包清单 | apm.yml pyproject.toml go.mod pom.xml — 每个包一个规范节点（按名称），加上 depends_on 边，因此从多个清单中引用的包是一个单一枢纽 |
| 文档 | .md .mdx .qmd .html .txt .rst .yaml .yml（markdown [text](./other.md) 链接和 [[wikilinks]] 成为文档之间的 references 边） |
| Office | .docx .xlsx（需要 uv tool install graphifyy[office]） |
| Google Workspace | .gdoc .gsheet .gslides（需选择加入；需要 gws 认证和 --google-workspace；Sheets 需要 uv tool install graphifyy[google]） |
| PDFs | .pdf |
| 图片 | .png .jpg .webp .gif |
| 视频/音频 | .mp4 .mov .mp3 .wav 等（需要 uv tool install graphifyy[video]） |
| YouTube / URLs | 任意视频 URL（需要 uv tool install graphifyy[video]） |
代码本地提取，无需 API 调用（通过 tree-sitter AST）。其他所有内容通过你的 AI 助手的模型 API 处理。
Google Drive for Desktop 的 .gdoc、.gsheet 和 .gslides 文件是快捷方式指针，不是文档内容。要在无头提取中包含原生 Google Docs、Sheets 和 Slides，请安装并认证 gws CLI，然后运行：
uv tool install "graphifyy[google]" # 需要用于 Google Sheets 表格渲染
gws auth login -s drive
graphify extract ./docs --google-workspace
你也可以设置 GRAPHIFY_GOOGLE_WORKSPACE=1。Graphify 将快捷方式导出到 graphify-out/converted/ 作为 Markdown 侧载文件，然后提取这些文件。
常用命令
/graphify . # 为当前文件夹构建图
/graphify ./docs --update # 仅重新提取已更改的文件
/graphify . --cluster-only # 仅重新聚类，不重新提取
/graphify . --cluster-only --resolution 1.5 # 更细粒度的社区
/graphify . --cluster-only