AB
AB
AiBoss站

全部分类

教程

用代码调用图给 AI 代码评审瘦身：code-review-graph 上手教程

教程

用代码调用图给 AI 代码评审瘦身：code-review-graph 上手教程

AI 代码评审常常把上下文窗口浪费在「猜哪些文件相关」上。code-review-graph 用 Tree-sitter 解析代码库，把函数与类之间的调用关系存进本地 SQLite 图数据库，再通过 MCP 把真正必要的上下文交给 AI 代理。本文介绍安装、MCP 配置、建图、增量更新、风险检测、可视化，以及图陈旧等常见坑。

让 AI 代理做代码评审时，很容易遇到一种别扭的情况：只改了一个函数，代理却为了搞清楚谁调用了它、它又调用了谁，反复去读周边文件。仓库一大，上下文窗口就被这些探索过程吃掉，真正需要看的 diff 反而被挤到后面，评审成本和等待时间一起上涨。根因在于多数 AI 编码工具只会「猜哪些文件可能相关」，并不真正掌握文件之间的调用关系。

code-review-graph 针对的正是这个问题。它用 Tree-sitter 解析代码库，把函数、类以及它们之间的调用关系抽出来，存成本地的 SQLite 图数据库，再通过 MCP 把「真正需要的那一小块上下文」交给 AI 代理。同一个图既能被命令行直接查询，也能被 MCP 工具查询，因此代理不必再靠 read_file 试探，而是直接问图：改这个符号会波及到哪里。本文按安装、配置、建图、增量更新、风险检测、MCP 调用、可视化的顺序讲一遍完整流程，并列出实际使用中容易踩的坑。

这个工具解决什么问题、适合谁

传统做法里，AI 代理面对一次改动，会先读改动文件，再顺着 import 或命名猜测相关文件，读进来发现不对再换一个。这个过程对单文件小改动没什么问题，但改动跨越多个模块时，代理需要读的文件数量会迅速膨胀。

code-review-graph 的思路是把「相关文件」这件事从猜测变成查询。它先对整个代码库做静态解析，把符号和调用关系持久化成图，之后无论是命令行还是 MCP 工具，查的都是同一份图数据。代理拿到的不再是一堆文件内容，而是经过裁剪的上下文和影响范围。

它适合这几类场景：

  • 仓库规模中等偏大，AI 评审时经常出现上下文被探索日志占满的情况。
  • 改动经常横跨多个模块，需要快速判断「这个函数被谁调用、改动会波及哪些调用方」。
  • 希望在提交前用命令行做一次本地风险预判，不依赖任何云端服务。
  • 团队需要给新成员一份可交互的代码结构图，用于熟悉模块全貌。

反过来，如果日常改动基本只落在一个文件里，或者仓库很小、代理本来就能轻松读完，这个工具带来的差异不会明显。它的价值主要体现在中大型改动和跨模块修改上。

准备工作

在动手之前，先确认下面几项。

运行环境

  • Python 3.10 或更高版本。这是硬性要求，版本不够会在安装或运行阶段直接失败。
  • 如果本机装了 uv，使用体验会更顺一些，因为 MCP 配置默认会通过 uvx 来调用。
  • 一个已经纳入版本管理的代码仓库，方便后续用 git 的改动信息做增量更新。

安装

用 pip 安装：

pip install code-review-graph

如果习惯用 pipx 管理命令行工具，也可以：

pipx install code-review-graph

确认要接入的 AI 工具

安装子命令会检测本机环境，并写入对应 AI 工具的 MCP 配置文件。目前支持显式指定平台的写法，例如 Claude Code、Cursor、Copilot。先想清楚要把图接到哪个代理上，再执行配置步骤，可以少走弯路。

了解支持的语言范围

解析层基于 Tree-sitter，覆盖 Python、JavaScript、TypeScript、Go、Rust、Java 等主流语言，另外还包括 Solidity、Terraform 和 Jupyter Notebook。如果你的仓库里有大量不在这个范围内的文件，建图后统计数字可能偏低，这一点在后面的「注意事项」里会再展开。

操作步骤

第一步：为你的 AI 工具生成 MCP 配置

安装完成后，用 install 子命令写入 MCP 配置。让它自动检测：

code-review-graph install

也可以显式指定平台：

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

以 Claude Code 为例，写入仓库的配置形如：

{
  "mcpServers": {
    "code-review-graph": {
      "command": "uvx",
      "args": ["code-review-graph", "serve"]
    }
  }
}

有一点值得留意：即使你已经用 pip 装过，配置里仍然是通过 uvx 来调用的。如果本机没有 uv，需要先补上，否则 MCP 服务起不来。

第二步：构建代码图

在仓库根目录执行：

code-review-graph build

构建过程会遍历代码库、解析符号、写入调用关系。图数据保存在仓库下的 .code-review-graph/ 目录中，以 SQLite 形式落盘，因此整个过程不需要把代码发到任何云端。

