graphify 入门指南

简介

graphify 是一个强大的 AI 编码助手技能，它能将你的代码库、文档、论文、图片、视频等转换为知识图谱，帮助你快速理解代码库结构，发现架构决策背后的”为什么”。

核心价值

  • 71.5x 更少的 Token 消耗：相比直接读取原始文件，查询知识图谱效率提升数十倍
  • 多模态支持：代码、PDF、Markdown、截图、图表、白板照片、视频、音频文件
  • 25 种编程语言：通过 tree-sitter AST 解析（Python、JS、TS、Go、Rust、Java、C、C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、Elixir、Objective-C、Julia、Verilog、SystemVerilog、Vue、Svelte、Dart）
  • 跨会话持久化：知识图谱保存在本地，随时可查询

工作原理

graphify 运行三个阶段：

  1. AST 解析：从代码文件中提取结构（类、函数、导入、调用图、文档字符串、注释），无需 LLM
  2. 音视频转录：使用 faster-whisper 本地转录视频和音频文件，转录结果被缓存
  3. 语义提取：Claude 子代理并行处理文档、论文、图片和转录文本，提取概念、关系和设计原理

最终输出：

  • graph.html - 交互式图谱可视化
  • GRAPH_REPORT.md - 核心节点、意外连接、建议问题
  • graph.json - 持久化图谱数据

快速入门（5分钟）

前置要求

  • Python 3.10+
  • 任一支持的 AI 编码助手：Claude Code、Codex、OpenCode、Cursor、Gemini CLI、GitHub Copilot CLI、VS Code Copilot Chat、Aider、OpenClaw、Factory Droid、Trae、Hermes、Kiro 或 Google Antigravity

安装

1
pip install graphifyy && graphify install

注意：PyPI 包名为 graphifyy（双 y），CLI 命令为 graphify。

基本使用

在你的 AI 编码助手中输入：

1
/graphify .

这将在当前目录生成知识图谱，输出到 graphify-out/ 文件夹。

查看结果

1
2
3
4
5
# 打开交互式图谱
open graphify-out/graph.html

# 查看分析报告
cat graphify-out/GRAPH_REPORT.md

详细教程

1. 平台特定安装

不同平台需要不同的安装命令：

平台 安装命令
Claude Code (Linux/Mac) graphify install
Claude Code (Windows) graphify install 或 graphify install --platform windows
Codex graphify install --platform codex
OpenCode graphify install --platform opencode
GitHub Copilot CLI graphify install --platform copilot
VS Code Copilot Chat graphify vscode install
Aider graphify install --platform aider
Cursor graphify cursor install
Gemini CLI graphify install --platform gemini
Kiro IDE/CLI graphify kiro install

2. 常用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 分析特定文件夹
/graphify ./raw

# 深度模式 - 更激进的推断边提取
/graphify ./raw --mode deep

# 增量更新 - 只处理变更文件
/graphify ./raw --update

# 构建有向图
/graphify ./raw --directed

# 跳过 HTML 可视化
/graphify ./raw --no-viz

# 生成 Obsidian 笔记库
/graphify ./raw --obsidian

# 自动同步 - 文件变更时自动更新图谱
/graphify ./raw --watch

3. 查询知识图谱

1
2
3
4
5
6
7
8
9
10
11
12
# 查询图谱
graphify query "show the auth flow"
graphify query "what connects DigestAuth to Response?"

# 查找最短路径
graphify path "DigestAuth" "Response"

# 解释节点
graphify explain "SwinTransformer"

# 指定图谱文件
graphify query "..." --graph path/to/graph.json

4. 添加外部内容

1
2
3
4
5
6
7
8
# 添加论文
/graphify add https://arxiv.org/abs/1706.03762

# 添加视频
/graphify add <video-url>

# 添加并标注作者
/graphify add https://... --author "Name" --contributor "Name"

5. 排除特定路径

在项目根目录创建 .graphifyignore 文件：

1
2
3
4
5
# .graphifyignore
vendor/
node_modules/
dist/
*.generated.py

语法与 .gitignore 相同。

6. 团队协作

graphify-out/ 设计为提交到 git，让团队成员共享知识图谱。

推荐的 .gitignore 配置：

