graphify 实战指南：用 /graphify 把代码库与多模态资料变成可查询知识图谱

本文基于 graphify 仓库的泰文版 README（docs/translations/README.th-TH.md）整理成文，完整覆盖原文档的"三轮处理流程、安装、命令、输出产物、隐私边界"等全部要素，并结合 docs/how-it-works.md 与仓库源码（提取器、聚类、缓存、转录等模块）逐项展开。读完后你可以独立完成：安装 graphify、在 AI 编程助手中运行 /graphify 建图、用 query/path/explain 查询图谱，并理解 EXTRACTED/INFERRED/AMBIGUOUS 置信度标签与 SHA256 增量缓存的底层机制。

一、graphify 是什么：面向 AI 编程助手的知识图谱技能

graphify 是一个"技能"（skill）：在 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Kiro、Google Antigravity 等 AI 编程助手里输入 /graphify，它会读取你的文件、构建一张知识图谱，并返回你原本不知道存在的结构关系，从而更快理解 codebase、追溯架构决策背后的"为什么"。

它的三个核心特性（与原文档一脉相承）：

• 代码解析免费且完全本地：代码走 tree-sitter AST 确定性解析，不用 LLM、不产生 API 调用，文件内容不出本机；当前仓库 README.md 中列出的 tree-sitter 语法覆盖 37 种语言，跨文件 calls/imports/inherits/mixes_in 解析支持约 40 种语言（泰文 README 写作时为 25 种，语法清单随版本增长）；
• 每条边都有解释：每条连接都会打上 EXTRACTED（源码中明确存在）或 INFERRED（由解析推导，附置信分）等标签，你能分清"直接读到的"和"推断出来的"；
• 不是向量索引：没有 embeddings、没有向量库，是一张真正可遍历的图——可以提问、追踪两个概念间的最短路径、解释单个概念。

多模态全覆盖：代码、PDF、Markdown、截图、图表、白板照片、其他语言的文字图片，以及视频和音频文件，graphify 都能从中抽取概念与关系，并把它们连接进同一张图。视频和音频在本地用 faster-whisper（Whisper 加速实现）转写成文字。原文档中关于 Karpathy /raw 文件夹的例子仍然适用：论文、推文、截图、笔记堆在一个文件夹里难以检索，graphify 给出的答案正是——每次查询比直接读原始文件少 71.5 倍 token，且图谱在会话之间持久存在。

二、工作原理：三轮（pass）处理流程

泰文 README 概括为"3 รอบ"（三轮），docs/how-it-works.md 给出了权威细节，下面逐轮对照仓库源码说明。

Pass 1：代码结构（免费、无 API 调用）

tree-sitter 解析代码文件，抽取类、函数、import、调用图与行内注释，全程本地运行、不涉及 LLM。SQL 文件有专门处理：表、视图、外键与 JOIN 关系同样被确定性抽取。

从源码结构看，这一轮的实现位于：

• graphify/extract.py：主提取入口 extract()，按扩展名分派到各语言提取器（Python、TS/JS、Go、Rust、Java、C/C++、C#、Swift、Ruby、Kotlin、Scala、PHP、Lua、Zig、PowerShell、Elixir、Julia、Verilog、Fortran 等，见 graphify/extractors/ 目录下的按语言拆分模块）；
• graphify/extractors/engine.py：通用 tree-sitter 遍历引擎，负责调用点收集、接收者类型推断、装饰器与注解边等；
• 解析后的符号跨文件解析由 graphify/extractors/resolution.py、graphify/symbol_resolution.py、graphify/resolver_registry.py 完成，把"裸调用名"落到具体目标节点。

关键设计：代码文件不会进入 LLM 语义提取路径。如果整个语料只有代码文件，Pass 3 会被整体跳过——语义提取只服务于文档、论文、图片与转写文本（docs/how-it-works.md 第 10 行明确说明）。

Pass 2：视频与音频（本地、无 API 调用）

音视频文件由 faster-whisper 本地转写。一个巧妙细节：转写提示词会用你代码图中当前度最高的 top god nodes 做"种子"（initial_prompt），让转写聚焦于你的领域术语。转写结果有缓存，重复运行会跳过已处理文件。

对应源码：graphify/transcribe.py 中 transcribe() 执行本地转写、build_whisper_prompt(god_nodes) 生成 god-node 种子提示词；pyproject.toml 中 video extra 声明了 faster-whisper 与 yt-dlp 依赖（且要求 Python 3.11+）。

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

