code-review-graph/CODE_REVIEW_GRAPH_ZH.md

# code-review-graph 功能文档

> **停止燃烧 token，让 AI 审查真正的代码。**
>
> code-review-graph 是一个本地优先的**代码审查引擎**：以 Tree-sitter 知识图谱为底座，
> 为 AI 编程助手提供精准的代码上下文与结构化的审查工作流——从 diff 影响面分析、
> 客观量化评分、并行深读覆盖度门禁，到最终的双格式审查报告，全流程只读、可审计。

- 当前版本：v2.5.1（本地定制版）
- 语言要求：Python 3.10+
- 运行形态：本地源码部署（venv / uv），MCP stdio 服务接入 AI 编程工具
- 数据形态：图谱存储于仓库本地 `.code-review-graph/`（SQLite），零遥测，源码不出本机

---

## 目录

1. [工具概述](#1-工具概述)
2. [核心原理](#2-核心原理)
3. [代码审查工作流](#3-代码审查工作流)
4. [MCP 工具（37 个）](#4-mcp-工具37-个)
5. [MCP Prompts（7 个）](#5-mcp-prompts7-个)
6. [CLI 命令参考](#6-cli-命令参考)
7. [opencode 本机集成现状](#7-opencode-本机集成现状)
8. [配置与环境变量](#8-配置与环境变量)
9. [已知局限](#9-已知局限)

---

## 1. 工具概述

AI 编程工具执行代码审查时，往往反复扫描大量文件造成严重 token 浪费，且缺乏统一的
审查方法论与量化标准。code-review-graph 的解决方式是：

- 使用 **Tree-sitter** 将仓库解析为知识图谱：节点（函数/类/导入/测试）+ 边（调用/继承/测试覆盖）
- 审查时通过图谱查询计算需要读取的**最小文件集合**（Blast-radius 分析）
- 在图谱之上提供**三套开箱即用的审查工作流**（diff 统一审查 / 全项目审查 / 单功能审查）
- 用**客观指标评分**（SQL 风险、异常分支覆盖、冗余率等）替代"凭感觉审完"
- 用**并行深读管线 + 覆盖度门禁**保证"审过了"不是由感觉决定，而是有数据支撑
- 最终产出自包含的中文 HTML + Markdown 双格式审查报告

核心特性一览：

| 特性 | 说明 |
| --- | --- |
| 本地优先 | 图谱存本机 SQLite，无需外部数据库；云端 embedding 为显式可选 |
| 增量更新 | 只重解析变更文件（SHA-256 比对），后续更新秒级完成 |
| 零遥测 | 不向任何外部服务发送源码 |
| 多语言 | 40+ 编程语言，支持自定义语言扩展 |
| 三种审查入口 | unified-review（diff）/ project-review（全项目）/ project-review（单功能） |
| 客观量化 | 5 项 Layer-2 指标 + good/warn/fail 分级，blocker 一票否决 |
| 覆盖度门禁 | 文件数口径 + 行覆盖 + 语义单元三件套，双目标（全库 ≥85% 且高风险 ≥95%） |
| 双格式报告 | 自包含中文 HTML（浏览器直开）+ Markdown（入库/PR 复用），全程只读不改代码 |

---

## 2. 核心原理

### 2.1 架构管线

```
仓库 → Tree-sitter 解析 → SQLite 图谱 → Blast-radius 分析 → 最小审查集
                                                      ↓
                              detect_changes 风险评分 → score_review 客观指标
                                                      ↓
                              deep_read 并行深读 → coverage 门禁 → dedupe 合并
                                                      ↓
                                       generate_report（HTML + Markdown）
```

### 2.2 从代码到图谱

`code-review-graph build` 用 Tree-sitter 把源码解析为 AST，提取：

- **节点**：函数、类、导入语句、测试函数等代码实体
- **边**：调用关系、继承关系、测试覆盖关系等结构联系

图谱把「代码长什么样」升级为「代码之间有什么关系」，这是后续一切审查能力的底座。
解析完成后图谱存储在仓库本地 `.code-review-graph/graph.db`。

### 2.3 Blast-radius（爆炸半径）分析

文件发生变更时，图谱追踪所有可能受影响的调用方、依赖方与测试：

- 变更波及面（谁调用了它、谁依赖它、哪些测试覆盖它）
- AI 只读取受影响文件而非扫描整个项目，token 消耗显著下降

### 2.4 增量更新

每次保存文件或 git commit 时计算变更文件的 SHA-256 哈希，只重新解析变化的文件，
再按图谱关系局部更新相关节点。配合 watch 模式 / 平台 hooks / crg-daemon 守护进程，
图谱始终贴近当前代码状态，不需要"用一次就过期"的全量重建。

---

## 3. 代码审查工作流

### 3.1 三种审查入口对比

| 维度 | unified-review（diff 审查） | project-review（全项目） | project-review（单功能） |
| --- | --- | --- | --- |
| **审查对象** | git diff（默认 `HEAD~1..HEAD`） | 图谱内全部源文件 | 目标功能/模块相关文件 + 影响面 |
| **触发指令** | "审查"、"检查代码"、"review" | "对项目代码进行全面审查"、"全面审查"、"整个项目" | "审查支付功能的代码"、"审查 auth 模块" |
| **入口** | `/code-review-graph-unified-review` | `/code-review-graph-project-review` | `/code-review-graph-project-review` |
| **核心工具** | `detect_changes` + `score_review` | `score_review(all_files=True)` + 深读管线 | `semantic_search` + `get_impact_radius` + `score_review` |
| **典型场景** | 合并前检查本次改动 | 代码质量体检、架构审计、发布前全面体检 | 上线前审查某个功能 |

三者共享同一套评分/去重/报告工具，流程结构一致：
**图谱上下文 → 客观评分 → 链路分解 → 去重 → 人工裁决 → 报告**，区别仅在范围获取方式。

### 3.2 unified-review：三层统一审查（diff）

```
触发 → 范围/档位判定 → [图谱上下文] → Layer 1 八分类 + CRITICAL 检查 → [score_review 量化]
→ [specialist 并行派发] → [dedupe 合并去重] → 人工裁决（只读）→ 验收门禁 → [HTML + Markdown 报告] → 持久化
```

| 步骤 | 内容 |
| --- | --- |
| Step 0 范围/档位 | 读 `.code-review.yaml` 确定 tier（fast / standard / strict）；检测语言/框架加载对应 checklist；判定 change/file/service/chain 级范围 |
| Step 1 图谱上下文 | `build_or_update_graph` → `get_review_context`（blast radius + 源码片段）→ `detect_changes`（风险分 + 测试缺口 + 受影响流） |
| Step 2 Layer 1 链路分解 | 八分类逐类检查（接口/业务/数据/工具/错误处理/安全/性能/可观测性），叠加 CRITICAL 五类（SQL 数据安全、竞态并发、LLM 信任边界、Shell 注入、枚举完整性） |
| Step 3 Layer 2 量化评分 | `score_review_tool` 计算 5 项客观指标；需求覆盖/逻辑对齐等由 LLM 判断（`llm_judged` 标注，无需求文档时 0.5× 降权） |
| Step 4 specialist 派发 | diff ≥ 50 行时并行派发 testing/maintainability/security/performance/data-migration/api-contract 子代理；security 与 data-migration 为保险型永不 gate |
| Step 5 合并去重 | `dedupe_findings_tool` 按 `path:line:category` 指纹合并、多源确认置信 +1、计算 PR 质量分、抑制历史已跳过项 |
| Step 6 人工裁决 | **只读**。每条 finding 带 severity + 置信度 + file:line + 修复建议，按 severity 批量呈现；blocker 不可批量跳过 |
| Step 7 验收门禁 | 任一 🔴 blocker → verdict `❌ FAIL`；分类 Ready / Needs Fix / Unusable |
| Step 8 报告 | `generate_report_tool`（默认 `format="both"`）产出中文报告 |
| Step 9 持久化 | 记录审查结果供后续去重抑制，不可用时静默跳过 |

### 3.3 project-review：全项目深读管线

全项目审查的关键难题是**覆盖度不能靠感觉**。主上下文无法逐文件深读数百个文件，
必须走并行子代理深读流水线：

```
a. deep_read_plan_tool(target_coverage=85)
   → 按风险权重贪心选出待深读文件并分组
b. 按组并行派发 explore 子代理，每个子代理完整深读该组全部文件，
   逐文件返回 read_ranges / semantic_units / findings[]（每条 finding 必须带 file:line 证据）
c. 三件套质量门禁（coverage_tool gate="both+line"）：
   ① 单元完整性：semantic_units 与图谱单元一一对应
   ② 行覆盖：union(read_ranges) / 真实行数 ≥ 95%
   ③ 防伪抽验：主代理抽样回读比对，防子代理假读
d. line_gap ∪ unit_gap 非空 → 补轮重读直至清空，禁止静默降级
e. 未达标 → 按 priority_deep_read_files 补一轮，循环至达标
f. 报告生成后 save_coverage_index_tool 写跨轮覆盖索引（file + SHA + ranges），
   下轮审查 include_prior=True 自动复用未变更文件，实现增量累积
```

**覆盖度双口径门禁**：

- 全库覆盖 = 已深读文件数 / 全部源文件数（目标 ≥85%）
- 高风险覆盖 = 已深读高风险文件数 / 信号点名文件数（目标 ≥95%）
- `target_reached=false` → 报告顶部标 🔴 覆盖不足；覆盖率结果完整透传进报告 `## 覆盖度` 区块

其余步骤（架构全景 → 高风险定位 → `score_review(all_files=True)` → 八分类 + CRITICAL →
dedupe → 人工裁决 → 报告）与 unified-review 同构。

单功能（feature）流程则先用 `semantic_search_nodes(query=target)` 定位代码，
再 `query_graph(children_of)` 聚合文件、`get_impact_radius` 扩影响面，
之后聚焦这些文件走同一套评分与裁决流程。

### 3.4 报告成果物

每次审查默认产出两份中文报告（`generate_report_tool format="both"`）：

- **`code-review-report.html`** — 自包含单文件（内联样式、零外部依赖），浏览器直接打开。
  含结论（PASS/FAIL）、PR 质量分、客观指标表、问题清单（severity + 置信度 + 位置 + 修复建议）、
  覆盖度区块、人工审查清单
- **`code-review-report.md`** — Markdown 版，便于 git 提交、PR 描述、内部文档复用

`format="html"` / `format="markdown"` 可单独产出；`output_path` 指定输出基础路径
（推荐归档到 `docs/reviews/{name}-review-{YYYY-MM-DD-HHMMSS}`，避免同名覆盖且便于追溯）。

**报告均为只读产物**：审查本身不修改任何代码，所有修复决定由人工确认后执行。

---

## 4. MCP 工具（37 个）

图谱构建完成后，AI 助手通过 MCP 自动使用以下工具（共 37 个，按类分组）。

### 4.1 图谱核心与上下文（12）

| 工具 | 描述 |
| --- | --- |
| `build_or_update_graph_tool` | 构建或增量更新图谱 |
| `run_postprocess_tool` | 重跑流检测、社区检测与 FTS 索引 |
| `get_minimal_context_tool` | 超紧凑上下文（~100 token），任何任务的第一个调用 |
| `get_impact_radius_tool` | 变更文件的爆炸半径分析 |
| `get_review_context_tool` | token 优化的审查上下文 + 结构摘要 + 源码片段 |
| `detect_changes_tool` | **风险评分的变更影响分析**：diff 映射到受影响函数/流/测试缺口，产出风险分与优先审查建议 |
| `query_graph_tool` | 关系模式查询：callers_of / callees_of / imports_of / tests_for / inheritors_of 等 |
| `traverse_graph_tool` | 从任意节点 BFS/DFS 探索，带深度与 token 预算 |
| `semantic_search_nodes_tool` | 向量语义搜索代码实体（需先 embed），无向量时回退 FTS 关键词匹配 |
| `embed_graph_tool` | 为全部图节点计算向量 embedding（local/openai/google/minimax/voyage） |
| `list_graph_stats_tool` | 图谱规模与健康状况统计 |
| `find_large_functions_tool` | 查找超过行数阈值的函数/类/文件（巨型文件审计） |

### 4.2 执行流与社区架构（11）

| 工具 | 描述 |
| --- | --- |
| `list_flows_tool` | 按关键度排序列出执行流（从入口点追踪的调用链） |
| `get_flow_tool` | 查看单个执行流的完整调用路径 |
| `get_affected_flows_tool` | 查找受变更文件影响的用户级执行路径 |
| `list_communities_tool` | 列出 Leiden 算法聚类出的代码社区 |
| `get_community_tool` | 查看单个社区详情（规模/内聚度/成员） |
| `get_architecture_overview_tool` | 从社区结构生成架构总览与耦合警告 |
| `get_hub_nodes_tool` | 找出连接最多的节点（架构热点，改动爆炸半径大） |
| `get_bridge_nodes_tool` | 通过介数中心性找出架构瓶颈（桥接节点） |
| `get_knowledge_gaps_tool` | 识别孤立节点、未测试热点、薄弱社区等结构弱点 |
| `get_surprising_connections_tool` | 检测意外耦合：跨社区/跨语言/外围到 Hub 的边 |
| `get_suggested_questions_tool` | 从图谱分析自动生成审查问题（桥/hub/惊喜耦合驱动） |

### 4.3 审查分析与报告（8）

| 工具 | 描述 |
| --- | --- |
| `score_review_tool` | **客观 Layer-2 指标**：SQL 风险、异常分支覆盖、冗余率、高风险密度、漏洞启发式五项，带 good/warn/fail 分级与证据；支持 `all_files=True` 全量评分；`llm_judged` 字段列出需 LLM 补判项 |
| `dedupe_findings_tool` | **Finding 合并去重**：按 `path:line:category` 指纹合并、多源置信 +1（上限 10）、低置信移附录、抑制历史已跳过项、计算 PR 质量分 `max(0, 10 - (critical×2 + informational×0.5))` |
| `generate_report_tool` | **报告生成**：渲染为自包含中文 HTML 与 Markdown（默认双格式），自动渲染结论/指标表/问题清单/覆盖度区块 |
| `refactor_tool` | 重命名预览、框架感知死代码检测、社区驱动重构建议 |
| `apply_refactor_tool` | 应用此前预览过的重构（精确字符串替换） |
| `generate_wiki_tool` | 从社区结构生成 markdown wiki（`.code-review-graph/wiki/`） |
| `get_wiki_page_tool` | 获取特定 wiki 页面 |
| `get_docs_section_tool` | 获取内置 LLM 优化文档的指定章节（usage/review-pr/troubleshooting 等） |

### 4.4 深读管线、覆盖度与多仓（6）

| 工具 | 描述 |
| --- | --- |
| `deep_read_plan_tool` | 生成按风险权重贪心分组的深读计划（groups + planned_files + estimated_batches），支持增量排除上轮已读文件 |
| `coverage_tool` | **覆盖度三件套门禁**：文件数口径 + 行覆盖 + 语义单元覆盖三重计算；`gate="both+line"` 时四项 AND 判定；返回缺口文件与补读优先级队列；`include_prior=True` 合并跨轮索引实现增量 |
| `save_coverage_index_tool` | 持久化深读名单到 `.code-review-graph/coverage-index.json`（file + per-file SHA + ranges），供下轮审查增量复用 |
| `community_health_tool` | 检查 nodes.community_id 归属健康度，归属率 <90% 时提示先 postprocess 再算覆盖度，防止失真 |
| `list_repos_tool` | 列出多仓注册表中已注册仓库 |
| `cross_repo_search_tool` | 跨所有已注册仓库搜索代码实体，按仓内 rank 交错返回 |

---

## 5. MCP Prompts（7 个）

MCP 协议层的 7 个预构建工作流模板，支持 MCP prompts 的客户端将其呈现为 "/" 可调用命令。
全部强制 token 效率模式：先调 `get_minimal_context`，默认 `detail_level="minimal"`。

| "/" 可调用命令 | 功能 | 参数 |
| --- | --- | --- |
| `/review_changes` | 提交前审查：`detect_changes` + 受影响执行流 + 测试缺口 | `base="HEAD~1"` |
| `/architecture_map` | 架构文档：社区、执行流、Mermaid 图 + 耦合警告 | 无 |
| `/debug_issue` | 引导式调试：语义搜索 + 调用链追踪 + 执行流定位根因 | `description=""` |
| `/onboard_developer` | 新成员入职指南：统计、架构、关键执行流 | 无 |
| `/pre_merge_check` | 合并前就绪检查：风险评分、测试缺口、死代码 | `base="HEAD~1"` |
| `/unified_review` | 三层统一审查（只读）：图谱上下文 → 客观评分 → 人工裁决 → 去重 → 双格式报告。任何 blocker 判 FAIL | `base="HEAD~1"`、`tier="standard"`（fast/standard/strict） |
| `/project_review` | 项目级审查（非 diff）：全项目或单功能，由用户自然语言指令决定范围，只读 | `scope="whole-project"`、`target=""` |

---

## 6. CLI 命令参考

### 6.1 安装与部署

```bash
code-review-graph install                     # 自动检测并配置所有支持的 AI 平台（MCP/hooks/skills/规则注入）
code-review-graph install --platform <name>   # 仅配置单个平台
code-review-graph install --dry-run           # 预览动作不写入
code-review-graph init                        # install 别名
code-review-graph uninstall --dry-run         # 对称卸载预览（只移除本工具拥有的组件）
code-review-graph uninstall --keep-data       # 移除集成但保留图谱数据库
code-review-graph uninstall --all-repos       # 同时清理所有已注册仓库
```

支持平台：Codex、Claude Code、CodeBuddy Code、Cursor、Windsurf、Zed、Continue、
OpenCode、Antigravity、Gemini CLI、Qwen、Qoder、Kiro、GitHub Copilot（含 CLI）。

### 6.2 图谱构建与维护

```bash
code-review-graph build                       # 全量解析整个代码库
code-review-graph build --skip-flows          # 跳过流检测
code-review-graph build --skip-postprocess    # 跳过后处理（流/社区/FTS）
code-review-graph update                      # 增量更新（仅变更文件）
code-review-graph update --base <ref>         # 指定 git diff 基线
code-review-graph update --brief              # 刷新后打印 Token Savings 面板
code-review-graph update --verify             # 用 tiktoken 交叉校验 token 估算
code-review-graph postprocess                 # 重跑后处理
code-review-graph postprocess --no-flows      #   跳过流检测
code-review-graph postprocess --no-communities#   跳过社区检测
code-review-graph postprocess --no-fts        #   跳过 FTS 重建
code-review-graph watch                       # 监听文件变更自动增量更新
code-review-graph status [--json]             # 图谱统计
code-review-graph forget <path> [--dry-run]   # 从图谱移除已解析文件（免全量重建）
code-review-graph embed --provider local      # 计算 embedding（--model all-MiniLM-L6-v2）
```

通用参数：绝大多数命令支持 `--repo <root>` 显式指定仓库根（默认自动探测）；
`--data-dir` 可覆盖图谱数据目录。

### 6.3 分析与审查

```bash
code-review-graph detect-changes --brief      # 风险面板 + token 节省估算（只读）
code-review-graph detect-changes --base <ref> # 指定 diff 基线（默认 HEAD~1）
code-review-graph detect-changes --churn      # 风险评分加入变更频率因子
code-review-graph impact --files <path>...    # 变更爆炸半径（--depth/--max-results/--base）
code-review-graph query <pattern> <target>    # 图谱关系查询（callers_of/callees_of/imports_of 等）
code-review-graph search <query> [--kind]     # FTS/语义混合搜索图谱实体
code-review-graph dead-code [--kind] [--file-pattern] [--json]   # 死代码检测
code-review-graph large-functions --min-lines 150 [--path] [--kind]   # 巨型函数/文件审计
code-review-graph refactor rename --old-name X --new-name Y       # 重命名预览
code-review-graph refactor dead_code|suggest  # 死代码/重构建议
```

### 6.4 结构浏览

```bash
code-review-graph flows [--limit 50] [--kind] [--sort]   # 执行流列表
code-review-graph flow --id 3 [--source]      # 单个执行流详情（可含源码片段）
code-review-graph communities [--min-size] [--sort]      # 社区列表
code-review-graph community --id 71 [--members]          # 单个社区详情
code-review-graph architecture [--detail-level minimal|standard]   # 架构总览
code-review-graph visualize [--format json|graphml|svg|obsidian|cypher] [--serve]
code-review-graph wiki [--force]              # 从社区生成 markdown wiki
```

### 6.5 多仓与服务

```bash
code-review-graph register <path> [--alias]   # 注册仓库到多仓注册表
code-review-graph unregister <path_or_alias>  # 移除注册
code-review-graph repos                       # 列出已注册仓库
code-review-graph eval [--benchmark ...] [--all] [--report]   # 评估基准

code-review-graph serve                       # 启动 MCP stdio 服务
code-review-graph serve --repo <root>         # 指定仓库根
code-review-graph serve --http --host 127.0.0.1 --port 5555    # Streamable HTTP 模式
code-review-graph serve --tools t1,t2         # 仅暴露部分 MCP 工具（token 受限环境）
code-review-graph serve --auto-watch          # 服务期间自动增量更新
code-review-graph mcp                         # serve 别名
```

### 6.6 多仓守护进程（crg-daemon）

编辑器不支持 hooks 或希望后台保持多仓图谱新鲜时使用，随主程序一并安装：

```bash
crg-daemon add ~/project-a --alias proj-a     # 注册监听（写 ~/.code-review-graph/watch.toml）
crg-daemon start                              # 后台启动，每 30s 健康检查并重启死掉的 watcher
crg-daemon status                             # 查看守护进程与各仓库 watcher 状态
crg-daemon logs --repo proj-a --follow        # 追踪某仓库日志
crg-daemon stop                               # 停止守护进程与全部 watcher
```

也支持 `code-review-graph daemon start|stop|restart|status|logs|add|remove`。

---

## 7. opencode 本机集成现状

本机采用**源码部署**方式：工具代码位于 `D:\code-review-graph\code-review-graph-main`，
venv 内的可执行文件被 MCP 配置以绝对路径引用。

### 7.1 MCP 配置（两处）

```json
// D:\AuraSpace\.mcp.json（项目级）
{
  "mcpServers": {
    "code-review-graph": {
      "command": "D:\\code-review-graph\\code-review-graph-main\\.venv\\Scripts\\code-review-graph.exe",
      "args": ["serve", "--repo", "D:\\AuraSpace"],
      "cwd": "D:\\AuraSpace",
      "type": "stdio"
    }
  }
}
```

```json
// %USERPROFILE%\.config\opencode\opencode.json（全局级，节选）
{
  "mcp": {
    "code-review-graph": {
      "type": "local",
      "command": [
        "D:\\code-review-graph\\code-review-graph-main\\.venv\\Scripts\\code-review-graph.exe",
        "serve", "--repo", "D:\\AuraSpace"
      ],
      "timeout": 600000,
      "env": { "CRG_REPO_ROOT": "D:\\AuraSpace" }
    }
  }
}
```

### 7.2 已安装的 skills（`%USERPROFILE%\.config\opencode\skills\`，9 个）

| Skill | 功能 |
| --- | --- |
| `build-graph` | 构建/重建代码图谱 |
| `explore-codebase` | 图谱结构探索导航 |
| `debug-issue` | 图谱引导式调试 |
| `refactor-safely` | 依赖分析驱动的安全重构 |
| `review-changes` | 变更审查（change detection + impact） |
| `review-delta` | 自上次提交以来的增量审查 |
| `review-pr` | PR/分支完整审查 |
| `unified-review` | 三层统一审查：CRG 图谱上下文 + ai-code-review 评分方法论 + gstack-review 流程 |
| `project-review` | 项目级审查（全项目/单功能）：并行深读管线 + 三件套覆盖度门禁 + 双格式报告 |

其中 `project-review` 附带 PowerShell 校验脚本（verify-report / verify-line-coverage /
verify-spot-check.ps1）与 Python 聚合脚本（aggregate_deep_read.py），
skill 文档内引用了绝对路径，迁移机器时需同步修改。

### 7.3 已安装的斜杠命令（`command\`，5 个）

| 命令 | 功能 |
| --- | --- |
| `/code-review-graph-build-graph` | 构建/更新图谱 |
| `/code-review-graph-unified-review` | diff 三层统一审查（只读） |
| `/code-review-graph-project-review` | 项目级审查：全项目或单功能（只读） |
| `/code-review-graph-review-pr` | PR/branch diff 审查 |
| `/code-review-graph-review-delta` | 自上次提交以来的变更审查 |

### 7.4 本地部署步骤（新机器/重建环境）

```powershell
# 前置：Python 3.10+ 与 uv
cd D:\code-review-graph\code-review-graph-main
uv sync                        # 按 uv.lock 重建 .venv（国内网络先设 UV_INDEX_URL 镜像）
.\.venv\Scripts\code-review-graph.exe --version    # 应输出 2.5.x
```

**配置 opencode.json（全局 MCP 注册）**

文件位于 `%USERPROFILE%\.config\opencode\opencode.json`，将 code-review-graph 段加入 `mcp` 对象
（若已有 `plugin`、`playwright` 等其他配置项则保留不动）：

```json
"code-review-graph": {
  "type": "local",
  "command": [
    "D:\\code-review-graph\\code-review-graph-main\\.venv\\Scripts\\code-review-graph.exe",
    "serve", "--repo", "D:\\AuraSpace"
  ],
  "timeout": 600000,
  "env": { "CRG_REPO_ROOT": "D:\\AuraSpace" }
}
```

按新机器实际修改 3 处：`command[0]` 的 exe 绝对路径、`--repo` 的仓库根、`env.CRG_REPO_ROOT`。
项目级 `.mcp.json`（可选）参考 §7.1。

然后核对 §7.1 的 `.mcp.json` 与本节 opencode.json 中的绝对路径与新机一致，
复制 7.2/7.3 的 skills 与 commands，重启 opencode 即生效。

> **使用前提**：先构建图谱（首次 `code-review-graph build` 或 `/code-review-graph-build-graph`），
> 否则图谱工具返回 `not_ready`。

---

## 8. 配置与环境变量

### 8.1 排除路径（`.code-review-graphignore`）

在仓库根目录创建 `.code-review-graphignore` 排除已跟踪文件的索引：

```
generated/**
*.generated.ts
vendor/**
node_modules/**
```

> git 仓库中默认只索引被跟踪文件（`git ls-files`），gitignore 文件自动跳过。
> `.code-review-graphignore` 用于排除已跟踪文件或 git 不可用的场景。

### 8.2 可选依赖组

```bash
pip install "code-review-graph[embeddings]"          # 本地向量 embedding（sentence-transformers）
pip install "code-review-graph[google-embeddings]"   # Google Gemini embeddings
pip install "code-review-graph[communities]"         # 社区检测（igraph）
pip install "code-review-graph[enrichment]"          # Python 调用解析富化（Jedi）
pip install "code-review-graph[eval]"                # 评估基准
pip install "code-review-graph[wiki]"                # Wiki 生成 + LLM 摘要（ollama）
pip install "code-review-graph[all]"                 # 全部可选依赖
```

源码部署时对应 `uv sync --extra <name>` 或在 venv 内 `pip install -e .[<name>]`。

### 8.3 环境变量

| 变量 | 描述 | 默认 |
| --- | --- | --- |
| `CRG_REPO_ROOT` | 显式指定仓库根（opencode 全局配置中使用） | - |
| `CRG_DATA_DIR` | 覆盖图谱数据库与生成产物的目录 | - |
| `CRG_GIT_TIMEOUT` | Git 操作超时（秒） | `30` |
| `CRG_TOOLS` | serve 时暴露的 MCP 工具允许列表（逗号分隔） | - |
| `CRG_TOOL_TIMEOUT` | 有界 MCP 工具的可选超时（秒，`0` 禁用） | `0` |
| `CRG_MAX_IMPACT_NODES` | 影响分析中最多包含的节点数 | `500` |
| `CRG_MAX_IMPACT_DEPTH` | 爆炸半径分析搜索深度 | `2` |
| `CRG_MAX_BFS_DEPTH` | 图谱遍历最大深度 | `15` |
| `CRG_MAX_SEARCH_RESULTS` | 搜索结果数上限 | `20` |
| `CRG_MAX_CHANGED_FUNCS` | 单次变更报告分析的最大变更函数数 | `500` |
| `CRG_MAX_TRANSITIVE_FRONTIER` | 传递调用方/被调用方展开的最大前沿大小 | `50` |
| `CRG_RECURSE_SUBMODULES` | 设为 `1`/`true`/`yes` 时包含 git 子模块文件 | - |
| `CRG_SERIAL_PARSE` | 设为 `1` 禁用并行解析（调试用） | - |
| `NO_COLOR` | 设置后禁用终端 ANSI 颜色 | - |

**Embedding 相关**（可选功能，全部默认关闭）：

| 变量 | 描述 | 默认 |
| --- | --- | --- |
| `CRG_EMBEDDING_MODEL` | 本地 embedding 默认模型 | `all-MiniLM-L6-v2` |
| `GOOGLE_API_KEY` | Google Gemini embedding 的 API key | - |
| `MINIMAX_API_KEY` | MiniMax embedding 的 API key | - |
| `VOYAGE_API_KEY` / `CRG_VOYAGE_*` | Voyage embedding 密钥与模型/维度/批大小等参数 | `voyage-code-3` |
| `CRG_OPENAI_BASE_URL` / `CRG_OPENAI_API_KEY` / `CRG_OPENAI_MODEL` | OpenAI 兼容端点（真实 OpenAI、Azure、new-api、LiteLLM、vLLM、LocalAI 等） | - |
| `CRG_ACCEPT_CLOUD_EMBEDDINGS` | 显式确认后抑制云端 embedding 出口警告 | - |
| `CRG_ALLOW_REMOTE_CODE` | 允许需要 `trust_remote_code=True` 的 HuggingFace 模型 | `0` |

隐私说明：embedding 只处理标识符、签名、结构上下文与首段 docstring 摘要，
**不传输函数体**；例行构建默认不刷新 embedding，刷新需显式传 provider + model。

### 8.4 语言覆盖

解析器覆盖函数、类、导入、调用点、继承与测试检测：

- **Web**：JavaScript / TypeScript / TSX、PHP、Ruby、Vue/Svelte SFC、Astro、Blade
- **后端**：Python、Go、Java、C/C++、C#、VB.NET、Kotlin、Scala、Elixir、R
- **系统**：Rust、Zig、Objective-C、Nix、Shell、Verilog/SystemVerilog、SQL
- **移动**：Swift、Kotlin、Objective-C
- **脚本**：Perl / Perl XS、Lua/Luau、PowerShell、Julia、ReScript、GDScript
- **配置/结构**：Terraform/OpenTofu（`.tf`）、Ansible playbook/role/task、Solidity、Dart
- **笔记本**：Jupyter / Databricks（`.ipynb`）

> 通用 YAML 不视为源码。PHP 项目额外获得 Composer PSR-4 解析、Blade 引用与
> Laravel Route/Eloquent 语义边（基于证据门控）。

### 8.5 自定义语言（无需改代码）

在仓库 `.code-review-graph/languages.toml` 将扩展名映射到 `tree_sitter_language_pack`
中任意已捆绑语法，并声明函数/类/导入/调用的 tree-sitter 节点类型：

```toml
[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 遍历器即可完成提取；内置语言永远不会被覆盖。
详见本仓库 `docs/CUSTOM_LANGUAGES.md`。

- **如何验证工具正常工作？** `code-review-graph status`、`detect-changes --brief`，
  或在 MCP 客户端中查看 code-review-graph 服务是否列出工具。
- **图谱何时需要重建？** 日常由 watch/hooks/crg-daemon 自动增量维护；仅在切换分支大范围
  变更、怀疑图谱过期或升级版本后建议全量 `build`。
- **审查会修改我的代码吗？** 不会。三种审查工作流全程只读，报告落盘于
  `docs/reviews/`（或指定的 `output_path`），修复决定始终由人工执行。
- **MCP 报 not_ready？** 该仓库尚未构建图谱，先运行一次 `build`。