graphify-rs 使用手册

📊项目概述

graphify-rs 是一个用 Rust 编写的 AI 代码知识图谱构建工具。它通过 AST 解析源码，提取函数、类、文件间的调用与依赖关系，生成结构化的 graph.json，并输出多种格式的报告和可视化文件。

AST 解析，无需编译

基于 treesitter 进行语法分析，支持 50+ 语言，不需要编译或运行代码即可构建依赖图。

增量构建

--update 模式只重新解析新增或修改的文件，大型项目构建仅需 2~5 秒。

多格式输出

支持 JSON、HTML 可视化、GraphML、Cypher、Wiki、Obsidian、SVG 等 8 种格式。

AI 集成

原生支持 Claude Code、Codex、OpenClaw、Trae 等编辑器，也可作为 MCP Server 运行。

支持的编程语言

语言	文件扩展名	解析器
Java	`.java`	treesitter-java
Python	`.py`	treesitter-python
JavaScript / TypeScript	`.js` `.ts` `.tsx`	treesitter-typescript
Go	`.go`	treesitter-go
Rust	`.rs`	treesitter-rust
C / C++	`.c` `.cpp` `.h`	treesitter-c / cpp
Ruby	`.rb`	treesitter-ruby
PHP	`.php`	treesitter-php
其他	Markdown / TOML / JSON / YAML 等	通用解析

📦安装方式

方式一：Cargo 安装（推荐）

cargo install graphify-rs

方式二：从源码构建

git clone https://github.com/nicbarker/graphify.git
cd graphify
cargo build --release
# 产物在 target/release/graphify-rs

方式三：预编译二进制

从 GitHub Releases 下载对应平台的二进制文件，放入 PATH 即可。

验证安装是否成功：

graphify-rs --version

🚀5 分钟上手

步骤 1：初始化配置（可选） graphify-rs init 步骤 2：构建知识图谱 cd /path/to/your-project graphify-rs build --path . --output graphify-out 步骤 3：查看输出 ls graphify-out/ ├── graph.json # 图谱数据（核心产物） ├── index.html # 交互式可视化页面 ├── GRAPH_REPORT.md # 架构深度报告 └── wiki/index.md # Wiki 导航索引步骤 4：在 Claude Code 中使用 graphify-rs install --platform claude

首次构建时 --no-llm 会跳过 LLM 摘要生成，速度更快。需要 AI 增强报告时去掉此标志。

🔨build — 构建知识图谱

build 是核心命令，解析源代码并生成图谱数据。

基础用法

# 构建当前目录
graphify-rs build

# 构建指定目录，输出到自定义路径
graphify-rs build --path /path/to/project --output my-graph

# 增量构建（只解析变更文件）
graphify-rs build --path . --output graphify-out --update

常用参数

参数	默认值	说明
`-p, --path`	`.`	要扫描的项目目录
`-o, --output`	`graphify-out`	输出目录路径
`--update`	—	增量模式，仅重新解析新/修改的文件
`--no-llm`	—	跳过 LLM 增强，纯 AST 解析（更快）
`--code-only`	—	只解析代码文件，忽略文档/配置
`--format`	`all`	指定输出格式，逗号分隔
`--max-viz-nodes`	`2000`	HTML 可视化节点上限，超出会卡顿
`-j, --jobs`	CPU 核数	并行任务数
`-v, --verbose`	—	输出 debug 级别日志
`-q, --quiet`	—	静默模式，只输出错误

实用场景

大型 Java 项目首次构建：

graphify-rs build --path ./crmeb-mer --output graphify-out --max-viz-nodes 5000

日常开发增量更新：

# 修改代码后快速更新图谱
graphify-rs build --path . --output graphify-out --no-llm --update

只生成 JSON 数据（不生成 HTML/Wiki 等）：

graphify-rs build --path . --output graphify-out --format json

指定多种输出格式：

graphify-rs build --path . --output graphify-out --format json,wiki,report

--max-viz-nodes 设置过高会导致浏览器渲染卡顿，建议 2000 以下。超过 5000 仅适合在高性能机器上查看。

🔍query — 查询知识图谱

基于自然语言提问，工具会在图谱数据中进行图遍历和语义匹配，返回相关节点和关系。

基础用法

graphify-rs query "项目中有哪些 Controller 类？"
graphify-rs query "UserService 依赖了哪些模块？"
graphify-rs query "支付相关的方法有哪些？"

参数

参数	默认值	说明
`<QUESTION>`	必填	自然语言查询问题
`--graph`	`graphify-out/graph.json`	图谱数据路径
`--budget`	`2000`	图遍历预算（步数）
`--dfs`	—	使用深度优先搜索策略

查询问题越具体，返回结果越精准。"入口方法有哪些" 比 "结构是什么" 效果好得多。

👁️watch — 监听模式

监听项目文件变化，自动触发增量重建图谱，适合开发过程中持续保持图谱最新。

# 监听当前目录
graphify-rs watch

# 监听指定目录
graphify-rs watch --path ./crmeb-mer --output graphify-out

运行后会保持后台监听进程，每次检测到文件变动自动执行 build --update。

监听模式对大型目录可能会频繁触发构建，建议配合 --update 使用（默认行为）。

🖥️serve — MCP Server

以 MCP（Model Context Protocol）服务形式暴露图谱查询能力，供 AI 编辑器远程调用。

