tirth8205/code-review-graph · 上手攻略
- 仓库：tirth8205/code-review-graph
- 链接：https://github.com/tirth8205/code-review-graph
- 分类：开发者工具 · AI 辅助编程 · 代码分析
- 作者：Tom
- 更新：2026-07-21
它是什么
code-review-graph（简称 CRG）是一个本地优先的代码智能图谱工具，为 MCP（Model Context Protocol）兼容的 AI 编程助手和 CLI 环境设计。它的核心思路是：先把你的代码库解析成一张结构化的知识图谱（节点 = 函数/类/导入，边 = 调用/继承/测试覆盖），然后在 AI 做代码审查时只喂给它真正相关的文件，而不是把整个代码库都塞进去。
官方标称数据：在 6 个真实开源仓库上，Token 消耗削减 38 倍到 528 倍；一个 2,900 文件的项目增量重索引只需不到 2 秒。最新版本为 v2.3.4，支持 MCP 1.0。
解决什么问题
AI 编程助手做代码审查时，通常需要读取大量代码上下文才能给出有意义的建议。对于小型项目这不是问题，但到了大型 monorepo（数千个文件）就会变成噩梦：
- Token 浪费：AI 反复读取大量无关代码，每次 API 调用都在烧钱
- 响应变慢：上下文太长，模型处理时间显著增加
- 质量下降：上下文噪音过多，AI 容易给出泛泛而论的评审意见
code-review-graph 解决这个问题的思路是：在 AI 读代码之前，先用 Tree-sitter 把代码结构解析成图谱，然后根据变更内容计算"影响半径"（blast radius）——只让 AI 读它真正需要看的文件。
快速安装
环境要求
- Python 3.10+
- 推荐安装 uv（可加速包管理，且 MCP 配置会自动使用
uvx）
安装命令
pip install code-review-graph
# 或
pipx install code-review-graph
初始化配置（一键自动检测）
code-review-graph install
这条命令会自动： 1. 检测你安装了哪些 AI 编程工具（Codex、Cursor、Claude Code、Copilot 等） 2. 为每个工具写入对应的 MCP 配置文件 3. 安装平台原生 Hook/Skill（若支持） 4. 将图谱感知指令注入平台规则
安装后重启编辑器或工具使配置生效。
指定平台安装
code-review-graph install --platform codex # 仅配置 Codex
code-review-graph install --platform cursor # 仅配置 Cursor
code-review-graph install --platform claude-code # 仅配置 Claude Code
code-review-graph install --platform copilot # 仅配置 GitHub Copilot (VS Code)
code-review-graph install --platform gemini-cli # 仅配置 Gemini CLI
code-review-graph install --platform kiro # 仅配置 Kiro
构建图谱
code-review-graph build # 解析整个代码库，构建本地图谱
500 个文件的项目首次构建约需 10 秒。
核心用法
基本工作流
1. 安装完成后，在项目目录执行：
code-review-graph build
2. 向 AI 助手发送指令：
"Build the code review graph for this project"
3. 之后每次代码变更，CRG 自动追踪影响范围，
AI 只需读取最小相关文件集
影响半径分析（Blast Radius）
当某个文件发生变更时，图谱会追踪所有可能受影响的调用方、依赖方和测试——这就是变更的"影响半径"。
code-review-graph detect-changes # 检出变更并分析影响范围
AI 读取的将从整个代码库缩减为：变更文件本身 + 直接影响文件 + 间接受影响文件 + 相关测试。
增量更新
启用 Hook 或 Watch 模式后，文件保存和 Git 提交会自动触发增量更新：
# 监听模式（工作目录有变更时自动更新图谱）
code-review-graph watch
# git commit 触发自动更新（需配合平台 hook）
# 一个 2,900 文件项目增量重索引 < 2 秒
卸载
code-review-graph uninstall --dry-run # 预览所有操作，不写入
code-review-graph uninstall # 预览后确认，再执行
code-review-graph uninstall --yes # 无需确认，直接执行
code-review-graph uninstall --all-repos # 同时清理所有已注册仓库
code-review-graph uninstall --keep-data # 保留图谱数据库，只移除集成
MCP 斜杠命令
| 命令 | 说明 |
|---|---|
/code-review-graph:build-graph |
构建或重建代码图谱 |
/code-review-graph:review-delta |
审查自上次提交以来的变更 |
/code-review-graph:review-pr |
完整 PR 审查，含影响半径分析 |
典型适用场景
场景一：大型 Monorepo 的 AI Code Review
27,700+ 文件的巨型仓库，AI 原本需要读取大量无关代码。使用 CRG 后，实际读取约 15 个文件，Token 消耗削减可达 528 倍（官方基准数据）。每个 PR 的 AI 审查成本大幅下降。
场景二：多语言混合项目的增量维护
项目包含 Python + TypeScript + Go + Rust 等多语言，AI 很难理解跨语言依赖关系。CRG 的 Tree-sitter 解析器支持 40+ 编程语言，可以构建跨语言的调用图谱，帮助 AI 理解不同语言模块之间的实际依赖。
场景三：AI 结对编程的上下文优化
在使用 Claude Code、Cursor 等 AI 编程工具时，工具容易"迷失"在庞大的代码库里。CRG 作为 MCP 服务器挂在工具上，每次对话只给 AI 提供与当前任务最相关的上下文，让 AI 真正变成"懂代码结构"的助手。
场景四：代码库结构探索与知识沉淀
CRG 不只是给 AI 用——它的图谱也可以被人用来理解陌生代码库的结构。提供架构概览、社区检测、知识缺口分析、可视化力导向图（基于 D3.js）等功能，帮助人类开发者快速把握代码全貌。
核心功能一览
| 功能 | 说明 |
|---|---|
| 增量更新 | 仅重解析变更文件，2,900 文件项目 < 2 秒 |
| 多语言覆盖 | Python, JS/TS, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua, Objective-C, Shell, Elixir, Zig, PowerShell, Julia, ReScript, GDScript, Nix, Verilog, SQL, Vue/Svelte SFC, Astro, Jupyter Notebook 等 |
| 影响半径分析 | 追踪变更的所有下游影响 |
| 自动更新钩子 | 文件编辑和 git 提交自动触发图谱更新 |
| 语义搜索 | 支持 sentence-transformers / Gemini / MiniMax / OpenAI 兼容端点 |
| 交互式可视化 | D3.js 力导向图，可搜索、按社区图例切换 |
| Hub 与 Bridge 检测 | 介数中心性发现架构瓶颈 |
| 异常评分 | 检测跨社区、跨语言、外围到核心的异常耦合 |
| 导出格式 | GraphML（Gephi/yEd）、Neo4j Cypher、Obsidian wikilinks、SVG |
| 图差异 | 比较不同时间点的图快照变化 |
| 记忆循环 | 将问答结果持久化为 Markdown 供后续摄入学习 |
| 全文搜索 | FTS5 混合搜索（关键词 + 向量相似度） |
| 本地存储 | SQLite，无需外部数据库或云服务 |
坑与注意
⚠️ Python 3.10+ 硬性要求
CRG 不支持 Python 3.9 及以下版本。如果你的系统默认 Python 版本过低，请使用 uv 或 pipx 安装特定版本，或使用虚拟环境指定 Python 版本：
python3.10 -m venv crg-env
source crg-env/bin/activate
pip install code-review-graph
⚠️ uv 安装时 MCP 配置差异
如果通过 uvx code-review-graph 运行，MCP 配置文件会使用 uvx 作为命令前缀；如果通过 pip install 安装，则直接使用 code-review-graph 命令。install 子命令会自动检测并生成正确格式的配置，但如果你手动配置 MCP，注意这个差异。
⚠️ 大型仓库首次构建耗时
虽然官方说 500 文件约 10 秒，但超大型 monorepo（5,000+ 文件）首次构建可能需要更长时间。建议在 CI/CD 环境中使用 code-review-graph build 时设置合理的超时。
⚠️ 不支持通用 YAML 解析
CRG 的解析器将 YAML 当作配置文件而非源代码，不做语义解析。如果你的项目中有自定义 YAML 领域语言（DSL），CRG 无法构建其内部结构。
⚠️ MCP 服务器兼容性
CRG 作为 MCP 服务器工作，需要你的 AI 编程工具支持 MCP 协议。确认你的工具（Claude Code、Cursor 等）在使用的版本支持 MCP 接入。部分较老版本的工具可能不支持。
⚠️ 增量更新依赖 Git/SVN
增量更新功能依赖 Git 或 SVN 的变更追踪。如果你的项目不使用版本控制系统，增量更新功能将不可用，每次都需要全量重建。
与同类对比
| 工具 | 核心思路 | Token 优化 | MCP 支持 | 本地存储 | 多语言 |
|---|---|---|---|---|---|
| code-review-graph | 代码结构图谱 + 影响半径 | 38x-528x 削减 | ✅ 原生 MCP 1.0 | ✅ SQLite | 40+ 语言 |
| GitHub Copilot | 统计语言模型补全 | ❌ 无针对性优化 | ❌ | ❌ | 数十种 |
| BBOT（OSINT 工具） | 多步骤安全扫描 | ❌ | ❌ | ❌ | 有限 |
| Dagger（CI/CD） | 可编程 CI 管道 | ❌ | ❌ | ❌ | 通用 |
CRG 的差异化优势在于专为 AI 代码审查场景设计的图谱结构和对 MCP 协议的深度整合。它不是通用的代码分析工具，而是专门解决"AI 编程助手的上下文膨胀"问题的基础设施。
一句话推荐结论
如果你在大型代码库中使用 Claude Code、Cursor、Codex 等 AI 编程工具做 Code Review，code-review-graph 是目前最成熟的本地图谱方案——一次建图、永久增量、Token 消耗可降一到两个数量级，隐私数据全留本地。
本攻略基于仓库 README（v2.3.4）、官方文档及 code-review-graph.com 公开信息撰写。基准测试数据来自 6 个真实开源仓库的自动化评估。各平台 MCP 集成细节请参考官方 USAGE 和 COMMANDS 文档。