graphify：把代码库、文档与论文变成可查询知识图谱的 /graphify 技能全解

本文基于 graphify 仓库的中文主文档，完整覆盖其核心内容：两遍式提取与基于图拓扑的社区聚类原理（不依赖 embeddings、不依赖向量库）、多平台安装与常驻助手规则、/graphify 全套构建/增量/查询/导出命令及其参数，并结合仓库源码（graphify/cli.py、graphify/cluster.py、graphify/extract.py 等）印证关键实现。读完后你可以完成从安装 skill、构建图谱、配置"图谱优先"助手行为，到用 query/path/explain 精确查询图谱的完整实操。

一、graphify 是什么：面向 AI 编码助手的技能

graphify 是一个面向 AI 编码助手的技能（skill）。在 Claude Code、CodeBuddy、Codex、OpenCode、OpenClaw、Factory Droid 或 Trae 中输入 /graphify，它会读取你的文件、构建知识图谱，并把原本不明显的结构关系还给你：更快理解代码库，找到架构决策背后的"为什么"。

它完全多模态：代码、PDF、Markdown、截图、流程图、白板照片，甚至其他语言的图片都可以丢进去——graphify 会用 Claude vision 从这些内容中提取概念和关系，并连接到同一张图里。

项目文档引用了一个典型场景：Andrej Karpathy 会维护一个 /raw 文件夹，把论文、推文、截图和笔记都丢进去。graphify 解决的就是这类问题——相比直接读取原始文件，每次查询的 token 消耗可降低 71.5 倍，结果还能跨会话持久保存，并且会明确区分哪些内容是实际发现的、哪些只是合理推断。

一次运行后你会得到如下产物：

/graphify .                        # 可用于任意目录：代码库、笔记、论文都可以

graphify-out/
├── graph.html       可交互图谱：可点节点、搜索、按社区过滤
├── GRAPH_REPORT.md  God nodes、意外连接、建议提问
├── graph.json       持久化图谱：数周后仍可查询，无需重新读原始文件
└── cache/           SHA256 缓存：重复运行时只处理变更过的文件

其中 SHA256 缓存的实现在 cache.py：file_hash、check_semantic_cache、save_semantic_cache 等函数按文件内容哈希决定哪些文件需要重新提取，这也是"重复运行时只处理变更文件"的底层保证。

二、工作原理：两遍提取 + 拓扑聚类，全程无向量库

2.1 第一轮：确定性 AST 提取（不需要 LLM）

graphify 分两轮执行。第一轮是确定性的 AST 提取，对代码文件做结构分析：类、函数、导入、调用图、docstring、解释性注释——这一轮完全不需要 LLM，代码内容不出本机。

从源码看，这一轮由 extract.py 驱动：extract() 入口按文件扩展名选择提取器，_extract_parallel / _extract_sequential 并行或串行处理未命中缓存的文件；各语言提取器集中在 graphify/extractors/ 目录下（Go、Rust、C#、SQL、Terraform、Verilog、Zig 等），公共的树遍历与调用解析引擎在 extractors/engine.py。仓库 tests/ 目录下有成百上千个针对提取与符号解析的测试（如 test_extract.py），对应这套提取器覆盖面。

2.2 第二轮：并行语义提取（文档、论文、图片）

第二轮会并行调用子代理处理文档、论文和图片，从中提取概念、关系和设计动机。对应实现是 llm.py 的 extract_corpus_parallel：按 token 预算把文件打包成 chunk（_pack_chunks_by_tokens，默认预算 60,000 tokens），以受控并发调用后端模型，并带自适应重试与部分失败标记（_extract_with_adaptive_retry、_mark_partial）。

2.3 合并与社区发现：NetworkX + Leiden，基于拓扑而非 embeddings

最后把两边结果合并到一个 NetworkX 图里，用 Leiden 社区发现算法做聚类，并导出成可交互 HTML、可查询 JSON，以及一份人类可读的审计报告。

聚类是基于图拓扑完成的，不依赖 embeddings。 Leiden 按边密度发现社区；Claude 抽取出的语义相似边（semantically_similar_to，标记为 INFERRED）本来就存在于图中，所以会直接影响社区划分。图结构本身就是相似性信号，不需要额外的 embedding 步骤，也不需要向量数据库。

