Graphify 实战指南：用一条 /graphify 命令把代码库变成可查询的知识图谱

本文以 graphify 仓库的意大利语 README（docs/translations/README.it-IT.md）为主线，完整覆盖该文档的三大核心主张——一条 /graphify 命令生成知识图谱、三阶段确定性流水线、边级置信度标注——并结合当前仓库源码（graphify/extract.py、graphify/cluster.py、graphify/cache.py、graphify/transcribe.py）与配套文档 docs/how-it-works.md，讲清楚安装、命令用法、输出产物、置信度体系与隐私边界。读完后你能够独立完成：安装并注册 skill、构建与增量更新图谱、执行 query/path/explain 查询、理解每条边的 EXTRACTED/INFERRED/AMBIGUOUS 标注含义。

一条命令：graphify 是什么

graphify 是一个面向 AI 编程助手的 skill（技能文件 + Python 工具包）。在 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、截图、架构图、白板照片、外语图片，乃至视频音频都可以加入。视频与音频在本地用 Whisper 转录，支持约 25 种以上编程语言（当前 README.md 列出 37 种 tree-sitter 语法对应扩展）通过 tree-sitter AST 解析；
• 本地确定性解析：代码文件走 tree-sitter AST，无 LLM、无网络调用；文档、PDF、图片、转录文本才交给模型的语义通道；
• 每条边都有解释：每个关系被标注为 EXTRACTED（源码中明确存在）、INFERRED（解析推断，附置信度分数）或 AMBIGUOUS（不确定，需人工复核）。

意大利语 README 中提到的 Karpathy /raw 目录场景在仓库里有对应实证：worked/karpathy-repos/ 目录保存了该混合语料的原始输入、GRAPH_REPORT.md 与 graph.json 实际输出，可对照验证「混合语料上每查询 token 减少 71.5 倍」这一基准数字（出处见 docs/how-it-works.md 的 Token benchmark 一节）。

运行后的输出目录结构（原文档即以此示例）：

graphify-out/
├── graph.html       交互式图谱 —— 在任意浏览器打开，可点击、过滤、搜索
├── GRAPH_REPORT.md  报告 —— 枢纽节点（god nodes）、意外连接、建议问题
├── graph.json       持久化图谱 —— 数周后仍可直接查询
└── cache/           SHA256 缓存 —— 重跑只处理有改动的文件

三阶段流水线：AST、Whisper、语义子代理

原文档「Come funziona」一节描述了三步流程，docs/how-it-works.md 给出了更精确的分工，二者一致：

Pass 1 — 代码结构（免费、零 API 调用）。tree-sitter 解析代码文件，提取类、函数、导入、调用图与行内注释，全程本地、无 LLM。纯代码语料会完全跳过语义通道——从 graphify/extract.py 的头部注释可以看到该模块的定位就是「deterministic structural extraction from source code using tree-sitter」。SQL 文件走专用提取器（表、视图、外键、JOIN 关系均为确定性抽取，见 graphify/extractors/sql.py）。

Pass 2 — 音视频（本地、零 API 调用）。视频与音频用 faster-whisper 转录。一个值得注意的实现细节：转录提示词会用当前图谱中度数最高的 god nodes 做种子，让转录聚焦于你的领域。这一点可以从源码直接印证——graphify/transcribe.py 中的 build_whisper_prompt(god_nodes) 与 transcribe() 函数，其中模型以 WhisperModel(model_name, device="cpu", compute_type="int8") 在 CPU 上以 int8 精度运行。转录结果同样有缓存，重跑会跳过已处理文件。

Pass 3 — 文档、论文、图片（并行子代理，消耗 token）。Claude（或配置的其它后端）以并行子代理方式处理 markdown、PDF、图片与转录文本，每个子代理读一批文件并输出 JSON 片段（节点、边、组关系），最终合并进同一个 NetworkX 图谱。进入 Pass 3 前，可选转换器会把 .docx/.xlsx 等格式转成 graphify-out/converted/ 下的 Markdown sidecar。

合并后的图谱经过 Leiden 社区检测 分组。graphify/cluster.py 的 _partition(G, resolution) 优先调用原生 Leiden 实现，再回退到 graspologic（仅 Python < 3.13，对应 pyproject.toml 中 leiden = ["graspologic; python_version < '3.13'"] 的约束）。docs/how-it-works.md 特别强调：这里不需要嵌入向量——语义相似边（semantically_similar_to）本身就在图中，直接影响社区形状，因此没有单独的 embedding 步骤，也没有向量数据库。

安装

原文档「Installazione」一节的前提是 Python 3.10+（与 pyproject.toml 中 requires-python = ">=3.10" 一致）加上一个 AI 编程助手。安装命令：

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

