graphify 实战指南：让 Claude Code、Codex 等 AI 助手把代码库变成可查询的知识图谱

graphify 是一个面向 AI 编码助手的 /graphify 技能：在 Claude Code、Codex、OpenCode、OpenClaw 或 Factory Droid 中输入一条命令，它就把一个文件夹里的代码、文档、论文、截图解析成一张可持久化、可查询的知识图谱，并用确定性的 tree-sitter AST 解析保证"每条边都能解释来源"。本文完整覆盖 graphify 的构建原理、安装配置、全量命令参数、输出产物与隐私边界，并结合仓库源码（graphify/detect.py、graphify/cluster.py、graphify/benchmark.py 等）说明每个机制背后的实现依据，读完后你可以直接在任意代码库上复现"71.5 倍 token 削减"的效果。

定位：解决 Karpathy 式 /raw 文件夹的问题

项目作者引用了一个真实场景：Andrej Karpathy 有一个装满论文、推文、截图和笔记的 /raw 文件夹——而 graphify 正是为这类问题设计的。它与传统"让 LLM 逐文件读"的区别有三点（见 README 日文版 与 docs/how-it-works.md）：

• 每查询 token 数比直接读原始文件少 71.5 倍（混合语料基准，见下文"实例"一节）；
• 跨会话持久化：图谱保存在 graphify-out/graph.json，数周后重新查询无需重建；
• 诚实区分"找到的"与"推测的"：每条边都带 EXTRACTED / INFERRED / AMBIGUOUS 标签。

它完全多模态：代码、PDF、Markdown、截图、图表、白板照片乃至非英语图片都可以通过 Claude Vision 抽出概念与关系，汇入同一张图。代码一侧则由 tree-sitter AST 支持 19 种语言（Python、JS、TS、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、Elixir、Objective-C），从 pyproject.toml 的依赖清单可以看到每一种语言都对应一个 tree-sitter-* 语法包。

输出结构与 .graphifyignore 排除规则

对任意文件夹执行 /graphify . 后，产物固定在 graphify-out/ 下：

graphify-out/
├── graph.html       交互式图谱 - 点击节点、搜索、按社区过滤
├── GRAPH_REPORT.md  上帝节点、意外连接、推荐问题
├── graph.json       持久化图谱 - 无需重新读取即可随时查询
└── cache/           SHA256 缓存 - 重跑时只处理变更过的文件

cache/ 中每个被抽取的文件都带内容哈希指纹，重跑时完全跳过未变更文件。不想让某些文件夹进入图谱时，在项目根放一个 .graphifyignore：

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

语法与 .gitignore 完全相同，模式相对于执行 graphify 的文件夹匹配。源码层面可以确认几个细节（graphify/detect.py）：

• .gitignore 与 .graphifyignore 会被合并读取，且 .gitignore 先读、.graphifyignore 后读——后者优先级更高，意味着 .graphifyignore 只能排除更多文件，不能反包含已被 .gitignore 排除的路径；
• 模式沿目录祖先链逐级加载（_load_graphifyignore），子目录可以有自己的 ignore 文件；
• 扫描时会被 ignore 规则丢弃的文件会被记录进检测结果的 warning 字段，detect() 返回的摘要里还有 graphifyignore_patterns 计数（graphify/detect.py），方便排查"为什么某文件没进图"。

工作原理：双路径抽取 + 基于图拓扑的 Leiden 社区检测

graphify 是两条路径（pass）的组合：

1. 确定性 AST 路径（无 LLM）：tree-sitter 解析代码文件，抽出类、函数、导入、调用图、docstring 和"理由"注释，全程本地运行、不花 token。从 docs/how-it-works.md 可以确认：纯代码语料会完全跳过语义抽取路径，语义路径只服务于文档、论文、图片与转录文本。
2. Claude 子代理路径（花费 token）：并行子代理处理文档、论文、图片，输出 JSON 片段（nodes/edges/超边），合并入同一张图。

两条路径的结果合并到一张 NetworkX 图，做 Leiden 社区检测，再导出为交互式 HTML、可查询 JSON 和"人话"审计报告。完整管线在 ARCHITECTURE.md 中有固定说明：

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

各阶段通过普通 Python dict 和 NetworkX 图通信，无共享状态；validate.py 会在 build() 之前强制校验抽取输出的 schema（nodes/edges 结构）。

为什么不需要向量数据库

这是 graphify 与普通 RAG 最大的架构差异：聚类基于图拓扑而非嵌入。Leiden 算法按边密度把节点聚成社区，而 Claude 抽出的语义相似边（semantically_similar_to，标记为 INFERRED）已经直接存在于图中，因此社区形状天然受语义信号影响——图结构本身就是相似性信号，无需单独的嵌入步骤或向量库。

