学习文学而懒于记诵是不成的，特别是诗。一个高中文科的学生，与其囫囵吞枣或走马观花地读十部诗集，不如仔仔细细地背诵三百首诗。——朱自清

https://github.com/tirth8205/code-review-graph

code-review-graph：别再把令牌烧进整座仓库里了

代码评审这件事，表面上看是在读改动，实际上很多时候是在和“上下文浪费”打架。AI 编码工具一旦接手 review 任务，很容易重新翻箱倒柜，把整个仓库又读一遍。它不是不努力，恰恰是太努力了，于是令牌飞快燃烧，真正重要的部分反而淹没在庞杂背景里。

code-review-graph 想解决的，就是这个问题。

它给自己的开场白相当直接：Stop burning tokens. Start reviewing smarter. 这句话不像一句普通 slogan，更像是一句带点脾气的提醒——别再把上下文预算浪费在大面积重复阅读上了，评审应该更聪明一点。

项目地址：https://github.com/tirth8205/code-review-graph

它是什么：一个本地优先的代码智能图谱

从 description 来看，code-review-graph 的定位非常明确：它是一个面向 MCP 和 CLI 的 local-first code intelligence graph。它会为你的代码库建立一张持久化地图，让 AI 编码工具只读取真正相关的部分，并且在代码评审和大型仓库工作流中给出经过基准测试的上下文缩减结果。

这句话信息量很大，但核心可以收束成三点：

它是 local-first
它构建的是 persistent map of your codebase
它的目标是让 AI read only what matters

这就决定了它不是一个单纯的搜索脚本，也不是一个一次性分析器。它更像是在本地为仓库建立一套长期可查询的结构化记忆，让 AI 在真正需要读代码时，不再像第一次闯进仓库的陌生人。

快速开始非常利落：安装、配置、构图

README 的 Quick Start 干脆得几乎没有多余动作：

1
2
3

pip install code-review-graph                     # or: pipx install code-review-graph
code-review-graph install          # auto-detects and configures all supported platforms
code-review-graph build            # parse your codebase

整个过程像一套三连动作：

安装
自动识别并配置平台
构建图谱

它还特别说明，install 这一步会自动检测你已经安装了哪些 AI 编码工具，然后为每个平台写入对应的 MCP 配置；如果平台支持，还会安装原生 hooks 或 skills，并注入项目级指令。

这种设计很讨喜，因为它没有把“接入多个平台”变成一串繁琐手工步骤，而是把这件事压缩成一个统一入口。你不需要一边查文档一边手配很多碎片，工具会主动把常见接线工作做完。

它也允许你点名平台，而不是一锅端

如果你只想配置某一个平台，README 也给出了明确命令：

code-review-graph install --platform codex       # configure only Codex
code-review-graph install --platform cursor      # configure only Cursor
code-review-graph install --platform claude-code  # configure only Claude Code
code-review-graph install --platform gemini-cli   # configure only Gemini CLI
code-review-graph install --platform kiro         # configure only Kiro
code-review-graph install --platform copilot      # configure only GitHub Copilot (VS Code)
code-review-graph install --platform copilot-cli  # configure only GitHub Copilot CLI
code-review-graph install --platform codebuddy    # configure only CodeBuddy Code

从这份列表里也能看出，这个项目并不是把自己锁在单一 Agent 生态里，而是在努力和多种 AI 编码工具打通。它更像一座本地化基础设施，而不是某个专属前端的附属插件。

拆除也做得很认真：卸载不是“删库跑路”，而是对称撤场

很多工具对安装充满热情，对卸载却语焉不详。code-review-graph 在这方面显得很有工程礼貌。README 直接给出了对称的卸载命令，并强调它只会移除 CRG-owned 的文件和配置项，不会去碰无关的 MCP 服务、hooks、skills 或 JSONC 注释。

code-review-graph uninstall --dry-run    # preview every action; write nothing
code-review-graph uninstall              # preview, ask for confirmation, then apply
code-review-graph uninstall --yes        # apply without prompting
code-review-graph uninstall --all-repos  # also clean every registered repository
code-review-graph uninstall --keep-data  # remove integrations but keep graph databases
code-review-graph uninstall --keep-user-configs --repo .  # clean this project only

这部分读起来很舒服，因为它透露出一种边界感：安装时接得上，撤场时也收得干净，而且不会顺手改动与你无关的内容。

真正的核心：它会把仓库解析成一张结构图

README 在 “How It Works” 中把原理讲得很清楚。你的仓库会先被 Tree-sitter 解析成 AST，然后以图的形式存储下来：

节点包括函数、类、导入等
边包括调用关系、继承关系、测试覆盖等

等到 review 发生时，再根据图去计算和当前问题最相关的上下文。

