Graphify：把整个代码库变成可查询的知识图谱 —— 三遍解析管线、置信度标签与本地化运行指南

graphify 是面向 AI 编码助手的"代码库地图"工具：在 Claude Code、Codex、Cursor、Gemini CLI 等助手中输入 /graphify，它读取你的代码、文档、PDF 与多媒体文件，构建一张知识图谱，并返回你原本"不知道存在"的结构关系。本文基于仓库中的罗马尼亚语 README（docs/translations/README.ro-RO.md）与 docs/how-it-works.md 展开，结合源码（graphify/cache.py、graphify/cluster.py、pyproject.toml）印证其实现细节，帮助读者掌握从安装、建图到查询图谱的完整实战链路。

一条命令的产出：graphify-out/ 里的四样东西

整个体验的入口只有一行：

/graphify .

运行完成后，项目根目录下会生成 graphify-out/ 输出目录（目录名可用环境变量 GRAPHIFY_OUT 覆盖，见 graphify/cache.py 对 graphify.paths.GRAPHIFY_OUT 的引用）：

graphify-out/
├── graph.html       交互式图谱 — 可在任意浏览器打开，点选节点、过滤、搜索
├── GRAPH_REPORT.md  亮点报告 — 上帝节点、意外连接、建议提问
├── graph.json       持久化图谱 — 数周后仍可直接查询，无需重读源文件
└── cache/           SHA256 缓存 — 重复运行只处理有改动的文件

这四样产物的分工是 graphify 的核心设计：graph.html 给人看，GRAPH_REPORT.md 给架构评审用，graph.json 给 Agent 查询用，cache/ 让增量重建免费。graph.json 采用 NetworkX 的 node-link 格式，每个节点含 id、label、file_type（code/document/paper/image/rationale）、source_file；每条边含 source、target、relation（如 calls、imports、semantically_similar_to）、confidence 与 confidence_score，格式细节见 docs/how-it-works.md。

三遍管线（three passes）：确定性 AST、本地 Whisper、并行语义抽取

罗马尼亚语 README 概括道："graphify 以三遍（three passes）工作：先是确定性 AST 遍历，用 tree-sitter 从代码中提取结构，完全不经过 LLM；然后视频与音频文件在本地由 faster-whisper 转写；最后由（助手的）子代理并行处理文档、论文、图片和转写稿。结果被合并进一张 NetworkX 图，用 Leiden 算法分组，并导出为交互式 HTML、可查询 JSON 与审计报告。" docs/how-it-works.md 对这三遍的展开更具体：

Pass 1 —— 代码结构（免费，零 API 调用）。tree-sitter 解析代码文件，抽取类、函数、import、调用图与内联注释，全程本地运行、无 LLM 参与。SQL 文件有特殊处理：表、视图、外键与 JOIN 关系被确定性抽取。一个关键边界是：纯代码语料不会进入 LLM 语义抽取——如果语料只有代码文件，Pass 3 会被整体跳过，语义抽取只留给文档、论文、图片和转写稿。这意味着代码建图可以完全离线、无需任何 API key。

Pass 2 —— 视频与音频（本地，零 API 调用）。用 faster-whisper 本地转写；转写 prompt 会用当前代码图中度最高的"上帝节点"来播种，使转写聚焦你的领域。转写结果同样进缓存，重跑跳过已处理文件。

Pass 3 —— 文档、论文、图片（子代理并行，消耗 token）。子代理并行读取 markdown、PDF、图片与转写稿，每个代理输出一段 JSON 片段（节点、边、群组关系），最终合并成一张图。在进入 Pass 3 之前，可选转换器会把 .docx/.xlsx 等指针/二进制格式转成 graphify-out/converted/ 下的 Markdown 侧车文件（Office 文件需要 [office] extra；Google Workspace 文件需 --google-workspace 且已认证的 gws CLI）。

