graphify：从代码、文档到视频构建可查询知识图谱——安装、用法与三阶段管线源码剖析

本文基于官方仓库的土耳其语 README（docs/translations/README.tr-TR.md）展开：它覆盖 graphify 的技能定位、三阶段处理管线、安装与日常命令、报告产出和隐私边界。读完本文，你将掌握如何在 Claude Code、Codex、Cursor、Gemini CLI 等 AI 编程助手中启用 /graphify 技能，把代码库连同 PDF、图片、音视频一起变成可持久查询的知识图谱，并理解其 SHA256 缓存、Leiden 社区检测与置信度标签背后的源码实现。

一、graphify 是什么：面向 AI 编程助手的 /graphify 技能

土耳其语 README 对 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 会从中抽取概念与关系，合并到同一张图里。视频由 faster-whisper 在本地转录；代码侧则通过 tree-sitter AST 支持多语言解析（土耳其语 README 原文表述为 25 种编程语言；从当前仓库英文版 README.md 的"处理文件"清单看，tree-sitter 语法覆盖已扩展到 37 种以上，另含 Apex、Terraform 等专用抽取器）。

土耳其语 README 中引用了一个很有代表性的使用场景：

Andrej Karpathy 会维护一个 /raw 文件夹，存放他的文章、推文、截图和笔记。graphify 正是对这个问题的回应——相比直接阅读原始文件，每次查询的 token 消耗降低 71.5 倍，且图谱跨会话持久可用。

这个 71.5x 的数字并非孤立的宣传口径，仓库中 docs/how-it-works.md 的"Token benchmark"一节给出了完整测量条件（Karpathy 仓库 + 5 篇论文 + 4 张图片，共 52 个文件），且 worked/karpathy-repos/ 目录下保留了原始输入文件与真实输出（GRAPH_REPORT.md、graph.json），可自行复算验证。

一条命令启动，产出固定为四个文件：

/graphify .

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

二、三阶段管线：先确定性 AST，再本地转录，最后 LLM 语义抽取

土耳其语 README 的"Nasıl çalışır（如何工作）"一节概括了三遍处理（three passes）：

1. 第一遍——确定性 AST 抽取（无 LLM）：tree-sitter 从代码文件中抽取结构，产出节点与边；
2. 第二遍——视频与音频：由 faster-whisper 本地转录；
3. 第三遍——LLM 子代理：并行处理文档、论文、图片与转录文本。

三遍结果在 NetworkX 图中合并，用 Leiden 算法做社区聚类，最终导出三种形态：交互式 HTML、可查询 JSON 与审查报告（GRAPH_REPORT.md）。

从源码结构看，这一管线与文档描述严格对应：

• 第一遍的入口是 graphify/extract.py，其模块 docstring 明确写着"Deterministic structural extraction from source code using tree-sitter. Outputs nodes+edges dicts"。具体语法各自独立成抽取器，统一放在 graphify/extractors/ 下（rust.py、go.py、csharp.py、pascal.py、sql.py、terraform.py 等约 25 个模块），由 graphify/extractors/engine.py 与 graphify/extractors/init.py 注册分发。docs/how-it-works.md 补充了一个关键细节：代码文件不会进入 LLM 语义抽取阶段——若语料库纯代码，第三遍直接跳过，语义抽取只服务于文档、论文、图片与转录文本。SQL 文件还有一层特殊处理：表、视图、外键与 JOIN 关系被确定性抽取。
• 第二遍的转录提示词并非空转：docs/how-it-works.md 指出，转录 prompt 会用当前代码图中度数最高的"神节点"作为种子，使转录聚焦在你的领域词汇上；转录结果同样走缓存，重跑跳过已处理文件。
• 第三之前还有可选的格式转换：Office 文件（.docx、.xlsx）与 Google Workspace 快捷方式（.gdoc、.gsheet、.gslides）会先转成 graphify-out/converted/ 下的 Markdown 侧车文件再进入抽取。

社区检测与"无向量库"原则

graphify/cluster.py 的 docstring 说明了社区检测策略：优先使用 graspologic 的 Leiden（图中边密度高的节点归入同一社区），不可用时回退到 NetworkX 的 Louvain。源码中还做了一个值得注意的工程优化：_native_leiden() 直接调用 Rust 编写的 graspologic_native.leiden()，绕开 graspologic 包自身的导入链——注释里解释了完整包导入会连带 umap/pynndescent，JIT 编译开销高达 7–19 秒，而原生调用只需约 1 秒。

