wehub/tirth8205--code-review-graph

Fork 0

Files

T

wehub-resource-sync 7a205e19e1

CI / lint (push) Waiting to run

Details

CI / type-check (push) Waiting to run

Details

CI / security (push) Waiting to run

Details

CI / schema-sync (push) Waiting to run

Details

CI / test (3.10) (push) Waiting to run

Details

CI / test (3.11) (push) Waiting to run

Details

CI / test (3.12) (push) Waiting to run

Details

CI / test (3.13) (push) Waiting to run

Details

docs: make Chinese README the default

2026-07-13 10:37:56 +00:00

18 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

code-review-graph

注意： 本翻译对应较早的版本；基准测试数据和平台列表可能落后于英文 README。

不再浪费 token，让代码审查更智能。

English | 简体中文 | 日本語 | 한국어 | हिन्दी

AI 编码工具在审查任务中可能会反复读取代码库的大量内容。code-review-graph 解决了这个问题。它使用 Tree-sitter 构建代码的结构化映射，增量跟踪变更，并通过 MCP 为 AI 助手提供精准的上下文，使其只读取真正需要的内容。

快速开始

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

一条命令完成所有配置。install 会检测你安装了哪些 AI 编码工具，为每个工具写入正确的 MCP 配置，并将图感知指令注入平台规则。它会自动判断你是通过 uvx 还是 pip/pipx 安装的，并生成相应的配置。安装后请重启编辑器或工具。

如需指定特定平台：

code-review-graph install --platform codex       # 仅配置 Codex
code-review-graph install --platform cursor      # 仅配置 Cursor
code-review-graph install --platform claude-code  # 仅配置 Claude Code
code-review-graph install --platform kiro         # 仅配置 Kiro

需要 Python 3.10+。为获得最佳体验，建议安装 uv（如果可用，MCP 配置将使用 uvx，否则直接使用 code-review-graph 命令）。

然后打开项目，向 AI 助手发出指令：

Build the code review graph for this project

首次构建在 500 个文件的项目上大约需要 10 秒。此后，可通过 watch 模式以及支持的平台钩子自动更新图。

工作原理

代码库通过 Tree-sitter 解析为 AST，以节点（函数、类、导入）和边（调用、继承、测试覆盖）的形式存储为图，然后在审查时查询，计算 AI 助手需要读取的最小文件集。

影响半径分析

当文件发生变更时，图会追踪所有可能受影响的调用者、依赖项和测试。这就是变更的"影响半径"。AI 只需读取这些文件，而无需扫描整个项目。

增量更新，不到 2 秒

启用钩子或 watch 模式后，文件保存和受支持的提交钩子会触发增量更新。图对变更文件做差异比较，通过 SHA-256 哈希校验找到相关依赖，仅重新解析变更部分。一个 2,900 文件的项目重新索引不到 2 秒。

解决 monorepo 难题

大型 monorepo 是 token 浪费最严重的场景。图能穿透噪音——排除 27,700+ 个文件，只读取约 15 个文件。

广泛语言覆盖 + Jupyter 笔记本

解析器支持覆盖当前解析面中的函数、类、导入、调用点、继承和测试检测：能用 Tree-sitter 的地方使用 Tree-sitter，需要时使用有针对性的回退解析。支持范围包括 Python、JavaScript/TypeScript/TSX、Go、Rust、Java、C/C++、C#、Ruby、Kotlin、Swift、PHP、Scala、Solidity、Dart、R、Perl、Lua/Luau、Objective-C、shell 脚本、Elixir、Zig、PowerShell、Julia、ReScript、GDScript、Nix、Verilog/SystemVerilog、SQL、Vue/Svelte 单文件组件、按 TypeScript 解析的 Astro 文件、Jupyter/Databricks 笔记本（.ipynb）和 Perl XS 文件（.xs）。

基准测试

所有数据来自针对 6 个真实开源仓库（共 13 次提交）的自动化评估。可通过 code-review-graph eval --all 复现。完整基准测试数据请参阅英文 README。

功能一览

