Graphify 实战指南：用 /graphify Skill 把代码、文档与多模态文件变成可查询的知识图谱

本篇以仓库中的波兰语版 README（docs/translations/README.pl-PL.md）为主线，完整继承其"三遍流水线、置信度标签、安装与使用命令、产出物与隐私模型"的核心脉络，并结合 docs/how-it-works.md 与源码实现逐点印证。读完你能掌握：如何用一条 /graphify . 命令为任意文件夹构建知识图谱、如何安装并注册到 AI 编码助手、如何用 query/path 替代全文 grep 提问，以及图谱的缓存、社区检测与置信度体系是如何在本地确定性完成的。

一、graphify 是什么：一条命令构建"可查询的知识图谱"

graphify 的定位是 AI 编码助手的技能（skill）：在 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Hermes、Kiro 或 Google Antigravity 中输入 /graphify，它会读取目标文件夹内的文件，构建一张知识图谱，并返回结构信息——包括你此前不知道存在的模块关系。核心卖点有三：

• 代码图谱免费且完全本地：代码经 tree-sitter AST 确定性解析，不经过 LLM，文件不离开本机；只有文档、PDF、图片、音视频走语义通道；
• 每条边都可解释：每条关系标注 EXTRACTED（源码中显式存在）或 INFERRED（由 graphify 推断，附带置信分），你能区分"读到的"与"猜到的"；
• 不是向量索引：没有 embedding、没有向量库，而是一张可遍历的真实图——可以提问、追踪两个概念之间的路径、解释单个概念。

它还是完全多模态的：代码、PDF、Markdown、截图、图表、白板照片、其他语言图片、音视频都可以纳入同一张图。视频/音频在本地用 faster-whisper 转写，代码则通过 tree-sitter AST 覆盖多种语言（波兰语版 README 写作于 v4 分支时期，称"25 种语言"；当前仓库 README.md 的文件类型表显示已扩展到 37 个 tree-sitter 语法族，覆盖 .py、.ts、.go、.rs、.java、.cpp、.cs、.swift、.sql 等数十种扩展名，另有 Apex、Terraform/HCL、OCaml、Common Lisp 等专项解析器）。

典型使用场景来自 Karpathy 的工作流：维护一个 /raw 文件夹堆放文章、推文、截图和笔记。graphify 针对的就是这类问题——在混合语料上，每次查询比直接读原始文件少 71.5 倍 token，且图谱跨会话持久。这个 71.5x 数据并非孤立声明，docs/how-it-works.md 给出了完整的基准表：

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

token 缩减随语料规模放大：6 个文件本身就能塞进上下文窗口，图谱的价值在于结构清晰而非压缩；52 个文件时节省才显著累积。仓库中的 worked/ 目录保留了原始输入与真实输出（GRAPH_REPORT.md、graph.json），例如 worked/httpx/graph.json 与 worked/karpathy-repos/GRAPH_REPORT.md，可复跑验证。

最简调用形式（对应波兰语版 README 的开场示例）：

/graphify .                        # 对任意文件夹生效

二、三遍流水线（Three Passes）：从文件到 NetworkX 图

波兰语版 README 的"Jak to działa（如何工作）"一节概括为：先由确定性 AST 遍在无 LLM 参与下提取代码结构，再由 faster-whisper 在本地转写音视频，最后由并行子代理处理文档、文章、图像与转写稿；结果合并进 NetworkX 图，用 Leiden 算法分组，导出交互式 HTML、JSON 与审计报告。 docs/how-it-works.md 对三遍做了逐遍展开，源码中也能一一对应：

Pass 1 — 代码结构（免费，无 API 调用）

tree-sitter 解析代码文件，提取类、函数、import 图、调用图与行内注释，全程本地、无 LLM。SQL 文件有特殊处理：表、视图、外键与 JOIN 关系被确定性提取。值得注意的是：代码文件不会进入 LLM 语义通道——若整个语料只有代码文件，Pass 3 会被整体跳过，纯代码仓库可以完全离线建图（graphify extract 不需要任何 API key）。

Pass 2 — 视频与音频（本地，无 API 调用）

视频和音频用 faster-whisper 转写。为了让转写聚焦你的领域，转写提示词会预先注入你当前代码图中度数最高的 top god nodes；转写结果同样进缓存，重跑时跳过已处理文件。此能力通过可选依赖启用，pyproject.toml 中 video extra 即 faster-whisper + yt-dlp（且要求 Python ≥ 3.11）。

Pass 3 — 文档、论文、图像（子代理并行，消耗 token）

