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

graphify 是一个面向 AI 编程助手（Claude Code、Codex、Cursor、Gemini CLI 等）的 /graphify 技能：它本地解析代码的 AST、转录音视频、对文档做语义抽取，最终把一切合并成一张带置信度标注的知识图谱，让你用 query / path / explain 命令提问，而不是逐文件 grep。读完本篇，你可以完成 graphify 的安装注册、理解其三通道抽取管线与置信度标签体系，并掌握增量更新与隐私边界的具体实现细节。

一、graphify 是什么

按仓库官方说明（README.md 与荷兰语文档 docs/translations/README.nl-NL.md），graphify 的定位是"AI 代码助手的技能"：在 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Hermes、Kiro、Google Antigravity 等助手中输入 /graphify，它会读取你的文件、构建知识图谱，并返回你原本不知道存在的结构信息——更快地理解代码库，并找到架构决策背后的"为什么"。

它的核心特性有四点，且都与"不引入向量数据库"的设计直接相关：

• 完全多模态：代码、PDF、Markdown、截图、图表、白板照片、其他语言图片以及音视频文件都可以加入，graphify 从中抽取概念与关系并连入同一张图；
• 确定性代码解析：代码走 tree-sitter AST，本地运行、不经过 LLM，官方文档声称支持 25 种编程语言（见下文源码佐证）；
• 每条边都可解释：每条关系都标注 EXTRACTED、INFERRED（带置信度分数）或 AMBIGUOUS；
• 不是向量索引：没有嵌入、没有向量库，是一张真正可遍历的图——可以提问、追踪两个概念之间的路径、解释某个概念。

文档中还引用了 Andrej Karpathy 维护 /raw 文件夹存放论文、推文、截图与笔记的场景，称 graphify 是对该问题的回答：相比直接读取原始文件，每次查询节省 71.5 倍 token，且图谱在会话之间持久化。

二、安装：注意 PyPI 包名是 graphifyy

前提条件：Python 3.10+（pyproject.toml 中 requires-python = ">=3.10"），以及任一受支持的 AI 助手环境。

uv tool install graphifyy && graphify install
# 或使用 pipx
pipx install graphifyy && graphify install
# 或使用 pip
pip install graphifyy && graphify install

官方包名提醒：PyPI 上的包名是 graphifyy（双 y），命令名则是 graphify。pyproject.toml 中 name = "graphifyy"，[project.scripts] 定义了 graphify = "graphify.__main__:main" 入口。荷兰语文档中特别注明"官方唯一仓库"的警示，与英文 README 保持一致：PyPI 上其他 graphify* 包均非官方。

