graphify 知识图谱技能完全指南：三遍提取管线、Leiden 社区检测与 EXTRACTED/INFERRED 边置信体系

graphify 知识图谱技能完全指南：三遍提取管线、Leiden 社区检测与 EXTRACTED/INFERRED 边置信体系

【免费下载链接】graphifyTurn 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 是一个面向 Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、Aider、OpenClaw、Factory Droid、Trae、Kiro 和 Google Antigravity 等 20 多个 AI 编码助手的「技能」(skill)：在任意仓库中敲下/graphify，它读取代码、文档、PDF、图片甚至音视频，构建出一张可查询的知识图谱，并把你在 grep 中看不到的结构性关系显式呈现出来。读完全文，你将掌握 graphify 的完整安装流程（含各平台命令对照表）、/graphify全部常用子命令与参数、.graphifyignore排除规则，以及从源码层面印证其三遍提取管线、SHA256 增量缓存、Leiden 社区检测和EXTRACTED/INFERRED/AMBIGUOUS三级边置信体系的底层实现位置。

一、图谱技能是什么：一条命令，三种产物

graphify 的核心用法只需一条命令——在 AI 助手的对话框里输入：

/graphify . # 对任意目录运行：代码、笔记、文章，什么都行

运行结束后，当前目录会生成graphify-out/输出文件夹，包含四类产物：

graphify-out/ ├── graph.html 交互式图谱 — 浏览器中打开，可点击、搜索、过滤 ├── GRAPH_REPORT.md 报告 — 上帝节点、惊人连接、建议问题 ├── graph.json 持久化图谱 — 数周后无需重读文件即可查询 └── cache/ SHA256 缓存 — 重新运行只处理已修改的文件

graphify 是完全多模态的：你可以放入代码、PDF、Markdown、截图、图表、白板照片、其他语言的文字图片，甚至音视频文件——graphify 从它们全部提取概念与关系并连接进同一张图。其中视频使用本地 faster-whisper 配合面向你领域定制的提示词完成转录，25 种编程语言通过 tree-sitter AST 解析（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）。

项目 README 中给出的一个典型场景是：Andrej Karpathy 习惯维护一个/raw目录，随手堆放文章、推文、截图和笔记——graphify 正是为这类问题而生：相比直接读取原始文件，每次查询节省约71.5 倍的 token，图谱在会话之间持久存在，并且诚实地区分「找到了什么」与「推断出了什么」。

排除不需要索引的目录，只需在仓库根目录放一个.graphifyignore文件：

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

语法与.gitignore完全一致，仓库根目录放一个即可生效。从源码看（graphify/detect.py），graphify 会同时合并读取各目录下的.gitignore与.graphifyignore，且.graphifyignore的模式最后求值、在冲突时获胜——因此添加.graphifyignore只会让排除更多，永远不会把.gitignore已排除的文件重新纳入。解析器逐行遵循 gitignore 规范，包括!取反语法（见 graphify/detect.py 的单行解析函数）。

二、三遍提取管线：从源码印证「无 LLM、无向量库」的设计

这是 graphify 区别于向量检索方案的核心设计，也是原文档「Comment ça fonctionne」一节的主体。graphify 按三遍（pass）处理文件：

第一遍：代码结构（免费，零 API 调用）。tree-sitter 对代码文件做确定性 AST 解析，提取类、函数、import、调用图、docstring 与「为什么这样设计」的注释，全程本地、不经过 LLM。代码文件不会进入语义提取器；如果语料只含代码文件，第三遍会被整体跳过，语义提取只保留给文档、论文、图片和转录文本。这一设计在源码中可直接验证：graphify/extract.py 中所有 AST 产出的边都被标注"confidence": "EXTRACTED"，即边是直接从源码中「读到」的。

第二遍：音视频（本地，无 API 调用）。视频与音频用 faster-whisper 本地转录。为了让转录聚焦于你的领域，转录提示词会以当前代码图中度数最高的「上帝节点」作为种子注入；转录结果被缓存，重跑时跳过已处理文件。

