code-review-graph：本地优先的代码智能图谱，让 AI 代码审查只读关键内容
发布时间：2026/9/10 11:26:28 作者：尧图编辑部 阅读量：1,286
code-review-graph本地优先的代码智能图谱让 AI 代码审查只读关键内容【免费下载链接】code-review-graphLocal-first code intelligence graph for MCP and CLI. Builds a persistent map of your codebase so AI coding tools read only what matters, with benchmarked context reductions on reviews and large-repo workflows.项目地址: https://gitcode.com/GitHub_Trending/co/code-review-graph代码审查类 AI 任务常常被迫通读整个代码库来回答问题token 浪费严重。code-review-graph用 Tree-sitter 把代码库解析成一张结构化的智能图谱通过 MCP 协议为 AI 编码助手提供精准上下文使其只读取真正与变更相关的内容。本文基于仓库中 README.zh-CN.md 展开结合源码带你掌握从安装、构建、增量更新到影响半径分析、风险评分审查与自定义语言扩展的完整实战方案。快速开始三条命令完成接入pip install code-review-graph # 或: pipx install code-review-graph code-review-graph install # 自动检测并配置所有支持的平台 code-review-graph build # 解析代码库install是核心的一键配置命令它会检测你机器上安装了哪些 AI 编码工具为每个工具写入正确的 MCP 配置并在平台规则中注入图感知指令同时自动判断你是通过uvx还是pip/pipx安装的并据此生成对应配置。安装完成后请重启编辑器或工具。需要 Python 3.10该版本检查直接内置于 CLI 入口低于 3.10 会立即退出并给出提示建议安装 uvMCP 配置将优先使用uvx否则回退到直接执行code-review-graph命令。如需指定特定平台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从 CLI 的_PLATFORM_CHOICES可以看到完整支持列表codex、claude/claude-code、cursor、windsurf、zed、continue、opencode、antigravity、gemini-cli、qwen、kiro、qoder、copilot、copilot-cli、codebuddy、hermes。底层安装逻辑MCP 配置写入、Skills 生成、平台规则注入实现在 skills.py 中支持 JSON/JSONC/TOML/YAML 多种配置格式的合并写入。配置完成后打开项目并向 AI 助手发出指令Build the code review graph for this project首次构建在 500 个文件的项目上大约需要 10 秒。此后可通过 watch 模式以及支持的平台钩子在文件保存和提交时自动更新图。工作原理从源码到可查询的图整个管线可以概括为代码库 → Tree-sitter 解析器 → SQLite 图 → 影响半径 → 最小审查集。代码库通过 Tree-sitter 解析为 AST以节点函数、类、导入和边调用、继承、测试覆盖的形式存储在 SQLite 图中然后在审查时查询计算 AI 助手需要读取的最小文件集。图的底层存储实现在 graph.py 中GraphStore负责节点/边的增删查、影响半径遍历、传递测试查询等数据文件位于仓库的.code-review-graph/目录核心图存储无需任何外部数据库或云服务。影响半径分析当文件发生变更时图会沿着调用、导入、继承等边追踪所有可能受影响的调用者、依赖项和测试——这就是该变更的影响半径。AI 只需读取这些文件而无需扫描整个项目。影响半径的默认搜索深度为 2、默认节点上限为 500可通过CRG_MAX_IMPACT_DEPTH和CRG_MAX_IMPACT_NODES环境变量调节见下文环境变量部分。在 graph.py 中get_impact_radius既提供基于 SQL 递归的实现也提供基于 networkx 的实现并内置了多条安全边界。增量更新只重解析哈希变化的文件启用钩子或 watch 模式后文件保存和受支持的提交钩子会触发增量更新。更新流程是图对变更文件做差异比较沿着图自身的 import 与调用边找到相关依赖只重新解析 SHA-256 哈希确实发生变化的文件。这一判断在 incremental.py 中直接可见——对每个候选文件先计算hashlib.sha256(raw).hexdigest()若与已存节点哈希一致则跳过解析fhash hashlib.sha256(raw).hexdigest() ... if existing_nodes and existing_nodes[0].file_hash fhash: # 哈希未变跳过重新解析一个 2,900 文件的项目重新索引不到 2 秒。watch模式本身也是生产级实现带健康检查、事件去重、目录级 watch 调度与自动降级策略相关的健壮性测试见 tests/test_watch_robustness.py。整个代码库还是有的放矢的回答仓库越大token 浪费越让人心疼。图不会把整个语料交给模型而是只返回与回答相关的那一部分在本仓库中208,821 个源码 token 会缩减为每个问题约 3,190 个 token约 68 倍。以 flask 为对比读完其全部源码需要 143,594 个 token而图给出的回答只需 2,196 个——减少 71.0 倍。get_minimal_context_tool甚至能以约 100 个 token 返回超紧凑上下文作为 AI 助手在处理任务时的首选入口对应实现见 context.py。广泛语言覆盖与笔记本支持解析器支持覆盖当前解析面中的函数、类、导入、调用点、继承和测试检测能用 Tree-sitter 的地方使用 Tree-sitter需要时使用有针对性的回退解析如 ReScript 用正则解析、VB.NET 用结构化回退。支持范围包括 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。从 parser.py 的EXTENSION_TO_LANGUAGE映射 可以看到完整的扩展名注册表如.py→python、.tsx→tsx、.kt→kotlin、.tf→hcl、.ipynb→notebook等无扩展名的脚本还会通过 shebang 解释器推断语言。文件哈希、C/C 头文件判别.h默认按 C 解析只有出现 C 特有语法证据才提升为 C、Qt 宏掩码等细节都有专门处理。基准测试用数据说话所有数据来自针对6 个真实开源仓库共 13 次提交的自动化评估可通过code-review-graph eval --all复现。评估基础设施位于 eval/runner.py各评测基准token 效率、影响准确率、多跳检索、构建性能、搜索质量等位于 eval/benchmarks/历史结果 CSV 存档在 evaluate/results/。关键结论包括Token 效率6 个仓库每个问题的 token 减少中位数约 65 倍区间 36x–376x其中 376x 是 fastapi 的最佳个案并非典型值。影响准确率13 个评估提交的平均 F1 为0.69、平均精确率 0.546。需要特别说明的是召回率 1.0是图派生的圆形上限——该模式下真值变更文件 通过调用/导入边连入的文件与预测器遍历的是同一张图因此只应视为上限而非100% 召回。设计上宁可多标记文件也不漏掉被破坏的依赖。构建性能如 express 141 文件解析出 1,910 节点 / 17,553 边、fastapi 1,122 文件解析出 6,285 节点 / 27,117 边流检测延迟在 100ms 级别搜索延迟亚毫秒级。已知局限原文档如实列出影响召回 1.0为圆形上限对琐碎的单文件小改动图上下文可能超过朴素文件读取关键词搜索 MRR 0.35 仍有提升空间Python 与 PHP/Laravel 的流检测最强JavaScript 与 Go 需要改进影响分析是刻意保守的大型依赖图中存在一些误报。功能一览功能说明增量更新仅重新解析变更文件后续更新不到 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 服务器完整命令参考见 docs/COMMANDS.md故障排查见 docs/TROUBLESHOOTING.md常见问题对比vs LSP、vs RAG、vs grep见 docs/FAQ.md。风险评分审查的内部机制detect-changes的风险评分并非黑盒其评分因子在 changes.py 的compute_risk_score中逐项可查最终归一到 0.0–1.0执行流参与度每个所属流 0.05按关键度加权上限 0.25跨社区调用每个来自不同社区的调用者 0.05上限 0.15——即被跨模块调用越多越危险测试覆盖未测试节点记 0.30随测试边数量递减至 0.055 条 TESTED_BY 边安全敏感度名称或限定名命中安全关键词 0.20调用者数量callers/20上限 0.10变更频率可选通过CRG_CHURN_WINDOW_DAYS配置回溯窗口提交数/10 计入上限 0.15。对应的变更输入侧parse_git_diff_ranges 运行git diff --unified0解析每个文件的变更行区间再通过map_changes_to_nodes将行区间与图中节点的行号范围重叠匹配从而把改了哪几行精确映射到影响了哪些函数。相关测试见 tests/test_changes.py。30 个 MCP 工具图构建完成后AI 助手会自动使用这些工具均定义于 tools/ 与 main.py工具说明build_or_update_graph_tool构建或增量更新图run_postprocess_tool重新运行执行流、社区和全文索引后处理get_minimal_context_tool超紧凑上下文约 100 tokens——首先调用此工具get_impact_radius_tool变更文件的影响半径get_review_context_toolToken 优化的审查上下文附带结构摘要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 Wikiget_wiki_page_tool获取特定 Wiki 页面list_repos_tool列出已注册的仓库cross_repo_search_tool跨所有注册仓库搜索MCP 提示模板5 种工作流模板实现于 prompts.pyreview_changes、architecture_map、debug_issue、onboard_developer、pre_merge_check在 token 受限的环境中可通过code-review-graph serve --tools query_graph_tool,semantic_search_nodes_tool,detect_changes_tool或CRG_TOOLS环境变量对暴露的工具做白名单过滤CLI 参数优先于环境变量。配置详解排除路径.code-review-graphignore在仓库根目录创建.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 兼容嵌入真实 OpenAI、Azure或自建网关如 new-api / LiteLLM / vLLM / LocalAI / Ollama openai 模式无需额外安装——只需设置环境变量并在embed_graph中传入provideropenaiexport CRG_OPENAI_BASE_URLhttp://127.0.0.1:3000/v1 # 或 https://api.openai.com/v1 export CRG_OPENAI_API_KEYsk-... export CRG_OPENAI_MODELtext-embedding-3-small # 取决于你网关提供的模型 # 可选 export CRG_OPENAI_DIMENSION1536 # 固定维度v3 模型支持维度缩减 export CRG_OPENAI_BATCH_SIZE100 # 某些网关有更严格的批次限制时下调 # 如 Qwen text-embedding-v4 上限为 10当 base URL 指向 localhost127.0.0.1、localhost、0.0.0.0、::1时会自动跳过云出口警告该判断由 http_origin_guard.py 与 embeddings.py 中的_is_localhost_url协同完成。VOYAGE_API_KEY则用于 Voyage 嵌入默认模型voyage-code-3。模型选择提示。避免用-preview/-beta/-exp结尾的 model ID例如google/gemini-embedding-2-preview做长期使用——preview 模型可能更换权重维度一变就要全量 re-embed或被无预警下架。建议改用正式 GA 模型text-embedding-3-small/text-embedding-3-largeOpenAI、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 嵌入已列为后续增强任务。关键环境变量以下变量对调优审查行为最常用完整清单见英文 README 的 Environment Variables 小节变量说明默认值CRG_GIT_TIMEOUTGit 操作超时秒数30CRG_DATA_DIR覆盖图数据库与产物目录-CRG_EMBEDDING_MODEL向量嵌入默认模型all-MiniLM-L6-v2CRG_MAX_IMPACT_NODES影响分析最多节点数500CRG_MAX_IMPACT_DEPTH影响半径搜索深度2CRG_MAX_BFS_DEPTH图遍历最大深度15CRG_MAX_CHANGED_FUNCS单份变更报告分析的最大函数数500CRG_TOOLSMCP 工具白名单逗号分隔-GOOGLE_API_KEY/MINIMAX_API_KEY/VOYAGE_API_KEY各家嵌入服务 API Key-参与贡献与扩展新语言本地开发与测试python3 -m venv .venv source .venv/bin/activate pip install -e .[dev] pytest添加新语言支持编辑 code_review_graph/parser.py将你的文件扩展名添加到EXTENSION_TO_LANGUAGE见 L715 起的映射表并在_CLASS_TYPES、_FUNCTION_TYPES、_IMPORT_TYPES和_CALL_TYPES分别位于 L900、L998、L1073、L1129 附近中添加对应的 Tree-sitter 节点类型映射。附上测试用例文件参考 tests/fixtures/ 中的多语言样例与对应测试然后提交 PR。小结code-review-graph的核心价值在于把AI 读全库变成AI 读关键用 Tree-sitter 建立跨语言的持久化代码图用 SHA-256 哈希驱动的增量更新保证图常新用影响半径与风险评分把审查上下文压缩到接近最优。无论你是想在 Claude Code、Cursor、Codex 等 AI 编码工具中接入 MCP 审查还是想在 CI 中落地风险评分的 PR 门禁GitHub Action 用法见 docs/GITHUB_ACTION.md从本仓库的 README.zh-CN.md 出发配合本文梳理的源码路径即可快速上手并深入其实现细节。【免费下载链接】code-review-graphLocal-first code intelligence graph for MCP and CLI. Builds a persistent map of your codebase so AI coding tools read only what matters, with benchmarked context reductions on reviews and large-repo workflows.项目地址: https://gitcode.com/GitHub_Trending/co/code-review-graph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 