关于语言支持：README（ro-RO 版）与 how-it-works 文档均写明"通过 tree-sitter AST 支持 25 种编程语言"；而从仓库当前的 README.md 文件类型表看，tree-sitter 语法已扩展到约 37 种（.py .ts .js .go .rs .java .c .cpp .cs .kt .scala .php .swift .zig .ps1 ...），并另有正则提取器（如 Salesforce Apex 的 .cls/.trigger）与可选 extra（Terraform、OCaml、Common Lisp、Pascal 等）。从源码结构看，pyproject.toml 列出了各 tree-sitter 语法包及其版本约束（如 tree-sitter>=0.23.0,<0.26），且 requires-python = ">=3.10"，与 ro-RO README 的"Cerințe: Python 3.10+"一致。

置信度标签：EXTRACTED / INFERRED / AMBIGUOUS

ro-RO README 的核心声明之一："每条关系都被打上 EXTRACTED、INFERRED（带置信度分数）或 AMBIGUOUS 标签"。这套标签让读者始终能区分"直接从源码读到的"与"推断出来的"。docs/how-it-works.md 给出了完整定义：

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

EXTRACTED 边的置信度恒为 1.0；INFERRED 边使用离散评分表：0.95（近乎确定：显式跨文件引用且只有一个可能目标）、0.85（强证据：命名与上下文一致）、0.75（合理：上下文相关但非显式）、0.65（弱：仅命名相似）、0.55（推测）。这一离散集合在源码中也有对应——graphify/export.py 的注释明确写出"离散的 INFERRED 集合 {0.55, 0.65, 0.75, 0.85, 0.95}"，graphify/build.py 则负责把字段里出现的其他数值归一化到该集合，测试 tests/test_inferred_confidence_rubric.py 对评分规则有专门覆盖。

安装与快速上手

前提：Python 3.10+，以及至少一个 AI 编码助手（Claude Code、Codex、OpenCode、Cursor、Gemini CLI 等）。

第一步 —— 安装包（三种方式任选）：

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

官方包名注意：PyPI 包名是 graphifyy（双 y），CLI 命令仍叫 graphify。若用 uvx 临时运行需写明包名：uvx --from graphifyy graphify install。

第二步：graphify install 把 /graphify 技能注册到你的 AI 助手。之后在助手里输入即可开始：

/graphify .                          # 为当前目录建图
/graphify ./raw --update             # 增量重建：只重抽改动的文件
/graphify query "ce conectează Attention cu optimizatorul?"
/graphify path "DigestAuth" "Response"
graphify hook install                # 安装 git 钩子，提交后自动重建
graphify update ./src                # git pull 后手动同步图谱

常用查询命令对应到终端则是：

graphify query "what connects auth to the database?"
graphify path "UserService" "DatabasePool"
graphify explain "RateLimiter"

graphify hook install 会注册 post-commit 与 post-checkout 钩子（commit 后自动重建——纯 AST、无 API 成本），并附带一个 git merge driver，使两个开发者同时提交时 graph.json 不会留下冲突标记。PowerShell 用户注意：Windows 上应写 graphify . 而非 /graphify .（前导斜杠会被当作路径分隔符）。更多可选依赖（[pdf]、[office]、[video]、[mcp]、[leiden]、[ollama] 等 extras）见 README.md 的 "Optional extras" 一节。

报告里有什么：上帝节点、意外连接与 71.5x token 基准

ro-RO README 的 "Ce obțineți"（你会得到什么）一节列出了五样开箱即得的能力：

• 上帝节点（God nodes）——度数最高的概念，一切流量都经过它们；
• 意外连接（Conexiuni surprinzătoare）——不同文件/模块之间的关系，按意外程度排序；
• 建议提问——图谱恰好能回答的 4–5 个问题；
• "为什么"（De ce）——docstring 与设计理由被抽成独立节点并链接到所解释的代码（# NOTE:、# WHY: 等注释也如此处理）；
• token 基准——在混合语料上每次查询少 71.5x token。

关于 71.5x 这个数字，docs/how-it-works.md 给出了可复核的出处：基准语料是 "Karpathy 仓库 + 5 篇论文 + 4 张图片，共 52 个文件"，即 ro-RO README 引言中提到的 "Andrej Karpathy 的 /raw 文件夹场景"——把论文、推文、截图和笔记丢进一个文件夹，graphify 就是对这个问题的回答：查询时读紧凑图谱而非原始文件，token 开销从"每次读全部原文"降为"读一次构建、反复查图"。完整基准表：

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

