代码审查图谱

项目动机

AI 编程助手在执行代码审查任务时，常常需要反复读取大量代码文件，造成严重的 Token 浪费。code-review-graph 通过为代码库构建结构化图谱，让 AI 只读取真正相关的文件，从而显著降低上下文开销。在 fastapi 等大型项目中，整库读取需约 94.8 万 Token，而基于图谱的查询仅需约 2,653 Token，最高可达 376 倍压缩。

核心特性

• 增量更新：仅重新解析 SHA-256 哈希变化的文件，钩子路径下约 2.5 秒可完成 3,000 文件项目中两文件的改动更新。
• 多语言支持：覆盖 Python、JavaScript/TypeScript、Go、Rust、Java、C/C++、Ruby、Kotlin、Swift 等 30 余种语言，以及 Jupyter 笔记本、PHP Laravel 框架语义边、Terraform 结构等。
• 爆炸半径分析：通过调用、继承、测试覆盖边追踪改动影响范围。
• 语义搜索：支持 sentence-transformers、Google Gemini、OpenAI 兼容端点等多后端向量嵌入。
• 知识图谱分析：包含 Louvain/Leiden 社区检测、枢纽与桥梁识别、惊讶度评分、知识缺口分析等功能。
• 风险评分 PR 审查：以 GitHub Action 形式运行，发布粘性审查评论，可作为合并门槛。
• 自定义语言：无需分叉代码，通过 .code-review-graph/languages.toml 即可添加新语言映射。

技术架构

代码库经 Tree-sitter 解析为 AST，提取函数、类、导入、调用点等节点，构建以节点和边构成的图谱（节点表示实体，边表示调用、继承、测试覆盖等关系），底层存储采用 SQLite 文件。审查时根据图谱计算改动文件的爆炸半径，返回最小必要文件集。

快速开始

pip install code-review-graph                     # 安装
code-review-graph install          # 自动检测并配置所有支持的 AI 平台
code-review-graph build            # 解析代码库

支持的目标平台包括 Codex、Claude Code、Cursor、Windsurf、Zed、Continue、OpenCode、Antigravity、Gemini CLI、Qwen、Qoder、Kiro、GitHub Copilot 等。若需指定单个平台，可使用 --platform <名称> 参数，例如 code-review-graph install --platform cursor。需要 Python 3.10 及以上环境，推荐安装 uv 以便 MCP 配置走 uvx 路径。

卸载命令示例：

code-review-graph uninstall --dry-run    # 预览删除动作，不写盘
code-review-graph uninstall --yes        # 直接执行
code-review-graph uninstall --keep-data  # 移除集成但保留图数据库

关键 CLI 与 MCP 用法

detect-changes --brief 与 update --brief 输出同一 Token 节省面板，区别在于是否先刷新图谱：

┌─────────────────────── Token Savings ────────────────────────┐
│ Full context would be:     12,921 tokens                     │
│ Graph context used:           762 tokens                     │
│ Saved:                     12,159 tokens (~94%)              │
└──────────────────────────────────────────────────────────────┘

可在任一命令后追加 --verify 参数，基于 OpenAI cl100k_base 分词器交叉校验，结果通常在约 1% 误差范围内。MCP 工具 get_impact_radius、get_review_context、detect_changes、get_architecture_overview 的 JSON 响应同样附带 context_savings 元数据。

GitHub Action 配置

# .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 }}

Action 在 CI 环境中完全本地构建与查询图谱，无需将源代码发送至外部服务；可选 fail-on-risk 输入将其转化为合并门槛。

多仓库守护进程

若编辑器不支持钩子（如 Cursor、OpenCode），可使用 crg-daemon 在后台守护多个仓库的图谱更新：

crg-daemon add ~/project-a --alias proj-a    # 注册仓库
crg-daemon start                              # 启动守护进程
crg-daemon status                             # 查看状态

配置文件位于 ~/.code-review-graph/watch.toml，守护进程每 30 秒执行健康检查并自动重启失效的监控进程。

性能基准

测试覆盖 6 个真实开源仓库：中位单问题 Token 压缩约 65 倍（区间 36–376 倍），爆炸半径分析 F1 平均 0.693（精确率偏低以换取高召回，属有意的保守策略）。需要注意的是当前评测中「召回 1.0」基于图谱自身派生的基准，属于理论上界；尚待修复的协同改动模式目前返回 0，不作为引用依据。