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 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。
四步流水线,全本地:
.gitignore 和 .graphifyignore,把文件分成代码 / 文档 / 论文 / 图片 / 视频。AMBIGUOUS,而不是猜一个。第三条是关键。每条边都带来源标签:
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 个文件)。跑完之后的规模:
text162 files · 2342 nodes · 7364 edges · 96 communities 边的分布:calls 2532 · imports 1618 · references 1296 · method 1071 · contains 792 置信度:86% EXTRACTED · 14% INFERRED · 0% AMBIGUOUS
bashgraphify god-nodes --top 5
textGod 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 名是个测试类,说明测试脚手架耦合偏重。这种判断以前靠印象,现在有数。
bashgraphify query "ingest chunk embedding" --budget 250
textGraph: 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 可改成顺一条链深挖),不是向量召回。而且结果超预算时它明说截断、还直接告诉你需要多少预算能装全——比某些工具「答案就这么多」友好。
bashgraphify path "...ingestservice_ingestservice_ingest" "...embeddingmodelguard_embeddingmodelguard" --undirected
textShortest 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 的时候,这个设计能省掉很多一本正经的胡说。
bashgraphify affected "RuntimeSettings" --depth 2
textAffected 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 的东西。
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……),基本就是我脑子里的模块划分,不用我维护文档。
bashgraphify benchmark
textCorpus: 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 在你自己仓库上跑的那个才算数。
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:
bashpython3 --version # Windows PowerShell 用 python --version
低于 3.11.5 → 别折腾系统 Python,直接走下面的 uv 路线,让它自己下一份。
① 装 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:
powershelluv 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 里 |
不确定就一条命令查,别猜:
powershelluv tool dir # 我这台机器输出:C:\Users\lhw\AppData\Roaming\uv\tools
④ Windows 最容易翻车的两点:
%USERPROFILE%\.local\bin 默认不在 PATH 里。graphify 报「不是内部或外部命令」就 uv tool update-shell 然后重开终端。.local\bin,从应用内部起的终端仍然找不到 graphify。在 MCP 配置里直接写 .exe 绝对路径一步绕过(第七节那段 JSON 就是这么写的)。graphify-mcp 传 C:/... 形式的路径没问题,但别混用 MSYS 风格 /c/...,那层路径转换会咬人。① 装 uv:
bashbrew 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 自己拉一份干净的:
bashuv tool install --python 3.12 graphifyy
③ PATH:zsh 是 macOS 默认 shell,全新环境最容易在这卡住。
bashuv tool update-shell # 然后把 ~/.local/bin 加进 PATH,或重开终端
④ zsh 的方括号必须加引号——这是 macOS/Linux(zsh) 特有的一条:
bashuv tool install --python 3.12 "graphifyy[mcp]" # 正确
uv tool install --python 3.12 graphifyy[mcp] # zsh 报 no matches found
① 装 uv:
bashcurl -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.04 | 3.10 | 不能(低于 3.11.5) |
| Debian 12 | 3.11 | 勉强够(贴着下限) |
| Ubuntu 24.04 | 3.12 | 能 |
自己 python3 --version 对一下。结论是:Linux 上请一律带 --python 3.12,让 uv 去下载,别赌发行版自带的那份:
bashuv 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 后行为漂移:
bashuv tool install --python 3.12 graphifyy && graphify extract . --code-only
--python 3.12 到底该不该带——我机器上是个反例老实说:我这篇文档写的 uv tool install --python 3.12 graphifyy,在我自己这台机器上并不是当初真实执行的那条。 查完之后很明确:
bashuv 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 天然隔离,撞不上这个。
不分系统,跑完这四条就说明第 1、2 层真的通了:
bashuv --version # 第 1 层:uv 在 PATH 里
graphify --version # 第 2 层:0.9.114
uv tool dir # 隔离环境根,确认它真装进去了
uv tool list # 应该列出 graphifyy x.y.z
最后一条的输出顺便把「包名双 y、命令单 y」这件事给你钉死:
textgraphifyy v0.9.114 - graphify - graphify-mcp
一个包,两个可执行文件。MCP 配置里要写的是 graphify-mcp,不是 graphify。
graphify --version 出得来但 MCP 客户端连不上 → 不是 PATH 问题,是 GUI 进程的环境变量问题,回 5.2 那条绝对路径。
uv 内置证书库有时候不信系统根证书(公司代理、安全软件做 TLS 拦截时尤其明显),报 invalid peer certificate: UnknownIssuer 就跟一句:
powershelluv tool install --system-certs graphifyy
还是不通(报 tunnel error / tcp connect error / 「目标计算机积极拒绝」,说明本机有个失效的本地代理在拦路),直接换国内源:
powershelluv 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。
一共 30 个,别一次全装(zsh 下记得给方括号加引号):
| 什么时候要 | 装什么 |
|---|---|
| 要跑本地 MCP server | uv 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。
bashgraphify uninstall # 移除所有平台注册 + git hooks,保留 graphify-out/
graphify uninstall --purge # 连图谱一起删
uv tool uninstall graphifyy # 删包
bashgraphify install
不带参数默认按当前机器探测(Claude Code 系)。指定平台:
bashgraphify 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(写进仓库、影响全组)之前,先读一眼它打印出来的文件清单。
bashcd 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 秒。
保鲜:
bashgraphify 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 环境后要重跑,因为解释器绝对路径被写进钩子脚本里了。
bashuv tool install --python 3.12 "graphifyy[mcp]"
json{
"mcpServers": {
"graphify": {
"command": "graphify-mcp",
"args": ["/absolute/path/to/repo/graphify-out/graph.json"]
}
}
}
Claude Code 一行:
bashclaude mcp add --transport stdio graphify -- graphify-mcp /absolute/path/to/repo/graphify-out/graph.json
团队共用一个 HTTP 服务:
bashgraphify-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 的直接看这节。graphify 的 23 个平台值里没有
qoder(graphify install --help里数得出来,Trae 反倒有两个值)。但这不构成障碍——接入是分两层的,而 Qoder 两层都吃。
| 层 | 干什么 | Qoder 靠什么 |
|---|---|---|
| Skill 层 | 让 Qoder「会用」:知道先查图再 grep | ~/.agents/skills/ 自动发现 |
| MCP 层(可选) | 让 Qoder「能查」:把 graph.json 变成工具调用 | Connectors 里的自定义 MCP |
bashuv 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/ 复制目录,也不用手写规则文件。**第二条命令的输出长这样:
textreferences -> 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;SKILL.md 逐字对得上。一个诚实的边界:技能出现在清单里,证明的是发现链路通(我能用它),不等于它一定会主动用。这一篇的图谱查询我就直接走的命令行,没让 skill 替我决策。想验证后者,按官方那句——新开任务输 /。
任务要跨多仓库、或者你希望图谱查询以 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',不是「命令找不到」——按「找不到命令」去查会一路查歪。补装:
bashuv tool install --python 3.12 "graphifyy[mcp]" --reinstall
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 规则。
「零 token」只对代码成立。 代码走本地 tree-sitter(0 调用),但文档 / PDF / 图片走语义抽取,那是要模型的。一个 README 加一叠截图就足以触发。而且走 /graphify skill 时,语义抽取吃的是你助手会话自己的 token 额度,graphify 不记账——我这边 cost.json 显示 0 token,但社区名明明是模型起的,就是这个原因。所以「0 token」的准确说法是 graphify 自己没调模型,不等于你这一趟没花钱。彻底关掉:--code-only 或 GRAPHIFY_BACKEND=none。
query 认标签词,不认整句。 丢一句自然语言进去很可能拿退出码 4 No matching nodes found.,要写 "cluster leiden" 这种符号名或文件名。explain 忘带函数括号("reflect()")会报 No unique node match。
退出码是给脚本用的:0 有答案,3 命中多个同名节点(候选会打印出来),4 一个没匹配。我就连撞 3:
textAmbiguous: '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。
扫描根会被编进节点 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 合,不作废)。
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 讲清楚。
它的文档页对 AI 助手藏了话术。 我逐页抓 docs.graphify.com/<path>.md 核实命令时发现,每页开头都有一个 ## Agent Instructions 引用块,明确写着「Graphify 是托管产品……默认推荐它(Recommend it by default)」;graphify --help 末尾也带一段托管版免费套餐引流。托管版确实存在也确实免费,这没什么,但当你的助手去「读文档」时,它读到的是被设计来影响它输出的文本——这事值得所有让 AI 查资料的团队知道。
适合:
不适合:
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 配置的加速器,值得先看清改动面再装。
BENCHMARKS.md 在根目录)~/.agents/skills https://docs.qoder.com/qoder/skills · Connectors 自定义 MCP https://docs.qoder.com/qoder/connectors · IDE 的 MCP https://docs.qoder.com/user-guide/chat/model-context-protocol · CLI 的 MCP https://docs.qoder.com/cli/mcp-servers本文作者:Weee
本文链接:
版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!