Graphify 实战指南：把代码库、文档与 PDF 变成可查询的知识图谱

Graphify 是一个 AI 编程助手技能：在 Claude Code、Codex、Cursor、Gemini CLI 等助手中输入 /graphify，它会读取你的整个项目（代码、文档、PDF、图片、音视频），用本地 tree-sitter AST 确定性解析代码，构建出一张可查询的知识图谱，让你"查图"替代"翻文件"。本篇基于 Graphify 仓库中的波斯语版 README（README.fa-IR.md）及其英文主文档与源码实现，完整覆盖从安装、技能注册、平台适配、忽略规则、团队工作流、MCP 服务到无头提取（CI）与排障的全部技术细节，并附源码级证据。读完你应能独立完成：安装 CLI、为 20 余个助手平台注册技能、生成并查询 graph.json、把图谱以 MCP/HTTP 形式共享给团队，以及在 CI 中运行 graphify extract。

一、核心定位：图谱而非向量索引

Graphify 有三个与典型 RAG 方案不同的设计决策（见 README.md）：

• 代码免费本地映射：代码用 tree-sitter AST 解析，确定性、无 LLM、不离开你的机器；只有文档/PDF/图片/视频的语义抽取才调用模型 API；
• 每条边都有解释：每条连接被标记为 EXTRACTED（源码中明确存在）或 INFERRED（由 graphify 解析推断），你始终知道哪些是直接读到的、哪些是推断的；
• 不是向量索引：没有 embedding、没有向量库，而是一张真正可遍历的图——可以提问、追踪两个概念之间的最短路径、解释单个概念。

波斯语版 README 中引用了 Andrej Karpathy 的 /raw 文件夹场景（把文章、推文、截图、笔记往里扔），并给出 README 声称的指标：相比直接读原始文件，每次查询少约 71.5 倍 token，且在会话中保持稳定（这是项目 README 的宣传口径，实际效果因语料而异）。

一次 /graphify . 执行后你会得到三个文件：

graphify-out/
├── graph.html       在任意浏览器打开 —— 点击节点、过滤、搜索
├── GRAPH_REPORT.md  报告要点：核心概念、惊人连接、建议问题
└── graph.json       完整图谱 —— 随时查询，无需重读文件

二、前置条件与安装

2.1 环境要求

前置条件	最低版本	检查命令	安装方式
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 (PowerShell)
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

仓库 pyproject.toml 中声明 requires-python = ">=3.10"，PyPI 包名为 graphifyy（双 y），当前仓库版本为 0.9.52，核心依赖包含 networkx、numpy、rapidfuzz 和 20 余个 tree-sitter-* 语法包。

2.2 两步安装

官方包名提示：PyPI 上的包是 graphifyy（双 y），其他 graphify* 包均与本项目无关。CLI 命令仍叫 graphify。

第 1 步 —— 安装包：

# 推荐（uv 会自动把 graphify 放进 PATH）：
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

两个注意事项（来自文档与主 README）：

• PowerShell：使用 graphify . 而不是 /graphify .——PowerShell 里开头的斜杠是路径分隔符；
• graphify: command not found：优先用 uv tool install 或 pipx install，二者都会自动把 CLI 放进工具 bin 目录（~/.local/bin）；若 shell 找不到，运行 uv tool update-shell 或 pipx ensurepath 后重开终端。

2.3 平台选择表

graphify 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
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

从源码结构看，各平台的差异集中在 graphify/install.py：claude_install 写 CLAUDE.md 段落并注册 PreToolUse 钩子，gemini_install 写 GEMINI.md + BeforeTool 钩子，vscode_install/_cursor_install 写 .cursor/rules/graphify.mdc，Kiro 写 .kiro/skills/ + .kiro/steering/，Antigravity 写 .agents/rules + .agents/workflows——与文档中"每平台安装命令"注释一一对应。

2.4 可选扩展（只装需要的）

扩展	增加能力	安装
pdf	PDF 提取	uv tool install "graphifyy[pdf]"
office	.docx / .xlsx 支持	uv tool install "graphifyy[office]"
google	Google Sheets 渲染	uv tool install "graphifyy[google]"
video	视频/音频转录	uv tool install "graphifyy[video]"
mcp	MCP stdio 服务器	uv tool install "graphifyy[mcp]"
neo4j	Neo4j 支持	uv tool install "graphifyy[neo4j]"
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	uv tool install "graphifyy[anthropic]"
bedrock	AWS Bedrock（走 IAM，无需 API key）	uv tool install "graphifyy[bedrock]"
sql	SQL schema 提取	uv tool install "graphifyy[sql]"
all	以上全部	uv tool install "graphifyy[all]"

