Code-Review-Graph：面向 AI 辅助代码审查的结构化上下文引擎

摘要

在 AI 编码工具日益普及的背景下，代码审查任务面临一个核心效率瓶颈：AI Agent 缺乏对代码库结构关系的先验认知，导致其在审查过程中不得不反复读取大量文件以构建上下文，或依赖基于文本匹配的搜索策略进行试探性定位，造成显著的 Token 消耗与响应延迟。

Code-Review-Graph（CRG）针对这一问题提出了一种基于代码结构图谱的解决方案------通过 Tree-sitter 对代码库进行静态解析，构建函数、类、调用关系、继承链与测试覆盖的结构化映射，并在变更发生时通过图查询精确计算"爆炸半径"（Blast Radius），仅向 AI 交付真正相关的上下文文件。

1. 核心设计理念

CRG 的设计遵循以下原则：

本地优先（Local-First） ：所有数据以 SQLite 文件形式存储在项目 .code-review-graph/ 目录下，不依赖任何外部服务或网络连接。
结构感知（Structure-Aware）：利用 Tree-sitter 进行 AST 级别的代码解析，将代码库抽象为一张包含函数、类、导入关系、调用边、继承关系与测试覆盖信息的有向图。
增量更新（Incremental Update）：变更时仅重新解析受影响的文件，保证在 2,900+ 文件的仓库规模下更新延迟控制在 2 秒以内。
协议集成（Protocol-Native）：通过 MCP（Model Context Protocol）服务器对外暴露 30 个查询工具，使 AI Assistant 能够以结构化的方式查询代码关系图谱。

2. 系统架构

2.1 整体数据流

复制代码

源代码文件
    │
    ▼
Tree-sitter AST 解析 ──────► SQLite 关系图谱
    │                              │
    │  (增量更新)                    │  (MCP 工具链)
    ▼                              ▼
变更检测                    AI Assistant 上下文查询

2.2 核心组件

|----------|----------------------|----------------|
| 组件 | 技术选型 | 职责 |
| AST 解析引擎 | Tree-sitter | 多语言代码结构的精确解析 |
| 图存储层 | SQLite | 持久化存储代码实体及其关系 |
| 增量更新模块 | 文件级差异检测 | 最小化重复解析开销 |
| 对外接口层 | MCP Server（30 Tools） | 向 AI 暴露结构化查询能力 |

2.3 MCP 协议集成

CRG 通过 MCP 服务器对外提供标准化的工具调用接口，AI Assistant 可以基于结构化查询获得精确的代码上下文。开发者无需手动复制或导入文件内容，AI 可直接通过协议完成关系查询、影响面评估与图谱导航。

3. 爆炸半径分析（Blast Radius Analysis）

3.1 问题定义

爆炸半径分析旨在回答：给定一组变更文件，哪些其他文件可能受到影响？ 传统方法依赖 AI Agent 自行推断或基于文本搜索，存在遗漏或过度读取的问题。

3.2 分析方法

CRG 的爆炸半径计算基于图遍历策略，从变更节点出发，沿着以下维度进行影响面扩散：

调用链上行（Caller Trace）：追踪哪些函数/模块调用了变更的代码
依赖链下行（Callee Trace）：追踪变更代码依赖了哪些外部模块
继承层级（Inheritance Hierarchy）：追踪类继承关系中的上下游
测试覆盖关联（Test Coverage Mapping）：关联受影响的测试用例

3.3 准确性与局限性

项目文档对指标给出了诚实的说明：

Recall 上界：当前报告的 recall = 1.0 是基于图导出结果与同图 ground truth 的对比，存在循环性偏差（circularity bias），不代表真实场景下的完整召回率。
Co-change 验证：使用 Git 历史中的 co-change 模式（同次 commit 中一起被修改的文件组）作为独立 ground truth 时，准确率会低于上界报告值。
设计策略 ：爆炸半径分析采用保守策略------宁可多标记候选文件（允许一定程度的误报），也不遗漏可能受影响的依赖（严格控制漏报）。

