graphify：把任意代码库变成可查询知识图谱——基于官方韩文文档的完整实践指南

本文以 graphify 仓库的韩文版文档 README.ko-KR.md 为主体，系统讲解 graphify 如何将代码、PDF、Markdown、截图甚至其他语言写成的图片统一转化为可查询的知识图谱。读完后，你将掌握 /graphify 技能在 Claude Code、Codex、OpenCode、Factory Droid、Trae 等 AI 编码助手中的完整安装与配置流程、全部命令行参数、.graphifyignore 排除规则、graph.json 与 LLM/MCP 的协作方式，以及其"确定性 AST 解析 + 语义抽取"两遍式管线背后的源码级原理。

一、graphify 是什么

graphify 是一个面向 AI 编码助手的技能（skill）：在 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid 或 Trae 中输入 /graphify，它会读取指定目录下的文件并构建知识图谱，把代码库中你可能从未注意过的结构可视化出来，帮助你更快地理解代码库、找到架构决策背后的"为什么"。

它的核心能力可以用三点概括：

1. 完全的多模态支持：代码、PDF、Markdown、截图、图表、白板照片，甚至其他语言写成的图像——graphify 使用 Claude Vision 从中抽取概念与关系，汇入同一张图。代码侧通过 tree-sitter AST 支持 20 种语言：Python、JS、TS、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、Elixir、Objective-C、Julia。这一点在 pyproject.toml 的基础依赖中可以得到印证：tree-sitter-python、tree-sitter-typescript、tree-sitter-go、tree-sitter-rust、tree-sitter-java、tree-sitter-c、tree-sitter-cpp、tree-sitter-ruby、tree-sitter-c-sharp、tree-sitter-kotlin、tree-sitter-scala、tree-sitter-php、tree-sitter-swift、tree-sitter-lua、tree-sitter-zig、tree-sitter-powershell、tree-sitter-elixir、tree-sitter-objc、tree-sitter-julia 等语法包均作为默认依赖随包安装。
2. 不用向量库：没有 embedding、没有向量数据库，只有一张真正可遍历的图。
3. 每条边都可解释：每个关系都带有 EXTRACTED / INFERRED / AMBIGUOUS 标签，你永远知道哪条关系是直接读到的、哪条是推断出来的。

文档中引用了一个典型使用场景：Andrej Karpathy 维护一个收集论文、推文、截图、笔记的 /raw 文件夹。graphify 正是针对这类混合语料库的方案——相比直接读取原始文件，其查询消耗的 token 少 71.5 倍，且图谱在会话之间持久存在，并把"发现的事实"与"猜测"诚实地区分开。

基本用法只有一行：

/graphify .                        # 任意文件夹都可用 - 代码库、笔记、论文，什么都行

运行后在项目下生成如下产物：

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

graphify-out/cache/ 的缓存机制在源码中可以直接确认：graphify/cache.py 注释说明缓存条目按 graphify-out/cache/{kind}/{hash}.json 存储，其中 hash 是文件内容的 SHA256；check_semantic_cache()（graphify/cache.py）负责比对后返回"仍然需要抽取的文件列表"，这就是"重跑只处理变更文件"的底层实现。

二、工作原理：两遍管线，无向量库

graphify 以两遍（two-pass）方式运行：

• 第一遍：确定性 AST 路径。不经过任何 LLM，直接从代码文件中抽取结构——类、函数、import、调用图、docstring、以及作为设计依据的注释。从源码结构看，这一路径对应 detect() → extract() → build() 阶段：文件发现由 graphify/detect.py 完成，树形解析后的节点与边由 graphify/build.py 合并为 NetworkX 图。ARCHITECTURE.md 给出的完整管线为：

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

• 第二遍：语义路径。Claude 子代理并行处理文档、论文与图像，抽取概念、关系与设计依据，结果与第一遍产物合并进同一张 NetworkX 图。

合并之后进入聚类与导出：Leiden 社区发现算法（经 graspologic 提供）对图做分社区，然后导出为交互式 HTML、可查询的 JSON 和自然语言审计报告。ARCHITECTURE.md 中 cluster.py 的职责定义即 cluster(G) → {community_id: [node_id, ...]}，且该测试约束很强——tests/test_architecture_doc.py 会导入文档中列出的每一个符号，保证文档与代码不会漂移。

这里有一个关键设计决策值得展开：聚类基于图谱拓扑，而非 embedding。Leiden 依据边密度寻找社区；而 Claude 抽取出的语义相似边（semantically_similar_to，标记为 INFERRED）本身已经包含在图中，因此直接参与社区发现。换句话说，图结构本身就是相似性信号，不需要额外的 embedding 步骤或向量数据库。