graphify install 的作用是把技能注册到你的 AI 助手。从 graphify/main.py 的导入结构可以看到，安装子系统被拆到 graphify/install.py，支持按平台分发（Claude Code、Cursor、Codex、Kilo、Kiro、Antigravity 等各有独立的安装/卸载函数），并按 pyproject.toml 的 package-data 配置把 skill-*.md 技能正文与 skills/*/references/*.md 渐进式参考文件随包分发。

首次运行后，你会得到四个输出文件：

graphify-out/
├── graph.html       交互式图谱——可用任意浏览器打开
├── GRAPH_REPORT.md  神节点、意外连接、建议提问
├── graph.json       持久化图谱——数周后仍可查询
└── cache/           SHA256 缓存——重复运行只处理变更过的文件

三、工作原理：三个 Pass 的抽取管线

荷兰语文档给出的核心流程是："graphify 分三次 pass 工作。首先是确定性的 AST pass，不经过 LLM 地从代码文件抽取结构；接着用 faster-whisper 在本地转录音视频；最后 Claude 子代理并行处理文档、论文、图片与转录文本。结果合并进一张 NetworkX 图，用 Leiden 算法聚类，导出为交互式 HTML、可查询的 JSON 与审计报告。"

这一点在 docs/how-it-works.md 中有完整展开，并可与源码相互印证：

Pass 1 —— 代码结构（免费、无 API 调用）。tree-sitter 解析代码文件，抽取类、函数、导入、调用图与行内注释，全程本地运行、无 LLM 参与。SQL 文件有专门处理：表、视图、外键与 JOIN 关系被确定性抽取。从 pyproject.toml 的依赖清单可以看到，默认包内内置了 20 余种 tree-sitter 语法（Python、JS/TS、Go、Rust、Java、C/C++、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、Elixir、ObjC、Julia、Verilog、Fortran、Bash、JSON 等），另有 pascal、ocaml、commonlisp、terraform、dm 等可选 extras 提供额外语言的 AST 支持——这与文档"25 种语言"的说法量级吻合，而 graphify/extractors/ 目录下的 go.py、rust.py、csharp.py、sql.py、terraform.py 等文件正是各语言抽取器的实现。文档同时明确：纯代码语料会完全跳过 Pass 3，语义抽取只留给文档、论文、图片与转录文本。

Pass 2 —— 音视频（本地、无 API 调用）。从 graphify/transcribe.py 可以看到实际调用：WhisperModel(model_name, device="cpu", compute_type="int8")——即 faster-whisper 在 CPU 上以 int8 精度运行，完全不出机器。按 docs/how-it-works.md，转录提示词会用当前代码图中连接度最高的"神节点"做种子，让转录聚焦你的领域；转录结果有缓存，重跑时跳过已处理文件。该功能对应 graphifyy[video] 可选依赖（pyproject.toml：faster-whisper + yt-dlp）。

Pass 3 —— 文档、论文、图片（LLM 子代理，消耗 token）。Claude（或配置的后端模型）并行处理 Markdown、PDF、图片与转录文本，每个子代理读取一批文件并输出 JSON 片段：节点、边与组关系，最终片段合并为单张图。

聚类：社区检测使用 Leiden 算法。从 graphify/cluster.py 的实现看，它优先直接调用 graspologic_native.leiden()，再回退到 graspologic.partition.leiden，最后回退到 networkx 的 Louvain（模块 docstring 明确写了这一降级链）；resolution 参数控制社区粒度，大于 1.0 得到更多更小的社区。值得注意的是 docs/how-it-works.md 强调"无需嵌入"：LLM 抽取的 semantically_similar_to 语义相似边已经直接存在于图中，图结构本身就是相似度信号。

并行与缓存：代码文件用 ProcessPoolExecutor 并行抽取（绕过 GIL 的真多进程）；每个被抽取的文件按内容做 SHA256 指纹。从 graphify/cache.py 的注释可以看到缓存文件按 graphify-out/cache/{kind}/{hash}.json 组织，hash 即文件内容的 SHA256——这就是 cache/ 目录让重复运行只处理变更文件的底层机制。

四、置信度标签：EXTRACTED / INFERRED / AMBIGUOUS

文档声明"每条关系都会标注为 EXTRACTED、INFERRED（带置信度分数）或 AMBIGUOUS"。docs/how-it-works.md 给出了完整标签体系与离散评分标尺：

标签	含义
EXTRACTED	直接在源码中发现（如函数调用、import），置信度恒为 1.0
INFERRED	模型的合理推断，带 confidence_score（0.0–1.0）
AMBIGUOUS	不确定——在报告中标出供人工复核

INFERRED 边采用五档离散标尺：0.95（近乎确定：显式跨文件引用、唯一合理目标）、0.85（证据充分：命名与上下文吻合）、0.75（合理：有上下文但非显式）、0.65（较弱：仅命名相似）、0.55（推测性）。在 graphify/analyze.py 中可以看到这些标签直接参与"意外连接"的排序打分：分析器读取每条边的 confidence 字段并据此赋分，跨语言的 INFERRED calls/uses 边还会被结构性加分抑制，避免噪声关系混入高亮结果。

五、日常使用：核心命令一览

荷兰语文档给出的六个常用命令，配合仓库 README.md 的"Common commands"一节，构成日常使用面：

/graphify .                                          # 为当前目录构建图谱
/graphify ./raw --update                             # 增量：只重新抽取变更文件
/graphify query "what connects Attention to the optimizer?"   # 自然语言查询
/graphify path "DigestAuth" "Response"               # 追踪两节点间最短路径
graphify hook install                                # git post-commit/post-checkout 自动重建
graphify update ./src                                # git pull 之后手动同步图谱

几个关键机制值得注意（均来自 README.md 与 docs/how-it-works.md）：

• --update 增量机制依赖第三节的 SHA256 缓存：未变更文件直接跳过；
• graphify hook install 安装 post-commit 与 post-checkout 钩子，提交/切分支后自动重建（纯 AST，无 API 成本），并配置 merge driver 让 graph.json 在多开发者并发提交时自动做并集合并、不出现冲突标记；
• 查询是读图而非读文件：graphify query 返回限定范围的子图，graphify path 输出逐跳路径，graphify explain 解释单个节点——这正是"节省 token"的来源；
• 英文 README 还提供 --cluster-only（跳过重抽取、只重聚类）、--no-viz（>5000 节点时跳过 HTML 直接用 JSON）、--mode deep（更激进的语义抽取）等开关，以及把图谱以 MCP stdio/HTTP 服务器形式暴露给整个团队的做法（python -m graphify.serve）。

六、你能得到什么：报告内容与 token 基准

运行后 GRAPH_REPORT.md 包含四类内容（荷兰语文档与 README.md 的 "What's in the report" 一致）：

• 神节点（God nodes）——连接度最高的概念，一切流程都经过它们。报告生成逻辑在 graphify/report.py 的 generate() 中，god_node_list 是核心输入；
• 意外连接（Surprising connections）——不同文件/模块之间的边，按意外程度排序（即第四节的打分体系）；
• 建议提问——图谱独特地有能力回答的 4–5 个问题，graphify/analyze.py 显示它们基于 AMBIGUOUS 边、桥节点、富 INFERRED 边的神节点与孤立节点自动生成；
• 架构"为什么"——# NOTE: / # WHY: 注释、docstring 与设计 rationale 被抽成独立节点并链接到所解释的代码。

Token 基准：文档宣称的"71.5 倍节省"有明确的测量前提。docs/how-it-works.md 给出了完整表格：在混合语料（Karpathy 仓库 + 5 篇论文 + 4 张图片，共 52 个文件）上，每次查询相比直接读原始文件节省 71.5 倍 token；4 个文件的语料为 5.4 倍；6 个文件的小型语料约 1 倍——节省随语料规模增长。仓库的 worked/ 目录保存了各次运行的原始输入与真实输出（如 worked/httpx/GRAPH_REPORT.md、worked/httpx/graph.json），你可以自行复跑验证。

七、隐私边界：哪些数据留在本地

荷兰语文档的 Privacy 一节只有两句，但边界清晰，且可与 README.md 的 "Privacy" 一节互相补充：

• 代码文件——本地经 tree-sitter 处理，"Nothing leaves your machine"。纯代码语料完全离线，甚至不需要任何 API key（graphify extract 加 --code-only 可只索引代码）；
• 视频/音频——本地 faster-whisper 转录（对应 graphify/transcribe.py 的 CPU int8 实现），不出机器；
• 文档、PDF、图片——走 AI 助手的模型 API 做语义抽取（技能模式下由 IDE 会话的模型提供；无头模式 graphify extract 需要配置相应后端的 key）；
• 无遥测、无使用追踪、无分析统计。

也就是说，graphify 的隐私设计原则是：结构抽取全部本地确定化，只有语义抽取（且仅针对非代码文件）才可能触达外部模型，并且后端选择完全由你配置的环境变量决定。

八、延伸：基于 graphify 构建的 Penpax

荷兰语文档末尾提到 Penpax 是构建在 graphify 之上的企业层（enterprise 层），主打"免费试用即将开放"。这与英文 README 的 "graphify Enterprise" 一节对应：始终在线（always-on）地把同一套图方法应用到会议、文件、文档与代码之上。若你只在本地开发场景使用，开源的 graphifyy 包本身已经覆盖了本文全部功能。

小结

• 安装：uv tool install graphifyy && graphify install（包名双 y，命令单 y）；
• 三条抽取通道：tree-sitter AST（本地、确定性）→ faster-whisper 转录（本地 int8）→ LLM 子代理（仅文档/媒体），合并为 NetworkX 图 + Leiden 聚类；
• 每条边都有 EXTRACTED/INFERRED/AMBIGUOUS 标签，INFERRED 边带 0.55–0.95 五档置信度；
• SHA256 缓存（graphify-out/cache/）支撑 --update 增量重建，git 钩子支撑团队级自动同步；
• 查询（query/path/explain）读图不读文件，在 52 文件混合语料上实测约 71.5 倍 token 节省；
• 代码与音视频处理完全本地，无遥测；只有文档类语义抽取依赖你所配置的后端。