编辑
2026-11-22
实用工具
0

目录

Graphify 是什么:给你的代码库建一张知识图谱,让 AI 助手先查图再翻文件
三十秒看懂
一、它治的是什么毛病
二、先别搞混:有两个东西都叫 Graphify
三、它凭什么比「让大模型读一遍」可信
四、有什么好处:直接看输出
好处 1:一条命令看清「谁是你的架构枢纽」
好处 2:追问关系,不用再去翻文件
好处 3:两个八竿子打不着的类,中间怎么连上的
好处 4:动手改之前,先知道会波及谁
好处 5:白送一份架构体检报告,而且它会主动挑刺
关于省 token,一句必须说准的话
五、安装
5.1 先认清三层,后面就不会乱
5.2 Windows
5.3 macOS
5.4 Linux
5.5 --python 3.12 到底该不该带——我机器上是个反例
5.6 装完自查这四条
5.7 国内网络:两条命令
5.8 extras:用到再装
5.9 卸载
六、怎么用
路线 A:接进 AI 助手(最省事,推荐先用这个)
路线 B:纯命令行(脚本 / CI / 想先自己验货)
路线 C:MCP server(客户端不支持 skill,或多人共用一张图)
七、Qoder 用户:官方没适配,但两条命令就够
7.1 Skill 层:一条命令,不用复制目录
插一句:写这一节时我手上的证据
7.2 MCP 层:可选,两种情况才需要
7.3 三个 Qoder 别混着记
八、上手前该知道的 6 件事
九、要不要用
十、上手清单(照抄即可)
参考

Graphify 是什么:给你的代码库建一张知识图谱,让 AI 助手先查图再翻文件

三十秒看懂

Graphify 是一个把代码库解析成「可查询知识图谱」的本地工具,解析靠 tree-sitter 读 AST,不传云端、纯代码不需要 API key。产物是仓库里一个 graphify-out/ 目录:一份 graph.json、一份浏览器里能点着看的 graph.html、一份 GRAPH_REPORT.md。然后你的 AI 编程助手(Claude Code / Cursor / Codex / Trae / Gemini CLI……)改成一问图谱、不再一遍遍 grep 源码。

PyPI 包名graphifyy(两个 y)
装好的命令graphify、graphify-mcp
许可 / 语言Apache-2.0 / Python ≥3.11.5 且 <3.15
代码要上传吗不用,本地 AST 解析
要向量库 / embedding 吗不要
我实测的版本0.9.114(2026-11-22)

用 Qoder 的话:graphify 的官方平台表里没有它,但接起来反而最短——直接跳第七节。

这个项目发版极勤(PyPI 上 282 个 release,最近一次就在两天前),任何教程里的 flag 都可能过期,以你机器上的 graphify --help 为准。本文数据全部来自真实执行,不是文档转抄。


一、它治的是什么毛病

你用 AI 助手改自己项目时,大概率见过这个场面:

你问「登录态是在哪几个模块之间流转的?」,它开始 grep → 读 8 个文件 → 再 grep → 再读 12 个文件 → 中间还开 subagent 各读一遍。半个上下文没了,最后给你一段似是而非的总结。

问题不在模型不够聪明,在于它理解项目的方式太原始:一个文件一个文件线性地翻。而代码的调用关系本来就是一张图,它每次都在从零重建这张图。

Graphify 的思路就一句话:先确定性地建好这张图,让 Agent 去查图,而不是翻文件。


二、先别搞混:有两个东西都叫 Graphify

这是新手第一个坑。同一个名字下有两套产品:

Graphify CLI(开源,本文讲这个)Graphify(托管平台)
跑在哪你自己的机器app.graphify.com
怎么装uv tool install graphifyy注册 + 授权 GitHub
代码出不出机器不出授权云端索引
图谱保鲜手动 update / watch / git hooks每次 push 自动重建
助手接入本地 skill 或 graphify-mcp托管 MCP https://api.graphify.com/mcp
团队协作提交 graph.json 共享PR review、Wiki、Memory、工作区

代码必须留在本地、或者你想把图谱当文件产物自己管 → 用开源 CLI。 本文之后全部指开源 CLI。


三、它凭什么比「让大模型读一遍」可信

