graphify：为 AI 编码助手构建可查询的知识图谱——/graphify 技能的安装、使用与三阶段管线原理

graphify 是一个面向 AI 编码助手（Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot 等）的 /graphify 技能，它通过本地确定性的 tree-sitter AST 解析，把代码库连同其文档、SQL 模式、配置文件和 PDF 一起转化为可查询的知识图谱，且每条边都带有可解释的置信度标签，不依赖向量数据库。本文完整覆盖 graphify 的安装方式、全平台支持矩阵、日常使用命令与产物结构，并结合仓库源码（cluster.py、pyproject.toml、skill.md 等）解释其三阶段管线的底层实现，读完你可以独立在任意项目中完成"安装—建图—查询—增量更新"的完整闭环。

定位：用图谱查询替代 grep

graphify 的核心主张是：当代码库足够复杂时，与其让助手逐个读文件或 grep，不如先把整个项目（代码、文档、PDF、图片、视频）映射成一张可遍历的图，然后直接对图提问。它完全多模态——除了代码，还可以加入 PDF、markdown、屏幕截图、架构图、白板照片、其他语言的图片、视频和音频，graphify 会从这些材料中抽取概念和关联，合并到同一张图中。其中视频通过 faster-whisper 在本地转写，并使用从你的语料中提取的领域专用提示词。代码侧则由 tree-sitter AST 支持约 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 等，具体以 pyproject.toml 中声明的 tree-sitter 语法包为准）。

用法本身只有一个入口命令：

/graphify .    # 对任意文件夹生效——代码、笔记、论文，全部支持

从 skill.md 中可以看到该命令背后封装了完整的构建管线：先检测语料、再抽取代码结构、再对文档/媒体做语义抽取、最后合并、聚类并导出产物。技能文件还定义了一条"快路径"：若 graphify-out/graph.json 已存在且用户只是提了一个自然语言问题，助手会跳过重新构建，直接执行 graphify query "<问题>" 对已有图查询。

产物：graphify-out/ 目录结构

一次构建完成后，你在项目根目录得到 graphify-out/ 目录，包含四类产物：

graphify-out/
├── graph.html       交互式图谱——浏览器中打开，可点节点、搜索、过滤
├── GRAPH_REPORT.md  高亮报告：god 节点、意外关联、建议提问
├── graph.json       持久化图谱——数周之后无需重读文件即可继续查询
└── cache/           SHA256 缓存——增量重跑只处理变更过的文件

各产物的作用：

• graph.html：基于 vis.js 的力导向交互式图谱，社区以颜色区分，节点可点击、可搜索、可过滤；
• GRAPH_REPORT.md：自然语言审计报告，包含 god 节点、意外关联、建议提问（见下文"你会得到什么"）；
• graph.json：持久化的完整图，是 graphify query / path / explain 的数据源；
• cache/：基于文件内容 SHA256 的提取缓存，保证 --update 增量模式只重新处理变化文件。

用 .graphifyignore 排除目录

构建前可以在项目根目录添加 .graphifyignore 文件来排除不想入图的目录和文件：

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

其语法与 .gitignore 相似。从 detect.py 的源码可以看到具体解析行为：

• .graphifyignore 按 gitignore 规范逐行解析，支持目录前缀与 glob 模式；
• 每个目录下的 .gitignore 和 .graphifyignore 会被合并读取，其中 .gitignore 先读、.graphifyignore 后读，因此添加 .graphifyignore 只会"排除更多"，永远不能重新纳入已被排除的路径；
• CLI 层还提供 --no-gitignore 选项（跳过 .gitignore 和 .git/info/exclude，以 .graphifyignore 为最高优先级），可用 graphify --help 查看。

三阶段管线：AST 本地抽取 → 本地转写 → 并行语义抽取

官方描述中，graphify 分三个阶段工作：

1. 确定性的 AST 阶段（无 LLM）：tree-sitter 从代码文件中抽取结构——类、函数、import、调用图、docstring 和"为什么"注释。整个阶段纯本地运行，没有任何内容离开你的机器；
2. 音视频转写阶段：视频和音频文件通过 faster-whisper 在本地转写为文字；
3. 语义抽取阶段：Claude subagent 对文档、论文、图片和转写文本并行工作，抽取概念、关联与设计理由（rationale）。

三类结果合并进 NetworkX 图，再用 Leiden 社区检测算法聚类，最终导出为交互式 HTML、可查询的 JSON 与自然语言审计报告。

聚类基于图拓扑，而非 embedding

这是一个关键的架构决策：聚类完全基于图的拓扑结构，不使用任何 embedding。Leiden 算法按边密度发现社区；而语义相似性本身已经被建模在图里——Claude 抽取的语义相似边（semantically_similar_to，标记为 INFERRED）已经是图的边之一。"图结构本身就是相似性信号"，因此不需要额外的 embedding 阶段或向量数据库。

