graphify 知识图谱技能详解：三趟提取管线、Leiden 拓扑聚类与边置信度标签

本文基于 graphify 仓库的官方俄语 README（docs/translations/README.ru-RU.md）整理并深入展开。graphify 是一个面向 AI 编码助手的 /graphify 技能：它对代码、文档、PDF、截图、视频音频做本地确定性解析与语义提取，产出一张可查询的知识图谱，让你“查图而不是 grep 文件”。读完全文，你可以掌握它的三趟处理管线、Leiden 社区检测原理、边置信度体系（EXTRACTED/INFERRED/AMBIGUOUS）、各平台安装命令，以及 --update、--cluster-only、--directed 等参数的实际行为与源码位置。

一、它解决什么问题：从“读文件”到“查图”

俄语 README 开篇即点明定位：在 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 从中提取概念和关系并合并为一张图。
• 代码解析零 LLM 成本：代码文件通过 tree-sitter AST 在本地做确定性解析，俄语 README 列出 25 种受支持语言（Python、JS、TS、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、Elixir、Objective-C、Julia、Verilog、SystemVerilog、Vue、Svelte、Dart）；对照当前英文 README，这一数字已扩展到 37 个 tree-sitter 语法。
• 不依赖向量库：聚类基于图拓扑而非嵌入向量，因此没有 embeddings、没有 vector store，只有一张可以遍历的真实图。

README 还提到一个动机场景：类似 Karpathy 的 /raw 文件夹（堆放文章、推文、截图、笔记）这类混合语料，直接读原始文件的 token 开销极高；graphify 在查询时相比读原始文件节省 71.5 倍 token，且结果在多次会话间持久化。该数字有独立佐证：docs/how-it-works.md 给出基准表——52 文件的混合语料（Karpathy 仓库 + 5 篇论文 + 4 张图）为 71.5 倍，语料越大收益越高，6 个文件的小语料则只有约 1 倍。仓库的 worked/ 目录（如 worked/httpx/、worked/mixed-corpus/、worked/karpathy-repos/）保存了原始输入与真实输出（GRAPH_REPORT.md、graph.json、review.md），可自行复现验证。

二、三趟管线：图谱是如何构建的

俄语 README 的 “Как это работает”（工作原理）一节把流程概括为三个 pass，docs/how-it-works.md 给出了完整展开，源码逐一对应。

Pass 1：本地 tree-sitter AST（免费、无 API 调用）

tree-sitter 解析代码文件，提取类、函数、import、调用图、docstring 和内联注释（包括 # NOTE:、# WHY:、# HACK: 这类“为什么”注释），全程不经过 LLM。一个值得注意的细节（见 how-it-works.md）：代码文件在正常管线中不会送入 LLM 语义提取器——如果语料只有代码，Pass 3 整体跳过。这意味着纯代码仓库的建图是 100% 离线、零 token 的（英文 README 将此列为 “0 LLM credits” 基准项）。

Pass 2：视频/音频本地转写（faster-whisper）

视频和音频用 faster-whisper 在本地转写，没有任何内容离开机器。更精细的机制是：转写使用的 prompt 会用你代码图中当前的 top 神节点（god nodes）做领域种子，使转写聚焦于你的技术域；转写结果同样走缓存，重复运行会跳过已处理文件。

Pass 3：Claude 子代理并行语义提取（消耗 token）

Claude 子代理在 markdown、PDF、图片与转写文本上并行运行，每个子代理读取一批文件并输出 JSON 片段（节点、边、组关系），所有片段合并为单一 NetworkX 图。在进入 Pass 3 之前，可选转换器会把 Office 文件（.docx/.xlsx，[office] extra）和 Google Workspace 快捷方式（.gdoc/.gsheet/.gslides，需 --google-workspace 或 GRAPHIFY_GOOGLE_WORKSPACE=1）转成 graphify-out/converted/ 下的 Markdown sidecar 再提取。

代码侧的并行性也有源码佐证：how-it-works.md 说明代码文件使用 ProcessPoolExecutor 做真正的多进程 AST 提取（绕过 GIL），84 个代码文件的语料上比顺序执行快约 1.66 倍。