3.4 Token 节省基准

下图展示了在相同变更场景下，使用图谱上下文与全量文件上下文的 Token 消耗对比。结果显示 CRG 通过精准的爆炸半径分析可将上下文 Token 消耗降低约 78%。

3.5 社区发现应用

基于代码图谱的结构化关系，CRG 还可应用于社区发现（Community Detection）场景，自动识别高度耦合的代码模块集群，辅助架构治理与技术债分析。

4. 三层边置信度模型

为应对静态分析在不同场景下推断能力的差异，CRG 对图谱中的关系边引入了三级置信度标注：

|---------------|----|---------------|-----------------|-----|
| 置信度等级 | 标识 | 推断方式 | 典型场景 | 可信度 |
| EXTRACTED | 高 | 直接从 AST 节点解析 | 显式函数调用、类继承声明 | 高 |
| INFERRED | 中 | 基于类型推断或语义分析推导 | 接口实现、类型推导的方法调用 | 中 |
| AMBIGUOUS | 低 | 动态特性导致无法静态确定 | 反射调用、运行时多态、动态导入 | 低 |

4.1 设计意义

该分层模型允许查询方根据场景需求进行置信度过滤：

安全审查场景：可仅使用 EXTRACTED 级别的关系，确保分析结果的高确定性；
全面影响分析：可引入 INFERRED 与 AMBIGUOUS 边，获取更完整的影响面视图，同时知晓其中存在的推断风险；
渐进式置信度提升：随着语言特性的深入支持与类型推断能力的增强，部分 AMBIGUOUS 边可向 INFERRED 乃至 EXTRACTED 迁移。

5. 安装与使用

5.1 环境要求

已配置 Claude Code 或其他支持 MCP 的 AI 编码工具
了解 MCP（Model Context Protocol）的基本工作原理
具备静态分析与代码调用图的基本概念

5.2 快速部署

复制代码

# 一键安装，自动检测已安装的 AI 工具并写入对应 MCP 配置
code-review-graph install

install 命令会自动完成以下步骤：

检测本机已安装的 AI 编码平台
为每个平台写入正确的 MCP 服务配置
将 graph-aware 指令注入平台规则文件
安装对应的 hooks 与 skills

5.3 初始化图谱

重启编辑器后，向 AI Assistant 发出指令：

帮我建立这个项目的知识图谱

下图展示了通过 AI 编码助手以自然语言交互方式构建项目知识图谱的实际过程。

5.4 变更检测

通过以下命令进行增量更新与校验：

复制代码

# 输出变更摘要
code-review-graph detect-changes --brief

# 或使用 update 命令
code-review-graph update --brief

# 与 OpenAI cl100k_base tokenizer 对比验证
code-review-graph detect-changes --verify

6. 关键指标

|--------------|-----------------|
| 指标 | 数值 / 说明 |
| 支持仓库规模 | 2,900+ 文件 |
| 增量更新时间 | ≤ 2 秒 |
| MCP 工具数量 | 30 |
| 存储格式 | SQLite（零网络依赖） |
| Token 节省上限 | 528x（最优场景，非中位数） |
| 上下文 Token 降幅 | 约 78%（典型场景） |

注意：528x 的 Token 节省比率来自最优场景的测量，不代表典型使用场景下的平均值或中位数。实际收益取决于代码库规模、变更范围以及 AI 工具的原生上下文策略。

7. 总结

Code-Review-Graph 通过将代码库的结构信息前置计算为可查询的关系图谱，从根本上改变了 AI 编码工具在代码审查场景中的上下文获取方式。其核心价值在于：

将 AI 从"盲目读取"转变为"精准查询"
通过增量更新保证大规模仓库的实时性
以三级置信度模型为不同安全等级的场景提供灵活的分析粒度
基于 MCP 协议实现与主流 AI 工具的标准化集成

该项目为 AI 辅助代码审查的上下文效率问题提供了一种工程上可行的解决路径，在 Token 消耗优化与审查准确性之间取得了务实的平衡。