当 AI 编程助手遇到大型代码仓库时，”大海捞针”式的文件搜索和上下文拼接很快就会达到性能和成本瓶颈。代码图（Code Graph） 技术应运而生——它预先把代码仓库的调用关系、依赖结构、模块边界等信息建模为一个可查询的图结构，让 AI 能够”按图索骥”而不是”全文扫描”。

当前最有代表性的两个解决方案是 CodeGraph（由 Colby McHenry 开发，Node.js 生态）和 Code-Review-Graph（由 Tirth Pandya 开发，Python 生态）。本文基于实际项目中的使用体验，从多个维度进行深度对比，并分享如何在 AI 编程工作流中组合使用它们。

一、基本介绍

CodeGraph

• 开发者：Colby McHenry
• 语言与运行环境：TypeScript / Node.js（自带 Node.js 运行时，无需预装 Node）
• 许可证：MIT 开源
• 核心定位：面向日常编码的轻量语义图工具，强调快速符号定位、调用链追踪和影响分析。
• 支持的 AI 平台：Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro。
• GitHub：colbymchenry/codegraph

Code-Review-Graph

• 开发者：Tirth Pandya
• 语言与运行环境：Python（通过 pip 安装，独立 CLI）
• 许可证：MIT 开源
• 核心定位：面向 Code Review 场景的重型图分析工具，强调影响半径分析、社区检测、执行流追踪和 Token 成本节省量化。
• 支持的 AI 平台：Claude Code、Cline、Windsurf、Copilot、Genkit 等，通过 MCP 协议接入。
• GitHub：tirth8205/code-review-graph

二、安装方法

CodeGraph 安装

# 一条命令完成：安装 + 自动配置所有已检测到的 AI 平台
npx @colbymchenry/codegraph

# 如果只想安装到 PATH（不自动配置 Agent）
npm install -g @colbymchenry/codegraph

安装时会自动检测已安装的 AI 助手（Claude Code、Cursor 等），询问配置范围（全局 or 当前项目），并写入对应的 MCP 配置文件和指令参考文件。

Code-Review-Graph 安装

# 通过 pip 安装
pip install code-review-graph

# 初始化项目
code-review-graph install

# 构建图索引
code-review-graph build

# 启动监听模式（自动更新图）
code-review-graph watch

安装后需要手动配置 MCP 服务器（mcp.json 或 claude_desktop_config.json），然后在项目中先 build 再 watch 维护图索引。

三、技术架构差异

两个工具虽然都基于”代码图”概念，但技术实现和侧重点有本质区别。

四、核心收益对比 — Token 节省与 Benchmark 数据

两个工具最显著的共同价值是大幅减少 AI 编程的 Token 消耗。传统方式下，AI 助手需要执行大量 grep/glob/Read 操作来理解代码——每次探索都产生大量输入 Token。代码图工具提前索引了代码关系，AI 只需查询图即可获知信息，无需反复读取文件。

4.1 没有代码图时发生了什么？

当 AI 助手（如 Claude Code）需要理解一个代码库时，它会：

1. 用 Grep 搜索符号定义
2. 用 Glob 查找相关文件
3. 用 Read 读取多个文件的完整内容
4. 用 Bash(find/grep) 在文件系统中搜索

每个步骤都消耗大量 Token，且随着代码库增大呈指数增长。

4.2 CodeGraph Benchmark

CodeGraph 在 7 个真实世界开源项目（涵盖 7 种编程语言）上进行了严格的基准测试。测试方式：让 Claude Code（headless 模式）回答同一个架构问题，分别对比使用 CodeGraph 和不使用 CodeGraph 的表现。每个测试取 4 次运行的中位数，在 v0.9.4 版本上验证。

平均：节省 35% 费用 · 减少 57% Token · 提速 46% · 减少 71% 工具调用

关键发现：

• 收益随代码库规模放大：VS Code（~1 万文件）Token 减少 78%；Excalidraw（~640 文件）甚至达到 90% Token 减少、96% 工具调用减少——因为 AI 直接从索引回答问题，零文件读取。
• 小项目（Gin 仅 ~110 文件）收益相对较小，因为传统搜索本身成本已很低。
• Tokio（Rust 项目）费用节省最高达 82%，说明图索引对强类型语言的分析优势显著。

4.3 Code-Review-Graph Benchmark