几个必须知道的注意点（均来自 README.md 的安装与故障排查章节，仓库实际验证过的坑）：

• PyPI 包名是 graphifyy（双 y），命令行仍是 graphify。PyPI 上其它 graphify* 包均与本项目无关；
• uv tool install 后若提示 command not found，执行 uv tool update-shell 重开终端（pipx 用户执行 pipx ensurepath）；
• 用 uvx 免安装运行时必须写明包名：uvx --from graphifyy graphify install，裸 uvx graphify … 会报 No solution found；
• 当前仓库版本为 0.9.52（pyproject.toml），许可为 Apache-2.0。

graphify install 的默认目标是 Claude Code（单平台）；其它平台用显式子命令或 --platform 参数注册 skill，例如：

graphify install --project                 # 装到当前仓库而非用户主目录
graphify install --platform codex
graphify cursor install                    # 写入 .cursor/rules/graphify.mdc
graphify gemini install                    # GEMINI.md + BeforeTool hook
graphify claude install                    # CLAUDE.md + PreToolUse hook

--project 安装会写入 .claude/skills/graphify/SKILL.md 或 .agents/skills/graphify/SKILL.md（外加按需加载的 references/ 侧车），并打印 git add 提示。skill 文件本体由 tools/skillgen 工具链从 tools/skillgen/fragments/ 生成，仓库内置 --check/--monolith-roundtrip 等一致性校验。

可选 extras：只装你需要的能力

pyproject.toml 定义了完整的可选依赖矩阵，安装时按需选择：

Extra	提供能力	安装方式
pdf	PDF 抽取	uv tool install "graphifyy[pdf]"
office	.docx/.xlsx	uv tool install "graphifyy[office]"
video	faster-whisper + yt-dlp 音视频转录	uv tool install "graphifyy[video]"
mcp	MCP stdio/HTTP 服务器	uv tool install "graphifyy[mcp]"
neo4j / falkordb	图谱推送到图数据库	uv tool install "graphifyy[neo4j]"
leiden	Leiden 社区检测（Python < 3.13）	uv tool install "graphifyy[leiden]"
ollama / openai / gemini / anthropic / bedrock	各 LLM 后端	uv tool install "graphifyy[ollama]" 等
sql	SQL schema 抽取	uv tool install "graphifyy[sql]"
postgres	在线 PostgreSQL schema 内省（--postgres DSN）	uv tool install "graphifyy[postgres]"
pascal / ocaml / commonlisp / terraform / dm	对应语言的 AST 级抽取	uv tool install "graphifyy[pascal]" 等
chinese	jieba 中文查询分词	uv tool install "graphifyy[chinese]"
all	以上全部	uv tool install "graphifyy[all]"

注意 pyproject.toml 的注释：postgres extra 必须同时携带 tree-sitter-sql 语法，否则 --postgres 内省会静默返回 0 个节点。

使用：核心命令

原文档「Utilizzo」一节给出的命令集合如下，全部保留：

/graphify .                        # 对当前文件夹建图
/graphify ./raw --update           # 只重新抽取改动的文件
/graphify ./raw --mode deep        # 更激进的语义关系抽取
/graphify query "cosa connette Attention all'ottimizzatore?"
/graphify path "DigestAuth" "Response"
graphify hook install
graphify update ./src

结合 README.md 的完整命令参考，日常最常用的扩展形态包括：

/graphify . --cluster-only                 # 不重新抽取，只重跑聚类
/graphify . --cluster-only --resolution 1.5 # 更细粒度的社区
/graphify . --no-viz                        # 跳过 HTML，只出报告 + JSON
/graphify . --wiki                          # 从图谱生成 markdown wiki
/graphify explain "RateLimiter"             # 解释单个概念
/graphify add https://arxiv.org/abs/1706.03762   # 抓一篇论文加进图
graphify extract ./docs --code-only         # 只索引代码，本地 AST，无需 API key
graphify extract ./docs --backend gemini    # 无 IDE 的 headless 抽取（CI 场景）
graphify merge-graphs a.json b.json         # 合并两个图谱
graphify prs                                # PR 仪表盘：CI 状态、社区冲突
graphify uninstall --purge                  # 从所有平台移除并删除 graphify-out/

团队工作流：commit 自动重建

graphify-out/ 建议提交进 git，让每个成员克隆即得全量地图。graphify hook install 会安装 post-commit 与 post-checkout hook（纯 AST 重建、无 API 成本），并注册 git merge driver 使 graph.json 冲突时自动 union-merge。日常约定：

