开源项目第162期：code-review-graph — 给 AI 代码审查建一张代码结构地图，减少 82 倍 Token 消耗

引言

"Stop burning tokens. Start reviewing smarter."

这是「每日一个开源项目」系列的第 162 篇 。今天的项目是 code-review-graph ------ 一个为 AI 代码审查工具构建持久化代码结构图谱的本地工具，通过 MCP 提供精准上下文，减少无效 token 消耗。

AI coding agent 在做代码审查时有一个隐藏的低效问题：它不知道「改这个函数会影响哪些地方」，所以只能读大量文件来建立上下文 ------ 或者靠 grep 碰运气。code-review-graph 的解法是：先把代码库解析成一张结构图（函数、类、调用关系、继承、测试覆盖），变更发生时直接查图，算出「爆炸半径」，只把真正相关的文件交给 AI 读。

基准测试数据：中位数 82 倍 token 减少，最好情况（fastapi 仓库）528 倍。

19,762 颗 Star，创建于 2026 年 2 月，支持 14 个 AI coding 平台。

你会学到什么

爆炸半径分析的工作原理：从变更文件追踪到调用者、依赖者、测试
Tree-sitter AST 解析 → SQLite 图谱 → MCP 工具链的完整架构
增量更新机制：为什么 2,900 个文件的仓库能在 2 秒内更新
三层边置信度评分（EXTRACTED/INFERRED/AMBIGUOUS）的意义
基准测试数字的诚实解读：528x 是最好情况，不是中位数

前提知识

使用过 Claude Code 或其他 AI coding 工具
了解 MCP（Model Context Protocol）的基本概念
基本了解静态分析和代码调用图

项目背景

概述

code-review-graph（简称 CRG）是一个本地优先的代码智能工具，核心功能：

用 Tree-sitter 解析代码库，构建函数/类/导入/调用关系的结构图
以 SQLite 文件存储在 .code-review-graph/ 目录，零网络依赖
通过 MCP 服务器对外暴露 30 个工具，AI assistant 可以查询「这次改动影响了哪些地方」
支持增量更新，变更时只重新解析变化的文件

项目信息

作者: tirth8205
主语言: Python 3.10+
许可证: MIT
版本: v2.3.6
官网: code-review-graph.com

项目数据

⭐ GitHub Stars: 19,762+
🍴 Forks: 2,107+
📄 许可证: MIT
📅 创建时间: 2026-02-26

功能特性

快速安装

bash 复制代码

pip install code-review-graph        # 或：pipx install code-review-graph
code-review-graph install            # 自动检测所有已安装的 AI 平台，写入 MCP 配置
code-review-graph build              # 解析代码库，构建图谱

三条命令完成设置。install 自动检测本机安装了哪些 AI 工具，为每个平台写入正确的 MCP 配置，注入 graph-aware 指令到平台规则文件，并安装对应的 hooks/skills。

重启编辑器后，向 AI 说：

text 复制代码

Build the code review graph for this project

支持的平台

一次安装，14 个平台同时生效：Codex、Claude Code、CodeBuddy Code、Cursor、Windsurf、Zed、Continue、OpenCode、Antigravity、Gemini CLI、Qwen、Qoder、Kiro、GitHub Copilot。

针对单个平台：

bash 复制代码

code-review-graph install --platform claude-code
code-review-graph install --platform cursor
code-review-graph install --platform codex

Token Savings 面板

text 复制代码

┌─────────────────────── Token Savings ────────────────────────┐
│ Full context would be:     12,921 tokens                     │
│ Graph context used:           762 tokens                     │
│ Saved:                     12,159 tokens (~94%)              │
│ Breakdown: Functions 244 · Tests 191 · Risk 244 · Other 83   │
└──────────────────────────────────────────────────────────────┘

通过 detect-changes --brief 或 update --brief 输出，加 --verify 可以和 OpenAI cl100k_base tokenizer 对比校验。

深度解析

核心架构

sql 复制代码

