AI 编码工具为了审查一次改动常常要重新读取代码库的大部分内容。code-review-graph用 Tree-sitter 构建代码的结构图增量保持更新并通过 MCP 提供紧凑的上下文让助手只读取改动涉及的文件。快速开始pip install code-review-graph # or: pipx install code-review-graph code-review-graph install # detect installed AI coding tools and configure each one code-review-graph build # parse the codebaseinstall会检测你安装了哪些 AI 编码工具为每个工具写入一条 MCP 服务器配置在平台支持的地方安装钩子和技能并把图谱说明加入平台的规则文件。在 Poetry 或 uv 项目环境中MCP 配置使用poetry run或uv run当 PATH 上有uvx时使用uvx code-review-graph serve否则使用当前的 Python 解释器。安装后请重启编辑器或工具。只配置一个平台时给--platform传入codex、claude-code、cursor、windsurf、zed、continue、opencode、antigravity、gemini-cli、qwen、kiro、qoder、copilot、copilot-cli、codebuddy或hermes之一code-review-graph install --platform cursor code-review-graph install --platform codebuddy配置文件的位置列在 docs/USAGE.md 中。需要 Python 3.10。uninstall会从 Git 或 SVN 工作树中移除 CRG 自己写入的文件和配置项不动其他 MCP 服务器、钩子、技能和 JSONC 注释。在工作树内的任意位置运行即可。共享配置文件采用原子替换写入失败时原文件保持完整。code-review-graph uninstall --dry-run # preview only code-review-graph uninstall # preview, confirm, apply code-review-graph uninstall --yes # apply without prompting code-review-graph uninstall --all-repos # also clean every registered repository code-review-graph uninstall --keep-data # remove integrations, keep graph databases code-review-graph uninstall --keep-user-configs --repo . # this project only然后打开项目对助手说Build the code review graph for this project构建时间随仓库规模增长一个约 3,000 个文件的仓库冷构建约需 40 秒实测。之后由钩子和 watch 模式保持图谱更新。如果部分文件解析失败结果状态为partial并在摘要中列出这些文件CLI 还会在 stderr 上打印一行Warning:这些文件保留原有的图谱记录。工作原理仓库通过 Tree-sitter 解析为 AST并以节点函数、类、导入和边调用、继承、测试覆盖的形式存为图谱。审查时查询图谱得到助手需要读取的最小文件集合。影响半径分析文件变更时图谱会追踪所有可能受影响的调用者、依赖方和测试。助手读取这些文件而不是扫描整个项目。增量更新钩子、pre-commit 钩子和 watch 模式都会触发增量更新。更新时对变更文件做 diff沿图谱的导入边和调用边找出依赖方并只重新解析 SHA-256 哈希发生变化的文件。在一个约 3,000 个文件的项目django上修改两个文件后沿钩子路径重新索引约需 2.5 秒其中约 1.4 秒是进程启动空更新只花这段启动时间。参见增量更新延迟。整个代码库还是有的放矢的回答图谱不会把整个语料喂给模型而是返回按问题裁剪的切片。在 2026-08-02 对本仓库84bde354的快照中208,821 个源码 token 变成每个问题约 3,190 个 token。此后仓库增长了很多所以今天这两个数字都更大。语言覆盖与笔记本解析器提取函数、类、导入、调用点、继承和测试有语法的地方用 Tree-sitter其他地方用有针对性的回退解析。支持范围Python、JavaScript/TypeScript/TSX、Go、Rust、Java、C/C、C#、VB.NET、Ruby、Kotlin、Swift、PHP、Scala、Solidity、Dart、R、Perl、Lua/Luau、Objective-C、shell 脚本、Elixir、Zig、PowerShell、Julia、ReScript、GDScript、Nix、Verilog/SystemVerilog、SQL、Terraform/OpenTofu.tf其他.hcl文件只生成文件节点、Ansible YAMLplaybook、role、task、Spring Boot 应用配置application.properties、application.yml、application.yaml及其application-profile变体只记录键名和值的类型绝不记录值、Vue/Svelte 单文件组件、Astro 文件用 TypeScript 语法解析、Jupyter 和 Databricks 笔记本.ipynb以及 Perl XS 文件.xs。其他 YAML 和其他.properties文件不被当作源代码。PHP 项目还会得到仓库范围内的 Composer PSR-4 解析、Blade 模板引用以及在源码中出现明确的框架导入、模型继承和接收者证据时生成的 Laravel Route 与 Eloquent 边。Java 项目会得到 Spring 依赖注入的调用解析、请求端点与 WebFlux 路由、定时触发器、应用事件的发布者到监听者的边以及 Temporal 工作流与活动的边。每个解析器都在解析之后运行并且需要被注入的字段、发布的事件或工作流 stub 在仓库中可见。添加你自己的语言如果你的仓库使用了解析器尚未覆盖的语言在.code-review-graph/中添加一个languages.toml把文件扩展名映射到tree_sitter_language_pack中自带的任意语法并给出函数、类、导入和调用的节点类型[languages.erlang] extensions [.erl] grammar erlang function_node_types [function_clause] class_node_types [record_decl] import_node_types [import_attribute] call_node_types [call]提取工作由通用的 tree-sitter 遍历器完成。内置语言不能被覆盖。schema、校验规则和完整示例见 docs/CUSTOM_LANGUAGES.md。在 CI 中做风险评分的 PR 审查GitHub Action同样的分析也以组合式 GitHub Action 的形式运行。图谱在你的 CI runner 上构建和查询不会把源代码发送给外部服务。每个 pull request 上该 action 会发布一条常驻评论列出风险评分的函数、受影响的执行流和测试缺口并在每次推送时就地更新。可选的fail-on-risk输入可以把它变成合并门禁。# .github/workflows/code-review-graph.yml on: pull_request: permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv7 - uses: tirth8205/code-review-graphv2.3.9 with: github-token: ${{ secrets.GITHUB_TOKEN }}输入参数、风险等级和缓存见 docs/GITHUB_ACTION.md本仓库自己运行的工作流见 .github/workflows/pr-review.yml。基准测试6 个仓库上每个问题的 token 减少中位数约为63 倍全语料基线对比图谱查询。358 倍的最大值只属于一个仓库fastapi语料最大不是典型结果。所有数字都来自针对 6 个开源仓库13 次提交的评估运行器。每个配置都固定了上游 SHALeiden 使用固定随机种子嵌入在 CPU 上是确定性的因此不同机器上的两次运行得到相同的数字。复现步骤见 docs/REPRODUCING.md。在两个最小配置上的每周只读运行位于 .github/workflows/eval.yml。Token 效率每个问题减少中位数约 63 倍范围 35 倍到 358 倍全语料对比图谱查询对于典型的智能体问题how does authentication work、what is the main entry point等图谱返回约 2,200 到 3,900 个 token 的搜索命中加邻接边而不是每一个源文件。表格对code_review_graph/token_benchmark.py中定义的 5 个样例问题取平均。仓库快照 SHAnaive_corpus_tokensavg graph_tokens减少倍数fastapi22381558948,7932,653357.6xflaska29f88ce143,5942,19665.4xcode-review-graph84bde354208,8213,19065.5xgin5c00df8a166,8682,76660.3xhttpxb55d4635142,3562,66153.5xexpressb4ab7d65136,0523,93634.6x2026-08-02 从固定 SHA 的干净克隆中采集crg 2.3.7本地all-MiniLM-L6-v2嵌入。这些数字低于它们取代的 2026-05-25 采集节点嵌入文本变得更丰富因此每个仓库的avg graph_tokens都上升了。fastapi 按当前固定的22381558测量而不是已退役的0227991a。减少倍数一列是naive_corpus_tokens / avg graph_tokens因此可以由旁边两列直接除出来。基准测试自己的average_reduction_ratio取的是五个问题各自比率的平均值那个值总是更高每个问题的数字见 docs/REPRODUCING.md。code-review-graph这一行是快照不是当前测量值。仓库自84bde354以来有所增长其语料和图谱今天都大得多。全语料基线是任何真实智能体都不会付出的上限智能体会 grep 标识符并读取最匹配的文件。agent_baseline评估基准测量的就是这种情况纯 Python 对语料做 grep按匹配数取前 3 个文件再与图谱查询开销做 token 对比。它写入evaluate/results/repo_agent_baseline_date.csv目前还没有发布过权威采集结果。正式的token_efficiency基准测量的是另一个场景完整的get_review_context()JSON 对比一次提交中仅变更文件的内容对于小提交它报告的比率低于 1因为响应里带有影响半径的边和源码片段。这两个基准回答的是不同的问题见 docs/REPRODUCING.md。审查和影响类工具会在响应中附带紧凑的context_savings估算。CLI 在Token Savings面板中显示同样的数字见下文使用方式--verify会把它们与 OpenAI 的cl100k_base分词器做对比。在 222 个样本文件上的校准表明总体估算与真实 token 的偏差约在 1% 以内数据。影响准确度对图谱生成的基准答案平均 F1 为 0.69召回率 1.0 是循环论证得出的上限在全部 13 次评估提交上影响半径分析都找回了基准答案中的每一个文件。请把它读作上限而不是100% 召回基准答案变更文件加上有调用边或导入边指向它们的文件来自预测器所遍历的同一张图谱。较低的精确率是有意为之多标一个文件的代价小于漏掉一个被破坏的依赖。仓库提交数平均 F1平均精确率召回率图谱生成的上限httpx20.8630.7851.0code-review-graph20.7340.5841.0fastapi20.6970.5391.0express20.6670.5001.0flask20.6330.4851.0gin30.6090.4391.0平均130.6930.5461.000该基准还会运行一种共变更模式给预测器一个变更文件作为种子再用作者在同一次提交中改动的其他文件来评分这是来自 git 历史而非图谱的证据。两种模式都出现在结果 CSV 中ground_truth_mode列。在 2026-08-02 的采集中共变更模式在每个被评分的提交上都返回predicted_files 0因此它还不是可用的测量结果也不引用任何共变更数字。构建统计来自上文固定 SHA 的同一次 2026-08-02 干净构建。嵌入数量低于节点数量因为 File 节点不做嵌入。code-review-graph这一行是那个快照不是仓库现在的状态。仓库节点边嵌入fastapi6,28732,0365,159express1,99019,4921,849gin1,58917,2371,491code-review-graph1,4469,0941,354flask1,4158,2591,329httpx1,2638,2361,193局限影响分析的召回率 1.0是循环论证。历史基准答案来自预测器所遍历的同一批图谱边因此按构造它就是一个上限。共变更模式还不是可用的测量结果。小的单文件改动。对于琐碎的编辑图谱上下文可能比直接读文件还大。多出来的是让多文件分析成为可能的结构化元数据。搜索排序。关键词搜索通常能把正确结果排在靠前位置但排序还需要改进。由于模块模式的命名方式针对 Express 的查询可能返回零命中。执行流检测。入口点检测对 Python 和 PHP/Laravel 最强。JavaScript 和 Go 的流检测还需要改进。精确率与召回率。影响分析偏保守。它会标出可能受影响的文件这意味着在大型依赖图中会出现误报。功能功能说明增量更新只重新解析哈希发生变化的文件。在一个约 3,000 个文件的仓库上修改两个文件沿钩子路径约需 2.5 秒实测。语言与笔记本支持见上文语言覆盖。框架感知的 PHP 解析仓库范围内的 Composer PSR-4 导入、Blade 模板引用、有证据支撑的 Laravel Route 到控制器以及 Eloquent 关系边框架感知的 Java 解析Spring 依赖注入的调用解析、请求端点与 WebFlux 路由、定时触发器、应用事件的发布者到监听者的边、Temporal 工作流与活动的边以及只索引键名不索引值的 Spring Boot 配置键影响半径分析一次改动可能影响哪些函数、类和文件自动更新钩子编辑器钩子、git pre-commit 钩子和 watch 模式在你工作时更新图谱语义搜索可选的向量嵌入通过 sentence-transformers、Google Gemini、MiniMax、Voyage AI或任何 OpenAI 兼容端点OpenAI、Azure、new-api、LiteLLM、vLLM、LocalAI交互式可视化D3.js 力导向图支持搜索、社区图例开关和按度数缩放的节点枢纽与桥接检测连接最多的节点和瓶颈点介数中心性意外度评分意外耦合跨社区、跨语言、外围到枢纽的边知识缺口分析孤立节点、未测试的热点、稀薄的社区建议问题从桥接点、枢纽和意外耦合生成的审查问题边置信度两级置信度EXTRACTED/INFERRED边上带浮点分数图谱遍历从任意节点出发的 BFS/DFS深度和 token 预算可配置导出格式GraphMLGephi/yEd、Neo4j Cypher、Obsidian 知识库、JSON以及 SVGSVG 需要eval附加依赖中的 matplotlibToken 基准测试code_review_graph/token_benchmark.py按问题测量全语料 token 与图谱查询 token估算的上下文节省在审查、影响、detect-changes 和架构响应上附带context_savings元数据estimated、saved_tokens、saved_percent社区自动拆分占图谱 25% 以上的社区用 Leiden 递归拆分执行流从入口点出发的调用链按加权关键度排序社区检测Leiden 聚类分辨率随图谱规模调整架构概览基于社区结构的架构图附带耦合警告风险评分审查detect_changes把 diff 映射到受影响的函数、执行流和测试缺口自定义语言通过.code-review-graph/languages.toml添加新语言无需 forkGitHub Action在 CI 中发布常驻的风险评分 PR 审查评论可选fail-on-risk合并门禁重构工具重命名预览、框架感知的死代码检测、基于社区的建议Wiki 生成从社区结构生成 Markdown Wiki多仓库注册表注册多个仓库并跨仓库搜索多仓库守护进程crg-daemon以子进程方式监视多个仓库带健康检查和重启MCP 提示模板5 个工作流模板审查、架构、调试、入职、合并前检查全文搜索FTS5 混合搜索结合关键词与向量相似度本地存储.code-review-graph/中的一个 SQLite 文件没有外部数据库或云服务使用方式技能install会为支持技能的平台Claude Code、Gemini CLI、CodeBuddy Code、Hermes Agent 和 Qoder写入以下四个技能。按名字调用即可。技能说明explore-codebase使用知识图谱浏览并理解代码库结构review-changes用变更检测与影响分析做结构化的代码审查debug-issue借助图谱驱动的代码导航系统性地排查问题refactor-safely用依赖分析规划并执行安全的重构Qoder 还会从本仓库的skills/目录得到build-graph、review-delta和review-pr。CLI 参考code-review-graph install # Detect and configure all platforms code-review-graph install --platform name # One platform code-review-graph uninstall --dry-run # Preview removal of installed artifacts code-review-graph build # Parse the whole codebase code-review-graph update # Incremental update (changed files only) code-review-graph status # Graph statistics code-review-graph watch # Update on file changes code-review-graph forget path # Drop already-parsed files from the graph code-review-graph dead-code # Functions and classes with no callers or tests code-review-graph visualize # Interactive HTML graph code-review-graph visualize --format json # Export graph data as JSON code-review-graph visualize --format graphml # Export as GraphML code-review-graph visualize --format svg # Export as SVG (needs matplotlib) code-review-graph visualize --format obsidian # Export as Obsidian vault code-review-graph visualize --format cypher # Export as Neo4j Cypher code-review-graph wiki # Markdown wiki from communities code-review-graph detect-changes --brief # Risk panel token savings (read-only) code-review-graph detect-changes --brief --base main # Against the merge base of main and HEAD code-review-graph update --brief # Refresh graph same panel code-review-graph detect-changes --brief --verify # Cross-check against tiktoken code-review-graph register path # Register repo in the multi-repo registry code-review-graph unregister path|alias # Remove repo from the registry code-review-graph repos # List registered repositories code-review-graph daemon start # Start the multi-repo watch daemon code-review-graph daemon stop # Stop the daemon code-review-graph daemon status # Daemon status and repos code-review-graph eval # Run evaluation benchmarks code-review-graph serve # Start the MCP server (stdio) code-review-graph serve --http # MCP over Streamable HTTP on localhost:5555这是一份精选列表。code-review-graph --help会列出全部命令docs/COMMANDS.md 记录了它们的参数。当detect-changes --base指定的是一个分支时diff 会针对该分支与 HEAD 的合并基做。提交哈希和其他 revision 按原样使用。visualize --format svg需要 matplotlib它随eval附加依赖提供pip install code-review-graph[eval]。其他导出格式无需额外安装。JSON 导出写在本地图谱数据目录中该目录默认被 Git 忽略。导出内容可能包含绝对路径和代码结构元数据发布前请先检查。Token Savings 面板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%) │ │ Breakdown: Functions 244 · Tests 191 · Risk 244 · Other 83 │ └──────────────────────────────────────────────────────────────┘命令作用何时使用detect-changes --brief只读。针对当前改动查询已有图谱并打印面板。大多数时候钩子或crg-daemon会保持图谱新鲜。update --brief先把变更文件重新解析进图谱再打印同样的面板。rebase 之后、改动集很大时或图谱可能已过期时。给任一命令加上--verify可以把数字与 OpenAI 的cl100k_base分词器做对比需要pip install tiktoken。总体估算与真实 token 的偏差约在 1% 以内见 docs/REPRODUCING.md。同样的context_savings元数据也附在get_impact_radius、get_review_context、detect_changes和get_architecture_overview这几个 MCP 工具的 JSON 响应上。多仓库守护进程如果你的编辑器不支持钩子例如 Cursor 或 OpenCode或者你想在没有编辑器集成的情况下保持图谱新鲜守护进程会监视你的仓库并更新它们的图谱。它随code-review-graph一起提供无需单独安装。# 1. Register the repos to watch crg-daemon add ~/project-a --alias proj-a crg-daemon add ~/project-b # 2. Start the daemon (runs in the background) crg-daemon start # 3. Check on it crg-daemon status # daemon and per-repo watcher status crg-daemon logs --repo proj-a -f # tail logs for one repo crg-daemon stop # stop the daemon and all watchers也可以用code-review-graph daemon start|stop|status|...。crg-daemon add写入~/.code-review-graph/watch.toml你也可以直接编辑该文件[[repos]] path /home/user/project-a alias proj-a [[repos]] path /home/user/project-b alias project-b守护进程会监视这个文件并随着仓库的增删启动或停止 watcher 进程。每 30 秒一次的健康检查会重启已死的 watcher。完整配置参考见 docs/COMMANDS.md。30 个 MCP 工具图谱构建完成后助手会使用这些工具。工具说明build_or_update_graph_tool构建或增量更新图谱run_postprocess_tool重新运行执行流检测、社区检测和 FTS 索引get_minimal_context_tool紧凑上下文约 100 token先调用这个get_impact_radius_tool变更文件的影响半径get_review_context_tool带结构摘要的审查上下文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搜索已注册的仓库repos可把搜索限定到一个子集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 时使用。默认忽略列表见 docs/USAGE.md。可选依赖组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[enrichment] # Python call-resolution enrichment (Jedi) pip install code-review-graph[eval] # Evaluation benchmarks and SVG export (matplotlib) pip install code-review-graph[wiki] # ollama client (not used by the current wiki generator) pip install code-review-graph[all] # All optional dependencies环境变量变量说明默认值CRG_GIT_TIMEOUTGit 操作的超时秒数build / update / watch30CRG_DISCOVERY_TIMEOUT未显式给出文件清单时用于识别变更的每个 Git 命令的超时秒数。超时会返回错误而不会报告“没有变更”5显式设置CRG_GIT_TIMEOUT时取该值CRG_DATA_DIR存放图谱数据库和生成产物的目录-CRG_HOOK_WORKTREES设为1时允许 pre-commit 钩子在链接的 git worktree 中运行-CRG_EMBEDDING_MODEL本地向量嵌入的默认模型all-MiniLM-L6-v2CRG_ACCEPT_CLOUD_EMBEDDINGS设为1可抑制云端嵌入的出网警告-CRG_ALLOW_REMOTE_CODE允许需要trust_remote_codeTrue的 HuggingFace 模型0CRG_MAX_IMPACT_NODES影响分析中的最大节点数500CRG_MAX_IMPACT_DEPTH影响半径分析的搜索深度2CRG_MAX_BFS_DEPTH图谱遍历的最大深度15CRG_MAX_CHANGED_FUNCS单份变更报告中分析的最大变更函数数500CRG_MAX_TRANSITIVE_FRONTIER传递性调用者/被调用者扩展的最大前沿规模50CRG_CALLER_TEST_ROUTE_DEPTH为没有测试的变更符号向上回溯CALLS寻找已测试调用者的跳数。仅作为提示报告不计为覆盖率2CRG_CALLER_TEST_ROUTE_MAX_CALLERS寻找该已测试调用者时检查的调用者数量上限500CRG_TOOL_TIMEOUT只读 MCP 工具的超时秒数0表示禁用。不限制写入类工具build、postprocess、embed、wiki 和 apply-refactor0CRG_CHURN_WINDOW_DAYSdetect-changes --churn统计提交数的时间窗口90CRG_LEIDEN_SEEDLeiden 社区检测的随机种子42CRG_RECURSE_SUBMODULES设为1、true或yes时包含 git 子模块-CRG_TOOLS提供服务时暴露的 MCP 工具白名单逗号分隔-GOOGLE_API_KEYGoogle Gemini 嵌入的 API 密钥-MINIMAX_API_KEYMiniMax 嵌入的 API 密钥-VOYAGE_API_KEYVoyage 嵌入的 API 密钥-CRG_VOYAGE_MODELVoyage 嵌入使用的模型voyage-code-3CRG_VOYAGE_OUTPUT_DIMENSIONVoyage 嵌入的输出维度1024CRG_VOYAGE_OUTPUT_DTYPEVoyage 嵌入的输出 dtypefloatCRG_VOYAGE_BASE_URLVoyage 嵌入端点https://api.voyageai.com/v1CRG_VOYAGE_BATCH_SIZEVoyage 请求的批大小100CRG_VOYAGE_MIN_INTERVAL_SECVoyage 请求之间的最小间隔0CRG_OPENAI_BASE_URLOpenAI 兼容的嵌入端点-CRG_OPENAI_API_KEYOpenAI 兼容嵌入的 API 密钥-CRG_OPENAI_MODELOpenAI 兼容嵌入使用的模型-CRG_OPENAI_DIMENSION固定嵌入维度v3 模型支持降维-CRG_OPENAI_BATCH_SIZEOpenAI 兼容请求的批大小100NO_COLOR关闭终端中的 ANSI 颜色-CRG_SERIAL_PARSE设为1可关闭并行解析用于调试-OpenAI 兼容嵌入OpenAI、Azure或自建网关如 new-api、LiteLLM、vLLM、LocalAI或 OpenAI 模式下的 Ollama无需额外安装。设置变量并给embed_graph传入provideropenaiexport CRG_OPENAI_BASE_URLhttp://127.0.0.1:3000/v1 # or https://api.openai.com/v1 export CRG_OPENAI_API_KEYsk-... export CRG_OPENAI_MODELtext-embedding-3-small # whatever your gateway serves # optional: export CRG_OPENAI_DIMENSION1536 # pin dim (v3 models support reduction) export CRG_OPENAI_BATCH_SIZE100 # lower for gateways with tight limits # (e.g. Qwen text-embedding-v4 caps at 10)当 base URL 指向 localhost127.0.0.1、localhost、0.0.0.0、::1时会跳过云端出网警告。Voyage 嵌入无需额外安装。设置VOYAGE_API_KEY并给embed_graph传入providervoyage默认模型是voyage-code-3export VOYAGE_API_KEYpa-... export CRG_ACCEPT_CLOUD_EMBEDDINGS1 code-review-graph embed --provider voyage --model voyage-code-3模型选择。对于打算长期保留的索引避免使用-preview、-beta或-exp结尾的模型 ID预览模型可能更换权重维度一变就要全量重新嵌入或被下架。请优先选择正式发布的模型例如text-embedding-3-small/text-embedding-3-largeOpenAI、Qwen/Qwen3-Embedding-8B自建 vLLM 或 LocalAI或gemini-embedding-001原生 Gemini 提供方需要GOOGLE_API_KEY。嵌入文本包含标识符、签名、结构上下文以及有长度上限的首段 docstring 或文档注释摘要。函数体不会被发送。在文档提取功能加入之前创建的图谱需要先完整执行一次code-review-graph build再重新嵌入。常规构建不会刷新嵌入要在构建后刷新请同时传入--embedding-provider和--embedding-model。云端提供方会收到这些由源码派生的文本并可能据此收费。工具过滤CRG 默认暴露 30 个 MCP 工具。要把服务器限制到一个子集使用--tools或CRG_TOOLS环境变量# CLI flag code-review-graph serve --tools query_graph_tool,semantic_search_nodes_tool,detect_changes_tool # Environment variable CRG_TOOLSquery_graph_tool,semantic_search_nodes_tool code-review-graph serve命令行参数优先于环境变量。两者都未设置时所有工具都可用。在 MCP 客户端配置中{ mcpServers: { code-review-graph: { command: code-review-graph, args: [serve, --tools, query_graph_tool,semantic_search_nodes_tool,detect_changes_tool,get_review_context_tool] } } }常见问题与对比答案见 docs/FAQ.md对比 LSP / 语言服务器一张持久的跨语言图谱而不是每种语言一个守护进程LSP 在单个符号上仍然更精确。对比 RAG / 嵌入从 AST 解析出的结构化边而不是相似度分块嵌入是可选的只辅助搜索。对比 grep / 智能体搜索单跳查找 grep 更快多跳问题影响半径、调用者的调用者、tests-for、受影响的执行流图谱更强。对比 Serena、codegraph、claude-context、repomix对比表格。什么时候不要用它小仓库、琐碎的单文件 diff、一次性问题。它会回传数据吗没有遥测云端嵌入需要主动开启。怎么确认它在工作status、detect-changes --brief、/mcp。故障排查更多情况包括 Windows/WSL见 docs/TROUBLESHOOTING.md。pip/pipx无法下载hatchling或出现Errno 9/Bad file descriptor连 PyPI 的错误从源码树安装例如pipx install .需要从 PyPI 取构建依赖。如果在一堆连接警告之后看到Could not find a version that satisfies the requirement hatchling那么该终端里的 Python 可能无法与pypi.org建立 HTTPS 连接。这在编辑器的集成终端里最常见有时也与 VPN、防火墙或代理有关。改用 Terminal.app 或 iTerm 运行同一条命令而不是编辑器的终端。用 uv 从 checkout 安装它使用不同的下载机制cd /path/to/code-review-graph uv tool install . --force在克隆中做开发时使用uv sync和uv run code-review-graph ...。诊断方法python3 scripts/diagnose_pypi_connectivity.py。如果它打印FAILED问题出在网络环境而不是包名。WindowsInvalid JSON: EOF while parsing或MCP error -32000: Connection closed不要在 Claude Code 配置中使用cmd /c包装。让~/.claude.json直接指向.exe并通过配置设置 UTF-8code-review-graph: { command: C:\\path\\to\\your\\venv\\Scripts\\code-review-graph.exe, args: [serve, --repo, C:\\path\\to\\your\\project], env: { PYTHONUTF8: 1 } }参与贡献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] pytestPull request 请提交到staging默认分支。变更按staging→testing→main的顺序推进版本从main打标签。完整流程见 CONTRIBUTING.md。要添加内置语言编辑code_review_graph/parser.py把扩展名加入EXTENSION_TO_LANGUAGE并把节点类型映射加入_CLASS_TYPES、_FUNCTION_TYPES、_IMPORT_TYPES和_CALL_TYPES。附上测试 fixture 并提交 PR。如果某种语言只在一个仓库里需要请改用 languages.toml。
