02 - code-review-graph：Claude Code 本地代码知识图谱

GitHub: tirth8205/code-review-graph（16.9k stars） License: MIT 语言: Python 3.10+ 核心定位: 给 Claude Code 等 AI 编码工具加一份持久化代码结构图，让 AI 只读真正相关的文件 —— PR 评审 token 减少 6.8 倍，日常编码任务最高减少 49 倍。

1. 项目背景

1.1 痛点

AI 编码工具（Claude Code / Codex / Cursor）在每次任务中重新扫描整个代码库：

一次 PR Review 平均 token 消耗：几万到几十万
大仓库（Monorepo）上几乎跑不动
模型靠 Grep + Read 的盲读，遗漏依赖关系

1.2 作者思路

既然代码本质上是图（函数互相调用、类互相继承、文件互相 import），那就把它建出来、缓存住、按需查。每次 LLM 任务只需要图的"局部子图"。

1.3 实测收益（README 官方基准）

在 6 个真实开源仓库（express、fastapi、flask、gin、httpx、nextjs）上做了 PR Review benchmark：

Repo	Naive Tokens	Graph Tokens	减少倍数
express	693	983	0.7×
fastapi	4,944	614	8.1×
flask	44,751	4,252	9.1×
gin	21,972	1,153	16.4×
httpx	12,044	1,728	6.9×
nextjs	9,882	1,249	8.0×
平均			8.2×

影响分析（impact）召回 = 100%（不会漏掉真正被影响的文件）
平均 F1 = 0.54（精度偏保守，宁多勿少）

2. 核心概览

维度	实现
索引方式	Tree-sitter AST 解析 → 节点（函数/类/导入）+ 边（调用/继承/测试覆盖）
存储	本地 SQLite 文件，位于 `.code-review-graph/`
增量更新	文件保存 / git commit 触发 hook，仅重解析变更文件（2,900 文件 <2s 完成）
集成	MCP Server（28 工具 + 5 prompt 模板） + CLI + 编辑器 hooks
多仓库	`crg-daemon` 后台守护进程，支持注册多个仓库自动监听
嵌入（可选）	sentence-transformers / Google Gemini / MiniMax / OpenAI 兼容端点

2.1 支持的语言（23 种 + Notebook）

Python、TypeScript/TSX、JavaScript、Vue、Svelte、Go、Rust、Java、Scala、C#、Ruby、Kotlin、Swift、PHP、Solidity、C/C++、Dart、R、Perl、Lua、Zig、PowerShell、Julia，外加 Jupyter/Databricks Notebook（.ipynb，多语言单元格）和 Perl XS 文件（.xs）。

2.2 支持的 AI 编码平台

code-review-graph install 自动检测并配置：

Claude Code
Codex
Cursor
Windsurf
Zed
Continue
OpenCode
Antigravity
Qwen
Qoder
Kiro

3. 实现原理

3.1 整体架构

┌──────────────────────────────────────────────┐
│              你的代码仓库                       │
└──────────────────┬───────────────────────────┘
                   │ git ls-files / 文件遍历
                   ▼
┌──────────────────────────────────────────────┐
│  Tree-sitter Parser（23 种语言 grammar）       │
│  - 抽取 FUNCTION / CLASS / IMPORT / CALL_SITE │
└──────────────────┬───────────────────────────┘
                   │ 节点 + 边
                   ▼
┌──────────────────────────────────────────────┐
│  Graph Builder                                │
│  - 调用关系                                    │
│  - 继承关系                                    │
│  - 测试覆盖关系                                 │
│  - 边置信度评分（EXTRACTED/INFERRED/AMBIGUOUS）│
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  本地 SQLite + FTS5（.code-review-graph/）     │
│  + 可选向量索引（embeddings）                  │
└──────────────────┬───────────────────────────┘
                   │ MCP / CLI
                   ▼
┌──────────────────────────────────────────────┐
│  AI Coding Agent (Claude Code / Codex / …)   │
└──────────────────────────────────────────────┘

3.2 关键机制

a) Blast Radius（爆炸半径）

文件 X 改了一行，AI 需要读哪些其他文件？

1. 在图中定位 X 的节点 N
2. BFS 出 N 的所有"上游"（caller / dependent）
3. 同时找出覆盖 N 的所有 test 节点
4. 把"上游 + 测试"作为爆炸半径
5. 把这些节点对应的源代码片段（不一定是整文件）打包给 AI

控制参数：

CRG_MAX_IMPACT_NODES（默认 500）：节点数上限
CRG_MAX_IMPACT_DEPTH（默认 2）：搜索深度

b) 增量更新 < 2 秒

git hook / file save 触发
  ↓
对比变更文件的 SHA-256 vs 上次入库的 SHA-256
  ↓
仅重新 Tree-sitter 解析变更文件
  ↓