1
2
# 提交图谱输出，忽略提取缓存
graphify-out/cache/

团队工作流：

  1. 一人运行 /graphify . 构建初始图谱并提交 graphify-out/
  2. 其他人拉取后，AI 助手立即可读取 GRAPH_REPORT.md
  3. 安装 git hooks 实现代码变更后自动重建图谱

7. Git Hooks 自动化

1
2
3
4
5
6
7
8
# 安装 git hooks（提交和分支切换后自动重建图谱）
graphify hook install

# 查看状态
graphify hook status

# 卸载
graphify hook uninstall

8. 让 AI 助手始终使用图谱

安装”始终开启”指令：

1
2
3
4
5
6
7
8
9
10
# Claude Code
graphify claude install

# Cursor
graphify cursor install

# Gemini CLI
graphify gemini install

# 其他平台参考 README

这会：

  • 写入配置文件让 AI 在回答架构问题前先读取图谱报告
  • 安装 PreToolUse 钩子，在搜索文件前提醒 AI 使用图谱

进阶用法

视频和音频处理

1
2
3
4
5
6
7
8
# 安装视频支持
pip install 'graphifyy[video]'

# 处理视频/音频文件
/graphify ./my-corpus

# 使用更大的 Whisper 模型提高准确率
/graphify ./my-corpus --whisper-model medium

支持的格式：.mp4、.mov、.mkv、.webm、.avi、.m4v、.mp3、.wav、.m4a、.ogg

导出格式

1
2
3
4
5
6
7
8
9
10
11
# 导出 SVG
/graphify ./raw --svg

# 导出 GraphML（用于 Gephi、yEd）
/graphify ./raw --graphml

# 生成 Neo4j Cypher 脚本
/graphify ./raw --neo4j

# 直接推送到 Neo4j 实例
/graphify ./raw --neo4j-push bolt://localhost:7687

MCP 服务器

将图谱暴露为 MCP 服务器，让 AI 助手通过工具调用直接查询：

1
python -m graphify.serve graphify-out/graph.json

生成 Wiki

1
2
# 生成 Wikipedia 风格的 Markdown 文章
/graphify ./raw --wiki

输出 index.md 入口文件，每个社区生成一篇文章。

输出说明

God Nodes（核心节点）

度数最高的概念 - 所有内容都通过它们连接。

Surprising Connections（意外连接）

按综合得分排名，代码-论文边排名高于代码-代码边。每个结果包含简明的”为什么”解释。

Suggested Questions（建议问题）

图谱独特视角能回答的 4-5 个问题。

Confidence Scores（置信度分数）

每条 INFERRED 边都有 confidence_score（0.0-1.0）。EXTRACTED 边始终为 1.0。

关系标签

  • EXTRACTED - 直接从源码中发现
  • INFERRED - 合理推断（带置信度分数）
  • AMBIGUOUS - 需要审查

常见问题

Windows 上 graphify: command not found

pip 用户脚本位于 %APPDATA%\Python\PythonXY\Scripts，将其添加到 PATH 或使用：

1
python -m graphify

macOS pipx 安装后找不到命令

1
2
pipx ensurepath
# 然后重启终端

如何只更新代码部分？

1
graphify update ./src

代码文件通过 AST 本地处理，无需 LLM 调用。

如何重新聚类？

1
graphify cluster-only ./my-project

在现有 graph.json 上重新运行聚类，无需重新提取。

隐私说明

  • 代码文件：通过 tree-sitter AST 本地处理，文件内容不会离开你的机器
  • 视频/音频：使用 faster-whisper 本地转录，音频不会离开你的机器
  • 文档/论文/图片：发送到 AI 平台的模型 API 进行语义提取
  • 无遥测：不收集使用数据或分析

相关链接

总结

graphify 是理解复杂代码库的利器：

  1. 快速上手：pip install graphifyy && graphify install，然后 /graphify .
  2. 多模态输入：代码、文档、论文、图片、视频都能处理
  3. 高效查询：71.5x Token 节省，跨会话持久化
  4. 团队协作：提交 graphify-out/ 让所有人共享知识图谱
  5. 自动化：Git hooks 和 watch 模式让图谱始终保持最新

开始使用 graphify，让你的 AI 编码助手真正理解你的代码库！