Claude 子代理并行处理 Markdown、PDF、图像与转写稿。每个子代理读取一批文件并输出 JSON 片段（节点、边、组关系），片段再合并为单图。在 Pass 3 之前，可选转换器会把 Office 文件（.docx/.xlsx）与 Google Workspace 快捷方式（.gdoc/.gsheet/.gslides）转成 Markdown 旁路文件，落在 graphify-out/converted/ 下。

社区检测与合并：Leiden 算法

合并后的图用 Leiden 算法做社区检测——按边密度把节点聚成子系统社区，"节点间连接密集者落入同一社区"。不需要 embedding：语义相似边（semantically_similar_to）已经在图里，直接参与社区形状，图结构本身就是相似性信号。实现上，graphify/cluster.py 优先走 graspologic_native.leiden() 原生路径并绕过进度条输出（见 graphify/cluster.py#L22 附近），失败时回退到 graspologic.partition.leiden；对应 leiden extra 且仅限 Python < 3.13（pyproject.toml 第 65 行 graspologic; python_version < '3.13'）。

三、置信度标签：每条边的"证据等级"

波兰语版 README 明确指出：每条关系被标注为 EXTRACTED、INFERRED（附置信分）或 AMBIGUOUS。 这不是口号，而是被硬性校验的契约——graphify/validate.py 定义了白名单：

VALID_FILE_TYPES = {"code", "document", "paper", "image", "rationale", "concept"}
VALID_CONFIDENCE = {"EXTRACTED", "INFERRED", "AMBIGUOUS"}

docs/how-it-works.md 给出了三级语义与 INFERRED 边的离散评分细则：

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

INFERRED 的置信分采用离散阶梯：0.95（近乎确定：显式跨文件引用且目标唯一）、0.85（证据较强：命名与上下文吻合）、0.75（合理：有上下文支撑但非显式）、0.65（弱：仅命名相似）、0.55（推测）。

输出格式方面，graph.json 采用 NetworkX 的 node-link 格式。每个节点含 id、label、file_type（code/document/paper/image/rationale）、source_file；每条边含 source、target、relation（动词短语，如 calls、imports、implements）、confidence 标签、confidence_score（仅 INFERRED）与 source_file。3 个以上节点的组关系以超边形式存在 G.graph["hyperedges"] 中。

四、安装：Python 3.10+，包名 graphifyy

波兰语版 README 列出的安装方式（要求 Python 3.10+）在 pyproject.toml 中得到印证：requires-python = ">=3.10"、包名 graphifyy（双 y）、当前版本 0.9.52，命令行入口仍为 graphify（[project.scripts] 中 graphify = "graphify.__main__:main"，另有 graphify-mcp = "graphify.serve:_main"）：

uv tool install graphifyy && graphify install   # 推荐，隔离环境
# 或 pipx
pipx install graphifyy && graphify install
# 或 pip
pip install graphifyy && graphify install

官方包名提醒：PyPI 包名是 graphifyy，其他 graphify* 包均非官方。graphify install 负责把技能注册进你的 AI 助手；--project 可装到当前仓库（如 .claude/skills/graphify/SKILL.md）而非用户目录。

按需启用可选能力（对应 pyproject.toml 的 [project.optional-dependencies]），只装需要的：

Extra	能力	安装
pdf	PDF 抽取	uv tool install "graphifyy[pdf]"
office	.docx/.xlsx	uv tool install "graphifyy[office]"
video	faster-whisper + yt-dlp 音视频转写	uv tool install "graphifyy[video]"
mcp	MCP stdio 服务	uv tool install "graphifyy[mcp]"
leiden	Leiden 社区检测（Python < 3.13）	uv tool install "graphifyy[leiden]"
neo4j / falkordb	图谱推送	uv tool install "graphifyy[neo4j]"
ollama / openai / gemini / anthropic / bedrock	各类 LLM 后端	如 uv tool install "graphifyy[ollama]"
all	以上全部	uv tool install "graphifyy[all]"

默认依赖已包含 networkx、numpy、rapidfuzz 与整套 tree-sitter 语法包（pyproject.toml 第 14–44 行），保证 Pass 1 开箱即用地本地运行。

五、使用：建图、增量更新与三类查询

波兰语版 README 给出的核心命令集（与 README.md 的 "Common commands" 一致）：

/graphify .                        # 对当前文件夹建图
/graphify ./raw --update           # 只重新抽取变更文件
/graphify ./raw --mode deep        # 更激进的语义抽取（扩展系统提示词）
/graphify query "co łączy Attention z optymalizatorem?"   # 自然语言提问
/graphify path "DigestAuth" "Response"                   # 两节点最短路径
graphify hook install              # 安装 git post-commit / post-checkout 钩子
graphify update ./src              # 手动增量同步

