code-review-graph 详细指南

版本 2.3.8~2.3.8 ｜分类 gate ｜安全（已审查）｜素材：项目官方文档（中文 README.zh-CN.md）+ 本市场实测（2026-08-28）
配套：站内文档（manifest + guide + 证据）｜快速版：站内文档

1. 场景：什么时候会用它

code-review-graph（tirth8205 出品，MIT，约 3.1 万星）是本地优先的代码智能图谱：用 tree-sitter 把你的代码库解析成图（函数、类、导入为节点；调用、继承、测试覆盖为边），审查时只把 AI 需要的文件喂给它——省 token、提效率。它提供 MCP 和 CLI 两种接入，还有官方中文文档。

一句话：让 AI 审代码时"只看该看的"，而不是把整个仓库塞进上下文。

这个工具解决什么问题：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 可完整清理。

2. 能力清单

能力	作用
build/update	全量/增量图谱构建
query/impact/search	图查询、影响面分析、语义搜索
dead-code/refactor	死代码与重构建议
mcp/serve	MCP server 与本地服务
watch	文件变化自动更新
tree-sitter 代码图谱	见 Agent 执行版 guide
MCP 集成	见 Agent 执行版 guide
死代码/影响分析	见 Agent 执行版 guide
官方中文文档	见 Agent 执行版 guide

3. 快速安装

note: 本环境实测路径；国内必须带清华镜像（PyPI 官方超时，探针 2026-08-27）

# 来源: Trove 详细指南 · 验证于 2026-08-28
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

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

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
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 侧的挂接已就位。

# 来源: Trove 详细指南 · 验证于 2026-08-28
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 已经够用。

安装变体

路径	命令	实测
主路径（实测）	`pip install -i https://pypi.tuna.tsinghua.edu.cn/simple code-review-graph==2.3.8…`	✅ 本市场实测
镜像/代理	见快速版与 semi_auto_note；国内安装按 code-review-graph 指引	实测

半自动说明：实测命令 = pip install -i 清华镜像 code-review-graph==2.3.8（2026-08-28 本环境验证，隔离 venv，Python 3.14）；国内必须带清华镜像（PyPI 官方超时）；可选 pipx 安装（官方推荐，本机未实测）；code-review-graph install 会向 Claude/Codex/Cursor/OpenCode 注册 MCP/hooks（写 ~/.claude.json、~/.codex/hooks.json、工作区 .mcp.json 等，见 guide 共享面）；crg-daemon 为后台进程

非 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 增量即可。

4. 为什么会这样（机制与共享面）

它怎么工作：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。

工作区：.code-review-graph/（SQLite 图数据）、.claude/settings.json（mcpServers 段）、.mcp.json（MCP 注册）
HOME：~/.claude.json（mcpServers）、~/.codex/hooks.json、~/.cursor/mcp.json + hooks、~/.config/opencode/plugins/crg-plugin.ts
运行时：watch/daemon 模式后台进程

5. 常用操作

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

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
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 审查就能用图谱定位影响面。

# 来源: Trove 详细指南 · 验证于 2026-08-28
code-review-graph build

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
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——这一步会写多平台配置，装前想清楚要不要全平台注册。

# 来源: Trove 详细指南 · 验证于 2026-08-28
code-review-graph watch

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
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 面）。

启动与入口

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

常用操作

操作一：构建代码图谱

# 来源: Trove 详细指南 · 验证于 2026-08-28
code-review-graph build

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

操作二：查看图谱统计

# 来源: Trove 详细指南 · 验证于 2026-08-28
code-review-graph status

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

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
code-review-graph watch

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

操作四：改动影响面分析（只读，改代码后随时跑）

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
code-review-graph detect-changes

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

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
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。

6. 冲突逐条（摘要）

与工具页矩阵同源，共 19 对（6 实测兼容 / 10 推断可能兼容 / 3 推断可能冲突）；完整对子、状态与证据见冲突对子（共装矩阵）。

7. 排障速查

暂无独立排障手册；安装/卸载问题先看 Agent 执行版 guide 注意事项

8. 卸载与残留检查

# 来源: Trove 详细指南 · 验证于 2026-08-28
code-review-graph uninstall 2>/dev/null || true; pip uninstall -y code-review-graph

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

# 来源: Trove 详细指南 · 验证于 2026-08-28
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（同上）

9. FAQ

运行环境预检（需 Python >= 3.10）
官方 pip 路径（本环境实测）；国内必须带清华镜像（PyPI 官方超时，探针 2026-08-27）
可选 pipx install code-review-graph（官方推荐，本机未实测）；install 子命令会注册 MCP/hooks（多平台写面，见 FAQ）
每条操作 = 一个命令块 + 预期输出；在目标代码仓库内执行
多注册面：install 会写 4 个平台的 MCP/hooks 配置；官方 code-review-graph uninstall 可完整清理

问：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 模板）；项目自身问题请向作者仓库反馈。

版本：[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。

10. 出处

条目签名：tirth8205/code-review-graph（MIT，原样收录 v2.3.8）

实测：实测记录（本地留存）（2026-08-28，pip 安装 + version/help 冒烟）；实测复现日志（2026-08-30）（2026-08-30，隔离仓库全链路：build 5 文件 → 9 节点/16 边、status 统计、detect-changes 影响面、watch 增量 9→10 节点/16→18 边；另实测非 git 目录不报错但 0 edges）。
未实测：install 多平台注册（需对应平台环境，本环境未跑不污染真实注册面）；pipx 安装路径（命令面与 pip 一致）。

外部教学（来源未实测）

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

博客园：code-review-graph 完整上手攻略——lsgxeva（转载自某内容平台专栏） [博客园 · lsgxeva（页面署名；原文标注转载自内容平台专栏，原作者未在页面体现） · 2026-05-17]
本地代码知识图谱 + MCP 接入的完整教学——为什么 AI 需要代码地图（上下文成本）、工作原理（Tree-sitter 解析→节点/边）、安装（pip/pipx、install --platform claude-code 注册 MCP）、核心操作（build 全量构建 / update 增量更新 / watch 监听自动更新 / status 图谱统计 / visualize 交互可视化 + graphml/svg/obsidian/cypher 导出 / detect-changes 变更影响分析 / serve MCP 服务器 / daemon 守护进程）

收录来源（已合并）

本页内容由多篇来源文章按哈希去重、实测验证、AI 重写后合并而来——来源不散落，全部挂在这一个页面上。

暂无已合并来源：本页为本地实测与多来源重写的沉淀；来源与验证细节见站内对应方案页。

← 返回 code-review-graph 方案页｜代码审查问题域