code-review-graph 深度拆解：Tree-sitter 知识图谱如何让 AI 代码审查节省 82 倍 Token

一、问题的本质：AI 编程工具正在"烧钱"

在 2026 年的今天，Claude Code、Cursor、Codex 这类 AI 编程工具已经成为无数开发者的日常伴侣。你让它审查一个 PR，它默默开始读取文件；你让它理解某个模块，它打开编辑器把整个仓库翻了一遍。问题来了——它读的那些代码，真的都必要吗？

答案在大多数场景下是否定的。

以一个 2000 文件的典型中大型项目为例。当 AI 收到"审查这个 PR"的任务时，它面临的选择是：

1. 保守策略：把仓库里所有可能相关的文件都读一遍，确保不遗漏任何上下文。后果是 Token 消耗爆炸，一个 PR 审查轻松烧掉几万 Token。
2. 激进策略：只读 diff 涉及的文件。后果是遗漏间接依赖，可能给出完全错误的审查意见。

这是传统 AI 编程工具的根本困境：没有结构化上下文感知能力，只能靠暴力枚举来规避遗漏。

2026 年 7 月，一个由知名独立开发者 Simon Willison（Datasette、sqlite-utils 作者）创建的开源工具 code-review-graph 横空出世，登顶 GitHub Trending 第一名，当天斩获 1641 颗 Stars。它用一种极其优雅的方式破解了这个困境——给代码库构建本地知识图谱，让 AI 只读真正该读的文件。

benchmark 数据相当惊人：中位数 Token 消耗降低 82 倍，最优案例（fastapi 仓库）达到 528 倍，官方甚至给出了可复现步骤。

二、项目概述：从"全量扫描"到"精准导航"

2.1 一句话定位

code-review-graph 是一个本地优先的代码知识图谱构建工具，专门为 AI 辅助代码审查场景优化。它通过 Tree-sitter 解析代码 AST，构建结构化关系图，通过 MCP（Model Context Protocol）协议向 AI 编程助手提供精准的上下文查询能力。

用一句话概括它的价值：让 AI 从"读完全部代码"变成"只读该读的代码"。

2.2 核心数据一览

2.3 适用场景

code-review-graph 特别适合以下场景：

• 大型 Monorepo 仓库：动辄数万文件的工程，AI 每次读取全量代码不现实
• 跨模块重构：修改一个底层模块，需要快速找出所有依赖它的上层模块
• PR 代码审查：AI 审查一个变更，需要了解其影响范围而非仅看 diff
• 遗留代码理解：接手陌生项目，需要快速建立代码结构认知
• CI/CD 集成：在流水线中自动进行风险评估和上下文审查

三、技术架构深度解析：三层架构的工程哲学

code-review-graph 的架构设计非常克制，核心只有三层：解析层 → 存储层 → 暴露层。每一层都有明确的设计决策，理解这些决策背后的原因，才能真正用好这个工具。

3.1 第一层：Tree-sitter AST 解析引擎

Tree-sitter 是 GitHub 开发的一个增量式语法解析器生成器，能够为任何编程语言生成精确的抽象语法树（AST）。它不同于正则表达式或简单文本匹配——它真正理解代码的结构。

# Tree-sitter 的核心能力：理解代码结构而非文本匹配

# 给定这样一段 Python 代码：
def authenticate_user(username, password):
    db = get_database()
    user = db.query("SELECT * FROM users WHERE name = ?", username)
    return verify_hash(password, user.password_hash)

# 正则匹配只能找到 "query" 这个字符串
# Tree-sitter 理解：
#   - 这是一个函数定义（FunctionDef），节点名为 "authenticate_user"
#   - 函数体内有一个调用表达式（Call），函数名是 "db.query"
#   - 参数包含字符串 "SELECT * FROM users WHERE name = ?"
#   - 另一个调用表达式 verify_hash，依赖 user.password_hash

code-review-graph 对 Tree-sitter 的使用方式：

从每个源文件中，工具提取两类核心数据：

节点（Nodes）：

• 函数定义（function_def）
• 类定义（class_def）
• 导入语句（import_statement / import_from）
• 变量声明（variable_declarator）
• 类型注解（type_annotation）

