Graphify 实战指南：把代码库、文档与多媒体变成可查询知识图谱

Graphify 是一款面向 AI 编码助手的 /graphify 技能：在 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Kiro、Google Antigravity 等助手中输入一条命令，它就能读取一个文件夹中的代码、文档、PDF、图片乃至音视频，构建出一张可持久查询的知识图谱。本文以该仓库的葡萄牙语版 README（docs/translations/README.pt-BR.md）为主体，逐节还原其安装、配置与命令体系，并结合仓库源码（graphify/extract.py、graphify/cache.py、graphify/cluster.py、graphify/analyze.py 等）解释三遍处理流水线的底层实现与"无向量库、无嵌入"的聚类设计原理。读完本文，你可以独立完成：从安装注册技能到增量更新、Git 钩子同步、以及用 query/path/explain 对图谱做自然语言查询的完整工作流。

一、Graphify 是什么：一条命令生成可查询的知识图谱

Graphify 的核心定位（引自 docs/translations/README.pt-BR.md）：

• 一条命令：在任意目录执行 /graphify .——你的代码、笔记、论文，全部可以进图。
• 完全多模态：除代码外，还可以加入 PDF、markdown、截图、架构图、白板照片、其他语言的照片，甚至音视频文件。graphify 从所有这些素材中提取概念与关系，并连接到同一个图。
• 本地确定性解析：代码文件完全由 tree-sitter AST 在本地解析，不经过 LLM，没有任何内容离开你的机器；只有文档、论文、图片的"语义抽取"这一遍会调用你助手所配置的大模型。
• 可持久化：生成的 graph.json 是持久图谱，几周之后直接查询即可，不需要重新读文件。
• 诚实的证据边界：每条边都标注它是"直接从源码读出来的"（EXTRACTED）还是"推断出来的"（INFERRED）。

文档中引用了一个典型场景：Andrej Karpathy 习惯维护一个 /raw 文件夹，随手堆放论文、推文、截图和笔记。graphify 正是为这类素材而生——在混合语料上，文档给出的实测数据是每次查询比直接读原始文件少 71.5 倍 token，且图谱在会话之间持久存在。

1.1 输出物：graphify-out 目录

执行 /graphify . 后，项目根目录会生成 graphify-out/，其中包含四个关键部分：

graphify-out/
├── graph.html       交互式图谱——在任意浏览器中打开，可点击节点、搜索
├── GRAPH_REPORT.md  审计报告——神节点、意外连接、建议问题
├── graph.json       持久化图谱——数周之后直接查询，无需重读文件
└── cache/           SHA256 文件缓存——重复运行时只处理被修改过的文件

其中 graph.json 是后续所有 query/path/explain 命令的数据源；cache/ 则支撑增量更新（--update）只重抽已变更文件的能力。缓存的具体结构在 graphify/cache.py 中实现，详见第 9.4 节。

1.2 排除文件：.graphifyignore

在项目中放置一个 .graphifyignore 即可排除不希望进图的目录或文件，语法与 .gitignore 完全相同（包括 ! 取反规则）：

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

补充两个来自英文主 README（README.md）的要点：

1. .gitignore 会被自动读取。如果同时存在 .graphifyignore，两份规则会合并，且 .graphifyignore 的优先级更高（后评估）；
2. 若被 git 忽略的生成代码/转译代码恰恰需要进图，可在 graphify extract 时传 --no-gitignore，此时 .gitignore 与 .git/info/exclude 失效，但 .graphifyignore 仍然生效。

二、工作原理：三遍处理流水线

docs/translations/README.pt-BR.md 对处理流程的描述是"graphify runs in three passes（三遍执行）"。结合仓库源码，三遍分别落在不同的模块中：

第一遍：确定性 AST 结构提取（无 LLM）

用 tree-sitter 对代码文件做确定性 AST 解析，提取：

• 类、函数等结构定义；
• import 关系与跨文件调用图（calls / imports / inherits）；
• docstring 与内联"理由"注释（# NOTE:、# IMPORTANT:、# HACK:、# WHY:）。

这一遍对应 graphify/extract.py（模块自述："Deterministic structural extraction from source code using tree-sitter"）以及 graphify/extractors/ 下的逐语言解析器目录。

第二遍：音视频本地转录

视频与音频文件使用 faster-whisper 在本地转录为文本，随后按普通文档进入后续抽取。实现见 graphify/transcribe.py：

