graphify 知识图谱实战：从三遍流水线到可查询图谱的完整构建指南

graphify 知识图谱实战：从三遍流水线到可查询图谱的完整构建指南

【免费下载链接】graphify Turn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store. 项目地址: https://gitcode.com/GitHub_Trending/graph/graphify

相关服务：菲律宾服务器

本文以 graphify 仓库中的官方文档（Filipino 版 README 及其指向的主文档）为骨架，结合仓库源码实现，完整讲解 graphify 如何将代码库、文档、PDF、图片乃至音视频转成一张可查询的 knowledge graph：如何安装并注册 /graphify 技能、三遍流水线（tree-sitter AST / faster-whisper 转写 / LLM 语义抽取）如何分工、EXTRACTED/INFERRED/AMBIGUOUS 置信度标签的判定标准、SHA256 缓存带来的增量构建机制，以及 query/path 等图谱查询命令的实际用法与源码级原理。读完本文，你可以在自己的项目中复现 graphify 的完整工作流，并理解每个输出文件（graph.html、GRAPH_REPORT.md、graph.json、cache/）背后的生成逻辑。

一、graphify 是什么：给 AI 编程助手用的 /graphify 技能

graphify 是一个面向 AI coding assistant 的技能（skill）。在 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Kiro、Google Antigravity 等助手中输入 /graphify，它会读取你的文件、构建一张 knowledge graph，然后把你"不知道存在的结构关系"呈现出来——理解代码库更快，还能追溯架构决策背后的"为什么"。

其核心定位有三个（均来自 README.md）：

• 代码映射免费且完全本地：代码用 tree-sitter AST 解析，确定性、无 LLM、没有任何内容离开你的机器；只有文档、PDF、图片、视频走语义抽取通道（使用助手会话的模型或你配置的 API key）。
• 每条边都有解释：每个连接都带 EXTRACTED（源码中显式存在）或 INFERRED（由 graphify 解析推断）标签，你能分清"直接读到的"和"推断出来的"。
• 不是向量索引：没有 embeddings、没有向量库，而是一张真正可以遍历的图。你可以提问、追踪两个概念之间的路径、解释某个概念。

官方文档还引用了一个典型场景：Andrej Karpathy 维护一个 /raw 文件夹存放论文、tweet、截图和笔记，graphify 正是为这类问题提供解法——相比直接读取 raw 文件，每次查询的 token 消耗降低 71.5 倍，并且图谱在会话之间是持久的（数据出处见 docs/how-it-works.md 的 Token benchmark 一节）。

二、多模态输入：代码、PDF、图片与音视频进同一张图

graphify 是完全多模态的。你可以加入代码、PDF、markdown、截图、架构图、白板照片、其他语言的照片、以及音视频文件——graphify 会从所有这些来源抽取概念与关系，并连接进同一张图。视频会用 Whisper 在本地转写；代码侧支持 25 种编程语言（按 docs/how-it-works.md 的说法），全部通过 tree-sitter AST 完成。

从源码结构看，语言覆盖面比文档口径更宽：graphify/extractors/ 目录下已经存在 Rust、Go、C/C++、C#、Java、Kotlin、Scala、Swift、PHP、Pascal、OCaml、Common Lisp、Zig、PowerShell、Fortran、Elixir、Verilog、Terraform、Apex、SQL 等独立提取器模块，另有 extract.py 中直接实现的 Python、JS/TS、Vue、Svelte、Astro、Groovy 等提取器，以及 XAML/C# 项目的视图模型关联、SQL 表/外键/JOIN 的确定性抽取等特殊通道。SQL 文件还会受到特殊对待：表、视图、外键和 JOIN 关系都是确定性抽取的（见 graphify/extractors/sql.py）。

三、工作原理：三遍流水线（The Three Passes）

Filipino 版 README 的 "Paano Gumagana"（工作原理）一节指出，graphify 分三遍处理文件：先是一次确定性的 AST 遍（无 LLM）从代码文件抽取结构；然后视频和音频文件用 faster-whisper 本地转写；最后由 Claude 子代理并行处理文档、论文、图片和转写文本。结果合并进一个 NetworkX 图，用 Leiden 算法聚类，导出为交互式 HTML、可查询 JSON 和审计报告。

docs/how-it-works.md 给出了更细的说明，每一条都可以在源码中找到对应实现：

Pass 1 — 代码结构（免费、无 API 调用）

tree-sitter 解析代码文件，抽取类、函数、import、调用图和内联注释，全程本地运行、不涉及 LLM。SQL 文件被特殊处理：表、视图、外键、JOIN 关系都是确定性抽取的。

