Code-Review-Graph：AI编程助手的本地代码知识图谱

📅 调研时间: 2026-04-27 

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

📊 版本: v2.3.2 (截至 2026-04-22) 

🔖 开源协议: MIT License

一、项目概述

1.1 核心定位

Code-Review-Graph 是一款专为 AI 编程助手（Claude Code、Cursor、Codex、Kiro 等）设计的本地代码知识图谱工具。它通过 Tree-sitter 解析整个代码库，构建持久化的结构化图谱，让 AI 助手只读取相关的代码部分，从而大幅减少 token 消耗并提升代码理解的准确性。

一句话价值：解决 AI 编程助手"缺乏全局视野"的痛点，让 Claude 从"盲目扫描整个项目"进化为"精准定位关键代码"。

1.2 解决的核心问题

1.3 核心价值主张

🚀 8.2x 平均 Token 减少（相比 naive 全量读取）🎯 100% Recall — 变更影响分析零遗漏⚡ <2秒 增量更新（2900 文件项目）🔒 100% 本地运行 — 零云端依赖

二、技术架构深度解析

2.1 整体架构流程

┌─────────────────────────────────────────────────────────────────┐│                    Code-Review-Graph 架构                        │├─────────────────────────────────────────────────────────────────┤│                                                                 ││  [代码库] ──► [Tree-sitter AST] ──► [图谱构建] ──► [SQLite]      ││     │              │                  │              │         ││     │              ▼                  ▼              │         ││     │        函数/类/导入         节点+边          本地存储     ││     │        调用关系/继承       (SHA-256)                    ││     │                                                           ││     │                    ▼                                      ││     │              [MCP Server]                                 ││     │                    │                                      ││     ▼                    ▼                                      ││  [文件变更] ──► [增量更新] ──► [Blast Radius] ──► [AI 助手]    ││                                                                 │└─────────────────────────────────────────────────────────────────┘

2.2 核心技术组件

2.2.1 Tree-sitter AST 解析引擎

# 解析流程伪代码defparse_file(path):    tree = tree_sitter.parse(file_content)    nodes = extract_nodes(tree)  # 函数、类、导入、调用点    edges = extract_edges(tree)  # 调用、继承、导入关系return Graph(nodes, edges)

支持的节点类型：

• 函数定义 (function_definition)
• 类定义 (class_definition)
• 导入语句 (import_statement)
• 调用点 (call_expression)
• 继承关系 (inheritance)
• 测试检测 (test_detection)

2.2.2 图谱存储结构

.code-review-graph/├── graph.db              # SQLite 数据库├── embeddings/           # 向量嵌入（可选）├── communities.json      # 社区检测结果└── watch.toml          # 多仓库守护配置

节点属性：

• id: SHA-256 哈希
• type: function/class/module/import
• name: 符号名称
• file_path: 文件路径
• line_start, line_end: 行号范围
• signature: 函数签名（用于嵌入）

边类型：

• CALLS: 函数调用
• IMPORTS: 导入依赖
• INHERITS: 类继承
• TESTS: 测试覆盖

2.2.3 MCP (Model Context Protocol) 集成

// MCP 配置示例（自动生成）{"mcpServers":{"code-review-graph":{"command":"uvx","args":["code-review-graph","serve"],"env":{}}}}

28 个 MCP 工具（主要工具）：

2.3 关键算法

2.3.1 Blast-Radius 影响范围分析

defcompute_blast_radius(changed_files):"""    计算变更的"爆炸半径"——受影响的所有代码节点    """    affected = set()for file in changed_files:# 1. 找到该文件中的所有节点        nodes = get_nodes_in_file(file)# 2. 反向追踪所有调用者for node in nodes:            callers = bfs_reverse(node, max_depth=2)            affected.update(callers)# 3. 正向追踪所有被调用者（可选）        callees = bfs_forward(node, max_depth=2)        affected.update(callees)# 4. 找相关测试        tests = find_tests_for(nodes)        affected.update(tests)return affected

参数配置：

• CRG_MAX_IMPACT_NODES: 最大影响节点数（默认 500）
• CRG_MAX_IMPACT_DEPTH: 搜索深度（默认 2）

2.3.2 社区检测 (Leiden 算法)

# 自动识别代码中的"模块"边界communities = leiden_algorithm(graph, resolution=1.0)# 大社区自动分割if community.size > 0.25 * total_nodes:    sub_communities = leiden_split(community)

2.3.3 增量更新机制

defon_file_change(file_path):    old_hash = get_stored_hash(file_path)    new_hash = sha256(read_file(file_path))if old_hash != new_hash:# 只重新解析变更的文件        remove_nodes_for(file_path)        add_nodes(parse_file(file_path))        update_edges(file_path)

三、性能基准数据

3.1 Token 效率对比

