你会遇到什么

这个工具解决什么问题：AI 做代码审查时「看太多」或「看漏了」。code-review-graph 在本地把代码库构建成知识图谱（tree-sitter 解析，SQLite 存储到工作区 .code-review-graph/），让 AI 只审查相关代码——改一个函数，它能告诉你这个改动影响哪些文件。 什么时候用：

• 你要给 AI 审查提供「影响面」上下文（改 A 会影响 B）；
• 你要在代码库内跑 build 建图、watch 增量监听、status 看统计；
• 你要把图谱注册成 MCP server 给 Claude/Codex/Cursor 用（install）。

什么时候别用：小仓库、单文件改动，图谱带来的收益小于建图成本时。 注意事项：多注册面重件——install 会向检测到的平台注册 MCP/hooks（写 ~/.claude.json、~/.codex/hooks.json 等），官方 uninstall 可完整清理。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：pip 安装 CLI（也可 pipx，官方推荐，本机未实测）。在工作区（git 仓库）内 build 全量建图（tree-sitter 解析 → SQLite），watch 增量监听文件变化（后台 crg-daemon），status 看统计，detect-changes 只读分析改动影响面（改 A 影响 B）。install 向已检测平台注册 MCP server（多平台写面，见依赖警告）。build/status/detect-changes/watch 已于 2026-08-30 隔离仓库实测。 关键概念：

• 图数据：工作区 .code-review-graph/（SQLite）；
• crg-daemon：watch 模式的后台进程；
• MCP 注册：install 写的多平台配置段。

装完它动哪里：pip 环境 + 工作区 .code-review-graph/；install 后写 ~/.claude.json（mcpServers）、~/.codex/hooks.json、~/.cursor/mcp.json、~/.config/opencode/plugins/crg-plugin.ts、工作区 .claude/settings.json 与 .mcp.json。

一步步来

第 1 步：装 CLI（为什么锁版本：2.3.8 为收录实测版本）

讲解：PyPI 官方直连在本环境超时（探针 2026-08-27），必须带清华镜像前缀；版本锁定 2.3.8 保证与实测一致。装完 --version 验证。

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple code-review-graph==2.3.8
code-review-graph --version

预期输出: code-review-graph 2.3.8

装好确认：

• --version 输出 2.3.8；
• 在 git 仓库内 code-review-graph --help 能看到 build/status/watch/install 等子命令。

卡住怎么办：

• pip 装不上 → 确认 Python >= 3.10；换清华镜像前缀重试；
• 命令找不到 → venv 场景先激活 venv。

第 2 步：建图 + 看统计（核心用法，在目标代码仓库内执行）

讲解：build 全量解析代码库生成图谱（首次较慢属正常）；status 看节点/边/文件统计。之后 AI 审查就能用图谱定位影响面。

code-review-graph build

预期输出: 解析进度 + 统计（实测样例：Full build: 5 files, 9 nodes, 16 edges；工作区出现 .code-review-graph/graph.db）

code-review-graph status

预期输出: 节点/边/文件统计（实测样例：Nodes: 9 / Edges: 16 / Files: 5 / Languages: javascript, python / Built at commit: …）

装好确认：

• build 完成后 .code-review-graph/ 出现图数据；
• status 有节点/边统计输出。

卡住怎么办：

• build 很慢 → 首次全量解析属正常；之后用 watch/update 增量；
• 非 git 仓库 → 实测 build/status 不报错（2026-08-30）但跨文件引用解析不出（样例：1 file → 0 edges），影响面分析无意义；要完整图，cd 到 git 仓库根目录再跑。

第 3 步：增量监听 + 注册 MCP（按需）

讲解：watch 监听文件变化增量更新（后台 crg-daemon，Ctrl+C 退出；2026-08-30 实测改文件 ~2s 内自动增量）；detect-changes 只读分析当前未提交改动的影响面（改 A 影响 B，不需要重新建图）；install 向已检测平台注册 MCP server——这一步会写多平台配置，装前想清楚要不要全平台注册。

code-review-graph watch

预期输出: Watching … for changes… (Ctrl+C to stop)（实测：改文件后 ~2s 自动增量，节点/边计数上升）

code-review-graph install

预期输出: 向已检测平台注册 MCP server（写 ~/.claude.json、~/.codex/hooks.json 等）

装好确认：

• watch 模式有文件变化日志；
• install 后对应平台配置出现 code-review-graph 段（~/.claude.json mcpServers 等）。

卡住怎么办：

• install 后平台不认 → 检查对应平台配置文件（~/.claude.json / ~/.codex/hooks.json / ~/.cursor/mcp.json / ~/.config/opencode/plugins/crg-plugin.ts）；
• 不想全平台注册 → 不跑 install，只用 build/status/watch（CLI 面）。

怎么确认修好了

第 1 步：确认图谱已建起来

讲解：build 成功后工作区出现 .code-review-graph/ 目录（SQLite 图数据），这是「图建好了」最直接的证据。

ls -d .code-review-graph 2>/dev/null && echo "graph dir: OK" || echo "graph dir: MISSING"
code-review-graph status

预期输出: graph dir: OK 以及节点/边/文件统计

卡住怎么办：

• 目录不存在 → 回到「一步步来」第 2 步重跑 build，确认在 git 仓库根目录执行；
• status 报错 → 检查当前目录是否有图数据（在别的目录跑 status 读不到本仓库的图）。

第 2 步：确认 AI 真能用上（如果注册了 MCP）