token 缩减随语料规模放大：6 个文件本来就能塞进上下文窗口，此时图谱的价值是结构性清晰而非压缩；52 个文件时节省开始复利式增长。仓库的 worked/ 目录保存了真实语料与真实输出，可自行复跑验证：例如 worked/karpathy-repos/GRAPH_REPORT.md、worked/karpathy-repos/graph.json 及配套的 review.md，还有 worked/httpx/、worked/mixed-corpus/ 等。

隐私边界：什么留在本地，什么会离开

ro-RO README 的 "Confidențialitate" 一节声明："代码文件通过 tree-sitter AST 在本地处理；视频在本地用 faster-whisper 转写；无遥测。" 结合 README.md 的 Privacy 节，完整边界是：

• 代码文件——tree-sitter 本地解析，零出网；纯代码语料甚至不需要 API key，graphify extract 可完全离线运行；混合仓库可加 --code-only 只索引代码、跳过需要 LLM 的文档/PDF/图片；
• 视频/音频——faster-whisper 本地转写，零出网；
• 文档、PDF、图片——经 AI 助手做语义抽取（/graphify 技能用 IDE 会话中的模型；无头 graphify extract 则需配置 Gemini / Kimi / Claude / OpenAI / DeepSeek / Ollama / Bedrock / claude-cli 等后端之一，按环境变量自动探测，优先级 Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama）；
• 无遥测、无使用统计、无分析。

源码级印证：缓存、聚类与并行的实现事实

以下实现细节均可在仓库中直接核对：

SHA256 缓存。graphify/cache.py 的实现比 README 描述更细：AST 缓存条目按"包版本 + schema 版本"命名空间隔离（cache/ast/v{version}-s{schema}/），因为 AST 输出是提取器代码的产物，跨版本复用旧结果会屏蔽提取器修复；语义缓存则故意不按版本隔离（否则每次发版都对未改动文件重新计费），而是按抽取 prompt 的指纹命名空间（cache/semantic/p{fingerprint}/）——prompt 不变则条目跨版本存活，prompt 变更才失效。首次使用会清扫其他版本遗留的旧目录（_cleanup_stale_ast_entries）。

Leiden 聚类与降级路径。graphify/cluster.py 的模块 docstring 写明："使用 Leiden（graspologic，若可用），否则回退到 Louvain（networkx）；拆分过大的社区并返回内聚度分数。" 它优先直调 graspologic_native.leiden() 以绕开 graspologic 的 ANSI 进度输出，失败再走 graspologic.partition.leiden()。注意 Leiden 仅在 Python < 3.13 下可用（pyproject.toml 中 leiden = ["graspologic; python_version < '3.13'"]），Python 3.13+ 环境会自然走 Louvain 回退路径。语义相似度边（semantically_similar_to）本身就在图里，直接参与社区形状——没有 embedding、没有向量库，图结构本身就是相似度信号。

并行 AST 抽取。从 docs/how-it-works.md 与代码结构看，代码文件用 ProcessPoolExecutor 多进程并行抽取（绕开 GIL），84 个代码文件的语料上比顺序运行快约 1.66x；文档/论文/图片批次则以并行子代理分发。

多语言提取器。graphify/extractors/ 目录下按语言组织提取器（go.py、rust.py、csharp.py、terraform.py、pascal.py 等），tests/fixtures/ 与 tests/test_languages.py 为每种语言提供固定夹具与测试，worked/example/raw/ 则给出一条完整的可复现样例语料。

从翻译文档回到项目本体

docs/translations/README.ro-RO.md 是项目 README 的罗马尼亚语官方译本（多语言索引见仓库根 README.md 的 "Read this in other languages"），其信息骨架——/graphify 单命令入口、四件套输出、三遍管线、三标签置信度、graphifyy 包名、71.5x token 基准、全本地隐私模型——与 docs/how-it-works.md 的管线细节和 graphify/ 源码一一对应。建议的深入路径：先读 docs/how-it-works.md 掌握管线与置信度评分，再读 ARCHITECTURE.md 看模块划分与如何添加新语言，最后跑一遍 worked/ 下的样例语料（如 worked/mixed-corpus/raw/），对照其 GRAPH_REPORT.md 与 graph.json 验证本文所有产出描述。