Graphify 知识图谱实战：用 /graphify 技能把代码、文档与 PDF 变成可查询的图

本文围绕 graphify 项目的主 README 翻译版（docs/translations/README.id-ID.md）展开，完整讲解 graphify 的核心能力：在 Claude Code、Codex、Cursor、Gemini CLI 等 AI 编码助手中输入 /graphify，即可把代码库连同文档、SQL schema、配置和 PDF 构建为一个可查询的知识图谱。读完后你将掌握安装配置、常用命令、graphify-out/ 产物结构，以及底层"确定性 AST + 本地转写 + LLM 语义提取"三段式流水线的实现原理。

graphify 是什么

graphify 是一个面向 AI 编码助手的技能（skill）：在 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、Factory Droid、Trae、Kiro、Google Antigravity 等平台中输入 /graphify，它会读取你的文件、构建知识图谱，并返回你原本不知道的结构化信息——更快理解代码库，并找到架构决策背后的"为什么"。

它的核心设计取向有三个（见 README.md）：

• 代码映射完全本地、零 LLM：代码通过 tree-sitter AST 解析，确定性、无模型调用、数据不出机器；
• 每条边都有解释：每条关系都被标记为 EXTRACTED（源码中明确存在）或 INFERRED（由 graphify 推理解析得出），让你分清"读到的"和"猜到的"；
• 不是向量索引：没有 embeddings、没有向量库，而是一张可以真正遍历的图——你可以提问、追踪两个概念之间的路径、解释某个概念。

它完全多模态：可以加入代码、PDF、markdown、截图、图表、白板照片、其他语言的图片，乃至音视频文件——graphify 从中抽取概念和关系并连入同一张图。视频在本地用 Whisper 转写。当前仓库的主 README 文件处理表中列出了 37 个 tree-sitter 文法（README.md "What files it handles" 一节），比翻译版文档中的"25 种语言"更新，两者差异来自版本演进，以当前仓库为准。

文档中提到的一个典型场景：维护一个存放论文、截图和笔记的 /raw 文件夹后如何低成本地反复提问。仓库内的 worked/karpathy-repos/ 目录就是这类语料的真实运行样本（含 graph.json、GRAPH_REPORT.md 和 review.md），可以直接对照验证。

产物结构：graphify-out/

执行 /graphify . 后，工作区会生成如下产物：

graphify-out/
├── graph.html       交互式图谱 —— 可在任意浏览器中打开
├── GRAPH_REPORT.md  报告：God nodes、意外连接、建议问题
├── graph.json       持久化图谱 —— 数周后仍可直接查询
└── cache/           SHA256 缓存 —— 重复运行只处理有变化的文件

• graph.html 是力导向布局的交互式可视化，可点击节点、过滤、搜索；
• graph.json 使用 NetworkX node-link 格式，后续所有 query/path/explain 都直接查它，无需重读源文件；
• cache/ 按内容指纹缓存每个已提取文件，增量重建时跳过未变化文件（原理见 docs/how-it-works.md 的 "SHA256 cache" 一节）。

交互式图谱的真实效果可以参考下图（FastAPI 代码库经 graphify 映射后的 graph.html，节点颜色为检测出的社区）：

工作原理：三段式流水线

翻译版 README（docs/translations/README.id-ID.md "Cara Kerja" 一节）概括了三个阶段，与 docs/how-it-works.md "The three passes" 的描述一一对应：

阶段一：确定性 AST 提取（免费、无 API 调用）

tree-sitter 解析代码文件，抽取类、函数、导入、调用图和行内注释，全程本地运行、不涉及 LLM。SQL 文件获得特殊处理：表、视图、外键和 JOIN 关系被确定性抽取。纯代码语料会完全跳过后续语义阶段。

源码层面的证据：

