code-review-graph:让 AI 代码审查只读它该读的——19万星的开源项目深度解析

作者：艾瑞Eric

前言

当你用 AI 工具做代码审查时，有没有遇到过这种尴尬——

AI 翻了半天整个代码库，最后给出一堆无关的废话？

问题不在 AI 不够聪明，而在于它被迫读了太多不该读的东西。一个 10 万行代码的仓库，AI 做一次 PR review，要读取多少 token？答案是：非常多，多到浪费。

今天介绍的这个项目，就是来解决这个问题的。

code-review-graph，GitHub Star 数 19,095（还在快速增长），Python 语言，MIT 协议，专注于一件事——让 AI 编码工具只读它该读的内容。

一、项目概览

1.1 基本信息

1.2 核心定位

一句话描述： Local-first 的代码智能图谱，专为 MCP 和 CLI 设计，构建代码库的持久化结构地图，让 AI 编码工具只读真正重要的内容。

核心数字：

• • 支持 13+ 种主流 AI 编码平台
• • 支持 30+ 种编程语言
• • 中位 Token 节省：~82 倍（最高 528 倍）
• • 增量更新：2,900 文件项目，索引时间 < 2 秒

二、设计哲学：代码即图谱

2.1 核心问题

当前 AI 编码工具的最大痛点，不是"AI 不够聪明"，而是上下文窗口被大量无意义的内容填满。

当你让 AI 做代码审查时，它面临的选择是：

• • 方案 A：读取整个代码库（浪费大量 Token）
• • 方案 B：用模糊的关键词搜索（容易遗漏重要上下文）

code-review-graph 提出了第三种方案：

让 AI 知道代码的结构——哪些文件调用了哪些函数，哪些模块依赖哪些模块，哪些测试覆盖哪些功能——然后只读真正相关的部分。

2.2 核心理念：Code is a Graph

code-review-graph 的设计哲学基于一个洞察：代码从来不是文件的集合，而是一张图（Graph）。

函数调用函数，类继承类，模块导入模块，测试覆盖功能。这张图天然存在，只是以前没有被结构化地提取出来。

当这张图构建完成后，"变更的影响半径"就可以精确计算——

如果我改了 login() 函数，会影响哪些文件？哪些测试需要重新跑？哪些模块可能需要同步更新？

答案是：图知道。

2.3 Local-First 的安全边界

很多 AI 代码分析工具需要把代码上传到云端处理，这带来了数据安全问题。

code-review-graph 的设计哲学强调：数据不出本地。

• • 图谱存储在本地 SQLite 数据库（.code-review-graph/ 目录）
• • 语义搜索可选用本地 sentence-transformers 模型
• • GitHub Action 也是本地执行，不上传任何代码

三、核心技术架构

3.1 整体工作流程

代码库 → Tree-sitter 解析 → AST → 节点/边 → SQLite 图 → MCP/CLI → AI 工具

四个步骤：

1. 1. 解析（Parse）：用 Tree-sitter 将代码解析为 AST
2. 2. 建图（Graph）：将 AST 转化为节点（函数、类、导入）和边（调用、继承、测试覆盖）
3. 3. 查询（Query）：审查时，通过图计算最小需要读取的文件集
4. 4. 输出（Output）：通过 MCP 协议把精准的上下文传给 AI 工具

3.2 节点与边的定义

节点类型：

• • 文件（File）
• • 类（Class）
• • 函数/方法（Function/Method）
• • 类型（Type）
• • 测试（Test）

边类型：

• • CALLS — 调用关系
• • IMPORTS_FROM — 导入关系
• • INHERITS — 继承关系
• • IMPLEMENTS — 实现关系
• • CONTAINS — 包含关系
• • TESTED_BY — 测试覆盖关系
• • DEPENDS_ON — 依赖关系

3.3 Blast Radius（影响半径）分析

当一个文件发生变化，影响半径分析会追踪：

1. 1. 直接调用者：哪些文件/函数调用了被修改的函数
2. 2. 间接依赖：调用者的调用者（两跳以内的传递依赖）
3. 3. 测试覆盖：哪些测试覆盖了这个功能

最终，AI 只需要读取这个"影响半径"内的文件，而不是整个代码库。

3.4 增量更新机制

这是工程实现中最见功力的部分。

当文件发生变化时，code-review-graph 的处理流程：

1. 1. Diff 检测：通过 git diff 找出变更文件
2. 2. 哈希校验：对未变更文件做 SHA-256 校验，快速确认无变化
3. 3. 选择性重解析：仅对变更文件重新解析 AST
4. 4. 图更新：增量更新节点和边

一个 2,900 文件的项目，增量更新只需要 < 2 秒。

3.5 存储架构

核心数据存储在本地 SQLite 文件中：

.code-review-graph/
├── graph.db              # 主图数据库
├── graph.html            # D3.js 可视化（可选）
└── cache/               # 向量嵌入缓存

不需要任何外部数据库或云服务。

四、功能全景

4.1 影响分析系列

4.2 搜索与分析系列

4.3 导出与可视化

4.4 特殊功能

五、支持的平台与语言

5.1 AI 编码平台（13+ 个）

5.2 编程语言（30+ 种）

Web 类：JavaScript、TypeScript/TSX、Vue SFC、Svelte SFC、Astro

后端类：Python、Go、Rust、Java、C/C++、C#、Ruby、Kotlin、PHP、Scala、Elixir

移动端：Swift、Dart、Kotlin

系统类：Zig、PowerShell、Verilog/SystemVerilog