这就意味着，它并不是在 review 当下才匆忙 grep 一遍项目，而是提前把代码结构整理成了一张图。评审时，AI 不再需要重新摸索整座建筑的房间布局，而是直接拿着地图去找重点。

Blast Radius：它最有代表性的能力之一

README 单独给了一个章节来解释 blast-radius analysis。

当一个文件发生变化时，图谱会追踪：

所有调用者
所有依赖方
所有可能受影响的测试

这部分受影响的范围，就是这次改动的 blast radius。AI 在 review 时只需要读取这些文件，而不是扫遍整个仓库。

这个概念非常形象。它不像传统“看 diff 说话”那样只盯着变化本身，而是会继续追问：这次变化可能向哪里扩散？哪些调用链会被波及？哪些测试应该被重新纳入视野？于是，评审就不再只是“读改动文件”，而变成“读改动影响面”。

增量更新：构图不是一次性大工程，而是能持续保鲜的

README 还特别强调了增量更新能力。当 hooks 或 watch mode 启用后，文件保存和受支持的 commit hook 会触发增量更新。系统会通过 SHA-256 hash 检查找到相关依赖，只重新解析真正需要更新的文件。

它给出的说法很醒目：Incremental updates in < 2 seconds。

这意味着这张图不是构建完就静静落灰的快照，而是一张会随着开发动作持续刷新的地图。它不像一张打印好的旧城区导览图，更像一个实时更新的导航层。

大仓库是它最想发力的战场

README 明确点出：The monorepo problem, solved。

大型 monorepo 正是令牌浪费最疼的地方。因为在这种场景里，真正相关的代码通常只占一小撮，但如果没有结构信息，AI 往往会被迫读进大量噪音。README 用非常具体的说法描述它的作用：27,700+ files excluded from review context, only ~15 files actually read。

这句话非常有冲击力。因为它讲的不是“也许更高效”，而是“我们把巨大背景噪音砍掉了，只留下少量真正相关的上下文”。对于 review 场景来说，这种收敛能力几乎就是决定体验上限的关键。

语言覆盖很广，而且还照顾到了 Jupyter notebooks

README 在 “Broad language coverage + Jupyter notebooks” 一节中说明，它目前的 parser surface 已经覆盖了函数、类、imports、call sites、inheritance 和 test detection，并且在可能的地方使用 Tree-sitter，在需要时使用针对性的 fallback。

它还特别指出，PHP 项目会额外获得：

repository-bounded Composer PSR-4 resolution
Blade template references
Laravel Route / Eloquent semantic edges

前提是源代码中包含显式框架导入、模型继承和接收者证据。这个细节很能说明项目的野心：它不只满足于泛化结构解析，也会在部分语言/框架里尝试更语义化的边。

语言不够？你还可以自己加，而且不需要 fork

这一点非常有吸引力。README 直接给出了自定义语言支持的方式：只需要在 .code-review-graph/ 下放一个 languages.toml，把扩展名映射到 tree_sitter_language_pack 中已打包的 grammar，并提供节点类型配置。

示例是这样的：

[languages.erlang]
extensions = [".erl"]
grammar = "erlang"
function_node_types = ["function_clause"]
class_node_types = ["record_decl"]
import_node_types = ["import_attribute"]
call_node_types = ["call"]

这意味着如果你的仓库语言不在当前覆盖面内，也不一定要等项目本身先支持，或者自己去维护一个 fork。对于一个主打“本地智能图谱”的工具来说，这种扩展方式非常灵活，也很实用。

GitHub Action：同样的分析也能进入 CI

code-review-graph 不是只在本地命令行里工作。README 明确说明，它也可以作为一个 composite GitHub Action 运行，并且依然保持 local-first：知识图谱的构建与查询都发生在 CI runner 上，源码不会被发送到外部服务。

示例 workflow 也给得很清楚：

# .github/workflows/code-review-graph.yml
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tirth8205/code-review-graph@v2.3.6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

这让项目从“本地帮你节省上下文”进一步走向“在团队评审流程里自动提供结构化分析”。评审不再只是个人侧的增强，也可以进入仓库协作环节。

基准测试部分很实诚：不只报亮眼数字，也解释这些数字代表什么

README 的 Benchmarks 部分相当详细，而且最可贵的是，它没有只挑最漂亮的那一个数字喊得震天响。

它明确写道：

headline number 是 6 个仓库上的 median per-question token reduction ~82x
528x 是最大值，是单个最佳案例，不是 headline

这一点非常难得。因为它主动把最容易被营销滥用的数字摆正了位置。

表格里给出的仓库和结果包括：

fastapi：528.4x
code-review-graph：93.0x
gin：91.8x
flask：71.4x
express：40.6x
httpx：38.0x

