内容
# rag_for_git
> **一款 AI 拉取请求审查工具，读取您的整个代码仓库 — 混合 RAG + 代码图 + Claude Code.**
> 普通的 lint 工具只能检查代码片段的差异；而这个工具为模型提供与人类审查者相同的上下文 — 在整个代码仓库中进行语义和词汇检索，以及结构化的代码图 — 然后将结果以 **GitHub 内联评论的形式反馈到确切的差异行中，并附带可应用的修复建议**。
[](https://pypi.org/project/rag-reviewer/)
[](https://pypi.org/project/rag-reviewer/)
[](LICENSE)
[](#mcp-tools-reference)
[](#claude-code-plugin-marketplace)
> 🇷🇺 [俄语版本](README.ru.md) — 深入的代码审查：[README.ru.md](README.ru.md)
---
## 目录
- [为什么存在](#why-it-exists)
- [审查示例](#what-a-review-looks-like)
- [亮点](#highlights)
- [审查流程](#how-a-review-runs)
- [工作原理 / 架构](#how-it-works--architecture)
- [一键安装提示](#one-click-install-prompt)
- [安装](#installation)
- [配置参考](#configuration-reference)
- [CLI 参考](#cli-reference)
- [技能参考](#skills-reference)
- [MCP 工具参考](#mcp-tools-reference)
- [插件使用](#plugin-usage)
- [每个仓库的策略和任务板](#per-repo-policy--task-board)
- [可观察性 Web 管理界面](#observability-web-admin)
- [已知限制和注意事项](#known-limitations--caveats)
- [测试](#tests)
- [项目布局](#project-layout)
- [贡献](#contributing)
- [许可证](#license)
---
## 为什么存在
普通的 lint 工具只能检查语法和风格，但会忽略**含义和关系** — 而这些正是人类审查者关注的重点：
- 修改后的函数接口可能会静默地破坏调用者，
- 删除的守卫子句可能会在三文件之外影响相关代码，
- 变更可能会与现有的测试相矛盾，
- 边缘情况可能只在调用的辅助函数中出现。
要捕捉这些问题，需要**超出差异的上下文**：谁调用这个函数，它实现了什么，有哪些测试验证其行为。`rag_for_git` 为模型提供这种上下文 — 在整个**代码仓库**中进行语义和词汇检索，以及结构化的**代码图** — 然后以 **GitHub 内联评论的形式反馈到确切的差异行中，并附带可应用的修复建议**。
它不是一个简单的 "将差异发送给 LLM" 的包装器。它是一个检索 + 代码图管道，具有确定性的、防止幻觉的发布尾部。
## 审查示例
审查代理发布到更改行的示例内联评论 — 它通过调用图从编辑函数追踪到调用者和合约测试：
> **🟠 正确性 — 过期的令牌不再被拒绝**
>
> `verify_token` 以前会因过期的签名而引发异常；新的守卫只检查 `payload is None`，因此 `_decode()` 返回具有过去 `exp` 的有效载体现在通过。两个调用站点依赖于该异常 — `require_auth` (`auth/deps.py:48`) 和合约测试 `test_expired_rejected` (`tests/test_auth.py:71`)，此更改将破坏这些依赖。
>
> ```suggestion
> if payload is None or payload.get("exp", 0) < now:
> raise InvalidToken("expired or malformed token")
> ```
> <!-- ai-review:9f3c2a -->
每个发现都基于**确切的引用**，并带有类别/严重程度/置信度 — 当安全时，会作为 GitHub `suggestion` 提供。一条隐藏的指纹 (`<!-- ai-review:… -->`) 使得重新运行**幂等**：永远不会发布相同的 issue。
## 亮点
- **整个仓库的上下文，而不仅仅是差异。** 在整个索引代码库上进行混合检索（pgvector ANN + BM25，与 RRF 融合，并由 Voyage 重新排序）— 对于更改的文件，代理看到新版本，对于其他文件，看到稳定的基础索引。
- **看到影响。** Neo4j 代码图（`CALLS` / `IMPLEMENTS`）将每个更改的符号扩展 1-2 跳跃，以显示调用者、被调用者、实现和测试。
- **通过构造防止幻觉。** 发现必须引用真实代码才能发布到一行；专用**验证**过程会删除虚构的发现；行对齐是精确匹配。
- **真正的 GitHub 输出。** 差异行上的内联评论，可应用的 `suggestion` 块 — 幂等且跨重新运行。
- **生活在您的编辑器中，而不是 CI 黑盒。** 作为 **Claude Code 插件** 和 **MCP 服务器**，可在 12+ AI 客户端中使用（Cursor，VS Code，Gemini CLI，Codex，Windsurf，Claude Desktop，...）。一个 `uvx` 命令；发布在 [PyPI](https://pypi.org/project/rag-reviewer/)。
- **本地优先。** 您的代码保留在您的机器上 — 只有嵌入/查询文本发送到 Voyage；存储（Postgres/ParadeDB + Neo4j）在本地 Docker 中运行。
- **不仅仅是审查。** 相同的 RAG + 图表支持有根据的代码库 **Q&A** (`ask`)，有纪律的任务上下文收集 (`solve-task`)，PR **walkthroughs** 和每个子系统的摘要。
## 审查流程
单个 PR 审查分为三个阶段：
**`prepare_review` (MCP)** → **analyze (Claude subagents)** → **`publish_review` (MCP)**
1. **准备** — `GitHubProvider` 拉取 PR（基准/头部 SHA）和更改文件；更改的 `.py` 文件被分割（tree-sitter）并嵌入（Voyage）到一个临时覆盖层 `ref="pr:N"`；组装策略和每个文件的审查单元。
2. **分析** — Claude Code 技能分发一个子代理到每个文件。每个代理都在一个工具循环中推理差异，拉取所需的代码：`search_code`，`get_related_symbols`，`read_file`，`get_definition`，`find_callers`，`get_changed_file_diff`。同时，维度代理运行 **性能** 和 **可维护性** 传递，以及 **需求** 传递（当任务板连接时），最后 **验证** 传递会剥离幻觉。
3. **发布** — 确定性尾部：策略门控（类别/严重性/置信度/路径）→ 通过确切代码引用进行行对齐（防止幻觉）→ 去重 → 组装（内联与摘要，建议不变， 指纹幂等，评论上限）→ 发布到 GitHub → 历史记录 → 覆盖层/会话清理。
> 状态：正在工作的 v1。目标分析语言是 **Python**；VCS 是 **GitHub**（在 `VCSProvider` 接口后面）。已证明可以捕获真实的错误并查看调用代码和现有测试的影响。
## 工作原理 / 架构
核心是 `reviewer/` 库，在 `reviewer/app.py::build_components(settings)` 中从 `Settings`（pydantic-settings，`.env`）组装。入口点是 `reviewer/entrypoints/cli.py`（Click）和 `reviewer/entrypoints/mcp_server.py`（FastMCP）。三个部分协同工作：
- **RAG（混合检索）。** Postgres/ParadeDB 存储代码块与 `pgvector`（HNSW ANN）和 `pg_search`（BM25）。查询嵌入到 Voyage，运行 ANN 和 BM25 搜索，结果列表通过 **Reciprocal Rank Fusion（RRF）** 合并，然后由 Voyage `rerank-2.5` 重新排序。
- **代码图（SCIP 或 tree-sitter，Neo4j）。** 符号及其关系存储在 Neo4j 中。图编排器 (`graph/backend.py`) 通过 `GRAPH_BACKEND` （`auto|scip|treesitter`）选择后端：**SCIP** (`@sourcegraph/scip-python`) 提供精确的、类型感知的图，带有 `CALLS` + `IMPLEMENTS` 边；**tree-sitter** 是仅限于按名称调用的快速备用。检索扩展更改的符号 1-2 跳跃，以显示调用者/被调用者/实现/测试。
- **通过 MCP 的 Claude Code 插件。** `reviewer-mcp` 服务器公开 `prepare_review`，`publish_review` 和代理工具。Claude Code 插件 (`plugin/`) 驱动审查：它调用 `prepare_review`，对那些 MCP 工具运行分析子代理，然后调用 `publish_review`。
**连接 RAG 和图的单个键是 `node_id = "path#fqn"`** （例如 `rag/embedder.py#VoyageEmbedder.embed_query`）。Postgres 中的块和 Neo4j 中的节点都使用它，因此图扩展和块检索在没有映射表的情况下连接起来。
**索引新鲜度：稳定的基础 + PR 覆盖层。** 大型仓库的完整重新索引很昂贵，因此索引保持持久的基础并分层 PR 更改：
- **`ref="base:<branch>"`** — 跟踪分支的持久索引（例如 `"base:main"`，`"base:master"`）。`REVIEW_BRANCHES` 中的每个跟踪分支都有自己的隔离索引。通过 `reviewer index --ref <branch>` 增量更新（仅更改的文件被分割；仅具有新的 `content_hash` 的块被重新嵌入 — 嵌入根据哈希在分支之间重复使用，从而节省 Voyage 配额）。
- **`ref="pr:N"`** — 仅 PR 的更改文件的临时覆盖层在其头部。
- **查询时**：`retrieval = (base:<branch> where path ∉ changed) ∪ overlay`。对于更改的文件，代理看到**新**版本；对于其他文件，看到稳定的基础。
- **多分支。** PR 针对其目标分支的索引进行审查（来自 PR 的 `base_ref`）。针对未跟踪分支的 PR 被跳过（`prepare_review` 返回 `{"status":"skipped",...}`）。代码图（Neo4j `:Symbol`）也通过 `branch` 属性按分支范围划分，具有唯一约束 `(repo, branch, id)`。
```
┌─────────────────────────── reviewer（核心库） ───────────────────────────┐
│ │
GitHub PR ───▶│ VCSProvider（github.py） ──diff/files/patches──▶ MCPReviewService │
（owner/repo#N）│ ▲ 发布内联 + 摘要 │ prepare_review │
│ │ ▼ │
│ │ ┌──────────── retrieval/Retriever ──────────┐ │
│ │ │ 混合搜索 图表扩展 │ │
│ │ │ ┌──────────────┐ ┌───────────────────┐ │ │
│ │ │ │ Postgres │ │ Neo4j │ │ │
│ │ │ │ （ParadeDB） │ │ Symbol（path#fqn） │ │ │
│ │ │ │ pgvector（HNSW）│ │ -[:CALLS]-> │ │ │
│ │ │ │ + pg_search │ │ （IMPLEMENTS: SCIP） │ │ │
│ │ │ │ （BM25, RRF） │ │ 扩展 1-2 跳跃 │ │ │
│ │ │ └──────┬───────┘ └─────────┬─────────┘ │ │
│ │ │ Voyage 嵌入/重新排序 tree-sitter 图 │ │
│ │ └─────────────────┬─────────────────────────┘ │
│ │ ▼ ContextPack │
│ │ Claude Code 子代理（技能 /rag-reviewer:reviewer_review-pr）
│ │ 工具： search_code, get_related_symbols, │
│ │ read_file, get_definition, find_callers, … │
│ └─────────────────── publish_review（门控/接地/去重/组装） ◀─────┘
└─────────────────────────────────────────────────────────────────────────────────┘
存储（Docker）： Postgres/ParadeDB (:5433) · Neo4j (:7687)
外部 API： Voyage （嵌入 voyage-code-3 + 重新排序器 rerank-2.5）
有关每个模块和数据流的更深入、代码验证的演走，请参阅
[README.ru.md](README.ru.md)（俄语）。
## 一键安装提示
复制并粘贴到任何 AI 编码助手（Claude Code，Cursor，Gemini CLI，Mimo Code，OpenCode，Kimi Code，Codex，Copilot…）：
```
在 AI 工具中设置 rag-reviewer MCP 服务器。
规则：
- 使用 `uvx --from rag-reviewer@latest reviewer-mcp` 运行服务器 - 不要 pip 安装，不要克隆仓库。
- 在 macOS/Linux 上需要 `bash -lc` 包装器，以便 GUI 工具找到 uvx：command="/bin/bash", args=["-lc", "uvx --from rag-reviewer@latest reviewer-mcp"]。在 Windows 上使用 command="uvx", args=["--from","rag-reviewer@latest","reviewer-mcp"]。
- 检测正在运行的 AI 工具，然后将 MCP 条目写入正确的配置文件：
- Claude Code / generic：.mcp.json 在项目根目录（{"mcpServers":{"reviewer":{"command":"/bin/bash","args":["-lc","uvx --from rag-reviewer@latest reviewer-mcp"]}}})
- Cursor：~/.cursor/mcp.json（相同格式）
- Gemini CLI：~/.gemini/settings.json（{"mcpServers":{"reviewer":{"command":"/bin/bash","args":["-lc","uvx --from rag-reviewer@latest reviewer-mcp"]}}})
- Antigravity：~/.gemini/antigravity/mcp_config.json（相同的 mcpServers 格式）
- Windsurf：~/.codeium/windsurf/mcp_config.json（相同的 mcpServers 格式）
- Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS），%APPDATA%\Claude\claude_desktop_config.json（Windows）（相同的 mcpServers 格式）
- Mimo Code：~/.config/mimocode/mimocode.json（{"mcp":{"reviewer":{"type":"local","command":["/bin/bash","-lc","uvx --from rag-reviewer@latest reviewer-mcp"],"enabled":true}}})
- OpenCode：~/.config/opencode/opencode.json（{"mcp":{"reviewer":{"type":"local","command":["/bin/bash","-lc","uvx --from rag-reviewer@latest reviewer-mcp"]}}})
- Kimi Code：~/.kimi-code/mcp.json（{"mcpServers":{"reviewer":{"command":"/bin/bash","args":["-lc","uvx --from rag-reviewer@latest reviewer-mcp"]}}})
- Codex CLI：~/.codex/config.toml ([mcp_servers.reviewer] command="/bin/bash" args=["-lc","uvx --from rag-reviewer@latest reviewer-mcp"])
- VS Code：~/Library Application Support/Code/User/mcp.json（key是“servers”而不是“mcpServers”：{"servers":{"reviewer":{"command":"/bin/bash","args":["-lc","uvx --from rag-reviewer@latest reviewer-mcp"]}}})
- 写完配置文件后，运行：uvx --from rag-reviewer reviewer check
- 报告写了哪个配置文件以及检查是否通过。
```
---
## 安装
MCP 服务器作为 [`rag-reviewer`](https://pypi.org/project/rag-reviewer/) 发布到 PyPI 上，并通过 `uvx` 运行 - **无需克隆此仓库**。
要求：Docker，[`uv`](https://docs.astral.sh/uv/getting-started/installation/)（包括 `uvx`），Voyage API 密钥，GitHub令牌。Python 3.11–3.13（仅在 `pip` / 可编辑安装时需要；`uvx` 管理其自己的）。
### 快速设置（推荐，所有平台）
```bash
# 0）全局安装 reviewer CLI - 一次
uv tool install rag-reviewer
# uv 和 uvx 是同一个二进制文件；安装 uv 会给你两个。
# MCP 服务器由您的编辑器启动，使用最新的 uvx 并自动自我更新。
# 1）基础设施
curl -O https://raw.githubusercontent.com/mimfort/rag_for_git/main/docker-compose.yml
docker compose up -d # Postgres/ParadeDB (:5433) + Neo4j (:7687)
# 2）交互式向导配置密钥和设置
reviewer init
# 交互式向导：填写 VOYAGE_API_KEY，GITHUB_TOKEN 和可选组
# （存储，多仓库，任务板）。重新运行任意时间以更新设置。
# CI / 非交互式：reviewer init --yes （接受所有默认值默默地）
# 3）在您的编辑器/CLI中注册MCP服务器（和技能）
reviewer install --all # 自动检测已安装的客户端 + 安装技能
# 或特定客户端：reviewer install cursor|vscode|claude-code|claude-desktop|windsurf|gemini|antigravity|mimo|opencode|kimi|trae|codex
# 技能适用于支持它们的客户端（Gemini/Mimo/Kimi）；添加 --no-skills 跳过
# 4）验证
reviewer check
# 后续更新 CLI：
uv tool upgrade rag-reviewer
```
> **`reviewer install` 跨平台** （Windows / macOS / Linux）。它自动注入 `uvx` 的绝对路径 - 不需要 `bash -lc` 包装器。手动 JSON 配置使用 `bash -lc` 仅适用于 macOS/Linux；Windows 使用 `reviewer install` 或设置 `"command": "uvx"` 和 `"args": ["--from", "rag-reviewer@latest", "reviewer-mcp"]` 直接。
> **Claude Code：工具开箱即用。** `reviewer install claude-code` 还会在您的全局 `~/.claude/settings.json` 中写入一个 allowlist 规则 `mcp__reviewer__*` 到您的全局文件，允许 reviewer MCP 工具在 **每个** 项目中运行，而不会触发 `auto` 模式的安全分类器 - 不需要手动设置编辑。全局有效，它也涵盖了插件（市场）安装，服务器在任何地方都可用，但不附带权限授予。
> **密钥读取位置。** 审查者解析其 `.env` 文件，从固定位置开始，**不** 是当前工作目录 - MCP 客户端启动服务器时使用任意 CWD，因此项目本地 `.env` 文件不可靠。查找顺序： `$REVIEWER_ENV_FILE` → `$XDG_CONFIG_HOME/rag-reviewer/.env` （默认为 `~/.config/rag-reviewer/.env`）→ `./.env` （当从仓库克隆运行时方便）。实际环境变量始终胜过文件中的变量，因此您也可以通过 `"env": { "VOYAGE_API_KEY": "…", "GITHUB_TOKEN": "…" }` 块在您的 MCP 客户端配置文件中传递密钥 - 在每个客户端中都有效。
- **Voyage** (`VOYAGE_API_KEY`)：https://dashboard.voyageai.com/ - 免费令牌池；附加卡片以提高 3 RPM / 10K TPM 限制（仅在超出免费池时收费）。
- **GitHub** (`GITHUB_TOKEN`)：具有 *拉取请求：读取和写入* + *内容：读取* 的 PAT（精细粒度）或 `repo` 范围（经典）。快速选项：`gh auth token`。
所有其他设置都有默认值（在 `.env.example` 和下面 [配置参考](#configuration-reference) 中记录）。
### 手动设置（替代方案）
如果您更喜欢手动配置客户端配置，而不是使用 `reviewer install`：
每个 AI 编码工具都有自己的配置文件。请选择您需要的：
| 工具 | 全局配置文件 | 项目配置文件 | 安装指南 |
| --- | --- | --- | --- |
| **Claude Code** | `/plugin marketplace add`（见下文） | `.claude-plugin/` ✓ | — |
| **Cursor** | `~/.cursor/mcp.json` | `.cursor/mcp.json` ✓ | — |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | — | — |
| **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`；Windows: `%APPDATA%\Claude\claude_desktop_config.json` | — | — |
| **Antigravity** | `~/.gemini/antigravity/mcp_config.json` | — | — |
| **Mimo Code** | `~/.config/mimocode/mimocode.json` | `.mimocode/mimocode.json` ✓ | [INSTALL.md](.mimocode/INSTALL.md) |
| **OpenCode** | `~/.config/opencode/opencode.json` | `.opencode/opencode.json` ✓ | [INSTALL.md](.opencode/INSTALL.md) |
| **Kimi Code** | `~/.kimi-code/mcp.json` | `.kimi-code/mcp.json` ✓ | [INSTALL.md](.kimi-code/INSTALL.md) |
| **Gemini CLI** | `~/.gemini/settings.json` | `.gemini/settings.json` ✓ | [GEMINI.md](GEMINI.md) |
| **Codex CLI** | `~/.codex/config.toml` | `.codex-plugin/plugin.json` ✓ | [AGENTS.md](AGENTS.md) |
| **Copilot CLI** | — | `.github-copilot/plugin.json` ✓ | — |
| **Trae IDE** | `~/Library/Application Support/Trae/User/mcp.json` | — | — |
| **VS Code** | `~/Library/Application Support/Code/User/mcp.json`（键：`servers`，而非 `mcpServers`） | — | — |
标记 ✓ 的文件已存在于此仓库中 — 如果您将 `rag_for_git` 作为项目在该工具中打开，MCP 服务器将自动连接。对于**全局安装**（可在任何项目中使用），请将条目添加到相应的全局配置文件中。
每个工具的 MCP 条目格式（macOS/Linux — 在 Windows 上使用 `reviewer install`）：
**Mimo Code** (`mimocode.json`)：
```json
{
"$schema": "https://mimo.xiaomi.com//config.json",
"mcp": {
"reviewer": {
"type": "local",
"command": ["/bin/bash", "-lc", "uvx --from rag-reviewer@latest reviewer-mcp"],
"enabled": true
}
}
}
```
**OpenCode** (`opencode.json`)：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"reviewer": {
"type": "local",
"command": ["/bin/bash", "-lc", "uvx --from rag-reviewer@latest reviewer-mcp"]
}
}
}
```
**Kimi Code / Cursor / Gemini CLI / Codex CLI / Trae / Claude Desktop / Windsurf / Antigravity**（标准 `mcpServers` JSON）：
```json
{
"mcpServers": {
"reviewer": {
"command": "/bin/bash",
"args": ["-lc", "uvx --from rag-reviewer@latest reviewer-mcp"]
}
}
}
```
**VS Code** (`mcp.json` — 注意：键为 `servers`，而非 `mcpServers`）：
```json
{
"servers": {
"reviewer": {
"command": "/bin/bash",
"args": ["-lc", "uvx --from rag-reviewer@latest reviewer-mcp"]
}
}
}
```
**Codex CLI** (`~/.codex/config.toml`)：
```toml
[mcp_servers.reviewer]
command = "/bin/bash"
args = ["-lc", "uvx --from rag-reviewer@latest reviewer-mcp"]
```
添加后，重启工具 — `reviewer` 将与其他 MCP 服务器一起出现。
### Claude Code（插件市场）
两个命令，从任何项目：
```text
/plugin marketplace add mimfort/rag_for_git
/plugin install rag-reviewer@rag-reviewer-marketplace
```
您将获得：
- **技能：** `/rag-reviewer:reviewer_review-pr`，`/rag-reviewer:reviewer_solve-task`，
`/rag-reviewer:reviewer_sync-codebase`，`/rag-reviewer:reviewer_sync-tasks`，
`/rag-reviewer:reviewer_performance-review`，`/rag-reviewer:reviewer_maintainability-review`，
`/rag-reviewer:reviewer_ask`（参见 [技能参考](#技能参考)）。
- **MCP 服务器** `reviewer` 暴露了 [MCP 工具参考](#mcp-工具参考) 中的 20 种工具。
> 运行 `/plugin` 以确认 `rag-reviewer` 已安装并启用。
### 全局安装技能（可选）
7 种技能封装了 MCP 工具成引导流程。没有它们，您仍然可以直接调用 MCP 工具，但技能是预期的入口点。
**`reviewer install` 已为支持基于文件的技能的客户端（Gemini、Mimo、Kimi）安装了它们**。要（重新）安装仅限技能 — 或选择特定客户端 — 请使用：
```bash
uvx --from rag-reviewer reviewer install-skills --all # 所有检测到的支持技能的客户端
uvx --from rag-reviewer reviewer install-skills gemini # 特定客户端
uvx --from rag-reviewer reviewer install-skills --list # 显示目标 + 目录
```
它从 GitHub 下载技能（无需仓库克隆）并将它们解压到每个客户端的全局技能目录中，并带有路径遍历保护。手动备用（等效）：
```bash
curl -sL https://github.com/mimfort/rag_for_git/archive/refs/heads/main.tar.gz -o /tmp/rag-reviewer.tgz
mkdir -p ~/.gemini/skills
tar xz -C ~/.gemini/skills --strip-components=3 -f /tmp/rag-reviewer.tgz 'rag_for_git-main/plugin/skills'
rm /tmp/rag-reviewer.tgz
```
| 工具 | 全局技能目录 |
| --- | --- |
| Gemini CLI | `~/.gemini/skills/` |
| Mimo Code | `~/.config/mimocode/skills/` |
| Kimi Code | `~/.kimi-code/skills/` + `extra_skill_dirs` in `~/.kimi-code/config.toml` |
| OpenCode | `~/.config/opencode/skills/` |
| Claude Code | 插件中捆绑（上述步骤） |
| Cursor | 通过 `.cursor-plugin/plugin.json` 进行项目级 |
就这样。构建基础索引（推荐 — 参见 [CLI 参考](#cli-参考)）并审查 PR（参见 [插件使用](#插件使用)）。
---
## 配置参考
所有内容都通过环境变量（`.env`，参见 `.env.example` 带有注释）进行配置。
**唯一必需的外部密钥是 `VOYAGE_API_KEY`**；`GITHUB_TOKEN` 是 PR 审查所必需的。
所有其他设置都有匹配的 `docker-compose.yml` 默认值。`.env` 从 `$REVIEWER_ENV_FILE` → `~/.config/rag-reviewer/.env` → `./.env` 解析（实际环境变量始终生效）。
### Voyage — 嵌入 + 重新排序（必需）
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `VOYAGE_API_KEY` | `""` | **必需。** Voyage 嵌入和重新排序的密钥。 |
| `EMBEDDING_MODEL` | `voyage-code-3` | 嵌入模型。 |
| `EMBEDDING_DIM` | `1024` | 嵌入维度；**必须**与 Postgres 中的 `vector(N)` 列匹配 — 更改它需要重新索引。 |
| `EMBEDDING_BATCH_SIZE` | `256` | 每个嵌入请求的文本数量（≤1000 和 ≤120K 个令牌）。 |
| `RERANK_MODEL` | `rerank-2.5` | Voyage 重新排序模型。 |
### GitHub（PR 审查必需）
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `GITHUB_TOKEN` | `""` | PAT — *拉取请求：读取和写入* + *内容：读取*。 |
| `GITHUB_RETRY_ATTEMPTS` | `3` | GitHub API 网络错误的重试次数。 |
| `GITHUB_RETRY_BACKOFF_BASE` | `1.0` | 指数退避基数（秒）。 |
### 存储（Postgres/ParadeDB + Neo4j）
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `PG_DSN` | `postgresql://reviewer:reviewer@localhost:5433/reviewer` | ParadeDB（pgvector + pg_search）位于主机端口 **5433**。 |
| `PG_POOL_MIN_SIZE` | `1` | Postgres 连接池最小值。 |
| `PG_POOL_MAX_SIZE` | `4` | Postgres 连接池最大值。 |
| `NEO4J_URI` | `neo4j://localhost:7687` | Neo4j bolt URI。 |
| `NEO4J_USER` | `neo4j` | Neo4j 用户。 |
| `NEO4J_PASSWORD` | `reviewerpass` | Neo4j 密码（一次性开发默认值）。 |
| `GRAPH_BACKEND` | `auto` | 代码图引擎：`auto`（如果 PATH 中有 `scip-python`，则为 SCIP，否则为 tree-sitter），`scip`，`treesitter`。 |
### 多仓库 / 多分支（可选）
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `DEFAULT_REPO` | `""` | 默认 `owner/name` 用于无会话工具和 `--repo` ；
| 空值 = 多仓库（必须显式传递仓库）。
### 审查策略（env 默认值；per-repo `.review.yml` 重写）
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `REVIEW_SEVERITY_THRESHOLD` | `medium` | 保留的最低严重程度：`low`/`medium`/`high`/`critical`。 |
| `REVIEW_MIN_CONFIDENCE` | `0.5` | 丢弃置信度低于此值（0..1）的发现。 |
| `REVIEW_MAX_COMMENTS` | `25` | 每篇评论的内联评论上限。 |
| `REVIEW_MAX_FILES` | `50` | 审查的 `.py` 文件上限；其余文件放入摘要中跳过。 |
| `REVIEW_CATEGORIES` | `""` | CSV 类别白名单（`correctness`、`security`、`performance`、`style`、`requirements`）；空值 = 全部。 |
| `REVIEW_SUGGESTIONS` | `apply` | `apply` = 可应用的 GitHub `suggestion` 块；`text` = 纯文本建议。 |
| `REVIEW_OUTPUT_LANGUAGE` | `ru` | 已发布发现的文本语言。 |
| `REVIEW_SKIP_DRAFTS` | `true` | 不审查草稿 PR。 |
| `MAX_TOOL_RESULT_CHARS` | `8000` | 输入提示的最大工具结果长度。 |
### 可观察性和会话（可选）
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `REVIEW_HISTORY` | `true` | 在 Postgres 中记录运行历史（`review_runs`/`review_findings`），失败-软。 |
| `REVIEW_SESSION_PERSIST` | `true` | 为崩溃恢复将 PR 会话保留在 Postgres 中。 |
| `REVIEW_SESSION_TTL_HOURS` | `24` | 持久会话的 TTL（小时）。 |
| `WEB_ADMIN_USER` | `""` | `reviewer serve` 的基本身份验证用户；空值 = 无身份验证。 |
| `WEB_ADMIN_PASSWORD` | `""` | 基本身份验证密码；空值 = 无身份验证。 |
### 任务板（可选） — 部署范围内的默认值
连接板对于每个团队的每个仓库都是相同的，因此它在
reviewer-mcp 环境中配置一次，而不是在每个仓库的 `.review.yml` 中重复。
[Per-repo policy & task board](#per-repo-policy--task-board)。
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `TASK_BOARD_TYPE` | `""` | 板块类型：`yougile`、`jira`，...（选择技能剧本）。 |
| `TASK_BOARD_MCP` | `""` | 连接的板块 MCP 服务器（LLM 端工具 `mcp__<mcp>__*）。 |
| `TASK_BOARD_KEY_PATTERN` | `""` | 任务密钥正则表达式，例如 `[A-Z]+-\d+`。 |
| `TASK_BOARD_URL_TEMPLATE` | `""` | 任务链接模板，例如 `https://ru.yougile.com/team/<id>/#{code}`。 |
| `TASK_BOARD_API_KEY` | `""` | 服务器端批量同步的 **REST API 密钥**（`sync_board`）。服务器内部 — 从不返回客户端。 |
| `TASK_BOARD_API_BASE` | `""` | REST API 基础 URL；空值 → 默认按类型（`yougile`：`https://yougile.com/api-v2）。 |
> **获取 `TASK_BOARD_API_KEY`（Yougile）。**：`POST /api-v2/auth/companies {login,password}`），然后 `POST /api-v2/auth/keys {login,password,companyId}`。
> 属于 **仅限** reviewer-mcp 环境（`~/.config/rag-reviewer/.env`），不在聊天或客户端配置中返回。
---
## CLI 参考
所有命令均通过 `uvx --from rag-reviewer <command>` 或在安装 `uv tool install rag-reviewer` / `pip install -e ".[dev]"` 后直接使用 `reviewer`。安装了两个入口点：
`reviewer`（下面的 CLI）和 `reviewer-mcp`（MCP 服务器，由您的编辑器/插件启动）。
| 命令 | 参数 | 选项 | 用途 |
| --- | --- | --- | --- |
| `check` | — | — | 验证环境准备情况（密钥、Postgres、Neo4j、GitHub）。每项打印 ✓/✗；如果有问题，则退出 1。不会消耗 Voyage 额度。 |
| `init` | — | `--path FILE`（默认 `~/.config/rag-reviewer/.env`）， `--yes`（接受默认值，CI 模式） | 交互式向导，编写 `.env`（Voyage/GitHub + 可选组）。 |
| `install` | `[client]` | `--all`， `--list`， `--path FILE`， `--pin VERSION`， `--no-latest`， `--no-skills`， `--dry-run` | 在 AI 客户端中注册 MCP 服务器（和技能）（跨平台）。 |
| `install-skills` | `[client]` | `--all`， `--list`， `--path FILE` | 仅将技能安装到客户端的全局技能目录中。 |
| `update` | — | — | 检查 PyPI 以获取较新的 `rag-reviewer` 并报告如何升级。 |
| `index` | `<repo>`（本地克隆的路径） | `--ref BRANCH`（读取的 git 引用；默认值 = 主分支）， `--branch NAME`（存储键；默认值 = `--ref`）， `--repo OWNER/NAME`（默认值来自 git `origin`） | 构建/更新分支的基础索引（向量 + 图）。一次完成，然后增量。 |
| `search` | `<query>` | `--repo OWNER/NAME`（默认 `DEFAULT_REPO`）， `--branch NAME`（默认主分支） | 诊断混合搜索整个分支的基础索引。 |
| `status` | `[path]`（默认 `.`） | `--repo OWNER/NAME`（默认来自 git `origin`）， `--branch NAME`（默认：所有 `REVIEW_BRANCHES`） | 索引健康/新鲜度与克隆的 HEAD 相比。不会消耗 Voyage 额度。 |
| `migrate-branches` | — | — | 一次性：将旧的 `ref="base"` 重命名为 `base:<primary>` 以升级到多分支。 |
| `serve` | — | `--host HOST`（默认 `127.0.0.1`）， `--port PORT`（默认 `8000`） | 在主机上运行可观察性 Web 管理控制台。 |
| `reviewer-mcp` | — | — | MCP 服务器（stdio 传输）。由插件/编辑器启动。 |
示例：
```bash
# 首次设置
uvx --from rag-reviewer reviewer init
uvx --from rag-reviewer reviewer install --all
uvx --from rag-reviewer reviewer check
# 构建基础索引（整个仓库上下文，用于 RAG + 图）
uvx --from rag-reviewer reviewer index /path/to/repo --ref main --repo owner/name
uvx --from rag-reviewer reviewer index /path/to/repo --ref master --repo owner/name # 第二个跟踪分支
# 诊断（无 Voyage 支出，除 `search` 外）
uvx --from rag-reviewer reviewer search "token verification" --branch master
uvx --from rag-reviewer reviewer status /path/to/repo --branch dev
# Web 管理控制台
uvx --from rag-reviewer reviewer serve --host 127.0.0.1 --port 8000
```
审查有效，即使没有先前的 `index` — 上下文仅限于差异和叠加层（RAG/图为“薄”）。对于完整的仓库影响分析，请针对目标分支运行 `index`。
---
## 技能参考
技能是工作流的引导式入口点。安装插件后，它们在 Claude Code 中被调用为 `/rag-reviewer:<name>`（前导 `/rag-reviewer:` 是插件命名空间；在其他客户端，技能名称相同）。参数作为技能名称后的自由文本传递 (`$ARGUMENTS`)。
### `reviewer_review-pr` — 完整的 PR 审查
协调三个阶段的流程（`prepare_review` → 子代理 → `publish_review`）。
- **参数：** PR 为 `owner/repo#N`、`owner/repo N` 或 GitHub PR URL。添加 `--dry-run` 来组装完整的报告 **而不** 发布到 GitHub。
- **使用的 MCP 工具：** `prepare_review`、`search_code`、`get_related_symbols`、`read_file`、
`get_definition`、`find_callers`、`get_changed_file_diff`、`publish_review`；另外，
`index_task`/`get_task_context`/`search_tasks` 当连接了任务板时。
- **流程：** 准备（PR + 策略 + 单元 + 板块配置）→ 将一个分析子代理分发到每个文件 →
并行 **性能** / **可维护性** 维度（+ **需求** 如果存在 `TaskBrief`）→ **验证** 传递（丢弃 `is_real=false` 发现）→ 发布（门控/接地/去重/组装）。
如果 `prepare_review` 返回 `status:"skipped"`（目标分支未跟踪），则停止；草稿 PR 除非 `REVIEW_SKIP_DRAFTS=false`，否则跳过。
### `reviewer_solve-task` — 收集任务上下文，然后交给开发人员
读取任务（如果有密钥和板块），拉取相关/类似任务和相关代码，蒸馏简报，
然后进入头脑风暴。它规范了上下文收集 — 它 **不** 编写代码。
- **参数：** 任务密钥（例如 `PRI-4`，必须匹配 `key_pattern`）**或** 自由文本描述
（例如“添加注销端点”）。无板块模式会回落到描述 + 代码搜索。
- **使用的 MCP 工具：** `get_board_config`、`index_task`、`get_task_context`、`search_tasks`、
`search_codebase`、`related_symbols`、`callers`、`definition`、`get_pr_diff`；另外，
连接的板块 MCP (`mcp__<board>__*`) 以读取任务。
- **流程：** 解析板块配置 → 标识任务（密钥 vs. 自由文本）→ 尽力而为、开放失败的上下文收集（任务图、类似任务、相关代码、惰性 PR 差异）→ 蒸馏结构化简报（任务 / 相关工作 / 相关代码 / 约束）→ 将简报作为种子交给
`superpowers:brainstorming` 进行头脑风暴。
### `reviewer_sync-codebase` — 构建/更新基础索引
`reviewer index` 的薄包装，用于从本地克隆构建/更新基础索引。
- **参数（均可选）：** `--path <path>`（默认：CWD）， `--ref <branch>`（默认：`main`），
`--repo <owner/name>`（默认：从 `git remote get-url origin` 派生），
`--backend <auto|scip|treesitter>`（默认：`auto`，设置 `GRAPH_BACKEND`）。
- **使用的 MCP 工具：** 无直接 - 它调用 `uvx --from rag-reviewer reviewer index`。
- **流程：** 解析输入 → 检查先决条件 (`uvx`，git 仓库，`reviewer check`，Docker 启动) →
运行索引 → 可选 `reviewer search` 验证 → 报告块/节点/边和使用的图后端。
### `reviewer_sync-tasks` — 预热任务图和向量存储
`sync_board` 服务器端 ETL 工具的薄触发器 — review 通过 REST 调用板块，
因此 LLM 不会传递任何任务文本（O(1) 个令牌，无论板块大小）。
- **参数（均可选）：** `--board <name>`（限制为一个板块/项目）， `--limit <N>`（烟雾
运行；**禁用** 清除和水印推进）， `--purge-orphaned`（删除不再在板块上的任务；
默认情况下已关闭）， `--no-keep-with-prs`（使用清除功能时，也删除具有 PR 历史的任务 —
默认情况下受保护）。
- **使用的 MCP 工具：** `sync_board`（单个调用）。
- **流程：** 映射参数 → 调用 `sync_board(...)` → 打印计数摘要（已枚举/更改/
嵌入/未更改/失败，清除，警告）。如果 `{"status":"error",...}` 板块未正确配置服务器端 —
在 `~/.config/rag-reviewer/.env` 中设置 `TASK_BOARD_*` 并重新连接。
### `reviewer_performance-review` — 性能评估
仅评估性能/效率风险（N+1 查询、重复工作、糟糕的渐近复杂度、缺少批处理/缓存、阻塞 I/O、内存增长）。
- **参数（独立运行）：** `scope` — `staged`、`unstaged`、`uncommitted`、`branch-vs-base`、`a commit`、`a branch comparison`、`a file list` 或类似 PR 的范围。如果不明确，它会询问。在 `reviewer_review-pr` 内部，它作为提供的单元差异的一个维度运行。
- **使用的 MCP 工具（在 PR 管道中运行）：** `search_code`、`read_file`、`find_callers`、`get_related_symbols`、`get_definition`、`get_changed_file_diff`。
- **输出：** JSON `{"findings":[{category:"performance", severity, file, line, side, code_quote, message, suggestion, fix, confidence}]}`。
### `reviewer_maintainability-review` — 可维护性评估
仅评估可维护性风险（不必要的复杂性、糟糕的可读性、重复、弱关注点分离、约定偏移）。
- **参数（独立运行）：** 与性能评估相同的范围选项。在 `reviewer_review-pr` 内部，它作为提供的单元差异的一个维度运行。
- **使用的 MCP 工具（在 PR 管道中运行）：** `search_code`、`get_related_symbols`、`read_file`、`get_definition`、`find_callers`、`get_changed_file_diff`。
- **输出：** JSON `{"findings":[{category:"maintainability", severity, file, line, side, code_quote, message, suggestion, fix, confidence}]}`。
### `reviewer_ask` — 基于代码库的 Q&A
使用 RAG + 代码图回答关于代码库的自由文本问题，并提供引用（`path:line`）。
- **参数：** 自由文本问题（例如 "where is authentication"、"how does index freshness work"、"explain the retrieval pipeline"）。
- **使用的 MCP 工具：** `search_codebase`、`related_symbols`、`callers`、`definition`；另外还有 `Read`/`Grep`/`Glob`。
- **流程：** 解析仓库/分支 → `search_codebase` → 可选地通过图扩展 → 使用证据列表的 `path:line` 引用回答。
---
## MCP 工具参考
`reviewer-mcp` 服务器暴露了 20 种工具。PR 会话工具需要为该 `(repo, pr)` 激活 `prepare_review`；其余工具则是无会话的。
### 审查生命周期
| 工具 | 签名 | 返回 / 执行 |
|---|---|---|
| `prepare_review` | `(repo: str, pr: int)` | 打开 PR 会话：同步基准索引、构建 PR 叠加层、加载策略、组装每个文件单元。返回 PR 元数据 + 策略 + 单元（或对于未跟踪的目标分支的 `{"status":"skipped"}`）。 |
| `publish_review` | `(repo, pr, summary, findings: list[dict], dry_run=False, task_key=None)` | 确定性尾部：门控 → 接地 → 去重 → 内联/摘要拆分 → 发布到 GitHub → 历史记录 → 叠加层清理。`dry_run=true` 返回报告而不发布；`task_key` 将 PR 链接到实际发布时的任务。 |
每个发现： `{category, severity(low|medium|high|critical), file, line, side(RIGHT|LEFT), code_quote, message, suggestion, fix:{start_line,end_line,replacement}|null, confidence:0..1}`。
### PR 会话分析工具（需要 `prepare_review`）
| 工具 | 签名 | 返回 / 执行 |
|---|---|---|
| `search_code` | `(repo, pr, query: str)` | `base ∪ overlay` 的混合语义 + 词汇搜索。 |
| `get_related_symbols` | `(repo, pr, node_id: str)` | `node_id` = `path#fqn` 的图邻居（调用/实现）。 |
| `read_file` | `(repo, pr, path, start=1, end=400)` | PR HEAD 处的源代码（1-based, inclusive）。 |
| `get_definition` | `(repo, pr, symbol: str)` | 符号定义（图 → 索引 → 语义备用）。 |
| `find_callers` | `(repo, pr, node_id: str)` | `node_id` `path#fqn` 的直接调用者（影响分析）。 |
| `get_changed_file_diff` | `(repo, pr, path: str)` | 相同 PR 中另一个更改文件的统一差异。 |
### 无会话工具（Q&A、`solve-task`）
| 工具 | 签名 | 返回 / 执行 |
|---|---|---|
| `search_codebase` | `(repo, query, top_k=10, branch=None, include_tests=False)` | 仓库基准索引的混合搜索；默认情况下行号、去重、测试排除。 |
| `related_symbols` | `(repo, node_id, branch=None)` | 符号的图邻居（调用/实现/测试）。 |
| `callers` | `(repo, node_id, branch=None)` | `node_id` `path#fqn` 的传入 `CALLS`。 |
| `definition` | `(repo, symbol, branch=None)` | 符号定义（图 → 索引 → 语义备用）。 |
| `get_pr_diff` | `(repo, number: int)` | 任意（历史）PR 的统一差异；上限，软故障。 |
### 任务 / 看板
| 工具 | 签名 | 返回 / 执行 |
|---|---|---|
| `sync_board` | `(board=None, limit=None, purge_orphaned=False, keep_with_prs=True)` | 服务器端 ETL：通过 REST 枚举看板，标准化为 `TaskBrief`，索引。增量式，通过每个看板的 watermark；O(1) tokens。 |
| `index_task` | `(task: dict)` | 将一个标准化的 `TaskBrief` 索引到任务图 + 向量存储（幂等）。 |
| `index_tasks_batch` | `(tasks: list[dict])` | 对于列表，同样在一个 Voyage 调用中。 |
| `search_tasks` | `(query, top_k=5)` | 来自索引语料库的语义相似任务。 |
| `get_task_context` | `(key: str)` | 图上下文：任务、其 PR、链接任务及其 PR 和受影响代码。 |
| `purge_orphaned_tasks` | `(active_keys: list[str], keep_with_prs=True)` | 删除不再位于看板上的任务（默认情况下 PR 链接任务受保护）。 |
| `get_board_config` | `()` | 部署范围的看板配置（`TASK_BOARD_*`）；`sync-tasks`/`solve-task` 的备用。凭证 **不** 返回。 |
---
## 插件使用
安装插件并在仓库根目录打开 Claude Code，调用技能：
```text
/rag-reviewer:reviewer_review-pr owner/repo#42 # 审查 PR（准备 → 子代理 → 发布)
/rag-reviewer:reviewer_review-pr owner/repo#42 --dry-run # 组装报告而不发布
/rag-reviewer:reviewer_sync-codebase --ref main # 构建/更新向量存储 + 代码图
/rag-reviewer:reviewer_sync-tasks # 预热任务图（服务器端 ETL)
/rag-reviewer:reviewer_solve-task PRI-4 # 收集任务上下文，然后交给开发人员
/rag-reviewer:reviewer_ask how does index freshness work # 基于代码库的 Q&A
```
典型的端到端运行：
```bash
git clone https://github.com/ORG/REPO /tmp/REPO
reviewer index /tmp/REPO --ref main # 为 main 构建基准索引 + 图
reviewer index /tmp/REPO --ref master # 可选地索引第二个分支（REVIEW_BRANCHES=main,master）
# 在 Claude Code 中（从仓库根目录）： /rag-reviewer:reviewer_review-pr ORG/REPO#42
```
---
## 每个仓库的策略和任务看板
目标分支中的 `.review.yml` 文件覆盖环境默认值（PR 不能削弱其自身的审查 - 参见*注意事项*）：
```yaml
categories: { correctness: true, security: true, performance: true, style: false, requirements: true }
severity_threshold: medium
min_confidence: 0.5
paths: { ignore: ["**/migrations/**", "vendor/**"] }
max_comments: 25
# 可选任务上下文：从看板读取任务并检查需求合规性。
# 看板（MCP）由用户在 Claude Code 侧连接；插件不包含它。
task_board:
type: yougile # yougile | jira — 选择技能剧本
mcp: yougile # 连接的看板 MCP 服务器（工具为 mcp__<mcp>__*）
key_pattern: "[A-Z]+-\\d+" # 可选；匹配 Yougile PRI-34/ID-34 和 Jira PROJ-123
```
**`task_board` 块是部署范围的默认值，而不是每个仓库的要求。** 看板连接对于一个团队的所有仓库都是相同的，因此 **一次** 在 reviewer `.env` 中配置它（`TASK_BOARD_TYPE` / `TASK_BOARD_MCP` / `TASK_BOARD_KEY_PATTERN` / `TASK_BOARD_URL_TEMPLATE`），每个仓库继承它 - 只需 `.review.yml` 即可，无需看板。`task_board` 块在仓库的 `.review.yml` 中 **覆盖** 该默认值；显式空 `task_board:` **禁用** 看板。`review-pr` 通过策略读取它；`solve-task` 通过 `get_board_config` MCP 工具（和看板-MCP，LLM 端）作为备用，当本地 `.review.yml` 没有块时。
**批量任务同步是服务器端，而不是 LLM（`sync-tasks`）。** `sync-tasks` 技能是一个薄触发器：它调用一个 MCP 工具，`sync_board(board, limit, purge_orphaned, keep_with_prs)`，而 reviewer 服务器通过 **REST** 自身枚举看板（在 `TaskBoardProvider` 接口后面 - Yougile 是参考），将每个任务标准化为 `TaskBrief`，然后通过现有批量索引器索引。LLM 不传递任何任务文本，因此同步成本为 O(1) 个 token，无论看板大小如何。它通过每个看板的 timestamp watermark 索引元数据（`ref="tasks:<board>"`）是增量式的；`--limit` 禁用清理和 watermark Advance。看板 REST 凭证仅存在于 reviewer-mcp 环境（`TASK_BOARD_API_KEY` / `TASK_BOARD_API_BASE`）。这反转了“reviewer Python 从不触摸看板”的规则 **仅适用于批量同步** - `solve-task` / `review-pr` 中的单个任务读取仍然通过 LLM 端的看板-MCP 进行。
任务图（`:Task`）是全局的，因此一个任务可以跨多个微服务仓库。
#### 上下文层（PRI-161）
- `paths.ignore` — `fnmatch` 模式列表；列出的路径 **不索引** （向量和图）并且不评论。纯文件夹名称（例如 `eval`）捕获所有子树；`eval/*` - 显式相同；glob - 例如 `*.gen.py`。节省 Voyage 配额并去除噪音。
- `summary_cluster_depth_overrides` - `prefix → depth` 映射以进行汇总聚类的点深度（按路径段的最长前缀匹配）；补充全局 `summary_cluster_depth`。更改深度会重新编译受影响的汇总。
- `summary_topk_threshold` - 汇总的系统阈值。如果存储库/分支的 **超过** 阈值，则在查询时使用 ANN top-k 接近度查询；否则，所有汇总都被发送完整（与小存储库的兼容行为）。默认值来自 env（`SUMMARY_TOPK_THRESHOLD`，20）。
所有键都来自目标分支的 `.review.yml`。示例 - 在根 `.review.yml` 中。
---
## 可观察性 Web 管理
每个 `publish_review` 都在 Postgres 中记录运行（`review_runs` / `review_findings`）：存储库/PR、模型、时间、状态、发现以及是否发布。写入是 **软故障**（写入失败永远不会破坏审查），并且由 `REVIEW_HISTORY` 控制（默认为 `true`）。Web 管理界面（FastAPI + React/Vite SPA）显示运行历史、聚合（门控过滤率、时间趋势、按类别/严重程度的发现）和运行详细信息以及发现的钻取。
```bash
# 在主机上 - 构建前端，然后提供 SPA + FastAPI：
pip install -e ".[web]"
(cd web/frontend && npm install && npm run build)
reviewer serve # http://127.0.0.1:8000 （选项：--host / --port）
```
API：`GET /api/runs`（可过滤列表），`GET /api/runs/{id}`（运行 + 发现），`GET /api/runs/{id}/trace`（步骤跟踪，仅向前 - 空白表示预功能运行），`GET /api/stats?days=N`（聚合）。
---
## 已知限制和注意事项
关于此功能列表以及当前不执行的功能：
- **没有自动触发。** 审查不会在 PR 打开/更新时启动。它是 Claude Code 中的手动技能调用 - 默认情况下没有 GitHub 应用程序 / webhook / CI 集成。
- **图自动重新索引是增量式，不是全精度。** 在 `prepare_review` 中，当基准分支 SHA 漂移时，代码图会针对更改的文件进行修补（tree-sitter，存储库范围）与自愈向量块 - 传入的 `CALLS` 边来自未更改的调用者得以保留。直到下一个手动 `reviewer index`：`IMPLEMENTS` 边，来自未更改的文件的输出 `CALLS` 边以及来自未更改调用者的新传入 `CALLS` 边。完整的 SCIP 精确性通过 `reviewer index` 恢复。
- **多仓库通过 `repo` 区分符。** 一个部署程序托管多个存储库，通过 Postgres 和 Neo4j 中的 `repo`（`owner/name`）列/属性隔离。每个审查都限定为其 PR 的存储库（不跨存储库检索）。使用 `reviewer index <path> --repo owner/name` 索引存储库（或从 git `origin` 远程派生，或设置 `DEFAULT_REPO`）。任务图（`:Task`）故意是全局的，以便一个任务可以跨多个微服务存储库。
- **语言范围：仅限 Python。** 切分器（tree-sitter）和 SCIP 后端（`scip-python`）是 Python 特有的。其他语言将位于相同的切分器/`GraphIndexer` 接口后面。
- **VCS 范围：仅限 GitHub。** 仅 GitHub 实现 `VCSProvider`；GitLab/Bitbucket 未实现（抽象存在，供应商不实现）。
- **图后端权衡。** 精确的类型感知图（`CALLS` + `IMPLEMENTS` 边）需要 `scip-python` 在 `PATH` 中。没有它，tree-sitter 后备给 `CALLS`仅限名称（无`IMPLEMENTS`）。模式由`GRAPH_BACKEND=auto|scip|treesitter`选择；在`auto`中，SCIP 失败会静默回落到 tree-sitter 并警告，而`scip`会传播错误。
- **审查范围。** 内联评论仅限于差异行（更改/上下文行）。所有其他内容都进入摘要。仅在安全不变的情况下才发出可应用的`suggestion`块（应用模式，精确替换，整个范围位于右侧差异内，无重叠修复）；否则建议为纯文本。
- **MCP 会话在进程内。** `prepare_review`和`publish_review`之间的状态位于正在运行的`reviewer-mcp`进程中（`_Session`在`MCPReviewService`中）。PR 的两个调用必须命中**相同的**运行服务器 - 会话在之间重启时丢失（由`REVIEW_SESSION_PERSIST`缓解）。
- **Voyage 免费套餐** = 3 RPM / 10K TPM；TPM 是主要的限制因素 - 一个大型存储库的完整`reviewer index`会受到限制（有重试/抖动）。单个 PR 审查（叠加层 + 查询嵌入）适合在限制范围内。
- **LLM 成本。** 审查会扩展 Claude 子代理每个文件 - 那是实际的 token 成本，而不是免费的。
- **Web 管理员身份验证是可选的。** 仅当设置了 `WEB_ADMIN_USER` / `WEB_ADMIN_PASSWORD` 时，才启用基本身份验证；否则它不会针对公共暴露进行加强（`reviewer serve` 默认绑定到环回地址）。
- **GitHub API 限制。** PR 文件列表分页为 100；比较 API 用于重新同步基准索引，返回最多 300 个文件 - 非常大的差异会被截断。
- **`.review.yml` 来自基准分支**（按设计 - PR 不能削弱其自身的审查），而不是 PR HEAD。
## 测试
```bash
.venv/bin/pytest -q # 单元测试：快速，在假数据上；从不命中外部 API
.venv/bin/pytest -m integration # 集成测试：需要运行的 Postgres/Neo4j + Voyage key
.venv/bin/ruff check . # 语法检查（行长 100，目标 Python 3.11）
```
`pytest` 默认情况下会排除集成测试（`addopts = -m 'not integration'`）。外部服务（GitHub，Voyage，Postgres，Neo4j）位于接口后面，在单元测试中被隔离和模拟；实际调用仅在集成/端到端测试中进行。
## 项目布局
```
reviewer/
config/ 设置（pydantic-settings）：环境 → 审查阈值、存储、分支、看板
vcs/ VCSProvider + github.py (httpx) · diff.py (lines available for inline)
index/ 切分器（tree-sitter）· 嵌入（Voyage）· 重新排序器 · 存储（pgvector+pg_search/RRF）· 新鲜度
graph/ 构建器（tree-sitter 调用图）· scip（SCIP 解析器）· 后端（后端协调器）· 存储（Neo4j）
retrieval/ 检索器：混合 + 图扩展 + 重新排序 → ContextPack
llm/ _retry.py（Voyage 的重试/回退）
tools/ 代理工具（search_code，get_related_symbols，read_file，get_definition，...）
tasks/ TaskBrief 标准化 · 看板/（TaskBoardProvider REST：yougile）· TaskService.index_batch
agent/ 状态（ReviewUnit）· 组装 · 复制
mcp/ MCPReviewService：prepare / 工具调用 / 发布；会话管理
services/ ReviewService.prepare：摄取 PR，叠加层，单元
policy/ ReviewPolicy：环境默认值 + .review.yml + 门控
entrypoints/ cli.py（Click）· mcp_server.py（FastMCP，20 种工具）
install.py reviewer init / install / install-skills（跨平台客户端线路）
web/ FastAPI + React/Vite SPA - 可观察性 Web 管理员
app.py 从 Settings 依赖程序集
plugin/ Claude Code 插件（7 种技能 /rag-reviewer:reviewer_*)
docker-compose.yml ParadeDB（pgvector+pg_search）+ Neo4j
```
---
## 贡献
问题和 PR 是欢迎的。要在本地开发该项目：
```bash
git clone https://github.com/mimfort/rag_for_git
cd rag_for_git
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
docker compose up -d # Postgres/ParadeDB (:5433) + Neo4j (:7687)
.venv/bin/pytest -q # 单元测试 - 快速，在假数据上，无外部 API
.venv/bin/ruff check . # 语法检查（行长 100，目标 Python 3.11）
```
外部服务（GitHub，Voyage，Postgres，Neo4j）位于接口后面，在单元测试中被隔离和模拟；实际调用仅在集成/端到端测试中进行。提交消息遵循 Conventional Commits。架构在 [README.ru.md](README.ru.md)（俄语）和 `CLAUDE.md` 中有深入的文档。
## 许可
[MIT](LICENSE) © rag_for_git 贡献者。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器