从 graphify/cluster.py 的实现看，有几处工程细节值得注意：

• 首选 Leiden（graspologic），不可用时回退到 NetworkX 内置的 Louvain；
• _native_leiden() 直接调用 graspologic_native 的 Rust 实现，绕开 graspologic 完整包的导入——注释中写明这是为了避开 umap/pynndescent/numba 导入链的 7~19 秒一次性开销；
• 模块 docstring 声明它会拆分超大社区并返回各社区的凝聚度（cohesion）分数，这两个数据会进入 GRAPH_REPORT.md。

对应地，pyproject.toml 中 Leiden 是可选依赖 leiden = ["graspologic; python_version < '3.13'"]：Python 3.13 及以上不装 graspologic 时，社区检测自动落到 Louvain 回退路径。

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

所有关系被三标签之一标记（与 ARCHITECTURE.md 的"Confidence labels"一致）：

标签	含义
EXTRACTED	关系直接来自源码（导入语句、直接调用等），置信度恒为 1.0
INFERRED	合理推断（如调用图二遍解析、上下文中共现），附带 confidence_score（0.0~1.0）
AMBIGUOUS	不确定，在 GRAPH_REPORT.md 中被标记为待人工复核

docs/how-it-works.md 进一步给出了 INFERRED 的离散评分标尺：0.95（近乎确定，显式跨文件引用且只有唯一合理目标）、0.85（命名与上下文一致）、0.75（上下文合理但非显式）、0.65（仅命名相似）、0.55（推测）。测试 tests/test_inferred_confidence_rubric.py 对这套标尺做了回归验证。

安装与平台支持

前置条件：Python 3.10+（pyproject.toml 中 requires-python = ">=3.10"）以及下列助手之一：Claude Code、Codex、OpenCode、OpenClaw、Factory Droid。

pip install graphifyy && graphify install

注意：因为 PyPI 上 graphify 这个名字正等待重新启用，包名暂时是 graphifyy。CLI 和技能命令本身仍然是 graphify。pyproject.toml 中也确认了两个可执行入口：graphify（graphify.__main__:main）和 graphify-mcp（graphify.serve:_main）。

各平台安装命令：

平台	安装命令
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
OpenClaw	graphify install --platform claw
Factory Droid	graphify install --platform droid

平台级注意事项：

• Codex 用户还需在 ~/.codex/config.toml 的 [features] 下设置 multi_agent = true 以启用并行抽取；
• Factory Droid 使用 Task 工具做并行子代理派发；
• OpenClaw 目前使用顺序抽取（该平台并行代理支持仍处于早期阶段）。

然后打开助手输入 /graphify . 即可。Codex 的技能调用用 $ 而不是 /，即输入 $graphify .。

从源码看，graphify/install.py 的 install(platform="claude", ...) 负责把技能文件复制到对应平台的技能目录、并在 CLAUDE.md（或对应平台的 AGENTS.md）中登记技能引用；重复执行是幂等的——检测到已注册内容时打印 already registered (no change) 而不重复写入。

手动安装

不装 pip 包也可以：把仓库中的技能源文件 graphify/skill.md 放到技能目录（例如 ~/.claude/skills/graphify/SKILL.md），再在 ~/.claude/CLAUDE.md 追加一段登记：

- **graphify** (`~/.claude/skills/graphify/SKILL.md`) - any input to knowledge graph. Trigger: `/graphify`
When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else.

让助手"永远"使用图谱（always-on）

建好图谱后，在项目里执行一次对应的 always-on 命令：

平台	命令
Claude Code	graphify claude install
Codex	graphify codex install
OpenCode	graphify opencode install
OpenClaw	graphify claw install
Factory Droid	graphify droid install

Claude Code 上它会做两件事：向 CLAUDE.md 写入一段"回答架构问题前先读 graphify-out/GRAPH_REPORT.md"的指令；并在 settings.json 中安装一个 PreToolUse 钩子——所有 Glob 和 Grep 调用之前触发。图谱存在时，Claude 会收到提示："Knowledge graph exists. Read GRAPH_REPORT.md for god nodes and community structure before searching raw files."，于是它通过图谱导航而不是 grep 全部文件。

Codex、OpenCode、OpenClaw、Factory Droid 不支持 PreToolUse 钩子，因此相同的规则被写入项目根的 AGENTS.md，由该文件作为常驻机制。

卸载对应用对应的 uninstall 命令，如 graphify claude uninstall。

always-on 与显式触发的分工：