更新这些文件涉及的节点和边
  ↓
其他节点保持不变

2,900 文件项目实测 <2s 完成。

c) 社区检测 + 中心度

Leiden 算法：把图按"内部连接紧密"切成 community，自动识别功能模块
Betweenness Centrality：找出"桥"节点（连接两个社区的关键），这种节点改动风险最高
Hub Detection：找出被调用次数最多的节点（架构热点）
Surprise Detection：检测"跨社区跨语言"等出乎意料的耦合

d) Token 优化策略

每次 AI 提问，先调用 get_minimal_context_tool（~100 token）拿到一个超紧凑的项目摘要，再由 LLM 决定是否需要进一步调用 get_review_context_tool / query_graph_tool。这样大部分简单查询不会读源码。

e) 知识缺口分析

get_knowledge_gaps_tool 自动识别：

孤岛节点：没有任何边的孤立函数（可能是死代码）
未测试的热点：被调用很多但没测试覆盖
稀薄社区：内部连接稀疏的伪模块
结构性弱点：单点故障的桥节点

f) 边置信度（Edge Confidence）

每条边有三档置信度 + 浮点分数：

EXTRACTED：直接从 AST 抽出（确定，如 import a from "./b"）
INFERRED：根据规则推断（较确定，如同名方法调用）
AMBIGUOUS：可能存在但不确定（如反射、动态调用）

这让 AI 在做"重命名"等高风险操作时，对低置信度边特别小心。

4. 完整使用步骤

4.1 环境要求

Python 3.10+
推荐安装 uv 以使用 uvx 启动 MCP

4.2 安装

bash

pip install code-review-graph
# 或
pipx install code-review-graph
# 或（推荐，无需占用 pip 全局）
uv tool install code-review-graph

4.3 一键配置所有 AI 平台

bash

code-review-graph install

该命令会：

自动检测本机已安装的 AI 工具（Claude Code、Codex、Cursor 等）
对每个工具写入正确的 MCP 配置文件
注入 graph-aware 的指令到平台规则文件

如果只想配置某个平台：

bash

code-review-graph install --platform claude-code
code-review-graph install --platform codex
code-review-graph install --platform cursor
code-review-graph install --platform kiro

⚠️ 重要：装完后重启编辑器，MCP 配置才会生效。

4.4 构建图谱

进入你的项目根目录：

bash

cd /path/to/your/project
code-review-graph build

或者直接在 Claude Code 里说：

Build the code review graph for this project

500 文件项目：~10 秒
之后每次文件保存 / git commit 都会自动增量更新

4.5 查看状态 / 可视化

bash

code-review-graph status            # 节点数 / 边数 / 健康度
code-review-graph visualize         # 生成 D3.js 交互式 HTML（用浏览器打开）
code-review-graph visualize --format graphml   # 导出到 Gephi / yEd
code-review-graph visualize --format svg
code-review-graph visualize --format obsidian  # 输出 Obsidian vault
code-review-graph visualize --format cypher    # 输出 Neo4j Cypher
code-review-graph wiki              # 基于 community 生成 markdown wiki

4.6 在 Claude Code 中使用

4.6.1 三个 Slash 命令

命令	作用
`/code-review-graph:build-graph`	构建或重建图
`/code-review-graph:review-delta`	审查最近一次 commit 的变更
`/code-review-graph:review-pr`	完整 PR 评审（带爆炸半径分析）

4.6.2 自然语言

直接问 Claude，它会自动调用 28 个 MCP 工具中的合适项：

"改了 src/auth/login.ts 会影响什么？"
→ 自动调 get_impact_radius_tool

"项目里有哪些核心架构热点？"
→ 自动调 get_hub_nodes_tool

"找一下处理支付的代码"
→ 自动调 semantic_search_nodes_tool

"这个 PR 安全吗？"
→ 自动调 detect_changes_tool + get_review_context_tool

4.7 多仓库守护进程（crg-daemon）

如果编辑器（Cursor / OpenCode）不支持 hooks，或者想在多个项目间共享图：

bash

# 注册要监听的仓库
crg-daemon add ~/project-a --alias proj-a
crg-daemon add ~/project-b

# 启动守护进程
crg-daemon start

# 查看状态
crg-daemon status
crg-daemon logs --repo proj-a -f

# 停止
crg-daemon stop

配置文件：~/.code-review-graph/watch.toml：

toml

[[repos]]
path = "/home/user/project-a"
alias = "proj-a"

[[repos]]
path = "/home/user/project-b"
alias = "project-b"

守护进程每 30 秒做一次健康检查，自动重启挂掉的 watcher。

4.8 忽略文件

在项目根目录创建 .code-review-graphignore：

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

Git 仓库下默认只索引 git ls-files 列出的文件，所以 gitignored 的文件自动跳过；.code-review-graphignore 用于额外排除 git 跟踪的文件。