• 支持 .mp4 .mov .webm .mkv .avi .m4v .mp3 .wav .m4a .ogg 等格式，也支持直接传入视频 URL（通过 yt-dlp 下载）；
• 默认使用 base 模型，可用环境变量 GRAPHIFY_WHISPER_MODEL 覆盖；
• 缺少依赖时会给出具体的安装提示（pip install 'graphifyy[video]'），而不是静默失败。

第三遍：语义概念抽取（并行 LLM 子代理）

由 Claude 等模型的子代理（subagent）并行处理文档、论文、图片与转录文本，抽取概念、关系与设计理由，最终与前两遍的结果合并成一张 NetworkX 图，再经社区检测分组，导出为：

• graph.html（交互式可视化，vis.js）；
• graph.json（可查询的持久图谱）；
• GRAPH_REPORT.md（自然语言审计报告）。

合并与校验逻辑集中在 graphify/build.py，图谱分析（神节点、意外连接、建议问题）在 graphify/analyze.py，HTML 导出在 graphify/exporters/html.py。

2.1 聚类基于图拓扑——没有 embedding

文档特别强调这一设计决策："clustering is based on graph topology — no embeddings"。具体而言：

• Leiden 算法按边密度发现社区，结构本身就是相似性信号；
• 语义相似边（semantically_similar_to，由 LLM 抽出并标记为 INFERRED）已经存在于图中，直接参与聚类；
• 因此不需要单独的 embedding 步骤，也不需要向量数据库。

这一点在 graphify/cluster.py 中得到印证：模块自述为"Uses Leiden (graspologic) if available, falls back to Louvain (networkx). Splits oversized communities."——优先调用 Leiden（含绕过 graspologic 进度条转义序列的原生调用路径），不可用时回退到 networkx 内置的 Louvain；对于超大社区还会二次 Leiden 递归拆分（见 run_community_detection 附近的注释）。resolution 参数控制社区粒度：大于 1.0 得到更多、更小的社区。

2.2 边的置信度标签

每条边都有明确的来源标记（这一机制遍布各解析器与合并逻辑，如 graphify/extract.py、graphify/build.py）：

标签	含义
EXTRACTED	在源文件中直接找到（如显式 import、方法调用）
INFERRED	合理推断得出，附带 0.0–1.0 的 confidence_score
AMBIGUOUS	存在歧义，标记待人工复核

graphify/build.py 中有一段专门的规范化逻辑：将 LLM 输出的 type 归一为 relation，并在存在 confidence 但缺失 confidence_score 时自动补齐浮点分值——这正是文档所说"每条 INFERRED 边都有 confidence_score"的实现基础。

三、安装与平台支持

3.1 前置要求与安装

要求：Python 3.10+（pyproject.toml 中声明为 requires-python = ">=3.10"，当前包版本 0.9.52），以及下列任一 AI 编码助手：Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Kiro、Hermes 或 Google Antigravity。

推荐安装方式（Mac 与 Linux 上无需手动配置 PATH）：

# 推荐——隔离环境，无需配置 PATH
uv tool install graphifyy && graphify install
# 或使用 pipx
pipx install graphifyy && graphify install
# 或直接用 pip
pip install graphifyy && graphify install

官方包提醒：PyPI 上的官方包名是 graphifyy（双 y，安装命令 pip install graphifyy），但 CLI 命令仍叫 graphify。PyPI 上其他名为 graphify* 的包均与本项目无关。

3.2 平台安装命令矩阵

不同平台对应不同的注册命令（完整继承自原文档的平台表）：

平台	安装命令
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 .。英文主 README 中还列有 CodeBuddy、Kilo Code、Kimi Code、Amp、Pi、Devin CLI 等 20+ 平台的安装项，安装入口实现在 graphify/install.py。

四、让助手始终查询图谱（推荐配置）

构建好图谱后，建议在项目中再执行一次"always-on"安装，让助手遇到代码库问题时优先查询图谱而不是逐个读文件或直接 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

其原理（结合 README.md 与 graphify/always_on/ 目录下的平台规则模板）：该命令会写入一小段平台配置/指令文件（如 AGENTS.md、.cursor/rules/、Claude Code 的 PreToolUse 钩子等），指示助手优先执行 graphify query "<question>" 这类作用域查询，而不是通读报告或裸读源码。graphify-out/GRAPH_REPORT.md 仍然保留，用于全局性的架构审阅。