聚类：Leiden 社区检测，没有 embeddings

这是 README 强调的第二点：聚类基于图拓扑——无需嵌入。Leiden 按边密度找社区；Claude 提取的语义相似边（semantically_similar_to，标记为 INFERRED）本来就在图里，直接参与社区形状。从源码结构看，graphify/cluster.py 的 _partition() 函数优先尝试 Leiden（先走 graspologic_native.leiden 直连路径，再回退 graspologic.partition.leiden），两者都不可用时回退到 NetworkX 的 Louvain；resolution 参数控制社区粒度（>1.0 得到更多更小的社区，<1.0 得到更少更大的社区）。文件头注释还说明了对超大社区的处理：切分后会在子图上跑第二遍 Leiden（见 graphify/cluster.py），这与 CLI 参数 --resolution 1.5（“更细粒度的社区”）的行为一一对应。

三、边置信度标签：EXTRACTED / INFERRED / AMBIGUOUS

README 的核心承诺之一是“每条边都有解释”。每条关系被标记为三种状态之一：

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

docs/how-it-works.md 给出了 INFERRED 边的离散评分标准：0.95（近乎确定，明确的跨文件引用）、0.85（强证据，命名与上下文吻合）、0.75（合理但非显式）、0.65（弱，仅命名相似）、0.55（推测）。

源码中这些标签不只是元数据，而是参与排名的真实信号：graphify/analyze.py 在计算“意外连接”分数时对不同置信度边给出加权（AMBIGUOUS/INFERRED/EXTRACTED 的 bonus 分别为 3/2/1，且跨语言的 INFERRED 调用/使用边会被压制结构性加分），报告中的待复核问题列表则按 AMBIGUOUS → INFERRED → EXTRACTED 排序（见 graphify/analyze.py）——这与 README “每条结果都附自然语言‘为什么’”的描述一致：AMBIGUOUS 边会直接生成形如 “Edge tagged AMBIGUOUS (relation: …) - confidence is low.” 的复核问题。相关行为有测试覆盖，见 tests/test_confidence.py 与 tests/test_inferred_confidence_rubric.py。

四、安装：graphifyy 包与多平台注册

前置要求与安装命令

要求：Python 3.10+，以及上述任一 AI 助手平台之一。

# 推荐 — Mac 和 Linux 上无需配置 PATH 即可工作
uv tool install graphifyy && graphify install
# 或用 pipx
pipx install graphifyy && graphify install
# 或普通 pip
pip install graphifyy && graphify install

俄语 README 特别强调：PyPI 官方包名是 graphifyy（双 y），通过 pip install graphifyy 安装；PyPI 上其他 graphify* 包均与本项目无关。若使用 uvx/uv tool run 而不安装，要写包名而非命令：uvx --from graphifyy graphify install（因为 uv tool run 把第一个词当包名解析，uvx graphify … 会报 “No solution found”）。另外，若装完提示 graphify: command not found，是 uv/pipx 的 bin 目录（~/.local/bin）不在 PATH 上，执行 uv tool update-shell 或 pipx ensurepath 后重开终端即可。

平台支持表（完整继承自俄语 README）

平台	安装命令
Claude Code (Linux/Mac)	graphify install
Claude Code (Windows)	graphify install（自动识别）或 graphify install --platform windows
Codex	graphify install --platform codex
OpenCode	graphify install --platform opencode
GitHub Copilot CLI	graphify install --platform copilot
VS Code Copilot Chat	graphify vscode install
Aider	graphify install --platform aider
OpenClaw	graphify install --platform claw
Factory Droid	graphify install --platform droid
Trae	graphify install --platform trae
Trae CN	graphify install --platform trae-cn
Gemini CLI	graphify install --platform gemini
Hermes	graphify install --platform hermes
Kiro IDE/CLI	graphify kiro install
Cursor	graphify cursor install
Google Antigravity	graphify antigravity install

然后打开 AI 助手输入 /graphify . 即可。注意：Codex 用 $ 而不是 /，所以要输入 $graphify .。

让助手始终优先查图（推荐的一次性配置）