Code-Review-Graph 在其自动化评估套件（code-review-graph eval --all）中对 FastAPI、HTTPX、Express 等仓库进行了测试，结果如下：

平均 Token 减少 6.8 倍，大型代码库场景最高可达 49 倍。

不仅如此，code-review-graph detect-changes --brief 命令会直接输出一个 Token 节省面板，实时对比”全量传递”和”结构化图上下文”的 Token 消耗差异：

┌─────────────────────── Token Savings ────────────────────────┐
│ Full context would be:     12,921 tokens                     │
│ Graph context is:             749 tokens                     │
│ Saved:                   ~94.2% (12,172 tokens)              │
│ Rate: $0.15/M in · $0.60/M out                              │
│ Cost: ~$0.0026 → ~$0.0002 / review                          │
└──────────────────────────────────────────────────────────────┘

上例来自一个中等规模的 PR review：传统方式需 12,921 tokens，使用图上下文仅需 749 tokens——节省了 94.2%。

4.4 收益对比总结

为什么 Code-Review-Graph 的 Token 节省更显著？ 因为它的定位更聚焦：Code Review 本身就是 Token 消耗大户（需要传递完整 diff + 相关上下文），且它的图查询返回的是高度结构化的摘要信息而非源码。而 CodeGraph 的日常编码查询也会返回源码片段供 AI 直接使用，Token 开销略高但交互更直接。

五、工具能力深度对比

这是实际使用中最核心的差异，我用一个对比表来呈现：

六、在 AI 编程中的合理使用策略

6.1 场景化选型

6.2 三步分析法（推荐工作流）

基于实际使用经验，我总结了一套”三步分析法”，将两个工具配合使用效果最佳：

Step 1 — 定位：codegraph_search / semantic_search_nodes
  ↓
Step 2 — 调用链：codegraph_callers/callees（简洁）或 query_graph（详细）
  ↓
Step 3 — 源码验证：codegraph_node（含源码）或 Read 源码

配合原则：

• 日常编码：以 CodeGraph 为主——它的查询轻量、响应快，codegraph_node 可以同时获取签名信息和源码，减少一次 Read 调用。
• Code Review / 重构：以 Code-Review-Graph 为主——它的 detect_changes 带风险评分面板，get_impact_radius 能准确计算波及范围，list_communities 帮你看清模块边界。
• 复杂流程理解：优先使用 Code-Review-Graph 的 list_flows 和 get_flow，自动提取执行路径。
• 宏/条件编译/刚改的代码：回退到传统 Grep/Read——图工具无法覆盖这些场景。

6.3 两个工具可以共存

两者互不冲突，可以同时在 MCP 配置中注册。AI 助手会根据任务场景自动选择调用哪个工具。例如：

# 当 AI 需要理解一个跨模块调用的影响时，可能依次调用：
# 1️⃣ code-review-graph: get_architecture_overview  → 看清模块结构
# 2️⃣ codegraph: codegraph_callers                    → 追踪调用链
# 3️⃣ codegraph: codegraph_node                       → 查看关键函数源码
# 4️⃣ code-review-graph: get_impact_radius             → 评估改动影响

七、使用时的注意事项

1. 图索引需要维护：新改的代码需要约 1 秒同步时间，刚改完的文件建议直接用 Read 而不是查询图。
2. Node.js 项目更适配 CodeGraph：因为它是 TypeScript 原生构建，对 JavaScript/TypeScript 项目的分析准确度最高。
3. Python/C++ 项目更适配 Code-Review-Graph：它的解析器对多语言支持更好，且社区检测功能对大型嵌入式项目（如 Android HAL 层、Linux 驱动）的模块划分非常有用。
4. Token 节省是真实可量化的收益：CodeGraph 在 7 个开源项目上的平均 Token 节省为 57%（费用节省 35%），大型项目可达 78%~90%；Code-Review-Graph 在 Code Review 场景的平均 Token 节省为 6.8x~8.2x（约 85%~88%），大型代码库最高达 49x（约 98%）。这意味着每月 $100 的 AI API 费用可能降至 $35~$65。

八、总结

如果只能选一个，我会建议：日常开发用 CodeGraph，Code Review 和大型项目重构用 Code-Review-Graph。 两者组合使用效果最佳——但不是必须二选一，它们可以共存，互为补充。

延伸阅读：

• CodeGraph GitHub
• Code-Review-Graph GitHub
• MCP 协议规范