⚠️ 注意：Express 显示 <1x 是因为单文件变更在小项目中，图谱元数据可能超过原始文件大小。多文件变更时优势明显。

3.2 Impact 准确性

✅ 关键洞察：100% Recall 意味着零遗漏——宁可多标记一些潜在受影响的文件，也不漏掉任何一个。

3.3 构建性能

四、支持的平台与语言

4.1 支持的 AI 编程平台

┌──────────────┬─────────────┬─────────────────────────────┐│    平台      │  支持状态   │         集成方式            │├──────────────┼─────────────┼─────────────────────────────┤│ Claude Code  │ ✅ 官方支持 │ MCP + 斜杠命令              ││ Cursor       │ ✅ 官方支持 │ MCP 配置自动注入           ││ Codex        │ ✅ 官方支持 │ MCP 集成                   ││ Kiro         │ ✅ 官方支持 │ MCP 集成                   ││ OpenCode     │ ✅ 社区支持 │ PR #366 已合并             ││ VS Code      │ ✅ 插件支持 │ code-review-graph-vscode   ││ Windsurf     │ 🔶 部分    │ 需要 daemon 模式           ││ Cline        │ 🔶 部分    │ 需要 daemon 模式           │└──────────────┴─────────────┴─────────────────────────────┘

4.2 支持的编程语言（23+ 种）

特殊支持：

• Jupyter/Databricks Notebook (.ipynb)：多语言单元格支持（Python, R, SQL）
• Perl XS 文件 (.xs)

五、安装与快速上手

5.1 安装方式

# 方式 1：pip 安装（推荐）pip install code-review-graph# 方式 2：pipx 安装（隔离环境）pipx install code-review-graph# 方式 3：uvx 安装（最快）uvx install code-review-graph

5.2 一键配置

# 自动检测并配置所有支持的平台code-review-graph install# 或指定特定平台code-review-graph install --platform claude-codecode-review-graph install --platform cursorcode-review-graph install --platform codex

自动完成的工作：

1. 检测已安装的 AI 编程工具
2. 写入正确的 MCP 配置
3. 注入图谱感知指令到平台规则
4. 自动判断 uvx 或 pip/pipx 安装方式

5.3 构建图谱

# 进入项目目录cd your-project# 构建图谱code-review-graph build# 查看状态code-review-graph status

5.4 日常使用

# 启动 watch 模式（自动增量更新）code-review-graph watch# 或使用 daemon 模式（多仓库后台守护）crg-daemon add ~/project-a --alias proj-acrg-daemon startcrg-daemon status

六、核心功能详解

6.1 Blast-Radius 影响范围分析

场景：修改了一个核心函数，需要知道哪些地方可能受影响。

# 修改了 auth.py 中的 login() 函数# Code-Review-Graph 自动分析：受影响的调用链：├── api/routes/user.py:45      → login()├── api/routes/admin.py:102     → login()├── services/auth_service.py   → login()└── tests/test_auth.py          → test_login()建议审查的文件（共 15 个）：[完整列表...]

6.2 架构热点识别

# 找出高连接节点（架构热点）code-review-graph hub-nodes输出示例：1. utils/helpers.py::validate_input()    [连接数: 47]2. core/engine.py::process()             [连接数: 32]3. api/base.py::handle_request()         [连接数: 28]

6.3 知识缺口分析

# 识别结构弱点code-review-graph knowledge-gaps输出示例：⚠️ 未测试的热点：  - payment/processor.py::charge()  [被调用 23 次，无测试]⚠️ 孤立节点（可能死代码）：  - legacy/migration.py::old_transform()⚠️ 薄弱社区（<5 个节点）：  - utils/temp/

6.4 可视化与导出

# 生成交互式 HTML 图谱code-review-graph visualize# 导出为各种格式code-review-graph visualize --format graphml   # Gephi/yEdcode-review-graph visualize --format svg      # 静态图code-review-graph visualize --format obsidian # Obsidian 知识库code-review-graph visualize --format cypher   # Neo4j

6.5 Wiki 自动生成

# 从社区结构生成 Wikicode-review-graph wiki生成结构：wiki/├── index.md              # 架构概览├── community-auth.md     # 认证模块├── community-api.md      # API 模块└── community-core.md     # 核心模块

七、进阶配置

7.1 排除路径

# 创建 .code-review-graphignorecat > .code-review-graphignore << 'EOF'generated/***.generated.tsvendor/**node_modules/**__pycache__/***.min.jsEOF

7.2 可选依赖

# 向量嵌入（本地）pip install code-review-graph[embeddings]# Google Gemini 嵌入pip install code-review-graph[google-embeddings]# 社区检测增强pip install code-review-graph[communities]# 全部功能pip install code-review-graph[all]

7.3 环境变量

7.4 OpenAI 兼容嵌入配置