从 cluster.py 的实现可以看到这条声明是真实的：模块 docstring 直接写明"Uses Leiden (graspologic) if available, falls back to Louvain (networkx). Splits oversized communities. Returns cohesion scores"。实际调用链是一个三级降级策略：

• 优先直接调用 graspologic_native.leiden()（Rust 原生扩展）。源码注释解释了这个绕开 graspologic 包导入的做法：包级导入会连带拉起 umap/pynndescent 的 numba JIT 编译，实测多花 7–19 秒导入成本，而原生调用只需约 1 秒；
• 原生扩展不可用或输入图不满足约束（有向图/多重图/节点字符串冲突）时，回落到 graspologic.partition.leiden；
• graspologic 整体缺失时（例如 pyproject.toml 中 leiden extra 声明为 graspologic; python_version < '3.13'，Python 3.13 下未安装），最终回落到 networkx 内置的 Louvain 社区检测。

同时该模块还实现了超大社区拆分（splits oversized communities）并计算每个社区的凝聚度分数（cohesion scores），供 GRAPH_REPORT.md 使用。

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

图中每条关联都被打上三类标签之一：

标签	含义
EXTRACTED	在源码中被直接找到（如 import 语句、显式调用）
INFERRED	由 graphify 的符号解析推断得出，附带置信度评分
AMBIGUOUS	被标记出来等待人工审查

这套标签贯穿整个仓库：从各语言提取器（extractors/ 下的 go.py、rust.py、csharp.py 等）到 extract.py、report.py 的汇总逻辑都有体现。标签的价值在于让你能一眼区分"直接从源码读到的"和"推断出来的"，这对审计图谱结论至关重要。

安装

前置要求：Python 3.10+（pyproject.toml 中 requires-python = ">=3.10"），以及以下任一 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
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* 命名的包与本项目无关。当前仓库版本见 pyproject.toml 中的 version 字段。

PATH 排障：uv tool install / pipx install 会把 graphify 放进工具 bin 目录（如 ~/.local/bin），若安装后找不到命令，执行 uv tool update-shell（或 pipx ensurepath）后重开终端；普通 pip 安装则需自行将该目录加入 PATH，或改用 python -m graphify 运行。

平台支持矩阵

平台	安装命令
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 .；PowerShell 下前导斜杠是路径分隔符，应使用 graphify .。

安装时默认写入用户主目录；若要装到当前项目（仓库级技能），可加 --project 标志，例如 graphify install --project --platform codex，产物会落在如 .claude/skills/graphify/SKILL.md、.agents/skills/graphify/SKILL.md 等位置，并附一个按需加载的 references/ 侧车目录。

强制助手优先使用图谱（推荐）

图谱构建完成后，建议在项目中执行一次对应平台的"always-on"安装，让助手在会话中优先走 graphify query 而不是直接读文件：

平台	命令
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

从 skill.md 的"Fast path"规则可以看到其机制：always-on 规则要求助手在执行任何子命令前先检查 graphify-out/graph.json 是否存在，若存在且用户只是提问，则跳过全部重建步骤直接查询图谱。

使用：命令与参数全集

/graphify                          # 当前目录
/graphify ./raw                    # 指定文件夹
/graphify ./raw --mode deep        # 更激进地抽取 INFERRED 边
/graphify ./raw --update           # 只重新抽取新增/变更的文件
/graphify ./raw --directed         # 构建有向图（保留 source→target 方向）
/graphify ./raw --cluster-only     # 对已有图谱重新聚类
/graphify ./raw --no-viz           # 跳过 HTML 可视化，只产出报告 + JSON
/graphify ./raw --obsidian         # 生成 Obsidian vault（可选）

/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               # 图谱自动更新

各参数的源码级含义（与 skill.md 中的说明一致）：

• --mode deep：要求助手向每个语义抽取 subagent 传递 DEEP_MODE=true，做更彻底的抽取、产出更丰富的 INFERRED 边；
• --update：增量模式，依赖 manifest 与 SHA256 缓存，只重新抽取新增或变更文件（manifest 中 all_files 记录完整语料，files 记录本次变更集，且 manifest 使用相对路径以便跨机器/克隆迁移）；
• --directed：构建时以 directed=True 传入 build_from_json()，产出保留边方向的 DiGraph 而非默认的无向 Graph；
• --cluster-only：不重新抽取，只对已有 graph.json 重跑 Leiden 聚类；
• --no-viz：跳过 graph.html 生成，只产出 GRAPH_REPORT.md 与 graph.json；
• --obsidian [--obsidian-dir <path>]：按节点逐个生成 Obsidian markdown vault，默认写入 graphify-out/obsidian，可用 --obsidian-dir 指向已有 vault；
• --watch：监听文件夹，代码变更时自动重建图谱（纯代码路径，不需要 LLM），底层依赖 watch.py 与 watchdog 可选依赖。

