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/ 提供宣传与文档站。整体可划分为四层：

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 端到端数据流

关键模块职责：

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]。
• 支持文件类型白名单：supported_file_types.json 未包含 HarmonyOS 的 .ets 后缀，导致 HarmonyOS 项目出现 "No supported files changed" 提示，#47 提议补齐 资料来源：[issue #47]。
• 全量扫描与非 Git 项目：#40 希望在不手动指定 --from/--to 的情况下也能对仓库做全量评审，并支持非 Git 项目 资料来源：[issue #40]。
• 规则合并语义：当前一个文件只会使用"匹配到的第一个 rule"作为 user_message，#35 期望高优先级 rule 能合并低优先级 rule，以同时支持用户级通用规则与项目级特殊规则 资料来源：[issue #35]。

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

See Also

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

CLI 命令总览

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

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

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

评审模式

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

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

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。这种"工程层做硬约束、Agent 层做语义判断"的设计，是工具在 AACR-Bench 等基准上稳定领先通用 Agent 方案的关键 资料来源：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。

高级配置与 Flag 参考

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

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

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

See Also

• 配置与 LLM 接入
• 评审规则与 Allowlist
• Agent 与 Memory 压缩机制

概述

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

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

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

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

四层评审规则架构

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

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]。
• L2 内置系统规则：由 system_rules.json 描述，覆盖 NPE、线程安全、XSS、SQL 注入等十余种风险类型，针对 Java、TypeScript、Go、Python、Kotlin、C++、C 等语言预置规则 资料来源：[internal/config/rules/system_rules.json]。
• L3 用户/项目级规则：通过 ocr config 写入全局配置，适用于个人偏好或一组固定仓库。
• L4 命令行自定义规则：以 --rule ./my-rules.json 形式在单次评审中注入，最高优先级，常用于 CI 流水线中的项目级覆盖 资料来源：[examples/gitlab_ci/README.md]。

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

评审 Flag 与验证流程

ocr review 核心命令支持三种模式：工作区（默认）、分支对比（--from/--to）、单提交（--commit/-c），且模式之间互斥 资料来源：[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] 资料来源：[README.md]。

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

常见失败模式与社区反馈

• 规则匹配冲突：当 L3 用户级与 L4 命令行规则同时命中时，当前行为是首个匹配胜出，Issue #35 期望支持"合并叠加"以保留通用规则叠加项目特殊规则 资料来源：[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
• examples/gitlab_ci/README.md
• pages/src/pages/DocsPage.tsx

LLM 协议接入与配置

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

内部模块 internal/llm/resolver.go 负责从环境变量、配置文件与默认约定中聚合最终生效的 LLM 参数（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）。internal/llm/embedded_loader.go 在未显式提供 system prompt 时加载内置的嵌入式提示词（internal/llm/embedded_loader.go），保证零外部依赖场景也能立即运行。

Claude Code 用户无需任何额外配置：OCR 会自动识别 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL 三个环境变量（pages/src/pages/DocsPage.tsx）。配置完成后可执行 ocr llm test 验证连通性，命令实现在 cmd/opencodereview/llm_cmd.go 中。

本地 WebUI Viewer

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

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

CI/CD 生态与流水线集成

仓库自带 GitLab CI 集成示例，目录为 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）。

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

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），使用 --background "$CI_MERGE_REQUEST_TITLE" 将 MR 标题作为需求背景传给 LLM（examples/gitlab_ci/README.md）。同时可通过固定版本号（如 @1.0.0）保证评审结果可复现。

社区反馈与已知限制

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

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

See Also

• 入门与安装：README.md
• 规则系统与 ocr rules check：internal/config/allowlist/supported_file_types.json
• GitLab CI 集成示例：examples/gitlab_ci/README.md

Pitfall Log / 踩坑日志

项目：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