代码仓库
    │
    ▼ git ls-files（只索引 tracked 文件）
Tree-sitter 解析器
    │ 提取：函数/类/导入/调用/继承/测试
    ▼
SQLite 图数据库
（.code-review-graph/，git 默认 ignore）
    │
    ├── MCP 服务器（30 个工具）
    │       ↓ AI assistant 查询
    │   get_impact_radius_tool
    │   get_review_context_tool
    │   detect_changes_tool
    │   ...
    │
    └── CLI
        detect-changes --brief
        update --brief
        visualize
        ...

图中的节点：函数、类、文件、模块图中的边：调用关系、导入关系、继承关系、测试覆盖关系

爆炸半径分析

这是 CRG 的核心概念。当一个文件发生变更时：

scss 复制代码

变更文件（例如 auth/login.py 里的 login() 函数）
    ↓
查图：哪些函数直接调用了 login()？
    ↓
查图：哪些函数调用了那些函数？（可配置深度，默认 depth=2）
    ↓
查图：哪些测试文件覆盖了这些函数？
    ↓
输出：这次变更的「爆炸半径」= 这批函数/文件的最小集合

AI 只读这个最小集合，而不是扫描整个代码库。

准确性说明（README 里的诚实表述）：

当前 recall=1.0 是图导出的上界，不是真实 recall ------ ground truth 来自同一张图，存在循环性偏差
「co-change 模式」用 git 历史（实际上同次 commit 修改了哪些文件）作为独立 ground truth，更诚实，数字会更低
爆炸半径分析刻意保守：宁可多标几个文件，也不漏掉可能受影响的依赖

增量更新：< 2 秒

markdown 复制代码

文件保存（hooks 触发 / watch mode / crg-daemon）
    │
    ▼
SHA-256 哈希检查：哪些文件变了？
    │
    ▼
只对变更文件重新解析
    │
    ▼
找到这些文件的依赖者，标记需要更新的边
    │
    ▼
图更新完成

典型数据：2,900 个文件的仓库，< 2 秒完成增量更新
         10 秒完成 500 个文件的初始构建

三层边置信度

图里的边（调用关系等）有三种置信度：

置信度	含义
EXTRACTED	从 AST 直接解析出的明确调用，高置信度
INFERRED	通过类型推断或语义分析推断的关系，中置信度
AMBIGUOUS	动态调用、多态、难以静态分析的情况，低置信度

这个分层设计让 AI 在查询图时可以根据置信度过滤，避免低质量的边引起误判。

30 个 MCP 工具

AI assistant 建立图谱后自动获得 30 个工具，按用途分类：

上下文获取（代码审查核心）

get_minimal_context_tool --- 超压缩上下文，约 100 tokens，第一步调用
get_impact_radius_tool --- 变更文件的爆炸半径
get_review_context_tool --- 带结构摘要的 token 优化审查上下文
detect_changes_tool --- 风险评分变更影响分析

图查询

query_graph_tool --- 查调用者/被调用者/测试/导入/继承
traverse_graph_tool --- BFS/DFS 自由遍历，可配置深度和 token 预算
semantic_search_nodes_tool --- 按名称或语义搜索代码实体

架构分析

get_architecture_overview_tool --- 从社区结构生成架构概览
get_hub_nodes_tool --- 找最高连接度节点（架构热点）
get_bridge_nodes_tool --- 通过介数中心性找架构瓶颈
get_surprising_connections_tool --- 检测意外的跨社区耦合
get_knowledge_gaps_tool --- 识别孤立节点、未测试热点、结构弱点

其他

refactor_tool --- 重命名预览、死代码检测
generate_wiki_tool --- 从社区结构生成 Markdown wiki
cross_repo_search_tool --- 跨所有注册仓库搜索

工具过多时，可以用 CRG_TOOLS 环境变量或 --tools 参数只暴露部分工具：

bash 复制代码

code-review-graph serve --tools query_graph_tool,detect_changes_tool,get_review_context_tool

语言支持