构建完成后查看统计：

code-review-graph status

这条命令会给出节点数、边数等信息。如果节点数或边数停留在 0，通常说明解析器没有命中你的语言或路径，优先检查两件事：目标语言是否在支持列表内，以及 .gitignore 是否把源码目录排除掉了。

第三步：让图跟上代码变化

图是某一时刻的快照，代码继续改，图就会过时。有三种方式维持同步。

开发过程中持续监听文件变化并自动更新：

code-review-graph watch

只做风险分析、不改动图（只读）：

code-review-graph detect-changes --brief

同时更新图并输出风险分析：

code-review-graph update --brief

其中 detect-changes --brief 很适合放在调用代理之前做一次本地预检。它完全在本地完成，能给出类似「这次改动涉及 5 处调用方，属于高风险变更」的判断，不需要消耗任何模型额度。

第四步：以 MCP 服务方式启动

手动启动服务：

code-review-graph serve

配置好之后，代理侧一般会自动拉起这个服务。服务对外暴露的工具数量在三十个左右，其中评审场景最常用的是下面几个：

工具作用
get_review_context_tool针对当前 diff 返回经过 token 优化的最小必要上下文
get_impact_radius_tool返回被改符号的影响范围，包含调用方的调用方
semantic_search_nodes_tool按语义而非关键词检索代码节点
query_graph_tool直接查询某个函数的调用方或被调用方

除了工具，还提供了一批 MCP 提示模板，例如 review_changes、pre_merge_check、architecture_map。有了这些模板，直接对代理说「帮我评审这个 PR」，代理就会自行组合上面的工具来完成工作，不需要你手动逐个调用。

第五步：生成可视化图

code-review-graph visualize

这条命令会生成一个可交互的 HTML 图。它适合两个用途：新成员入职时快速建立对代码结构的整体印象；以及隔了很久重新接触某个模块时，先看一眼它和外界的关系再动手。

一个完整示例

下面把流程串成一条最小可跑的路径。假设你有一个 TypeScript 仓库，希望让 AI 代理在评审时少读无关文件。

先安装并写入配置：

pip install code-review-graph
code-review-graph install --platform claude-code

在仓库根目录建图，并确认解析结果不是空的：

code-review-graph build
code-review-graph status

如果 status 显示的节点数明显偏少，先检查 .gitignore 是否把源码目录排除在外，再确认语言是否在支持范围内。

接着在开发过程中保持图更新。可以开一个终端跑监听：

code-review-graph watch

改完代码、准备提交之前，先做一次本地风险预检：

code-review-graph detect-changes --brief

如果输出提示这次改动涉及多个调用方，就说明它属于需要仔细看的变更；如果只是单点小改，风险提示会很轻。

然后让代理介入。启动 MCP 服务：

code-review-graph serve

在代理侧提出评审请求，代理会调用 get_review_context_tool 拿到裁剪后的上下文，必要时再用 get_impact_radius_tool 确认影响范围，而不是逐个文件去读。

最后，如果想让团队里其他人也能直观看到结构，生成一份可视化：

code-review-graph visualize

整条链路的核心只有三个动作：install 写配置，build 建图，serve 供代理查询。其余命令都是围绕这三步做的补充。

注意事项

图会过时，而且不容易察觉

这是最容易出问题的一点。如果没有跑 watch，图就停留在 build 那一刻的状态。代理拿着过时的调用关系做评审，可能得出错误结论，而你在界面上看不出任何异常。稳妥的做法是把 update 放进 CI 或 pre-commit 流程，让图在每次改动后自动跟上，而不是依赖人工记得手动执行。

首次构建在混合语言仓库里会更慢

Tree-sitter 在不同解析器之间切换是有成本的。语言混杂的 monorepo 里，首次 build 的耗时会被拉长。比较现实的做法是限定目标路径，只对真正需要分析的子目录建图，而不是整个仓库一把梭。

token 节省效果取决于改动形态

收益在「需要读很多文件才能理解」的评审场景里最明显。如果一次改动只碰一个文件、上下文本来就很小，体感差异会很有限。判断是否值得引入，可以先看自己日常的改动是不是经常跨模块。

统计数字为 0 时先查两处

status 里节点数和边数没有增长，通常不是工具坏了，而是解析器没抓到目标代码。先确认语言是否在支持列表内，再检查 .gitignore 的排除规则是否把源码目录也一起排掉了。

MCP 配置依赖 uvx

自动生成的配置里，命令是 uvx 而不是直接调用已安装的可执行文件。本机没有 uv 时，MCP 服务无法启动。安装 uv 之后再重跑 install 子命令即可。

版本与功能以官网为准

工具迭代较快，支持的语言列表、子命令参数、MCP 工具数量都可能变化。本文描述的是当前已知的行为，实际使用时请以官网和仓库当前信息为准，尤其是许可证、版本号和各项默认值。

返回