code-review-graph 代码图谱实战指南

code-review-graph 的价值在于先为本地仓库建立可持久化的代码关系图谱，再通过 MCP 向 Claude Code、Cursor 等工具提供最小必要上下文。对于 Monorepo、跨模块修改和 PR 评审，它能明显减少重复扫描与 Token 消耗；但在单文件项目、动态调用密集的代码库中，收益有限，仍需人工复核。

01 AI 编码为何会浪费 Token

使用 Claude Code、Cursor 等工具处理大型项目时，常见问题包括：

• 修改底层工具函数时，AI 可能扫描大量无关配置、脚手架和静态文件；
• 询问接口变更影响范围时，单纯依靠 grep 难以完整还原调用链；
• 新建会话或重启编辑器后，需要重新理解项目结构；
• Monorepo 评审容易加载数万行无关代码，导致有效上下文被噪声稀释。

根本原因是多数原生 AI 编码工具缺少可跨会话复用的结构化代码记忆。code-review-graph 通过 Tree-sitter 解析代码，在本地生成知识图谱，并以 MCP 工具形式提供精准上下文。

项目公布的基准结果显示，代码评审平均可减少约 8.2 倍 Token；在部分大型仓库中，削减倍数可达到 49 倍，个别测试场景最高达到 82 倍。评审质量评分则由 7.2 提升至 8.8。实际效果会受到仓库规模、语言和变更范围影响。

02 核心原理

2.1 整体工作链路

其处理流程可以概括为：

本地代码仓库
  → Tree-sitter 解析并生成 AST
  → 提取节点与关系
  → 写入本地 SQLite 图谱
  → MCP Server 提供查询工具
  → AI 计算影响范围并读取最小相关文件集

2.2 用节点和边构建代码地图

节点代表代码实体：

• 函数与方法；
• 类与组件；
• 导入语句；
• 测试函数；
• Jupyter Notebook 单元格等。

边代表实体之间的关系：

• 函数调用；
• 类继承；
• 模块导入；
• 测试覆盖；
• 跨文件耦合；
• 执行流依赖。

图谱默认保存在项目目录下：

.code-review-graph/graph.db

该文件使用 SQLite 存储，代码解析和图谱查询均可在本地完成，不必依赖云端服务，适合私有仓库和敏感业务代码。

2.3 Blast Radius 影响分析

Blast Radius 用于计算一次修改可能影响的范围，主要执行以下步骤：

1. 定位本次变更涉及的函数和文件节点；
2. 逆向查找调用这些节点的上层业务代码；
3. 正向分析其依赖的底层工具与公共模块；
4. 匹配覆盖相关逻辑的测试用例；
5. 过滤无关文件，生成最小评审文件集合。

项目给出的 Next.js Monorepo 测试包含 27732 个文件。传统方式需要读取超过 73 万 Token，而图谱筛选后只需读取 15 个相关文件，对应约 49 倍的 Token 压缩。

2.4 增量更新

code-review-graph 使用 SHA-256 文件哈希识别差异，不必在每次修改后重建整个仓库：

• 文件保存或 Git 提交可触发更新；
• 仅比较发生变化的文件；
• 重新解析变更文件及相关节点；
• 未变化的文件直接跳过；
• 可通过 watch 模式持续维护图谱。

项目公布的数据中，一个包含约 2900 个文件的仓库，增量更新耗时低于 2 秒。

03 主要特性

3.1 支持 30 多种语言和 Notebook

覆盖的常见语言与文件类型包括：

• **前后端语言：**Python、TypeScript、JavaScript、Go、Rust、Java、C、C++、C#、Vue、Svelte、Astro；
• **脚本与静态语言：**Scala、Kotlin、Swift、PHP、Solidity、Dart、Shell、Zig、PowerShell、Julia、SQL；
• **其他类型：**Ruby、Perl、Lua、Objective-C、Elixir、Verilog、Jupyter Notebook、Perl XS。

3.2 兼容主流 AI 编码平台

工具可为以下平台配置 MCP：