四步流水线,全本地:

  1. Detect — 遍历目录,遵守 .gitignore 和 .graphifyignore,把文件分成代码 / 文档 / 论文 / 图片 / 视频。
  2. Extract — 代码用 tree-sitter 语法解析出 AST,确定性结果,不调模型。只有文档和媒体才可选走 LLM。
  3. Resolve — 跨文件绑定调用、导入、继承。绑不到唯一定义的边,标成 AMBIGUOUS,而不是猜一个。
  4. Cluster & Report — Leiden 社区发现聚类,输出图谱 + HTML 可视化 + Markdown 报告。

第三条是关键。每条边都带来源标签:

  • EXTRACTED — 源码里明摆着写的(import、调用)
  • INFERRED — resolver 或模型推出来的
  • AMBIGUOUS — 有多个可能目标,没敢定

所以助手回答你「为什么 A 通到 B」时,你能分清这条线索是实锤还是推测。这是它和「让 LLM 读一遍然后凭印象画架构图」最本质的区别。

支持的语言:Python / JS / TS / Go / Rust / Java / C / C++ / Ruby / C# / Kotlin / Scala / PHP / Swift / Lua / Zig,外加 Vue / Svelte / Astro / JSX / TSX;pom.xml、go.mod、pyproject.toml 这类清单也会作为包依赖进图。官方明确说框架代码按语言本身解析——Spring 应用就是 Java,框架特有的 wiring 能采到多少因项目而异。


四、有什么好处:直接看输出

演示仓库是我自己的一个 Spring Boot 项目(rag-agent,Java + 前端静态页,162 个文件)。跑完之后的规模:

text
162 files · 2342 nodes · 7364 edges · 96 communities 边的分布:calls 2532 · imports 1618 · references 1296 · method 1071 · contains 792 置信度:86% EXTRACTED · 14% INFERRED · 0% AMBIGUOUS

好处 1:一条命令看清「谁是你的架构枢纽」

bash
graphify god-nodes --top 5
text
God nodes (most connected): 1. JsonFileChatMemoryRepository - 87 edges 2. RuntimeSettings - 68 edges 3. SourcesIndex - 59 edges 4. BlogWriteServiceTest - 55 edges 5. el() - 53 edges

我一眼看到 RuntimeSettings 挂了 68 条边——一个运行时配置对象被这么多地方引用,本身就是「这玩意是不是上帝类」的信号。第 4 名是个测试类,说明测试脚手架耦合偏重。这种判断以前靠印象,现在有数。

好处 2:追问关系,不用再去翻文件

bash
graphify query "ingest chunk embedding" --budget 250
text
Graph: graphify-out/graph.json (2342 nodes) | Traversal: BFS depth=2 | Start: ['embedding', 'ingest', 'EmbeddingModelGuard', '.ingest()', '.chunk()'] | 244 nodes found [!] TRUNCATED: showing 6 of 244 nodes (~250-token budget). The answer may be among the 238 cut nodes — raise the token budget to 9595 to get all 244 (CLI: --budget 9595) or narrow the query (e.g. context_filter=['call'], or get_node for a specific symbol). NODE EmbeddingModelGuard [src=main/java/cn/haowee/rag/service/EmbeddingModelGuard.java loc=L24 community=Health and Store Status] NODE .ingest() [src=main/java/cn/haowee/rag/service/IngestService.java loc=L116 community=Ingest Pipeline] NODE .chunk() [src=test/java/cn/haowee/rag/service/RetrievalServiceTest.java loc=L49 community=Retrieval Service Tests]

注意它是从命中关键词的节点出发做图遍历(--dfs 可改成顺一条链深挖),不是向量召回。而且结果超预算时它明说截断、还直接告诉你需要多少预算能装全——比某些工具「答案就这么多」友好。

好处 3:两个八竿子打不着的类,中间怎么连上的

bash
graphify path "...ingestservice_ingestservice_ingest" "...embeddingmodelguard_embeddingmodelguard" --undirected
text
Shortest path (3 hops): .ingest() <--method [EXTRACTED]-- IngestService <--references [EXTRACTED]-- BlogImportService --references [EXTRACTED]--> EmbeddingModelGuard Path confidence: EXTRACTED (weakest hop 1: method) (weakest of 4 equal-length routes)

这段输出值得夸:它不只给路径,还按最弱一跳给出整条路径的置信度,并告诉你有 4 条等长路径。答案 + 答案的可信程度——下游是 LLM 的时候,这个设计能省掉很多一本正经的胡说。

好处 4:动手改之前,先知道会波及谁