• always-on 钩子把 GRAPH_REPORT.md 顶到助手眼前——一页纸的上帝节点、社区与意外连接摘要，覆盖日常问题的"方向感"；
• /graphify query、/graphify path、/graphify explain 则更深：逐跳遍历原始 graph.json、追踪节点间的精确路径、给出边级细节（关系类型、置信度、源码位置）。

官方给出的心智模型是：always-on 钩子给助手一张地图，/graphify 命令让它精确地导航这张地图。

完整命令参考

/graphify                          # 在当前目录执行
/graphify ./raw                    # 在指定文件夹执行
/graphify ./raw --mode deep        # 更积极地抽取 INFERRED 边
/graphify ./raw --update           # 只重抽变更文件，合并进现有图谱
/graphify ./raw --cluster-only     # 仅对现有图谱重跑聚类（不重抽）
/graphify ./raw --no-viz           # 跳过 HTML，只出报告 + JSON
/graphify ./raw --obsidian                          # 额外生成 Obsidian 仓库（opt-in）
/graphify ./raw --obsidian --obsidian-dir ~/vaults/myproject  # 指定仓库输出目录

/graphify add https://arxiv.org/abs/1706.03762        # 抓取论文、保存并更新图谱
/graphify add https://x.com/karpathy/status/...       # 抓取推文
/graphify add https://... --author "Name"             # 标注原始作者
/graphify add https://... --contributor "Name"        # 标注加入语料的人

/graphify query "连接 attention 和 optimizer 的是什么？"
/graphify query "..." --dfs   # 追踪具体路径
/graphify query "..." --budget 1500  # 限制答案在 N token 内
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"

/graphify ./raw --watch            # 文件变更时自动同步（代码即时、文档发通知）
/graphify ./raw --wiki             # 生成 agent 可爬取的 wiki（index.md + 每社区文章）
/graphify ./raw --svg              # 导出 graph.svg
/graphify ./raw --graphml          # 导出 graph.graphml（Gephi、yEd）
/graphify ./raw --neo4j            # 生成 Neo4j 用的 cypher.txt
/graphify ./raw --neo4j-push bolt://localhost:7687    # 直推运行中的 Neo4j
/graphify ./raw --mcp              # 启动 MCP stdio 服务器

# git 钩子 - 平台无关，提交/切分支时重建图谱
graphify hook install
graphify hook uninstall
graphify hook status

# always-on 助手指令 - 平台特定
graphify claude install            # CLAUDE.md + PreToolUse 钩子（Claude Code）
graphify claude uninstall
graphify codex install             # AGENTS.md（Codex）
graphify opencode install          # AGENTS.md（OpenCode）
graphify claw install              # AGENTS.md（OpenClaw）
graphify droid install             # AGENTS.md（Factory Droid）

# 无需 AI 助手，直接在终端查询
graphify query "连接 attention 和 optimizer 的是什么？"
graphify query "展示认证流程" --dfs
graphify query "CfgNode 是什么？" --budget 500
graphify query "..." --graph path/to/graph.json

各导出格式由 graphify/export.py 中"一格式一函数"的实现提供（to_json、to_html、to_obsidian、to_svg、to_graphml、to_canvas、to_cypher），wiki 则由 graphify/wiki.py 的 to_wiki() 生成。--mcp 背后是 graphify/serve.py 的 serve()（stdio）/ serve_http()；--neo4j-push 与 --mcp 需要安装对应 extras（pyproject.toml：neo4j = ["neo4j"]、mcp = ["mcp>=1,<3", "starlette>=1.3.1,<2"]、watch = ["watchdog"]、svg = ["matplotlib", ...]）。

混合任意文件类型都能工作：

类型	扩展名	抽取方式
代码	.py .ts .js .go .rs .java .c .cpp .rb .cs .kt .scala .php .swift .lua .zig .ps1 .ex .exs .m .mm	tree-sitter AST + 调用图 + docstring/注释中的"理由"
文档	.md .txt .rst	Claude 抽概念 + 关系 + 设计依据
Office	.docx .xlsx	先转 Markdown 再交给 Claude（需 pip install graphifyy[office]）
论文	.pdf	引用挖掘 + 概念抽取
图片	.png .jpg .webp .gif	Claude Vision —— 截图、图表、任意语言

对应地，PDF 解析需要 [pdf] extra（pypdf + markdownify），Office 需要 [office] extra（python-docx + openpyxl），见 pyproject.toml。

你会得到什么：图谱报告的核心要素

