共计 5772 个字符，预计需要花费 15 分钟才能阅读完成。
Graphify 是一个开源的命令行工具，也是一个给 AI 编程助手用的技能。它把一个代码库连同里面的文档、SQL 表结构、配置文件和 PDF 解析成一张知识图谱，存成 graph.json，之后你和 AI 助手都可以直接查这张图，不用每次从头翻文件。
截至 10 月 25 日下午（北京时间），Graphify-Labs/graphify 在 GitHub 上有 134,591 个 star，许可证是 Apache-2.0。项目早期以 MIT 许可贡献的那部分代码仍可按 MIT 使用，仓库里保留了 LICENSE-MIT 文件。最新版本 v0.9.95 在北京时间 10 月 24 日凌晨发布，PyPI 上同步更新。
这篇分两条路线讲部署。路线一是在本机或 VPS 上装好命令行、给项目建图、用命令查询。路线二是用仓库自带的 Dockerfile，在 VPS 上把图谱开成一个带密钥的 HTTP MCP 服务，让几台电脑上的 AI 助手共用同一份图谱。路线一的命令我在一台 Linux 机器上实际跑过，路线二的 Docker 部分是按官方 Dockerfile 写的，下文会说明哪些地方没有实测。
Graphify 能做什么
在支持技能的 AI 编程助手里输入 /graphify .，它会扫描当前项目，在项目下生成一个 graphify-out 目录，里面有三个文件：
graph.html：浏览器直接打开，可以点节点、筛选、搜索；GRAPH_REPORT.md：一份要点报告，列出连接最多的核心概念、自动划分的模块（社区）和建议提问；graph.json：完整图谱，后续查询都读这个文件。
代码部分用 tree-sitter 做语法树解析，在本地完成，不调用大模型，代码不会离开你的机器。README 写的是支持大约 40 种语言的跨文件关系，包括调用、导入和继承。文档、PDF、图片和音视频要做语义提取（音视频先在本地用 faster-whisper 转写），这一步才需要模型：在助手里用 /graphify 时用的是助手当前的模型，在命令行里无人值守运行时要配置 API key。
图里的每条边都带一个标签。EXTRACTED 表示源码里明写的关系，比如一个 import；INFERRED 表示 Graphify 解析推断出来的关系。看到一条边时，你能分清它是读出来的还是推出来的。Graphify 不做向量索引，没有 embedding，也不需要向量数据库。
准备环境
官方要求 Python 3.10 或更高，推荐用 uv 安装，也可以用 pipx。以 Ubuntu 或 Debian 的 VPS 为例，二选一即可：
# 方式 A：装 uv (README 推荐)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 方式 B：用系统包装 Python 和 pipx
sudo apt install python3.12 python3-pip pipx
注意，PyPI 上的官方包名是 graphifyy，结尾两个 y。README 专门提醒过，PyPI 上其他名字带 graphify 的包和官方无关。装好以后命令行里的命令仍然叫 graphify。
路线一：在本机或 VPS 上建图
1. 安装命令行
uv tool install graphifyy
# 或者
pipx install graphifyy
用 uv 装完提示找不到 graphify 命令时，运行一次 uv tool update-shell，再重新打开终端。我测试时 uv 把命令装在 ~/.local/bin，这个目录不在 PATH 里就会出现这种情况。
如果想不用 Docker、直接在本机或 VPS 上开 MCP 服务（见路线二第 4 步），安装时带上 mcp 扩展。走 Docker 的话镜像里会自带，不用在宿主机上装：
uv tool install "graphifyy[mcp]"
装完运行 graphify --version，我这边输出的是 graphify 0.9.95。同时会多出一个 graphify-mcp 命令，后面会用到。
2. 注册到你的 AI 助手
graphify install
README 开头说这条命令会检测你在用的助手，但同一份 README 的平台表和源码都写明，不带参数的 graphify install 默认只给 Claude Code 注册（在 Windows 上换成 Windows 版的 Claude Code）。用其他助手时要显式指定平台，README 列了 20 多个，常用的几个是：
graphify cursor install # Cursor
graphify install --platform codex # Codex
graphify install --platform gemini # Gemini CLI
想把技能装进当前仓库而不是用户目录，加 --project，方便和团队一起提交。注册完在助手里输入 /graphify . 就能建图。Codex 里的写法是 $graphify。
3. 不用任何 API key，只给代码建图
在 VPS 上通常没有图形界面的 AI 助手，这时用 graphify extract 在命令行里直接建图。只给代码建图不需要 API key，可以完全离线：
cd /path/to/your-repo
GRAPHIFY_BACKEND=none graphify extract . --code-only
--code-only 表示跳过文档、PDF 和图片，只索引代码。GRAPHIFY_BACKEND=none 会关掉所有大模型后端，防止机器上恰好有某个 API key 时被自动调用。
我拿一个小型 Python 库 pallets/itsdangerous 试了一次，用时约 1.4 秒，输出的最后几行是：
[graphify extract] wrote /tmp/demo/graphify-out/graph.json: 364 nodes, 691 edges, 19 communities
[graphify extract] next: run `graphify cluster-only /tmp/demo` to generate GRAPH_REPORT.md and name communities
这里要注意，extract 只写出 graph.json。要拿到报告和可视化页面，按提示再跑一次：
GRAPHIFY_BACKEND=none graphify cluster-only . --no-label
--no-label 表示不调用模型给社区起名，社区会显示成 Community 0、Community 1 这样的编号。跑完以后 graphify-out 下就有了 GRAPH_REPORT.md 和 graph.html。VPS 上没有浏览器，可以把 graph.html 下载到自己电脑上打开。
下面这张是官方 README 里的界面截图，展示的是 FastAPI 代码库的图谱，右边是按颜色区分的社区列表。
图源：Graphify 官方 README（github.com/Graphify-Labs/graphify，Apache-2.0）
如果项目里的文档也想进图谱，就要给 extract 配一个模型后端。README 列出的选项有 Gemini、Kimi、Claude、OpenAI、DeepSeek、Azure、Bedrock 和本地 Ollama，有对应的 API key 时会自动选用，也可以用 --backend 指定。这部分我没有实测。
4. 在命令行里查询图谱
建好图以后有三个常用查询命令：
graphify query "how is a token signed" # 用一句话提问，返回相关的子图
graphify explain "Signer" # 解释一个节点和它的连接
graphify path "A" "B" # 找两个节点之间的最短路径
实际用的时候会碰到重名。我在测试库里查 Signer，源码和测试文件里各有一个，Graphify 不会自己挑一个，它列出两个候选，让我用“文件路径::名称”的写法重查：
graphify explain "src/itsdangerous/signer.py::Signer"
这次就返回了节点所在文件、行号和 25 条连接，每条连接后面都标着 EXTRACTED 或 INFERRED。写脚本时可以看退出码：0 表示有结果，3 表示名称有歧义，4 表示没找到节点。
代码改了以后，用 graphify update . 只重新提取代码文件，不花模型费用。
路线二：用 Docker 在 VPS 上开 HTTP MCP 服务
MCP 是 AI 助手调用外部工具的协议。Graphify 自带一个 MCP 服务，可以把 graph.json 开成服务，让助手通过 MCP 直接查询。仓库根目录的 Dockerfile 就是为这个用途写的，注释里说明它把 Graphify 的 MCP 服务做成一个共享的 HTTP 服务。
先说清楚三点。第一，仓库里没有 docker-compose 文件，我也没有查到官方发布的预构建镜像，需要自己 build。第二，图谱不打包进镜像，运行时把 graph.json 挂载进去。第三，我写这篇用的机器上没有 Docker，下面的 build 和 run 命令以官方 Dockerfile 注释为准，run 命令我加了几个参数（后面会说明），都没有实测。
1. 先准备好 graph.json
按路线一在 VPS 上给项目建图，或者在自己电脑上建好后把 graphify-out 目录传到 VPS。容器里只需要 graph.json。
2. 构建镜像
git clone https://github.com/Graphify-Labs/graphify.git
cd graphify
docker build -t graphify .
镜像基于 python:3.12-slim，从源码安装 Graphify 和 mcp 扩展，以 uid 10001 的普通用户运行，对外暴露 8080 端口。
3. 运行容器
回到你的项目目录，先生成一个随机密钥，再启动：
export SECRET=$(openssl rand -hex 32)
docker run -d --name graphify-mcp -p 127.0.0.1:8080:8080 \
-v "$(pwd)/graphify-out:/data" graphify \
/data/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"
官方注释里的端口写法是 -p 8080:8080。我改成了 127.0.0.1:8080:8080，只让本机访问，外部访问交给下一步的反向代理。如果你打算直接暴露端口，可以用官方写法，但一定要带 --api-key。源码里写明，绑定 0.0.0.0 又不设密钥时，服务会打印警告，因为这样谁都能访问你的图谱。-d 和 --name 是我加的，用来后台运行和方便管理。
服务地址是 http://<主机>:8080/mcp。客户端请求时在请求头里带上 Authorization: Bearer <密钥> 或 X-API-Key: <密钥>。
4. 不用 Docker 的等价做法
如果 VPS 上不想装 Docker，装了 graphifyy[mcp] 以后直接运行：
graphify-mcp graphify-out/graph.json --transport http --host 127.0.0.1 --port 8080 --api-key "$SECRET"
这条我实测过：不带密钥的请求返回 401，带上 Authorization: Bearer 头的初始化请求返回 200，服务端报的版本是 graphify 0.9.95。长期运行可以交给 systemd 或进程管理工具，具体配置按你的习惯来。
5. 反向代理和 HTTPS
要从外网访问，建议在前面放一层 Nginx 或 Caddy，配上 HTTPS 证书，再把 /mcp 转发到 127.0.0.1:8080。这个 HTTP 服务默认用流式响应（SSE）返回结果，常见做法是在反向代理上关闭响应缓冲，避免流被攒住。官方没有提供反向代理配置样例，这里不给现成配置，请按你用的代理软件文档设置。
各个 AI 助手怎么添加一个远程 HTTP MCP 服务，写法各不相同，请看你所用助手的 MCP 设置说明，填上地址和请求头即可。
更新和维护
代码有改动时，在项目目录运行 graphify update . 刷新 graph.json。MCP 服务的源码里写了图谱热重载：graph.json 的修改时间或大小变了，下一次查询会自动读新文件，所以一般不用重启容器。如果发现查询结果没变，再 docker restart graphify-mcp 一次。
升级 Graphify 本身：用 uv 安装的运行 uv tool upgrade graphifyy（这是 uv 自己的升级命令），Docker 路线进入 graphify 源码目录执行 git pull，再重新 docker build。v0.9.95 的更新说明里写了 AST 缓存格式有变动，升级后第一次建图会全部重新提取，耗时会比平时长一些。
这一版还修了一个安全问题：注册技能时写文件改用随机命名的临时文件，防止有人预先放一个符号链接，把写入重定向去覆盖其他文件。在多人共用的服务器上，建议升级到这个版本。
隐私和安全注意事项
- 只建代码图谱时，代码在本地解析，不需要 API key，README 写明没有遥测。
- 文档、PDF 和图片会发给你配置的模型后端做提取。README 特别注明，Kimi 后端（MOONSHOT_API_KEY）连接的是位于中国的 Moonshot 服务器，在意数据存放地点的话请留意。完全不想外发可以用本地 Ollama，或者用
GRAPHIFY_BACKEND=none只建代码图谱。 - 每次
query、path、explain和 MCP 查询都会记一行日志到~/.cache/graphify-queries.log，内容包括提问文本。不想留记录，设置环境变量GRAPHIFY_QUERY_LOG_DISABLE=1。 - 对外开放 MCP 服务时，密钥必须设，最好再加 HTTPS。图谱里包含代码结构和函数名，别人拿到就能看清项目内部怎么组织。
适合谁用
Graphify 适合经常让 AI 助手读中大型代码库的人。建一次图，助手问到项目结构时先查图，不用每次从头读文件。团队里几个人用同一个仓库时，把 graph.json 放到 VPS 上开成 MCP 服务，大家查的是同一份图谱。
只想先看看效果，从路线一开始就够了。小项目只给代码建图，extract 和 cluster-only 两条命令在我这边几秒内跑完，不需要任何密钥，然后在浏览器里打开 graph.html 看结构。