bash
graphify affected "RuntimeSettings" --depth 2
text
Affected nodes for RuntimeSettings Depth: 2 - NativeHints.java [imports] main/java/cn/haowee/rag/config/NativeHints.java:L44 - AdminControllerTest.java [imports] test/java/cn/haowee/rag/controller/AdminControllerTest.java:L41 - .adminDeletesAnotherOwnersConversationWithAuditFields() [calls] test/java/cn/haowee/rag/controller/AdminControllerTest.java:L314 - AdminController [references] main/java/cn/haowee/rag/controller/AdminController.java:L66 - IngestService [references] main/java/cn/haowee/rag/service/IngestService.java:L85

反向遍历,--relation calls 只看你关心的边类型。「影响面分析」从一句玄学变成了能列清单、能进 CI 的东西。

好处 5:白送一份架构体检报告,而且它会主动挑刺

GRAPH_REPORT.md 里有一节 Suggested Questions,真实输出:

text
- Should `Admin Panel Frontend` be split into smaller, more focused modules? _Cohesion score 0.01514161220043573 - nodes in this community are weakly interconnected._ - Why does `RuntimeSettings` connect `Runtime Settings and Stats` to `Widget Quota and Meal Decision`, `Blog Write and VanBlog API`, `Ingest Pipeline`, ... ? _High betweenness centrality (0.028) - this node is a cross-community bridge._ - **18 isolated node(s):** `RUNNING`, `SUCCEEDED`, `PARTIAL`, `FAILED`, `CANCELLED` (+13 more) These have ≤1 connection - possible missing edges or undocumented components.

内聚度、介数中心性、孤立节点清单——这些是图算法算出来的结构指标,不是模型编的。RuntimeSettings 同时被报成「高耦合枢纽」和「跨社区桥梁」,和好处 1 里那 68 条边完全对得上。这种自洽是我不敢指望纯 LLM 生成的架构文档给的。

报告还会给每个社区起名(Ingest Pipeline、Hybrid Reranker、Sa-Token Auth Config、Marked Tokenizer……),基本就是我脑子里的模块划分,不用我维护文档。

关于省 token,一句必须说准的话

bash
graphify benchmark
text
Corpus: 117,100 words → ~156,133 tokens (naive) Graph: 2,342 nodes, 7,364 edges Avg query cost: ~1,624 tokens Reduction: 96.1x fewer tokens per query

96 倍是真实测出来的,但口径要看清:它比的是「把整个语料塞进上下文」vs「对几个预设问题的平均回答长度」,是个容量对比,不是省钱凭证——它没有度量你的代理实际少读了多少文件。

官方还有份 BENCHMARKS.md(我逐条核对过数字没抄错):LOCOMO 检索 recall@10 0.497,对比 mem0 的 0.048;LongMemEval-S 76%,与 dense RAG 并列第一;在约 100 万行的 ERPNext 上关键事实覆盖 82.0% vs grep/read 基线 70.8%。这些是它自家 harness 跑的,别当客观结论,graphify benchmark 在你自己仓库上跑的那个才算数。


五、安装

5.1 先认清三层,后面就不会乱

text
第 1 层 uv(或 pipx) ← 隔离安装命令行工具;缺 Python 它自己下 第 2 层 graphifyy ← uv tool install graphifyy,产出 graphify / graphify-mcp 两个命令 第 3 层 注册到你的 AI 助手 ← graphify install --platform xxx
项值
Python 版本>=3.11.5,<3.15(PyPI 元数据原文,3.10 和 3.15 都不行)
包名 / 命令名graphifyy(双 y) / graphify、graphify-mcp
要 API key 吗纯代码不需要
要预装 Python 吗用 uv 官方脚本的话不用,uv 自己下

先确认一下你系统里的 Python:

bash
python3 --version # Windows PowerShell 用 python --version

低于 3.11.5 → 别折腾系统 Python,直接走下面的 uv 路线,让它自己下一份。


5.2 Windows

① 装 uv,三条路任选:

powershell
# 路 A:官方独立脚本(不依赖已装 Python,最推荐) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # 路 B:winget winget install --id=astral-sh.uv -e # 路 C:Scoop scoop install main/uv

脚本方式装的 uv 可以自我升级:uv self update。装完必须关掉终端重开一个,PATH 才生效。想知道自己走的是哪条,跑 where uv 看落点:...\Scoop\shims\uv 是 Scoop,%USERPROFILE%\.local\bin\uv.exe 是官方脚本。