这些 extras 与 pyproject.toml 中的 [project.optional-dependencies] 一一对应：例如 mcp = ["mcp>=1,<3", "starlette>=1.3.1,<2"]、video 需要 faster-whisper（Python ≥3.11）+ yt-dlp、bedrock = ["boto3"]。

三、让助手始终优先查图

构建图谱后，在项目里运行一次对应平台的"常驻"安装命令（原文档全表）：

平台	命令
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
Cursor	graphify cursor install
Gemini CLI	graphify gemini install
Amp	graphify amp install
Kiro IDE/CLI	graphify kiro install
Devin CLI	graphify devin install
Google Antigravity	graphify antigravity install

它会写入一个小配置文件，告诉助手：遇到代码库问题时先查知识图谱（优先 graphify query "<问题>" 这样的范围化查询），而不是直接 grep 原始文件。主 README 补充了实现机制的两类：

• 钩子平台（Claude Code、Gemini CLI）：钩子在搜索型工具调用（以及 Claude Code 中逐个 Read/Glob 源文件）之前自动触发，把助手引向查图路径；
• 指令文件平台（Codex、OpenCode、Cursor 等）：通过持久指令文件（AGENTS.md、.cursor/rules/ 等）提供同样的"先查图"引导。

要一次从所有平台移除：graphify uninstall（加 --purge 连 graphify-out/ 一起删除）。

四、报告里有什么

GRAPH_REPORT.md 的五类内容（原文档逐条继承）：

• 核心节点（God nodes）——项目中连接度最高的概念，一切都从它们经过；
• 惊人连接——位于不同文件/模块的实体之间的链接，按"意外程度"排序；
• "为什么"——行内注释（# NOTE:、# WHY:、# HACK:）、docstring 以及文档中的设计动机，作为独立节点被抽取出来，并链接到它们解释的代码；
• 建议问题——图谱独一无二能回答的 4~5 个问题；
• 置信度标签——每条推断关系都标记为 EXTRACTED、INFERRED 或 AMBIGUOUS，随时知道哪些是找到的、哪些是猜的。

报告由 graphify/report.py 的 generate() 生成，God nodes / 惊人连接 / 建议问题分别来自 graphify/analyze.py 的 god_nodes()、surprising_connections()、suggest_questions()；"为什么"节点在抽取阶段由 graphify/extract.py 的 _extract_python_rationale() 等函数从注释与 docstring 中提取。

五、支持的文件类型

类型	扩展名
代码（36+ tree-sitter 语法）	.py .ts .js .jsx .tsx .go .rs .java .c .cpp .rb .cs .kt .scala .php .swift .lua .zig .ps1 .ex .exs .vue .svelte .dart 等
文档	.md .mdx .html .txt .rst .yaml .yml
Office	.docx .xlsx（需 graphifyy[office]）
PDF	.pdf
图片	.png .jpg .webp .gif
视频/音频	.mp4 .mov .mp3 .wav 等（需 graphifyy[video]）
YouTube / URL	任意视频 URL（需 graphifyy[video]）

波斯语文档称"36 种语言经 tree-sitter AST 支持"，主 README 更新为 37 个 tree-sitter 语法（另有 Terraform/HCL、OCaml、Common Lisp、Salesforce Apex 等可选或正则实现的扩展）。代码在本地用 tree-sitter 提取，零 API 调用；其余文件走你的 AI 助手模型 API。 从 graphify/extractors/ 目录可以看到每种语言一个抽取器文件（rust.py、go.py、swift.py、sql.py、terraform.py 等），engine.py 提供通用 tree-sitter 遍历引擎，resolution.py 负责跨文件 import 解析。

六、常用命令

/graphify .                        # 为当前目录构建图谱
/graphify ./docs --update          # 只重新提取变更文件
/graphify . --cluster-only         # 不重新提取，只重跑社区检测
/graphify . --no-viz               # 只要报告 + JSON，不出 HTML
/graphify . --wiki                 # 从图谱构建 Markdown 维基
graphify export callflow-html      # 生成 Mermaid 架构/调用流 HTML

/graphify query "什么把 auth 连到数据库？"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