40+ 种语言/格式，包括：Python、JavaScript/TypeScript/TSX、Go、Rust、Java、C/C++、C#、Ruby、Kotlin、Swift、PHP、Scala、Solidity、Dart、R、Elixir、Zig、Vue/Svelte、Jupyter/Databricks notebooks（.ipynb）等。

不支持的语言，可以通过 .code-review-graph/languages.toml 添加，无需 fork：

toml 复制代码

[languages.erlang]
extensions = [".erl"]
grammar = "erlang"
function_node_types = ["function_clause"]
class_node_types = ["record_decl"]
import_node_types = ["import_attribute"]
call_node_types = ["call"]

CI 集成：GitHub Action

yaml 复制代码

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

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

在 CI runner 本地构建和查询图谱，源代码不发送到任何外部服务 。每次 PR 生成一条带风险评分的置顶 comment，push 时原位更新。可选 fail-on-risk 输入作为合并门控。

多仓库 Daemon

bash 复制代码

crg-daemon add ~/project-a --alias proj-a
crg-daemon add ~/project-b
crg-daemon start

crg-daemon status
crg-daemon logs --repo proj-a -f
crg-daemon stop

适合不支持 hooks 的编辑器（Cursor、OpenCode 等）。后台监控多个仓库文件变更，每 30 秒健康检查，自动重启挂死的 watcher 进程。配置存储在 ~/.code-review-graph/watch.toml。

基准测试数据（诚实解读）

README 里对基准数字的解读很罕见地诚实，值得完整呈现：

仓库	代码库 token	图查询 token	减少倍数
fastapi	951,071	2,169	528x
code-review-graph	208,821	2,495	93x
gin	166,868	1,990	92x
flask	125,022	1,986	71x
express	135,955	3,465	41x
httpx	89,492	2,438	38x
中位数			~82x

528x 是最好情况（fastapi，最大的代码库），不是典型值。中位数是 82x。

整个代码库 token 是「没有工具的 agent 读所有源文件」的上界 ------ 实际上，一个合理的 agent 会 grep 关键词然后只读最匹配的文件。README 里专门设计了 agent_baseline 评测：用 pure-python grep 找 top-3 文件，对比图查询成本，这才是更诚实的基线。

小文件改动时，图查询可能比直接读文件更贵（结构元数据开销超过文件内容）------ express 仓库的数字就说明了这一点。

参考资源

官方链接

🌟 GitHub : tirth8205/code-review-graph
🌐 官网 : code-review-graph.com
📦 PyPI : code-review-graph
📄 基准测试复现 : docs/REPRODUCING.md
💬 Discord : discord.gg/3p58KXqGFN

总结

code-review-graph 解决的是一个在 AI coding 场景里会随代码库变大而持续恶化的问题：agent 不知道改了 A 会影响 B，所以要么读很多无关文件，要么靠 grep 碰运气。CRG 提前把「什么影响什么」建成图谱，让 agent 能直接查。

几个工程决策值得关注：

本地优先 + 零遥测：图谱存 SQLite，云端 embedding 是可选项（默认不开），CI runner 上也本地运行。代码不出机器。

诚实的基准测试：528x 标注为「最好情况」，中位数 82x 才是主打数字；recall=1.0 明确标注为「图导出的上界，存在循环性偏差」；小文件改动可能净负 ------ 这种程度的透明度在开发工具里罕见。

增量更新优先：初始构建是一次性成本，之后的更新才是日常路径。2 秒完成增量更新意味着 hooks + watch mode 可以真正做到「始终最新」，而不是「手动触发一次」。

对于中大型代码库（几百到几千文件）、频繁代码审查场景、或者经常遇到「改了这里会不会影响那里」问题的团队，CRG 的 MCP 集成路径是目前最直接的解法之一：pip install + install + build，三步接入，之后交给 agent 自动查询。

探索 PrimeSkills ------ 精选 AI agent 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。

访问我的个人主页，获取更多见解和有趣的产品。