功能	说明
增量更新	仅重新解析变更文件，后续更新不到 2 秒完成
广泛语言覆盖 + 笔记本	Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua/Luau, Objective-C, shell, Elixir, Zig, PowerShell, Julia, ReScript, GDScript, Nix, Verilog/SystemVerilog, SQL, Vue/Svelte SFCs, Astro files parsed as TypeScript, Jupyter/Databricks (.ipynb)
影响半径分析	展示某次变更可能影响的函数、类和文件
自动更新钩子	每次文件编辑和 git 提交时自动更新图，无需手动干预
语义搜索	可选的向量嵌入，支持 sentence-transformers、Google Gemini、MiniMax，或任何 OpenAI 兼容端点（真实 OpenAI、Azure、new-api、LiteLLM、vLLM、LocalAI）
交互式可视化	D3.js 力导向图，支持搜索、社区图例切换和按度数缩放的节点
Hub 与 Bridge 检测	查找连接最多的节点和通过介数中心性发现架构瓶颈
异常评分	检测意外耦合：跨社区、跨语言、外围到核心的边
知识缺口分析	识别孤立节点、未测试热点、薄弱社区和结构性弱点
智能提问	基于图分析（桥接点、枢纽、异常）自动生成审查问题
边置信度	三级置信度评分（EXTRACTED/INFERRED/AMBIGUOUS），边上附带浮点分数
图遍历	从任意节点进行自由 BFS/DFS 探索，可配置深度和 token 预算
导出格式	GraphML (Gephi/yEd)、Neo4j Cypher、Obsidian 知识库（含 wikilinks）、SVG 静态图
图差异	比较不同时间的图快照：新增/删除的节点、边和社区变化
Token 基准测试	测量朴素全量 token 与图查询 token，附带逐题比率
记忆循环	将问答结果持久化为 Markdown 以供重新摄入，使图从查询中不断成长
社区自动分割	过大的社区（>图的 25%）通过 Leiden 算法递归分割
执行流	从入口点追踪调用链，按加权关键度排序
社区检测	通过 Leiden 算法聚类相关代码，大型图自动调节分辨率
架构概览	自动生成架构图，附带耦合警告
风险评分审查	`detect_changes` 将差异映射到受影响的函数、执行流和测试缺口
重构工具	重命名预览、框架感知的死代码检测、基于社区的重构建议
Wiki 生成	从社区结构自动生成 Markdown Wiki
多仓库注册	注册多个仓库，跨仓库搜索
MCP 提示模板	5 种工作流模板：审查、架构、调试、入职引导、合并前检查
全文搜索	基于 FTS5 的混合搜索，结合关键词和向量相似度
本地存储	SQLite 文件存储在 `.code-review-graph/` 中，核心图存储无需外部数据库或云服务
监听模式	工作时持续更新图

使用方式

斜杠命令

命令	说明
`/code-review-graph:build-graph`	构建或重新构建代码图
`/code-review-graph:review-delta`	审查自上次提交以来的变更
`/code-review-graph:review-pr`	完整的 PR 审查，含影响半径分析

CLI 参考

code-review-graph install          # 自动检测并配置所有平台
code-review-graph install --platform <name>  # 指定特定平台
code-review-graph build            # 解析整个代码库
code-review-graph update           # 增量更新（仅变更文件）
code-review-graph status           # 图统计信息
code-review-graph watch            # 文件变更时自动更新
code-review-graph visualize        # 生成交互式 HTML 图
code-review-graph visualize --format graphml   # 导出为 GraphML
code-review-graph visualize --format svg       # 导出为 SVG
code-review-graph visualize --format obsidian  # 导出为 Obsidian 知识库
code-review-graph visualize --format cypher    # 导出为 Neo4j Cypher
code-review-graph wiki             # 从社区结构生成 Markdown Wiki
code-review-graph detect-changes   # 风险评分的变更影响分析
code-review-graph register <path>  # 将仓库注册到多仓库注册表
code-review-graph unregister <id>  # 从注册表移除仓库
code-review-graph repos            # 列出已注册的仓库
code-review-graph eval             # 运行评估基准测试
code-review-graph serve            # 启动 MCP 服务器

30 个 MCP 工具

图构建完成后，AI 助手会自动使用这些工具。

