Graphify：把整个代码库变成可查询的知识图谱——/graphify 技能实战指南

Graphify 是一个面向 AI 编码助手（Claude Code、Codex、Cursor、Gemini CLI 等）的 /graphify 技能：在本地用确定性 AST 解析你的代码、文档、SQL、PDF 和音视频，构建出一个可持久查询的知识图谱，让"理解代码库"从逐文件阅读变成图查询。读完本文，你将掌握 graphify 的完整安装与使用流程、它的三遍式处理管线、边置信度标记体系（EXTRACTED / INFERRED / AMBIGUOUS），以及 SHA256 增量缓存机制在源码层面的实现细节。

一个技能命令，覆盖 15+ AI 编码助手

按官方文档（docs/translations/README.sv-SE.md，瑞典语版 README，内容与英文版保持一致）描述，graphify 的使用方式是一条斜杠命令：在 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 完成解析（早期文档标注 25 种，当前英文版 README.md 称已扩展到约 40 种）。

文档中提到的一个经典场景：Andrej Karpathy 习惯把一个 /raw 目录堆满论文、推文、截图和笔记。graphify 正是为这类"越攒越乱"的知识堆积而设计的方案——官方称其单次查询比直接读取原始文件减少 71.5 倍的 token 消耗，且图谱在会话之间持久存在，几周后仍可继续提问。该数字出自 README 文档自身的声明，完整的对照基准与复现方式见 BENCHMARKS.md。

执行 /graphify . 后，产物落在一个固定的输出目录：

graphify-out/
├── graph.html       交互式图表 — 可用任意浏览器打开
├── GRAPH_REPORT.md  枢纽节点（god nodes）、意外的关联、建议的追问
├── graph.json       持久化图谱 — 数周之后依然可以直接查询
└── cache/           SHA256 缓存 — 重复运行只处理发生变化的文件

其中 cache/ 目录对应源码中的实现：graphify/cache.py 以"文件内容 + 相对路径"的 SHA256 作为缓存键，按 graphify-out/cache/{kind}/{hash}.json 落盘，首次运行做全量哈希，之后仅在文件内容变化时才重算——这就是"重复运行只处理变更文件"的保证。

三遍式管线：确定性 AST、本地转写、并行语义代理

文档明确描述了 graphify 的三遍（three passes）工作方式：

1. 第一遍：确定性 AST 提取。 用 tree-sitter 从代码文件中抽取结构，完全不调用 LLM，结果确定、可复现。在源码中，每个语言对应一个独立的提取器（如 graphify/extract.py 中的 extract_python、extract_js、extract_go 等），统一的 AST 遍历框架与语言配置集中在 graphify/extractors/ 子包：LanguageConfig（见 graphify/extractors/models.py）为每种语言声明类/函数/import/调用节点的树节点类型、名称字段、调用名提取规则与自定义解析钩子，新语言只需提供配置而非重写解析器。
2. 第二遍：本地转写。 视频和音频文件由 faster-whisper 在本地转写成文本，供后续语义处理使用（转写逻辑见 graphify/transcribe.py）。
3. 第三遍：并行语义代理。 Claude 子代理并行处理文档、论文、图片与转写文本，做语义层的概念与关系抽取。

三遍结果最终合并进一个 NetworkX 图，用 Leiden 算法做社区划分，再导出为交互式 HTML、可查询 JSON 和审查报告。社区划分的具体实现在 graphify/cluster.py：它优先直接调用 graspologic_native.leiden() 以绕过上层封装的输出噪音（见 graphify/cluster.py#L22-L78），失败时回退到 graspologic.partition.leiden。

每条边都带置信度标记：EXTRACTED / INFERRED / AMBIGUOUS

这是 graphify 相对"向量检索"方案的核心差异点：每条关系边都被显式标注来源。官方文档给出的三档标记是：

标记	含义
EXTRACTED	源码中显式存在（如 import、直接调用），直接从 AST 读出
INFERRED	由 graphify 的符号解析推导得出，附置信度分数
AMBIGUOUS	存在歧义、无法唯一确定目标的边

在源码中可以验证这一契约。graphify/validate.py#L5 定义了合法值集合 VALID_CONFIDENCE = {"EXTRACTED", "INFERRED", "AMBIGUOUS"}，图谱在构建时即按此校验；graphify/export.py#L177 给出了各档缺省置信度分数的默认值：