• 入口是 graphify/extract.py 中的 extract()（约 L5859），其 docstring 明确说明是两遍处理：第一遍逐文件结构提取（类、函数、导入），第二遍跨文件导入解析，把文件级 import 转成类级 INFERRED 边（如 DigestAuth --uses--> Response）；
• 文件到提取器的路由在 _get_extractor()（约 L5584-L5627）：先按文件名特判（.blade.php、MCP 配置、包清单 pyproject.toml/go.mod 等），再按扩展名查 _DISPATCH 表，并对歧义后缀做嗅探——例如 .h 先判断是 Objective-C 头文件（@interface）还是 C++ 类头，.m 只有在文件确实像 Objective-C 源码时才走 ObjC 提取器，否则宁可返回 None 也不误解析 MATLAB；
• 并行策略：未缓存文件数达到阈值 _PARALLEL_THRESHOLD = 20（extract.py 约 L5856）时启用 ProcessPoolExecutor 多进程绕开 GIL，worker 数默认取 CPU 核数或 GRAPHIFY_MAX_WORKERS 环境变量。

阶段二：音视频本地转写（免费、无 API 调用）

视频和音频文件由 faster-whisper 在本地转写，转写提示词会用你代码图中当前的 God nodes（连接度最高的概念）做领域预热；转写结果同样进缓存，重复运行跳过已处理文件。此能力需要 video 可选依赖：uv tool install "graphifyy[video]"。

阶段三：文档、论文、图片的语义提取（消耗 token）

LLM 以并行子代理（subagent）方式处理 markdown、PDF、图片和转写文本，每个子代理输出一段 JSON 片段（节点、边、组关系），最终合并为一张图。当前仓库的 graphify/llm.py 支持 gemini、kimi、claude、openai、deepseek、ollama、bedrock、claude-cli、azure 等后端，由 --backend 选择；在 IDE 中通过 /graphify 技能运行时直接使用会话自带的模型，无需额外配置 key。

合并、聚类与导出

三个阶段的碎片合并到 NetworkX 图中后，用 Leiden 算法做社区检测，再导出为交互式 HTML、可查询 JSON 和审计报告。从 graphify/cluster.py 的模块 docstring 可以直接确认："Use Leiden (graspologic) if available, falls back to Louvain (networkx)"——即优先 Leiden，不可用时回退 Louvain，并拆分过大社区、返回内聚度分数。语义相似边（semantically_similar_to）本身就在图里，直接参与社区形状，因此整个过程不需要任何 embedding 步骤或向量数据库。

边的置信度标签

每条关系都带有三类标签之一（docs/translations/README.id-ID.md 与 docs/how-it-works.md 一致）：

标签	含义
EXTRACTED	直接来自源码（如函数调用、import 语句），置信度恒为 1.0
INFERRED	合理推理得出，附带 confidence_score（0.0–1.0）
AMBIGUOUS	不确定，在报告中列出供人工复核

INFERRED 边采用离散评分准则（docs/how-it-works.md "Confidence tagging"）：

• 0.95 — 几乎确定（显式跨文件引用，目标唯一）
• 0.85 — 强证据（命名与上下文吻合）
• 0.75 — 合理（上下文相关但非显式）
• 0.65 — 较弱（仅命名相似）
• 0.55 — 推测性

安装

前提条件：Python 3.10+，以及一个支持的 AI 助手（Claude Code、Codex、OpenCode、Cursor 等）。

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

官方包名提醒：PyPI 上的包名是 graphifyy（双 y），CLI 命令仍叫 graphify；其他 graphify* 包与本项目无关。若用 uvx/uv tool run 临时运行，必须写 uvx --from graphifyy graphify install，因为 uv tool run 把第一个词当作包名解析（详见 README.md "Troubleshooting"）。

graphify install 把技能注册到 AI 助手；项目级安装可加 --project（如 graphify install --project --platform codex），会写入当前目录的 .claude/skills/graphify/SKILL.md 或 .agents/skills/graphify/SKILL.md 等位置。各平台的完整安装命令表见 README.md "Install" 一节的 20+ 平台对照表。

常用命令

翻译版 README "Penggunaan"（用法）一节给出的核心命令：

/graphify .
/graphify ./raw --update
/graphify query "apa yang menghubungkan Attention dengan optimizer?"
/graphify path "DigestAuth" "Response"
graphify hook install
graphify update ./src