边（Edges）：

• 调用关系：function_a → function_b（a 调用了 b）
• 依赖关系：file_a → file_b（a 导入了 b）
• 继承关系：class_a → class_b（a 继承了 b）
• 测试覆盖：test_file → tested_file（测试文件覆盖了哪些文件）

# code-review-graph 内部节点数据结构示意（简化版）
@dataclass
class GraphNode:
    node_id: str           # 全局唯一标识，如 "python:authenticate_user:12:1"
    node_type: str         # "function_def" | "class_def" | "import" | ...
    file_path: str         # 文件路径
    name: str              # 节点名称
    start_line: int        # 在文件中的起始行
    end_line: int          # 在文件中的结束行
    docstring: Optional[str]  # 文档字符串（如果有）

@dataclass
class GraphEdge:
    source_id: str    # 起始节点
    target_id: str    # 目标节点
    edge_type: str    # "calls" | "imports" | "inherits" | "tests" | ...
    confidence: float # 置信度（用于模糊匹配场景）

为什么选 Tree-sitter 而非 LSP？

这是一个常见问题：为什么不直接用 Language Server Protocol（LSP）？LSP 同样可以提供符号查找、引用跳转等功能。Tree-sitter 的核心优势在于：

1. 离线可用：不需要运行语言的 LSP 服务器，纯本地解析
2. 支持 40+ 语言：LSP 服务器需要每种语言单独安装
3. 增量解析：Tree-sitter 本身就是增量的，文件修改时只重解析受影响部分
4. 无状态：不需要维护 LSP 会话状态

3.2 第二层：SQLite 本地知识图谱存储

SQLite 是这个项目中另一个关键选择。它不是"为了简单而简单"的妥协，而是一个深思熟虑的架构决策。

-- code-review-graph 的 SQLite schema 核心结构