② 装 graphify:

powershell
uv tool install --python 3.12 graphifyy graphify --version # 期望:graphify 0.9.114

③ 装完之后,文件在哪(这些路径我本机逐个读过):

东西Windows 落点我机器上的实际值
可执行命令%USERPROFILE%\.local\bin\graphify.exe、graphify-mcp.exe
隔离环境根%APPDATA%\uv\tools\graphifyy\里面 Lib\site-packages\graphify
它用的解释器...\graphifyy\Scripts\python.exe记在 graphify-out\.graphify_python 里

不确定就一条命令查,别猜:

powershell
uv tool dir # 我这台机器输出:C:\Users\lhw\AppData\Roaming\uv\tools

④ Windows 最容易翻车的两点:

  • PATH:%USERPROFILE%\.local\bin 默认不在 PATH 里。graphify 报「不是内部或外部命令」就 uv tool update-shell 然后重开终端。
  • GUI 客户端不继承你的终端 PATH。Qoder / Cursor 这类桌面应用启动时读到的环境变量和 PowerShell 里的往往不是同一份——我本机就是活案例:用户 PATH 里明明有 .local\bin,从应用内部起的终端仍然找不到 graphify。在 MCP 配置里直接写 .exe 绝对路径一步绕过(第七节那段 JSON 就是这么写的)。
  • 顺带:在 Git Bash 里给 graphify-mcp 传 C:/... 形式的路径没问题,但别混用 MSYS 风格 /c/...,那层路径转换会咬人。

5.3 macOS

① 装 uv:

bash
brew install uv # 最常见 curl -LsSf https://astral.sh/uv/install.sh | sh # 或官方脚本(不依赖 brew) sudo port install uv # MacPorts

Apple Silicon 的 brew 前缀是 /opt/homebrew,Intel 是 /usr/local——uv 本身装在 ~/.local/bin(脚本方式)或 brew 前缀下(brew 方式),两者 PATH 处理不同,别照抄别人的 export 行。

② macOS 自带 Python 的坑: Xcode 命令行工具那份 python3 版本通常偏老(不少机器上还是 3.9.x),直接 pip install graphifyy 会因为 <3.11.5 的下限失败。所以 macOS 上更要带上 --python 3.12,让 uv 自己拉一份干净的:

bash
uv tool install --python 3.12 graphifyy

③ PATH:zsh 是 macOS 默认 shell,全新环境最容易在这卡住。

bash
uv tool update-shell # 然后把 ~/.local/bin 加进 PATH,或重开终端

④ zsh 的方括号必须加引号——这是 macOS/Linux(zsh) 特有的一条:

bash
uv tool install --python 3.12 "graphifyy[mcp]" # 正确 uv tool install --python 3.12 graphifyy[mcp] # zsh 报 no matches found

5.4 Linux

① 装 uv:

bash
curl -LsSf https://astral.sh/uv/install.sh | sh # 系统没 curl 就 wget -qO- https://astral.sh/uv/install.sh | sh

发行版官方源里普遍没有 uv,别在 apt search 上浪费时间。已有 Python 环境的话也可以 pipx install uv。

② Linux 的头号坑是系统 Python 太老:

发行版默认 python3能直接装吗
Ubuntu 22.043.10不能(低于 3.11.5)
Debian 123.11勉强够(贴着下限)
Ubuntu 24.043.12能

自己 python3 --version 对一下。结论是:Linux 上请一律带 --python 3.12,让 uv 去下载,别赌发行版自带的那份:

bash
uv tool install --python 3.12 graphifyy

③ PATH:~/.local/bin 在某些精简发行版/Docker 镜像里默认不在 PATH。uv tool update-shell,或往 ~/.bashrc / ~/.profile 补一行 export PATH="$HOME/.local/bin:$PATH" 后重开 shell。

④ CI / 容器里建议显式锁版本,避免基础镜像换 Python 后行为漂移:

bash
uv tool install --python 3.12 graphifyy && graphify extract . --code-only

5.5 --python 3.12 到底该不该带——我机器上是个反例

老实说:我这篇文档写的 uv tool install --python 3.12 graphifyy,在我自己这台机器上并不是当初真实执行的那条。 查完之后很明确:

bash
uv python list | findstr 3.12 # cpython-3.12.16-windows-x86_64-none <download available>

