code-review-graph 怎么用：给 Codex 和 Claude Code 添加 PR 影响分析

code-review-graph 是一个本地优先的代码知识图谱工具，目标是减少 AI 代码审查时反复读取整个仓库的问题。它使用 Tree-sitter 解析函数、类、导入、调用、继承和测试关系，将结果保存到项目内的 SQLite 数据库，再通过 MCP、CLI、Skills 和钩子提供给 Codex、Claude Code、Cursor 等 AI 编程工具。

它尤其适合大型仓库、monorepo 和跨文件 PR：当某个函数发生变化时，图谱可以沿调用与依赖关系计算影响半径，告诉 AI 哪些调用者、测试和执行流更值得检查。

快速结论

需要 Python 3.10 或更高版本。
安装后执行 code-review-graph install，工具会检测已安装的 AI 编程平台并写入对应 MCP 配置。
首次使用要运行 code-review-graph build，之后可用 update、watch 或平台钩子增量维护图谱。
数据默认保存在项目的 .code-review-graph/，核心构图和查询不要求把源码发送到外部服务。
简单的单文件修改不一定省 Token；跨文件调用、测试影响和大型仓库审查更能体现图谱价值。

安装 code-review-graph

推荐使用独立的 Python 工具环境，避免污染项目依赖：

1

pipx install code-review-graph

也可以直接使用 pip：

1

pip install code-review-graph

进入需要分析的 Git 仓库后执行：

1
2
3


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

install 会检测 Codex、Claude Code、Cursor、Windsurf、Zed、Continue、OpenCode、Gemini CLI、GitHub Copilot 等受支持平台，生成合适的 MCP 配置和平台规则。完成后需要重启编辑器或 AI 编程工具。

如果只想配置一个平台，可以指定名称：

1
2
3
4


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

使用 uvx、pip 或 pipx 安装时，install 会尽量识别实际入口并生成对应配置。若 MCP 启动失败，应先确认终端里可以直接运行：

1
2


code-review-graph --help
code-review-graph status

它如何缩小代码审查上下文

构图流程可以简化为：

1

代码仓库 -> Tree-sitter AST -> SQLite 图谱 -> 影响半径 -> 最小审查文件集

图中的节点包括函数、类、文件和导入，边则表示调用、继承、测试覆盖等关系。PR 修改一个文件后，工具会查找：

哪些函数和类直接发生变化；
哪些调用者或依赖可能受影响；
哪些执行流经过这些节点；
是否存在对应测试，以及测试覆盖是否有缺口；
AI 审查时最值得读取哪些文件。

这样，AI 不必只依赖文件名搜索，也不必默认扫描整个仓库。对于跨模块调用和不熟悉的代码库，这比单纯把 PR diff 丢给模型更容易发现间接影响。

如果你想了解通用代码知识图谱与架构分析，可对比 CodeGraph 本地代码知识图谱教程和 Graphify 的 Claude Code 图谱工作流。code-review-graph 的定位更偏向变更影响、风险评分和 PR 审查。

在 Codex 或 Claude Code 中使用

完成安装和构图后，可以直接向 AI 助手提出任务：

1

Build the code review graph for this project

项目还提供 3 个常用斜杠命令：

1
2
3


/code-review-graph:build-graph
/code-review-graph:review-delta
/code-review-graph:review-pr

一个实用的审查流程是：

在仓库根目录确认 code-review-graph status 正常；
修改代码或切换到待审查分支；
执行 code-review-graph update 更新变化部分；
在 Codex 或 Claude Code 中运行 review-delta 或 review-pr；
先看影响半径、风险函数和测试缺口，再让 AI 阅读必要源码；
最后运行项目原有测试，而不是把图谱结果当成测试替代品。

CLI 也提供对应的日常命令：

1
2
3
4
5
6


code-review-graph build
code-review-graph update
code-review-graph status
code-review-graph watch
code-review-graph detect-changes
code-review-graph visualize

watch 适合持续开发；detect-changes 用于分析当前变更；visualize 会生成交互式 HTML 图，便于查看代码社区、Hub、Bridge 和异常耦合。

MCP 工具应该先调用哪个

项目提供多种 MCP 查询工具。日常对话不必一次取回完整图谱，建议从最小上下文开始：

目的	建议工具
先取得极简入口	`get_minimal_context_tool`
查看某个变更的影响范围	`get_impact_radius_tool`
获取审查所需上下文	`get_review_context_tool`
查询调用者、测试、导入或继承	`query_graph_tool`
查看受影响的执行流	`get_affected_flows_tool`
检查风险与测试缺口	`detect_changes_tool`
理解整体架构	`get_architecture_overview_tool`