Leiden 的输入就是图结构本身：Claude 在语义遍中抽取的相似边（semantically_similar_to）已作为普通边存在于图中，直接参与社区形状，因此不需要嵌入向量，也不需要向量数据库——这正是项目"no vector store"承诺的落点。

置信度标签：每条边都注明出处

土耳其语 README 强调：每条关系都会被标记为 EXTRACTED、INFERRED（带置信分）或 AMBIGUOUS。docs/how-it-works.md 给出了完整评分细则——EXTRACTED 边置信度恒为 1.0，INFERRED 边使用离散档位：

标签	含义	置信分
EXTRACTED	源码中直接存在（函数调用、import 等）	1.0
INFERRED 近确定	显式跨文件引用，唯一合理解释目标	0.95
INFERRED 强证据	命名与上下文一致	0.85
INFERRED 合理	上下文支持但非显式	0.75
INFERRED 弱	仅命名相似	0.65
INFERRED 推测	无直接证据	0.55
AMBIGUOUS	不确定，标记待人工审查	—

图谱格式上，graph.json 采用 NetworkX node-link 结构：每个节点带 id、label、file_type（code/document/paper/image/rationale）、source_file；每条边带 relation 动词短语（calls、imports、implements、semantically_similar_to 等）、confidence 标签与出处文件。

三、安装：两条命令完成"装包 + 注册技能"

土耳其语 README 给出的环境要求是 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

土耳其语 README 特别提醒：PyPI 官方包名是 graphifyy（双 y），唯一官方仓库即本项目；PyPI 上其他 graphify* 命名的包均非官方。README.md 的"Install"小节补充了几个实操细节：

• 第二步 graphify install 是把技能文件写入助手的技能目录。若希望技能只落在当前仓库而非用户主目录，加 --project，例如 graphify install --project --platform codex，会在 .claude/skills/graphify/SKILL.md 或 .agents/skills/graphify/SKILL.md 下写入（附 references/ 侧车），并打印可提交的 git add 提示；
• 若装完提示 graphify: command not found，通常是 uv tool install/pipx install 的 bin 目录（~/.local/bin）不在 PATH 中，运行 uv tool update-shell（或 pipx ensurepath）后重开终端即可；
• 仓库提供 uvx --from graphifyy graphify ... 的免安装跑法，注意必须显式写明包名 graphifyy，否则 uv tool run 会把第一个词当作包名去解析而失败。

技能文件本身由仓库内的 tools/skillgen/ 生成器统一管理：各平台的技能文件（graphify/skill-claude.md、graphify/skill-codex.md 等）与 graphify/skills/ 下的多平台 references/ 文档都由 tools/skillgen/gen.py 按 tools/skillgen/platforms.toml 拼装，tests/test_skillgen.py 与 tools/skillgen/expected/ 中的快照共同保证生成结果与提交内容一致。

四、日常用法：构建、增量更新与查询

土耳其语 README 的"Kullanım（用法）"一节列出的命令集：

/graphify .
/graphify ./raw --update
/graphify query "Attention'ı optimizer'a ne bağlıyor?"
/graphify path "DigestAuth" "Response"
graphify hook install
graphify update ./src

对应语义分别是：

• /graphify . — 对当前目录构建整图；
• /graphify ./raw --update — 增量模式，仅重新抽取已变更的文件（依赖后文的 SHA256 缓存）；
• /graphify query "..." — 用自然语言提问，返回一个作用域受限的子图（土耳其语示例问的是"什么把 Attention 连到 optimizer"）；
• /graphify path "DigestAuth" "Response" — 追踪两个实体之间的连接路径；
• graphify hook install — 安装 git hooks，提交后自动重建图谱；
• graphify update ./src — 手动同步指定目录的图谱。

README.md 中的真实查询示例展示了返回形态：graphify explain "APIRouter" 输出节点的源码位置（routing.py L2210）、所属社区、度数及 47 条连接（每条连接标注 uses/imports 等关系与 EXTRACTED/INFERRED 标签）；graphify path "FastAPI" "ModelField" 输出 3 跳最短路径 FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField。英文版还给出了更完整的命令面，例如 /graphify . --cluster-only（只重跑聚类）、/graphify . --wiki（从图谱生成 Markdown 维基）、graphify export callflow-html（Mermaid 调用流 HTML），以及把图谱暴露为 MCP 服务的 python -m graphify.serve graphify-out/graph.json（实现见 graphify/serve.py）。

