Graphify 是什么：在 Claude Code 里用 /graphify 把代码库变成知识图谱，怎么装、怎么问、哪些步骤花 Token

Graphify 是一个开源的代码知识图谱工具：在编程 AI 里输入 /graphify .，它会把整个项目（代码、文档、PDF、图片）整理成一张知识图谱，之后 AI 回答代码问题时先查图，不用一个个文件去搜。 项目在 GitHub 上是 Graphify-Labs/graphify，Apache-2.0 协议，2026-11-14 查看时约 14.7 万星，最新版本是 11-12 发布的 0.9.108。除了 Claude Code，也支持 Codex、Cursor、Gemini CLI、OpenCode 等二十多种工具。同一家公司还有付费的托管版 Graphify Cloud，本文只讲免费的开源版。

上手前先记住三件事：

1. 安装包叫 graphifyy，两个 y。 PyPI 上没有叫 graphify 的官方包，uv tool install graphify 会直接报找不到；名字相近的其他包都不是官方的。装好以后，命令才叫 graphify。
2. 代码建图不花 Token，文档、PDF、图片要花。 代码在本机解析，不调用模型；文档类文件要让模型读一遍。
3. 在 Claude Code 里用 /graphify，不用另配 API Key。 需要模型的那部分由 Claude Code 自己的子代理来做，走 Claude Code 已经配好的接口。所以接第三方 API 的人也不用额外设置，这点和 claude-mem 不一样。只有在终端里单独跑某几个命令时才要另配，见下文。

它做了什么

• 代码：用 tree-sitter 在本机解析约 40 种语言，找出函数、类、文件之间的调用、导入、继承关系，并跨文件连起来。不调用模型，代码不会离开你的电脑。
• 文档、PDF、图片：让模型读一遍，提取里面的概念，以及它们和代码的关系，比如设计文档里提到的模块会连到对应的代码。
• 分组：把整张图自动切成若干组（社区），每组大致对应一个子系统，并找出连接最多的中心节点。
• 每条连线都标了来源：EXTRACTED 表示源文件里明确写着，INFERRED 表示 graphify 推断出来的，读到的和推出来的分得清。
• 不是向量检索：不做 embedding、不建向量库，是一张能顺着走的图。

建完后项目里会多一个 graphify-out/ 文件夹：

graphify-out/
├── graph.html       用浏览器打开，可以点节点、筛选、搜索
├── GRAPH_REPORT.md  重点摘要：核心概念、意外的关联、建议问的问题
└── graph.json       完整的图，之后查询都读它，不用再读源文件

安装

要求：Python 3.10 到 3.14，推荐用 uv 安装（uv 会自己准备 Python）。还没装 uv 的话：macOS 用 brew install uv，Windows 用 winget install astral-sh.uv，Linux 用 curl -LsSf https://astral.sh/uv/install.sh | sh。

第 1 步：装命令行工具

uv tool install graphifyy

也可以用 pipx install graphifyy。装完提示找不到 graphify 命令的话，运行 uv tool update-shell（pipx 用 pipx ensurepath），再开一个新终端。

第 2 步：注册到 Claude Code

graphify install

不加参数时默认装给 Claude Code：把技能放到 ~/.claude/skills/graphify/SKILL.md，并登记到 ~/.claude/CLAUDE.md。Windows 会自动识别。只想装在当前项目里（方便提交给团队），加 --project。

第 3 步：重启 Claude Code，在项目目录里发送

/graphify .

它会依次识别文件、提取关系、分组、写报告，最后给你一段总结。项目超过 500 个文件（或文字量特别大）时，它会先列出文件最多的几个子目录，问你先建哪一个。想确认图建好了，在终端运行 graphify god-nodes --top 5，能列出项目里连接最多的 5 个符号就行。

升级：运行 uv tool upgrade graphifyy，再运行一次 graphify install，让技能文件和新版本对上。卸载：graphify uninstall，加 --purge 会连 graphify-out/ 一起删掉。

其他工具：每个工具分别注册一次。

怎么用

提问：建好图以后，用这三个命令：

/graphify query "登录是怎么一路走到数据库的"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