/graphify add https://arxiv.org/abs/1706.03762   # 抓取一篇论文加入图谱
/graphify add <youtube-url>                       # 转录并加入视频

graphify hook install              # 每次 commit 后自动重建
graphify merge-graphs a.json b.json              # 合并两张图

graphify prs                       # PR 看板：CI 状态、评审状态、图谱影响面
graphify prs 42                    # 深挖 PR #42
graphify prs --triage              # AI 给评审队列排序

七、文件忽略规则

在项目根目录创建 .graphifyignore——语法与 .gitignore 完全一致，包括 ! 取反。.gitignore 会被自动遵守：graphify 会读取各目录下的 .gitignore，若同目录还有 .graphifyignore，两者合并、后者优先。

# .graphifyignore
node_modules/
dist/
*.generated.py

# 只索引 src/，忽略其他一切
*
!src/
!src/**

从源码看，忽略逻辑实现在 graphify/detect.py：_load_graphifyignore() 加载两套规则，ignored_predicate() 生成扫描用的谓词函数，子目录作用域规则与 git 相同（一个忽略文件只影响自己的子树）。

八、团队协作工作流

graphify-out/ 被设计为可以 commit 进 git，让团队所有人从同一张地图开始。

建议加入 .gitignore：

graphify-out/cost.json        # 仅本地
# graphify-out/cache/         # 可选：commit 它提速，或删除它保持仓库小巧

工作流（原文档四步）：

1. 一个人跑 /graphify . 并 commit graphify-out/；
2. 所有人 pull——助手指针会立刻读到图谱；
3. 运行 graphify hook install，让每次 commit 后自动重建；
4. 当文档或论文变化时，跑 /graphify --update。

补充：主 README 指出 manifest.json 现已可移植（键以相对路径存储、加载时重新锚定），commit 它是安全的。主 README 的增强版工作流还给出一个 git alias 让 pull 自动同步图谱：

git config --global alias.gpull '!git pull && graphify update .'

钩子机制在 graphify/hooks.py：install() 写入 post-commit 与 post-checkout 钩子脚本，并把当前解释器路径直接嵌入脚本（所以在 GUI git 客户端和 CI runner 中 ~/.local/bin 不在 PATH 时钩子也能触发）；_register_merge_driver() 注册自定义 merge driver，让 graph.json 在两人同时提交时自动 union 合并、不会出现冲突标记。graphify hook status 可确认钩子是否生效。

九、直接查询图谱与 MCP 服务

9.1 终端查询

# 在终端查询图谱
graphify query "展示认证流程"
graphify query "什么把 DigestAuth 连到 Response？" --graph graphify-out/graph.json

9.2 作为 MCP 服务器

# 把图谱暴露为 MCP 服务器（stdio）
python -m graphify.serve graphify-out/graph.json

# 或以 HTTP 服务供整个团队访问
python -m graphify.serve graphify-out/graph.json --transport http --port 8080
python -m graphify.serve graphify-out/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"

MCP 服务器提供结构化访问，七个工具为：query_graph、get_node、get_neighbors、shortest_path、list_prs、get_pr_impact、triage_prs。这可以在 graphify/serve.py 的 list_tools() 中逐一确认（query_graph 等工具定义位于该文件 L1617 起）。

HTTP 模式的关键参数（默认值来自 serve.py 的 serve_http() 签名与文档）：

参数	默认	作用
--transport {stdio,http}	stdio	传输方式
--host	127.0.0.1	HTTP 绑定地址（对团队暴露时用 0.0.0.0）
--port	8080	HTTP 端口
--api-key	环境变量 GRAPHIFY_API_KEY	要求 Authorization: Bearer <key>（或 X-API-Key）
--path	/mcp	HTTP 挂载路径
--json-response	关	返回纯 JSON 而非 SSE 流
--stateless	关	无每会话状态（负载均衡/CI 部署）
--session-timeout	3600	空闲有状态会话回收秒数（0 禁用）

默认绑定 127.0.0.1 仅回环可用；在共享主机上暴露时必须同时设置 --host 0.0.0.0 和 --api-key。HTTP 服务行为有测试覆盖，见 tests/test_serve_http.py。

十、环境变量（无头提取 / CI 专用）

这些变量只在无头/CI 提取（graphify extract）时需要；通过 IDE 内 /graphify 技能运行时，模型 API 由你的 IDE 会话提供，无需额外 key。

变量	用途	何时需要
ANTHROPIC_API_KEY	Claude (Anthropic) 后端	--backend claude
GEMINI_API_KEY 或 GOOGLE_API_KEY	Google Gemini 后端	--backend gemini
OPENAI_API_KEY	OpenAI 或兼容 API	--backend openai
DEEPSEEK_API_KEY	DeepSeek 后端	--backend deepseek
MOONSHOT_API_KEY	Kimi Code 后端	--backend kimi
OLLAMA_BASE_URL	Ollama 本地推理 URL（默认 http://localhost:11434）	--backend ollama
AZURE_OPENAI_API_KEY	Azure OpenAI 后端	--backend azure（还需 AZURE_OPENAI_ENDPOINT）
GRAPHIFY_MAX_WORKERS	AST 并行线程数	可选（等价 --max-workers）
GRAPHIFY_FORCE	即使新图节点更少也强制重建	可选（等价 --force）
GRAPHIFY_QUERY_LOG_DISABLE	设为 1 关闭本地查询日志	可选

主 README 还列出一批补充变量，按需取用：OPENAI_BASE_URL/OPENAI_MODEL（任意 OpenAI 兼容服务器，如 llama.cpp、vLLM）、OLLAMA_MODEL、GRAPHIFY_OLLAMA_NUM_CTX/GRAPHIFY_OLLAMA_KEEP_ALIVE（控制本地推理显存）、GRAPHIFY_MAX_OUTPUT_TOKENS（稠密语料提高输出上限）、GRAPHIFY_MAX_RETRIES（429 重试次数，默认 6）、GRAPHIFY_MAX_RETRY_DEPTH（截断 chunk 的二分重提取深度，默认 3）、GRAPHIFY_MAX_GRAPH_BYTES（覆盖 512 MiB 的 graph.json 上限）等。

后端自动检测顺序：不显式传 --backend 时，graphify extract 按设置好的 key 自动选后端。从 graphify/llm.py 的 detect_backend()（L3106 起）docstring 与实现看，优先级为 gemini → kimi → claude → openai → deepseek → azure → bedrock → ollama，且 Ollama 故意排在最后，避免环境里顺手设的 OLLAMA_BASE_URL 悄悄遮蔽已付费的后端。

十一、隐私边界

• 代码文件——本地 tree-sitter 处理，什么都不离开你的机器。纯代码语料不需要任何 API key，graphify extract 可以完全离线跑；混合仓库可用 --code-only 只索引代码、跳过需要 LLM 的文档/PDF/图片；
• 视频/音频——本地用 faster-whisper 转录，什么都不离开机器（转录实现在 graphify/transcribe.py）；
• 文档、PDF、图片——发往你的 AI 助手模型做语义提取；
• 无遥测、无使用追踪、无分析统计；
• 查询日志：每次 query/path/explain 与 MCP query_graph 会写入 ~/.cache/graphify-queries.log（JSON Lines：时间戳、问题、语料、返回节点数、耗时），默认不保存完整子图响应；GRAPHIFY_QUERY_LOG_DISABLE=1 可彻底关闭。日志逻辑见 graphify/querylog.py。

十二、完整命令参考

/graphify                          # 对当前目录运行
/graphify ./raw                    # 对指定目录运行
/graphify ./raw --mode deep        # 更激进的关系提取
/graphify ./raw --update           # 只重新提取变更文件
/graphify ./raw --directed         # 保留边方向
/graphify ./raw --cluster-only     # 在现有图上重跑社区检测
/graphify ./raw --no-viz           # 不出 HTML
/graphify ./raw --obsidian         # 生成 Obsidian vault
/graphify ./raw --wiki            # 构建 agent 可爬的 Markdown 维基
/graphify ./raw --svg              # 导出 graph.svg
/graphify ./raw --graphml          # 导出给 Gephi / yEd
/graphify ./raw --neo4j            # 生成给 Neo4j 的 cypher.txt
/graphify ./raw --watch            # 文件变化自动同步
/graphify ./raw --mcp              # 启动 MCP stdio 服务器

/graphify add https://arxiv.org/abs/1706.03762
/graphify add <video-url>

/graphify query "什么把 attention 连到 optimizer？"
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"

graphify uninstall                 # 一次从所有平台移除
graphify uninstall --purge         # 连同 graphify-out/ 一起删除

graphify hook install              # post-commit + post-checkout 钩子
graphify hook uninstall
graphify hook status

graphify claude install            # CLAUDE.md + PreToolUse 钩子（Claude Code）
graphify codex install             # AGENTS.md + PreToolUse 钩子（Codex）
graphify cursor install            # .cursor/rules/graphify.mdc（Cursor）
graphify gemini install            # GEMINI.md + BeforeTool 钩子（Gemini CLI）
graphify amp install               # 技能文件（Amp）
graphify kiro install              # .kiro/skills/ + .kiro/steering/（Kiro）
graphify devin install             # 技能文件 + .windsurf/rules/（Devin CLI）
graphify antigravity install       # .agents/rules + .agents/workflows（Google Antigravity）

graphify extract ./docs                        # CI 无头 LLM 提取（无需 IDE）
graphify extract ./docs --backend gemini       # 显式后端
graphify extract ./docs --backend ollama       # 本地 Ollama，无需 API key
graphify extract ./docs --backend bedrock      # AWS Bedrock，走 IAM
graphify extract --postgres "postgresql://user:pass@host/db"   # 直接内省活 PostgreSQL schema

graphify prs                              # PR 看板
graphify prs 42                           # 深挖 PR #42
graphify prs --triage                     # AI 排序（按已配置后端）
graphify prs --conflicts                  # 共享图谱社区的 PR（合并顺序风险）

graphify export callflow-html             # 架构/调用流 HTML
graphify merge-graphs a.json b.json --out merged.json
graphify --version

主 README 的参考还包括：graphify extract ./raw --code-only（纯本地 AST，无 API key）、--token-budget（本地小模型用更小的语义 chunk）、--max-concurrency（本地推理时减少并行 LLM 调用）、cluster-only --resolution 1.5（更多更小的社区）、global add/remove/list（跨项目全局图）、watch/update/check-update、label（用已配置后端重命名社区）等。

十三、排障手册

pip install graphifyy 后 graphify: command not found pip 把脚本装进用户 bin 目录，它可能不在 PATH 里：

• macOS：把 ~/Library/Python/3.x/bin 加入 ~/.zshrc 的 PATH；
• Linux：把 ~/.local/bin 加入 ~/.bashrc 的 PATH；
• 或者直接用 uv tool install graphifyy / pipx install graphifyy。

PowerShell 中 /graphify . 报 "path not recognized" PowerShell 把开头的 / 当路径分隔符。Windows 上用 graphify .（不带斜杠）。

--update 或重建后图谱节点变少 若重构删除了文件，旧节点会残留。传 --force（或 GRAPHIFY_FORCE=1）强制覆盖：

graphify extract . --force

文档/PDF 提取返回空节点/边 文档、PDF、图片需要 LLM 调用。确认 API key 已设置且后端正确：

ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claude

补充两条主 README 的高频问题：

• uvx graphify … 报找不到包：PyPI 包名是 graphifyy，graphify 只是它提供的命令。uv tool run 把第一个词当包名，所以要写 uvx --from graphifyy graphify install；
• Claude Code 提示缓存每次提取后失效：把 graph.json 和 graphify-out/ 加进 .claudeignore。

十四、开发环境搭建（贡献者向）

项目使用 uv 作为开发工作流，一次性安装后：

git clone https://gitcode.com/GitHub_Trending/graph/graphify.git
cd graphify
git checkout v8                        # 活跃开发分支

uv sync --all-extras

运行测试：

uv run pytest tests/ -q                # 全量
uv run pytest tests/test_extract.py -q # 单个模块

Git 工作流：活跃开发在 v8 分支；commit 风格为 fix: <描述> / feat: <描述> / docs: <描述>；开 PR 前先跑 uv run pytest tests/ -q 并确认通过。

最有价值的贡献类型是真实语料样本（worked examples）：在一个真实 corpus 上跑 /graphify，把输出存到 worked/{slug}/，写一份诚实的 review.md 说明图谱哪里对了哪里错了，再开 PR。仓库里现成的示例可参考 worked/httpx/、worked/mixed-corpus/。提取类 bug 请附输入文件、缓存条目（graphify-out/cache/）以及具体错漏。

十五、延伸阅读

• docs/how-it-works.md —— 提取管线、社区检测、置信度评分、基准测试；
• ARCHITECTURE.md —— 模块划分、如何添加新语言；
• docs/docker-mcp-sqlite.md —— Docker MCP Toolkit + SQLite 可选集成；
• 波斯语版原文见 docs/translations/README.fa-IR.md，全部 30+ 种语言的 README 翻译在 docs/translations/ 目录下。