graphify：把代码库与文档变成知识图谱的 Claude Code 技能部署指南

graphify 是一个 Claude Code 技能，在 Claude Code 里输入 /graphify，它会读取你的文件、自动构建知识图谱，把你原本没意识到的结构呈现出来。它完全多模态：代码、PDF、Markdown、截图、图表、白板照片，甚至其他语言的图片都能丢进去——graphify 借助 Claude 视觉能力从中抽取概念与关系，再把它们连成一张图。

它的灵感来自 Andrej Karpathy 的 /raw 文件夹——那里堆满了论文、推文、截图和笔记。graphify 就是为了解决"素材太多、每次都要重新读一遍"的问题：官方基准显示，在混合语料（Karpathy 的仓库加论文加图片）上，每次查询比直接读原始文件少用约 71.5 倍的 token，而且图谱跨会话持久化，它会诚实地标注哪些是真抽到的、哪些是推测的。

/graphify .

它可以作用于任意文件夹：你的代码库、笔记、论文都行。运行后在 graphify-out/ 目录产出一组成果：可交互的 graph.html（点击节点、搜索、按社区过滤）、可直接当 Obsidian vault 打开的 obsidian/、供 Agent 导航的维基 wiki/、总结"中心节点、意外关联、建议提问"的 GRAPH_REPORT.md、可持续查询的 graph.json，以及用 SHA256 做增量、只处理改动文件的 cache/。

这套输出的关键是"一次构建、多次复用"。graph.html 给人看，在浏览器里点来点去理解结构；graph.json 给程序读，几周后再查询时不必重新读文件；wiki/ 给 Agent 爬，每个社区一篇文章，Agent 顺着 index.md 就能在知识库里导航；GRAPH_REPORT.md 则是一份自动写好的摘要，告诉你整张图里最重要的节点和最值得追问的问题。配合 obsidian/ 目录，你甚至可以直接把这套图谱当成一个 Obsidian 笔记库来用。

换言之，graphify 不只是一次性的可视化工具，而是一个可持续积累的个人或团队知识库底座。你今天往文件夹里加一篇论文，明天加一段代码，后天加一张白板照片，它都通过增量缓存把新材料合并进同一张图，越用越丰富。配合 post-commit 钩子和 --watch 自动同步，这张图几乎不需要你手动维护，始终跟着你的素材走。

一、项目官方信息

二、项目背景

读一个大型代码库时，最大的成本不是"找不到文件"，而是"不知道哪些概念彼此关联"。你读了一篇论文，又改了一段代码，再过几周就忘了论文里的某个结论和代码里的某个函数其实在讲同一件事。传统做法是把素材都堆进一个文件夹，每次靠 LLM 重新通读一遍——这既费 token，又无法跨会话保留结构。

graphify 的思路是把"读"这件事前置成一次性的图谱构建：让 Claude 从每种文件里抽概念与关系，用图算法（Leiden 社区检测）把它们组织成网络，再持久化下来。之后你查"注意力机制和优化器之间有什么联系"，直接在图谱上走路径，而不是把几十份原始文件再塞进上下文。每条边还被标成 EXTRACTED（真抽到）、INFERRED（推测）或 AMBIGUOUS（存疑），让你分得清哪些是证据、哪些是猜测，避免把模型的臆测当成事实。

这种设计特别适合两类人：一类是刚接手陌生代码库的工程师，想在几天内摸清模块之间的依赖关系和核心概念；另一类是做研究的人，手里堆着论文、笔记和截图，需要一个可持续积累的个人知识库。传统做法是在笔记软件里手工连线，既慢又容易漏；graphify 让 Claude 自动读完所有材料并把关系画出来，你只需要在图上提问和浏览。它不依赖专门的图数据库，普通开发者本地装一个 Python 包就能跑，门槛很低。

三、核心特性

