今日开源[第35期] Code-Review-Graph

Code-Review-Graph 项目分析报告

分析日期：2026-07-22

一、项目介绍

1.1 项目概述

Code-Review-Graph（CRG）是一个本地优先的代码智能图谱工具，专为 MCP 协议和 AI 编程助手设计。其核心 slogan 是 "Stop burning tokens. Start reviewing smarter."（停止浪费 token，让代码审查更智能）。它通过 Tree-sitter 将代码库解析为持久化的结构化知识图谱，让 AI 编程助手只读取真正需要的内容，在代码审查和大仓库场景下中位数可实现 82 倍 token 缩减，最佳场景可达 528 倍 $TRAE_REF。

1.2 项目信息

项目	详情
项目名称	Code-Review-Graph
项目地址	https://github.com/tirth8205/code-review-graph
项目官网	https://code-review-graph.com
PyPI 包名	`code-review-graph`
作者	Tirth Kanani（GitHub: @tirth8205）
Stars	19,762（截至 2026 年 7 月）
Forks	2,107
当前版本	v2.3.7（2026 年 7 月 18 日发布）
开源协议	MIT License
主要语言	Python 100%
创建时间	2026 年 2 月 26 日
提交数	714 commits
Open Issues	74
仓库标签	ai-coding, claude, code-review, graphrag, knowledge-graph, llm, mcp, tree-sitter, static-analysis

1.3 项目示意图

项目 README 和文档中提供了丰富的可视化资源：

工作原理流程图：展示从代码库 → Tree-sitter AST 解析 → 图谱构建（节点 + 边）→ MCP 查询的完整流程
影响半径分析图（Blast-Radius）：文件变更时追踪所有调用者、依赖项和测试，计算影响范围
增量更新流程图：2900 文件项目重新索引不到 2 秒
Monorepo 场景图：27,700+ 文件中排除无关文件，仅保留约 15 个相关文件
语言覆盖图：展示 35+ 种编程语言的支持状态
基准测试数据图：6 个真实开源仓库的 token 节省对比
Token Savings 面板截图：终端中展示的 token 节省统计
交互式可视化：D3.js 力导向图，支持搜索、社区切换、按度数缩放节点
diagrams/ 目录：9 个 Excalidraw 架构图源文件 + PNG 导出 + 44 秒演示 GIF
多语言 README：支持英文、简体中文、日文、韩文、印地语五种语言

二、项目亮点

2.1 结构化图谱而非 RAG

CRG 的核心理念是结构化知识图谱，而非传统的 RAG（检索增强生成）。差异在于：

维度	RAG（检索增强生成）	CRG（结构图谱）
核心问题	"哪里讨论了 X？"	"谁调用 X？"
技术方案	文本分块 + 向量嵌入	Tree-sitter AST → 节点和边
查询方式	语义相似度搜索	图遍历（调用链、继承链）
准确性	相似度猜测	确定性图查询

RAG 回答"哪里讨论了 X"，而 CRG 回答"谁调用 X"——这是图谱查询，不是相似度猜测 $TRAE_REF。

2.2 影响半径分析（Blast-Radius）

文件变更时，图谱自动追踪所有调用者、依赖项和测试，计算"爆炸半径"。AI 只读取变更影响范围内的文件，而非整个代码库。这使得在 Monorepo 场景下，能从 27,700+ 文件中排除无关文件，仅保留约 15 个相关文件。

2.3 超大规模 Token 缩减

基于 6 个真实开源仓库（13 次提交）的自动化评估基准测试：

仓库	全量 Token	图谱 Token	缩减倍数
fastapi	951,071	2,169	528.4x
code-review-graph	208,821	2,495	93.0x
gin	166,868	1,990	91.8x
flask	125,022	1,986	71.4x
express	135,955	3,465	40.6x
httpx	89,492	2,438	38.0x

中位数 82x 缩减，多跳检索准确率 0.909（11 个任务中 10 个通过）$TRAE_REF。

2.4 增量更新（<2 秒）

通过 SHA-256 哈希校验变更文件，仅重新解析变化部分。2900 文件项目重新索引不到 2 秒，无需每次全量重建。

2.5 35+ 语言支持 + 自定义扩展