cluster.py 印证了这一点：_partition(G, resolution=1.0) 先尝试原生 Leiden 快速路径（_native_leiden），失败再回落到 graspologic 的 leiden()；cluster() 的 docstring 明确写出调参语义——resolution > 1.0 得到更多更小的社区，resolution < 1.0 得到更少更大的社区。聚类完成后的 cohesion_score / score_all 为每个社区计算内聚度分数，label_communities_by_hub 则在不调用 LLM 的情况下按枢纽节点给社区起名。

2.4 每条边都有置信度标签

每条关系都会被标记为：

• EXTRACTED：直接在源材料中找到；
• INFERRED：合理推断，并附带置信度分数；
• AMBIGUOUS：有歧义，需要复核。

所以你始终知道哪些是实际发现的，哪些是模型猜出来的。每条 INFERRED 边都有 confidence_score（0.0–1.0），EXTRACTED 边恒为 1.0。

三、安装

要求： Python 3.10+，并且使用以下平台之一：Claude Code、CodeBuddy、Codex、OpenCode、OpenClaw、Factory Droid 或 Trae。

pip install graphifyy && graphify install

注意包名： PyPI 包当前暂时叫 graphifyy（双 y），因为 graphify 这个名字还在回收中。CLI 命令和 skill 命令仍然都是 graphify。当前 README.md 还推荐用 uv tool install graphifyy 或 pipx install graphifyy 做隔离环境安装，以避免 pip install 在 macOS/Windows 上出现的 Python 解析问题。

平台支持

平台	安装命令
Claude Code	graphify install
CodeBuddy	graphify install --platform codebuddy
Codex	graphify install --platform codex
OpenCode	graphify install --platform opencode
OpenClaw	graphify install --platform claw
Factory Droid	graphify install --platform droid
Trae	graphify install --platform trae
Trae CN	graphify install --platform trae-cn

平台安装逻辑集中在 install.py：install(platform, project=...) 负责把 skill 文件复制到各平台约定目录，claude_install / codebuddy_install / _install_codex_hook 等函数分别处理各平台的常驻规则与 hook 注册。

各平台差异要点（与文档一致）：

• Codex 用户还需要在 ~/.codex/config.toml 的 [features] 下打开 multi_agent = true，这样才能并行提取；
• CodeBuddy 使用与 Claude Code 相同的 Agent 工具和 PreToolUse hook 机制；
• OpenClaw 目前的并行 agent 支持还比较早期，所以使用顺序提取；
• Trae 使用 Agent 工具进行并行子代理调度，不支持 PreToolUse hook，因此 AGENTS.md 是其常驻机制。

说明：本文档（中文版 README）列出的是首批 8 个平台；当前仓库 README.md 的平台表已扩展到 20+ 个助手（Gemini CLI、Cursor、GitHub Copilot、Aider、Kilo Code、Devin CLI 等），安装方式同样是 graphify install --platform <name> 或各平台子命令（如 graphify gemini install）。以当前仓库 README 的"Pick your platform"表为准。

然后打开你的 AI 编码助手，输入：

/graphify .

手动安装（skill.md 方式）

不经过 pip 也可以手动安装：把仓库中的 skill 定义文件（当前仓库内的 skill.md）保存为 ~/.claude/skills/graphify/SKILL.md，即等效于文档给出的：

mkdir -p ~/.claude/skills/graphify
# 将仓库 v3 分支的 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.

四、让助手始终优先使用图谱（推荐）

图构建完成后，在项目里运行一次常驻规则安装命令：

平台	命令
Claude Code	graphify claude install
CodeBuddy	graphify codebuddy install
Codex	graphify codex install
OpenCode	graphify opencode install
OpenClaw	graphify claw install
Factory Droid	graphify droid install
Trae	graphify trae install
Trae CN	graphify trae-cn install

Claude Code 会做两件事：

1. 在 CLAUDE.md 中写入一段规则，告诉 Claude 在回答架构问题前先读 graphify-out/GRAPH_REPORT.md；
2. 安装一个 PreToolUse hook（写入 settings.json），在每次 Glob 和 Grep 前触发。