<download available> 的意思是这份 Python 从没被下载过。再看 graphify 隔离环境实际用的解释器:

bash
%APPDATA%\uv\tools\graphifyy\Scripts\python.exe --version # Python 3.14.4 ← 和系统 Python 一模一样

也就是说当初走的是不带 --python 的裸 uv tool install graphifyy,uv 直接复用了系统的 3.14.4。这次能跑,纯属运气好——3.14.4 刚好落在 >=3.11.5,<3.15 里。

所以这条建议这样理解:

  • 带上 --python 3.12 = 把解释器版本钉死,换机器、换基础镜像、系统升级 Python 之后行为一致。Ubuntu 22.04(3.10)、macOS 自带旧 Python、以及将来系统升到 3.15,都靠这一条躲过去。
  • 不带的写法 uv tool install graphifyy 更短、下载更少(不必多拉一份 Python),代价是你的图谱行为跟着系统 Python 漂。

个人本机随便用哪个;进 CI、进团队文档、进 Dockerfile,请一律带。

不想用 uv 的话:pipx install graphifyy 是等效替代,同样给 graphify 单开隔离环境。但不建议裸 pip install——graphify 运行时会去读 graphify-out/.graphify_python 来定位解释器(这文件确实存在,我上面那个表里列的就是它),pip 装的环境和运行时解析到的环境一旦不一致,就会报 ModuleNotFoundError: No module named 'graphify'。uv / pipx 天然隔离,撞不上这个。


5.6 装完自查这四条

不分系统,跑完这四条就说明第 1、2 层真的通了:

bash
uv --version # 第 1 层:uv 在 PATH 里 graphify --version # 第 2 层:0.9.114 uv tool dir # 隔离环境根,确认它真装进去了 uv tool list # 应该列出 graphifyy x.y.z

最后一条的输出顺便把「包名双 y、命令单 y」这件事给你钉死:

text
graphifyy v0.9.114 - graphify - graphify-mcp

一个包,两个可执行文件。MCP 配置里要写的是 graphify-mcp,不是 graphify。

graphify --version 出得来但 MCP 客户端连不上 → 不是 PATH 问题,是 GUI 进程的环境变量问题,回 5.2 那条绝对路径。


5.7 国内网络:两条命令

uv 内置证书库有时候不信系统根证书(公司代理、安全软件做 TLS 拦截时尤其明显),报 invalid peer certificate: UnknownIssuer 就跟一句:

powershell
uv tool install --system-certs graphifyy

还是不通(报 tunnel error / tcp connect error / 「目标计算机积极拒绝」,说明本机有个失效的本地代理在拦路),直接换国内源:

powershell
uv tool install --system-certs --default-index https://pypi.tuna.tsinghua.edu.cn/simple graphifyy

想永久生效:UV_SYSTEM_CERTS=1、UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple。

5.8 extras:用到再装

一共 30 个,别一次全装(zsh 下记得给方括号加引号):

什么时候要装什么
要跑本地 MCP serveruv tool install --python 3.12 "graphifyy[mcp]"
存盘自动重建图"graphifyy[watch]"
PDF / Office 文档"graphifyy[pdf]" / "graphifyy[office]"
SQL 文件解析 / 直连 Postgres 内省"graphifyy[sql]" / "graphifyy[postgres]"
语义抽取走本机 Ollama(不出内网)"graphifyy[ollama]"

[chinese] 这个要不要装,先自己测。 它拉的是 jieba(Python ≥3.12 装 jieba-py),给中文查询做分词。我在自己项目上没装它跑 graphify query "检索 分块",照样命中了含中文标签的节点(因为图谱里本来就有中文命名的概念节点),只是只匹配到 1 个种子词。所以:先裸跑几条中文查询看命中率,不满意再补 [chinese],比照着别人的清单装划算。

已经装过再加 extras 属于重装,要带 --reinstall。

5.9 卸载

bash
graphify uninstall # 移除所有平台注册 + git hooks,保留 graphify-out/ graphify uninstall --purge # 连图谱一起删 uv tool uninstall graphifyy # 删包

六、怎么用

路线 A:接进 AI 助手(最省事,推荐先用这个)

bash
graphify install

不带参数默认按当前机器探测(Claude Code 系)。指定平台:

bash
graphify install --platform cursor graphify install --platform codex graphify install --platform trae-cn

