# https://github.com/alibaba/open-code-review 项目说明书

生成时间：2026-06-05 04:43:11 UTC

## 目录

- [概览与系统架构](#page-1)
- [CLI 命令、评审模式与 Diff 流水线](#page-2)
- [配置体系与四层评审规则解析](#page-3)
- [LLM 集成、WebUI Viewer 与 CI/CD 生态](#page-4)

<a id='page-1'></a>

## 概览与系统架构

### 相关页面

相关主题：[CLI 命令、评审模式与 Diff 流水线](#page-2), [配置体系与四层评审规则解析](#page-3), [LLM 集成、WebUI Viewer 与 CI/CD 生态](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/alibaba/open-code-review/blob/main/README.md)
- [pages/src/i18n/zh.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts)
- [pages/src/i18n/en.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/en.ts)
- [pages/src/components/FeaturesSection.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/components/FeaturesSection.tsx)
- [pages/src/components/QuickStartSection.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/components/QuickStartSection.tsx)
- [pages/src/pages/DocsPage.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/pages/DocsPage.tsx)
- [pages/src/components/BenchmarkSection.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/components/BenchmarkSection.tsx)
- [examples/gitlab_ci/README.md](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/README.md)
</details>

# 概览与系统架构

Open Code Review（简称 `ocr`）是源自阿里巴巴集团内部、经过大规模生产验证后开源的 AI 代码评审 CLI 工具。它读取 Git diff、将变更文件交由可配置 LLM 的 Agent 处理，并产出带有行级精度的结构化评审意见。Agent 可以读取完整文件内容、检索代码库、引用其它变更文件作为上下文，从而进行深度评审，而非仅限于表层 diff 反馈 [资料来源：[README.md:1-15]()]。

## 1. 项目定位与核心理念

通用 Agent 在大变更集下常出现三类问题：覆盖不全（只评部分文件）、位置漂移（行号错位）、质量不稳定（prompt 微调带来大幅波动）。其根因在于纯语言驱动的架构缺乏对评审流程的硬约束 [资料来源：[README.md:24-32]()]。

Open Code Review 的设计哲学是把"确定性工程"与"Agent 推理"组合起来，各司其职：

- **确定性工程**（文件筛选、diff 解析、行号定位、规则路由、并发调度）由代码保证正确性；
- **Agent 推理**（风险识别、上下文探索、问题分类）交由 LLM 处理语义。

这种"硬约束 × 软推理"的混合架构是项目的核心差异点 [资料来源：[README.md:34-42]()]。

## 2. 系统架构

`ocr` 的运行时由 Go 编写的 CLI 承载，前端 `pages/` 提供宣传与文档站。整体可划分为四层：

```mermaid
flowchart LR
    A[用户/GitLab CI] -->|ocr review| B[CLI 入口]
    B --> C[Diff 解析与文件筛选]
    C --> D[规则路由与任务拆分]
    D --> E[Agent 推理循环]
    E --> F[LLM 后端<br/>Anthropic / OpenAI 兼容]
    E --> G[行级定位与反思模块]
    G --> H[评审输出<br/>text / json / WebUI]
```

**图 1：Open Code Review 端到端数据流**

关键模块职责：

| 模块 | 职责 |
|------|------|
| CLI 入口 | 解析 `ocr review / config / viewer` 子命令与 flags |
| Diff 解析 | 从 `git diff` 中识别 staged/unstaged/untracked 三类变更 |
| 规则路由 | 按文件后缀与目录匹配加载评审规则 JSON，生成 user_message |
| Agent 循环 | 多轮 tool-use 调用，搜索代码库、读全文、关联其它变更 |
| 定位与反思 | 3 段渐进式 LLM 策略把评审意见钉到精确行号，并拦截幻觉 |
| 输出层 | 支持 `text`/`json` 终端输出，以及 `ocr viewer` 启用的 WebUI |

## 3. 核心能力

参考官方介绍页的特性矩阵 [资料来源：[pages/src/components/FeaturesSection.tsx:1-40]()][资料来源：[pages/src/i18n/zh.ts:1-60]()]：

- **混合架构**：确定性与 Agent 解耦，工程模块处理"必须正确"的步骤，Agent 处理"需要语义"的部分，平衡质量、token 成本与速度。
- **精确行号定位 + 反思**：独立的行级评论定位模块配合 3 段渐进 LLM 策略；独立的反思模块提前拦截幻觉与知识漂移。
- **多模型协议**：同时支持 Anthropic Messages API 与 OpenAI Chat Completions API，可对接自定义模型端点。
- **动态并发**：子任务并行评审，goroutine 数量可配（默认 8），大变更集也能快速完成。
- **智能记忆压缩**：专为代码评审设计的 3 段（frozen / compress / active）上下文分区管理，突破 token 限制以做深度评审。
- **场景化 Prompt 与工具集**：prompt 与 toolset 均经生产 trace 调优，比通用 Agent + Skills 更稳定可预测。

## 4. 部署形态与边界

`ocr` 主要通过 npm 全局安装或 GitHub Release 二进制分发，CLI 主命令为 `ocr` [资料来源：[README.md:70-95]()][资料来源：[pages/src/components/QuickStartSection.tsx:1-60]()]。配置存放于 `~/.opencodereview/config.json`，支持 `api_url`、`api_key`、`model`、`use_anthropic`、`extra_body`、`language`、`telemetry` 等键值 [资料来源：[pages/src/i18n/zh.ts:14-25]()]。已配置 Claude Code 环境变量（`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_MODEL`）的用户可零额外配置启用 [资料来源：[pages/src/components/QuickStartSection.tsx:40-58]()]。

评审支持三种模式：workspace（默认，评 staged + unstaged + untracked）、branch diff（`--from/--to`）、commit（`--commit`），并可通过 `--background` 传入需求背景以提高评审相关性 [资料来源：[pages/src/pages/DocsPage.tsx:1-120]()]。CI 场景下官方提供了 GitLab CI 示例，可配合 `--concurrency` 等 flag 适配不同 MR 规模 [资料来源：[examples/gitlab_ci/README.md:1-60]()]。

### 已知边界与社区关切

当前实现对评审范围与协议仍存在一些社区讨论中的限制：

- **多模型协议覆盖**：官方主推 Anthropic 与 OpenAI 兼容协议，#49 提议增加 Gemini API 支持，以便本地与 CI 场景复用 [资料来源：[issue #49](https://github.com/alibaba/open-code-review/issues/49)]。
- **支持文件类型白名单**：`supported_file_types.json` 未包含 HarmonyOS 的 `.ets` 后缀，导致 HarmonyOS 项目出现 "No supported files changed" 提示，#47 提议补齐 [资料来源：[issue #47](https://github.com/alibaba/open-code-review/issues/47)]。
- **全量扫描与非 Git 项目**：#40 希望在不手动指定 `--from/--to` 的情况下也能对仓库做全量评审，并支持非 Git 项目 [资料来源：[issue #40](https://github.com/alibaba/open-code-review/issues/40)]。
- **规则合并语义**：当前一个文件只会使用"匹配到的第一个 rule"作为 user_message，#35 期望高优先级 rule 能合并低优先级 rule，以同时支持用户级通用规则与项目级特殊规则 [资料来源：[issue #35](https://github.com/alibaba/open-code-review/issues/35)]。

了解这些边界有助于在引入 `ocr` 时合理设置评审范围与规则集。

## See Also

- 安装与快速开始（QuickStart）
- `ocr review` 命令与 Flag 参考
- 配置与 LLM 协议选择
- CI 集成（GitLab CI 示例）
- 基准与排行（AACR-Bench）

---

<a id='page-2'></a>

## CLI 命令、评审模式与 Diff 流水线

### 相关页面

相关主题：[概览与系统架构](#page-1), [配置体系与四层评审规则解析](#page-3), [LLM 集成、WebUI Viewer 与 CI/CD 生态](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/alibaba/open-code-review/blob/main/README.md)
- [pages/src/i18n/zh.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts)
- [pages/src/i18n/en.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/en.ts)
- [pages/src/pages/DocsPage.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/pages/DocsPage.tsx)
- [pages/src/components/QuickStartSection.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/components/QuickStartSection.tsx)
- [pages/src/components/BenchmarkSection.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/components/BenchmarkSection.tsx)
- [examples/gitlab_ci/README.md](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/README.md)
</details>

# CLI 命令、评审模式与 Diff 流水线

Open Code Review（`ocr`）的核心使用面是一个全局 CLI 工具，它把"读 Git diff → 过滤文件 → 路由规则 → 调度 Agent 评审"这一整套流水线封装成少量子命令。本文围绕 CLI 命令总览、评审模式、Diff 流水线与高级配置四个维度展开，帮助读者建立端到端的认知。

## CLI 命令总览

CLI 在全局安装 `@alibaba-group/open-code-review` 后暴露 `ocr` 命令，三大主要子命令分别是 `ocr review`、`ocr config` 与 `ocr viewer`：

- `ocr review` 是核心命令，负责发起一次 AI 代码评审 资料来源：[pages/src/i18n/zh.ts](pages/src/i18n/zh.ts)
- `ocr config` 管理存储于 `~/.opencodereview/config.json` 的 CLI 配置，包括 LLM 地址、密钥、模型、是否启用 Anthropic SDK、厂商额外请求体、输出语言与遥测开关等 资料来源：[pages/src/i18n/zh.ts](pages/src/i18n/zh.ts)
- `ocr viewer` 启动本地 HTTP 服务，提供网页形式的评审结果浏览界面 资料来源：[pages/src/i18n/zh.ts](pages/src/i18n/zh.ts)

如果用户已是 Claude Code 用户，并已设置 `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_MODEL` 环境变量，CLI 会自动识别这些变量，无需额外配置 资料来源：[pages/src/components/QuickStartSection.tsx](pages/src/components/QuickStartSection.tsx)。

## 评审模式

`ocr review` 通过不同 flag 组合支持三种评审模式，对应不同的 diff 来源 资料来源：[pages/src/pages/DocsPage.tsx](pages/src/pages/DocsPage.tsx)：

| 模式 | 触发方式 | 评审范围 |
| --- | --- | --- |
| 工作区模式（默认） | `ocr review` | 当前工作区的暂存 + 未暂存 + 未跟踪变更 |
| 分支对比模式 | `ocr review --from <ref> --to <ref>` | 基于 merge-base 的两个引用之间差异 |
| 单提交模式 | `ocr review --commit <hash>` 或 `ocr review -c <hash>` | 指定提交与其父提交之间的差异 |

`--from/--to` 与 `--commit` 不可同时使用，且指定 `--from` 时必须同时指定 `--to` 资料来源：[pages/src/i18n/zh.ts](pages/src/i18n/zh.ts)。

```mermaid
flowchart LR
  A[ocr review] --> B{Flag 组合}
  B -- 无 flag --> C[工作区模式<br/>staged+unstaged+untracked]
  B -- from + to --> D[分支对比模式<br/>merge-base diff]
  B -- commit --> E[单提交模式<br/>commit^ → commit]
  C --> F[Diff 流水线]
  D --> F
  E --> F
  F --> G[并发评审 + 规则路由]
  G --> H[结构化评审结果]
```

## Diff 流水线与文件过滤

CLI 拿到 diff 后会进入"确定性工程"主导的处理阶段：先解析变更文件集合，再依据内置/自定义规则进行过滤与路由，最后才把子任务派发给 LLM Agent 资料来源：[README.md](README.md)。这种"工程层做硬约束、Agent 层做语义判断"的设计，是工具在 AACR-Bench 等基准上稳定领先通用 Agent 方案的关键 资料来源：[pages/src/components/BenchmarkSection.tsx](pages/src/components/BenchmarkSection.tsx)。

文件过滤环节使用 allowlist 机制，社区曾反馈 HarmonyOS 工程的 `.ets` 文件因未列入 supported_file_types.json 而被整体跳过（Issue #47），这说明 diff 流水线对可评审文件类型有明确边界。

对于需要全仓库扫描而非仅 diff 变更的场景，社区在 Issue #40 中提出"全量评审"诉求，并希望自动获取初始与最新版本号；当前 CLI 仍以 diff-based 模式为主，用户可通过 `--from` + `--to` 显式指定范围 资料来源：[pages/src/i18n/zh.ts](pages/src/i18n/zh.ts)。

## 高级配置与 Flag 参考

`ocr review` 的关键 flag 及其默认值如下 资料来源：[pages/src/i18n/zh.ts](pages/src/i18n/zh.ts)：

| Flag | 含义 | 默认值 |
| --- | --- | --- |
| `--commit` / `-c` | 指定提交哈希 | — |
| `--from` | diff 起点引用 | — |
| `--to` | diff 终点引用 | — |
| `--format` | text 或 json | text |
| `--root` | Git 仓库根目录 | 当前目录 |
| `--rule` | 评审规则 JSON 文件 | 内置 |
| `--concurrency` | 最大并发评审文件数 | 内置 |
| `--timeout` | 单任务超时（分钟） | 内置 |
| `--audience` | human / agent | human |
| `--tool-rounds` | 每文件最大工具调用轮次 | 内置（仅在更大时生效） |
| `--background` | 需求背景文本 | — |

其中 `--background` 适合在 CI 流水线中传入 Merge Request 标题等语义化上下文，使 Agent 评审更贴合本次改动目的 资料来源：[examples/gitlab_ci/README.md](examples/gitlab_ci/README.md)。GitLab CI 示例中还演示了通过 `--rule` 注入自定义规则、以及使用 `--concurrency` 调参控制并发 LLM 请求数量的用法 资料来源：[examples/gitlab_ci/README.md](examples/gitlab_ci/README.md)。

关于规则的优先级与合并，社区在 Issue #35 中提出"高优先级 rule 应合并低优先级 rule"的诉求，目前文件级匹配仍采用首个命中规则作为 `user_message` 资料来源：[pages/src/i18n/zh.ts](pages/src/i18n/zh.ts)。如果希望同时生效通用与项目级规则，建议把内容合并到一个 `--rule` 文件中传入。

## See Also

- [配置与 LLM 接入](./configuration.md)
- [评审规则与 Allowlist](./rules-and-allowlist.md)
- [Agent 与 Memory 压缩机制](./agent-architecture.md)

---

<a id='page-3'></a>

## 配置体系与四层评审规则解析

### 相关页面

相关主题：[CLI 命令、评审模式与 Diff 流水线](#page-2), [LLM 集成、WebUI Viewer 与 CI/CD 生态](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cmd/opencodereview/config_cmd.go](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/config_cmd.go)
- [internal/config/rules/system_rules.json](https://github.com/alibaba/open-code-review/blob/main/internal/config/rules/system_rules.json)
- [internal/config/rules/system_rules.go](https://github.com/alibaba/open-code-review/blob/main/internal/config/rules/system_rules.go)
- [internal/config/template/task_template.json](https://github.com/alibaba/open-code-review/blob/main/internal/config/template/task_template.json)
- [internal/config/template/template.go](https://github.com/alibaba/open-code-review/blob/main/internal/config/template/template.go)
- [internal/telemetry/config.go](https://github.com/alibaba/open-code-review/blob/main/internal/telemetry/config.go)
- [pages/src/i18n/zh.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts)
- [pages/src/i18n/en.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/en.ts)
- [pages/src/pages/DocsPage.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/pages/DocsPage.tsx)
- [README.md](https://github.com/alibaba/open-code-review/blob/main/README.md)
- [examples/gitlab_ci/README.md](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/README.md)
</details>

# 配置体系与四层评审规则解析

## 概述

Open Code Review（以下简称 OCR）的配置体系承担两重职责：一是把 LLM 接入信息（API 地址、密钥、模型、协议族等）以结构化方式持久化在用户本地；二是组织评审时使用的规则集，使得不同来源、不同优先级的规则可以匹配到具体文件。CLI 通过 `ocr config` 子命令读写配置，配置落盘在 `~/.opencodereview/config.json` 中 [资料来源：[README.md](https://github.com/alibaba/open-code-review/blob/main/README.md)]。在评审阶段，规则由内置模板、系统规则、用户/项目级规则与命令行 `--rule` 自定义规则四层组成，由路由模块按优先级匹配后下发到 Agent [资料来源：[internal/config/rules/system_rules.go](https://github.com/alibaba/open-code-review/blob/main/internal/config/rules/system_rules.go)]。

## 全局配置：配置键与默认值

`ocr config` 命令族负责设置、查询和验证全局配置。官方文档列出了 7 个被识别的 key，覆盖 LLM 接入与产品行为 [资料来源：[pages/src/i18n/zh.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts)] [资料来源：[pages/src/pages/DocsPage.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/pages/DocsPage.tsx)]：

| 配置 Key | 用途 | 备注 |
|---|---|---|
| `url` | LLM 服务的 API 入口地址 | 兼容 Anthropic 与 OpenAI 协议 |
| `token` | API 鉴权密钥 | 也可读取 `ANTHROPIC_AUTH_TOKEN` 等环境变量 |
| `model` | 调用的具体模型名 | Claude Code 用户自动继承 `ANTHROPIC_MODEL` |
| `anthropic` | 是否强制走 Anthropic Messages SDK | 布尔值 |
| `extraBody` | 厂商特定的请求体字段 | 以 JSON 字符串形式传入 |
| `language` | 评审输出语言 | 默认英文 |
| `telemetry` | 数据上报开关 | 与 telemetry 模块联动 |

Claude Code 生态的用户被允许"零配置"接入：当环境变量 `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_MODEL` 已存在时，OCR 自动拾取，CLI 配置仅起到覆盖和补全作用 [资料来源：[pages/src/components/QuickStartSection.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/components/QuickStartSection.tsx)]。

## 四层评审规则架构

OCR 的规则栈按"覆盖范围 + 优先级"划分为四层，下层规则在匹配到具体文件后向上合并，再交给 Agent 渲染 user message [资料来源：[internal/config/rules/system_rules.go](https://github.com/alibaba/open-code-review/blob/main/internal/config/rules/system_rules.go)] [资料来源：[internal/config/template/template.go](https://github.com/alibaba/open-code-review/blob/main/internal/config/template/template.go)]：

```mermaid
flowchart TB
  L1["L1 任务模板<br/>internal/config/template/task_template.json"] --> L2
  L2["L2 内置系统规则<br/>internal/config/rules/system_rules.json"] --> L3
  L3["L3 用户/项目级规则<br/>ocr config 写入 ~/.opencodereview/config.json"] --> L4
  L4["L4 命令行自定义规则<br/>--rule ./my-rules.json"] --> Merge["规则合并 → Agent prompt"]
```

- **L1 任务模板**：定义 Agent 的工具集、记忆压缩策略与输出骨架，是所有评审的公共基线 [资料来源：[internal/config/template/task_template.json](https://github.com/alibaba/open-code-review/blob/main/internal/config/template/task_template.json)]。
- **L2 内置系统规则**：由 `system_rules.json` 描述，覆盖 NPE、线程安全、XSS、SQL 注入等十余种风险类型，针对 Java、TypeScript、Go、Python、Kotlin、C++、C 等语言预置规则 [资料来源：[internal/config/rules/system_rules.json](https://github.com/alibaba/open-code-review/blob/main/internal/config/rules/system_rules.json)]。
- **L3 用户/项目级规则**：通过 `ocr config` 写入全局配置，适用于个人偏好或一组固定仓库。
- **L4 命令行自定义规则**：以 `--rule ./my-rules.json` 形式在单次评审中注入，最高优先级，常用于 CI 流水线中的项目级覆盖 [资料来源：[examples/gitlab_ci/README.md](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/README.md)]。

社区 Issue #35 提出"高优先级规则应合并低优先级规则"，目前的实现是"首个匹配生效"，这正是后续路线图中关于规则合并演进的目标 [资料来源：[pages/src/i18n/en.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/en.ts)]。

## 评审 Flag 与验证流程

`ocr review` 核心命令支持三种模式：工作区（默认）、分支对比（`--from/--to`）、单提交（`--commit/-c`），且模式之间互斥 [资料来源：[pages/src/pages/DocsPage.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/pages/DocsPage.tsx)]。常见的扩展 flag 包括 `--rule`（规则文件）、`--concurrency`（并发 worker 数，默认 8）、`--timeout`（单任务超时分钟）、`--background`（需求背景）、`--format text|json`、`--audience human|agent`、`--max-tool-rounds`、`--repo`（Git 根目录）[资料来源：[pages/src/i18n/zh.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts)] [资料来源：[README.md](https://github.com/alibaba/open-code-review/blob/main/README.md)]。

完成配置后应运行 `ocr config verify` 触发一次连接测试，确认 LLM 端点可访问、鉴权有效，再进入实际评审 [资料来源：[pages/src/pages/DocsPage.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/pages/DocsPage.tsx)]。`internal/telemetry/config.go` 负责遥测开关与上报策略，与 `telemetry` 配置键联动 [资料来源：[internal/telemetry/config.go](https://github.com/alibaba/open-code-review/blob/main/internal/telemetry/config.go)]。

## 常见失败模式与社区反馈

- **规则匹配冲突**：当 L3 用户级与 L4 命令行规则同时命中时，当前行为是首个匹配胜出，Issue #35 期望支持"合并叠加"以保留通用规则叠加项目特殊规则 [资料来源：[pages/src/i18n/en.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/en.ts)]。
- **文件类型白名单**：HarmonyOS 的 `.ets` 文件目前不在 `supported_file_types.json` 中，会出现 `No supported files changed` 提示（Issue #47）。
- **评审范围**：当前只针对 diff 变更部分，全量全库评审与对非 Git 项目的支持仍在讨论中（Issue #40）。
- **LLM 协议**：默认覆盖 Anthropic 与 OpenAI 兼容协议，Gemini API 仍需适配（Issue #49）。

## See Also

- [README.md](https://github.com/alibaba/open-code-review/blob/main/README.md)
- [examples/gitlab_ci/README.md](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/README.md)
- [pages/src/pages/DocsPage.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/pages/DocsPage.tsx)

---

<a id='page-4'></a>

## LLM 集成、WebUI Viewer 与 CI/CD 生态

### 相关页面

相关主题：[概览与系统架构](#page-1), [CLI 命令、评审模式与 Diff 流水线](#page-2), [配置体系与四层评审规则解析](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cmd/opencodereview/llm_cmd.go](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/llm_cmd.go)
- [cmd/opencodereview/viewer.go](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/viewer.go)
- [internal/llm/client.go](https://github.com/alibaba/open-code-review/blob/main/internal/llm/client.go)
- [internal/llm/resolver.go](https://github.com/alibaba/open-code-review/blob/main/internal/llm/resolver.go)
- [internal/llm/embedded_loader.go](https://github.com/alibaba/open-code-review/blob/main/internal/llm/embedded_loader.go)
- [internal/llm/usage_resolver.go](https://github.com/alibaba/open-code-review/blob/main/internal/llm/usage_resolver.go)
- [internal/viewer/server.go](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/server.go)
- [internal/config/allowlist/supported_file_types.json](https://github.com/alibaba/open-code-review/blob/main/internal/config/allowlist/supported_file_types.json)
- [examples/gitlab_ci/README.md](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/README.md)
- [README.md](https://github.com/alibaba/open-code-review/blob/main/README.md)
- [pages/src/i18n/zh.ts](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts)
- [pages/src/pages/DocsPage.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/pages/DocsPage.tsx)
</details>

# LLM 集成、WebUI Viewer 与 CI/CD 生态

本页聚焦于 Open Code Review（以下简称 OCR）面向"运行时"与"工程落地"的三大支撑能力：**LLM 协议接入**、**本地 WebUI Viewer** 以及 **CI/CD 集成示例**。这三者共同决定了 OCR 能否在企业内不同形态的工作流（本地开发、CLI 批处理、流水线自动评审）中以一致的方式被调用与审计。

## LLM 协议接入与配置

OCR 通过 `ocr config set` 命令将 LLM 连接信息持久化到 `~/.opencodereview/config.json`，支持的配置键与说明如下：

| 配置 Key | 含义 | 来源 |
|----------|------|------|
| `llm.url` | LLM 服务地址（兼容 Anthropic 或 OpenAI 协议） | [pages/src/i18n/zh.ts:docs.configKeyUrl](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts) |
| `llm.auth_token` | API 密钥 | [pages/src/i18n/zh.ts:docs.configKeyToken](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts) |
| `llm.model` | 模型名称（如 `claude-opus-4-6`） | [pages/src/i18n/zh.ts:docs.configKeyModel](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts) |
| `llm.use_anthropic` | 是否使用 Anthropic SDK | [pages/src/i18n/zh.ts:docs.configKeyAnthropic](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts) |
| `llm.extra_body` | 厂商特定的请求体字段（JSON 字符串） | [pages/src/i18n/zh.ts:docs.configKeyExtraBody](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts) |
| `language` | 评审输出语言 | [pages/src/i18n/zh.ts:docs.configKeyLanguage](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts) |
| `telemetry` | 数据上报开关 | [pages/src/i18n/zh.ts:docs.configKeyTelemetry](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts) |

内部模块 `internal/llm/resolver.go` 负责从环境变量、配置文件与默认约定中聚合最终生效的 LLM 参数（[internal/llm/resolver.go](https://github.com/alibaba/open-code-review/blob/main/internal/llm/resolver.go)）；`internal/llm/client.go` 则依据 `use_anthropic` 标志选择 Anthropic Messages API 或 OpenAI Chat Completions API 实现，从而同时兼容自托管 vLLM/Ollama 等 OpenAI 兼容服务与官方 Claude 模型（[internal/llm/client.go](https://github.com/alibaba/open-code-review/blob/main/internal/llm/client.go)）。`internal/llm/embedded_loader.go` 在未显式提供 system prompt 时加载内置的嵌入式提示词（[internal/llm/embedded_loader.go](https://github.com/alibaba/open-code-review/blob/main/internal/llm/embedded_loader.go)），保证零外部依赖场景也能立即运行。

Claude Code 用户无需任何额外配置：OCR 会自动识别 `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL` 三个环境变量（[pages/src/pages/DocsPage.tsx](https://github.com/alibaba/open-code-review/blob/main/pages/src/pages/DocsPage.tsx)）。配置完成后可执行 `ocr llm test` 验证连通性，命令实现在 [cmd/opencodereview/llm_cmd.go](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/llm_cmd.go) 中。

## 本地 WebUI Viewer

`ocr viewer`（别名 `ocr v`）用于启动本地 HTTP 服务，将 `ocr review` 的 JSON 输出渲染为可视化评审界面，默认监听 `localhost:5483`（[README.md](https://github.com/alibaba/open-code-review/blob/main/README.md)）。`internal/viewer/server.go` 负责 HTTP 服务的路由与静态资源分发（[internal/viewer/server.go](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/server.go)），命令行入口在 [cmd/opencodereview/viewer.go](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/viewer.go)。

典型流程为：先以 `--format json` 跑一次 `ocr review` 并落盘，再调用 `ocr viewer` 在浏览器中逐文件查看 LLM 标注的位置、规则匹配、置信度等元信息。这一组合特别适合需要在本地调试规则、复核 AI 评审结果、且不想把结果直接推回代码托管平台的场景（[pages/src/i18n/zh.ts:docs.viewerNote](https://github.com/alibaba/open-code-review/blob/main/pages/src/i18n/zh.ts)）。

## CI/CD 生态与流水线集成

仓库自带 GitLab CI 集成示例，目录为 [`examples/gitlab_ci/`](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/)。该示例展示了在 Merge Request 流水线中以 npm 全局安装 OCR，并基于 `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` / `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` 调用 `ocr review --from ... --to ...` 的标准模式（[examples/gitlab_ci/README.md](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/README.md)）。

下面以一个简化的数据流示意 Review Agent 在 CI 环境中的关键协作点：

```mermaid
flowchart LR
  A[GitLab MR Push] --> B[Pipeline Job]
  B --> C[npm install -g open-code-review]
  C --> D[ocr review --from --to]
  D --> E[internal/llm/client.go]
  E --> F[Anthropic / OpenAI 兼容服务]
  F --> E
  E --> G[JSON 评审结果]
  G --> H[MR 评论 / 制品归档]
```

可定制的常见旋钮包括：使用 `--rule ./my-rules.json` 注入项目级规则，使用 `--concurrency N` 调整并发评审数（默认为 8，[README.md](https://github.com/alibaba/open-code-review/blob/main/README.md)），使用 `--background "$CI_MERGE_REQUEST_TITLE"` 将 MR 标题作为需求背景传给 LLM（[examples/gitlab_ci/README.md](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/README.md)）。同时可通过固定版本号（如 `@1.0.0`）保证评审结果可复现。

## 社区反馈与已知限制

社区中与本页主题直接相关的活跃诉求集中在以下几点：

- **Gemini API 支持**：[Issue #49](https://github.com/alibaba/open-code-review/issues/49) 指出当前 LLM 客户端仅覆盖 Anthropic 与 OpenAI 兼容协议，尚未提供 Gemini 适配，影响了在本地或 CI 中使用 Google 模型的场景。该缺口需要扩展 `internal/llm/client.go` 与 `resolver.go` 中的协议分支。
- **文件类型白名单**：[Issue #47](https://github.com/alibaba/open-code-review/issues/47) 反馈 HarmonyOS `.ets` 文件被 [internal/config/allowlist/supported_file_types.json](https://github.com/alibaba/open-code-review/blob/main/internal/config/allowlist/supported_file_types.json) 漏掉，导致出现 "No supported files changed"。在自定义 CI 流水线中同样会遇到此问题。
- **全量扫描与非 Git 仓库**：[Issue #40](https://github.com/alibaba/open-code-review/issues/40) 希望提供"全库全量评审"模式而非必须依赖 `--from/--to` diff。
- **规则合并**：[Issue #35](https://github.com/alibaba/open-code-review/issues/35) 期望高优先级规则能与低优先级规则叠加，而不是只取首个匹配项（[internal/llm/usage_resolver.go](https://github.com/alibaba/open-code-review/blob/main/internal/llm/usage_resolver.go)）。

## See Also

- 入门与安装：[README.md](https://github.com/alibaba/open-code-review/blob/main/README.md)
- 规则系统与 `ocr rules check`：[internal/config/allowlist/supported_file_types.json](https://github.com/alibaba/open-code-review/blob/main/internal/config/allowlist/supported_file_types.json)
- GitLab CI 集成示例：[examples/gitlab_ci/README.md](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：alibaba/open-code-review

摘要：发现 14 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：window版本安装闪退。

## 1. 安装坑 · 来源证据：window版本安装闪退

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：window版本安装闪退
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/alibaba/open-code-review/issues/32 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 2. 安全/权限坑 · 来源证据：feat(agent): add structured category and severity fields to review output

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(agent): add structured category and severity fields to review output
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/alibaba/open-code-review/issues/16 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：Support for Gemini API

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support for Gemini API
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/alibaba/open-code-review/issues/49 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安装坑 · 来源证据：Windows系统无法写入session对话信息，无法看到结果

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows系统无法写入session对话信息，无法看到结果
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/alibaba/open-code-review/issues/34 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 5. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | hn_item:48406358 | https://news.ycombinator.com/item?id=48406358 | host_targets=claude, claude_code

## 6. 能力坑 · 来源证据：关于benchmark

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：关于benchmark
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/alibaba/open-code-review/issues/24 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | hn_item:48406358 | https://news.ycombinator.com/item?id=48406358 | README/documentation is current enough for a first validation pass.

## 8. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | hn_item:48406358 | https://news.ycombinator.com/item?id=48406358 | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | hn_item:48406358 | https://news.ycombinator.com/item?id=48406358 | no_demo; severity=medium

## 10. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | hn_item:48406358 | https://news.ycombinator.com/item?id=48406358 | no_demo; severity=medium

## 11. 安全/权限坑 · 来源证据：Support for AWS Bedrock

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support for AWS Bedrock
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/alibaba/open-code-review/issues/50 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 12. 安全/权限坑 · 来源证据：mac 端审查 Python 项目失败

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：mac 端审查 Python 项目失败
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/alibaba/open-code-review/issues/23 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 13. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | hn_item:48406358 | https://news.ycombinator.com/item?id=48406358 | issue_or_pr_quality=unknown

## 14. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | hn_item:48406358 | https://news.ycombinator.com/item?id=48406358 | release_recency=unknown

<!-- canonical_name: alibaba/open-code-review; human_manual_source: deepwiki_human_wiki -->