查询侧三个命令：graphify query "<自然语言问题>" 返回一个作用域子图；graphify path "A" "B" 追踪两个概念之间的最短路径；graphify explain "<概念>" 给出节点详情（来源文件与行号、所属社区、度数）及全部连接边及其标签。

你会得到什么

• God 节点——连接度最高的概念，所有东西都流经它们；
• 意外关联——按组合评分排序，代码—论文之间的边会被赋予更高权重，每条结果附自然语言的"为什么"解释；
• 建议提问——图谱能够单独回答的 4–5 个问题；
• "为什么"（rationale）——docstring、内部注释（# NOTE:、# IMPORTANT:、# HACK:、# WHY:）以及文档中的设计理由，被抽取为一等公民的 rationale_for 节点并与代码相连；
• 置信度评分——每条 INFERRED 边携带 confidence_score（0.0–1.0）；
• Token 基准——每次运行后自动输出。在混合语料上，查询一次比直接读原始文件少 71.5 倍 token（该数字来自项目自报的 token benchmark，适用前提是其混合语料测试集）；
• 自动同步（--watch）——代码变更时自动更新图谱；
• Git 钩子（graphify hook install）——安装 post-commit 与 post-checkout 钩子。钩子脚本在安装时嵌入当前解释器的绝对路径，因此在 ~/.local/bin 不在 PATH 的 GUI git 客户端和 CI 环境中也能正确触发；升级 graphify 后需重新执行 graphify hook install 刷新路径。

隐私与数据边界

graphify 的数据流划分非常清晰：

• 文档、论文、图片：语义抽取会把文件内容发送到你所用 AI 助手的模型 API；
• 代码文件：tree-sitter AST 本地解析，完全不经过 LLM，内容不出机器；
• 视频/音频：faster-whisper 本地转写；
• 遥测：无任何遥测或使用跟踪。

也就是说，如果只跑代码路径（graphify update ./src 这类命令），整个过程可以做到零外部调用。

技术栈与可选依赖

核心栈：NetworkX + Leiden (graspologic) + tree-sitter + vis.js。语义抽取走 Claude、GPT-4 或你所用平台的模型；视频转写走 faster-whisper + yt-dlp（可选）。

从 pyproject.toml 可以看到基础依赖与按功能划分的可选 extra：

Extra	提供能力	安装方式
pdf	PDF 抽取（pypdf + markdownify）	uv tool install "graphifyy[pdf]"
video	faster-whisper（需 Python 3.11+）+ yt-dlp	"graphifyy[video]"
leiden	graspologic 原生 Leiden（Python 3.13 以下）	"graphifyy[leiden]"
watch	watchdog 文件监听（--watch）	"graphifyy[watch]"
sql	tree-sitter-sql 语法	"graphifyy[sql]"
mcp	MCP/HTTP 服务（graphify-mcp 入口）	"graphifyy[mcp]"
postgres	从 Postgres 重建 DDL 入图	"graphifyy[postgres]"
neo4j / falkordb	图数据库导出	"graphifyy[neo4j]" 等
office	docx/xlsx 支持	"graphifyy[office]"

基础依赖中已内置约 27 个 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），另加 networkx、numpy、rapidfuzz；而 Pascal、OCaml、Common Lisp、Terraform(HCL)、DM 等小众语言语法因体积或平台轮子限制被放到对应 extra 中，按需安装。

深入源码：值得进一步阅读的文件

• graphify/cluster.py——Leiden 三级降级（graspologic_native → graspologic → networkx Louvain）、超大社区拆分与凝聚度计算；
• graphify/detect.py——.graphifyignore/.gitignore 的解析、祖先链加载与"只能排除更多"的合并语义；
• graphify/skill.md——/graphify 技能正文，含各参数（--mode deep、--update、--directed 等）的执行手册与 query/path/explain 子流程；
• graphify/extract.py 与 graphify/extractors/——AST 抽取引擎与分语言提取器；
• graphify/report.py——god 节点、意外关联、建议提问等报告项的生成；
• docs/how-it-works.md——项目官方的原理说明文档，可作为本文的补充读物。

graphify 的设计取向可以概括为一句话：能确定性计算的就绝不交给 LLM——代码结构走 AST、视频走本地 Whisper、聚类走图拓扑，LLM 只负责语义层的概念与关联抽取；而每一条推断出来的边都用 INFERRED + 置信度分数标注清楚。这正是它"每条边都可解释、无向量库"主张在工程上的落点。