-- 节点表：存储所有代码实体
CREATE TABLE nodes (
    id TEXT PRIMARY KEY,
    node_type TEXT NOT NULL,      -- function_def, class_def, import, ...
    file_path TEXT NOT NULL,
    name TEXT NOT NULL,
    start_line INTEGER,
    end_line INTEGER,
    docstring TEXT,
    content_hash TEXT,            -- SHA-256，用于增量更新判断
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 边表：存储节点之间的关系
CREATE TABLE edges (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    source_id TEXT NOT NULL,
    target_id TEXT NOT NULL,
    edge_type TEXT NOT NULL,      -- calls, imports, inherits, tests, ...
    confidence REAL DEFAULT 1.0,
    FOREIGN KEY (source_id) REFERENCES nodes(id),
    FOREIGN KEY (target_id) REFERENCES nodes(id)
);

-- 文件表：存储文件元数据
CREATE TABLE files (
    path TEXT PRIMARY KEY,
    language TEXT NOT NULL,
    line_count INTEGER,
    content_hash TEXT NOT NULL,   -- 用于检测变更
    last_analyzed TIMESTAMP
);

-- 变更记录表：用于爆炸半径分析
CREATE TABLE blast_radius_cache (
    file_path TEXT PRIMARY KEY,
    affected_files TEXT NOT NULL,  -- JSON 数组，存储受影响的文件列表
    computed_at TIMESTAMP
);

-- 全文搜索索引
CREATE VIRTUAL TABLE nodes_fts USING fts5(
    name, docstring, content='nodes', content_rowid='rowid'
);

SQLite 的设计优势：

1. 零配置：无需安装数据库服务，.code-review-graph/graph.db 就是一个完整的图数据库
2. 原子性：增量更新要么全成功要么全失败，不会出现半损坏状态
3. 跨平台：macOS/Linux/Windows 均可原生运行
4. 性能足够：对于单项目仓库（几千到几万节点），SQLite 的查询性能完全够用
5. 可移植：图谱数据库就是单个文件，Git 协作时同事可以共享

存储位置约定：

your-project/
└── .code-review-graph/
    ├── graph.db              # SQLite 知识图谱
    ├── config.toml           # 项目配置
    ├── logs/                 # 解析日志
    └── cache/                # 增量更新缓存

3.3 第三层：MCP 协议暴露机制

MCP（Model Context Protocol） 是 Anthropic 在 2024 年底提出的标准协议，旨在让 AI 助手能够安全、可控地调用外部工具和数据访问接口。code-review-graph 通过 MCP 将知识图谱暴露给 AI 编程助手。

MCP 的核心价值在这里体现为两个维度：

安全维度：AI 不会直接读取文件，而是通过 MCP 调用工具获取结构化信息。代码始终在本地，MCP 只是查询接口。

结构维度：AI 不再处理原始文本，而是接收结构化的图谱查询结果（"以下 8 个文件是变更的爆炸半径"），大幅降低了理解成本。

# MCP 工具接口示意（简化）

# 当 Claude Code 询问："审查这个 PR 涉及哪些模块？"
# code-review-graph 通过 MCP 返回的工具调用结果：

{
    "tool": "get_blast_radius",
    "arguments": {
        "changed_files": ["src/auth/handlers.py", "src/auth/models.py"],
        "max_depth": 3
    },
    "result": {
        "impacted_files": [
            {"path": "src/auth/handlers.py", "depth": 0, "reason": "直接变更"},
            {"path": "src/auth/models.py", "depth": 0, "reason": "直接变更"},
            {"path": "src/auth/middleware.py", "depth": 1, "reason": "导入 models.py"},
            {"path": "tests/auth/test_handlers.py", "depth": 1, "reason": "测试覆盖 handlers.py"},
            {"path": "src/api/routes.py", "depth": 2, "reason": "通过 handlers 间接依赖"},
            {"path": "src/auth/jwt.py", "depth": 2, "reason": "被 handlers 调用"},
        ],
        "excluded_files": 2847,   # 被排除在审查上下文之外的文件数
        "risk_score": "medium"
    }
}

四、爆炸半径分析：从图论到代码工程

4.1 什么是"爆炸半径"

"爆炸半径"（Blast Radius）是一个工程安全领域的概念，原指危险物质爆炸时的影响范围。code-review-graph 将这个概念引入代码工程：当某个文件发生变更时，这个变更会影响到哪些文件？

# 爆炸半径分析示意代码

def compute_blast_radius(changed_file: str, graph: GraphDB, max_depth: int = 3) -> list[ImpactedFile]:
    """
    计算变更文件的爆炸半径

    广度优先搜索：从变更文件出发，沿调用/依赖关系向外扩散
    """
    results = []
    visited = set()
    queue = deque([(changed_file, 0, "直接变更")])

    while queue:
        current_file, depth, reason = queue.popleft()
        if depth > max_depth or current_file in visited:
            continue
        visited.add(current_file)

        results.append(ImpactedFile(
            path=current_file,
            depth=depth,
            impact_reason=reason
        ))

        # 找出所有依赖 current_file 的文件（反向调用关系）
        dependents = graph.get_dependents(current_file)
        for dep in dependents:
            queue.append((dep.file_path, depth + 1, f"依赖 {current_file}"))

        # 找出 current_file 的测试覆盖
        test_files = graph.get_test_coverage(current_file)
        for test_file in test_files:
            if test_file not in visited:
                results.append(ImpactedFile(
                    path=test_file,
                    depth=depth + 1,
                    impact_reason=f"测试覆盖 {current_file}"
                ))

    return results

4.2 增量更新：SHA-256 哈希对比

全量重建知识图谱的成本太高。code-review-graph 的增量更新机制非常优雅：

文件变更检测流程：
1. 计算所有文件的 SHA-256 内容哈希（初始构建）
2. 每次更新时，重新计算变更文件的哈希
3. 哈希变化 → 文件实际修改 → 重新解析该文件
4. 更新图谱中该文件的所有节点和边
5. 清理该文件的所有出边/入边（关系可能变化）
6. 重新建立受影响节点的关系

# 增量更新实战演示

# 初始构建（假设 2900 文件）
$ code-review-graph build
[code-review-graph] 解析中: 2900 文件 ✓ (8.7 秒)

# 修改了一个文件后增量更新
$ code-review-graph update
[code-review-graph] 检测变更: 1 文件 (src/auth/handlers.py)
[code-review-graph] 重新解析: 1 文件
[code-review-graph] 更新图谱: 3 个节点, 7 条边
[code-review-graph] ✓ 增量更新完成 (1.3 秒)

# 查看图谱状态
$ code-review-graph status
图谱节点总数: 4,291
图谱边总数:   18,472
上次更新:    2026-07-28 15:05:23
存储大小:    2.4 MB

Git 集成钩子：

# 安装 pre-commit hook，每次 commit 自动增量更新
$ code-review-graph install --git-hook

# 安装后，git commit 时自动触发：
# 1. 获取本次 commit 涉及的文件列表
# 2. 增量更新图谱
# 3. 可选：在 commit message 中附加爆炸半径摘要

4.3 Monorepo 漏斗过滤

对于大型 Monorepo，爆炸半径分析的价值被无限放大。以一个典型 Monorepo 为例：

• 总文件数：27,700+
• 爆炸半径内文件数：~15
• 排除文件数：27,700+

这就是"漏斗过滤"的核心思想：27,700 个文件 → 精准过滤 → 只给 AI 呈现真正相关的 15 个文件。

# Monorepo 漏斗过滤示意

def monorepo_filter(graph: GraphDB, changed_packages: list[str], max_files: int = 50) -> list[File]:
    """
    Monorepo 场景下的多级漏斗过滤

    Level 1: 变更包内的文件
    Level 2: 变更包直接依赖的其他包
    Level 3: 被测试覆盖的文件
    Level 4: 入口点相关的文件
    """
    candidates = []

    for pkg in changed_packages:
        # Level 1: 包内变更
        pkg_files = graph.get_package_files(pkg)
        candidates.extend([(f, 1) for f in pkg_files])

        # Level 2: 包外直接依赖
        dep_pkgs = graph.get_dependent_packages(pkg)
        for dep_pkg in dep_pkgs:
            dep_files = graph.get_package_files(dep_pkg)
            candidates.extend([(f, 2) for f in dep_files])

    # 按深度排序，取前 N 个
    candidates.sort(key=lambda x: x[1])
    return [f for f, _ in candidates[:max_files]]

五、代码实战：从安装到生产级使用

5.1 环境准备与安装

# 方式一：pip 安装
pip install code-review-graph

# 方式二：pipx 安装（推荐，隔离环境）
pipx install code-review-graph

# 方式三：uv 安装（最快）
uv tool install code-review-graph

# 验证安装
$ code-review-graph --version
code-review-graph 0.9.x

5.2 基础配置

# 进入你的项目目录
cd your-awesome-project

# 自动检测并配置所有支持的 AI 平台
code-review-graph install

# 预期输出：
# [code-review-graph] 检测到以下已安装平台:
#   - Claude Code ✓
#   - Cursor ✓
#   - GitHub Copilot (VS Code) ✓
# [code-review-graph] 正在写入 MCP 配置...
# [code-review-graph] 安装完成！运行 `code-review-graph build` 开始构建图谱

配置特定平台：

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

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

# 列出所有支持平台
code-review-graph install --list-platforms

5.3 构建与增量更新

# 初始构建（一次性）
$ code-review-graph build
[code-review-graph] 开始解析代码库...
[code-review-graph]   发现 40+ 种编程语言
[code-review-graph]   解析文件: 847  files (Python), 234 (TypeScript), ...
[code-review-graph]   构建知识图谱...
[code-review-graph]   索引完成: 4,291 节点, 18,472 边
[code-review-graph] ✓ 图谱构建完成 (9.2 秒)

# 后续增量更新（推荐放在 pre-commit hook 中）
$ code-review-graph update
[code-review-graph] 检测到 2 个文件变更
[code-review-graph] ✓ 更新完成 (0.8 秒)

# 监听文件变更自动更新（开发时使用）
$ code-review-graph watch
[code-review-graph] 监听中... (Ctrl+C 退出)
[code-review-graph] 检测到变更: src/api/handlers.py
[code-review-graph] ✓ 增量更新 (0.4 秒)

5.4 在 Claude Code 中使用

配置完成后，直接在 Claude Code 中对话即可：

# 在 Claude Code 中输入：
> Build the code review graph for this project

# Claude Code 会自动通过 MCP 调用 code-review-graph，
# 构建图谱并缓存

# 之后审查 PR：
> Review this PR, show me the blast radius

# Claude Code 响应：
# 爆炸半径包含以下 12 个文件：
# 1. src/auth/handlers.py（直接变更）
# 2. src/auth/models.py（直接变更）
# 3. tests/auth/test_handlers.py（测试覆盖）
# 4. src/auth/middleware.py（依赖 models.py）
# ...
#
# Token 节省：原本需读取 23,847 个 Token，
# 爆炸半径方案仅需读取 1,892 个 Token（节省 91%）

5.5 命令行直接查询

# 查看图谱统计
$ code-review-graph status
节点总数: 4,291
  - 函数定义: 1,847
  - 类定义: 423
  - 导入语句: 1,204
  - 类型注解: 817
边总数: 18,472
  - 调用关系: 8,234
  - 导入关系: 6,891
  - 继承关系: 412
  - 测试覆盖: 2,935
存储: 2.4 MB (SQLite)

# 查询文件依赖
$ code-review-graph query deps src/auth/handlers.py
src/auth/handlers.py 依赖:
  - src/auth/models.py
  - src/auth/jwt.py
  - src/common/exceptions.py
  - src/database/connection.py

# 查询谁依赖某文件
$ code-review-graph query dependents src/auth/models.py
依赖 src/auth/models.py 的文件:
  - src/auth/handlers.py (调用: User, authenticate_user)
  - src/auth/middleware.py (调用: get_current_user)
  - src/auth/admin.py (调用: User, update_user)

# 风险评估
$ code-review-graph risk src/auth/handlers.py
文件: src/auth/handlers.py
风险评分: 中等 (3.2/10)
影响: 4 个直接依赖, 7 个间接依赖, 12 个测试用例
建议: 提交前运行认证相关测试套件

5.6 可视化导出

# 生成交互式 HTML 架构图
$ code-review-graph visualize --output ./graph.html
[code-review-graph] 生成交互式图谱...
[code-review-graph] ✓ 已保存至 ./graph.html

# 导出为 DOT 格式（用于 Graphviz）
$ code-review-graph visualize --format dot --output ./graph.dot

# 生成 Markdown 架构文档
$ code-review-graph wiki --output ./ARCHITECTURE.md

六、CI/CD 集成实战

6.1 GitHub Actions 集成

# .github/workflows/code-review.yml
name: Code Review Graph

on:
  pull_request:
    types: [opened, synchronize]
  push:
    branches: [main]

jobs:
  code-review-graph:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 需要完整历史以计算 blast radius

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install code-review-graph
        run: pip install code-review-graph

      - name: Build knowledge graph
        run: code-review-graph build

      - name: Run risk assessment
        id: risk
        run: |
          RESULT=$(code-review-graph risk --changed-files "${{ github.event.pull_request.changed_files }}")
          echo "result=$RESULT" >> $GITHUB_OUTPUT
          echo "$RESULT"

      - name: Post comment
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 📊 Code Review Graph 分析结果\n\n**风险评分**: ${{ steps.risk.outputs.result }}\n\n请确保在合并前完成相关测试。`
            })

6.2 合并门控（Fail on High Risk）

# 在 CI 中使用高风险阻断
$ code-review-graph risk --changed-files "src/core/payment.py" --threshold 7.0
ERROR: 风险评分 8.5 超过阈值 7.0
  → 建议: 阻止合并，安排专项 review

# 在 GitHub Actions 中使用
$ code-review-graph risk \
    --changed-files "${{ github.event.pull_request.changed_files }}" \
    --fail-on-high-risk \
    --threshold 7.0

6.3 GitLab CI 集成

# .gitlab-ci.yml
code-review:
  stage: test
  image: python:3.12-slim
  before_script:
    - pip install code-review-graph
    - code-review-graph build
  script:
    - code-review-graph risk --changed-files "$CHANGED_FILES"
  variables:
    CHANGED_FILES: ""  # 在 MR pipeline 中由 GitLab 自动填充
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

七、与其他方案的对比：为什么知识图谱优于传统 RAG

7.1 RAG 方案的根本问题

在 code-review-graph 出现之前，业界主流的"AI 读懂代码"方案是 RAG（检索增强生成）——将代码切成块，通过 embedding 存入向量数据库，查询时用相似度检索。

这个方案有三个根本性问题：

问题一：丢失调用关系

# 一段典型的 Python 代码
def process_payment(order_id: str, amount: float) -> PaymentResult:
    order = Order.objects.get(id=order_id)
    payment = Payment.objects.create(order=order, amount=amount)
    # 发送通知
    NotificationService.send(order.user, "payment_success")
    return PaymentResult(success=True, payment_id=payment.id)

RAG 将这段代码切成块后，可能丢失的信息：

• process_payment 调用了 Order.objects.get
• process_payment 调用了 Payment.objects.create
• process_payment 调用了 NotificationService.send
• order.user 访问了一个外键关系

向量检索只知道"这段文字和查询相似"，不知道这些调用关系。

问题二：上下文窗口浪费

# 检索回来的内容可能包含大量无关信息
# 查询: "认证流程"
# RAG 返回:
#   - auth.py: "def authenticate..." (有用)
#   - middleware.py: "async def auth_middleware..." (部分有用)
#   - logging.py: "# TODO: add auth logging" (完全无关，但恰好包含 "auth" 关键词)
#   - config.py: "AUTH_CONFIG = {'timeout': 30}" (边界相关)

问题三：无法回答结构化问题

• ❌ "修改这个文件会影响哪些测试？"（RAG 无法回答）
• ❌ "这个函数的调用链路是什么？"（RAG 只能返回文本片段）
• ✅ "谁调用了这个函数？"（知识图谱可以精确回答）

7.2 方案对比表

7.3 两者结合的场景

在某些场景下，RAG 和知识图谱可以互补：

# 混合使用策略

def hybrid_code_query(query: str, graph: GraphDB, vector_db: VectorDB):
    """
    结合图谱精确性和 RAG 语义理解的最优查询策略
    """
    # Step 1: 图谱查询获取精确的爆炸半径
    if "impact" in query or "affect" in query or "dependency" in query:
        return graph.query_blast_radius(...)

    # Step 2: 图谱查询获取相关文件
    relevant_files = graph.get_related_files(...)

    # Step 3: 在相关文件范围内使用 RAG 做语义检索
    if "why" in query or "explain" in query or "how does" in query:
        return vector_db.semantic_search(
            query=query,
            filter_files=relevant_files  # 在已知相关文件内检索，而非全库
        )

    # Step 4: 两者结合
    return {
        "files": relevant_files,
        "explanation": vector_db.summarize_context(query, relevant_files),
        "call_graph": graph.get_call_chain(relevant_files)
    }

八、性能基准测试：82 倍 Token 节省是怎么算出来的

8.1 测试方法论

code-review-graph 的 benchmark 完全可复现，官方在 docs/REPRODUCING.md 中详细记录了每一步：

测试环境：

• 6 个真实开源仓库（fastapi、code-review-graph 自身、gin、flask、express、httpx）
• 13 个真实 commit 样本
• 对比基准：Claude Code 默认行为（读取完整仓库上下文）
• 对比目标：code-review-graph 爆炸半径方案（只读相关文件）

Token 计算方法：

# 模拟 Claude Code 读取文件的 Token 估算
def estimate_tokens(file_path: str) -> int:
    with open(file_path) as f:
        content = f.read()
    # Claude 的 Token 估算：中文约 2 字符/token，英文约 4 字符/token
    # 简化估算：总字符数 / 4
    lines = content.count('\n') + 1
    avg_chars_per_line = len(content) / max(lines, 1)
    return int(len(content) / 3.5)  # 中英文混合场景

# 原始方案 Token 数 = 所有读取文件的 Token 之和
# 图谱方案 Token 数 = 爆炸半径内文件的 Token 之和

8.2 核心测试数据

中位数降低：82 倍

8.3 复现步骤

# 完整复现步骤（官方文档简化版）

# 1. 克隆官方 benchmark 仓库
git clone https://github.com/.../code-review-graph-benchmark
cd code-review-graph-benchmark

# 2. 安装依赖
pip install -r requirements.txt
pip install code-review-graph

# 3. 运行基准测试
python -m benchmark \
    --repos ./test-repos \
    --commits ./test-commits.json \
    --output ./results.csv

# 4. 生成报告
python -m benchmark.report ./results.csv

# 预期输出：
# ========================================================================
# code-review-graph Benchmark Results
# ========================================================================
# Total repos tested: 6
# Total commits tested: 13
#
# Median token reduction: 82.0x
# Min token reduction:  38.0x
# Max token reduction:  528.4x
#
# ✅ Results are deterministic (CPU embedding, fixed seeds)

8.4 关于 528x 的特别说明

官方明确指出，528 倍是 fastapi 仓库的最优单案例，不代表日常使用中的典型数值。更现实的参考值是中位数的 82 倍。 即使是 82 倍，对于一个月均消耗数万 Token 的大型团队来说，也是显著的成本节省。

九、支持平台与生态

9.1 支持的编程语言（40+）

主流语言：
Python, JavaScript, TypeScript, JSX, TSX, Go, Rust, Java, C, C++, C#, Ruby, Kotlin, Swift, PHP, Scala

前端框架：
Vue SFCs, Svelte SFCs, Astro

脚本与配置：
Shell (Bash/Zsh), PowerShell, Lua/Luau, Perl, Nix

数据与查询：
SQL, R, Julia

区块链：
Solidity

基础设施即代码：
Terraform/OpenTofu (.tf 文件), Ansible

其他：
Verilog/SystemVerilog, Zig, Elixir, ReScript, GDScript, Objective-C, Jupyter/Databricks notebooks (.ipynb)

自定义语言扩展：
如果你的语言不在列表中，可以编辑 languages.toml 配置文件添加，无需修改源代码：

# .code-review-graph/languages.toml

[[language]]
name = "Zig"
extensions = ["zig"]
tree_sitter_scope = "zig"

[[language]]
name = "Nim"
extensions = ["nim"]
tree_sitter_scope = "nim"
# 自定义节点提取规则
[node_selectors]
function = ["function_definition", "proc_definition"]
import = ["import_statement", "using"]

9.2 支持的 AI 平台（16 个）

通过 code-review-graph install 自动配置：

9.3 MCP 工具列表

code-review-graph 通过 MCP 暴露了约 30 个工具，以下是最核心的几个：

// MCP 工具清单（核心子集）

// 1. 构建图谱
get_code_graph(config: { skip_positions?: boolean })

// 2. 爆炸半径分析
get_blast_radius(changes: {
  changed_files: string[],
  max_depth?: number,      // 默认 3
  include_tests?: boolean   // 默认 true
})

// 3. 依赖查询
get_dependencies(file: string, direction: "forward" | "reverse")

// 4. 调用链路追踪
get_call_chain(
  function_name: string,
  file?: string,
  max_depth?: number
)

// 5. 语义搜索
semantic_search(
  query: string,
  limit?: number,
  filter?: { languages?: string[], min_depth?: number }
)

// 6. 风险评分
get_risk_score(
  files: string[],
  threshold?: number
)

// 7. 测试影响分析
get_test_impact(files: string[])

// 8. 架构概览
get_architecture_overview(options: {
  depth?: number,
  layout?: "radial" | "hierarchical"
})

十、局限性分析：它不能做什么

作为一个诚实的工程师视角，我必须指出 code-review-graph 的局限性：

10.1 Tree-sitter 的解析局限性

1. 不理解运行时行为

# Tree-sitter 只能静态分析，无法追踪动态调用
def router():
    # 这是一个运行时才确定的动态调用
    # Tree-sitter 不知道 handler 实际指向什么
    handler = get_handler(request.path)  # ❌ 无法解析
    return handler(request)

# 同样的问题出现在：
# - 反射：type(...)
# - 元编程：decorator 动态注册
# - 动态 import：__import__(...)

2. 跨二进制依赖无法分析

# Python 调用 Rust 编译的 .so 文件
# Tree-sitter 只能看到 Python 侧，无法分析 Rust 侧
import my_rust_lib  # ❌ 不知道 Rust 函数的具体签名
result = my_rust_lib.process(data)

3. 动态类型语言的歧义

# TypeScript 的类型推断有时需要完整上下文
# Tree-sitter 可能在单独文件中无法准确判断类型
const data: any = await fetch(url)
data.someMethod()  # Tree-sitter 不知道 data 的实际类型

10.2 爆炸半径分析的局限性

1. 语义等价性漏报

# 如果两个函数名字不同但逻辑相似，
# Tree-sitter 不会标记它们为相关
def validate_email(email: str) -> bool:
    return re.match(r'^[a-zA-Z0-9...]', email) is not None

# 另一个文件中有一个功能完全相同的函数
def check_email_validity(addr: str) -> bool:
    return bool(re.fullmatch(r'^[a-zA-Z0-9...]', addr))
# Tree-sitter 认为这是两个无关函数
# 但如果你删除了 validate_email，可能影响 check_email_validity 的维护

2. 外部 API 依赖无法追踪

# 依赖外部服务的场景
# 任何修改 httpbin.org 或 Stripe API 的变更
# code-review-graph 只能追踪代码内关系，无法感知外部依赖
import requests
requests.post("https://api.stripe.com/v1/charges", ...)

10.3 使用门槛

• 需要开发者理解"图谱"这个概念，对非技术管理者有认知门槛
• 初始构建在大型 Monorepo 上可能需要数分钟
• 需要维护 Git hook 或 CI pipeline 集成

十一、总结与展望：知识图谱是 AI 编程的下一个基础设施

11.1 核心价值回顾

code-review-graph 解决了一个非常具体但极其普遍的问题：AI 编程工具缺乏代码结构感知能力，只能靠暴力枚举来避免遗漏。

它用知识图谱替代了向量检索，用结构化关系替代了文本相似度，用精确上下文替代了全量扫描。82 倍的 Token 节省只是表面结果，更深层的价值是：

• 质量提升：AI 不再被无关代码干扰，审查意见更精准
• 成本下降：Token 消耗降低一个数量级
• 速度提升：增量更新 < 2 秒，AI 响应更快
• 隐私保护：代码完全本地，AI 服务商看不到你的代码

11.2 未来演进方向

从项目的 README 和 Simon Willison 的博客中可以推测几个可能的发展方向：

1. 多语言交叉分析：当前版本主要在单仓库内工作，未来可能支持跨语言依赖分析（例如 Python 项目中对 C 扩展的依赖追踪）

2. 实时协作：多人协作时图谱的实时同步

3. 更强的语义层：从纯结构化图谱向语义图谱演进，结合 LLM 自动生成函数文档和代码解释

4. IDE 深度集成：不只是 MCP 工具调用，而是作为 IDE 的原生功能（如跳转到"这个函数的调用者"）

5. 安全扫描增强：结合 CVE 数据库，标记爆炸半径内涉及已知漏洞的依赖

11.3 开发者行动建议

立即可做：

# 1. 安装体验（5 分钟）
pip install code-review-graph
cd your-project
code-review-graph install
code-review-graph build

# 2. 在 Claude Code 中试用
# > Review the blast radius of the last commit

# 3. 如果满意，集成到 pre-commit hook
code-review-graph install --git-hook

规模化使用：

# 1. 在团队 Monorepo 中推广
# 2. 配置 GitHub Actions CI
# 3. 建立团队规范：PR 审查必须包含图谱爆炸半径报告

贡献社区：

• 如果你的编程语言不在支持列表，提交 languages.toml 配置 PR
• 如果发现 Tree-sitter 解析质量问题，提交 issue 或修复 parser
• 参与 benchmark 复现，推动数据透明化

写在最后：

code-review-graph 的出现，标志着 AI 编程工具从"暴力枚举时代"迈向"结构化推理时代"。当 AI 能够真正理解代码的结构——调用关系、依赖关系、测试覆盖——而不只是把代码当作一段段文字来处理，它才能真正成为一个合格的"代码工程师"而非"超级文本补全器"。

这个转变才刚刚开始。

Slogan: Stop burning tokens. Start reviewing smarter.
翻译：别再把 Token 烧在无关代码上了，开始更聪明地审查。

本文参考资料：code-review-graph 官方文档（2026年7月）、CSDN 技术博客系列、Simon Willison 博客（simonwillison.net）。所有 benchmark 数据来源于项目官方可复现测试。