第三遍：文档、论文、图片（Claude 子代理并行，消耗 token）。Claude 子代理并行处理 markdown、PDF、图片和转录文本，每个子代理读取一批文件并输出 JSON 片段（节点、边、组关系），片段最终合并为一张 NetworkX 图。

关于「聚类基于图谱拓扑、而非 embeddings」这一点，docs/how-it-works.md 给出了权威解释，源码则印证了具体实现与降级链：

• Leiden 优先，逐级降级。graphify/cluster.py 优先调用graspologic_native.leiden()，失败再走graspologic.partition.leiden()，两者都不可用时回退到 networkx 内置的 Louvain。模块文档字符串明确写着这一策略（"Uses Leiden (graspologic) if available, falls back to Louvain"）。
• 社区内节点按边密度聚合：连接越密集，越容易被划入同一社区。Claude 提取的语义相似边（semantically_similar_to，标记为INFERRED）已经存在于图中，会直接参与塑造社区形状——因此图谱结构本身就是相似度信号，无需单独的 embedding 步骤或向量数据库。
• 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、source_file；连接 3 个以上节点的超边存放在G.graph["hyperedges"]。

三、边置信体系：EXTRACTED / INFERRED / AMBIGUOUS 三级标注

每一条关系都被打上三个标签之一，让你始终能分清「读到的」和「猜的」：

EXTRACTED边的置信恒为 1.0；INFERRED边使用一套离散评分细则（docs/how-it-works.md 定义，并由 tests/test_inferred_confidence_rubric.py 中的RUBRIC = {0.55, 0.65, 0.75, 0.85, 0.95}测试固化）：

• 0.95— 近乎确定（显式跨文件引用，只有一个可能的目标）
• 0.85— 强证据（命名与上下文都对齐）
• 0.75— 合理（上下文推断但非显式）
• 0.65— 弱（仅命名相似）
• 0.55— 猜测

从源码结构看，EXTRACTED与INFERRED的边界判据非常严格：graphify/extract.py 中，接收者类型在源码里被显式写出（如Type.method()、Foo::bar()）的调用判定为EXTRACTED，而类型来自本地推断（如obj.method()）的调用则判为INFERRED——这与文档「EXTRACTED = 源中明确写出」的定义一一对应。

四、安装：包名陷阱与各平台命令对照

前置要求：Python 3.10+，以及上述任一 AI 编码助手。

# 推荐 — 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*包均与本项目无关。用uvx运行时必须指明包名：uvx --from graphifyy graphify install——因为uv tool run会把第一个词当作包名解析，直接uvx graphify会报「No solution found」。

平台安装命令对照

各平台的 skill 文件并非手写，而是由仓库内的生成器统一产出：tools/skillgen/ 按平台配置生成skill-*.md与always_on/下的常驻指令文件（如 graphify/always_on/claude-md.md），并由 tools/expected/ 下的快照文件做一致性校验。

安装完成后，打开你的 AI 助手，输入：

/graphify .

注意：Codex 用$而不是/来调用技能，因此应输入$graphify .；PowerShell 中开头的/会被当作路径分隔符，应使用graphify .。

让助手始终走图谱（推荐）

图谱构建完成后，在项目里执行一次对应平台的「常驻指令」安装，助手遇到代码库问题时就会优先查图谱而不是逐个读文件：

从源码结构看，这类安装会向平台写入一份「查询优先」的引导配置；钩子型平台（如 Claude Code）还会注册PreToolUse钩子，在搜索类工具调用前把助手引向graphify query，而纯指令文件型平台（Codex、OpenCode、Cursor 等）则通过AGENTS.md、.cursor/rules/等持久化指令文件提供同样的引导。

五、完整命令速查：构建、更新、查询

原文档列出的常用命令全量继承如下，每条都可直接在助手对话或终端中使用：

/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 库（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 钩子 graphify update ./src # 只重提取代码文件，不经过 LLM graphify watch ./src # 文件变化时自动更新图谱

其中query/path/explain三个命令全部直接作用于graph.json，无需重读原始文件。README 中给出的真实示例（graphify 跑在 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

六、每次运行你能得到什么