• 全模态抽取：代码用 tree-sitter 走 AST 加调用图；文档用 Claude 抽概念与关系；PDF 论文做引用挖掘与概念抽取；图片用 Claude 视觉识别截图、图表与白板照片。
• 多语言代码支持：.py .ts .js .go .rs .java .c .cpp .rb .cs .kt .scala .php 等主流语言都能解析结构。
• 中心节点（God nodes）：自动找出度数最高、所有东西都绕其连接的核心概念。
• 意外关联：按综合评分排序，代码—论文之间的跨类型边权重高于代码—代码，每条结果附一句大白话解释为什么。
• 建议提问：自动给出 4-5 个"这张图最适合回答"的问题。
• Token 基准：每次运行后自动打印压缩比，52 个文件的混合语料可达约 71.5 倍。
• 增量更新：--update 只重新抽取改动文件并合并进已有图谱；cache/ 用 SHA256 记录，重复运行不浪费 token。
• 自动同步：--watch 后台运行，代码保存即时重建（只跑 AST、不调 LLM），文档/图片变更时提醒你跑 --update。
• Git 钩子：graphify hook install 装 post-commit 钩子，每次提交自动重建图谱。
• 多格式导出：--wiki 生成 Agent 可爬的维基、--svg 导出矢量图、--graphml 给 Gephi/yEd、--neo4j 生成 cypher 脚本、--mcp 启动 MCP 服务器。
• 完全本地：基于 NetworkX + Leiden（graspologic）+ tree-sitter + Claude + vis.js，不需要 Neo4j、不需要服务器。

技术栈的分工很清楚：tree-sitter 负责把代码解析成抽象语法树并抽出调用关系，这部分是确定性的、不花 token；Claude 负责理解文档、论文和图片里的语义概念，这部分是智能的但要消耗 token；NetworkX 在内存里维护图结构，Leiden 算法负责把节点聚类成社区；vis.js 负责在浏览器里把图画出来。正因为代码结构走 AST、只有语义才调 LLM，它才能做到"改一行代码只重建 AST、不重复调用大模型"的增量效率。

它支持的文件类型覆盖了日常素材的绝大多数：代码文件按语言解析结构，Markdown / 纯文本 / reStructuredText 走概念与关系抽取，PDF 论文做引用挖掘和概念抽取，PNG / JPG / WebP / GIF 图片则交给 Claude 视觉识别——无论是截图、流程图还是白板拍照，哪怕图里是其他语言，都能被抽成节点连进同一张图。这种"跨模态统一成一张图"的能力，正是它区别于普通代码依赖分析工具的地方。

四、环境要求

• Claude Code：必须先安装 Claude Code，graphify 是作为它的技能运行的。
• Python 3.10 及以上：CLI 与技能都跑在 Python 上。
• Windows：若安装后提示 graphify 不是内部命令，把 Python 的 Scripts 目录（%APPDATA%\Python\Python3xx\Scripts，xx 换成你的版本号如 313）加入 PATH，或直接用 pipx install graphifyy 自动处理 PATH。
• macOS（externally managed）：若 pip install 报"externally-managed-environment"错误，改用 pipx install graphifyy。

五、部署步骤

方式一：pip 安装（推荐）

pip install graphifyy && graphify install

注意 PyPI 包目前临时叫 graphifyy（正在回收 graphify 这个名字），但 CLI 命令和技能触发仍然是 graphify。安装完成后，在任意目录打开 Claude Code，输入：

/graphify .

方式二：手动 curl 安装

mkdir -p ~/.claude/skills/graphify
curl -fsSL https://raw.githubusercontent.com/safishamsi/graphify/v1/skills/graphify/skill.md \
  > ~/.claude/skills/graphify/SKILL.md

然后在 ~/.claude/CLAUDE.md 里加上一段说明，让 Claude Code 知道 /graphify 时要调用这个技能：

- **graphify** (`~/.claude/skills/graphify/SKILL.md`) - any input to knowledge graph. Trigger: `/graphify`
When the user types `/graphify`, invoke the Skill tool with `skill: "graphify"` before doing anything else.

方式三：浏览器网页端查看图谱

graphify 本身不需要服务器，但它产出的 graph.html 是一个用 vis.js 渲染的交互式网页。运行 /graphify 后，直接用浏览器打开 graphify-out/graph.html，就能点击节点、搜索概念、按社区过滤，在网页里漫游整张知识图谱。想接入其他 Agent 时，可运行 /graphify ./raw --mcp 启动一个 stdio MCP 服务器，或用 --neo4j 导出 cypher 脚本导入 Neo4j。

这个网页查看器不需要任何后端，双击本地文件即可打开，适合在没有部署环境的笔记本上随身查看。节点按社区着色，度数高的中心节点会更大，点任意节点右侧会列出它连接的概念和边的类型（抽取、推测、存疑）。把 graph.html 和 graph.json 一起拷给同事，对方无需安装任何 Python 环境就能在浏览器里看同一张图。

六、使用方法

常用命令一览：