docs/how-it-works.md 还提到并行抽取的工程细节：代码文件通过 ProcessPoolExecutor 做多进程 AST 抽取以绕开 GIL，在 84 个代码文件的语料上比串行快约 1.66 倍；文档/论文/图片批次则派发为并行 Claude 子代理。

五、你得到什么：神节点、惊人连接与"为什么"

土耳其语 README 的"Ne elde edersin（你将获得）"一节列出报告的五类产出：

• 神节点（God nodes）——度数最高的概念，即整个系统"流经"的核心；
• 惊人连接（Surprising connections）——按意外程度排序的跨文件/跨模块关联；
• 建议提问——这张图"独有能力回答"的问题清单（英文版说明为 4–5 条）；
• "为什么"——# NOTE:/# WHY: 行内注释、docstring 与设计文档中的设计动机被抽取为独立的 rationale 节点并链接到被解释的代码；
• Token 对比——混合语料上每次查询比直接读文件少 71.5x token。

这些能力在仓库中有可核查的实证产出：worked/karpathy-repos/ 保存了对 Karpathy 仓库语料运行后的 GRAPH_REPORT.md、graph.json 与诚实的 review.md（记录图谱对在哪里、错在哪里）；worked/httpx/ 与 worked/mixed-corpus/ 则是合成 Python 库与混合语料的两组对照。token 缩减随语料规模放大：docs/how-it-works.md 的表格显示 4 文件语料约 5.4x、52 文件语料 71.5x，而 6 文件语料接近 1x——语料小到能塞进上下文窗口时，图谱的价值在于结构清晰度而非压缩。

六、隐私边界：什么是本地处理

土耳其语 README 的"Gizlilik（隐私）"一节给出三条边界，均可在仓库中找到对应实现：

1. 代码文件——tree-sitter AST 本地解析，不出机器。纯代码语料甚至可以完全离线运行（英文版说明可加 --code-only 跳过文档/PDF/图片的 LLM 语义遍）；
2. 视频/音频——faster-whisper 本地转录，同样不出机器；
3. 文档、PDF、图片——经由 /graphify 技能走你 IDE 会话所用的模型做语义抽取（无头 CI 场景则需配置 API key，后端自动探测优先级为 Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama）；
4. 无遥测——没有使用统计、没有分析上报。

七、源码纵深：SHA256 缓存与版本化失效策略

输出目录中的 cache/ 是增量更新的地基。docs/how-it-works.md 的表述是"每个被抽取文件按内容哈希指纹化，重跑完全跳过未变更文件，缓存位于 graphify-out/cache/"。graphify/cache.py 的源码把这句话展开成了精细的失效策略：

• AST 缓存按"包版本 + 缓存 schema"命名空间化（cache/ast/v{version}-s{schema}/）。原因写得很直白：AST 缓存条目是本包抽取器代码的产物，若只按文件内容做键，新版本修复了抽取器 bug 后仍会持续回放修复前的旧结果。首次使用会自动清扫其他版本的残留目录（_cleanup_stale_ast_entries）；
• 语义缓存刻意不按版本号失效——条目由 LLM 依据文件内容生成，按版本失效会在每次补丁发布时让未变更文件重新计费。取而代之的是对抽取 prompt 做 SHA256 指纹（_PROMPT_FP_LEN 截断的十六进制前缀），条目存于 cache/semantic/p{fingerprint}/：prompt 没变则跨版本复用，prompt 变更则整批失效。

这一设计直接支撑了土耳其语 README 中 --update 的承诺：重复运行只处理变更文件，图谱可在数周之后仍保持可查询。

八、小结与延伸阅读

graphify 的核心主张可以用土耳其语 README 的两句原话概括：在任意 AI 助手中输入 /graphify，把"阅读文件"替换为"查询图谱"；每条边都可解释（EXTRACTED/INFERRED/AMBIGUOUS），代码解析完全本地、无向量库。土耳其语 README 末尾还提到，官方在 graphify 之上构建了企业层 Penpax（graphify 之上的 always-on 层，面向会议、文件、文档与代码的持续更新场景，免费试用即将开放）——该部分属于产品预告，本文不作展开。

想要继续深入，建议从以下仓库文件入手：

• docs/how-it-works.md：三遍管线、Leiden 社区检测、置信度评分、token 基准的完整说明；
• ARCHITECTURE.md：模块划分与"如何新增一种语言"；
• worked/：三组真实运行语料的输入与输出，可直接对照验证；
• graphify/extract.py 与 graphify/extractors/engine.py：AST 抽取主流程与抽取器注册引擎；
• graphify/cluster.py、graphify/cache.py：社区检测回退策略与缓存失效机制。