你做什么	graphify 做什么
git commit	后台自动重建（AST only）
git checkout / git switch	后台自动重建
git pull / git merge	手动跑一次 graphify update .
文档/论文变更	跑 /graphify --update 刷新相应节点

可配一个别名把 pull 同步变成一步：git config --global alias.gpull '!git pull && graphify update .'。

增量与缓存：SHA256 + stat 索引

「cache/ —— 重跑只处理修改过的文件」这句话背后有两层实现，见 graphify/cache.py：

• 语义缓存以内容指纹命名（cache/semantic/p{fingerprint}/），其中 prompt 指纹由 prompt_fingerprint()（graphify/cache.py）对抽取提示词归一化后取 SHA256 前缀计算——提示词变了就整体失效，避免用旧提示词的 LLM 输出冒充新结果；
• AST 缓存按包版本 + 缓存 schema 命名空间隔离（cache/ast/v{version}-s{schema}/），并在加载时清理旧版本残留条目；
• 大语料下还有 stat 索引（cache/stat-index.json），以 (mtime, size, …) 签名做快速新鲜度判断，签名一致就直接命中缓存，不必重算内容哈希。

重跑行为由此可预期：文件未变 → 跳过；文件变了 → 只重抽该文件；提示词变了 → 语义缓存整体重建。

你得到什么：报告的五类内容

原文档「Cosa ottieni」一节列出五类产物，README.md 的「What's in the report」与之对应：

• God nodes（枢纽节点）——度数最高的概念，一切流量经过的地方；支持 --exclude-hubs 99 之类参数把 p99 度数以上的工具型超级枢纽从排名中排除；
• Surprising connections（意外连接）——不同文件/模块之间的边，按「意外程度」排序；
• Suggested questions（建议问题）——4–5 个图谱独有位置才能回答的问题；
• 「为什么」——# NOTE: / # WHY: / # HACK: 注释、docstring 与 ADR/RFC 引述被抽取为独立的 rationale 节点，链接到它们解释的代码；
• Token benchmark——混合语料上每查询 token 减少 71.5x。

置信度标注：EXTRACTED / INFERRED / AMBIGUOUS

这是原文档最强调的机制（「Ogni relazione è etichettata ...」）。docs/how-it-works.md 给出了完整规则：

标签	含义	置信度
EXTRACTED	直接从源码读到（函数调用、import）	恒为 1.0
INFERRED	带 confidence_score（0.0–1.0）的合理推断	离散刻度
AMBIGUOUS	不确定，报告中标出供人工复核	—

INFERRED 使用离散评分表而非连续值：0.95 近乎确定（显式跨文件引用、唯一候选）、0.85 证据充分（命名 + 上下文一致）、0.75 合理（上下文明确但非显式）、0.65 弱（仅命名相似）、0.55 推测。这套刻度使「从源码直接读到的」与「推断出来的」永远可区分——这也是项目「不是向量索引，而是可遍历的真图」这一主张的落地方式。

查询示例

README.md 展示了在 FastAPI 代码库上的真实输出形态：

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

Connections (47):
  --> RequestValidationError [uses] [INFERRED]
  <-- __init__.py [imports] [EXTRACTED]
  ...

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

graphify query "<question>" 返回面向问题的作用域子图；graphify path A B 追踪两事物之间的最短路径；graphify explain X 给出单个概念的全部连接。每个节点与边都带来源文件，结论可回溯到具体行号。

graph.json 的数据格式

docs/how-it-works.md 定义了输出格式：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。三节点以上的组关系（hyperedges）存在 G.graph["hyperedges"] 中。仓库内 worked/httpx/graph.json 与 worked/mixed-corpus/graph.json 都是可直接打开的真实产物。

隐私边界：什么在本地，什么走 API

原文档「Privacy」一节的三个承诺，与 README.md 的隐私章节逐条对应：

1. 代码文件——tree-sitter 本地解析，什么都不离开你的机器。纯代码语料连 API key 都不需要，graphify extract 可完全离线运行；混合仓库加 --code-only 只索引代码；
2. 视频/音频——faster-whisper 本地转录（如前所述，CPU + int8），同样不出机器；
3. 文档、PDF、图片——经 AI 助手做语义抽取：走 /graphify skill 时用你 IDE 会话的模型；headless graphify extract 则需要配置后端（Gemini、Kimi、Claude、OpenAI 兼容端点、Ollama、Bedrock、Azure 或 claude-cli 等），graphify extract 会按已设置的 key 自动选择后端（优先级：Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama）。有数据驻留要求的代码建议 --backend ollama 全本地运行。