代码文件在正常流水线中不会发给 LLM 语义抽取器。如果整个语料只有代码文件，Pass 3 会被完全跳过——语义抽取只保留给文档、论文、图片和转写文本。

并行实现上，graphify/extract.py 中 _extract_parallel() 使用 ProcessPoolExecutor 做真正的多进程并行（绕过 GIL），graphify/extract.py#L5749 处可以看到 concurrent.futures.ProcessPoolExecutor(max_workers=max_workers) 的实际调用。docs/how-it-works.md 给出的实测：在 84 个代码文件的语料上，并行 AST 抽取比串行快约 1.66 倍。

Pass 2 — 视频与音频（本地、无 API 调用）

视频和音频用 faster-whisper 转写。为了让转写聚焦在你的领域上，转写 prompt 会用你当前代码图谱中连接度最高的 god nodes 作为种子。转写文本会被缓存——重跑时跳过已处理文件。

源码印证：graphify/transcribe.py 中 from faster_whisper import WhisperModel 确认了本地转写引擎，build_whisper_prompt(god_nodes) 函数实现了"用 god nodes 播种转写 prompt"的行为，transcribe() 支持 force 参数控制是否覆盖已有缓存。

Pass 3 — 文档、论文、图片（Claude 子代理、消耗 token）

Claude 并行处理 markdown、PDF、图片和转写文本。每个子代理读取一批文件，输出一个 JSON 片段（节点、边、以及分组关系），所有片段合并为一张图。Pass 3 之前还有可选的转换器：Office 文件（.docx、.xlsx）通过 [office] extra 支持，Google Workspace 快捷方式（.gdoc/.gsheet/.gslides）通过 --google-workspace 或 GRAPHIFY_GOOGLE_WORKSPACE=1 开启，且需要已认证的 gws CLI。

从 ARCHITECTURE.md 可以看到整条流水线的模块链：

detect()  →  extract()  →  build()  →  cluster()  →  analyze helpers  →  report.generate()  →  export.to_*()

各阶段以独立的 Python dict 和 NetworkX 图通信，没有共享状态，副作用只落在 graphify-out/ 内。validate.py 会在 build() 消费之前强制校验每个提取器的输出 schema（{nodes: [...], edges: [...]}，节点含 id/label/source_file/source_location，边含 source/target/relation/confidence）。

四、社区检测与置信度标签

Leiden 聚类：没有 embeddings 的社区发现

社区用 Leiden 算法 检测——一种按边密度分组的图聚类方法，连接密集的节点会落入同一社区。不需要 embeddings：语义相似度边（Claude 抽取的 semantically_similar_to）已经在图里，直接影响社区形状。图结构本身就是相似度信号，没有单独的 embedding 步骤或向量数据库。

源码中 graphify/cluster.py 通过 from graspologic.partition import leiden 调用 Leiden 实现，并优先走 _native_leiden() 直接调用 graspologic_native.leiden() 以绕开进度条的 ANSI 转义输出；cluster(G, resolution, exclude_hubs_percentile) 是对外入口，resolution 控制社区粒度（数值越大社区越细）。

每条边都可审计：三种置信度标签

每条关系都带三种标签之一：

标签	含义
EXTRACTED	直接来自源码（如函数调用、import 语句）
INFERRED	合理的推断，附带 confidence_score（0.0–1.0）
AMBIGUOUS	不确定——在报告中被标记供人工复核

EXTRACTED 边恒为置信度 1.0；INFERRED 边使用离散评分标准（见 docs/how-it-works.md）：

• 0.95 — 接近确定（显式的跨文件引用、唯一合理目标）
• 0.85 — 强证据（命名与上下文吻合）
• 0.75 — 合理（上下文相关但非显式）
• 0.65 — 弱（仅命名相似）
• 0.55 — 推测性

测试用例 tests/test_inferred_confidence_rubric.py 对这个评分标准做了固化，tests/test_evidence_binding.py 则验证抽取结果与源码证据的绑定，保证标签不是"拍脑袋"产物。

五、安装

环境要求：Python 3.10+，以及 Claude Code、Codex、OpenCode、Cursor 等任一 AI 助手。

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

官方包命名：PyPI 上的包名是 graphifyy（双 y），命令仍然是 graphify。这是官方文档特别强调的易错点：uvx graphify … 或 uv tool run graphify … 会失败，因为 uv tool run 把第一个词当作包名去查找；正确写法是 uvx --from graphifyy graphify install。用 pip 安装时可能还需要把 ~/.local/bin（Linux）或 ~/Library/Python/3.x/bin（macOS）加入 PATH，或直接 python -m graphify。

