code-review-graph 中文教程：先核对图，再让 Agent 依赖它

code-review-graph 用 Tree-sitter 抽取函数、类、导入、调用、继承和测试关系，存进项目本地 SQLite，再通过 MCP 向 AI 编码工具提供影响范围和执行流。它解决的是“该读哪些代码”，不能证明业务行为一定正确。

1. 固定版本，安装到隔离环境

python3 -m venv .venv-crg
source .venv-crg/bin/activate
pip install 'code-review-graph==2.3.9'
code-review-graph --version

官方也支持 pipx 和 uvx。固定版本能避免 main 和最新 wheel 在 schema、客户端配置或语言解析上发生变化。生产仓库还应核对 PyPI 包来源与 release tag。

2. 第一次只配置一个客户端

code-review-graph install --platform codex --no-instructions

install 可能写 MCP 配置、hooks、skills 和平台规则文件。--platform 把范围限制到一个客户端，--no-instructions 跳过规则注入。运行前后查看用户配置和仓库 diff，确认没有覆盖已有 MCP server 或 instructions。

3. 建图后先做结构抽查

code-review-graph build
code-review-graph status

默认图数据库位于项目 .code-review-graph/graph.db。选择三类已知事实来检查：一个公共函数的调用方、一条跨模块执行流、一项测试覆盖关系。若这些基本关系都缺失，应先查语言识别、ignore 规则和图的新鲜度，不要急着比较 token 数。

4. 正确理解空结果

v2.3.9 给 query_graph、get_impact_radius 和 semantic_search_nodes 的空结果增加 confidence 说明。它会区分从未建图、图落后工作区、语言静态分析缺口和确认后的真实空集。看到 0 时应把原因和 status 一起交给 Agent，避免把“没有解析到”写成“没有影响”。

5. 官方 benchmark 应怎样使用

项目当前强调约 82 倍的 median context reduction，并把 528 倍标为最佳案例。v2.3.6 和 v2.3.5 提供固定上游 commit、失败 run 排除规则与 tiktoken 校验方法。这让结果更容易复现，但仍是项目方 benchmark。应在自己的仓库选择几类真实任务，记录图上下文、完整搜索、答案正确率和耗时，再决定是否有净收益。

6. CI 与云 embeddings 分开评估

官方 GitHub Action 在 CI runner 上建图和查询，文档明确说不把源代码发送给外部服务。先只发布 sticky comment，观察风险表和测试空白是否稳定，再考虑 fail-on-risk。语义搜索的 embedding 是另一条数据路径；选择 Voyage 等云 provider 时，相关文本会发送到供应商，不应沿用“全本地”的判断。

7. 相比 brooks-lint 怎么选

brooks-lint 用 12 本工程著作和固定风险分类约束语言模型审查，适合统一架构与技术债提问方式。code-review-graph 从源码抽取结构事实，适合找调用链、影响范围和测试关系。图工具能缩小上下文，skills 能规范最终评语；任何一方都不能替代测试和人工 review。

8. 验证状态与验证边界

未验证：安装写入、建图速度、语言覆盖、影响半径、MCP、图更新、token benchmark、可视化、CI 和云 embedding 数据路径。

常见问题