此外项目明确「无遥测、无使用跟踪、无分析」。查询日志是显式 opt-in：默认不写，设 GRAPHIFY_QUERY_LOG_ENABLE=1 才会在 ~/.cache/graphify-queries.log 记录每次 query/path/explain 的问题与语料（GRAPHIFY_QUERY_LOG_DISABLE=1 强制关闭）。

常用后端环境变量（完整表见 README.md「Environment variables」节，仅在 headless/CI 抽取时需要）：

变量	用途
ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL / ANTHROPIC_MODEL	Claude 后端及其兼容端点（默认模型 claude-sonnet-4-6）
OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL	OpenAI 及兼容服务（llama.cpp、vLLM、LM Studio，默认 gpt-4.1-mini）
OLLAMA_BASE_URL / OLLAMA_MODEL	本地 Ollama（默认 http://localhost:11434）
AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT	Azure OpenAI
GRAPHIFY_MAX_WORKERS	AST 并行线程数（等价 --max-workers）
GRAPHIFY_MAX_OUTPUT_TOKENS	提高稠密语料的输出上限
GRAPHIFY_FORCE	即使节点变少也强制覆盖 graph.json
GRAPHIFY_MAX_RETRIES / GRAPHIFY_MAX_RETRY_DEPTH	429 重试次数（默认 6）与被截断 chunk 的二分重抽深度（默认 3）

Token 基准与可验证性

原文档宣称「71,5x meno token per query」。这个数字出自 docs/how-it-works.md 的 Token benchmark 表，且语料规模是关键前提——token 节省随语料规模增长：

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

六七个文件本身就放得进上下文窗口，此时的价值是结构清晰度而非压缩；到 52 个文件时节省开始复利。仓库的每个 worked/ 目录都保留原始输入与真实输出（GRAPH_REPORT.md + graph.json），你可以自行复算。另有 BENCHMARKS.md 记录同一开放测试台上（同模型 Kimi K2.6、同预算、双判官盲评、90.6% 一致率、Cohen's kappa 0.81）的记忆基准结果：LOCOMO recall@10 为 0.497，且图构建本身消耗 0 LLM 额度。

直接消费图谱：MCP 服务器与 Docker

除了 skill 内查询，graph.json 也可以作为独立服务暴露（需要 mcp extra）。README.md 给出两种传输：

# stdio（默认）：每个开发者本地起一个
python -m graphify.serve graphify-out/graph.json

# HTTP：整个团队指向同一个 URL，客户端无需本地 graphify
python -m graphify.serve graphify-out/graph.json --transport http --port 8080
python -m graphify.serve graphify-out/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"

HTTP 传输关键参数：--host（默认 127.0.0.1，仅回环）、--port（默认 8080）、--api-key（启用后要求 Authorization: Bearer）、--path（默认 /mcp）、--stateless（无会话状态，适合负载均衡/CI）、--session-timeout（默认 3600 秒）。对外的官方建议是 --host 0.0.0.0 与 --api-key 必须成对使用，并可用仓库根目录的 Dockerfile 容器化部署（卷挂 graphify-out 到 /data）。MCP 服务器暴露的结构化工具包括 query_graph、get_node、get_neighbors、shortest_path、list_prs 等，使助手获得与终端等价的图遍历能力。

构建在 graphify 之上

意大利语 README 的最后一节介绍了 Penpax——构建在 graphify 之上的企业层（原文档称「Prova gratuita in arrivo」，即免费试用即将上线）。当前 README.md 将这一层描述为 graphify Enterprise（graphify.com，等待名单开放）：把同样的图谱方法应用到整个工作上下文（会议、文件、文档、代码），并在后台持续更新。两者是同一产品方向在不同文档时点的表述；以当前仓库 README 的表述为准。

小结与延伸阅读

回到原文档的三句主张并逐一对上仓库证据：一条 /graphify 命令生成 graph.html + GRAPH_REPORT.md + graph.json 三件套；三阶段流水线（本地 tree-sitter AST → 本地 faster-whisper → 并行语义子代理）把成本与隐私边界切得很清楚；每条边的 EXTRACTED/INFERRED（带 0.55–0.95 离散置信度）/AMBIGUOUS 标注让「读到的」与「推断的」始终可区分。

延伸阅读（均为仓库内相对路径）：

• docs/how-it-works.md——三阶段流水线、Leiden 社区检测、置信度评分表、token 基准的完整说明；
• ARCHITECTURE.md——模块划分与如何为 graphify 添加一种新语言；
• docs/docker-mcp-sqlite.md——Docker MCP Toolkit + SQLite 可选集成；
• worked/karpathy-repos/、worked/mixed-corpus/——真实语料的输入输出对照，可自行验证基准数字；
• tests/fixtures/ 与 tests/——各语言抽取器（AST 质量）与解析行为的测试证据。