可信度标签：每条边都有出处

所有关系都被打上三类标签之一（这一定义同时出现在 ARCHITECTURE.md 的 "Confidence labels" 一节与 graphify/build.py 的实现中）：

标签	含义
EXTRACTED	关系在源中显式存在（如一条 import 语句、一次直接调用）
INFERRED	合理推断（如调用图二次解析、上下文共现），INFERRED 边附带 confidence_score（0.0~1.0），EXTRACTED 边恒为 1.0
AMBIGUOUS	不确定关系，会被标记出来供人工在 GRAPH_REPORT.md 中复核

抽取输出的统一 schema 由 graphify/validate.py 在 build() 消费前强制校验：

{
  "nodes": [
    {"id": "unique_string", "label": "human name", "source_file": "path", "source_location": "L42"}
  ],
  "edges": [
    {"source": "id_a", "target": "id_b", "relation": "calls|imports|uses|...", "confidence": "EXTRACTED|INFERRED|AMBIGUOUS"}
  ]
}

排除规则：.graphifyignore

不想进入图谱的目录/文件，通过 .graphifyignore 排除，语法与 .gitignore 相同，模式相对于运行 graphify 的文件夹按相对路径匹配：

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

从源码实现看（graphify/detect.py 的 _load_dir_own_ignore()），.gitignore 会被自动读取，且与同目录下的 .graphifyignore 合并；两者冲突时 .graphifyignore 的模式最后求值、优先生效，且每个忽略文件只作用于自己的子树——与 git 的子目录作用域行为一致。

三、安装

必需条件：Python 3.10+（与 pyproject.toml 的 requires-python = ">=3.10" 一致），以及 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid、Trae 之一。

pip install graphifyy && graphify install

注意包名：PyPI 上的包名是 graphifyy（双 y），因为 graphify 名称正在被收回，属于临时命名；CLI 命令与技能命令仍叫 graphify。这在 pyproject.toml 中可直接确认：name = "graphifyy"，脚本入口注册为 graphify = "graphify.__main__:main" 与 graphify-mcp = "graphify.serve:_main"（pyproject.toml）。

平台支持

韩文文档列出的平台与安装命令如下：

平台	安装命令
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
Trae	graphify install --platform trae
Trae CN	graphify install --platform trae-cn

各平台的差异细节（韩文文档原文要点）：

• Codex 用户还必须在 ~/.codex/config.toml 的 [features] 下设置 multi_agent = true 才能启用并行抽取。
• Factory Droid 使用 Task 工具进行并行子代理分发。
• OpenClaw 使用顺序抽取（该平台的并行代理支持仍处于早期阶段）。
• Trae 使用 Agent 工具做并行子代理分发，且不支持 PreToolUse 钩子——AGENTS.md 是它的常开（always-on）机制。

版本适配说明：韩文文档对应的平台清单较旧。当前仓库（pyproject.toml 版本 0.9.52）已支持的平台更多，完整的平台表见 README.md 的 "Pick your platform" 一节，包括 CodeBuddy、Kilo Code、GitHub Copilot、Cursor、Gemini CLI、Aider、Devin CLI、Google Antigravity 等。

安装完成后，打开 AI 编码助手并输入：

/graphify .

注：Codex 的技能调用用 $ 代替 /，所以要输入 $graphify .。

手动安装（不经过 pip）

也可以直接把技能文件放进 Claude 的技能目录：mkdir -p ~/.claude/skills/graphify 后，将技能文件（仓库中的 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
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 做两件事：写入一段 CLAUDE.md 指示（在回答架构类问题前先读 graphify-out/GRAPH_REPORT.md），并安装 PreToolUse 钩子（settings.json），在所有 Glob/Grep 调用之前触发。图谱存在时 Claude 会收到提示："graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes and community structure before searching raw files."——于是它走图谱导航，而不是 grep 全部文件。
• Codex 写入 AGENTS.md，并在 .codex/hooks.json 注册钩子条目。按当前仓库 README.md 的更新说明，该钩子条目（graphify hook-check）被刻意设计为 no-op——因为 Codex Desktop 拒绝在 PreToolUse 上接受 hookSpecificOutput.additionalContext，真正承载常开指引的是 AGENTS.md。
• OpenCode、OpenClaw、Factory Droid、Trae 均在项目根写入相同的 AGENTS.md 规则；因为这些平台不支持 PreToolUse 钩子，AGENTS.md 就是常开机制。

