开源项目第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）是一个本地优先的代码智能工具，核心功能：

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

项目信息

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

项目数据

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

---

功能特性

快速安装

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

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

重启编辑器后，向 AI 说：

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。

针对单个平台：

code-review-graphinstall--platformclaude-code code-review-graphinstall--platformcursor code-review-graphinstall--platformcodex

Token Savings 面板

┌─────────────────────── 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可以和 OpenAIcl100k_basetokenizer 对比校验。

---

深度解析

核心架构

代码仓库 │ ▼ 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 的核心概念。当一个文件发生变更时：

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

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

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

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

增量更新：< 2 秒

文件保存（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参数只暴露部分工具：

code-review-graph serve--toolsquery_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：

[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

on:pull_request:permissions:contents:readpull-requests:writejobs:review:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v7-uses:tirth8205/code-review-graph@v2.3.6with:github-token:${{secrets.GITHUB_TOKEN}}

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

多仓库 Daemon

crg-daemonadd~/project-a--aliasproj-a crg-daemonadd~/project-b crg-daemon start crg-daemon status crg-daemon logs--repoproj-a-fcrg-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 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。

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