五、完整命令参考

以下命令集合完整继承自 docs/translations/README.pt-BR.md，覆盖构建、查询、增量与同步四类场景：

/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 vault（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 hooks（post-commit / post-checkout）
graphify update ./src              # 无 LLM，仅重新抽取代码文件
graphify watch ./src               # 代码变更时自动更新图谱

补充说明：

• --cluster-only 可配合 --resolution 1.5（更细粒度社区）与 --exclude-hubs 99（在神节点排名中抑制工具型超级枢纽）使用；
• --directed 对应 NetworkX 有向图模式，适合需要方向语义（谁调用谁）的场景；
• graphify update ./src 只跑第一遍 AST 路径，不消耗任何 LLM token，这是它与 /graphify --update（同时刷新文档/PDF/图片节点）的关键区别。

六、你会得到什么：报告中的六类产出

1. 神节点（God nodes）——度数最高的概念，即"一切都经过的地方"。实现在 graphify/analyze.py 的 god_nodes(G, top_n=10)：按连接度排名，返回度数最高的概念列表。

2. 意外连接（Surprising connections）——跨文件/跨模块的链接，按复合评分排序；代码—论文之间的边得分更高。每条结果附带一句自然语言解释"为什么这条边值得关注"。graphify/analyze.py 中的评分逻辑会累加多个信号：跨社区结构距离（Leiden 认为两者在结构上相距很远）、外围节点连向枢纽（低度节点触达神节点）等；semantically_similar_to 这类真正的跨边界洞察会被排除出"噪声"，保留为高价值发现。

3. 建议问题（Suggested questions）——图谱"独有资格回答"的 4–5 个问题。同一模块中的知识缺口分析会基于 AMBIGUOUS 边、桥节点、未被充分探索的神节点与孤立节点生成验证性问题。

4. "为什么"（Rationale）——docstring、内联注释（# NOTE:、# IMPORTANT:、# HACK:、# WHY:）以及文档中的设计理由，都会被抽取为独立的 rationale_for 节点并链接到它所解释的代码。在 graphify/extract.py 中可以看到 "relation": "rationale_for" 的边构造逻辑。

5. 置信度评分——每条 INFERRED 边都带 0.0–1.0 的 confidence_score，构建期由 graphify/build.py 统一规范化。

6. Token 基准——每次运行结束自动打印。文档给出的混合语料实测：每次查询比读原始文件少 71.5x token。基准脚本见 graphify/benchmark.py。

此外还有两项自动化能力：

• 自动同步（--watch）：代码变化时自动更新图谱，实现在 graphify/watch.py；
• Git hooks（graphify hook install）：安装 post-commit 与 post-checkout 钩子，提交/切分支后自动重建（仅 AST，无 API 成本），实现在 graphify/hooks.py。

七、隐私与数据驻留

原文档的隐私声明非常明确，逐条对应到实现：

素材类型	处理方式
代码文件	本地 tree-sitter AST 解析，不离开你的机器；纯代码语料甚至不需要任何 API key（graphify extract 可完全离线）
视频/音频	本地 faster-whisper 转录，不离开你的机器
文档/PDF/图片	内容会发送给你 AI 助手的模型 API，用于语义抽取

同时文档强调：无遥测、无使用追踪、无分析统计。若代码有数据驻留要求，英文主 README 还建议显式指定 --backend ollama（完全本地）或其他受控后端。

八、技术栈与依赖声明

文档给出的技术栈为：NetworkX + Leiden（graspologic）+ tree-sitter + vis.js；语义抽取走 Claude、GPT-4 或你所用平台的模型；视频转录走 faster-whisper + yt-dlp（可选）。

对照 pyproject.toml 的依赖声明，可以看到具体边界：

• 核心依赖：networkx>=3.4、numpy、rapidfuzz，以及 20 余个 tree-sitter 语法包（python、javascript、typescript、go、rust、java、groovy、c、cpp、ruby、c-sharp、kotlin、scala、php、swift、lua、zig、powershell、elixir、objc、julia、verilog、fortran、bash、json），对应文档所称"25 种编程语言通过 tree-sitter AST 支持"；
• 可选依赖组（extras）：pdf（pypdf + markdownify）、office（.docx/.xlsx）、video（faster-whisper + yt-dlp，需 Python 3.11+）、mcp（MCP stdio 服务器）、neo4j、falkordb（图数据库推送）、svg、leiden（graspologic，仅 Python < 3.13）、ollama、openai、sql、postgres、terraform、pascal、ocaml、commonlisp 等，按需以 uv tool install "graphifyy[extras]" 安装。