如果 MCP 工具没有出现，可参考 MCP 工具调用失败排查指南，重点检查配置文件位置、命令是否在 PATH 中、工作目录和编辑器是否已经重启。

让图谱保持最新

首次 build 之后，不需要每次重建整个仓库。可以手动增量更新：

1

code-review-graph update

也可以持续监听：

1

code-review-graph watch

启用受支持的平台钩子后，保存文件或提交时可以触发增量更新。官方 README 给出的示例中，一个约 2,900 文件的项目只重新解析少量变更文件时可在 2 秒内更新，但实际时间仍取决于仓库大小、语言、磁盘和后处理功能。

如果生成文件、vendor 或大型目录已经被 Git 跟踪，但不希望进入图谱，可在仓库根目录创建 .code-review-graphignore：

1
2
3
4


generated/**
*.generated.ts
vendor/**
node_modules/**

在 Git 仓库中，工具默认以 git ls-files 为索引范围，因此 Git 未跟踪和 .gitignore 排除的文件通常不会被索引。

接入 GitHub Action 做 PR 风险检查

code-review-graph 还可以在 GitHub Actions 中运行。官方 README 当前示例为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


name: Code Review Graph

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tirth8205/[email protected]
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Action 会在 CI Runner 本地构图和查询，并给 PR 写入风险函数、受影响执行流和测试缺口。正式采用前应检查仓库最新 Release 或 README，固定明确版本，不要长期复制可能过期的示例版本。

如果团队只想观察结果，可以先让工作流发表评论；确认误报率和速度可以接受后，再考虑启用 fail-on-risk 作为合并门禁。

如何正确理解 Token 节省基准

官方英文 README 报告，在 6 个真实开源仓库的逐问题测试中，相对于“读取整个代码语料库”的基线，中位 Token 缩减约为 82 倍，范围约 38 至 528 倍。528 倍来自单个最佳样本，不是一般项目都能达到的结果。

阅读这些数字时要注意：

全量读取仓库是偏理想化的上界，成熟 Agent 本来就会先搜索再读取少量文件；
对很小的单文件修改，图谱返回的边、影响范围和结构摘要可能比直接读取 diff 更大；
影响分析的部分召回率基准使用同一图谱派生的 ground truth，存在循环性，应视为上界；
搜索排序、JavaScript 和 Go 执行流检测仍有已知改进空间；
图谱倾向多报一些潜在受影响文件，以降低漏掉依赖的风险。

因此，不要把“最高 528 倍”写进团队成本预算。更可靠的方法是在自己的仓库中对比同一批 PR：记录 AI 实际读取文件数、上下文长度、误报、漏报和审查耗时。

常见问题排查

安装后 AI 看不到 MCP 工具

先检查：

1
2


code-review-graph --help
code-review-graph status

然后重新执行指定平台安装并重启工具：

1

code-review-graph install --platform codex

如果使用虚拟环境安装，AI 工具启动时可能找不到同一个 Python 环境。pipx 或 uvx 通常更适合作为全局 CLI 入口。

图谱结果没有包含新代码

先运行：

1
2


code-review-graph update
code-review-graph status

同时确认新文件已经被 Git 跟踪，没有被 .gitignore 或 .code-review-graphignore 排除。必要时执行完整的 build。

小 PR 的上下文反而更多

这是图谱结构元数据带来的固定开销。对于只改一行且没有依赖的修改，直接读 diff 更快。可以让 AI 先调用 get_minimal_context_tool，只有发现跨文件影响时再展开完整审查上下文。

如何安全卸载

先预览将要删除的内容：

1

code-review-graph uninstall --dry-run

确认后再执行：

1

code-review-graph uninstall

如果只想移除集成但保留图谱数据，可使用：

1

code-review-graph uninstall --keep-data

适合哪些项目

比较适合：

有大量跨文件调用的大型代码库；
monorepo、多语言仓库和多人协作项目；
经常用 Codex、Claude Code 或 Cursor 审查 PR；
需要追踪调用者、测试缺口和执行流；
不希望核心代码图依赖外部云数据库。

不一定需要：

只有少量文件的小项目；
主要审查文档或配置变更；
每次修改都局限在单个、独立文件；
团队没有维护索引和处理误报的意愿。

总结

code-review-graph 为 AI 代码审查增加了一层可持续更新的结构索引。它可以帮助 Codex、Claude Code 等工具从“搜索看起来相关的文件”，进一步走向“沿调用、依赖和测试关系分析变更影响”。

实际使用时，先从一个常见 PR 开始：安装、构图、运行增量审查，再把结果与人工审查和真实测试对照。若它能稳定找出跨文件影响并减少无关读取，再接入 watch、钩子或 GitHub Action，会比一开始启用所有功能更容易评估收益。

项目地址：tirth8205/code-review-graph