• query：按问题返回相关的那一小块图，默认控制在 2000 Token 左右，可以用 --budget 调。
• path：两个东西之间的最短路径，看它们是怎么连起来的。
• explain：讲清楚一个节点在哪个文件哪一行、连着谁。

在 Claude Code 里可以直接用中文问：它会先从图里挑出意思对得上的英文词（比如把「登录」对到 auth、login），再去查。这三个命令在终端里也能跑（graphify query "..."），不经过 AI，也不花 Token，但终端里只按字面匹配，要用代码里出现的名字，用中文问英文代码会什么都查不到。

如果你的文档和注释主要是中文，装上中文分词扩展，中文词会匹配得更准：

uv tool install --reinstall "graphifyy[chinese]"

保持图是最新的：

graphify hook install

装好 git 钩子后，每次提交、切分支、合并、变基，它都会在后台重建代码部分的图，不调用模型。文档或图片改了，要在 Claude Code 里运行 /graphify . --update。想和团队共用同一张图，可以提交 graph.json 和 GRAPH_REPORT.md，把 graphify-out/cache/ 加进 .gitignore。

让 Claude Code 每次先查图：在项目目录里运行

graphify claude install

它会在项目的 CLAUDE.md 里加一段 ## graphify 规则，并在 .claude/settings.json 里加两个钩子：Claude Code 每次要搜索或读文件之前，先提醒它用 graphify query 查图。钩子出错时什么都不做，不会卡住 Claude Code。想更强制一点，可以用 graphify install --project --strict，每个会话里第一次直接读源文件会被拦一次，要求先查图。这两条命令都会改项目里的文件，提交前先看一眼改了什么。

用第三方 API 要配什么

在 Claude Code 里用 /graphify：什么都不用配。 读文档、PDF、图片时，它让 Claude Code 开子代理去读，子代理用的就是 Claude Code 当前的接口和 Key；给分组起名也是 Claude Code 自己做。技能说明里写明了它不读 ANTHROPIC_API_KEY，也不会向你要 Key。

只有一个例外：如果你的环境变量里设了 GEMINI_API_KEY 或 GOOGLE_API_KEY，读文档这一步会改用 Gemini，花的是那个 Key 的额度。

在终端里单独跑命令时，有三处要注意：

1. graphify extract . 建图，项目里又有文档的时候，要给它指定一个模型来源（只建代码图就加 --code-only，不需要模型）。最省事的是让它借用 Claude Code：

   GRAPHIFY_CLAUDE_CLI_MODEL=模型ID graphify extract . --backend claude-cli
   

   它会在后台调用 claude -p，走的就是你给 Claude Code 配好的地址和 Key。不设 GRAPHIFY_CLAUDE_CLI_MODEL 时用 Claude Code 的默认型号，提取这种活不需要最强的型号，选单价低的就够。注意 graphify 估算费用时把这条路按 0 元算，但按 Token 计费的 API 照样扣费，以服务方的账单为准。

2. 想直接调 Anthropic 兼容接口，要先装 uv tool install --reinstall "graphifyy[anthropic]"，然后：

   ANTHROPIC_BASE_URL=https://www.ccsub.net \
   ANTHROPIC_API_KEY=你的Key \
   ANTHROPIC_MODEL=模型ID \
   graphify extract . --backend claude
   

   这三个变量建议像上面这样只写在这一条命令前面，不要写进 ~/.zshrc 之类的配置：Claude Code 也读 ANTHROPIC_MODEL 和 ANTHROPIC_API_KEY，写进去会连带改掉 Claude Code 的默认型号和登录方式。graphify 只认 ANTHROPIC_API_KEY，不认 ANTHROPIC_AUTH_TOKEN；CCSub 两种写法都接受。默认型号是 claude-sonnet-4-6，服务方不认这个名字就会报错，所以要用 ANTHROPIC_MODEL 换成服务方列表里的完整 ID（CCSub 的见模型列表）。它默认给提示词开缓存，有的服务不接受，报相关错误时在命令前加 GRAPHIFY_CLAUDE_PROMPT_CACHE=0。它打印的费用估算按 Anthropic 官方价算，和你实际付的不一定一样；CCSub 的缓存读写按输入单价计，开了缓存也不会更便宜。