graphify install 会把技能文件注册到你的 AI 助手（默认 Claude Code）。如果希望技能装进当前仓库而不是用户目录，加 --project，例如 graphify install --project --platform codex，会写入 .claude/skills/graphify/SKILL.md 或 .agents/skills/graphify/SKILL.md 一类的技能文件并提示 git add。安装逻辑在 graphify/install.py 中，按平台分发（claude_install、codex_install、cursor_install、gemini_install、vscode_install 等）。

六、使用：核心命令

/graphify .
/graphify ./raw --update
/graphify query "ano ang nagkokonekta sa Attention at sa optimizer?"
/graphify path "DigestAuth" "Response"
graphify hook install
graphify update ./src

即：对当前目录建图；对 ./raw 做增量更新；用自然语言提问（示例问题是菲律宾语"什么连接了 Attention 和 optimizer？"）；追踪两个概念之间的最短路径；安装 git hook 实现提交后自动重建；对 ./src 做增量更新。

结合 README.md 的完整命令参考，实际可用的命令面包括：

/graphify . --cluster-only --resolution 1.5      # 更细粒度的社区
/graphify . --no-viz                             # 跳过 HTML，只出报告 + JSON
/graphify . --wiki                               # 从图谱构建 markdown wiki
/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"
/graphify add https://arxiv.org/abs/1706.03762   # 拉取论文并入图
graphify hook install                            # 提交 / 切分支时自动重建
graphify merge-graphs a.json b.json              # 合并两张图

README 给出的真实输出示例（在 FastAPI 代码库上运行）：

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

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

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

从源码看，这些查询能力由 graphify/serve.py 实现：_query_graph_text() 对问题做关键词评分（含 IDF 加权与 trigram 索引加速）选出种子节点，再沿图做 BFS/DFS 展开为带 token 预算的子图；_shortest_path_text() 负责两节点之间的路径追踪。MCP 服务器把 query_graph、get_node、get_neighbors、shortest_path 等暴露为结构化工具，供助手以工具调用的方式反复访问图谱。

七、构建产物：graphify-out/ 里有什么

一次 /graphify . 运行之后你会得到：

graphify-out/
├── graph.html       交互式图谱——用任何浏览器打开
├── GRAPH_REPORT.md  god nodes、惊人的连接、建议问题
├── graph.json       持久化图谱——几周后仍可查询
└── cache/           SHA256 缓存——重跑只处理变更过的文件

报告里有什么

• God nodes — 连接度最高的概念，"一切流量都经过这里"。实现见 graphify/analyze.py 的 god_nodes(G, top_n)，按节点度数排序。
• 惊人的连接（Surprising connections） — 不同文件/模块之间的链接，按"意外程度"打分排序。surprising_connections() 通过 _surprise_score() 对跨文件、跨社区的边做加权。
• "为什么" — 内联注释（# NOTE:、# WHY:、# HACK:）、docstring 和来自文档的设计理由，被抽取为独立节点并链接到被解释的代码。graphify/extract.py 中 _extract_python_rationale()、walk_docstrings() 负责 Python 侧，JS 侧有 _extract_js_rationale()。
• 建议问题 — 图谱独特有能力回答的 4–5 个问题，由 suggest_questions() 生成。
• Token 基准 — 官方基准：在混合语料（Karpathy repos + 5 篇论文 + 4 张图片，52 个文件）上，每次查询比直接读原始文件少 71.5 倍 token。完整数据见 docs/how-it-works.md：

语料	文件数	缩减倍数
Karpathy repos + 论文 + 图片	52	71.5x
graphify 源码 + Transformer 论文	4	5.4x
httpx（合成 Python 库）	6	~1x

token 缩减随语料规模放大——6 个文件本来就能装进上下文窗口，图的价值在于结构性清晰而非压缩；到 52 个文件时节省开始显著累积。仓库的 worked/ 目录保留了真实语料与产物（如 worked/karpathy-repos/GRAPH_REPORT.md、worked/httpx/graph.json），可自行运行验证。

graph.json 的格式

输出 graph.json 使用 NetworkX 的 node-link 格式（导出实现在 graphify/export.py 的 to_json()）。每个节点含：

• id — 稳定标识符
• label — 人类可读名称
• file_type — code、document、paper、image、rationale
• source_file — 来源文件

每条边含：

• source、target — 节点 ID
• relation — 动词短语（如 calls、imports、implements、semantically_similar_to）
• confidence — EXTRACTED、INFERRED 或 AMBIGUOUS
• confidence_score — 浮点数（仅 INFERRED 边）
• source_file — 关系被发现的出处