文档、PDF、图片与转写文本被并行分派给 LLM 子代理（Claude subagent），每个子代理读一批文件并输出 JSON 片段（nodes、edges、群体关系/hyperedges），片段再合并成单一图。合并与构建逻辑在 graphify/llm.py（extract_corpus_parallel()，按 token 预算分块、可配置并发与重试）与 graphify/build.py（build_merge()，含节点/边去重与增量合并）。

在 Pass 3 之前，可选的转换器会先把支持的"指针/二进制"格式转成 Markdown 边车文件放到 graphify-out/converted/：Office 文件（.docx、.xlsx）需要 office extra；Google Workspace 快捷方式（.gdoc、.gsheet、.gslides）是 opt-in，用 --google-workspace 或 GRAPHIFY_GOOGLE_WORKSPACE=1 开启，且需要一个已认证的 gws CLI。

聚类与导出：NetworkX + Leiden

三轮结果汇入一张 NetworkX 图，用 Leiden 算法（一种按边密度聚类的图聚类方法）划分社区——节点之间连接越密集越落在同一个社区。由于 LLM 抽取的语义相似边（semantically_similar_to）本来就在图里，社区形状直接受其影响，不需要单独的 embedding 步骤。聚类实现在 graphify/cluster.py 的 cluster(G, resolution, exclude_hubs_percentile)，并计算每个社区的凝聚度分数 cohesion_score。最终导出为：交互式 HTML（graphify/exporters/html.py 的 to_html()）、可查询的 JSON（graphify/export.py 的 to_json()，NetworkX node-link 格式）以及检查报告（graphify/report.py）。

三、安装：Python 3.10+ 与官方包名 graphifyy

泰文 README 给出的安装要求与命令完整保留如下。

要求：Python 3.10+（pyproject.toml 中 requires-python = ">=3.10"）以及下列任一 AI 编程助手：Claude Code、Codex、OpenCode、Cursor 等（当前仓库支持 20+ 平台）。

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

官方包名提示（泰文 README 原文强调）：PyPI 上的包名是 graphifyy（双 y），CLI 命令仍叫 graphify；PyPI 上其他 graphify* 包均非官方。

从源码结构看，graphify 命令对应 pyproject.toml 的 [project.scripts]：graphify = "graphify.__main__:main"，另有 graphify-mcp 指向 graphify.serve:_main（MCP stdio 服务器）。graphify/install.py 的 install() 负责把技能文件（skill*.md，打包在 graphify/skill.md 等）与 always-on 指令块（graphify/always_on/ 下的 claude-md.md、agents-md.md 等）写入对应平台的目录。

当前 README.md 补充了几个实用细节：

• 想装到当前仓库而非用户主目录，加 --project：graphify install --project、graphify install --project --platform codex，会写入 .claude/skills/graphify/SKILL.md 或 .agents/skills/graphify/SKILL.md 及按需加载的 references/ 侧车文件，并打印 git add 提示；
• PowerShell 里用 graphify . 而不是 /graphify .（开头的斜杠是路径分隔符）；
• graphify: command not found 通常是 ~/.local/bin 不在 PATH，跑 uv tool update-shell 或 pipx ensurepath 后重开终端；
• uvx 临时运行要写包名：uvx --from graphifyy graphify install（uv tool run 把第一个词当包名解析，而包是 graphifyy）。

按需安装可选 extra（来自 pyproject.toml 的 [project.optional-dependencies]，与 README 表格一致，摘选常用项）：

Extra	增加的能力	安装方式
pdf	PDF 抽取	uv tool install "graphifyy[pdf]"
video	音视频转写（faster-whisper + yt-dlp）	uv tool install "graphifyy[video]"
mcp	MCP stdio 服务器	uv tool install "graphifyy[mcp]"
office	.docx/.xlsx 支持	uv tool install "graphifyy[office]"
neo4j / falkordb	图数据库推送	uv tool install "graphifyy[neo4j]"
leiden	Leiden 社区检测（Python < 3.13）	uv tool install "graphifyy[leiden]"
openai / anthropic / gemini / ollama / bedrock / azure	各 LLM 后端	同模式安装对应 extra
all	以上全部	uv tool install "graphifyy[all]"

四、运行与查询：常用命令

泰文 README 的"การใช้งาน"（用法）一节给出的五条命令如下，均可直接在助手会话中使用：

/graphify .                        # 为当前文件夹建图
/graphify ./raw --update           # 只重新抽取发生变更的文件
/graphify query "อะไรเชื่อม Attention กับ optimizer?"   # 即：/graphify query "什么把 Attention 和 optimizer 连接起来？"
/graphify path "DigestAuth" "Response"
graphify hook install
graphify update ./src

当前 README.md 的 "Common commands" 在此基础上给出了更完整的命令集（可作为复制即用清单）：