_CONFIDENCE_SCORE_DEFAULTS = {"EXTRACTED": 1.0, "INFERRED": 0.55, "AMBIGUOUS": 0.2}

也就是说，EXTRACTED 边默认按满分 1.0 对待，INFERRED 按 0.55，AMBIGUOUS 仅 0.2——从源码结构看，下游分析（排序、评分、报告）会直接利用这个分数差来区分"读到的事实"与"推断出的连接"。graphify/analyze.py 在计算关联度时也按档位加权（{"AMBIGUOUS": 3, "INFERRED": 2, "EXTRACTED": 1} 的置信度加成，见 graphify/analyze.py#L220），graphify/report.py 则在 GRAPH_REPORT.md 中单独统计 AMBIGUOUS 边的占比，让使用者明确知道图谱里有多少"不确定"的部分。

安装：三种包管理器，同一个官方包名

前置要求是 Python 3.10+，外加任意一个受支持的 AI 编码助手。官方文档给出的三种安装方式：

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

官方包名注意：PyPI 上的包名是 graphifyy（双 y），命令行仍是 graphify。官方文档强调唯一官方仓库为 safishamsi/graphify，PyPI 上其他 graphify* 开头的包均非官方出品。graphify install 这一步负责把技能文件注册到你使用的 AI 助手中（各平台技能模板见 graphify/skills/ 目录下的 claude、codex、cursor、gemini、vscode、kiro 等子目录）。

日常使用：构建、增量更新、查询、路径追踪

文档给出的核心命令集，全部继承如下（在 AI 助手中用 /graphify 前缀，在终端直接用 graphify CLI）：

/graphify .                                        # 对当前目录构建图谱
/graphify ./raw --update                           # 增量更新已有图谱
/graphify query "Attention 和 optimizer 之间有什么连接？"
/graphify path "DigestAuth" "Response"            # 追踪两个概念间的最短路径
graphify hook install                              # 安装 git hook，提交后自动维护图谱
graphify update ./src                              # 命令行方式增量更新指定目录

• query 用自然语言提问，返回一个限定作用域的子图，而不是重新读一遍文件；
• path A B 沿图追踪任意两个节点之间的最短路径，逐跳展示 uses / imports / references 等关系——上面第二张截图正是该命令在 FastAPI 代码库上的真实演示，完整示例输出（graphify explain "APIRouter"、graphify path "FastAPI" "ModelField"）见 README.md 的 "See it in action" 一节；
• --update / update 依赖 cache/ 的 SHA256 指纹，只重处理变更文件，配合 git hook 可做到"提交即更新"。

你能从图谱里得到什么

文档列出的开箱即得能力，每一条都有对应的源码落点：

• 枢纽节点（God nodes）——度数最高的概念，看出"一切流量经过哪里"。计算逻辑在 graphify/analyze.py；
• 意外的关联——按评分排序的跨社区连接，帮助发现架构中的隐性耦合；
• 建议的追问——GRAPH_REPORT.md 中的 "suggested questions"，由 graphify/report.py 生成；
• "为什么"（Rationale）——docstring 和设计动机被抽取为一等节点并与代码关联；
• Token 基准——README 声称在混合语料上单次查询减少 71.5 倍 token；构建图谱本身 0 LLM 消耗（代码侧全程无 LLM），这一条在 BENCHMARKS.md 的基准表中有对应指标。

隐私：本地优先，零遥测

官方文档对隐私的描述非常简洁，但值得逐条对照源码：

• 代码文件：纯本地处理，tree-sitter AST 解析，不经过任何 LLM，文件内容不离开本机；
• 视频/音频：faster-whisper 本地转写；
• 无遥测：代码库中不存在遥测上报逻辑。

需要 LLM 的只有第三遍的语义抽取（文档、论文、图片、转写文本），且仅在你配置的助手/API 后端存在时才发生——这意味着纯代码仓库可以完全离线构建图谱。

小结

graphify 的设计取舍可以概括为三句话：代码路径确定性优先（tree-sitter AST、零 LLM）、每条边可解释（EXTRACTED / INFERRED / AMBIGUOUS 三级标记加置信度分数）、图而非向量（可查询、可追路径、可跨会话持久化）。配合 SHA256 增量缓存和 --update / git hook，它把"理解一个代码库"从一次性的人工成本变成了一个持续维护的、随时可问的本地资产。