如果知识图谱存在，Claude 会先看到："graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files."——这样 Claude 会优先按图谱导航，而不是一上来就 grep 整个项目。hook 的注入逻辑在 install.py 的 _claude_pretooluse_hooks / _install_claude_hook 中。

CodeBuddy 与 Claude Code 相同：在 CODEBUDDY.md 中写入规则，并安装 PreToolUse hook（写入 .codebuddy/settings.json），在每次 Glob 和 Grep 前触发（对应 _install_codebuddy_hook）。

Codex、OpenCode、OpenClaw、Factory Droid、Trae 会把同样的规则写进项目根目录的 AGENTS.md。这些平台没有 PreToolUse hook，所以 AGENTS.md 是它们的常驻机制（_agents_install）。

卸载时使用对应平台的 uninstall 命令即可（例如 graphify claude uninstall）。

常驻模式和显式触发有什么区别？

常驻 hook 会优先暴露 GRAPH_REPORT.md——这是一页式总结，包含 god nodes、社区结构和意外连接。你的助手在搜索文件前会先读它，因此会按结构导航，而不是按关键字乱搜。这已经能覆盖大部分日常问题。

/graphify query、/graphify path 和 /graphify explain 会更深入：它们会逐跳遍历底层 graph.json，追踪节点之间的精确路径，并展示边级别细节（关系类型、置信度、源位置）。当你想从图谱里精确回答某个问题，而不仅仅是获得整体感知时，就该用这些命令。

可以这样理解：常驻 hook 是先给助手一张地图，/graphify 这几个命令则是让它沿着地图精确导航。

五、用法：完整命令与参数

/graphify                          # 对当前目录运行
/graphify ./raw                    # 对指定目录运行
/graphify ./raw --mode deep        # 更激进地抽取 INFERRED 边
/graphify ./raw --update           # 只重新提取变更文件，并合并到已有图谱
/graphify ./raw --cluster-only     # 只重新聚类已有图谱，不重新提取
/graphify ./raw --no-viz           # 跳过 HTML，只生成 report + JSON
/graphify ./raw --obsidian         # 额外生成 Obsidian vault（可选）

/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 "what connects attention to the optimizer?"
/graphify query "what connects attention to the optimizer?" --dfs   # 追踪一条具体路径
/graphify query "what connects attention to the optimizer?" --budget 1500  # 把预算限制在 N tokens
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"

/graphify ./raw --watch            # 文件变更时自动同步图谱（代码：立即更新；文档：提醒你）
/graphify ./raw --wiki             # 构建可供 agent 抓取的 wiki（index.md + 每个 community 一篇文章）
/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 server

# git hooks - 跨平台，在 commit 和切分支后重建图谱
graphify hook install
graphify hook uninstall
graphify hook status

# 常驻助手规则 - 按平台区分
graphify claude install            # CLAUDE.md + PreToolUse hook（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）
graphify trae install               # AGENTS.md（Trae）
graphify trae uninstall
graphify trae-cn install            # AGENTS.md（Trae CN）
graphify trae-cn uninstall

5.1 增量更新与只聚类

--update 只重新提取变更文件并合并进已有图谱；--cluster-only 只重新聚类，不重新提取。从源码看，cli.py 中 update 命令走 watch.py 的 _rebuild_code（纯 AST 路径，提示语明确写着 "Re-extracting code files ... (no LLM needed)"），而 cluster-only 会读取现有 graph.json 重新跑 Leiden 聚类并刷新 GRAPH_REPORT.md 与 graph.json，同时把新的社区编号映射回旧编号以保持报告稳定。--no-viz 时只保留 GRAPH_REPORT.md 和 graph.json，并移除 graph.html。

5.2 语料积累：/graphify add

/graphify add <url> 支持拉取 arXiv 论文、推文和一般网页，保存进语料目录并更新图谱；--author 标记原作者，--contributor 标记是谁把内容加入语料库的。实现在 ingest.py：_fetch_arxiv / _fetch_tweet / _fetch_webpage 按 URL 类型分派（_detect_url_type），统一走 ingest() 入口，网络请求经过 security.py 的 safe_fetch 做主机名与大小限制。

5.3 查询图谱：query / path / explain