/graphify .                        # 为当前文件夹建图
/graphify ./docs --update          # 只重新抽取变更文件
/graphify . --cluster-only         # 不重新抽取，仅重跑聚类
/graphify . --cluster-only --resolution 1.5      # 更细粒度的社区
/graphify . --cluster-only --exclude-hubs 99     # 在 god-node 排名中压制工具类超级枢纽
/graphify . --no-viz               # 跳过 HTML，只出报告 + JSON
/graphify . --wiki                 # 从图构建 Markdown wiki

/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              # commit 与切换分支时自动重建
graphify merge-graphs a.json b.json  # 合并两张图

各命令的底层入口：

• query / path / explain：graphify/serve.py 实现了图检索核心——_query_graph_text()（BFS/DFS 取作用域子图并按 token 预算裁剪）、_shortest_path_text()（path 查询）、_tool_explain 系列（explain 单概念，含 Community、Degree 与全部连接边及置信标签）。README.md 中给出了真实输出示例：graphify path "FastAPI" "ModelField" 返回 3 跳最短路径，每跳带 --uses-->/[INFERRED] 之类的关系与置信标注；
• hook install：graphify/hooks.py 的 install() 向 .git/hooks 写入带标记的 post-commit / post-checkout 脚本，并在安装时把当前解释器路径直接嵌入脚本，保证 GUI git 客户端和 CI 环境（~/.local/bin 不在 PATH）也能正确触发；升级 graphify 后需重跑一次 graphify hook install 刷新内嵌路径。README 还建议 git pull 之后手动跑 graphify update .；
• 增量更新：--update/update 走 graphify/manifest.py 的清单比对（mtime + 内容指纹）与 graphify/build.py 的 merge_raw_extraction()，只重处理变更文件并修剪已删源文件的节点/边。

五、输出产物：graphify-out/ 目录

泰文 README 给出的四产物目录结构原文照录并补充说明：

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

关于 graph.json 的具体格式（docs/how-it-works.md "The graph format" 一节）：采用 NetworkX node-link 格式。每个节点含：

• id——稳定标识符
• label——人类可读名称
• file_type——code、document、paper、image、rationale
• source_file——来源文件

每条边含：

• source、target——节点 ID
• relation——动词短语（如 calls、imports、implements、semantically_similar_to）
• confidence——EXTRACTED、INFERRED 或 AMBIGUOUS
• confidence_score——浮点分（仅 INFERRED 有）
• source_file——关系被发现的位置

连接 3 个及以上节点的群体关系（hyperedges）存放在 G.graph["hyperedges"]。

关于 cache/：每个被抽取的文件按内容哈希（SHA256）做指纹，重跑时完全跳过未变更文件，只有新增或修改的文件重新过抽取流程。实现在 graphify/cache.py：file_hash() 计算指纹、load_cached()/save_cached() 读写缓存条目（AST 缓存与语义缓存分开管理），另有词数缓存 cached_word_count() 避免重复统计。

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

泰文 README 一句话概括——每条关系被标记为 EXTRACTED、INFERRED（附置信分）或 AMBIGUOUS。docs/how-it-works.md 给出了完整定义表与评分细则：

标签	含义
EXTRACTED	直接在源码中发现（如一个函数调用、一条 import）
INFERRED	LLM 做出的合理推断，附 confidence_score（0.0–1.0）
AMBIGUOUS	不确定——在报告中被标记出来供人工复核

EXTRACTED 边置信分恒为 1.0；INFERRED 边使用离散评分标准：

• 0.95——近乎确定（明确的跨文件引用、唯一合理目标）
• 0.85——强证据（命名与上下文一致）
• 0.75——合理（语境性支持但非显式）
• 0.65——较弱（仅命名相似）
• 0.55——推测性

这一契约在测试中也有约束，例如 tests/test_confidence.py 与 tests/test_evidence_binding.py 会校验标签与证据绑定的一致性。

七、报告会给你什么：god nodes 到"为什么"

泰文 README "สิ่งที่คุณได้รับ"（你会得到什么）一节列举的五项能力，全部保留并补充源码依据：

1. God nodes（枢纽节点）——度最高的概念，一切都经过它们。实现在 graphify/analyze.py 的 god_nodes(G, top_n=10)；
2. 意外连接（surprising connections）——位于不同文件/模块之间的边，按"意外度"评分排名，由 surprising_connections() 计算（跨社区、跨文件、跨语言都会加分）；
3. 建议问题（suggested questions）——suggest_questions() 基于社区标签生成 4–5 个这张图特别适合回答的问题；
4. "为什么"——行内注释（# NOTE:、# WHY:、# HACK:）、docstring 与设计理由被抽成独立 rationale 节点并链接到它们解释的代码；graphify/extract.py 中 _extract_python_rationale() 与 _add_rationale() 就是这一机制的 Python 实现，ADR/RFC 引用也会成为节点；
5. Token 基准——见下一节。