# 启动 MCP 服务
graphify-rs serve

# 指定图谱数据
graphify-rs serve --graph graphify-out/graph.json

启动后支持 SSE / stdio 传输协议，可在 Claude Code 的 MCP 配置中注册为远程工具。

⚙️配置系统

初始化配置

graphify-rs init

在项目根目录生成 graphify.toml 配置文件，可自定义：

include / exclude 规则 — 控制哪些文件/目录被扫描
LLM 提供商和模型 — 配置增强摘要使用的 AI 模型
输出格式默认值 — 设置 --format 的默认行为

示例配置

# graphify.toml
[build]
path = "."
output = "graphify-out"

[exclude]
paths = ["node_modules", "target", "dist", ".git"]

[llm]
enabled = true
model = "claude-sonnet-4-6"

有配置文件后，build 命令会自动读取，命令行参数会覆盖配置文件中的值。

📋输出格式速查

通过 --format 参数控制输出产物，默认 all 生成全部格式。

格式	说明	典型用途
`json`	结构化图谱数据 `graph.json`	查询、MCP 服务、二次开发
`html`	交互式可视化页面 `index.html`	浏览器中浏览代码关系
`report`	架构深度分析报告 `GRAPH_REPORT.md`	架构评审、文档沉淀
`wiki`	Wiki 格式文档 `wiki/index.md`	AI 编辑器导航
`obsidian`	Obsidian 双向链接笔记	个人知识管理
`graphml`	GraphML 格式图	导入 Gephi 等图分析工具
`cypher`	Neo4j Cypher 导入脚本	导入 Neo4j 图数据库
`svg`	静态 SVG 依赖图	文档嵌入、打印

🔄diff — 对比图谱差异

比较两次构建之间的图谱变化，查看新增/删除/修改的节点和关系。

graphify-rs diff old-graph.json new-graph.json
graphify-rs diff graphify-out/graph.json graphify-out-v2/graph.json --output json

参数	默认值	说明
`<OLD>`	必填	旧版 graph.json 路径
`<NEW>`	必填	新版 graph.json 路径
`--output`	`text`	输出格式：`text` 或 `json`

典型用法：重构前后对比架构变化，或者验证某个模块的依赖是否被正确删除。

📈stats — 统计信息

不重新构建，直接读取已有的 graph.json 并输出统计摘要。

graphify-rs stats
graphify-rs stats graphify-out/graph.json

输出内容包括：节点数、边数、文件数、语言分布、拓扑指标等。

🌐ingest — 导入外链内容

抓取指定 URL 的内容并纳入图谱分析范围，适合分析在线文档或远程代码。

graphify-rs ingest https://example.com/api-docs

内容会被保存到输出目录，后续 build 时一并分析。

🤖Claude Code 集成

安装技能

graphify-rs install --platform claude

自动将 graphify 技能注册到 Claude Code，注册后可在对话中使用 /graphify 命令。

卸载

graphify-rs claude uninstall

也可以在 CLAUDE.md 中手动配置图谱使用规则，例如：

# 回答架构问题前先读取图谱
- 先读取 graphify-out/GRAPH_REPORT.md 了解核心节点和社区结构
- 如果 graphify-out/wiki/index.md 存在，优先导航该索引

🪝Git Hook 集成

将图谱构建绑定到 Git 事件（如 commit 后自动构建），保持图谱始终与代码同步。

安装 Hook

graphify-rs hook install

查看状态

graphify-rs hook status

卸载 Hook

graphify-rs hook uninstall

默认在 post-commit 阶段触发增量构建，等价于每次提交后自动运行 build --update。

📌全局参数速查

以下参数对所有子命令生效：

参数	说明
`-q, --quiet`	静默模式，抑制非必要输出
`-v, --verbose`	调试模式，输出 debug 级日志
`-j, --jobs`	并行任务数，默认等于 CPU 核数
`-h, --help`	打印帮助信息
`-V, --version`	打印版本号

💡常见问题

构建太慢了怎么办？

首次构建对大型项目可能需要十几秒。优化方案：

使用 --update 增量构建（通常 2~5 秒）
使用 --no-llm 跳过 LLM 增强
在 graphify.toml 中排除不需要的目录（如 node_modules、vendor）

HTML 可视化页面卡顿？

节点过多会导致浏览器渲染性能下降。通过 --max-viz-nodes 1000 限制节点数量。

如何排除某些文件/目录？

在项目根目录创建 graphify.toml，在 [exclude] 中配置路径列表，或运行 graphify-rs init 生成模板后修改。

图谱数据在哪个目录？

默认输出到 graphify-out/，核心产物是 graph.json，所有查询、MCP 服务、diff 对比都基于此文件。

如何在团队中共享图谱？

将 graphify-out/ 提交到 Git，团队成员可直接查看报告
使用 graphify-rs serve 启动 MCP Server 共享查询能力
生成 GraphML 格式导入 Gephi 进行深度图分析

日常开发工作流建议

开发中: graphify-rs watch # 后台监听，自动更新提交前: graphify-rs stats # 快速检查图谱状态提交后: git hook 自动 build --update # 保持图谱同步需要分析: graphify-rs query "..." # 自然语言查询图谱归档: git commit graphify-out/ # 将图谱随代码一起版本管理