code-review-graph

代码审查图谱 — 通过 MCP 获取高效的代码库上下文

为 AI 提供结构图，而不是让它读取所有内容，从而大幅减少大型代码库中的 AI 令牌用量。节省幅度随代码库规模增长——小型项目的收益有限，大型单体仓库的收益则很显著。

概述

code-review-graph 是一个 MCP 服务，使用 Tree-sitter 将代码库解析为 AST 图谱，并存储在 SQLite 中。当 AI 助手需要任务上下文时，会先查询图谱——仅获取更改的影响范围内的文件，而不是读取目录中的每个文件。

令牌影响（示例——因代码库而异）：

代码库类型	规律
大型单体仓库（10K+ 个文件）	节省最多——图谱只读取一小部分文件
中型应用（1-5K 个文件）	多文件更改时可显著减少用量
小型项目（<200 个文件）	收益有限——图谱开销可能超过节省的用量

质量方面： 将 AI 的范围限定在影响范围内可以减少干扰，通常有助于提高审查专注度。请在自己的仓库中进行测量，不要依赖固定倍数。

初始化协议（可选）

在中大型项目中通过 /plan 或常规用法调用时，在依赖图谱分析之前，先确认图谱分析是否可用：

1. 步骤 1： 检查是否已安装该工具：Get-Command code-review-graph（Windows）或 which code-review-graph（macOS/Linux）。
2. 步骤 2： 检查工作区中是否存在 .code-review-graph/ 目录。
3. 步骤 3： 如果已安装但索引不存在，运行 code-review-graph build 前先询问用户（该命令会扫描整个项目）。
4. 步骤 4： 如果尚未安装且项目规模较大，询问用户：“您愿意运行 pip install code-review-graph 并构建本地映射，以减少此项目的令牌用量吗？”未经确认，绝不安装或运行构建命令。

---

何时使用，何时跳过

✅ 适合安装的情况：

• 代码库有 500 个以上文件
• 你会进行多文件更改，且存在跨模块依赖
• 你每月在 AI 助手令牌上花费 20 美元以上
• 你使用单体仓库、微服务或跨包 TypeScript 项目
• 除了节省成本，还希望提高审查质量

❌ 适合跳过的情况：

• 代码库少于约 200 个文件，且更改仅涉及相互独立的单个文件
• 大量使用动态模式（反射、运行时代码生成、动态导入）
• 你希望无需维护——图谱需要保持同步
• 团队尚未统一使用 AI 编码工具

⚠️ 建议先评估的情况：

• 代码库有 200–500 个文件——在决定采用前进行基准测试
• 静态与动态模式混用——在有代表性的提交上进行测试

---

工作原理（4 个层次）

Layer 1: PARSE    → Tree-sitter builds ASTs from 19 languages
Layer 2: STORE    → Nodes + edges saved in SQLite graph
Layer 3: TRACE    → BFS computes blast radius of changes
Layer 4: SERVE    → MCP exposes graph to AI assistants

图谱包含的内容

• 节点： 文件、函数、方法、类、导入、测试
• 边：“A 调用 B”、“X 导入 Y”、“TestZ 覆盖 FunctionW”、“ClassA 扩展 ClassB”
• 元数据： 每个节点的名称、类型、文件路径、行范围
• 隐私： 仅包含结构元数据——图谱中不含源代码内容

支持的语言（19 种）

Python、TypeScript、JavaScript、Go、Rust、Java、C#、Ruby、Kotlin、Swift、PHP、C/C++、Vue SFC、Solidity、Dart、R、Perl、Lua、Jupyter/Databricks 笔记本。

---

安装

前置条件

• Python 3.9+（python3 --version）
• 已安装 pip 或 pipx
• 兼容 MCP 的 AI 客户端（AG Kit、Claude Code、Cursor、Windsurf、Zed）
• 使用 Git 跟踪的代码库（用于增量更新）

步骤 1：安装软件包

# Recommended: isolated environment
pipx install code-review-graph

# Alternative: fastest, no permanent install
uvx code-review-graph install

# Alternative: global pip
pip install code-review-graph

步骤 2：配置 MCP 客户端

# Auto-detect all supported tools
code-review-graph install

# Or target a specific platform
code-review-graph install --platform claude-code
code-review-graph install --platform cursor
code-review-graph install --platform windsurf

完成此步骤后，请重启编辑器。MCP 服务将在重启后激活。

步骤 3：构建初始图谱

cd /your/project
code-review-graph build

代码库规模	预期构建时间
500 个文件	10–30 秒
5,000 个文件	2–5 分钟
27,000 个文件	5–10 分钟

步骤 4：启用监视模式（推荐）

# Keep graph current as you work
code-review-graph watch

增量更新可在 2 秒内完成。如果你更喜欢手动更新：

code-review-graph update

步骤 5：验证集成