九、源码级深挖：三遍流水线如何落地

9.1 第一遍：按语言分派的提取器注册

graphify/extract.py 顶部集中导入了 graphify/extractors/ 下的全部语言解析器（rust、go、csharp、dart、sql、terraform、verilog、zig、commonlisp……），并通过 resolver_registry（graphify/resolver_registry.py）的"语言解析器注册表"机制，在通用 AST 提取之外挂接各语言的符号解析钩子（如 Ruby 成员调用、C# 接口分派、Pascal 继承调用解析）。这种"提取器 + 解析器"的两层结构，正是跨文件 calls/imports/inherits 边能跨越数十种语言成立的原因。

9.2 第二遍：本地转录的健壮性

graphify/transcribe.py 的关键设计：

• 依赖缺失时抛出可操作的错误信息（直接提示 pip install 'graphifyy[video]'），而不是静默跳过；
• 转录文本落在 graphify-out/transcripts/ 目录，作为中间产物可复查；
• 模型选择通过环境变量 GRAPHIFY_WHISPER_MODEL 覆盖，默认 base，在精度与速度间取平衡。

9.3 第三遍与聚类：Leiden 优先、Louvain 兜底、超大社区递归拆分

graphify/cluster.py 的调用链是：

1. 优先直接调用 graspologic_native.leiden()（绕过 graspologic 封装层的进度条与 ANSI 转义序列）；
2. 失败则回退到 graspologic.partition.leiden；
3. 再失败则回退到 networkx 的 Louvain；
4. resolution > 1.0 产生更多更小的社区；孤立节点被单独处理（Leiden 会告警并丢弃孤立点）；
5. 超大社区在子图上再跑一次 Leiden 递归拆分。

这与文档"Leiden finds communities by edge density（Leiden 按边密度发现社区）"的表述一一对应。graphify/analyze.py 中"cross-community bonus"（跨社区加分）正是消费聚类结果的下游：结构上相距越远的两个节点连了边，这条边在"意外连接"评分中得分越高。

9.4 缓存策略：AST 缓存按版本命名空间，语义缓存不失效

docs/translations/README.pt-BR.md 说 cache/ 是"SHA256 缓存，重跑只处理已修改文件"。graphify/cache.py 中的注释揭示了更精细的设计：

• AST 缓存按包版本与缓存 schema 双命名空间（cache/ast/v{version}-s{schema}/）：AST 条目是 graphify 自己提取器代码的产物，若只按文件内容做键，新版本中修复的提取逻辑会继续吐出旧版的错误结果。因此升级 graphify 后，旧版本目录会被清理，未命中缓存、保证用新提取器重算；
• 语义缓存刻意不按版本失效：语义条目是 LLM 基于文件内容生成的，若每次发版都失效，未修改的文件将被重复计费抽取。

这一"AST 缓存版本敏感、语义缓存内容敏感"的分治策略，是 --update 增量更新既正确又省 token 的关键。

十、验证与延伸阅读

• 报告内容的正确性测试：tests/test_analyze.py、tests/test_report.py；
• 聚类与社区标签测试：tests/test_cluster.py、tests/test_community_hub_labels.py；
• 置信度与 INFERRED 边评分测试：tests/test_confidence.py、tests/test_inferred_confidence_rubric.py；
• 边标签（EXTRACTED/INFERRED/AMBIGUOUS）的契约测试：tests/test_id_normalization_contract.py 与 tests/test_validate.py；
• 增量更新与 mtime 冲突测试：tests/test_incremental.py、tests/test_incremental_mtime_collision.py；
• 更多葡语读者可对照 docs/translations/README.pt-BR.md 与英文原版 README.md 交叉阅读；深度原理可参考 docs/how-it-works.md。

小结：graphify 的价值不在于"又一套索引"，而在于把代码结构（tree-sitter 确定性 AST）、人类意图（注释与理由节点）和外部知识（文档、论文、音视频转录）编织进同一张可遍历、可审计、无向量库的图。/graphify . 是起点，query/path/explain 是日常，--update 与 Git hooks 让它始终新鲜——这正是"图谱即索引、结构即相似性"这一设计哲学的完整落地。