• 上帝节点（God nodes）——度最高的概念，"一切都连接到的东西"；
• 意外连接——按复合分数排序；代码↔论文的边比代码↔代码的边排名更高；每条附一句人话理由；
• 推荐问题——图谱恰好能独家回答的 4~5 个问题；
• "为什么"——docstring、行内注释（# NOTE:、# IMPORTANT:、# HACK:、# WHY:）和文档中的设计依据被抽成 rationale_for 节点。图谱回答的不只是"代码做了什么"，还有"它为什么这样写"；
• 置信度分数——每条 INFERRED 边都有 confidence_score，EXTRACTED 恒为 1.0；
• 语义相似边——无结构连接的跨文件概念链接：两个互不调用但解决同一问题的函数，或代码中的类与论文中描述同一算法的概念；
• 超边（Hyperedge）——连接 3 个以上节点的组关系，表达成对边无法表达的结构：实现同一协议的所有类、认证流程中的所有函数、论文中构成一个想法的一组概念。从源码结构看，超边存放在 G.graph["hyperedges"]（docs/how-it-works.md "The graph format" 一节），并有专门的往返与去重重映射测试（tests/test_hyperedge_roundtrip.py、tests/test_dedup_remaps_hyperedges.py）。

自动同步（--watch）：在后台终端运行，代码文件保存立即触发重建（纯 AST、无 LLM），文档/图片变更则提示运行 --update 做 LLM 重抽。实现见 graphify/watch.py 的 watch(watch_path, debounce=3.0)，启动时会一次性加载 .graphifyignore 模式以便事件处理路径快速匹配。

Git 钩子（graphify hook install）：安装 post-commit 与 post-checkout 钩子，每次提交、每次切分支自动重建图谱；重建失败时钩子以非零码退出，让 git 把错误暴露出来而不是静默跳过——不需要后台进程。

Wiki（--wiki）：按社区和上帝节点生成 Wikipedia 风格 Markdown 文章加 index.md 入口。把任何 agent 指向 index.md，它就能通过读文件而不是解析 JSON 来导航知识库。

实例与 token 削减：数字如何验证

仓库 worked/ 目录下有三个公开实例（每个都带原始输入文件与实际输出 GRAPH_REPORT.md、graph.json，可自行复跑验证）：

语料	文件数	削减率	输出
Karpathy 仓库 + 5 篇论文 + 4 张图	52	71.5x	worked/karpathy-repos/
graphify 源码 + Transformer 论文	4	5.4x	worked/mixed-corpus/
httpx（合成 Python 库）	6	~1x	worked/httpx/

token 削减随语料规模放大：6 个文件本来就装得进上下文窗口，图谱的价值是结构清晰度而非压缩；52 个文件（代码+论文+图片）时节省达 71 倍以上。基准的测量逻辑在 graphify/benchmark.py：run_benchmark() 对比"整语料 token 数"与"单次查询 token 数"，输出 reduction_ratio（corpus_tokens / avg_query_tokens）及逐问题明细。

第一次运行做抽取和建图（花 token），之后的每次查询只读紧凑图谱——节省从这里开始复利积累。worked/karpathy-repos/README.md 给出了 71.5x 语料的完整构成：3 个代码仓库（nanoGPT、minGPT、micrograd）、5 篇 attention 相关论文、4 张图，共 52 个文件。

隐私与技术栈

隐私边界（与 README 日文版 "Privacy" 一节一致）：

• 文档、论文、图片的语义抽取会把内容发往 AI 助手所用的底层模型 API（Claude Code 对应 Anthropic、Codex 对应 OpenAI，或其他平台自带供应商）；
• 代码文件例外：代码完全在本地经 tree-sitter AST 处理，代码内容不会离开机器；
• 无遥测、无使用追踪、无分析；唯一的网络调用是抽取期间对你自己 API key 对应模型 API 的调用。

所有外部输入在 graphify/security.py 中过校验：URL 仅允许 http/https 且屏蔽 file:// 重定向，抓取内容有大小上限与超时，图文件路径必须解析在 graphify-out/ 内，节点标签会剥离控制字符并截断到 256 字符（详见 SECURITY.md 的威胁模型）。

技术栈：NetworkX + Leiden（graspologic）+ tree-sitter + vis.js；语义抽取由 Claude（Claude Code）、GPT（Codex）或平台运行模型完成。不需要 Neo4j、不需要服务器，完全本地运行（--neo4j 是可选导出，不是依赖）。

继续深入

• 想了解模块职责、extract() 的调用约定（注意 root 参数是 keyword-only 且建议显式传入）、新增语言抽取器的五步流程，读 ARCHITECTURE.md——其中函数签名表由 tests/test_architecture_doc.py 强制与代码同步；
• 想理解三遍处理、置信度标尺、SHA256 缓存和 graph.json 格式细节，读 docs/how-it-works.md；
• 想复现基准数字，从 worked/karpathy-repos/ 的 README 按清单备齐语料即可。