README 还解释，这里的 whole-corpus baseline 本身就是上界，并不代表真实世界中的 competent agent 会真的每次都通读全仓。也就是说，它没有把 benchmark 包装成某种“现实中的绝对提升值”，而是明确说明了比较对象和上下文。

影响分析准确性也写得很清楚，甚至把局限直接摆出来

在 Impact accuracy 部分，它给出了 0.71 average F1 的结果，并且提醒：recall 1.0 是 graph-derived upper bound，不应被理解成“100% recall”。

这段措辞非常克制，也很有说服力。因为它主动指出了这个评估模式里的“循环上界”问题，而不是把结果直接包装成完美表现。

对应的表格里给出：

平均 F1：0.714
平均 Precision：0.578
Recall：1.000

但 README 明确说明，这个 recall 需要谨慎理解。这样的表述方式，会让人更愿意相信项目是在认真做评估，而不是只做表面宣传。

它还把自己的弱点写在脸上

“Limitations and known weaknesses” 这一节很加分。它列出了几个已知问题：

impact 的 recall 1.0 是 graph-derived 和 circular 的上界
小型单文件改动时，graph context 可能比直接读文件还重
search quality 还有提升空间
flow detection 在 JavaScript 和 Go 上仍需改进
impact analysis 偏保守，因此可能在大依赖图中产生 false positives

这种写法会让整个项目显得很诚实。它没有把图谱分析吹成万能钥匙，而是承认某些场景下它并不总是最划算、最精准或最优雅的选择。

功能表很长，但其实都围绕一个核心问题展开

README 的 Features 表列得非常丰富，不过如果把它们重新归类，会发现很多能力都围绕同一个目标：让 AI 在更少上下文里做出更结构化的理解和判断。

其中包括：

增量更新
多语言与 notebook 支持
blast-radius analysis
auto-update hooks
semantic search
interactive visualization
hub & bridge detection
surprise scoring
knowledge gap analysis
suggested questions
edge confidence
graph traversal
export formats
graph diff
token benchmarking
estimated context savings
memory loop
community detection
architecture overview
risk-scored reviews
refactoring tools
wiki generation
multi-repo registry
multi-repo daemon
MCP prompts
full-text search
local storage
watch mode

这些功能看上去很多，但并不是各自飘散的。它们共同服务于一个图谱：有的负责构建，有的负责更新，有的负责查询，有的负责压缩上下文，有的负责把分析结果变得更可视化、更可解释。

它的本地性并不是一句口号，而是落实在存储与服务方式里

README 明确写到，核心图存储使用的是位于 .code-review-graph/ 中的 SQLite 文件，不需要外部数据库或云服务。

这和它的 description 是完全一致的：local-first 不是宣传词，而是架构选择。图谱就在本地，查询也围绕本地展开。对很多关心隐私、代码出域以及环境可控性的团队来说，这一点会特别有吸引力。

使用方式既照顾 CLI，也照顾 MCP

README 中既给了 CLI 命令，也给了 slash commands，还列出了 30 个 MCP tools。

Slash commands

1
2
3

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

常用 CLI

code-review-graph install
code-review-graph build
code-review-graph update
code-review-graph status
code-review-graph watch
code-review-graph visualize
code-review-graph wiki
code-review-graph detect-changes --brief
code-review-graph serve

这说明它不是执着于某一种入口，而是努力让不同类型的工作流都能接上这张图：有人偏爱命令行，有人依赖编辑器，有人依赖 MCP 接口，有人只想在 CI 里用，它都试图给出对应接法。

Token Savings 面板，把“省下了多少上下文”直接摆到眼前

README 中对 detect-changes --brief 和 update --brief 的说明很直观。两者都会输出同一个紧凑面板，展示图谱相较于直接把 changed files 交给 Agent，节省了多少 token。

示例面板如下：

┌─────────────────────── Token Savings ────────────────────────┐
│ Full context would be:     12,921 tokens                     │
│ Graph context used:           762 tokens                     │
│ Saved:                     12,159 tokens (~94%)              │
│ Breakdown: Functions 244 · Tests 191 · Risk 244 · Other 83   │
└──────────────────────────────────────────────────────────────┘

这是一种很友好的反馈方式。它没有让“上下文节省”停留在模糊感觉里，而是把节省结果具体展示出来。对长期使用者来说，这种即时反馈很容易形成直观认知：图谱到底有没有帮我省东西，一眼就能看出来。

多仓库守护进程：它甚至考虑到了“编辑器不支持 hooks 怎么办”

如果你的编辑器不支持 hooks，或者你只是希望图谱在后台持续更新，README 给出了一个叫 crg-daemon 的多仓库守护进程方案。