连接 3 个以上节点的分组关系（超边）存放在 G.graph["hyperedges"] 中。

八、SHA256 缓存：增量的底层机制

README 说"SHA256 cache — 重跑只处理变更文件"。源码实现见 graphify/cache.py：file_hash() 对文件内容做 hashlib.sha256() 指纹，check_semantic_cache() 在每次运行前把文件分成"已缓存"和"需要抽取"两组；detect_incremental()（graphify/detect.py）基于 graphify-out/manifest.json 中记录的哈希做增量判定。缓存位于 graphify-out/cache/。

这带来了几个实用特性：

• /graphify ./raw --update 只重新抽取变更过的文件；
• 纯代码语料的提交后重建是零 API 成本的——graphify hook install 安装 post-commit / post-checkout hook 后，git commit 和分支切换都会触发后台重建（仅 AST 通道），git pull 后手动跑一次 graphify update . 与团队同步；
• manifest.json 以相对路径存储并支持重新锚定，因此可以安全提交进 git，团队首个 checkout 不需要全量重建。

hook 的安装在 graphify/hooks.py 中，install() 会写入 post-commit/post-checkout 脚本并注册一个 git merge driver，让 graph.json 在并发提交时做 union 合并而不是留下冲突标记。

九、隐私边界

Filipino 版 README 的 "Privacy" 一节声明：代码文件通过 tree-sitter AST 本地处理；视频用 faster-whisper 本地转写；无遥测。结合 README.md 更完整的隐私说明：

• 代码文件 — 本地 tree-sitter 处理，无任何内容离开你的机器。纯代码语料不需要任何 API key，graphify extract 可以完全离线运行；混合仓库可加 --code-only 只索引代码、跳过需要 LLM 的文档/PDF/图片。
• 视频/音频 — 本地 faster-whisper 转写，同样不离开机器。
• 文档、PDF、图片 — 通过 /graphify 技能发送给你 AI 助手的模型做语义抽取；headless 的 graphify extract 则按已设置的 API key 自动选择后端（优先级：Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama），有数据驻留要求的代码可用 --backend ollama 走完全本地。
• 无遥测、无用量跟踪、无分析。

外部输入还会经过 graphify/security.py 的校验（URL 仅允许 http/https、抓取内容有大小的与超时限制、图路径必须落在 graphify-out/ 内、节点标签做控制字符清洗），完整威胁模型见 SECURITY.md。

十、适用前提与限制

• 需要 Python 3.10+；推荐 uv tool install 或 pipx install 以获得隔离环境，避免 pip install 在 macOS/Windows 上出现 ModuleNotFoundError: No module named 'graphify' 的环境错配问题。
• PowerShell 中请用 graphify . 而不是 /graphify .（前导斜杠是路径分隔符）；Codex 用户用 $graphify 而非 /graphify。
• 语义抽取通道（Pass 3）消耗 token 并依赖模型后端；代码通道（Pass 1）则完全免费。如果某次 --update 或重建后节点数变少，用 --force（或 GRAPHIFY_FORCE=1）允许覆盖。
• 文档提到的企业层 Penpax（graphify.com 上的 waitlist 产品）是官方文档中的预告性内容，本文不展开。

小结

graphify 的核心思路可以概括为：确定性的部分绝不动用 LLM，需要 LLM 的部分绝不动用代码通道。tree-sitter AST 通道免费且本地，faster-whisper 转写通道免费且本地，只有文档/图片/论文的语义通道消耗 token——而这一通道换来的是一张每条边都可审计（EXTRACTED/INFERRED/AMBIGUOUS + 置信度评分）、社区结构由 Leiden 算法直接给出（无需向量库）、SHA256 缓存保证增量更新的 NetworkX 图。对读者而言，最值得记住的实操路径是：uv tool install graphifyy → graphify install → /graphify . → 用 query/path/explain 查询，把 graphify-out/ 提交进 git，让全团队共享同一张地图。

延伸阅读：docs/how-it-works.md（流水线与基准细节）、ARCHITECTURE.md（模块职责与新增语言的 5 步流程）、BENCHMARKS.md（LOCOMO / LongMemEval 评测）、docs/docker-mcp-sqlite.md（Docker MCP Toolkit + SQLite 集成）、worked/mixed-corpus/GRAPH_REPORT.md（混合语料的真实报告样例）。

【免费下载链接】graphify Turn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store. 项目地址: https://gitcode.com/GitHub_Trending/graph/graphify