• Claude Code；
• Cursor；
• Codex；
• Gemini CLI；
• GitHub Copilot；
• Windsurf；
• Zed；
• Continue；
• OpenCode；
• Kiro；
• Antigravity。

安装命令支持自动检测，也能只配置指定平台，无需手动编写完整的 MCP 配置。

3.3 MCP 查询工具

高频工具包括：

• getimpactradius_tool：分析变更爆炸半径；
• getreviewcontext_tool：生成经过 Token 优化的评审上下文；
• querygraphtool：查询调用、继承、导入和测试关系；
• semanticsearchnodes_tool：对代码实体进行语义搜索；
• detectchangestool：评估变更风险并检查测试缺口。

进阶能力还包括社区聚类、架构概览、热点节点、架构桥接点、知识缺口检测、跨仓库检索、重构预览和项目 Wiki 生成。工具内置代码评审、架构梳理、问题调试、新人上手和合并前预检等提示模板。

3.4 附加能力

• 使用 D3.js 展示交互式图谱；
• 导出 SVG、GraphML、Cypher 或 Obsidian 知识库；
• 接入本地 sentence-transformers、Gemini 或 OpenAI 兼容向量接口；
• 使用 crg-daemon 管理多个仓库；
• 通过 .code-review-graphignore 排除生成文件和第三方依赖；
• 使用 Leiden 算法识别业务模块与异常耦合；
• 通过 eval 命令生成 Token 消耗对比报告。

04 安装与使用教程

4.1 前置依赖

需要 Python 3.10 或更高版本，建议使用 pipx 或 uv 隔离环境。

python --version

4.2 安装 code-review-graph

# 方式一：使用 pip
pip install code-review-graph

# 方式二：使用 pipx 隔离安装，推荐
pipx install code-review-graph

# 方式三：使用 uv
uv pip install code-review-graph

按需安装扩展功能：

# 向量语义搜索
pip install 'code-review-graph[embeddings]'

# 社区聚类分析
pip install 'code-review-graph[communities]'

# 安装全部扩展
pip install 'code-review-graph[all]'

4.3 自动配置 MCP

# 自动检测并配置本机支持的平台
code-review-graph install

# 仅配置 Claude Code
code-review-graph install --platform claude-code

# 仅配置 Cursor
code-review-graph install --platform cursor

执行后需要重启编辑器或 Claude Code 客户端。相关配置通常位于：

~/.claude.json

或项目目录中的：

.claude/settings.json

4.4 构建项目图谱

进入项目根目录后执行：

code-review-graph build

参考数据中，约 500 个文件的小型项目首次构建需要约 10 秒；约 2900 个文件的项目完成增量更新可低于 2 秒。

4.5 常用 CLI 命令

# 手动增量更新
code-review-graph update

# 监听文件改动并持续更新
code-review-graph watch

# 查看节点、边和图谱健康状态
code-review-graph status

# 打开交互式图谱页面
code-review-graph visualize

# 执行变更风险分析
code-review-graph detect-changes

# 手动启动 MCP 服务，用于排障
code-review-graph serve

# 生成 Markdown 项目文档
code-review-graph wiki

4.6 Claude Code 斜杠命令

接入后可以直接使用：

• /code-review-graph:build-graph：重建图谱；
• /code-review-graph:review-delta：评审当前未提交的本地变更；
• /code-review-graph:review-pr：评审完整 PR，并计算影响范围。

4.7 配置忽略规则

在项目根目录创建 .code-review-graphignore：