/graphify                          # 对当前目录建图
/graphify ./raw                    # 对指定文件夹建图
/graphify ./raw --mode deep        # 更激进地抽取 INFERRED 边
/graphify ./raw --update           # 只重新抽取改动文件并合并
/graphify add https://arxiv.org/abs/1706.03762   # 抓一篇论文并入图
/graphify query "what connects attention to the optimizer?"
/graphify path "DigestAuth" "Response"            # 查两节点之间的路径
/graphify explain "SwinTransformer"               # 解释某个概念
/graphify ./raw --watch            # 文件变化时自动同步图谱
graphify hook install              # 装 post-commit 钩子自动重建

工作流建议：先把要梳理的素材（代码、笔记、论文 PDF、截图）放进一个文件夹，跑一次 /graphify ./raw 建出初始图谱；之后改代码时让 --watch 在后台自动维护，文档或图片变动时手动跑一次 --update；查资料时优先用 /graphify query 或在 graph.html 里走路径，而不是把原始文件重新喂给模型。想让别的 Agent 也能读这个知识库，就跑 --wiki 生成带 index.md 的维基目录，让 Agent 通过读文件来导航。

几个查询技巧：/graphify path A B 用来发现两个看似无关的概念之间的间接联系，常能挖出跨代码与论文的隐藏线索；/graphify explain X 用来让图谱解释某个核心概念为什么重要、它连接了哪些东西；/graphify add <url> 可以直接抓取一篇 arXiv 论文或一条推文并入图，省去手动下载。多人协作时，把 graph.json 和 graphify-out/ 一起提交进仓库，团队就能共享同一份结构视图。

官方给出的三个实测语料很有参考价值：Karpathy 仓库加 5 篇论文加 4 张图片共 52 个文件，压缩比约 71.5 倍；graphify 自身源码加 Transformer 论文共 4 个文件，压缩比约 5.4 倍；合成的 Python 库 httpx 6 个文件，压缩比约 1 倍。结论是：文件越少，图谱越接近"帮你理清结构"而非"省 token"；语料越大，图谱的压缩红利越明显。每个示例目录都保留了原始输入和真实输出，你可以自己跑一遍核对数字，而不是只信官方宣传。

七、常见问题 FAQ

Q：为什么 PyPI 包叫 graphifyy 而不是 graphify？ A：graphify 这个名字正在被回收，过渡期内 PyPI 包临时用 graphifyy，但安装后的 CLI 命令和 Claude Code 里的 /graphify 触发保持不变。

Q：一定要装 Neo4j 吗？ A：不用。图谱存在本地的 graph.json 里，基于 NetworkX 内存图计算，不需要任何数据库或服务器；--neo4j 只是可选地导出 cypher 脚本供你自己导入。

Q：重新跑一次会不会把之前的结果丢了？ A：不会。cache/ 用 SHA256 记录文件内容，重复运行只处理改动过的文件；--update 会把新结果合并进已有图谱，graph.json 跨会话持久保存。

Q：图谱里的边是模型猜的吗？ A：每条边都标了 EXTRACTED、INFERRED 或 AMBIGUOUS，真抽到的和推测的分得很清，--mode deep 才会更激进地抽 INFERRED 边。

Q：token 节省是怎么算出来的？ A：每次运行后自动打印基准。官方在 52 个文件（代码加论文加图片）的混合语料上测到约 71.5 倍；小语料（如 6 个文件）本身就能塞进上下文，这时图谱的价值主要是结构清晰而非压缩。

Q：Windows 下装完提示找不到命令？ A：把 %APPDATA%\Python\Python3xx\Scripts 加进 PATH，或改用 pipx install graphifyy 自动配置。

Q：没有 Claude Code 能用吗？ A：graphify 本身是作为 Claude Code 技能设计的，抽取依赖 Claude 视觉与语言能力，所以需要 Claude Code 环境。它不要求你装 Neo4j 或其他服务器，本地有 Python 3.10+ 和 Claude Code 即可。

Q：图谱能导出到别的工具吗？ A：可以。--graphml 导出给 Gephi、yEd 做进一步图分析；--svg 导出矢量图放进文档；--neo4j 生成 cypher 脚本；--mcp 启动 MCP 服务器让别的 Agent 通过协议查询。

八、跳转链接

总体而言，graphify 解决的是"素材越攒越多、每次都要重读"的问题：它把一次性的阅读变成持久的知识图谱，之后查询走图而不是重读原文，token 随语料增大而显著下降。对刚接手代码库的工程师和做研究的人，它提供了一个本地、免数据库、可持续积累的个人知识底座。

• GitHub 仓库：Graphify-Labs/graphify
• 官方网站：graphify.com
• PyPI 包：graphifyy
• Claude Code：claude.ai/code
• 工作示例：worked/karpathy-repos
• 架构说明：ARCHITECTURE.md
• 问题反馈：GitHub Issues