GRAPH_REPORT.md 本身由 graphify/report.py 的 generate() 汇总以上所有分析结果渲染而成。

八、71.5 倍 token 基准：数字从何而来

泰文 README 反复引用的 "71.5 เท่า"（71.5 倍）有明确的出处与复现材料：

• docs/how-it-works.md 的 "Token benchmark" 一节说明原理：首次运行做抽取和建图（消耗 token），之后每次查询读的是紧凑图而非原始文件，节省随查询次数复利累积。在混合语料（Karpathy 仓库 + 5 篇论文 + 4 张图片，共 52 个文件）上，每次查询比直接读原始文件少 71.5 倍 token；
• 同文件附了对照表：52 文件混合语料 71.5x；graphify 源码 + Transformer 论文（4 文件）5.4x；httpx 合成 Python 库（6 文件）约 1x——token 压缩比随语料规模增长，小语料的价值更多在结构清晰度而非压缩；
• 完整复现材料在 worked/karpathy-repos/README.md：三个代码仓库（nanoGPT、minGPT、micrograd）+ 5 篇 PDF + 4 张图片共 52 文件，预期约 285 节点、约 340 边、约 17 个有意义社区，god nodes 包括 Value（micrograd）、GPT（nanoGPT）等；同目录的 GRAPH_REPORT.md、graph.json 与 review.md 就是真实运行输出，可自行复算验证；
• 另有 worked/example/README.md（7 文件小文档管线，纯 AST + Markdown、零语义 token 成本）与 worked/httpx/（小型 Python 库）两个更轻量的验证语料。

量化检索本身也可以跑：graphify/benchmark.py 的 run_benchmark() 会测量每次查询子图的 token 量并打印基准。更广泛的检索/记忆基准（LOCOMO、LongMemEval 等）见 BENCHMARKS.md，注意其结论均以该文件标注的测试台架与日期为适用前提。

九、隐私边界：什么在本地，什么走 API

泰文 README "ความเป็นส่วนตัว"（隐私）一节的三条论断逐一对应仓库实现：

• 代码在本地经 tree-sitter AST 处理——Pass 1 无 API 调用，代码文件不会发给 LLM 语义提取器（见第二节 Pass 1 说明）；
• 视频在本地用 faster-whisper 转写——graphify/transcribe.py 本地加载 Whisper 模型，仅 add 外部视频 URL 时才涉及下载；
• 没有遥测上报——源码中查询日志仅写本地文件：graphify/querylog.py 的 log_query() 落盘于本地图谱目录，_log_responses() 决定开关，不存在外部上报通道。

唯一会调用外部后端的是 Pass 3（文档/论文/图片的语义抽取）以及社区命名等 LLM 辅助步骤，且只有在你配置了助手模型或 API key 时才会发生——这正对应 README.md 对 Local-first 特性的表述："代码本地解析（无 LLM、不出本机）；只有对文档/媒体的语义 pass 会调用后端，且仅当你配置了它"。

十、延伸：并行抽取与性能

docs/how-it-works.md "Parallel extraction" 一节还说明：代码文件抽取使用 ProcessPoolExecutor 真多进程（绕过 GIL），文档/论文/图片批次则以并行子代理分派；在 84 个代码文件的语料上，并行 AST 抽取比串行快约 1.66 倍。该行为对应 graphify/extract.py 中的 _extract_parallel() 与 _extract_sequential() 两条路径。若你对抽取正确性有疑虑，graphify/diagnostics.py 的 diagnose_file() 可对单个文件或 JSON 产物做诊断（重复边、悬空引用等），tests/ 目录下的 200+ 测试文件（如 test_extract.py、test_incremental.py、test_dedup.py、test_cache.py）覆盖了解析、增量、去重与缓存各链路，可作为理解内部行为的第二入口。

小结：graphify 的完整工作闭环是——uv tool install graphifyy + graphify install 完成部署，/graphify . 三轮建图（本地 AST → 本地 Whisper → LLM 语义），产物落在 graphify-out/（HTML/报告/JSON/缓存），之后用 query、path、explain 直接查图；EXTRACTED/INFERRED/AMBIGUOUS 标签保证每条边的来源可信可追溯，SHA256 缓存与 --update/hook install 保证增量成本可控。以上每个环节均可在 docs/how-it-works.md、pyproject.toml 与 graphify/ 源码中找到对应实现。