3. graphify cluster-only . 和 graphify label 会给分组起名。没设任何 API Key、但电脑上装了 Claude Code 时，它会自动改用 claude -p 来起名，终端会打印一行提示。这一步只发送节点名称，用量不大，但同样走你的接口计费。不想让它调用任何模型，在命令前加 GRAPHIFY_BACKEND=none，它会改用每组里连接最多的那个节点来命名。

花多少 Token

建图：

• 只有代码的项目，提取本身不调用模型。
• 文档、PDF、图片要让模型每个文件读一遍。技能说明里自己写着，这一步可能要几分钟、几万 Token。一个 README 加一个截图文件夹就会触发它。
• --mode deep 提取得更细，也更费。
• 在 Claude Code 里用 /graphify . 还有一份固定开销：技能说明文件本身约 5 万字节（英文），每次调用都会读进对话，Claude Code 还要逐步执行命令、给分组起名。所以哪怕是纯代码项目，用 /graphify 建图也会花一些 Token。

最省钱的建图方式：在终端里建，再回到 Claude Code 里查：

graphify extract . --code-only
GRAPHIFY_BACKEND=none graphify cluster-only .

第一条只解析代码，第二条写报告和 graph.html，两条都不调用模型。之后在 Claude Code 里用 /graphify query 提问，或者装上前面说的 graphify claude install 让它自己先查图。

更新：graphify update .、git 钩子和 graphify watch 只重读代码，不调用模型。没改过的文档会用缓存，不会重复花钱。

到底能省多少：GitHub 首页那个「省 80% Token」说的是付费托管版。开源版官方文档也写了，宣传里的数字不等于你项目里的数字。graphify 自带一个测算命令：

graphify benchmark

它会拿五个典型问题，对比「把整个项目塞给模型」和「从图里取答案」各要多少 Token。不过这比的是把全部代码都塞进去的极端情况，Claude Code 平时本来就只读一部分文件，实际省多少还得看账单：用 CCSub 的话，控制台「使用记录」里每条请求都有 Token 数和扣费，装之前和装之后各做几件差不多的事，对比一下就知道。

隐私

• 代码：在本机解析，不发给任何服务。
• 文档、PDF、图片：会发给模型去读。用 /graphify 时发给 Claude Code 当前用的接口，用终端命令时发给你指定的模型来源。它会跳过它判断为敏感的文件，并把跳过的文件列出来。
• 不想让某些文件进图：在项目根目录建一个 .graphifyignore，写法和 .gitignore 一样。
• 没有遥测。但每次查询的问题会记到本机的 ~/.cache/graphify-queries.log，不想记的话设 GRAPHIFY_QUERY_LOG_DISABLE=1。

常见问题

uv tool install graphify 报找不到？ 包名少了一个 y，应该是 graphifyy。

Claude Code 不认识 /graphify？ 运行 graphify install --platform claude，确认 ~/.claude/skills/graphify/SKILL.md 存在，然后重启 Claude Code。用 --project 装的，要在那个项目的根目录里打开 Claude Code。

提示找不到 graph.json？ 还没建图，或者不在项目根目录。先建图，或者在命令后加 --graph，跟上 graph.json 的完整路径。

回答还是旧代码？ 运行 graphify update . 再问。装了 git 钩子的话，刚提交完的几秒内后台可能还在重建。

和 API 服务的关系

graphify 不改 Claude Code 的接口设置。在 Claude Code 里用 /graphify，所有要用模型的步骤都走 Claude Code 当前的接口，官方账号和第三方服务的用法一样，不用另配。只有在终端里单独提取文档、给分组起名时，才要按上面「用第三方 API 要配什么」那一节处理。要留意的是建图时读文档花的 Token，以及每次调用 /graphify 读技能说明的固定开销。

还没配置好 Claude Code 的话，先看 Claude Code 接入教程；用 Codex 的看 Codex CLI 接入教程。同样是给 Claude Code 用的扩展，还可以看看技能库 Superpowers 和记忆插件 claude-mem。