语言类别	支持的语言
主流语言	Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, Scala, Dart
脚本语言	R, Perl, Lua/Luau, Shell, PowerShell, Julia
领域语言	Solidity, GDScript, Verilog/SystemVerilog, SQL, Terraform/OpenTofu, Nix
前端框架	Vue/Svelte SFCs, Astro
笔记本	Jupyter/Databricks (.ipynb)
其他	Objective-C, Elixir, Zig, ReScript, VB.NET

支持通过 languages.toml 配置文件添加新语言，无需 fork 项目。

2.6 MCP 原生集成（30 个工具）

通过 FastMCP 框架暴露 30 个 MCP 工具 + 5 个 MCP 提示模板，原生集成到 AI 编程助手（Claude Code、Cursor、Windsurf、Codex、Zed、Continue、OpenCode、Gemini CLI、Qwen、Kiro、GitHub Copilot 等）。一条命令 code-review-graph install 自动检测并配置所有工具。

2.7 核心算法能力

功能	算法/技术	说明
社区检测	Leiden 算法	自动聚类相关代码，大型图自动调节分辨率
Hub/Bridge 检测	度中心性 + 介数中心性	发现架构热点和瓶颈节点
边置信度	三级评分	EXTRACTED / INFERRED / AMBIGUOUS，附带浮点分数
语义搜索	可选嵌入	支持 sentence-transformers、Google Gemini、MiniMax、OpenAI 兼容
风险评分	多维度评估	GitHub Action 集成，本地优先，源码不离开 CI runner

2.8 与同类工具的差异化优势

对比维度	CRG	Serena	claude-context	repomix
技术方案	Tree-sitter AST → 结构图谱	LSP 符号检索	文本分块+向量嵌入	全量打包为单文件
持久化	SQLite 增量更新	语言服务器状态	向量数据库	无（每次重新生成）
外部依赖	核心零外部依赖	每种语言需语言服务器	嵌入服务+向量数据库	Node.js
审查聚焦	是（影响半径、风险评分、测试缺口）	通用编码工具包	搜索为主	上下文打包
Token 节省	中位数 82x	中等	中等	无节省

三、项目运行环境

3.1 基础要求

要求	说明
Python	>= 3.10（支持 3.10/3.11/3.12/3.13）
包管理器	推荐 `uv`（可用 `pip` 或 `pipx` 备选）
操作系统	跨平台（Windows/Linux/macOS）
外部数据库	无（使用 SQLite 本地存储）
构建系统	Hatchling

3.2 核心依赖

依赖	版本	用途
mcp	>= 1.0.0	MCP 协议实现
fastmcp	>= 0.1.0	FastMCP 框架（MCP 服务器）
tree-sitter	>= 0.23.0	代码 AST 解析
tree-sitter-language-pack	>= 0.3.0	35+ 语言语法包
networkx	>= 3.2	图算法（社区检测、中心性分析）
watchdog	>= 4.0.0	文件变更监听

3.3 可选依赖

依赖组	用途
`[embeddings]`	本地向量嵌入（sentence-transformers + numpy）
`[google-embeddings]`	Google Gemini 嵌入
`[communities]`	社区检测（igraph）
`[enrichment]`	Python 调用解析增强（Jedi）
`[eval]`	评估基准测试（matplotlib）
`[wiki]`	LLM 摘要生成 Wiki（ollama）
`[dev]`	开发工具（pytest, pytest-asyncio, ruff）

3.4 安装与运行步骤

# 方式一：uv 安装（推荐）
uv tool install code-review-graph

# 方式二：pip 安装
pip install code-review-graph

# 方式三：pipx 安装
pipx install code-review-graph

# 一键配置所有 AI 编程工具
code-review-graph install

# 首次构建图谱
code-review-graph build

# 启动守护进程（自动监听文件变更）
code-review-graph daemon start

# 启动 MCP 服务器
code-review-graph serve

# 可视化图谱
code-review-graph visualize

install 命令自动检测已安装的 AI 编程工具（Claude Code、Cursor、Windsurf、Codex、Zed、Continue、OpenCode、Gemini CLI、Qwen、GitHub Copilot 等），写入对应的 MCP 配置，并注入图谱感知指令。

3.5 数据存储

存储位置	内容
`.code-review-graph/graph.db`	SQLite 图谱数据库（含 FTS5 全文索引）
`~/.code-review-graph/registry.json`	多仓库注册表
`~/.code-review-graph/watch.toml`	守护进程配置
`.code-review-graphignore`	排除规则（类似 .gitignore）