移除用对应的 uninstall 命令（如 graphify claude uninstall）。

常开机制 vs 显式触发——差别在哪？

• 常开钩子暴露的是 GRAPH_REPORT.md——一页纸概括神节点、社区与意外连接。助手在文件搜索前先读它，于是导航基于结构而非关键词匹配，仅凭这一点就能覆盖大部分日常提问。
• /graphify query、/graphify path、/graphify explain 则走得更深：逐跳遍历原始 graph.json、追踪两个节点间的精确路径、展示边级细节（关系类型、置信度分数、源码位置）。当你想在图上回答某个具体问题而非泛泛浏览时使用。

韩文文档给了一个很贴切的比喻：常开钩子是给助手一张地图，/graphify 命令是让助手精确地在这张地图上导航。

五、graph.json 如何与 LLM 协作

graph.json 不是用来整段粘贴进 prompt 的。推荐工作流是三步：

1. 先看 graphify-out/GRAPH_REPORT.md 获得高层概览；
2. 用 graphify query 针对具体问题取一个小得多的子图；
3. 把这份聚焦后的结果（而非整个原始语料）交给助手。

例如在项目里跑完 graphify 后：

graphify query "show the auth flow" --graph graphify-out/graph.json
graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json

输出包含节点标签、边类型、置信度标签、源文件与源位置，天然适合作为喂给 LLM 的中间上下文块：

请基于这份图谱查询结果回答问题。优先采用图结构而非猜测，
并尽量引用源文件。

如果助手支持工具调用或 MCP，就直接让助手查图谱而不是贴文本。graphify 可以把 graph.json 作为 MCP 服务器暴露：

python -m graphify.serve graphify-out/graph.json

这样助手就能通过结构化工具做重复查询。从源码看，MCP 服务器实现在 graphify/serve.py，当前版本注册的工具比韩文文档时期更多：query_graph、get_node、get_neighbors、get_community、god_nodes、graph_stats、shortest_path、list_prs、get_pr_impact、triage_prs（工具注册表见 graphify/serve.py），并且 serve.py 同时兼容 MCP 1.x 装饰器 API 与 2.x 回调式 API（pyproject.toml 中 mcp extra 的注释有说明）。当前仓库还支持 --transport http 将同一组工具以 HTTP 方式暴露给整个团队，细节见 README.md 的 "Using the graph directly" 一节。

六、完整用法速查

以下是韩文文档给出的全部命令形态，可直接复制使用：

/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 库（可选开启）
/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

# 常开助手指令 - 按平台
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)
graphify trae install              # AGENTS.md (Trae)
graphify trae uninstall
graphify trae-cn install           # AGENTS.md (Trae CN)
graphify trae-cn uninstall

# 直接在终端查图谱（不依赖 AI 助手）
graphify query "attention 和 optimizer 之间是什么连接？"
graphify query "show the auth flow" --dfs
graphify query "What is CfgNode?" --budget 500
graphify query "..." --graph path/to/graph.json

支持的文件类型

graphify 可混合处理多种文件类型：

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

可选依赖在 pyproject.toml 中以 extras 形式提供：pdf（pypdf + markdownify）、office（python-docx + openpyxl）、video（faster-whisper + yt-dlp）、mcp、neo4j、falkordb、ollama、openai、gemini、anthropic、bedrock、sql、chinese（jieba，用于中文查询分词）等。

七、结果物：报告里到底有什么

神节点（God nodes）——度最高的概念，即"一切流经的枢纽"。由 graphify/analyze.py 中的 god_nodes(G) 计算（ARCHITECTURE.md 的模块职责表有对应条目）。

意外的连接（Surprising connections）——按复合得分排序，代码-论文边比代码-代码边排得更靠前；每条结果附带易读的解释。

推荐问题（Suggested questions）——图谱独有、且恰好能回答的 4~5 个问题。

"为什么"（Rationale）——docstring、行内注释（# NOTE:、# IMPORTANT:、# HACK:、# WHY:）以及文档中的设计依据，都被抽取为 rationale_for 节点。图谱不仅回答"代码做什么"，还回答"代码为什么这样写"。

置信度分数——每条 INFERRED 边带 confidence_score（0.0~1.0），你知道的不只是"哪些是猜的"，还有"模型猜得有多肯定"；EXTRACTED 边恒为 1.0。

语义相似边——跨越无结构连接的文件的概念链接：两个互不调用但解决同一问题的函数、代码中的类与描述同一算法的论文概念，等等。