# 支持任何 OpenAI 兼容端点export CRG_OPENAI_BASE_URL=127.0.0.1:3000/v1export CRG_OPENAI_API_KEY=sk-...export CRG_OPENAI_MODEL=text-embedding-3-smallexport CRG_OPENAI_DIMENSION=1536  # 可选，用于降维export CRG_OPENAI_BATCH_SIZE=100  # 批量大小

八、与竞品对比分析

8.1 Code-Review-Graph vs GitNexus vs Graphify

8.2 选择建议

┌────────────────────────────────────────────────────────────┐│                      选择决策树                             │├────────────────────────────────────────────────────────────┤│                                                            ││  你的主要场景是什么？                                        ││  │                                                         ││  ├─ 日常代码审查 + 变更影响分析                               ││  │   └─ 推荐：Code-Review-Graph ✅                          ││  │                                                         ││  ├─ 多种 AI 助手通用 + 企业级部署                             ││  │   └─ 推荐：GitNexus                                      ││  │                                                         ││  └─ 论文与代码关联 + 学术研究                                 ││      └─ 推荐：Graphify                                       ││                                                            │└────────────────────────────────────────────────────────────┘

九、实际应用场景

9.1 场景一：代码审查效率提升

问题：PR 改动了 50 个文件，如何快速判断影响范围？

解决方案：

# 一键生成变更影响报告code-review-graph detect-changes --since HEAD~1输出：📊 变更影响分析报告━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━变更文件: 50受影响节点: 312风险评分: 高 (7/10)🔴 高风险变更：  - core/engine.py::process()  [影响 47 个调用者]🟡 中风险变更：  - utils/validators.py::check()  [影响 23 个调用者]✅ 建议审查顺序：  1. tests/test_engine.py（覆盖核心变更）  2. api/routes/...

9.2 场景二：新人项目上手

问题：刚加入团队，面对 10 万行代码无从下手。

解决方案：

# 生成架构概览code-review-graph wiki# 生成可视化图谱code-review-graph visualize --format obsidian# 询问 Claude Code"请根据图谱，解释这个项目的核心架构"

9.3 场景三：重构风险评估

问题：想重构一个"上帝类"，但不确定影响范围。

解决方案：

# 找出高连接节点code-review-graph hub-nodes# 分析特定节点的依赖code-review-graph query --node "GodClass" --callers --depth 3

十、限制与已知问题

10.1 当前限制

1. 小项目单文件变更：图谱元数据可能超过原始文件大小
2. 搜索质量：MRR 0.35，关键词搜索排序需改进
3. Flow Detection：仅 Python 项目入口点检测可靠（33% recall）
4. 精度 vs 召回权衡：影响分析保守，可能存在误报

10.2 不适用场景

• 纯静态资源项目（无代码）
• 高度混淆的代码（压缩后难以解析）
• 超大型 monorepo（>100 万行可能需要分批处理）

十一、社区与生态

11.1 项目活跃度

GitHub 统计 (截至 2026-04-27)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━⭐ Stars:        持续增长中🔀 Forks:        活跃📋 Issues:        响应及时🔁 PRs:          社区活跃📦 Releases:      v2.3.2 (2026-04-22)

11.2 资源链接

十二、总结与建议

12.1 核心价值

1. Token 效率革命：8.2x 平均 token 减少，直接降低 API 成本
2. 零遗漏变更追踪：100% recall 确保审查完整性
3. 本地优先架构：100% 本地运行，代码不出域
4. 一键部署体验：pip install + install 即可完成配置

12.2 适用人群

12.3 最佳实践建议

1. 首次使用：在项目根目录运行 build，等待初始构建完成
2. 日常开发：开启 watch 模式，保持图谱实时更新
3. 代码审查前：运行 detect-changes 获取影响分析报告
4. 重构前：使用 hub-nodes 和 bridge-nodes 识别架构瓶颈
5. 新人入职：生成 Wiki 和可视化图谱作为入门材料

12.4 未来展望

随着 AI 编程助手的普及，代码知识图谱将成为基础设施。Code-Review-Graph 代表了这一趋势的前沿实践：

• 从被动查询到主动理解：AI 不再盲目扫描，而是"理解"代码结构
• 从单文件到全局视野：跨越文件边界的语义关联
• 从瞬时到持久：知识图谱随项目演进，而非每次重建

附录：快速参考命令

# 安装pip install code-review-graph# 配置（自动检测平台）code-review-graph install# 构建/更新图谱code-review-graph buildcode-review-graph update# 查看状态code-review-graph status# 监控文件变更code-review-graph watch# 可视化code-review-graph visualizecode-review-graph visualize --format graphmlcode-review-graph visualize --format obsidian# 分析命令code-review-graph detect-changescode-review-graph wiki# 多仓库守护crg-daemon add ~/project-a --alias proj-acrg-daemon startcrg-daemon statuscrg-daemon stop# MCP 服务器code-review-graph serve