四、项目代码介绍

4.1 代码架构图

code-review-graph/
├── .github/                          # GitHub Actions（CI/CD、PR Review 工作流）
│   └── workflows/                    # 测试、发布、PR 审查工作流
│
├── code_review_graph/                # ⭐ 核心 Python 包
│   ├── __init__.py                   # 包初始化
│   ├── __main__.py                   # python -m 入口
│   ├── cli.py                        # CLI 命令行接口（67KB，最大模块）
│   ├── parser.py                     # Tree-sitter 解析器（语言支持、AST 提取）
│   ├── graph.py                      # 图谱构建与存储（NetworkX + SQLite）
│   ├── server.py                     # MCP 服务器（FastMCP 框架，30 个工具）
│   ├── analysis.py                   # 图分析（Hub/Bridge/异常检测，13KB）
│   ├── changes.py                    # 变更检测与影响分析（19KB）
│   ├── communities.py                # 社区检测（Leiden 算法，38KB）
│   ├── embeddings.py                 # 向量嵌入（45KB）
│   ├── enrich.py                     # 图增强（9KB）
│   ├── context_savings.py            # Token 节省估算（11KB）
│   ├── custom_languages.py           # 自定义语言支持（11KB）
│   ├── daemon.py                     # 后台守护进程（37KB）
│   ├── daemon_cli.py                 # 守护进程 CLI（9KB）
│   ├── event_resolver.py             # 事件解析器（4KB）
│   ├── config_keys.py                # 配置键常量（1KB）
│   ├── constants.py                  # 全局常量（2KB）
│   │
│   └── eval/                         # 评估基准测试框架
│       ├── configs/                  # 各仓库评估配置（YAML）
│       ├── runner.py                 # 评估执行器
│       └── benchmarks/               # 基准测试脚本
│
├── code-review-graph-vscode/         # VS Code 扩展
├── diagrams/                         # 架构图（Excalidraw 源文件 + PNG）
├── docs/                             # 文档（USAGE, COMMANDS, FAQ, TROUBLESHOOTING 等）
├── evaluate/results/                 # 评估结果数据
├── hooks/                            # 平台钩子（Codex, Claude 等）
├── scripts/                          # 辅助脚本
├── skills/                           # 技能定义（斜杠命令）
├── tests/                            # 测试套件
│   └── fixtures/                     # 测试固件（各语言示例文件）
│
├── pyproject.toml                    # 项目配置与依赖
├── uv.lock                           # 依赖锁定
├── action.yml                        # GitHub Action 定义
├── AGENTS.md / CLAUDE.md / GEMINI.md # AI 助手指令文件
├── CHANGELOG.md                      # 变更日志
├── LICENSE                           # MIT 许可证
└── README.md                         # 多语言项目说明

4.2 系统架构

┌─────────────────────────────────────────────────────┐
│                    AI 编程助手层                       │
│  Claude Code │ Cursor │ Windsurf │ Codex │ Gemini   │
└───────────────────────┬─────────────────────────────┘
                        │ MCP 协议（30 个工具）
┌───────────────────────┴─────────────────────────────┐
│                  MCP 服务层 (server.py)               │
│  FastMCP 框架 │ stdio 传输 │ Streamable HTTP 传输    │
└───────────────────────┬─────────────────────────────┘
                        │
┌───────────────────────┴─────────────────────────────┐
│                   核心引擎层                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ 解析器    │  │  图谱    │  │   分析引擎        │  │
│  │ parser.py │→│ graph.py │→│ analysis.py       │  │
│  │ Tree-     │  │ NetworkX │  │ communities.py   │  │
│  │ sitter    │  │ + SQLite │  │ changes.py       │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
└───────────────────────┬─────────────────────────────┘
                        │
┌───────────────────────┴─────────────────────────────┐
│                   存储与基础设施层                      │
│  SQLite + FTS5 │ 文件监听(watchdog) │ 守护进程(daemon) │
└─────────────────────────────────────────────────────┘

4.3 核心模块介绍