超边（Hyperedges）——三个及以上节点的群组关系，两两成对边无法表达：实现同一共享协议的所有类、认证流程中的全部函数、论文某节里构成一个思想的全部概念。

Token 基准——每次运行后自动打印。混合语料库（Karpathy 仓库 + 论文 + 图片）上：相比原文件每次查询少 71.5 倍 token。首次运行做抽取与建图（消耗 token）；此后所有查询都读压缩后的图谱而非原文件——省下的量会复利式累积。SHA256 缓存保证重跑只重处理有变更的文件。

自动同步（--watch）——放在后台终端里，代码库变更时图谱自动更新。代码文件保存即触发重构建（仅 AST，无 LLM）；文档/图像变更时则提示你去跑一次 --update 以触发 LLM 重处理。

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

Wiki（--wiki）——按社区与神节点生成维基百科风格的 Markdown 文档和 index.md 入口。任何 agent 只要被指向 index.md，就能通过读文件（而非解析 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 倍以上。

每个 worked/ 目录都保留了原始输入与真实输出，可以直接跑一遍验证数字。以 worked/karpathy-repos/README.md 为例，其复现配方是：克隆 nanoGPT、minGPT、micrograd 三个仓库，放入 5 篇 attention 主题论文的 PDF 和 4 张图片，共 52 个文件放入 raw/ 后执行 /graphify ./raw。该文档预期输出约 285 节点、约 340 边、约 17 个有意义的社区，神节点为 Value（micrograd）、GPT（nanoGPT）、Training Script、Layer；意外连接包括跨仓库的 nanoGPT Block ↔ minGPT Block、FlashAttention 论文桥接两个仓库的 CausalSelfAttention。实际产出就在同目录的 GRAPH_REPORT.md、graph.json 与诚实评估 review.md 中。

九、隐私与数据边界

这一点韩文文档说得很明确，也与 ARCHITECTURE.md 的管线设计一致：

• 代码文件：tree-sitter 在本地解析，不离开你的机器。纯代码语料库甚至不需要 API key（当前仓库还支持 graphify extract ./path --code-only 只索引代码、跳过需要 LLM 的文档/PDF/图片）。
• 文档、论文、图像：语义抽取会把内容发送到你所用 AI 编码助手的底层模型 API——Anthropic（Claude Code）、OpenAI（Codex）或对应平台的提供方。
• 没有任何遥测、使用跟踪或分析。唯一的网络调用是抽取期间对你本人 API key 对应平台模型 API 的调用。

十、技术栈

NetworkX + Leiden（graspologic）+ tree-sitter + vis.js。语义抽取经由 Claude（Claude Code）、GPT-4（Codex）或平台所运行的模型完成。不需要 Neo4j、不需要服务器、完全本地运行。依赖关系与 pyproject.toml 完全对应：networkx>=3.4、tree-sitter>=0.23,<0.26 为默认依赖，graspologic 在 leiden extra 中（注意标注 python_version < '3.13'，即 Leiden 社区发现仅适用于 Python 3.13 以下环境）。

十一、贡献方式（来自韩文文档）

韩文文档 "기여하기"（贡献）一节给出的建议值得参考：

• 实战案例是最能建立信任的贡献方式：在真实语料库上跑 /graphify，把结果存入 worked/{slug}/，写一篇诚实评估图谱哪里判对、哪里判错的 review.md，然后提 PR。
• 抽取 bug：提交 issue 时附上输入文件、缓存条目（graphify-out/cache/）以及遗漏或捏造的内容。
• 模块职责与添加新语言的方式见 ARCHITECTURE.md——新语言抽取器按 extract_<lang>(path) -> dict 模式实现，放入 graphify/extractors/，并在 extract.py 的分发表、graphify/detect.py 的 CODE_EXTENSIONS 与 graphify/watch.py 的 _WATCHED_EXTENSIONS 中注册后缀，补 tests/fixtures/ 用例。

小结

graphify 的定位是"图谱层"（graph layer）：确定性、本地、零 LLM 的 AST 路径负责代码结构的骨架，并行语义路径负责文档、论文与图像的软性知识，两者合并成一张每条边都可解释、每个社区都有依据的持久化图谱。对使用者的直接价值是三条可验证的事实链——安装一行命令（pip install graphifyy && graphify install）、使用一个斜杠命令（/graphify .）、查询一个终端命令（graphify query "..."），而 71.5x 的 token 压缩数字可以在 worked/karpathy-repos/ 中亲自复现核验。