讲解：install 后检查对应平台配置里出现 code-review-graph 段，说明 AI 侧的挂接已就位。

grep -l "code-review-graph" ~/.claude.json ~/.codex/hooks.json ~/.cursor/mcp.json 2>/dev/null || echo "check config files manually"

预期输出: 至少一个配置文件路径（有注册的平台）；都没有则说明未注册

卡住怎么办：

• 平台配置里没有 → 重跑 install，确认该平台被检测到；
• 只想用 CLI 不想注册 → 跳过 install，build/status/watch 已经够用。

其它环境的表现（常见变体）

• 非 git 仓库：实测 build/status 不报错（2026-08-30），但解析不出跨文件引用（样例：1 file → 0 edges）——影响面分析无意义；仍建议在 git 仓库根目录跑以获得完整图。
• Windows / macOS：pip 安装命令一致（仍建议带清华镜像）；MCP 配置文件路径与 Linux 不同（Windows 下 ~/.claude.json 在用户目录、.cursor 配置在 %USERPROFILE%），uninstall 清理逻辑一致。
• venv / conda：装完命令找不到时先激活虚拟环境；pipx 安装是官方推荐路径（本机未实测，命令面与 pip 一致）。
• 首次建图耗时：仓库越大首次 build 越慢，属正常；之后用 watch/update 增量即可。

日常使用

启动与入口

CLI 在目标代码仓库内调用；watch 模式后台监听。

常用操作

操作一：构建代码图谱

code-review-graph build

预期输出: 解析进度 + 统计（实测样例：Full build: 5 files, 9 nodes, 16 edges；工作区出现 .code-review-graph/graph.db）

操作二：查看图谱统计

code-review-graph status

预期输出: 节点/边/文件统计（实测样例：Nodes: 9 / Edges: 16 / Files: 5 / Languages: javascript, python / Built at commit: …）

操作三：增量更新（监听文件变化）

code-review-graph watch

预期输出: Watching … for changes… (Ctrl+C to stop)（实测：改文件后 ~2s 自动增量，节点/边计数上升）

操作四：改动影响面分析（只读，改代码后随时跑） 讲解：detect-changes 不重新建图，只读分析当前未提交改动影响了哪些函数/文件（输出 JSON：影响面列表 + risk_score + 上下文节省估算）。实测在 5 文件小仓库上直接可用（2026-08-30）。

code-review-graph detect-changes

预期输出: JSON 影响面报告（受影响函数/文件 + risk_score 字段）

操作五：注册 MCP（多平台）

code-review-graph install

预期输出: 向已检测平台注册 MCP server（写 ~/.claude.json、~/.codex/hooks.json 等）

数据与目录

• 图数据：工作区 .code-review-graph/（SQLite，卸载前确认是否需要备份）；
• 注册面：~/.claude.json（mcpServers）、~/.codex/hooks.json、~/.cursor/mcp.json、~/.config/opencode/plugins/crg-plugin.ts、工作区 .claude/settings.json 与 .mcp.json。

卸载与清理

note: 官方 uninstall 子命令完整清理（数据/配置/hooks/skills/MCP 注册），然后 pip 卸载；本市场一键卸载自动执行

code-review-graph uninstall 2>/dev/null || true
pip uninstall -y code-review-graph
command -v code-review-graph >/dev/null 2>&1 && echo "残留: code-review-graph 仍存在" || echo "code-review-graph removed: OK"

预期输出: code-review-graph removed: OK

手动确认清单（如需彻底清理）：

• 工作区 .code-review-graph/（图数据，卸载前确认是否需要备份）
• ~/.claude.json 的 code-review-graph mcpServers 段（官方卸载应已清；残留可手动删）
• ~/.codex/hooks.json / ~/.cursor/mcp.json / ~/.config/opencode/plugins/crg-plugin.ts（同上）

依赖警告

• 版本：[2.3.8, 2.3.8] 锁定（收录实测版本）。
• 环境：Python >= 3.10；建图依赖仓库结构（git 仓库内执行）。
• 网络：PyPI 官方超时（探针 2026-08-27），必须清华镜像。
• 写面（多）：工作区 .code-review-graph/ + install 后的多平台注册段（~/.claude.json / ~/.codex/hooks.json / ~/.cursor/mcp.json / ~/.config/opencode/plugins/crg-plugin.ts / 工作区 .claude/settings.json 与 .mcp.json）。
• 共装：与 ruflo / omc / agt 判定 possible-conflict（都与 ~/.claude.json 或工作区 .claude/settings.json/.mcp.json 同文件写面，不同 key/段，共装未实测）；与 deepcode / superpowers / claude-code-router 判定 possible-compatible。

FAQ（常见问题）

• 问：install 会改我的什么配置？答：向检测到的平台注册 MCP/hooks：~/.claude.json（mcpServers）、~/.codex/hooks.json、~/.cursor/mcp.json、~/.config/opencode/plugins/crg-plugin.ts、工作区 .claude/settings.json 与 .mcp.json——全部可被官方 uninstall 清理。
• 问：和 ruflo/omc/agt 一起装会冲突吗？答：判定 possible-conflict——都与 ~/.claude.json 或工作区 .claude/settings.json/.mcp.json 同文件写面（不同 key/段），共装未实测；建议先装一个跑通。
• 问：构建很慢？答：首次 build 全量解析属正常；之后用 watch/update 增量。
• 问：国内 pip 装不上？答：用安装段的清华镜像前缀（PyPI 官方在本环境超时）。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口（usage-report 模板）；项目自身问题请向作者仓库反馈。