code-review-graph

停止浪费 token。开始更智能地审查。

AI 编码工具在每项任务中都会重读你的整个代码库。`code-review-graph` 解决了这个问题。它使用 [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) 构建代码的结构图，增量跟踪更改，并通过 [MCP](https://modelcontextprotocol.io/) 为你的 AI 助手提供精确的上下文，使其只读取相关内容。

## 快速开始 ``` pip install code-review-graph # or: pipx install code-review-graph code-review-graph install # auto-detects and configures all supported platforms code-review-graph build # parse your codebase ``` 一条命令即可完成所有设置。`install` 会检测你拥有的 AI 编码工具，为每个工具写入正确的 MCP 配置，并将感知图的指令注入到你的平台规则中。它会自动检测你是通过 `uvx` 还是 `pip`/`pipx` 安装的，并生成相应的配置。安装后请重启你的编辑器/工具。

要针对特定平台： ``` code-review-graph install --platform codex # configure only Codex code-review-graph install --platform cursor # configure only Cursor code-review-graph install --platform claude-code # configure only Claude Code ``` 需要 Python 3.10+。为了获得最佳体验，请安装 [uv](https://docs.astral.sh/uv/)（如果可用，MCP 配置将使用 `uvx`，否则直接回退到 `code-review-graph` 命令）。 然后打开你的项目并询问你的 AI 助手： ``` Build the code review graph for this project ``` 对于包含 500 个文件的项目，初始构建大约需要 10 秒。之后，图会在每次文件编辑和 git 提交时自动更新。 ## 工作原理

你的仓库会被 Tree-sitter 解析为 AST，并存储为节点（函数、类、导入）和边（调用、继承、测试覆盖）组成的图，然后在审查时进行查询，以计算 AI 助手需要读取的最小文件集。

### 影响范围分析 当文件发生更改时，图会追踪每一个可能受到影响的调用者、依赖项和测试。这就是更改的“影响范围”。你的 AI 只读取这些文件，而不是扫描整个项目。

### 2 秒内的增量更新 在每次 git 提交或文件保存时，会触发一个钩子。图会对更改的文件进行 diff，通过 SHA-256 哈希检查找到它们的依赖项，并仅重新解析更改的内容。一个包含 2,900 个文件的项目在 2 秒内即可完成重新索引。

### 解决 monorepo 问题 大型 monorepo 是 token 浪费最严重的地方。图可以过滤掉噪音——从审查上下文中排除了 27,700 多个文件，实际只读取约 15 个文件。

### 支持 19 种语言 + Jupyter notebooks

通过 Tree-sitter 语法全面支持每种语言的函数、类、导入、调用点、继承和测试检测。此外，还支持 Jupyter/Databricks notebook 解析（`.ipynb`），包括多语言 cell 支持（Python、R、SQL），以及 Perl XS 文件（`.xs`）。 ## 基准测试

所有数据均来自针对 6 个真实开源仓库（共 13 次提交）的自动化评估运行程序。使用 `code-review-graph eval --all` 复现。原始数据位于 [`evaluate/reports/summary.md`](evaluate/reports/summary.md)。

Token 效率：平均减少 8.2 倍（naive vs graph）

图用覆盖影响范围、依赖链和测试覆盖缺口的紧凑结构上下文，替代了读取整个源文件。 | Repo | Commits | Avg Naive Tokens | Avg Graph Tokens | Reduction | |------|--------:|-----------------:|----------------:|----------:| | express | 2 | 693 | 983 | 0.7x | | fastapi | 2 | 4,944 | 614 | 8.1x | | flask | 2 | 44,751 | 4,252 | 9.1x | | gin | 3 | 21,972 | 1,153 | 16.4x | | httpx | 2 | 12,044 | 1,728 | 6.9x | | nextjs | 2 | 9,882 | 1,249 | 8.0x | | **Average** | **13** | | | **8.2x** | **为什么 express 显示 <1x：** 对于小包中的单文件更改，图上下文（元数据、边、审查指导）可能会超过原始文件大小。图方法在多文件更改时更有优势，因为它可以修剪无关代码。

影响准确性：100% 召回率，0.54 平均 F1 值

影响范围分析绝不会漏掉实际受影响的文件（完美召回率）。它在某些情况下会过度预测，这是一种保守的权衡——标记太多文件总比漏掉损坏的依赖项要好。 | Repo | Commits | Avg F1 | Avg Precision | Recall | |------|--------:|-------:|--------------:|-------:| | express | 2 | 0.667 | 0.50 | 1.0 | | fastapi | 2 | 0.584 | 0.42 | 1.0 | | flask | 2 | 0.475 | 0.34 | 1.0 | | gin | 3 | 0.429 | 0.29 | 1.0 | | httpx | 2 | 0.762 | 0.63 | 1.0 | | nextjs | 2 | 0.331 | 0.20 | 1.0 | | **Average** | **13** | **0.54** | **0.38** | **1.0** |

构建性能

| Repo | Files | Nodes | Edges | Flow Detection | Search Latency | |------|------:|------:|------:|---------------:|---------------:| | express | 141 | 1,910 | 17,553 | 106ms | 0.7ms | | fastapi | 1,122 | 6,285 | 27,117 | 128ms | 1.5ms | | flask | 83 | 1,446 | 7,974 | 95ms | 0.7ms | | gin | 99 | 1,286 | 16,762 | 111ms | 0.5ms | | httpx | 60 | 1,253 | 7,896 | 96ms | 0.4ms |

局限性和已知弱点

- **小型单文件更改：** 对于微不足道的编辑，图上下文可能会超过朴素的文件读取（参见上面的 express 结果）。开销是启用多文件分析的结构元数据。 - **搜索质量 (MRR 0.35)：** 关键字搜索在大多数查询的前 4 个结果中能找到正确结果，但排名仍需改进。由于模块模式命名，Express 查询返回 0 个命中。 - **Flow 检测 (33% 召回率)：** 仅在识别出框架模式的 Python 仓库（fastapi、httpx）中可靠检测入口点。JavaScript 和 Go 的 flow 检测需要改进。 - **精确率与召回率的权衡：** 影响分析是刻意保守的。它标记*可能*受影响的文件，这意味着在大型依赖图中会有一些误报。

## 功能 | Feature | Details | |---------|---------| | **增量更新** | 仅重新解析更改的文件。后续更新在 2 秒内完成。 | | **19 种语言 + notebooks** | Python, TypeScript/TSX, JavaScript, Vue, Go, Rust, Java, Scala, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++, Dart, R, Perl, Lua, Jupyter/Databricks (.ipynb) | | **影响范围分析** | 精确显示哪些函数、类和文件受到任何更改的影响 | | **自动更新钩子** | 在每次文件编辑和 git 提交时自动更新图，无需手动干预 | | **语义搜索** | 可选的向量嵌入，支持 sentence-transformers、Google Gemini 或 MiniMax | | **交互式可视化** | D3.js 力导向图，支持边类型切换和搜索 | | **本地存储** | `.code-review-graph/` 中的 SQLite 文件。无外部数据库，无云依赖。 | | **监视模式** | 工作时持续更新图 | | **执行流** | 从入口点追踪调用链，按关键性排序 | | **社区检测** | 通过 Leiden 算法或文件分组聚类相关代码 | | **架构概览** | 自动生成架构图并附带耦合警告 | | **风险评分审查** | `detect_changes` 将 diff 映射到受影响的函数、流和测试缺口 | | **重构工具** | 重命名预览、死代码检测、社区驱动的建议 | | **Wiki 生成** | 从社区结构自动生成 markdown wiki | | **多仓库注册表** | 注册多个仓库，跨所有仓库搜索 | | **MCP 提示** | 5 个工作流模板：review, architecture, debug, onboard, pre-merge | | **全文搜索** | 基于 FTS5 的混合搜索，结合关键字和向量相似性 | ## 用法

斜杠命令

| Command | Description | |---------|-------------| | `/code-review-graph:build-graph` | 构建或重建代码图 | | `/code-review-graph:review-delta` | 审查自上次提交以来的更改 | | `/code-review-graph:review-pr` | 带有影响范围分析的完整 PR 审查 |

CLI 参考

``` code-review-graph install # Auto-detect and configure all platforms code-review-graph install --platform # Target a specific platform code-review-graph build # Parse entire codebase code-review-graph update # Incremental update (changed files only) code-review-graph status # Graph statistics code-review-graph watch # Auto-update on file changes code-review-graph visualize # Generate interactive HTML graph code-review-graph wiki # Generate markdown wiki from communities code-review-graph detect-changes # Risk-scored change impact analysis code-review-graph register # Register repo in multi-repo registry code-review-graph unregister # Remove repo from registry code-review-graph repos # List registered repositories code-review-graph eval # Run evaluation benchmarks code-review-graph serve # Start MCP server ```

22 个 MCP 工具

一旦图构建完成，你的 AI 助手将自动使用这些工具。 | Tool | Description | |------|-------------| | `build_or_update_graph_tool` | 构建或增量更新图 | | `get_impact_radius_tool` | 更改文件的影响范围 | | `get_review_context_tool` | 经过 token 优化的审查上下文，包含结构摘要 | | `query_graph_tool` | 调用者、被调用者、测试、导入、继承查询 | | `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` | 用于代码审查的风险评分变更影响分析 | | `refactor_tool` | 重命名预览、死代码检测、建议 | | `apply_refactor_tool` | 应用之前预览的重构 | | `generate_wiki_tool` | 从社区生成 markdown wiki | | `get_wiki_page_tool` | 检索特定的 wiki 页面 | | `list_repos_tool` | 列出已注册的仓库 | | `cross_repo_search_tool` | 跨所有已注册的仓库搜索 | **MCP 提示**（5 个工作流模板）： `review_changes`, `architecture_map`, `debug_issue`, `onboard_developer`, `pre_merge_check`

配置

要从索引中排除路径，请在仓库根目录下创建一个 `.code-review-graphignore` 文件： ``` generated/** *.generated.ts vendor/** node_modules/** ``` 注意：在 git 仓库中，仅索引被跟踪的文件（`git ls-files`），因此被 git 忽略的文件会自动跳过。使用 `.code-review-graphignore` 来排除被跟踪的文件或在 git 不可用时使用。 可选依赖组： ``` pip install code-review-graph[embeddings] # Local vector embeddings (sentence-transformers) pip install code-review-graph[google-embeddings] # Google Gemini embeddings pip install code-review-graph[communities] # Community detection (igraph) pip install code-review-graph[eval] # Evaluation benchmarks (matplotlib) pip install code-review-graph[wiki] # Wiki generation with LLM summaries (ollama) pip install code-review-graph[all] # All optional dependencies ```

## 贡献 ``` git clone https://github.com/tirth8205/code-review-graph.git cd code-review-graph python3 -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" pytest ```

添加新语言

编辑 `code_review_graph/parser.py`，将你的扩展名添加到 `EXTENSION_TO_LANGUAGE` 中，并在 `_CLASS_TYPES`、`_FUNCTION_TYPES`、`_IMPORT_TYPES` 和 `_CALL_TYPES` 中添加节点类型映射。包含一个测试 fixture 并提交 PR。

## 许可证 MIT。参见 [LICENSE]()。

code-review-graph.com

pip install code-review-graph && code-review-graph install
_{适用于 Codex、Claude Code、Cursor、Windsurf、Zed、Continue、OpenCode 和 Antigravity}

标签：AI编程助手, Claude, Claude Code, CVE检测, IDE插件, MCP, Model Context Protocol, Python, SOC Prime, Token优化, Tree-sitter, 上下文管理, 人工智能, 代码分析, 代码审查, 代码库映射, 凭证管理, 增量更新, 开发工具, 开发者效率, 成本优化, 无后门, 本地知识图谱, 用户模式Hook绕过, 网络调试, 自动化, 语义搜索, 逆向工具