code-review-graph 故障排查全指南从安装报错、数据库锁到 Watch 守护进程的完整修复手册【免费下载链接】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导读本文是 code-review-graph面向 MCP 与 CLI 的本地优先代码知识图谱工具的官方故障排查手册的深度展开版覆盖安装/配置期、构建期、运行期三大阶段的高频问题包括 hook schema 报错、command not found、venv 路径硬编码、图被“污染”poisonedgraph.db、Watcher 停摆等。读完本文你将掌握一条可复现的排障路径先用code-review-graph status快速定位问题层CLI / MCP / 数据库 / 守护进程再按对应章节给出的命令与配置逐项修复并理解每类问题背后的源码实现依据SQLite WAL、增量更新回退、Watch 健康心跳等从而在大型仓库、多仓库与 WSL/Windows 环境下独立解决问题。一、安装与配置期先查这四个高频问题官方排查手册明确指出绝大多数支持问题只集中在四个场景。在深入任何疑难杂症之前先按顺序核对它们通常能直接命中根因。1.1.claude/settings.json报Hooks use a matcher hooks array错误症状Claude Code 在启动或调用 hook 时报 schema 校验错误错误信息包含Hooks use a matcher hooks array。根因你安装的是v2.2.3 之前的版本。v2.2.1 与 v2.2.2 发布过一个损坏的 hook 生成 schema——它生成的是扁平的{matcher, command, timeout}条目缺少 v1.x 所要求的嵌套hooks: []数组同时把超时单位写成了毫秒而非秒还引入了一个并不存在的PreCommit事件Claude Code 没有这个事件。该问题由 PR #208 修复随 v2.2.3 发布。修复步骤pip install --upgrade code-review-graph # → v2.2.4 或更高版本 cd /path/to/your/project code-review-graph install # 重写 .claude/settings.json重新执行install会合并替换整个损坏的hooks块为新的嵌套格式并把真正的 git pre-commit hook 写入 hooks 目录。该目录通过git rev-parse --git-path hooks解析——通常是.git/hooks/pre-commit但链接工作树linked worktrees与core.hooksPath如 husky配置也能被正确处理。也就是说从 v2.2.3 起“提交前检查”的逻辑位于 git hooks 目录而不是 Claude Code 的 settings 里。验证依据当前仓库hooks/hooks.json展示了正确的 v1.x 嵌套 schema——顶层是事件名如SessionStart、PostToolUse每个事件下是 matcher 数组matcher 内才是hooks: []数组每个 hook 包含type: command、command与可选的timeout秒{ SessionStart: [ { matcher: , hooks: [ { type: command, command: cat /dev/null || true; code-review-graph status, timeout: 10 } ] } ] }Claude Code 合法的 hook 事件集合是PreToolUse、PostToolUse、UserPromptSubmit、Stop、SubagentStop、SessionStart、SessionEnd、PreCompact、Notification。没有PreCommit——如果你在配置里看到它说明版本过旧。1.2pip install后报code-review-graph: command not found根因pip install把 console script 装进了某个bin/目录但它不在你的$PATH里。四种修复方式按推荐程度排序方案 1 —— 用pipx最干净pipx将 CLI 工具装在隔离 venv 中不污染全局 Pythonpip uninstall code-review-graph pipx install code-review-graph若装完仍找不到命令执行pipx ensurepath或把~/.local/bin加入 PATH。方案 2 —— 用uvx免安装无需安装即可直接运行适合临时验证uvx code-review-graph install uvx code-review-graph build方案 3 —— 以 Python 模块方式运行永远可用python -m code_review_graph install python -m code_review_graph build方案 4 —— 手动修正 PATHpip show code-review-graph | grep Location # 找到同级的 bin/ 目录macOS 用户安装通常在 # ~/Library/Python/3.X/bin。加入 shell rc echo export PATH$HOME/Library/Python/3.12/bin:$PATH ~/.zshrc source ~/.zshrc补充约束从源码看CLI 入口 在导入任何其他模块前会强制检查sys.version_info (3, 10)Python 低于 3.10 会直接打印提示并退出——这也是command not found之外另一个常见的“命令装了却跑不起来”的原因pyproject.toml中requires-python 3.10与之对应。1.3 code-review-graph 是项目级作用域还是用户级作用域两者都是——它由四块作用域完全不同的部分组成组成部分作用域位置Python 包本体用户级通过pip/pipx/uvx安装一次即可图谱数据库项目级每个项目内的.code-review-graph/graph.dbMCP server 配置.mcp.json项目级Claude Code 为每个项目启动一个 MCP servercwdproject多仓库注册表用户级~/.code-review-graph/registry.json仅用于cross_repo_search一句话总结工具只装一次然后在每个需要图谱感知评审的项目里各执行一次code-review-graph install code-review-graph build。1.4 使用 venv必须手动更新settings.json根因.claude/settings.json中的 Claude Code hooks 与 MCP 工具路径在安装时被硬编码。如果运行code-review-graph install之后才切换到或新建虚拟环境路径仍指向旧解释器server 会静默失败或使用错误的 Python。修复把.mcp.json中的command/args以及.claude/settings.json里的任何 hook 命令改成指向你的 venv// .mcp.json —— 指向 venv 内的 Python 或 venv 内的 uvx { mcpServers: { code-review-graph: { command: /path/to/your/venv/bin/uvx, args: [code-review-graph, serve] } } }或者更简单——在激活的 venv 内重新执行install让路径按新解释器重新生成source .venv/bin/activate # 先激活 venv code-review-graph install # 重写 .mcp.json 与 hook 路径改完后彻底退出并重新打开 Claude Code让它加载新配置。1.5 “图建好了但新会话里 Claude Code 看不到”按可能性从高到低排查install之后没重启 Claude CodeClaude Code 在启动时读取.mcp.json——如果在会话内执行了install必须彻底退出并重新打开MCP server 才会注册。新会话的cwd是另一个目录MCP server 以cwdproject启动并从这里读取.code-review-graph/graph.db。如果新会话开在父目录或其他项目里自然找不到你刚建的图。只跑了build没跑installbuild生成graph.dbinstall才是通过.mcp.json向 Claude Code 注册 MCP server 的那一步。两者缺一不可。MCP server 启动即崩溃在 Claude Code 里执行/mcp查看 server 状态macOS 上也可检查~/Library/Logs/Claude/mcp*.log。快速核对清单cd /path/to/your/project code-review-graph status # 应打印已建图的 Files/Nodes/Edges ls .mcp.json # 应存在 cat .mcp.json # 应引用 code-review-graph serve # 然后彻底退出 Claude Code并在该项目内重新打开如果status能看到图、但新会话的/mcp里没有code-review-graph说明.mcp.json不在该会话的cwd下——在正确的项目根目录重新执行code-review-graph install即可。二、数据库锁错误SQLite WAL 模式下的正确姿势图谱使用SQLite 且开启 WAL 模式PRAGMA journal_modeWAL在 graph.py 中强制设置。遇到锁错误时确保同一时刻只有一个 build 进程在运行数据库会自动恢复——直接重试即可若确实损坏删除.code-review-graph/graph.db-wal与.code-review-graph/graph.db-shm这两个 WAL 伴生文件后再重试。原理补充WAL 模式把写操作追加到-wal文件允许读与写并发这正是watch增量更新与status/visualize等只读命令能同时运行的基础。多进程同时写才会触发锁冲突因此“单 build 进程”是硬性约束。三、大型仓库超过 1 万文件的性能调优首次全量构建可能需要 30–60 秒这是正常的它要解析整棵代码树之后的增量更新很快在约 3,000 文件的仓库上hook 路径约2.5 秒可参考 REPRODUCING.md 的复现说明在.code-review-graphignore中增加更多忽略模式把生成物与第三方代码排除在图谱之外generated/** vendor/** *.min.js忽略模式的加载实现在 incremental.py它读取仓库根目录的.code-review-graphignore文件在解析阶段就把匹配文件过滤掉——所以这些模式不仅能加快构建还能让semantic_search_nodes_tool等检索工具的命中质量更高。四、构建后缺失节点Missing nodes按以下顺序排查确认文件语言受支持查看 FEATURES.md 中的语言支持清单覆盖 Java、Kotlin、PHP/Laravel、Ruby、Rust、Julia、Zig、Ansible、HCL 等社区可在 CUSTOM_LANGUAGES.md 自定义确认文件没有被忽略模式命中检查.code-review-graphignore及!例外行强制完整重解析在 MCP 工具中调用build_or_update_graph_tool时设置full_rebuildTrue。实现细节full_rebuildTrue会绕过增量路径触发全量 re-parse。从 tools/build.py 看增量更新还有两道内置防线当 store 里没有任何节点not store.has_nodes()或无法解析 diff base 时即使未显式要求也会自动回退为全量重建——这一点与下文“空图修复”直接相关。五、空或不完整的图poisonedgraph.db背景旧版本在某些命令status、detect-changes、visualize、wiki、watch在首次全量 build之前运行时会创建一个空的.code-review-graph/graph.db。随后的增量update只 re-parse 变更过的文件导致图谱一直不完整却看起来“有效”——这就是“中毒”的数据库。当前 CLI 行为v2.2.4status、detect-changes、visualize、wiki、watch在数据库不存在时不再创建它而是直接退出并提示No graph found … Run code-review-graph build first.实现见 cli.py 与 cli.pystatus无图时以退出码 1 结束且不建库update会自动修复缺失或零节点的图——检测到异常时回退到全量重建参见 tools/build.py 的full_rebuild回退逻辑。如果图已经被污染schema 存在、也有部分节点但索引文件数远少于仓库实际文件数——例如只有空库创建后被改动的文件执行一次完整重建code-review-graph buildbuild始终重新解析整棵代码树——没有单独的--force标志这一点与某些工具的语义不同值得注意。重建之后update/ hooks /watch就可以安全地继续走增量路径了。六、图看起来过时Graph seems stalehooks 会在编辑/提交时自动更新见 hooks/hooks.jsonPostToolUse的Write|Edit|Bashmatcher 触发code-review-graph update --skip-flowsSessionStart触发status若仍感觉陈旧手动执行/code-review-graph:build-graph或code-review-graph update检查 hooks 是否确实配置在.claude/settings.json中——不确定就重跑code-review-graph install重新生成。七、Watcher 在运行但图停止更新了核心疑难这是排障手册中实现细节最丰富的部分。crg-daemon status在进程Status列旁边增加了一个Watcher列并显示每个 watcher 处理最后事件的时间Alias Status Watcher PID Event Path backend alive stalled 48213 3d /work/backendWatcher列的取值语义如下状态含义处理方式ok文件系统观察器observer在运行并持续发布心跳无需处理stalled进程还活着但 observer 线程死了什么都没在索引先crg-daemon logs --repo ALIAS看日志再crg-daemon restartpartialwatcher 用完了 watch 槽位退化为一个递归 watch。仍然完整但不再过滤被忽略的目录提高CRG_MAX_WATCH_SCHEDULES恢复过滤unknownwatcher 尚未发布健康信息刚启动或早于本功能引入的版本稍候再查dead进程本身已退出守护进程会自动重启带指数退避源码佐证健康判定实现在 daemon.py 的watcher_status()进程不活即dead从未发布健康文件即unknown心跳过期CRG_WATCH_HEALTH_STALE默认 90 秒或 observer 报告死亡即stalleddegraded标记则归类为partial。stalled的检测非常关键——daemon.py 注释明确指出observer 线程死亡时进程仍活着仅靠poll()会永远显示健康所以每个 watch 子进程会向~/.code-review-graph/watch-health/发布自身状态与最后事件时间。关于“死 watcher”的判定watcher 一旦检测到自己的 observer 死亡会记录错误并以非零状态退出让守护进程重启它对应 issue #811而不是安静地卡住。有两类情况不算死 watcher因为它们属于正常作业删除被监视的目录watch 会被释放删除后重建同一目录watch 按inode追踪替换后的目录会被重新监视并重新索引而不是被误判为尸体。一个在其目录确实没有变化时死亡的 watch在 watcher 放弃前会被重新调度一次。Watch 模式如何过滤目录watch 模式只为通过忽略模式筛选的目录注册 OS watch因此node_modules/、.git/和构建产物根本不再产生事件。后来出现/消失的目录通过每个非递归 watch 的每 tick 列表扫描约 0.1 ms发现而不是依赖目录事件——因为 macOS 对非递归 watch 的子目录完全不发目录事件事件驱动设计将永远注意不到新的顶层目录。相关环境变量全部可选变量默认值作用CRG_MAX_WATCH_SCHEDULES24独立 watch 数量上限仓库需要更多时退化为根目录一个递归 watchCRG_WATCH_PLAN_DEPTH3planner 允许拆分的深度CRG_WATCH_SPLIT_MIN_DIRS4值得单独 watch 的最小被忽略目录树规模CRG_RESTART_BACKOFF30s守护进程重启退避初始值CRG_RESTART_BACKOFF_MAX900s退避上限CRG_RESTART_HEALTHY_AFTER600s恢复健康判定时长这些默认值在源码中均有对应_WATCH_PLAN_DEPTH、_MAX_WATCH_SCHEDULES、_WATCH_SPLIT_MIN_DIRS定义于 incremental.py退避参数定义于 daemon.py。指数退避的意义在于一个无法启动的仓库不会每 30 秒就触发一次完整的初始构建。八、某个目录从图中消失了嵌套构建产物自动排除根因嵌套的target/、build/、.next/、.nuxt/目录当同级清单文件pom.xml、Cargo.toml、build.sbt、build.gradle、next.config.*、nuxt.config.*表明它们是构建产物时会被自动当作 build output 排除。每次 build 都会记录排除了什么Excluding 2 nested build-output directories (a sibling manifest marks them as build output; keep one with !path in .code-review-graphignore): moduleA/target, moduleB/target修复如果其中某个目录真的是源码在.code-review-graphignore里用!行保留它!moduleA/target重要语义!行只将该路径从“自动检测”中豁免不会否定你显式写的忽略模式。如需对整个仓库关闭该检测设置CRG_NESTED_OUTPUT_SCAN0实现见 incremental.py。九、Embeddings 不工作语义搜索安装时带上扩展组pip install code-review-graph[embeddings]运行embed_graph_tool或 CLI 的code-review-graph embed --provider local计算向量首次 embedding 运行会下载一次模型约 90MB补充本地 embedding 基于sentence-transformers云端 providerOpenAI 兼容、Google Gemini、MiniMax、Voyage则只用 stdlib HTTP 客户端仅需各自的环境变量不装额外依赖。十、MCP server 无法启动确认uv已安装uv --version未安装时pip install uv或brew install uv验证uvx code-review-graph serve能无错运行若使用自定义.mcp.json确保是command: uvx配合args: [code-review-graph, serve]重跑code-review-graph install重新生成配置十一、Windows / WSL 专项升级到 v2.3.6daemon status在 Windows 崩溃WinError 87issue #511与 CLIdetect-changes映射 0 个函数issue #528都在该版本修复。Windows 上 PID 存活检测使用 Win32 APIOpenProcess/WaitForSingleObject因为os.kill(pid, 0)会路由到GenerateConsoleCtrlEvent并对活进程抛 WinError 87见 daemon.py向 MCP 工具传repo_root时路径使用正斜杠WSL 中确保安装的是WSL 内的 uv而非 Windows 版本curl -LsSf https://astral.sh/uv/install.sh | sh装完 uv 找不到时把~/.cargo/bin加入 PATHcode-review-graph watch在WSL1上可能因文件系统事件限制有延迟推荐 WSL2Windows 原生非 WSL可能需要开启长路径支持git config --system core.longpaths true。十二、按功能所需的可选依赖组ImportError 排查速查表如果某个工具返回ImportError先对照下表确认是否缺少对应的 optional group——这是“Embeddings 不工作”“社区发现不可用”“Wiki 无摘要”等问题的统一根因。依赖声明见 pyproject.toml功能安装命令说明语义搜索本地 embeddingpip install code-review-graph[embeddings]基于 sentence-transformers 的本地向量Google Gemini embeddingspip install code-review-graph[google-embeddings]需要 google-genaiOpenAI 兼容 / MiniMax embeddings仅需环境变量使用 stdlib HTTP 客户端无额外依赖社区检测igraphpip install code-review-graph[communities]无 igraph 时回退为基于文件的粗分组可用但不精确Python 调用解析增强pip install code-review-graph[enrichment]通过 Jedi 实现 Python call-resolution评估基准pip install code-review-graph[eval]需要 matplotlib还有 igraph 相关场景Wiki LLM 摘要pip install code-review-graph[wiki]依赖 ollama无 Ollama 时仅生成结构信息、不含摘要全部pip install code-review-graph[all]一键装齐以上所有组十三、排障流程速览一张图走完现象第一条命令关键修复动作hook schema 报错pip show code-review-graph升级到 v2.2.3 后重跑installcommand not foundpython -m code_review_graph status用 pipx / uvx或修 PATH新会话看不到图ls .mcp.json code-review-graph status重启 Claude Code在正确 cwd 重跑install数据库锁等待并重试删除-wal/-shm伴生文件图不完整code-review-graph status执行code-review-graph build全量重建图陈旧code-review-graph update重跑install恢复 hooksWatcher 停摆crg-daemon status看Watcher列crg-daemon logs --repo后restart目录消失查看 build 日志的 Excluding 行在.code-review-graphignore加!行ImportError对照上表安装对应 optional group最后别忘了仓库是本地优先的几乎所有诊断都可以离线完成——code-review-graph status是整套排查流程的起点它能在一秒内告诉你问题出在 CLI、数据库还是配置层。相关命令全量清单见 COMMANDS.md社区文档入口见 INDEX.md常见问答见 FAQ.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），仅供参考
code-review-graph 故障排查全指南：从安装报错、数据库锁到 Watch 守护进程的完整修复手册
code-review-graph 故障排查全指南从安装报错、数据库锁到 Watch 守护进程的完整修复手册【免费下载链接】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导读本文是 code-review-graph面向 MCP 与 CLI 的本地优先代码知识图谱工具的官方故障排查手册的深度展开版覆盖安装/配置期、构建期、运行期三大阶段的高频问题包括 hook schema 报错、command not found、venv 路径硬编码、图被“污染”poisonedgraph.db、Watcher 停摆等。读完本文你将掌握一条可复现的排障路径先用code-review-graph status快速定位问题层CLI / MCP / 数据库 / 守护进程再按对应章节给出的命令与配置逐项修复并理解每类问题背后的源码实现依据SQLite WAL、增量更新回退、Watch 健康心跳等从而在大型仓库、多仓库与 WSL/Windows 环境下独立解决问题。一、安装与配置期先查这四个高频问题官方排查手册明确指出绝大多数支持问题只集中在四个场景。在深入任何疑难杂症之前先按顺序核对它们通常能直接命中根因。1.1.claude/settings.json报Hooks use a matcher hooks array错误症状Claude Code 在启动或调用 hook 时报 schema 校验错误错误信息包含Hooks use a matcher hooks array。根因你安装的是v2.2.3 之前的版本。v2.2.1 与 v2.2.2 发布过一个损坏的 hook 生成 schema——它生成的是扁平的{matcher, command, timeout}条目缺少 v1.x 所要求的嵌套hooks: []数组同时把超时单位写成了毫秒而非秒还引入了一个并不存在的PreCommit事件Claude Code 没有这个事件。该问题由 PR #208 修复随 v2.2.3 发布。修复步骤pip install --upgrade code-review-graph # → v2.2.4 或更高版本 cd /path/to/your/project code-review-graph install # 重写 .claude/settings.json重新执行install会合并替换整个损坏的hooks块为新的嵌套格式并把真正的 git pre-commit hook 写入 hooks 目录。该目录通过git rev-parse --git-path hooks解析——通常是.git/hooks/pre-commit但链接工作树linked worktrees与core.hooksPath如 husky配置也能被正确处理。也就是说从 v2.2.3 起“提交前检查”的逻辑位于 git hooks 目录而不是 Claude Code 的 settings 里。验证依据当前仓库hooks/hooks.json展示了正确的 v1.x 嵌套 schema——顶层是事件名如SessionStart、PostToolUse每个事件下是 matcher 数组matcher 内才是hooks: []数组每个 hook 包含type: command、command与可选的timeout秒{ SessionStart: [ { matcher: , hooks: [ { type: command, command: cat /dev/null || true; code-review-graph status, timeout: 10 } ] } ] }Claude Code 合法的 hook 事件集合是PreToolUse、PostToolUse、UserPromptSubmit、Stop、SubagentStop、SessionStart、SessionEnd、PreCompact、Notification。没有PreCommit——如果你在配置里看到它说明版本过旧。1.2pip install后报code-review-graph: command not found根因pip install把 console script 装进了某个bin/目录但它不在你的$PATH里。四种修复方式按推荐程度排序方案 1 —— 用pipx最干净pipx将 CLI 工具装在隔离 venv 中不污染全局 Pythonpip uninstall code-review-graph pipx install code-review-graph若装完仍找不到命令执行pipx ensurepath或把~/.local/bin加入 PATH。方案 2 —— 用uvx免安装无需安装即可直接运行适合临时验证uvx code-review-graph install uvx code-review-graph build方案 3 —— 以 Python 模块方式运行永远可用python -m code_review_graph install python -m code_review_graph build方案 4 —— 手动修正 PATHpip show code-review-graph | grep Location # 找到同级的 bin/ 目录macOS 用户安装通常在 # ~/Library/Python/3.X/bin。加入 shell rc echo export PATH$HOME/Library/Python/3.12/bin:$PATH ~/.zshrc source ~/.zshrc补充约束从源码看CLI 入口 在导入任何其他模块前会强制检查sys.version_info (3, 10)Python 低于 3.10 会直接打印提示并退出——这也是command not found之外另一个常见的“命令装了却跑不起来”的原因pyproject.toml中requires-python 3.10与之对应。1.3 code-review-graph 是项目级作用域还是用户级作用域两者都是——它由四块作用域完全不同的部分组成组成部分作用域位置Python 包本体用户级通过pip/pipx/uvx安装一次即可图谱数据库项目级每个项目内的.code-review-graph/graph.dbMCP server 配置.mcp.json项目级Claude Code 为每个项目启动一个 MCP servercwdproject多仓库注册表用户级~/.code-review-graph/registry.json仅用于cross_repo_search一句话总结工具只装一次然后在每个需要图谱感知评审的项目里各执行一次code-review-graph install code-review-graph build。1.4 使用 venv必须手动更新settings.json根因.claude/settings.json中的 Claude Code hooks 与 MCP 工具路径在安装时被硬编码。如果运行code-review-graph install之后才切换到或新建虚拟环境路径仍指向旧解释器server 会静默失败或使用错误的 Python。修复把.mcp.json中的command/args以及.claude/settings.json里的任何 hook 命令改成指向你的 venv// .mcp.json —— 指向 venv 内的 Python 或 venv 内的 uvx { mcpServers: { code-review-graph: { command: /path/to/your/venv/bin/uvx, args: [code-review-graph, serve] } } }或者更简单——在激活的 venv 内重新执行install让路径按新解释器重新生成source .venv/bin/activate # 先激活 venv code-review-graph install # 重写 .mcp.json 与 hook 路径改完后彻底退出并重新打开 Claude Code让它加载新配置。1.5 “图建好了但新会话里 Claude Code 看不到”按可能性从高到低排查install之后没重启 Claude CodeClaude Code 在启动时读取.mcp.json——如果在会话内执行了install必须彻底退出并重新打开MCP server 才会注册。新会话的cwd是另一个目录MCP server 以cwdproject启动并从这里读取.code-review-graph/graph.db。如果新会话开在父目录或其他项目里自然找不到你刚建的图。只跑了build没跑installbuild生成graph.dbinstall才是通过.mcp.json向 Claude Code 注册 MCP server 的那一步。两者缺一不可。MCP server 启动即崩溃在 Claude Code 里执行/mcp查看 server 状态macOS 上也可检查~/Library/Logs/Claude/mcp*.log。快速核对清单cd /path/to/your/project code-review-graph status # 应打印已建图的 Files/Nodes/Edges ls .mcp.json # 应存在 cat .mcp.json # 应引用 code-review-graph serve # 然后彻底退出 Claude Code并在该项目内重新打开如果status能看到图、但新会话的/mcp里没有code-review-graph说明.mcp.json不在该会话的cwd下——在正确的项目根目录重新执行code-review-graph install即可。二、数据库锁错误SQLite WAL 模式下的正确姿势图谱使用SQLite 且开启 WAL 模式PRAGMA journal_modeWAL在 graph.py 中强制设置。遇到锁错误时确保同一时刻只有一个 build 进程在运行数据库会自动恢复——直接重试即可若确实损坏删除.code-review-graph/graph.db-wal与.code-review-graph/graph.db-shm这两个 WAL 伴生文件后再重试。原理补充WAL 模式把写操作追加到-wal文件允许读与写并发这正是watch增量更新与status/visualize等只读命令能同时运行的基础。多进程同时写才会触发锁冲突因此“单 build 进程”是硬性约束。三、大型仓库超过 1 万文件的性能调优首次全量构建可能需要 30–60 秒这是正常的它要解析整棵代码树之后的增量更新很快在约 3,000 文件的仓库上hook 路径约2.5 秒可参考 REPRODUCING.md 的复现说明在.code-review-graphignore中增加更多忽略模式把生成物与第三方代码排除在图谱之外generated/** vendor/** *.min.js忽略模式的加载实现在 incremental.py它读取仓库根目录的.code-review-graphignore文件在解析阶段就把匹配文件过滤掉——所以这些模式不仅能加快构建还能让semantic_search_nodes_tool等检索工具的命中质量更高。四、构建后缺失节点Missing nodes按以下顺序排查确认文件语言受支持查看 FEATURES.md 中的语言支持清单覆盖 Java、Kotlin、PHP/Laravel、Ruby、Rust、Julia、Zig、Ansible、HCL 等社区可在 CUSTOM_LANGUAGES.md 自定义确认文件没有被忽略模式命中检查.code-review-graphignore及!例外行强制完整重解析在 MCP 工具中调用build_or_update_graph_tool时设置full_rebuildTrue。实现细节full_rebuildTrue会绕过增量路径触发全量 re-parse。从 tools/build.py 看增量更新还有两道内置防线当 store 里没有任何节点not store.has_nodes()或无法解析 diff base 时即使未显式要求也会自动回退为全量重建——这一点与下文“空图修复”直接相关。五、空或不完整的图poisonedgraph.db背景旧版本在某些命令status、detect-changes、visualize、wiki、watch在首次全量 build之前运行时会创建一个空的.code-review-graph/graph.db。随后的增量update只 re-parse 变更过的文件导致图谱一直不完整却看起来“有效”——这就是“中毒”的数据库。当前 CLI 行为v2.2.4status、detect-changes、visualize、wiki、watch在数据库不存在时不再创建它而是直接退出并提示No graph found … Run code-review-graph build first.实现见 cli.py 与 cli.pystatus无图时以退出码 1 结束且不建库update会自动修复缺失或零节点的图——检测到异常时回退到全量重建参见 tools/build.py 的full_rebuild回退逻辑。如果图已经被污染schema 存在、也有部分节点但索引文件数远少于仓库实际文件数——例如只有空库创建后被改动的文件执行一次完整重建code-review-graph buildbuild始终重新解析整棵代码树——没有单独的--force标志这一点与某些工具的语义不同值得注意。重建之后update/ hooks /watch就可以安全地继续走增量路径了。六、图看起来过时Graph seems stalehooks 会在编辑/提交时自动更新见 hooks/hooks.jsonPostToolUse的Write|Edit|Bashmatcher 触发code-review-graph update --skip-flowsSessionStart触发status若仍感觉陈旧手动执行/code-review-graph:build-graph或code-review-graph update检查 hooks 是否确实配置在.claude/settings.json中——不确定就重跑code-review-graph install重新生成。七、Watcher 在运行但图停止更新了核心疑难这是排障手册中实现细节最丰富的部分。crg-daemon status在进程Status列旁边增加了一个Watcher列并显示每个 watcher 处理最后事件的时间Alias Status Watcher PID Event Path backend alive stalled 48213 3d /work/backendWatcher列的取值语义如下状态含义处理方式ok文件系统观察器observer在运行并持续发布心跳无需处理stalled进程还活着但 observer 线程死了什么都没在索引先crg-daemon logs --repo ALIAS看日志再crg-daemon restartpartialwatcher 用完了 watch 槽位退化为一个递归 watch。仍然完整但不再过滤被忽略的目录提高CRG_MAX_WATCH_SCHEDULES恢复过滤unknownwatcher 尚未发布健康信息刚启动或早于本功能引入的版本稍候再查dead进程本身已退出守护进程会自动重启带指数退避源码佐证健康判定实现在 daemon.py 的watcher_status()进程不活即dead从未发布健康文件即unknown心跳过期CRG_WATCH_HEALTH_STALE默认 90 秒或 observer 报告死亡即stalleddegraded标记则归类为partial。stalled的检测非常关键——daemon.py 注释明确指出observer 线程死亡时进程仍活着仅靠poll()会永远显示健康所以每个 watch 子进程会向~/.code-review-graph/watch-health/发布自身状态与最后事件时间。关于“死 watcher”的判定watcher 一旦检测到自己的 observer 死亡会记录错误并以非零状态退出让守护进程重启它对应 issue #811而不是安静地卡住。有两类情况不算死 watcher因为它们属于正常作业删除被监视的目录watch 会被释放删除后重建同一目录watch 按inode追踪替换后的目录会被重新监视并重新索引而不是被误判为尸体。一个在其目录确实没有变化时死亡的 watch在 watcher 放弃前会被重新调度一次。Watch 模式如何过滤目录watch 模式只为通过忽略模式筛选的目录注册 OS watch因此node_modules/、.git/和构建产物根本不再产生事件。后来出现/消失的目录通过每个非递归 watch 的每 tick 列表扫描约 0.1 ms发现而不是依赖目录事件——因为 macOS 对非递归 watch 的子目录完全不发目录事件事件驱动设计将永远注意不到新的顶层目录。相关环境变量全部可选变量默认值作用CRG_MAX_WATCH_SCHEDULES24独立 watch 数量上限仓库需要更多时退化为根目录一个递归 watchCRG_WATCH_PLAN_DEPTH3planner 允许拆分的深度CRG_WATCH_SPLIT_MIN_DIRS4值得单独 watch 的最小被忽略目录树规模CRG_RESTART_BACKOFF30s守护进程重启退避初始值CRG_RESTART_BACKOFF_MAX900s退避上限CRG_RESTART_HEALTHY_AFTER600s恢复健康判定时长这些默认值在源码中均有对应_WATCH_PLAN_DEPTH、_MAX_WATCH_SCHEDULES、_WATCH_SPLIT_MIN_DIRS定义于 incremental.py退避参数定义于 daemon.py。指数退避的意义在于一个无法启动的仓库不会每 30 秒就触发一次完整的初始构建。八、某个目录从图中消失了嵌套构建产物自动排除根因嵌套的target/、build/、.next/、.nuxt/目录当同级清单文件pom.xml、Cargo.toml、build.sbt、build.gradle、next.config.*、nuxt.config.*表明它们是构建产物时会被自动当作 build output 排除。每次 build 都会记录排除了什么Excluding 2 nested build-output directories (a sibling manifest marks them as build output; keep one with !path in .code-review-graphignore): moduleA/target, moduleB/target修复如果其中某个目录真的是源码在.code-review-graphignore里用!行保留它!moduleA/target重要语义!行只将该路径从“自动检测”中豁免不会否定你显式写的忽略模式。如需对整个仓库关闭该检测设置CRG_NESTED_OUTPUT_SCAN0实现见 incremental.py。九、Embeddings 不工作语义搜索安装时带上扩展组pip install code-review-graph[embeddings]运行embed_graph_tool或 CLI 的code-review-graph embed --provider local计算向量首次 embedding 运行会下载一次模型约 90MB补充本地 embedding 基于sentence-transformers云端 providerOpenAI 兼容、Google Gemini、MiniMax、Voyage则只用 stdlib HTTP 客户端仅需各自的环境变量不装额外依赖。十、MCP server 无法启动确认uv已安装uv --version未安装时pip install uv或brew install uv验证uvx code-review-graph serve能无错运行若使用自定义.mcp.json确保是command: uvx配合args: [code-review-graph, serve]重跑code-review-graph install重新生成配置十一、Windows / WSL 专项升级到 v2.3.6daemon status在 Windows 崩溃WinError 87issue #511与 CLIdetect-changes映射 0 个函数issue #528都在该版本修复。Windows 上 PID 存活检测使用 Win32 APIOpenProcess/WaitForSingleObject因为os.kill(pid, 0)会路由到GenerateConsoleCtrlEvent并对活进程抛 WinError 87见 daemon.py向 MCP 工具传repo_root时路径使用正斜杠WSL 中确保安装的是WSL 内的 uv而非 Windows 版本curl -LsSf https://astral.sh/uv/install.sh | sh装完 uv 找不到时把~/.cargo/bin加入 PATHcode-review-graph watch在WSL1上可能因文件系统事件限制有延迟推荐 WSL2Windows 原生非 WSL可能需要开启长路径支持git config --system core.longpaths true。十二、按功能所需的可选依赖组ImportError 排查速查表如果某个工具返回ImportError先对照下表确认是否缺少对应的 optional group——这是“Embeddings 不工作”“社区发现不可用”“Wiki 无摘要”等问题的统一根因。依赖声明见 pyproject.toml功能安装命令说明语义搜索本地 embeddingpip install code-review-graph[embeddings]基于 sentence-transformers 的本地向量Google Gemini embeddingspip install code-review-graph[google-embeddings]需要 google-genaiOpenAI 兼容 / MiniMax embeddings仅需环境变量使用 stdlib HTTP 客户端无额外依赖社区检测igraphpip install code-review-graph[communities]无 igraph 时回退为基于文件的粗分组可用但不精确Python 调用解析增强pip install code-review-graph[enrichment]通过 Jedi 实现 Python call-resolution评估基准pip install code-review-graph[eval]需要 matplotlib还有 igraph 相关场景Wiki LLM 摘要pip install code-review-graph[wiki]依赖 ollama无 Ollama 时仅生成结构信息、不含摘要全部pip install code-review-graph[all]一键装齐以上所有组十三、排障流程速览一张图走完现象第一条命令关键修复动作hook schema 报错pip show code-review-graph升级到 v2.2.3 后重跑installcommand not foundpython -m code_review_graph status用 pipx / uvx或修 PATH新会话看不到图ls .mcp.json code-review-graph status重启 Claude Code在正确 cwd 重跑install数据库锁等待并重试删除-wal/-shm伴生文件图不完整code-review-graph status执行code-review-graph build全量重建图陈旧code-review-graph update重跑install恢复 hooksWatcher 停摆crg-daemon status看Watcher列crg-daemon logs --repo后restart目录消失查看 build 日志的 Excluding 行在.code-review-graphignore加!行ImportError对照上表安装对应 optional group最后别忘了仓库是本地优先的几乎所有诊断都可以离线完成——code-review-graph status是整套排查流程的起点它能在一秒内告诉你问题出在 CLI、数据库还是配置层。相关命令全量清单见 COMMANDS.md社区文档入口见 INDEX.md常见问答见 FAQ.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），仅供参考