工具	说明
`build_or_update_graph_tool`	构建或增量更新图
`run_postprocess_tool`	重新运行执行流、社区和全文索引后处理
`get_minimal_context_tool`	超紧凑上下文（约 100 tokens）——首先调用此工具
`get_impact_radius_tool`	变更文件的影响半径
`get_review_context_tool`	Token 优化的审查上下文，附带结构摘要
`query_graph_tool`	查询调用者、被调用者、测试、导入、继承关系
`traverse_graph_tool`	从任意节点进行 BFS/DFS 遍历，可设置 token 预算
`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`	面向代码审查的风险评分变更影响分析
`get_hub_nodes_tool`	查找连接最多的节点（架构热点）
`get_bridge_nodes_tool`	通过介数中心性查找架构瓶颈
`get_knowledge_gaps_tool`	识别结构性弱点和未测试热点
`get_surprising_connections_tool`	检测意外的跨社区耦合
`get_suggested_questions_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），因此 gitignore 中的文件会自动跳过。.code-review-graphignore 用于排除已跟踪的文件，或在没有 git 的环境中使用。

可选依赖组：

pip install code-review-graph[embeddings]          # 本地向量嵌入 (sentence-transformers)
pip install code-review-graph[google-embeddings]   # Google Gemini 嵌入
pip install code-review-graph[communities]         # 社区检测 (igraph)
pip install code-review-graph[enrichment]          # Python 调用解析增强 (Jedi)
pip install code-review-graph[eval]                # 评估基准测试 (matplotlib)
pip install code-review-graph[wiki]                # 使用 LLM 摘要生成 Wiki (ollama)
pip install code-review-graph[all]                 # 所有可选依赖

OpenAI 兼容嵌入（真实 OpenAI、Azure，或自建网关如 new-api / LiteLLM / vLLM / LocalAI / Ollama openai 模式）无需额外安装 —— 只需设置环境变量并在 embed_graph 中传入 provider="openai"：

export CRG_OPENAI_BASE_URL=http://127.0.0.1:3000/v1     # 或 https://api.openai.com/v1
export CRG_OPENAI_API_KEY=sk-...
export CRG_OPENAI_MODEL=text-embedding-3-small          # 取决于你网关提供的模型
# 可选：
export CRG_OPENAI_DIMENSION=1536                        # 固定维度（v3 模型支持维度缩减）
export CRG_OPENAI_BATCH_SIZE=100                        # 某些网关有更严格的批次限制时下调
                                                        # （如 Qwen text-embedding-v4 上限为 10）

当 base URL 指向 localhost（127.0.0.1、localhost、0.0.0.0、::1）时，会自动跳过云出口警告。

模型选择提示。 避免用 -preview / -beta / -exp 结尾的 model ID（例如 google/gemini-embedding-2-preview）做长期使用——preview 模型可能更换权重（维度一变就要全量 re-embed）或被无预警下架。建议改用正式 GA 模型：text-embedding-3-small / text-embedding-3-large（OpenAI）、Qwen/Qwen3-Embedding-8B（经 vLLM / LocalAI 自宿主）、或 gemini-embedding-001（经原生 Gemini provider，需要 GOOGLE_API_KEY）。

另外请注意：目前 code-review-graph 只嵌入函数签名（每节点约 10 tokens，例如 "parse_file function (path: str) returns Tree"）。那些靠长 context 理解函数 body 来拉开差距的模型（Gemini 2 或 Qwen3-8B 在 MTEB-code 的 SOTA 分数）在这个输入长度下跟小模型的品质差距会小很多。Body / docstring 嵌入已列为后续增强任务。

参与贡献

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 中添加节点类型映射。附上测试用例文件，然后提交 PR。

许可证

MIT。详见 LICENSE。

code-review-graph.com

pip install code-review-graph && code-review-graph install
_{自动检测并配置支持的 AI 编码工具，包括 Codex、Claude Code、Cursor、Windsurf、Zed、Continue、OpenCode、Antigravity、Gemini CLI、Qwen、Kiro、Qoder 和 GitHub Copilot}

18 KiB Raw Permalink Blame History Unescape Escape

code-review-graph

快速开始

工作原理

影响半径分析

增量更新，不到 2 秒

解决 monorepo 难题

广泛语言覆盖 + Jupyter 笔记本

基准测试

功能一览

使用方式

参与贡献

许可证

18 KiB

Raw Permalink Blame History