建好图后，在项目中执行一次对应命令，写入“优先用 graphify query 回答代码库问题、而不是读整个报告或 grep 原始文件”的指令：

平台	命令
Claude Code	graphify claude install
Codex	graphify codex install
OpenCode	graphify opencode install
Cursor	graphify cursor install
Gemini CLI	graphify gemini install
Kiro IDE/CLI	graphify kiro install
Google Antigravity	graphify antigravity install

从源码结构看，这类“always-on”机制按平台分两种实现：钩子型平台（如 Claude Code）在搜索/读文件类工具调用前触发 hook 提示；指令文件型平台（Codex、OpenCode、Cursor 等）写入 AGENTS.md、.cursor/rules/ 等持久指令文件。英文 README 还说明 Codex 的 PreToolUse hook 被刻意设为 no-op（其 Desktop 版本拒绝该输出），真正起作用的是 AGENTS.md。

五、实战：/graphify 命令族与常用参数

以下命令块完整继承自俄语 README 的 “Использование” 一节，并与 graphify/cli.py 的参数解析实现核对：

/graphify                          # 当前目录
/graphify ./raw                    # 指定文件夹
/graphify ./raw --mode deep        # 更激进的 INFERRED 边提取
/graphify ./raw --update           # 只重新提取变更过的文件
/graphify ./raw --directed         # 有向图
/graphify ./raw --cluster-only     # 在现有图上重跑聚类
/graphify ./raw --no-viz            # 不生成 HTML，只出报告 + JSON
/graphify ./raw --obsidian         # 生成 Obsidian 库（opt-in）

/graphify add https://arxiv.org/abs/1706.03762   # 抓取一篇论文
/graphify add <video-url>                         # 下载音频、转写并加入

/graphify query "Attention 和优化器之间有什么联系？"
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"

graphify hook install              # 安装 Git 钩子
graphify update ./src              # 重新提取代码文件，无需 LLM
graphify watch ./src               # 代码变更时自动更新图谱

关键参数在源码中的行为：

• --directed / --undirected 互斥：graphify/cli.py 中两者同时出现会直接报错 “--directed and --undirected are mutually exclusive”。有向图保留边的方向，无向模式用于 Leiden/Louvain 这类要求无向输入的聚类算法（cluster.py 注释亦确认聚类前会内部转换）。
• --update：增量更新，依赖 SHA256 缓存跳过未变文件，只重跑有变化的部分；这是“重跑只处理变更文件”承诺的实现基础。
• --cluster-only：不重新提取，只在现有 graph.json 上重跑聚类，可配合 --resolution 调粒度、--no-viz 跳过 HTML。
• --no-viz：graphify/cli.py 中显式尊重该标志，跳过 graph.html 生成，保留 GRAPH_REPORT.md 和 graph.json——英文 README 建议在超过 5000 节点、HTML 打不开时用它。
• query / path / explain：对图而不是文件提问。path 返回两节点间最短路径，explain 返回节点的来源文件行号、所属社区、度数及全部连接边（每条边带关系动词与置信标签）。实际效果可参考 docs/demo-path.svg 展示的路径查询，以及英文 README 中 graphify explain "APIRouter" 的真实输出样例。

增量更新的缓存机制在 graphify/cache.py 有清晰实现：指纹是“文件内容 SHA256 + 相对路径”，缓存以 graphify-out/cache/{kind}/{hash}.json 落盘（见 graphify/cache.py），测试覆盖见 tests/test_cache.py。

六、输出物：graphify-out/ 目录与 GRAPH_REPORT.md

每次运行你得到（完整继承自俄语 README 的输出结构说明）：

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

GRAPH_REPORT.md 的内容构成（README “Что вы получаете” 一节，逐项对应源码能力）：