graphify query "<question>" 对 graph.json 做一次作用域子图查询。从 cli.py 看，其用法签名为 graphify query "<question>" [--dfs] [--context C] [--budget N] [--graph path]，其中 --budget 的默认值为 2000 tokens（budget = 2000），即返回的文本超过预算时会截断并给出收窄提示。--dfs 切换到深度优先遍历以追踪一条具体路径；graphify path A B 计算两点间最短路径；graphify explain <concept> 打印单个节点的来源、社区、度数和逐条连接（含关系与置信度标签）。查询的文本化实现在 serve.py 的 _query_graph_text / _bfs / _dfs / _subgraph_to_text 中，MCP 形态下以 query_graph、shortest_path、god_nodes 等工具暴露。

5.4 自动同步与导出

• --watch：后台监听文件变更。watch.py 的 watch(watch_path, debounce=3.0) 带防抖；代码文件保存会立刻触发 _rebuild_code（只走 AST，不用 LLM）；文档/图片变更则会提醒你跑 --update 进行 LLM 再提取（_batch_needs_llm_flag）。
• graphify hook install：安装 post-commit 和 post-checkout git hook，每次 commit 后、每次切分支后自动重建图谱，不需要额外开一个后台进程。实现在 hooks.py 的 install() / uninstall() / status()；hook 脚本在安装时内嵌当前解释器路径，所以 GUI git 客户端和 CI 里 ~/.local/bin 不在 PATH 也能触发，升级 graphify 后建议重跑 graphify hook install 刷新路径。
• --wiki：为每个 community 和 god node 生成类似维基百科的 Markdown 文章，并提供 index.md 作为入口。任何 agent 只要读 index.md，就能通过普通文件导航整个知识库，而不必直接解析 JSON。实现在 wiki.py 的 to_wiki。
• --svg / --graphml / --neo4j / --neo4j-push / --obsidian / --mcp：分别导出 SVG、GraphML（Gephi、yEd 可用）、生成/推送 Neo4j 的 Cypher、生成 Obsidian vault（含 graph.canvas）、启动 MCP stdio server。对应实现集中在 export.py（to_svg、to_graphml、to_cypher、to_obsidian、to_canvas）、exporters/graphdb.py（push_to_neo4j、push_to_falkordb）和 serve.py（serve / serve_http）。

5.5 支持混合文件类型

类型	扩展名	提取方式
代码	.py .ts .js .go .rs .java .c .cpp .rb .cs .kt .scala .php	tree-sitter AST + 调用图 + docstring / 注释中的 rationale
文档	.md .txt .rst	通过 Claude 提取概念、关系和设计动机
论文	.pdf	引文挖掘 + 概念提取
图片	.png .jpg .webp .gif	Claude vision —— 截图、图表、任意语言都可以

六、你会得到什么

• God nodes —— 度最高的概念节点（整个系统最容易汇聚到的地方），由 analyze.py 的 god_nodes(G, top_n=10) 计算。
• 意外连接 —— 按综合得分排序，代码-论文之间的边会比代码-代码边权重更高（_surprise_score），每条结果都会附带一段人话解释。
• 建议提问 —— 图谱特别擅长回答的 4 到 5 个问题（suggest_questions）。
• "为什么"（rationale） —— docstring、行内注释（# NOTE:、# IMPORTANT:、# HACK:、# WHY:）以及文档里的设计动机都会被抽取成 rationale_for 节点。从源码看，extract.py 的 _RATIONALE_PREFIXES 实际覆盖的前缀更宽：# NOTE:、# IMPORTANT:、# HACK:、# WHY:、# RATIONALE:、# TODO:、# FIXME:。不只是知道代码"做了什么"，还能知道"为什么要这么写"。
• 置信度分数 —— 每条 INFERRED 边都有 confidence_score（0.0–1.0）。你不只知道哪些是猜出来的，还知道模型对这个猜测有多有把握。EXTRACTED 边恒为 1.0。
• 语义相似边 —— 跨文件的概念连接，即使结构上没有直接依赖也能建立关联。比如两个函数做的是同一类问题但彼此没有调用，或者某个代码类和某篇论文里的算法概念本质相同。
• 超边（Hyperedges） —— 用来表达 3 个以上节点的群组关系，这是普通两两边表达不出来的。比如：一组类共同实现一个协议、认证链路里的一组函数、同一篇论文某一节里的多个概念共同组成一个想法。超边随图谱导出（export.py 的 attach_hyperedges），并在缓存读写中做悬挂检查（hyperedge_dangles）。
• Token 基准 —— 每次运行后都会自动打印，实现在 benchmark.py 的 run_benchmark。对混合语料（Karpathy 的仓库 + 论文 + 图片），每次查询的 token 消耗可以比直接读原文件少 71.5 倍。第一次运行需要先提取并建图，这一步会花 token；后续查询直接读取压缩后的图谱，节省会越来越明显。SHA256 缓存保证重复运行时只重新处理变更文件。
• 自动同步（--watch）—— 在后台终端里跑着，代码库一变化，图谱就会跟着更新（机制见 5.4）。
• Git hooks（graphify hook install）—— 安装 post-commit 和 post-checkout hook，commit 后、切分支后自动重建图谱。
• Wiki（--wiki）—— 见 5.4。