模块	路径	功能
CLI 层	`cli.py` (67KB)	最大模块，包含所有 CLI 子命令：install、build、update、status、watch、visualize、detect-changes、serve、register、eval、daemon
解析器	`parser.py`	Tree-sitter 核心引擎，管理 35+ 种语言语法，定义 `EXTENSION_TO_LANGUAGE`、`_FUNCTION_TYPES`、`_IMPORT_TYPES`、`_CALL_TYPES` 等节点类型
图谱引擎	`graph.py`	基于 NetworkX + SQLite 的图谱存储。节点：函数、类、文件。边：CALLS、IMPORTS_FROM、INHERITS、TESTS_FOR
MCP 服务	`server.py`	基于 FastMCP，暴露 30 个 MCP 工具 + 5 个提示模板，支持 `--tools` 白名单过滤
图分析	`analysis.py` (13KB)	Hub/Bridge 节点检测、异常连接检测、知识缺口分析、执行流追踪
社区检测	`communities.py` (38KB)	Leiden 算法自动聚类，大社区自动递归分割
变更分析	`changes.py` (19KB)	文件变更检测、影响半径计算、风险评分、测试缺口分析
向量嵌入	`embeddings.py` (45KB)	支持本地/OpenAI/Gemini/MiniMax 四种 provider，嵌入函数签名
守护进程	`daemon.py` (37KB)	后台文件监听，自动触发增量更新，支持多仓库注册
Token 估算	`context_savings.py` (11KB)	计算全量读取 vs 图谱精准读取的 token 差值
自定义语言	`custom_languages.py` (11KB)	通过 `languages.toml` 扩展新语言支持

4.4 核心代码解析

4.4.1 Tree-sitter AST 解析流程

# parser.py 中的核心解析逻辑
# 1. 根据文件扩展名选择对应的 Tree-sitter 语法
EXTENSION_TO_LANGUAGE = {
    ".py": "python",
    ".js": "javascript",
    ".ts": "typescript",
    ".go": "go",
    ".rs": "rust",
    # ... 35+ 种语言的映射
}

# 2. 遍历 AST 提取代码实体
# 节点类型分类：
_FUNCTION_TYPES = {"function_definition", "method_definition", ...}
_CLASS_TYPES = {"class_definition", ...}
_IMPORT_TYPES = {"import_statement", "import_from_statement", ...}
_CALL_TYPES = {"call", "method_invocation", ...}

# 3. 构建节点 → 边关系：
# - 函数/方法 → 节点
# - 类 → 节点
# - 调用关系 → CALLS 边
# - 导入关系 → IMPORTS_FROM 边
# - 继承关系 → INHERITS 边
# - 测试覆盖 → TESTS_FOR 边

4.4.2 影响半径分析（Blast-Radius）

# changes.py 中的影响半径计算
# 当文件变更时：
# 1. 解析变更文件，提取变更的函数/类
# 2. 在图谱中查找所有调用者（callers）
# 3. 递归追踪调用链（可配置深度）
# 4. 查找相关测试文件（TESTS_FOR 边）
# 5. 计算"爆炸半径"：所有受影响文件的并集
# 6. 输出最小上下文：仅将这些文件提供给 AI

# 效果示例（Monorepo 场景）：
# 27,700+ 文件 → 仅保留约 15 个相关文件
# 全量 token: 951,071 → 图谱 token: 2,169（528x 缩减）

4.4.3 增量更新机制

# 增量更新流程（daemon.py + graph.py 协作）
# 1. 守护进程监听文件变更（watchdog）
# 2. 对变更文件计算 SHA-256 哈希
# 3. 与图谱中存储的哈希对比，仅处理变化文件
# 4. 移除旧节点和边，重新解析并插入新节点和边
# 5. 2900 文件项目重新索引不到 2 秒

4.4.4 社区检测（Leiden 算法）

# communities.py 中的社区检测
# 使用 Leiden 算法对代码图谱进行社区划分
# 核心流程：
# 1. 构建加权图（边权重反映调用频率）
# 2. Leiden 算法迭代优化模块度
# 3. 大社区自动递归分割（可配置分辨率参数）
# 4. 输出社区结构：每个社区代表一组紧密耦合的代码模块

# 应用场景：
# - 架构分析：了解代码库的模块化程度
# - 新人引导：快速理解代码组织
# - 重构辅助：识别跨社区的高耦合边

4.4.5 MCP 服务器 30 个工具

# server.py 基于 FastMCP 框架暴露的核心工具
# 工具分类：
# 查询类：
#   - get_function_info: 获取函数详情（参数、返回值、调用者）
#   - get_class_info: 获取类详情（方法、属性、继承链）
#   - get_callers: 获取调用者列表
#   - get_callees: 获取被调用者列表
#   - search_symbols: 全文搜索代码实体
#   - semantic_search: 语义搜索（需嵌入模块）