5. MCP 工具完整列表（28 项）

工具	用途
`build_or_update_graph_tool`	构建或增量更新图
`get_minimal_context_tool`	超紧凑上下文（~100 tokens），优先调用
`get_impact_radius_tool`	变更文件的爆炸半径
`get_review_context_tool`	Token 优化的评审上下文
`query_graph_tool`	callers / callees / tests / imports / inheritance
`traverse_graph_tool`	BFS/DFS 自由探索，可配置深度和 token 预算
`semantic_search_nodes_tool`	按名字或语义找代码实体
`embed_graph_tool`	计算向量嵌入
`list_graph_stats_tool`	图大小和健康度
`get_docs_section_tool`	获取文档片段
`find_large_functions_tool`	找出超过行数阈值的函数/类
`list_flows_tool`	列出关键执行流（按重要度排序）
`get_flow_tool`	单个执行流详情
`get_affected_flows_tool`	受变更影响的流
`list_communities_tool`	列出检测到的代码社区
`get_community_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`	基于社区生成 markdown wiki
`get_wiki_page_tool`	获取特定 wiki 页
`list_repos_tool`	列出已注册仓库
`cross_repo_search_tool`	跨所有注册仓库搜索

5.1 5 个 MCP Prompt 模板

模板	触发场景
`review_changes`	审查变更
`architecture_map`	生成架构图
`debug_issue`	调试问题
`onboard_developer`	新人引入
`pre_merge_check`	合并前检查

5.2 工具裁剪（Token 受限场景）

CRG 默认开 28 个工具，可在 MCP 配置里只暴露子集：

json

{
  "mcpServers": {
    "code-review-graph": {
      "command": "code-review-graph",
      "args": [
        "serve",
        "--tools",
        "query_graph_tool,semantic_search_nodes_tool,detect_changes_tool,get_review_context_tool"
      ]
    }
  }
}

或环境变量：

bash

CRG_TOOLS=query_graph_tool,semantic_search_nodes_tool code-review-graph serve

6. 配置项

6.1 可选依赖组

bash

pip install code-review-graph[embeddings]         # 本地嵌入（sentence-transformers）
pip install code-review-graph[google-embeddings]  # Google Gemini
pip install code-review-graph[communities]        # 社区检测（igraph）
pip install code-review-graph[eval]               # 评估基准（matplotlib）
pip install code-review-graph[wiki]               # wiki 生成（ollama）
pip install code-review-graph[all]                # 全部

6.2 关键环境变量

变量	默认	说明
`CRG_GIT_TIMEOUT`	30	Git 操作超时（秒）
`CRG_EMBEDDING_MODEL`	`all-MiniLM-L6-v2`	默认嵌入模型
`CRG_MAX_IMPACT_NODES`	500	影响分析节点数上限
`CRG_MAX_IMPACT_DEPTH`	2	影响分析深度
`CRG_MAX_BFS_DEPTH`	15	图遍历最大深度
`GOOGLE_API_KEY`	—	Gemini 嵌入
`MINIMAX_API_KEY`	—	MiniMax 嵌入
`CRG_OPENAI_BASE_URL`	—	OpenAI 兼容端点（vLLM/LiteLLM/LocalAI/Ollama OpenAI 模式都行）
`CRG_OPENAI_API_KEY`	—	API key
`CRG_OPENAI_MODEL`	—	模型名
`CRG_OPENAI_DIMENSION`	—	嵌入维度（v3 模型支持降维）
`CRG_OPENAI_BATCH_SIZE`	—	嵌入 batch（Qwen text-embedding-v4 限 10）

6.3 嵌入路由（推荐 OpenAI 兼容）

bash

export CRG_OPENAI_BASE_URL=http://127.0.0.1:3000/v1   # 或 https://api.openai.com/v1
export CRG_OPENAI_API_KEY=sk-...
export CRG_OPENAI_MODEL=text-embedding-3-small
export CRG_OPENAI_DIMENSION=1536

模型选择小贴士：避免用 -preview / -beta / -exp 模型（如 google/gemini-embedding-2-preview），它们的权重可能在生命周期内变化，需要全量重嵌。优先用 GA 模型：text-embedding-3-small（OpenAI）、Qwen/Qwen3-Embedding-8B（自建 vLLM）、gemini-embedding-001（原生 Gemini provider）。

code-review-graph 当前只嵌函数签名（~10 tokens/节点），所以 Gemini 2 这类靠"长文本理解"出名的大模型在这里相对小模型的优势并不显著。

7. Windows 用户排坑

如果 Claude Code 报 Invalid JSON: EOF while parsing 或 MCP error -32000: Connection closed：

升级 fastmcp 到 ≥ 3.2.4
不要用 cmd /c 包裹命令
直接调用 .exe，UTF-8 通过 env 注入：

json