• 上帝节点——度数最高的概念（一切都经过它们）；
• 惊人连接——按复合分数排序的跨模块关联，代码-文章边获得更高评分，每条结果附一段自然语言的「为什么」；
• 建议问题——4–5 个该图谱特别擅长回答的问题；
• 「为什么」——docstring、行内注释（# NOTE:、# IMPORTANT:、# HACK:、# WHY:）与设计理由被提取为rationale_for节点并链接到所解释的代码；
• 置信分数——每条INFERRED边都带confidence_score（0.0–1.0）；
• token 基准——每次运行后自动打印。在混合语料上，每次查询比直接读原始文件少71.5 倍token。docs/how-it-works.md 给出了基准明细：52 文件混合语料（Karpathy 仓库 + 5 篇论文 + 4 张图片）为 71.5x，4 文件语料约 5.4x，6 文件的小库约 1x——token 节省随语料规模增长，小语料的价值在于结构清晰度而非压缩。仓库中每个worked/目录都保留了原始输入与真实输出（如 worked/httpx/graph.json、worked/karpathy-repos/GRAPH_REPORT.md），可自行复现验证；
• 自动同步（--watch）——代码修改时自动更新图谱，实现在 graphify/watch.py；
• Git 钩子（graphify hook install）——安装 post-commit 与 post-checkout 两个钩子。从源码看（graphify/hooks.py），安装时还会注册一个 merge driver，让graph.json在两人同时提交时自动做并集合并，不会出现冲突标记；钩子在安装时把当前解释器路径直接嵌入脚本，因此即使在~/.local/bin不在 PATH 的 GUI git 客户端或 CI 中也能触发，且支持GRAPHIFY_SKIP_HOOK=1跳过。

七、增量缓存：SHA256 指纹与「只重跑改过的文件」

graphify-out/cache/目录的机制在 docs/how-it-works.md 中概括为：每个已提取文件都按内容哈希做指纹，重跑时完全跳过未变更文件。源码印证了实现细节（graphify/cache.py、graphify/cache.py）：缓存键是文件内容 + 相对路径的 SHA256，条目以graphify-out/cache/{kind}/{hash}.json形式落盘；首次遇到文件时走完整 SHA256，之后可用轻量指纹快速判定未变更。这也是--update增量模式与 Git 钩子后台重建之所以低成本的底层原因。

八、隐私边界：什么本地处理，什么发往模型

• 代码文件——tree-sitter 本地解析，不出你的机器。纯代码语料无需任何 API key；混合仓库可用--code-only只索引代码，跳过需要 LLM 的文档/PDF/图片；
• 音视频——faster-whisper 本地转录，不出机器；
• 文档、PDF、图片——会发送到你的 AI 助手的模型 API 做语义提取（经由/graphify技能，使用你 IDE 会话正在运行的模型）；
• 无遥测、无使用追踪、无分析。

九、技术栈与延伸阅读

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

围绕本主题，仓库中以下路径适合继续深入：

• docs/how-it-works.md——三遍管线、Leiden 社区检测、置信度细则、token 基准的完整说明；
• graphify/extract.py——确定性 AST 提取与EXTRACTED/INFERRED判定（约 7300 行，项目最大模块）；
• graphify/cluster.py——Leiden → graspologic → Louvain 的聚类降级链；
• graphify/cache.py——SHA256 缓存与增量提取；
• graphify/hooks.py、graphify/watch.py——Git 钩子与自动同步；
• tests/test_inferred_confidence_rubric.py——置信评分细则的回归测试；
• tests/test_hooks.py、tests/test_watch.py——钩子与监控机制的行为验证。

适用前提与限制：上述平台命令、包名graphifyy、Python 3.10+ 要求均基于当前仓库的 README 与pyproject.toml；Leiden 需安装 graspologic（可选依赖），否则自动降级到 Louvain，社区划分结果可能略有差异；71.5x 的 token 节省是仓库在 52 文件混合语料上测得并公开可复现的基准数据，小语料下节省幅度会显著缩小。

【免费下载链接】graphifyTurn 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