--platform 一共支持 23 个值:claude codex opencode kilo aider copilot claw droid trae trae-cn hermes kiro pi codebuddy antigravity antigravity-windows windows kimi amp agents devin gemini cursor。

装错目录当场就能发现:它会把写入目标逐行打印出来,看那两行比查文档快。 不认识你的助手就用 --platform agents,它写通用的 ~/.agents/skills/。

然后在助手里发一句话:

text
/graphify .

它就开始建图。之后常用:

命令作用
/graphify src仓库太大时只对源码目录建图
/graphify . --update只重抽新增/变更文件
/graphify . --wiki每个社区生成一篇 wiki 文章
/graphify explain "X"单个节点的人话解释

⚠️ graphify install 会动你的文件,这点必须知道。它往 CLAUDE.md / AGENTS.md / .cursor/rules/graphify.mdc 里插一段规则,部分平台还会注册 PreToolUse hook。插进去的规则核心是那句:回答代码库问题前,先 graphify query,再去 grep。这条是整套东西能否省 token 的关键——没有它,助手还是会习惯性地先 grep。但也意味着你的助手从此多了一个工具链依赖。所以 --project(写进仓库、影响全组)之前,先读一眼它打印出来的文件清单。

路线 B:纯命令行(脚本 / CI / 想先自己验货)

bash
cd your-repo graphify extract . --code-only # 只解析代码,不调模型,不要 key graphify cluster-only . --no-label # 出 GRAPH_REPORT.md + graph.html

这两步是分开的,而且坑在这里:extract 只落 graph.json,报告和 HTML 是聚类那步才生成的。脚本里漏掉第二步,就会出现「图建了、报告没了」。(在助手里跑 /graphify . 是两步串起来的,所以平时看不出边界。)

--no-label 是跳过用模型给社区起名字;去掉它就会花 token。官方参考量级:在 graphify 自己包的一份拷贝(98 个代码文件)上 extract 大约 6 秒。

保鲜:

bash
graphify update . # 只重解析哈希变了的代码文件,永远不调模型 graphify hook install # commit / checkout / merge / rebase 后自动重建 graphify hook status # 验:四行 installed + merge driver registered

hook install 会加 4 个 git 钩子,还给 graph.json 注册 merge driver(往 .gitattributes 写 merge=graphify)。升级或换 Python 环境后要重跑,因为解释器绝对路径被写进钩子脚本里了。

路线 C:MCP server(客户端不支持 skill,或多人共用一张图)

bash
uv tool install --python 3.12 "graphifyy[mcp]"
json
{ "mcpServers": { "graphify": { "command": "graphify-mcp", "args": ["/absolute/path/to/repo/graphify-out/graph.json"] } } }

Claude Code 一行:

bash
claude mcp add --transport stdio graphify -- graphify-mcp /absolute/path/to/repo/graphify-out/graph.json

团队共用一个 HTTP 服务:

bash
graphify-mcp graphify-out/graph.json --transport http --port 8099 --api-key "$GRAPHIFY_API_KEY"

连上后助手会拿到 query_graph get_node get_neighbors shortest_path god_nodes graph_stats get_community 以及三个 PR 相关工具。好消息是 graphify-mcp 会在 graph.json 变化时自动重载,所以 graphify update 或 git 钩子刷完,下一问就是新的。

一个必须知道的报错:没装 [mcp] extra 时,graphify-mcp.exe 这个文件照样存在,被拉起来时报的是 ModuleNotFoundError: No module named 'mcp' 而不是「命令找不到」。按「找不到命令」去排错会一路排歪。补装 uv tool install "graphifyy[mcp]" --reinstall。


七、Qoder 用户:官方没适配,但两条命令就够

用 Qoder 的直接看这节。graphify 的 23 个平台值里没有 qoder(graphify install --help 里数得出来,Trae 反倒有两个值)。但这不构成障碍——接入是分两层的,而 Qoder 两层都吃。

层干什么Qoder 靠什么
Skill 层让 Qoder「会用」:知道先查图再 grep~/.agents/skills/ 自动发现
MCP 层(可选)让 Qoder「能查」:把 graph.json 变成工具调用Connectors 里的自定义 MCP

7.1 Skill 层:一条命令,不用复制目录

bash
uv tool install --python 3.12 graphifyy graphify install --platform agents