脚本类：Shell、R、Perl、Lua/Luau、Objective-C

其他：Solidity、Julia、ReScript、GDScript、Nix、SQL

特殊格式：Jupyter Notebook（.ipynb）、Databricks Notebook、Perl XS（.xs）

六、详细安装教程

6.1 环境要求

• • Python 3.10+
• • Git（用于增量更新的差异检测）
• • 可选：uv（用于更优的 Python 环境管理）

6.2 安装步骤

第一步：安装 code-review-graph

pip install code-review-graph
# 或
pipx install code-review-graph

第二步：自动配置所有支持的平台

code-review-graph install

这会自动检测你安装了哪些 AI 编码工具，并生成对应的 MCP 配置文件。

第三步：构建代码图谱

code-review-graph build

首次构建约需 10 秒（500 文件项目）。

第四步：重启编辑器/工具

安装后需要重启 AI 编码工具才能加载新的 MCP 配置。

6.3 指定平台安装

如果只想配置特定平台：

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

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

# 仅配置 GitHub Copilot
code-review-graph install --platform copilot

# 仅配置 Gemini CLI
code-review-graph install --platform gemini-cli

6.4 启用 Watch 模式（可选）

让图谱在文件变更时自动更新：

code-review-graph watch

6.5 可视化查看

生成交互式 D3.js 图谱：

code-review-graph visualize
open .code-review-graph/graph.html

七、GitHub Action 部署教程

这是我认为最有价值的功能之一：把 AI 代码审查集成到 CI 流程中。

7.1 工作原理

1. 1. CI runner 安装 code-review-graph（从 PyPI）
2. 2. 恢复缓存的 SQLite 图（或从零构建）
3. 3. 对 PR 变更文件做增量重解析
4. 4. 生成风险评分报告
5. 5. 在 PR 上发布/更新一条"粘性"评论（sticky comment）

关键点：所有分析都在 runner 本地执行，代码不会上传到任何外部服务。

7.2 快速部署

在仓库中创建 .github/workflows/code-review-graph.yml：

name: code-review-graph

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: tirth8205/code-review-graph@v2.3.6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

7.3 开启风险门控（merge gate）

设置当风险评分达到一定程度时，阻止合并：

- uses: tirth8205/code-review-graph@v2.3.6
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    fail-on-risk: high  # risk ≥ 0.70 时失败

风险等级定义：

7.4 PR 评论内容

这条"粘性"评论包含：

• • 整体风险评分 — 变更函数数、影响执行流数、测试缺口数
• • 风险排序的变更 — 按风险排序的变更函数表，含文件/行号和测试覆盖状态
• • 受影响的执行流 — 按关键度排序的入口点执行流
• • 测试缺口 — 无直接测试覆盖的变更函数
• • Token 节省 — 图谱审查比全文读取节省的 token 数

八、基准测试数据

8.1 Token 效率

中位节省倍数：~82 倍

8.2 影响分析准确率

平均 F1：0.714

8.3 构建性能

九、观点与总结

9.1 核心创新

1. 图谱先于搜索

大多数 AI 代码工具依赖关键词搜索或 RAG。code-review-graph 的思路是：先把代码结构提取成图谱，查询时从图谱出发找到最小上下文。这是从"搜什么"到"理解结构"的方法论升级。

2. 增量优先

对于大仓库，全量重解析成本极高。code-review-graph 通过 SHA-256 哈希校验和差异分析，实现了< 2 秒的增量更新，这意味着它可以在实际工作流中持续运行，而不是一次性工具。

3. MCP 协议原生集成

Model Context Protocol 是 AI 编码工具的标准接口。code-review-graph 的 MCP 工具（30+ 个）覆盖了从图构建到审查、到架构分析的全流程，让 AI 工具天然能"理解"代码结构。

9.2 适用场景

强烈推荐：

• • 大型代码仓库（1,000+ 文件）的 AI 代码审查
• • Monorepo 环境（多语言、多包、多服务）
• • 有 CI/CD 集成需求的团队（GitHub Action）
• • 需要控制 AI Token 消耗的个人开发者或团队
• • 对代码安全有要求的项目（数据不出本地）

不太适合：

• • 小型单文件项目（overkill）
• • 非结构化代码（如大量动态生成代码）
• • 对解析准确性要求极高的场景（Tree-sitter 的解析覆盖率不是 100%）

9.3 与类似项目对比

9.4 未来展望

根据 Roadmap，项目规划的方向包括：

• • GitHub App 模式：组织级别的安装，不只是仓库级别
• • 团队同步：通过 git 跟踪图数据库的团队共享
• • 超大型 Monorepo 优化：50k+ 文件的性能优化

十、关键命令速查

结语

code-review-graph 解决了一个非常具体但极其普遍的问题：AI 编码工具在代码审查时浪费了大量 Token 在读无关代码上。

它的解法优雅而有效：先把代码解析成结构化的图谱，再通过图的遍历找到最小影响集，让 AI 只读它真正需要的内容。

对于大型仓库和 Monorepo 项目，这个方案的价值尤为明显——当一个变更可能影响几十个文件时，精确知道"哪些文件需要关注"，不仅节省 Token，更能提升审查质量。

GitHub：https://github.com/tirth8205/code-review-graph

官网：https://code-review-graph.com

官网文档：https://code-review-graph.com/docs

本文由 AI 辅助生成，参考来源：code-review-graph 官方 GitHub 仓库及文档。首发于微信公众号「艾瑞Eric」。