graphify
AI 编码助手技能插件，将任意代码库、文档、图片等转为可查询的知识图谱，替代传统 grep 检索。基于 tree-sitter AST 本地解析代码，无需 LLM 调用；文档/图片等借助助手模型进行语义提取。亮点是与 Claude Code、Cursor、Gemini CLI 等 20+ 平台无缝集成，生成交互式 HTML 图谱和查询接口，且代码解析完全本地化，隐私友好。当前因提升开发效率而受到关注。
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 个以上平台——选择你的平台。
实际效果
图谱构建完成后，你可以直接查询它，而不是阅读文件。以下是在上述 FastAPI 代码库上运行 graphify 的真实输出：
$ graphify explain "APIRouter"
节点: APIRouter
来源: routing.py L2210
社区: 2
度数: 47
连接 (47):
--> RequestValidationError [uses] [INFERRED]
--> Dependant [uses] [INFERRED]
--> .get() [method] [EXTRACTED]
<-- __init__.py [imports] [EXTRACTED]
...
$ graphify path "FastAPI" "ModelField"
最短路径 (3 跳):
FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField
每条边都带有置信度标签（EXTRACTED = 源文件中显式存在，INFERRED = 通过解析推导得出），因此你可以区分哪些是从源文件直接读取的，哪些是推理出来的。graphify query "<question>" 对自然语言问题返回一个限定范围的子图，graphify path A B 则追踪任意两个事物之间的连接方式。
功能概览
开箱即用的功能：
| 能力 | 说明 |
|---|---|
| 上帝节点 | 连接最多的概念，让你看到所有事物流经哪里 |
| 社区 | 图谱按子系统分割（Leiden 算法），无需 LLM 自动生成标签 |
| 跨文件链接 | 通过 tree-sitter AST 在约 40 种语言中解析 calls / imports / inherits / mixes_in |
| 查询、路径、解释 | 提出问题、追踪两个事物之间的路径、或解释一个概念，全部基于 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 脚本中，因此即使在 GUI git 客户端和 CI 运行器中（~/.local/bin不在 PATH 上），post-commit hook 也能正确触发。如果你重新安装或升级 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 工具和 PreToolUse hook 机制。Factory Droid 使用 Task 工具进行并行子代理调度。OpenClaw 和 Aider 使用顺序提取（这些平台上对并行代理的支持仍处于早期阶段）。Trae 使用 Agent 工具进行并行子代理调度，但不支持 PreToolUse hook，因此 AGENTS.md 是始终在线的机制。
--platform agents（别名 --platform skills）针对通用跨框架 Agent-Skills 位置：标准全局 ~/.agents/skills/（由 npx skills 和符合标准的框架读取）用于全局安装，以及 ./.agents/skills/ 用于项目（--project）安装。裸 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 Service（--backend azure，使用 AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT） |
uv tool install "graphifyy[openai]" |
sql |
SQL schema 提取 | uv tool install "graphifyy[sql]" |
postgres |
实时 PostgreSQL 内省（--postgres DSN） |
uv tool install "graphifyy[postgres]" |
dm |
BYOND DreamMaker .dm/.dme AST 提取（如果平台没有匹配的 wheel，可能需要 C 编译器和 python3-dev） |
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），这些 hook 在 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]） |
.pdf |
|
| 图片 | .png .jpg .webp .gif |
| 视频 / 音频 | .mp4 .mov .mp3 .wav 等（需要 uv tool install graphifyy[video]） |
| YouTube / URL | 任何视频 URL（需要 uv tool install graphifyy[video]） |
代码提取在本地完成，无需 API 调用（通过 tree-sitter 进行 AST 解析）。其他所有内容通过你的 AI 助手的模型 API 处理。
Google Drive for desktop 的 .gdoc、.gsheet 和 .gslides 文件是指针快捷方式，而非文档内容。要在无头提取中包含原生 Google 文档、表格和幻灯片，请安装并认证 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 --exclude-hubs 99 # 抑制工具性超级枢纽出现在上帝节点排名中
/graphify . --no-viz # 跳过 HTML，只生成报告 + JSON
/graphify . --wiki # 从图谱构建 markdown wiki
graphify export callflow-html # Mermaid 架构/调用流 HTML（如果安装了 hook，每次 git commit 时自动重新生成）
/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"
/graphify add https://arxiv.org/abs/1706.03762 # 获取论文并添加
/graphify add <youtube-url> # 转录并添加视频
graphify hook install # 在 git commit 时自动重建
graphify merge-graphs a.json b.json # 合并两个图谱
graphify prs # PR 面板：CI 状态、审查状态、工作树映射
graphify prs 42 # 深入分析 PR #42 及其图谱影响
graphify prs --triage # AI 排序你的审查队列（使用已配置的后端）
graphify prs --conflicts # 共享图谱社区的 PR——合并顺序风险
请参阅下面的完整命令参考。
忽略文件
在项目根目录创建 .graphifyignore——语法与 .gitignore 相同，包括 ! 否定。
.gitignore 会自动被尊重。 graphify 读取每个目录的 .gitignore。如果同时存在 .graphifyignore，两者会合并——.graphifyignore 模式最后评估，因此在冲突时优先（包括 ! 否定）。添加 .graphifyignore 只会排除更多文件；它永远不会重新包含 .gitignore 已排除的文件。子目录作用域与 git 相同——忽略文件只影响其自己的子树。
# .graphifyignore
node_modules/
dist/
*.generated.py
# 只索引 src/，忽略其他所有
*
!src/
!src/**