code-review-graph：为 AI 编程工具提供精准上下文的本地代码知识图谱
你是否曾经被这样的场景困扰：让 AI 助手审查一次改动，它却先抛开整个代码库，把成百上千个毫不相关的文件从头读一遍，既慢又烧 token？code-review-graph 的出现，正是为了彻底解决这个问题。它是一个用 Python 编写的本地优先（local-first）代码知识图谱工具，通过 Tree-sitter 解析代码库、构建持久化的结构图，并通过 MCP（Model Context Protocol）向 AI 编程工具提供”刚刚好”的上下文，让助手只读这次改动真正涉及的文件。本文将带你全面了解这个潜力新星。
截至收录：
code-review-graph stars数：31519
code-review-graph forks数：2864
code-review-graph项目目录截图
code-review-graph项目核心亮点
🌟 亮点一：爆炸半径分析，只读该读的文件：当某个文件发生变化时，图谱会沿着调用、依赖和测试边反向追踪所有可能受影响的调用方、依赖方与测试用例。AI 助手只需读取这些文件，而不是扫描整个项目。这解决的是 AI 编程中最昂贵的浪费——把整个语料库塞进上下文窗口。
⚡ 亮点二：增量更新，快到几乎无感：编辑器钩子、Git pre-commit 钩子和 watch 模式都会触发增量更新。更新过程会先 diff 出变更文件，再通过 import 与调用边找到它们的依赖者，最后只重新解析 SHA-256 哈希真正变化的文件。在一个约 3000 文件的项目（django）上，两文件编辑走钩子路径重新索引仅需约 2.5 秒，其中约 1.4 秒还是进程启动成本；一次空更新的代价就只有这点启动开销。
📉 亮点三：benchmark 可复现的 token 削减：项目通过统一的评测运行器对 6 个开源仓库（13 个 commit）做对比，整库语料基线与图谱查询之间的每问题 token 削减中位数约为 63 倍（区间 35x–358x，358x 的极值来自最大语料 fastapi，并非典型结果）。所有配置都固定了上游 SHA，Leiden 聚类使用固定随机种子，CPU 上的 embedding 也是确定性的——这意味着在不同机器上跑两遍，会得到相同的数字。复现脚本公开在 docs/REPRODUCING.md。
🔌 亮点四：一条命令接入 16+ 种 AI 编程工具：code-review-graph install 会自动探测你本机安装的 AI 编程工具，为每一个写入 MCP server 配置，在平台支持时安装钩子与技能，并把图谱使用说明追加到该平台的规则文件中。支持 codex、claude-code、cursor、windsurf、zed、continue、opencode、antigravity、gemini-cli、qwen、kiro、qoder、copilot、copilot-cli、codebuddy、hermes 等平台，也可以用 --platform 单独配置某一个。卸载同样克制：uninstall 只清理 CRG 自己创建的文件与条目，不会碰其他 MCP server、钩子、技能和 JSONC 注释。
🔒 亮点五：本地优先，数据不出机器：整个图谱就是 .code-review-graph/ 目录下的一个 SQLite 文件，不需要外部数据库，也没有任何遥测。云端 embedding 是可选项而非默认项；CI 场景下图谱同样在你的 runner 上构建和查询，源码不会被发送到第三方服务。
🧩 亮点六：语言与框架覆盖广，还能自己扩：解析器基于 Tree-sitter，覆盖 Python、JavaScript/TypeScript/TSX、Go、Rust、Java、C/C++、C#、VB.NET、Ruby、Kotlin、Swift、PHP、Scala、Solidity、Dart、R、Perl、Lua/Luau、Objective-C、Shell、Elixir、Zig、PowerShell、Julia、ReScript、GDScript、Nix、Verilog/SystemVerilog、SQL、Terraform/OpenTofu、Ansible YAML、Vue/Svelte SFC、Astro 以及 Jupyter / Databricks notebook 等。PHP 还会有 Composer PSR-4 解析、Blade 模板引用和 Laravel Route / Eloquent 边；Java 则有 Spring 依赖注入调用解析、WebFlux 路由、事件发布-监听边和 Temporal 工作流边。如果还用不上，可以在 .code-review-graph/languages.toml 里声明式地添加新语言，无需 fork。
🤖 亮点七：CI 里的风险评分 PR 审查：同一套分析可以作为 composite GitHub Action 运行，在 PR 上留下一条”粘性评论”（sticky comment），列出风险评分函数、受影响的执行流和测试缺口，并在每次 push 时原地更新。可选的 fail-on-risk 输入还能把它变成合并门禁。
code-review-graph快速开始
只需几步，你就能在本地跑起 code-review-graph：
- 安装（需要 Python 3.10+）：
bash
# 选择一种主要安装方式
$ pip install code-review-graph
# 或者
$ pipx install code-review-graph - 自动配置已安装的 AI 编程工具：
bash
$ code-review-graph install
# 只配置某一个平台
$ code-review-graph install --platform cursor
$ code-review-graph install --platform codebuddy
这条命令会探测本机已安装的 AI 编程工具、为每个写入 MCP server 条目、在平台支持时安装钩子与技能，并向平台规则文件追加图谱说明。MCP 条目会根据环境智能选择poetry run、uv run、uvx code-review-graph serve或当前 Python 解释器。配置完成后记得重启编辑器或工具。 - 构建代码库图谱：
bash
$ code-review-graph build
构建时间随仓库规模增长，实测一个约 3000 文件仓库的冷构建约需 40 秒。此后 hooks 与 watch 模式会持续维护图谱的新鲜度。 - 在你的 AI 助手里提第一个问题：
text
Build the code review graph for this project
之后就可以让助手基于图谱做审查、影响面分析或架构梳理了。
想要撤回改动也很简单，并且默认是安全的：
$ code-review-graph uninstall --dry-run # 只预览
$ code-review-graph uninstall # 预览、确认、执行
$ code-review-graph uninstall --yes # 不再询问直接执行
$ code-review-graph uninstall --all-repos # 同时清理所有已注册仓库
$ code-review-graph uninstall --keep-data # 移除集成，保留图谱数据库
共享配置文件采用原子替换写入，因此一次失败的写入会保留原文件不变。
code-review-graph应用场景
场景一：AI 辅助的 PR 代码审查：这是最核心的场景。开发者在提交 PR 后，助手不再需要通读仓库，而是先查询图谱得到”这次改动可能影响哪些函数、类和文件”，然后只针对这个切片做审查。对于大型仓库，这直接把每次问答的上下文从几十万 token 压缩到几千 token 量级。
场景二：CI 中的自动化风险门禁：在 .github/workflows 里引用 tirth8205/code-review-graph@v2.3.8，每次 PR 自动生成风险评分评论。团队可以把 fail-on-risk 打开，让高风险改动无法直接合并。这个仓库自身就在 pr-review.yml 里跑着同一套流程。
场景三：大型代码库的架构理解与新人上手：图谱自带基于 Leiden 聚类的社区检测、架构概览图与耦合告警，还能生成 Markdown Wiki。新人可以用它快速搞清”这个模块的入口在哪里、谁在调用谁、哪些是枢纽节点（hub）和瓶颈（bridge）”。
场景四：重构与死代码清理：内置重命名预览、框架感知的死代码检测和社区驱动的重构建议；surprise scoring 还能揭示跨社区、跨语言、边缘到枢纽的”意外耦合”，帮助发现隐藏的架构问题。
场景五：多仓库统一检索：通过多仓库注册表可以把多个仓库登记进来并在它们之间搜索；crg-daemon 则以子进程方式同时监视多个仓库，带健康检查与自动重启。
补充说明：项目也坦率列出了自己的边界——它更适合小仓库之外的场景。对于单文件小改动，图谱上下文的开销可能超过直接读文件；关键词搜索的排序仍有改进空间；JS 与 Go 的流程检测不如 Python 和 PHP/Laravel 成熟；影响分析偏保守，在大型依赖图上会有误报。官方 FAQ 里还给出了它与 LSP、RAG/embedding、grep/agentic search、Serena、codegraph、claude-context、repomix 的对比，以及”什么时候不该用它”的说明。
code-review-graph链接
- GitHub 仓库：https://github.com/tirth8205/code-review-graph
- 官方网站：https://code-review-graph.com
- 快速体验：
bash
pip install code-review-graph && code-review-graph install
tirth8205 / code-review-graph项目地址：https://github.com/tirth8205/code-review-graph
本文地址：https://www.tgoos.com/46503