• 神节点（God nodes）——度数最高的概念，一切连接都经过它们；
• 意外连接（Surprising connections）——跨文件/模块的边，按复合分排序，代码-文章交叉边权重更高；
• “为什么”——docstring、内联注释（# NOTE:、# IMPORTANT:、# HACK:、# WHY:）与文档中的设计理由，被提取为 rationale_for 节点挂到相应代码上；
• 建议问题——4 到 5 个该图谱独有能力的可回答之问；
• 置信度评分——每条 INFERRED 边都有 confidence_score（0.0–1.0）；
• token 基准——每次运行自动输出，混合语料下为 71.5 倍节省；
• 自动同步（--watch）与 Git 钩子（graphify hook install 安装 post-commit / post-checkout 钩子，提交与切分支后自动重建图）。

graph.json 本身采用 NetworkX node-link 格式：每个节点带 id、label、file_type（code/document/paper/image/rationale）、source_file；每条边带 source、target、relation（动词短语，如 calls、imports、implements、semantically_similar_to）、confidence、confidence_score（仅 INFERRED）、source_file，见 docs/how-it-works.md。仓库内可直接查阅真实产物：worked/httpx/graph.json、worked/mixed-corpus/GRAPH_REPORT.md、worked/rsl-siege-manager/（含 graph.html 与 manifest.json）。

七、文件排除：.graphifyignore

在项目根目录创建 .graphifyignore，语法与 .gitignore 相同（支持 ! 取反）：

# .graphifyignore
vendor/
node_modules/
dist/
*.generated.py

实现细节可从源码确认：graphify/detect.py 按 gitignore 规范逐行解析，并在同一目录中先读 .gitignore、再读 .graphifyignore——因此 .graphifyignore 的模式最后求值、冲突时获胜，它只会排除更多文件，绝不会把 .gitignore 已排除的文件重新包含回来；子目录作用域与 git 相同，忽略文件只影响自身子树。英文 README 补充：需要把被 git 忽略的生成代码纳入图谱时，可用 graphify extract --no-gitignore 关闭 .gitignore/.git/info/exclude（.graphifyignore 仍然生效）。

八、隐私与数据边界

俄语 README 的隐私说明（与源码行为一致）：

• graphify 会把文件内容发送到你的 AI 助手所连的模型 API，用于文档、文章、图像的语义提取；
• 代码文件例外：完全在本地经 tree-sitter AST 处理，不出机器；纯代码语料可以零 API key 离线建图（graphify extract 可加 --code-only 只索引代码）；
• 视频/音频在本地经 faster-whisper 转写，不出机器；
• 无遥测、无使用跟踪、无分析。

九、技术栈与仓库内可继续深入的入口

俄语 README 给出的技术栈：NetworkX + Leiden（graspologic）+ tree-sitter + vis.js；语义提取经由 Claude、GPT-4 或你所在平台的模型；视频转写经 faster-whisper + yt-dlp（可选）。

围绕本文各主题，仓库中可继续深入的材料：

主题	入口
三趟管线、Leiden、置信度评分标准、token 基准	docs/how-it-works.md
模块划分、如何新增语言	ARCHITECTURE.md
聚类实现（Leiden/Louvain、resolution、超大社区切分）	graphify/cluster.py
神节点、意外连接、建议问题的打分逻辑	graphify/analyze.py
.gitignore/.graphifyignore 解析与合并	graphify/detect.py
SHA256 内容指纹缓存	graphify/cache.py
语言检测	tests/test_detect.py、tests/test_languages.py
聚类与置信度测试	tests/test_cluster.py、tests/test_confidence.py、tests/test_inferred_confidence_rubric.py
真实语料输入/输出样本	worked/httpx/、worked/mixed-corpus/、worked/karpathy-repos/
技能文件生成器（各平台 SKILL.md 的来源）	tools/skillgen/gen.py

十、小结

graphify 的设计取舍可以浓缩为三条：代码结构提取走本地确定性 AST（免费、离线、可复现），语义层才交给 LLM；聚类完全依赖图拓扑 + 语义边，省掉了 embedding 与向量库这一整套基础设施；每条边携带 EXTRACTED/INFERRED/AMBIGUOUS 标签和离散置信分，让“读到的”与“猜的”永远可区分。配合 SHA256 增量缓存、--watch 自动同步与 Git 钩子，图谱能以接近零的边际成本持续跟随代码库演进——这正是“查询时比读原始文件省 71.5 倍 token”这一数字背后的工程逻辑。