输出样例：看一份真实的 GRAPH_REPORT.md

仓库内置了真实运行结果 worked/karpathy-repos/GRAPH_REPORT.md，其结构与文档描述一一对应：

• Summary 段：285 nodes · 340 edges · 53 communities detected，并给出提取纯度 81% EXTRACTED · 19% INFERRED · 0% AMBIGUOUS 与 token 消耗；
• God Nodes 段：按边数排序的核心抽象，如 Value（15 edges）、Training Script（11 edges）、GPT（9 edges）；
• Surprising Connections 段：跨仓库的推断连接，例如 get_batch() --conceptually_related_to--> get_batch()（nanoGPT 的 train.py 与 bench.py），每条都标注 [INFERRED] 与源文件路径；
• Communities 段：每个社区带 LLM 生成的名字（"nanoGPT Model Architecture"、"FlashAttention Paper"、"BPE Tokenizer"…）与内聚度分数（Cohesion）。

七、Worked examples：可复现的压缩数据

语料	文件数	压缩比	输出
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 个文件本来就塞得进上下文窗口，所以 graphify 在这种场景里的价值更多是结构清晰度，而不是 token 压缩。到了 52 个文件（代码 + 论文 + 图片）这种规模，就能做到 71x+。每个 worked/ 目录里都带了原始输入（raw/）和真实输出（GRAPH_REPORT.md、graph.json，部分含 review.md），你可以自己跑一遍核对数字。

八、隐私边界与技术栈

隐私： graphify 会把文档、论文和图片的内容发送给你所用 AI 编码助手背后的模型 API 来做语义提取——可能是 Anthropic（Claude Code）、OpenAI（Codex），或者你当前平台使用的其他提供方。代码文件则完全在本地通过 tree-sitter AST 处理，不会把代码内容发出去。 项目本身没有任何遥测、使用跟踪或分析。唯一的网络请求就是语义提取阶段调用你平台自己的模型 API，使用的也是你自己的 API key。

技术栈： NetworkX + Leiden（graspologic）+ tree-sitter + vis.js。语义提取由 Claude（Claude Code）、GPT-4（Codex）或你当前平台所运行的模型完成。不需要 Neo4j，不需要 server，整体是纯本地运行；Neo4j/FalkorDB 推送只是可选导出路径。

九、延伸阅读与贡献

• 模块职责和新增语言的方法见 ARCHITECTURE.md；
• 更多基准数据与复现命令见 BENCHMARKS.md；
• skill 的完整指令定义在 graphify/skill.md，各平台变体在 graphify/skills/ 下；
• 中文主文档位于 docs/translations/README.zh-CN.md，同目录另有日、韩、德、法、西等 30 余种语言版本。

贡献方面（与文档一致）：Worked examples 是最能建立信任的贡献方式——对一个真实语料跑 /graphify，把输出保存到 worked/{slug}/，再写一份诚实的 review.md，评价图谱哪些地方做得对、哪些地方做得不对，然后提交 PR。提取 bug——提 issue 时请附上输入文件、对应的缓存项（graphify-out/cache/）以及它漏提取或瞎编了什么。