中文释义与补充：

• /graphify . — 为当前目录构建图谱；
• /graphify ./raw --update — 增量模式，仅重新提取有变化的文件（SHA256 缓存保证未变文件被跳过）；
• /graphify query "..." — 用自然语言问题查询图谱，返回一个受限子图，而不是重读文件。终端下等价于 graphify query "..."；
• /graphify path A B — 追踪两个实体之间的最短路径。下图展示了 path 查询的真实交互效果（在 FastAPI 语料上查询 FastAPI 到 ModelField 的路径，逐跳高亮）：

• graphify hook install — 安装 git 钩子，git commit 与切换分支时自动在后台重建（纯 AST，无 API 成本），并配置 graph.json 的 union merge driver 避免合并冲突；
• graphify update ./src — git pull 之后手动同步图谱。推荐工作流（README.md "Team setup"）：clone 后 graphify hook install 一次，之后 commit/切分支全自动，pull 后手动 graphify update .，甚至可用 git config --global alias.gpull '!git pull && graphify update .' 合并成一条命令。

完整命令参考（含 --mode deep、--cluster-only --resolution 1.5、--obsidian、--neo4j-push、graphify global、graphify prs 等）见 README.md "Full command reference"。

你会得到什么

God nodes — 连接度最高的概念，代表"一切都经过它"的核心抽象；意外连接（Surprising connections） — 按"意外程度"排序的跨文件/跨模块边；建议问题 — 图谱最有资格回答的 4–5 个问题；"为什么" — 行内注释（# NOTE: / # WHY: / # HACK:）、docstring 与设计理由被抽取为独立节点并链接到所解释的代码；Token 基准 — 在混合语料上比直接读原始文件少 71.5 倍的每次查询 token。

token 节省的具体数据来自 docs/how-it-works.md "Token benchmark"，且与翻译版 README 中的 71.5x 数字一致：

语料	文件数	压缩比
Karpathy 仓库 + 5 篇论文 + 4 张图片	52	71.5x
graphify 源码 + Transformer 论文	4	5.4x
httpx（合成 Python 库）	6	~1x

规律很明确：节省随语料规模增长。6 个文件本身就能塞进上下文窗口，小语料的价值在结构清晰度而非压缩；52 个文件时节省显著。每个 worked/ 目录都保留了原始输入和真实输出，可复跑验证，例如 worked/httpx/GRAPH_REPORT.md 展示了 144 节点/330 边/6 社区的 httpx 样例：Client 以 26 条边成为 God node，报告自动给出 53% EXTRACTED / 47% INFERRED 的置信度分布、跨社区桥接节点（betweenness centrality 最高的 Client、Response）以及"这些 INFERRED 边是否正确"这类待人工验证的问题。

隐私与本地优先

翻译版 README "Privasi"（隐私）一节与当前 README.md "Privacy" 的要点一致：

• 代码文件 — 本地 tree-sitter 处理，数据不出机器；纯代码语料完全离线（graphify extract 可加 --code-only，不需要任何 API key）；
• 音视频 — 本地 faster-whisper 转写，数据不出机器；
• 文档、PDF、图片 — 经由 AI 助手的模型做语义提取（IDE 内使用当前会话模型；headless graphify extract 需配置对应后端 key，本地可用 --backend ollama）；
• 无遥测、无用量追踪、无分析统计。

延伸阅读与证据入口

• docs/how-it-works.md — 三遍流水线、Leiden 社区检测、置信度评分准则、token 基准与 SHA256 缓存的完整说明；
• ARCHITECTURE.md — 模块职责划分与如何新增一门语言；
• worked/ — 每个子目录含 raw/ 原始输入、graph.json、GRAPH_REPORT.md 和诚实的 review.md 复盘，可直接复跑核对；
• tests/ — 覆盖提取器、跨语言调用解析、Leiden 聚类与增量更新的完整测试套件，可查证本文所述每条行为的实现事实；
• docs/translations/README.zh-CN.md 等其他 25+ 语言翻译版，与本印尼语版内容同源。