Graphify 是一个将代码库、文档、PDF等多模态资料转化为可查询知识图谱的工具，特别适合与 AI 编程助手配合使用，能显著降低跨会话的 Token 消耗。它通过 AST 解析代码，语义提取文档，最终构建一张可持久化查询的图谱。

以下是根据官方文档整理的部署和使用指南。

📦 第一步：环境准备与安装

1.1 前置要求

  • Python 3.10+：在终端运行 python --version 检查。
  • AI 编程助手（可选）：如 Claude Code, Cursor, Codex 等，Graphify 可作为技能（Skill）安装到这些工具中。
  • 包管理工具（推荐）：uv 或 pipx，用于隔离安装环境，避免依赖冲突。

1.2 安装 Graphify

重要提醒：PyPI 上的官方包名为 graphifyy（末尾两个 y），但命令行命令依然是 graphify。

1
2
3
4
5
6
7
8
9
# 推荐方式1：使用 uv 工具安装（隔离环境）
uv tool install graphifyy
# 如果 'graphify' 命令找不到，运行 uv tool update-shell

# 推荐方式2：使用 pipx 安装（隔离环境）
pipx install graphifyy

# 备选方式：直接使用 pip 安装（可能需手动配置 PATH）
pip install graphifyy

安装后找不到 graphify 命令？ uv 或 pipx 会将命令安装在 ~/.local/bin 等目录。如果终端提示找不到，可以运行 uv tool update-shell (或 pipx ensurepath)，然后重新打开终端即可。

⚙️ 第二步：安装到你的 AI 编程助手

在项目目录中，将 Graphify 注册为 AI 助手的技能（Skill）：

1
2
3
4
5
6
7
8
9
10
11
# 进入你的项目根目录
cd /path/to/your/project

# 通用安装命令（适用于 Claude Code 等）
graphify install

# 如果使用其他平台，需指定 --platform，例如 Codex:
graphify install --platform codex

# 若希望仅安装到当前项目（而非用户全局），可加 --project 参数
graphify install --project

支持 20+ 种平台，完整列表可参考[官方文档]。

🚀 第三步：构建知识图谱

3.1 首次全量构建

在 AI 助手的对话框中输入以下命令，Graphify 便会扫描当前目录下的所有文件：

1
/graphify .
  • 如果要扫描指定目录，可以使用 /graphify ./my-project。
  • 首次构建耗时取决于项目大小，中型项目大约 5-10 分钟。

3.2 增量更新

当项目代码有变更时，无需重新全量扫描，使用 --update 参数只处理变化文件：

1
/graphify . --update

🔍 第四步：查询与使用图谱

构建完成后，项目根目录下会出现 graphify-out/ 文件夹，包含主要产出：

  • graph.html：交互式图谱，可在浏览器中点击探索。
  • GRAPH_REPORT.md：文字报告，列出核心节点、社区结构和意外连接。
  • graph.json：持久化的图谱数据，供后续查询使用。

常见查询命令（在 AI 助手中使用）

功能 命令示例
语义提问 /graphify query "数据库连接用了哪些中间件？"
查找节点间路径 /graphify path "UserAuth" "SessionStore"
解释某个节点 /graphify explain "CfgNode"
只重新聚类 /graphify . --cluster-only

⚙️ 第五步：高级配置与扩展功能

5.1 可选依赖安装

Graphify 支持多模态资料（音视频、Office文档等），按需安装对应扩展：

1
2
3
4
5
6
7
8
9
10
11
# 支持音视频转写 (使用 faster-whisper)
uv tool install "graphifyy[video]"

# 支持 .docx / .xlsx 文件
uv tool install "graphifyy[office]"

# 支持 PDF 抽取
uv tool install "graphifyy[pdf]"

# 安装所有扩展
uv tool install "graphifyy[all]"

5.2 命令行查询（无需 AI 助手）

也可以直接在终端使用 graphify 命令查询图谱：

1
2
graphify query "attention 和 optimizer 如何连接？"
graphify path "DigestAuth" "Response"

🩺 常见问题与排障

  1. pip install graphifyy 报错或找不到包？
    可以尝试升级 pip 或使用清华等国内镜像源。另外，官方强烈推荐使用 uv tool install 或 pipx install 来隔离安装环境。

  2. 构建速度太慢或文件太多怎么办？
    在项目根目录创建一个 .graphifyignore 文件，将 node_modules/、dist/、build/ 等无需扫描的目录写进去排除，能大幅缩短时间。

  3. graph.json 文件太大导致 AI 助手卡顿？
    可以在命令行中运行以下命令将其压缩为紧凑格式：

    1
    python -c "import json; from pathlib import Path; p=Path('graphify-out/graph.json'); d=json.loads(p.read_text()); p.write_text(json.dumps(d, separators=(',', ':')))"

  4. 在 PowerShell 中使用时提示错误？
    在 PowerShell 中，请使用 graphify . 而不是 /graphify .，因为前导斜杠是路径分隔符。