## 📊项目概述

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/ # 将图谱随代码一起版本管理