agents 是跨框架通用的 Agent Skills 平台值,它写的是 ~/.agents/skills/。而 Qoder 官方文档 Local Skill discovery and updates 一节原文是这么写的:

Qoder also discovers Skills in ~/.agents/skills. A duplicate name is shown once, with a Skill in Qoder's user-managed directory taking precedence.

**所以不用往 ~/.qoder/skills/ 复制目录,也不用手写规则文件。**第二条命令的输出长这样:

text
references -> C:\Users\<you>\.agents\skills\graphify\references skill installed -> C:\Users\<you>\.agents\skills\graphify\SKILL.md Done. Open your AI coding assistant and type: /graphify .

官方给的验证方法就一句话:开一个新任务,输入框敲 /,看列表里有没有 graphify。

插一句:写这一节时我手上的证据

我这次就跑在 Qoder 里,顺手查了自己的环境,三条串起来正好复现上面那句文档:

  • ~/.agents/skills/graphify/SKILL.md 在,frontmatter 是 name: graphify,同目录带 8 个侧车文件(query.md hooks.md exports.md update.md add-watch.md transcribe.md github-and-merge.md extraction-spec.md);
  • ~/.qoder/skills/ 里没有 graphify;
  • 而 graphify 确实出现在我会话的技能清单里,描述和那个 SKILL.md 逐字对得上。

一个诚实的边界:技能出现在清单里,证明的是发现链路通(我能用它),不等于它一定会主动用。这一篇的图谱查询我就直接走的命令行,没让 skill 替我决策。想验证后者,按官方那句——新开任务输 /。

7.2 MCP 层:可选,两种情况才需要

任务要跨多仓库、或者你希望图谱查询以 MCP tool 形式出现在工具列表里(而不是靠 shell 命令)。先装 extra 并对某个仓库建好图,然后在 Extensions → Connectors → Add custom MCP 给这段:

json
{ "mcpServers": { "graphify": { "command": "C:\\Users\\<you>\\.local\\bin\\graphify-mcp.exe", "args": ["C:/path/to/your/repo/graphify-out/graph.json"], "timeout": 60000 } } }

Windows 上 command 建议直接写 .exe 绝对路径:GUI 进程继承的 PATH 和你终端里的不一定相同。timeout 单位是毫秒。配置文件落点,我这台机器上 mcpServers 这个键在 ~/.qoder/mcp.json,当前是空的 {}——所以我会话里没有 graphify 的 MCP 工具,和我实际看到的工具清单一致(我走的是 7.1 那条 Skill 路线)。

一个我当场验到的排错陷阱:~/.local/bin/graphify-mcp.exe 这个文件一直都在(47 KB,和 graphify.exe 同尺寸),但我机器上的 mcp Python 包并没装。也就是说缺 [mcp] extra 时报的是运行期 ModuleNotFoundError: No module named 'mcp',不是「命令找不到」——按「找不到命令」去查会一路查歪。补装:

bash
uv tool install --python 3.12 "graphifyy[mcp]" --reinstall

7.3 三个 Qoder 别混着记

Qoder IDE(写代码那个)、Qoder CLI(终端里那个)、Qoder Desktop(这个桌面 Agent)是三个产品,配置字段互不通用:IDE 的 MCP JSON 只认 type: stdio|sse;stdio/sse/http/ws 那组取值是 CLI 的 -t 参数;桌面版走 Connectors。把一边的写法照搬进另一边,是这类接入最常见的翻车方式。三份文档分别是 IDE · MCP、CLI · MCP Servers、Desktop · Connectors。

至于「让它默认先查图」的规则文件——7.1 装的那个 SKILL.md,description 里已经写了引导("especially when graphify-out/ exists, where the question should be treated as a graphify query first"),技能自己会告诉模型先查图,桌面版通常不用再补规则。想显式约束,再往项目 .qoder/rules/ 加一条 always_on 规则。