三类查询直接作用于 graph.json：

• query "<问题>"：为自然语言问题返回作用域子图，替代对原始文件的 grep；
• path "A" "B"：追踪任意两个概念如何相连（如 DigestAuth 到 Response 的最短路径）；
• explain "<概念>"：解释单个节点——源码位置、所属社区、度数与连接列表（每条带 EXTRACTED/INFERRED 标签）。

增量能力由 SHA256 内容缓存支撑：每个被抽取的文件按内容哈希指纹化，重跑时未变更文件整体跳过，只有新增或修改的文件重新过抽取管线，缓存位于 graphify-out/cache/。graphify/cache.py 中可以看到指纹计算逻辑（hashlib.sha256 对文件内容更新哈希，Markdown 只取正文部分）；--update 即建立在"指纹未变即跳过"之上。团队场景下 graphify-out/ 建议提交进 git，配 graphify hook install 后，git commit 与切分支会自动后台重建（纯 AST，无 API 费用），git pull 后补一次 graphify update . 即可与队友同步。

六、产出物：graphify-out/ 里有什么

建图完成后你得到以下产物（波兰语版 README 的四行目录树）：

graphify-out/
├── graph.html       交互式图谱 — 任意浏览器打开，可点节点、过滤、搜索
├── GRAPH_REPORT.md  审计报告：god nodes、意外连接、建议问题
├── graph.json       持久图谱 — 数周后仍可查询，无需重读文件
└── cache/           SHA256 缓存 — 重跑只处理变更文件

输出目录名默认 graphify-out，可通过 GRAPHIFY_OUT 环境变量覆盖（支持相对名或绝对路径），目录名收敛在 graphify/paths.py 单点定义，供缓存、watch、安全等模块共用。

报告（GRAPH_REPORT.md）内容对应波兰语版 README 的"Co otrzymujesz（你将得到）"五项，graphify/report.py 中实现了建议问题的渲染（graphify/report.py#L312 附近）：

• God nodes——度数最高的概念，一切调用流经之处；
• 意外连接（Surprising connections）——跨文件/跨模块的边，按"意外程度"排序；
• 建议问题——图谱特别擅长回答的 4–5 个问题；
• "为什么"——# NOTE: / # WHY: 注释、docstring 与设计文档中的设计理由被抽取为独立节点，链接到被解释的代码；
• token 基准——混合语料下每次查询比读原始文件少 71.5 倍 token。

七、隐私模型：什么留在本地，什么走 API

波兰语版 README 的"Privacy"一节三句话概括，均与当前仓库的隐私说明一致：

1. 代码文件：本地 tree-sitter AST 处理，不离开机器。纯代码语料完全离线——graphify extract 不需要任何 key；混合仓库可加 --code-only 只索引代码、跳过需要 LLM 的文档/PDF/图片；
2. 视频/音频：本地 faster-whisper 转写，不离开机器；
3. 无遥测：没有使用统计、没有分析上报。

只有文档、PDF、图像这类语义通道会调用模型 API（IDE 内由助手会话的模型提供；无头 CI 场景 graphify extract 需要配置相应后端 key，如 ANTHROPIC_API_KEY、OPENAI_API_KEY、OLLAMA_BASE_URL 等，且支持 Ollama 全本地方案）。数据驻留有要求的团队可以用 --backend ollama 或显式 --backend 固定后端。

八、延伸阅读

• docs/how-it-works.md：抽取管线、Leiden 社区检测、置信度评分细则与 token 基准的完整依据；
• ARCHITECTURE.md：模块划分、如何新增一种语言解析器；
• docs/translations/README.pl-PL.md：本文所基于的波兰语版 README 原文；
• tests/：如 tests/test_extract.py、tests/test_incremental.py 覆盖了抽取与增量缓存行为；worked/httpx/、worked/karpathy-repos/ 提供可复跑的输入与真实输出。

总结一句：graphify 把"读文件找答案"替换成"查图谱找答案"——建图阶段代码走本地确定性 AST（免费、无 LLM）、媒体走本地转写、文档走并行语义通道；产出物是带证据标签（EXTRACTED/INFERRED/AMBIGUOUS）与置信分的 NetworkX 图，配合 SHA256 缓存与 git 钩子保持新鲜，从而让"两个概念怎么连起来""这个模块为什么这么设计"这类问题变成一次 query/path 调用的事。