generated/**
*.generated.ts
vendor/**
node_modules/**
dist/**
build/**

Git 仓库中，.gitignore 已排除的文件通常会自动跳过。.code-review-graphignore 更适合过滤仍被 Git 跟踪、但无需纳入图谱的内容。

4.8 Windows 常见错误排查

如果出现以下错误：

Invalid JSON: EOF while parsing
MCP error -32000: Connection closed

可依次检查：

1. 将 fastmcp 升级至 3.2.4 或更高版本；
2. MCP 配置不要使用 cmd /c 包装，直接调用可执行文件；
3. 设置 PYTHONUTF8=1，避免中文编码导致进程中断；
4. 先在终端执行 code-review-graph serve，确认服务能够独立启动。

Claude Code MCP 配置示例：

{
  "mcpServers": {
    "code-review-graph": {
      "command": "C:\\path\\to\\venv\\Scripts\\code-review-graph.exe",
      "args": ["serve"],
      "env": {
        "PYTHONUTF8": "1"
      }
    }
  }
}

05 与原生检索方式对比

对比维度	Claude/Cursor 原生方式	code-review-graph
检索逻辑	grep 或文本匹配，可能扫描整个目录	AST 图谱遍历，按依赖关系查询
上下文成本	新会话可能重复读取大量文件	图谱一次构建，可跨会话复用
影响分析	依赖模型自行推理	内置 Blast Radius 分析
跨模块理解	受单次上下文和文件读取量限制	可跨文件追踪调用链
持久记忆	通常仅在当前会话有效	SQLite 图谱可长期保存
适用场景	单文件、小项目和临时脚本	Monorepo、PR 评审和架构分析

5.1 六个开源仓库的基准数据

仓库	原生 Token	图谱优化后 Token	削减倍数
fastapi	4944	614	8.1x
flask	44751	4252	9.1x
gin	21972	1153	16.4x
httpx	12044	1728	6.9x
nextjs	9882	1249	8.0x
express	693	983	0.7x

express 的测试结果表明，小型或单文件项目可能因为额外的图谱元数据而增加 Token。该工具的主要收益集中在多文件、跨模块变更场景。

基准中的影响分析平均召回率为 100%，平均精确率为 0.38。这意味着测试中没有漏掉受影响文件，但保守策略会纳入部分无关文件。该数据不应理解为所有项目都能保证同样结果。

06 适用场景与局限

6.1 推荐使用的场景

• 数千文件以上的 Monorepo；
• 高频 PR 代码评审和合并前预检；
• 修改底层公共工具、中间件或通用校验函数；
• 新成员快速理解项目架构；
• 大规模重构、重命名和死代码清理；
• 对 AI Token 成本敏感的团队。

6.2 收益较低的场景

• 只有几十行代码的独立脚本；
• 一次性 Demo 或调用链简单的小工具；
• 仅修改文档、静态资源和配置文件；
• 单文件、微小范围的代码变更。

6.3 已知局限

1. 动态调用难以静态捕获。 Python 和 JavaScript 中的反射、装饰器、元类、eval、getattr 等运行时行为，可能不在静态图谱中。Go、Rust、Java 等静态语言通常更容易完整解析。
2. 语义搜索精度有限。 已公布的语义检索 MRR 为 0.35，更适合作为辅助筛选，不能替代人工核验。
3. 复杂执行流覆盖不足。 执行流检测召回率为 33%，动态框架中的隐式依赖仍可能遗漏。
4. 引入额外维护环节。 SQLite 图谱、watch 进程和 MCP 配置都会增加故障点。
5. 小项目可能得不偿失。 图谱元数据本身也会占用上下文，极小变更甚至可能增加 Token。

07 选型与落地建议

7.1 个人开发者

• 项目少于 500 个文件且结构简单：通常无需安装；
• 项目超过 1000 个文件、模块较多并频繁评审 PR：值得接入；
• 长期维护多个仓库：可使用 crg-daemon 统一管理。

7.2 团队使用

• 私有代码可优先采用本地 SQLite 存储方案；
• 在 CI/CD 中运行 code-review-graph detect-changes，辅助 PR 风险预检；
• 动态语言项目必须保留人工复核环节；
• 团队可统一使用 pipx 隔离安装，减少 Python 环境冲突。

7.3 总结

code-review-graph 不是通用的“零成本增强器”，而是一套面向中大型代码库的本地代码关系索引。它适合通过结构化依赖查询减少无关上下文，改善跨模块评审效率；对于小型项目或高度动态的代码，原生工具配合人工检查通常更直接。