打开你的 AI 客户端并检查 MCP 连接。对于 Claude Code：运行 /mcp，确认 code-review-graph 已显示。

---

配置

忽略文件

在项目根目录创建 .code-review-graphignore（使用 .gitignore 语法）：

# Build artifacts
dist/**
.next/**
build/**

# Dependencies
node_modules/**
vendor/**

# Generated files
generated/**
*.generated.ts
*.min.js

# Test fixtures (if large)
__fixtures__/**

排除生成文件和构建产物至关重要——它们会让图中充斥无意义的节点。

多仓库设置

适用于微服务架构：

# Register additional repos
code-review-graph register /path/to/other/repo

# List all registered repos
code-review-graph repos

MCP 服务会为所有已注册的仓库提供上下文。

---

核心工作流

1. 影响范围分析（主要用途）

MCP 服务处于活动状态时，此过程会自动进行。你的 AI 助手会在读取文件前查询图，只获取受影响的文件，而不是所有文件。

Without graph:  Changed auth/middleware.py → AI reads 200+ files → 8,200 tokens
With graph:     Changed auth/middleware.py → Graph returns 12 impacted files → 1,000 tokens

2. 基于风险评分的变更分析

code-review-graph detect-changes

按风险级别对每项未提交的变更进行评分：

• 依赖项数量
• 测试覆盖率缺口
• 变更的函数是否处于关键路径上
• 在你要求审查之前标记高风险变更

3. 死代码检测

该图会查找没有入边的节点——没有调用者、没有导入者、没有测试覆盖：

# Surfaces functions/classes that are candidates for removal
# Useful on mature codebases to reduce cruft

4. 重构预览

code-review-graph rename preview --from OldClassName --to NewClassName

显示重命名所影响的每个文件，并标记边缘情况（静态分析无法捕获的动态字符串引用）。

5. 架构可视化

code-review-graph visualize

使用社区检测（Leiden 算法）生成交互式可视化，展示模块集群。适用于：

• 帮助新贡献者熟悉项目
• 识别架构偏移
• 发现耦合过度的模块

6. 生成 Wiki

code-review-graph wiki

生成代码库结构的 Markdown Wiki，涵盖每个模块、其公共 API、依赖项和测试覆盖率。

---

已知限制

限制	影响	缓解措施
动态导入（require(variable)、import(buildPath())）	解析器无法看到依赖项	在 .code-review-graphignore 中手动注明，或接受预测范围偏大的情况
基于反射的调用（Django 信号、getattr()、Java 反射）	图中会遗漏边	对于这类代码库，Serena（基于 LSP）效果更好
运行时生成的代码（eval、模板引擎）	无法在静态分析时解析	接受此限制，或将其排除在图之外
跨语言边界（Python 调用 TypeScript API）	不同语言运行时之间没有边	使用多仓库注册作为部分变通方案
图已过时（未启用监视模式）	Claude 查询到过时的关系	执行任务前始终运行 code-review-graph update，或使用监视模式
TypeScript 路径别名（@/components/...）	可能需要配置 tsconfig 解析器	检查 tsconfig_resolver.py 是否支持你的设置

---

替代方案比较

工具	方法	优点	缺点	最适合
code-review-graph	Tree-sitter + SQLite	快速、支持 19 种语言、本地运行、无依赖	仅限静态分析	通用场景、大型代码库
Claudette	Go 重写版	单一二进制文件、无需 Python	支持的语言较少、功能更简单	不愿使用 Python 的团队
Serena	基于 LSP	深度语义精度、类型解析	设置繁琐、速度较慢	多态性较复杂的代码库
code-graph-rag	RAG + 向量搜索	自然语言查询	设置复杂	代码库探索
原生 IDE 上下文	编辑器内置	无需设置	无显式影响范围分析	简单项目

---

与 AG Kit 集成

配套技能

AG Kit 技能	如何配合
context-compression	图谱减少输入上下文；压缩减少输出冗长程度
coordinator-mode	可将明确的文件列表分派给了解图谱的工作者
verify-changes	基于图谱完成审查后，通过执行来验证更改
batch-operations	图谱的影响范围可帮助确定哪些文件需要批量更新

推荐的会话架构

1. Start fresh session for each distinct task
2. Graph pre-filters context → AI reads only blast radius
3. Context compression summarizes completed phases
4. Memory system saves key decisions for next session
5. Result: minimum tokens, maximum quality

---

最佳实践

1. 开发时始终运行监视模式——过时的图谱会生成过时的上下文
2. 排除生成的文件——它们会让图谱充斥噪声
3. 先进行基准测试——先测量 1 周不使用时的 Token 用量，再测量 1 周使用时的用量
4. 结合输出约束——图谱减少输入，提示词工程减少输出
5. 对构建产物、node_modules、dist/ 使用 .code-review-graphignore
6. 保持会话简短——新会话加图谱可实现最佳 Token 效率
7. 对微服务架构使用多仓库注册