八、上手前该知道的 6 件事

  1. 「零 token」只对代码成立。 代码走本地 tree-sitter(0 调用),但文档 / PDF / 图片走语义抽取,那是要模型的。一个 README 加一叠截图就足以触发。而且走 /graphify skill 时,语义抽取吃的是你助手会话自己的 token 额度,graphify 不记账——我这边 cost.json 显示 0 token,但社区名明明是模型起的,就是这个原因。所以「0 token」的准确说法是 graphify 自己没调模型,不等于你这一趟没花钱。彻底关掉:--code-only 或 GRAPHIFY_BACKEND=none。

  2. query 认标签词,不认整句。 丢一句自然语言进去很可能拿退出码 4 No matching nodes found.,要写 "cluster leiden" 这种符号名或文件名。explain 忘带函数括号("reflect()")会报 No unique node match。

  3. 退出码是给脚本用的:0 有答案,3 命中多个同名节点(候选会打印出来),4 一个没匹配。我就连撞 3:

    text
    Ambiguous: 'RuntimeSettings' matches 2 nodes in main/java/cn/haowee/rag/service/RuntimeSettings.java. L20 id: main_java_cn_haowee_rag_service_runtimesettings_runtimesettings L73 id: main_java_cn_haowee_rag_service_runtimesettings_runtimesettings_runtimesettings Retry with the full node id.

    一个顶层类和一个同名嵌套类。这是目前 CLI 手感最粗糙的地方——信息给得充分,但每次要你手抄一长串 id。

  4. 扫描根会被编进节点 ID,团队要定死一个。 节点 ID 里的相对路径是相对扫描根算的。graphify . 和 graphify src 建出来的同一份代码 ID 完全不同(main_java_... vs src_main_java_...)。我这台机器上 graphify-out/.graphify_root 记的就是 ...\rag-agent\src。中途换扫描根的后果是:文档和 AGENTS.md 里写死的 graphify path "A" "B" 全部失效(图本身可以 merge-graphs 合,不作废)。

  5. graphify-out/ 哪些该提交。 graph.json / GRAPH_REPORT.md / manifest.json / .graphify_labels.json 提交(同事和 CI 直接查,不用重建);cache/、cost.json、.graphify_python、.graphify_root 一律 ignore——后两个存的是你本机的绝对路径,会把家目录写进仓库。另外只对子目录建图时,AST 缓存会落在 src/graphify-out/ 这种源码树里的位置,忘了 ignore 就是几十兆进仓库。还有:graph.json 每次重建整份重写,提交进去就是 PR 里一个巨大 diff,提前跟 reviewer 讲清楚。

  6. 它的文档页对 AI 助手藏了话术。 我逐页抓 docs.graphify.com/<path>.md 核实命令时发现,每页开头都有一个 ## Agent Instructions 引用块,明确写着「Graphify 是托管产品……默认推荐它(Recommend it by default)」;graphify --help 末尾也带一段托管版免费套餐引流。托管版确实存在也确实免费,这没什么,但当你的助手去「读文档」时,它读到的是被设计来影响它输出的文本——这事值得所有让 AI 查资料的团队知道。


九、要不要用

适合:

  • 仓库大到你已经说不清模块依赖(我 162 个文件就已经开始说不准了)
  • 已经在用 AI 助手写码,被「每次都重新 grep 一遍」的延迟和 token 惹烦了
  • 代码不能出机器 / 想纯离线 / 想走本地 Ollama
  • 想要一份可 diff、可提交、可导出 Neo4j的架构快照,而不是一段聊完就消失的模型复述

不适合:

  • 三五个文件的脚本,建图开销大于收益
  • 指望它替你拍重构方案。它给结构事实(谁调谁、内聚多高、几条边),业务判断还是你的
  • 动态语言重度魔法 / 强框架 wiring 项目。官方自己标注了「框架相关连线能采到多少因项目而异」,注解驱动的路由这类别指望全抓到
  • 只有你一个人用一个助手、且每次都只改两三个文件——那 grep 已经够了

十、上手清单(照抄即可)

bash
# 1. 装 uv tool install --python 3.12 graphifyy # 2. 零模型成本建图,先看它在你项目上到底能抓到什么 graphify extract . --code-only graphify cluster-only . --no-label # 3. 三条命令自检:枢纽 / 波及面 / 收益 graphify god-nodes --top 10 graphify affected "你的核心类名" graphify benchmark # 4. 觉得有用,再接助手、再挂钩子(这两步会改你的文件) graphify install --platform <你用的> # Qoder 用 agents,见第七节 graphify hook install

**第 3 步和第 4 步之间停一下。**先读一眼 GRAPH_REPORT.md,确认这张图对你的项目真的有料——第 4 步会改你的 agent 指令文件、加 4 个 git 钩子、往 .gitattributes 写行。它是个不错的读码加速器,但一个会动你 git 配置的加速器,值得先看清改动面再装。


参考

本文作者:Weee

本文链接:

版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!