# 分析类：
#   - get_blast_radius: 计算文件变更的影响范围
#   - get_risk_score: 评估变更的风险等级
#   - get_test_gaps: 检测未覆盖的测试缺口
#   - get_communities: 获取社区检测结果
#   - get_hub_nodes: 获取架构热点节点

# 管理类：
#   - list_repositories: 列出已注册的仓库
#   - get_graph_status: 获取图谱构建状态
#   - rebuild_graph: 触发全量重建
#   - update_graph: 触发增量更新

4.4.6 边置信度评分机制

# 三级置信度评分，诚实标注推断 vs 确定边
# EXTRACTED (1.0): 直接从 AST 提取的确定性关系
#   - 静态调用：foo() 调用 bar()
#   - 明确导入：from module import Class
#   - 显式继承：class Child(Parent)

# INFERRED (0.5-0.9): 基于启发式算法推断的关系
#   - 动态分发：通过接口/抽象类的间接调用
#   - 鸭子类型：参数类型推断

# AMBIGUOUS (0.1-0.4): 不确定的关系
#   - 元编程：getattr()、反射等动态调用
#   - 字符串引用：通过字符串名称的调用

五、项目应用与评价

5.1 应用场景

场景	说明
AI 代码审查	最核心场景。PR 审查时只提供变更影响范围内的文件，大幅减少 token 消耗
大型/Monorepo 项目	价值最高。数千到数万文件的仓库中，AI 无法全量读取，图谱精准定位
架构分析	通过社区检测、Hub/Bridge 节点分析理解代码整体架构
新人入职引导	自动生成架构概览、Wiki、执行流，快速了解代码库
重构辅助	死代码检测、重命名影响预览、影响范围分析
CI/CD 集成	GitHub Action 在每次 PR 自动进行风险评分审查
多仓库管理	注册多个仓库，跨仓库搜索代码实体
AI 编程助手增强	30 个 MCP 工具无缝集成到 Claude Code、Cursor、Windsurf 等工作流

5.2 项目优点

Token 节省效果显著：中位数 82x 缩减，最佳场景 528x，直接降低 AI 编程成本。
本地优先、隐私安全：零遥测，SQLite 本地存储，源代码不离开本地（云嵌入为可选）。
安装极简：一条命令 code-review-graph install 自动检测并配置所有 AI 编程工具。
增量更新高效：2900 文件项目重新索引不到 2 秒，无需每次全量重建。
语言覆盖广泛：35+ 种语言，支持通过 languages.toml 自定义扩展。
MCP 生态原生：30 个 MCP 工具无缝集成到 AI 助手工作流，5 种提示模板开箱即用。
核心零外部依赖：不依赖外部数据库或云服务，可完全离线运行。
社区活跃：19.7K Stars，714 次提交，频繁更新（v2.3.7 距创建仅 5 个月）。
边置信度机制：诚实标注推断 vs 确定边，避免误导 AI 决策。
可复现基准测试：固定 SHA 种子，确定性评估，结果可复现验证。

5.3 项目不足

小仓库性价比低：几百个文件以下的项目，AI 直接读取可能更高效；单文件变更时图谱响应可能比原始 diff 更大。
调用解析精度有限：基于 AST 级别和启发式算法，不是编译器级别的。动态分发、元编程、鸭子类型可能产生 INFERRED/AMBIGUOUS 边。
JS/Go 流检测不完善：入口点检测目前主要对 Python 框架模式可靠，JS/Go 的流检测召回率仅 33%。
向量嵌入深度受限：仅嵌入函数签名（约 10 tokens/节点），不嵌入函数体或文档字符串，语义搜索的深度有限。
关键词搜索排名偏弱：MRR（平均倒数排名）仅 0.35，不如专用搜索工具。
一次性查询不划算：首次构建需要约 10 秒（500 文件），但如果只问一次问题，不值得构建。
Python 3.10+ 限制：对老项目有一定环境要求，部分旧系统可能不兼容。
版本依赖较新：tree-sitter >= 0.23.0 等底层依赖版本较新，可能与某些环境冲突。

参考来源

posted @ 2026-07-22 00:50 zhang-yd 阅读(5) 评论(0) 收藏举报

刷新页面返回顶部

zhang-yd

专注技术，追求极致