"code-review-graph": {
  "command": "C:\\path\\to\\your\\venv\\Scripts\\code-review-graph.exe",
  "args": ["serve", "--repo", "C:\\path\\to\\your\\project"],
  "env": { "PYTHONUTF8": "1" }
}

8. 已知限制

来自官方 benchmark 的诚实自评：

限制	说明
小单文件改动	对 trivial 修改，graph 上下文反而比直接读文件更贵（express 测例 0.7×）
搜索质量（MRR 0.35）	关键词搜索 top-4 命中率可，但排序需提升；express 用 module-pattern 命名时 0 hits
流检测 33% 召回	仅在 Python（fastapi/httpx）这种框架模式明显的项目上识别入口可靠；JS/Go 待改进
精确率 vs 召回率	影响分析故意偏保守（recall 100%，precision 偏低），宁多报勿漏报
函数体未嵌入	当前只嵌函数签名，长函数体的语义搜索效果有限（路线图中）

9. 适用场景

✅ 强推：

中大型项目（500 文件以上）
频繁做 PR Review 的团队
Monorepo（特别是多语言）
需要"改这里影响哪里"分析的场景
23 种语言中的任何一种（特别是 Python/TS/Go/Java）

⚠️ 慎用：

单文件 / 几百行的玩具项目（开销不值得）
高度依赖反射/动态 dispatch 的代码（如 Rails 的 Method missing、Python 的 metaclass）
不能本地存储索引数据的场景

❌ 不适用：

需要"按语义找代码"为主的场景（用 Semble 更合适）
Chromium 级超大仓库（用 BitFun flashgrep 加速 grep 更现实）

10. 参考链接

GitHub: https://github.com/tirth8205/code-review-graph
PyPI: https://pypi.org/project/code-review-graph/
官网: https://code-review-graph.com
Discord: https://discord.gg/3p58KXqGFN
知乎《开源 Claude Code 本地代码知识图谱：code-review-graph 完整上手攻略》

docs

hook

watcher

02 - code-review-graph：Claude Code 本地代码知识图谱 ​

1. 项目背景 ​

1.1 痛点 ​

1.2 作者思路 ​

1.3 实测收益（README 官方基准） ​

2. 核心概览 ​

2.1 支持的语言（23 种 + Notebook） ​

2.2 支持的 AI 编码平台 ​

3. 实现原理 ​

3.1 整体架构 ​

3.2 关键机制 ​

a) Blast Radius（爆炸半径） ​

b) 增量更新 < 2 秒 ​

c) 社区检测 + 中心度 ​

d) Token 优化策略 ​

e) 知识缺口分析 ​

f) 边置信度（Edge Confidence） ​

4. 完整使用步骤 ​

4.1 环境要求 ​

4.2 安装 ​

4.3 一键配置所有 AI 平台 ​

4.4 构建图谱 ​

4.5 查看状态 / 可视化 ​

4.6 在 Claude Code 中使用 ​

4.6.1 三个 Slash 命令 ​

4.6.2 自然语言 ​

4.7 多仓库守护进程（crg-daemon） ​

4.8 忽略文件 ​

5. MCP 工具完整列表（28 项） ​

5.1 5 个 MCP Prompt 模板 ​

5.2 工具裁剪（Token 受限场景） ​

6. 配置项 ​

6.1 可选依赖组 ​

6.2 关键环境变量 ​

6.3 嵌入路由（推荐 OpenAI 兼容） ​

7. Windows 用户排坑 ​

8. 已知限制 ​

9. 适用场景 ​

10. 参考链接 ​

02 - code-review-graph：Claude Code 本地代码知识图谱

1. 项目背景

1.1 痛点

1.2 作者思路

1.3 实测收益（README 官方基准）

2. 核心概览

2.1 支持的语言（23 种 + Notebook）

2.2 支持的 AI 编码平台

3. 实现原理

3.1 整体架构

3.2 关键机制

a) Blast Radius（爆炸半径）

b) 增量更新 < 2 秒

c) 社区检测 + 中心度

d) Token 优化策略

e) 知识缺口分析

f) 边置信度（Edge Confidence）

4. 完整使用步骤

4.1 环境要求

4.2 安装

4.3 一键配置所有 AI 平台

4.4 构建图谱

4.5 查看状态 / 可视化

4.6 在 Claude Code 中使用

4.6.1 三个 Slash 命令

4.6.2 自然语言

4.7 多仓库守护进程（crg-daemon）

4.8 忽略文件

5. MCP 工具完整列表（28 项）

5.1 5 个 MCP Prompt 模板

5.2 工具裁剪（Token 受限场景）

6. 配置项

6.1 可选依赖组

6.2 关键环境变量

6.3 嵌入路由（推荐 OpenAI 兼容）

7. Windows 用户排坑

8. 已知限制

9. 适用场景

10. 参考链接