快速设置示例：

# 1. Register the repos you want to watch
crg-daemon add ~/project-a --alias proj-a
crg-daemon add ~/project-b

# 2. Start the daemon (runs in the background)
crg-daemon start

# 3. That's it — graphs stay up to date automatically
crg-daemon status                 # check daemon and per-repo watcher status
crg-daemon logs --repo proj-a -f  # tail logs for a specific repo
crg-daemon stop                   # stop daemon and all watcher processes

它还说明底层使用 ~/.code-review-graph/watch.toml 来保存配置。这个细节让整个方案更加落地：不是“将来支持”，而是已经考虑到了后台守护、健康检查、自动重启、多仓库管理这些实际使用问题。

30 个 MCP tools：这张图不是摆设，而是一个可以被反复提问的系统

README 列出的 30 个 MCP tools 很能说明项目的雄心。里面包括：

build_or_update_graph_tool
get_minimal_context_tool
get_impact_radius_tool
get_review_context_tool
query_graph_tool
traverse_graph_tool
semantic_search_nodes_tool
embed_graph_tool
list_graph_stats_tool
get_architecture_overview_tool
detect_changes_tool
get_hub_nodes_tool
get_bridge_nodes_tool
get_knowledge_gaps_tool
get_surprising_connections_tool
get_suggested_questions_tool
refactor_tool
apply_refactor_tool
generate_wiki_tool
cross_repo_search_tool

再加上 5 个 MCP prompts：

review_changes
architecture_map
debug_issue
onboard_developer
pre_merge_check

这说明 code-review-graph 的图谱不是只为“review changed files”设计的，它还想向架构理解、问题排查、开发 onboarding、预合并检查等方向延伸。

VS Code 扩展也在仓库里，占了一个很自然的位置

仓库中的 code-review-graph-vscode/README.md 进一步说明，它还有一套 VS Code 扩展，用来在编辑器里直接查看：

code dependencies
blast radius
review context

扩展提供的功能包括：

Code Graph Explorer
Blast Radius
Review Changes
Find Callers / Callees
Find Tests
Query Graph
Find Large Functions
Interactive Graph
Live Search
Compute Embeddings
Watch Mode
Auto-Update

它要求后端安装 code-review-graph Python CLI，并把本地图数据库存放在 .code-review-graph/graph.db。这和主 README 的设计理念完全一致：图谱仍然是本地的，编辑器只是一个更顺手的观察窗口。

它甚至在 FAQ 里直接回答“这和 LSP、RAG、grep 有什么不同”

README 最后的 FAQ & how it compares 部分非常有意思。虽然正文里没有展开完整细节，但它明确列出了对比方向：

vs LSP / language servers
vs RAG / embeddings
vs grep / agentic search
vs Serena、codegraph、claude-context、repomix
When NOT to use it
Does it phone home?
How do I verify it is working?

尤其是这几个问题本身，就说明作者非常清楚：任何做代码理解基础设施的工具，都绕不开这些比较。它没有逃避，而是把这些问题正面摆出来。

本地性、结构性、持续性，是它最鲜明的三张面孔

如果把 code-review-graph 的 README 通读一遍，会发现这个项目真正迷人的地方，不只是“它能省 token”。那只是最先打到眼睛的一层。

再往里看，会发现它同时具备三种很鲜明的气质：

1. 本地性

图谱构建在本地，存储在本地，CI 运行也强调本地完成。它尽量不把你的代码阅读过程外包给云端黑盒。

2. 结构性

它不是用模糊相似度粗略捞片段，而是先把仓库解析成 AST 和图，再沿着函数、类、调用、继承、测试等边去提取真正相关的上下文。

3. 持续性

它不是一次问答式工具，而是一张会持续更新、可以被反复查询、还能跨 review / debug / architecture / onboarding 多场景复用的长期地图。

它最适合的，不是“帮你看一个文件”，而是帮 AI 少走很多冤枉路

code-review-graph 给人的最大印象，是它非常清楚自己要解决什么问题。它不是试图取代所有代码阅读方式，也没有声称每一种问题都必须上图谱。相反，README 已经坦白地承认：小仓库、微小单文件改动、一次性简单问题，并不一定值得动用这套机制。

但在真正会让 AI 迷路、会让上下文膨胀、会让 review 失焦的大仓库与多跳依赖问题里，它显然是一种很有想象力的做法。

它像是在仓库里提前铺了一层轨道。平时你可能不太注意它，但当 AI 要开始审查改动、查调用链、找受影响测试、理解架构边界时，这层轨道会让整个过程不再像盲走，而像顺着既有线路精准前进。

而这，也许正是它最动人的地方：它不是让 AI 读得更多，而是让 AI 更有可能读对。