第一部分 概述

Open Code Review 是阿里巴巴开源的 AI 代码审查 CLI 工具。它起源于阿里巴巴集团内部官方 AI 代码审查助手，过去两年已服务数万名开发者，识别了数百万代码缺陷。经过大规模验证后，阿里巴巴将其孵化为开源项目供社区使用。工具读取 Git 差异，通过具备工具调用能力的 Agent 将变更文件发送给可配置的大语言模型，生成结构化的审查评论，精确定位到具体代码行。Agent 能够读取完整文件内容、搜索代码库、检查其他变更文件获取上下文，从而产出深度审查结果而非仅停留在表面的差异反馈。只需配置一个模型端点即可开始使用。

第二部分 为什么选择 Open Code Review

通用 Agent 的痛点

使用 Claude Code 等通用 Agent 配合 Skills 进行代码审查时，开发者常遇到以下问题：

覆盖不完整 — 处理较大变更集时，Agent 往往"偷懒"，选择性审查部分文件而遗漏其他文件。

位置漂移 — 报告的问题经常与实际代码位置不匹配，行号或文件引用偏离目标。

质量不稳定 — 自然语言驱动的 Skills 难以调试，审查质量随提示词微小变化而大幅波动。

根本原因在于纯语言驱动的架构缺乏对审查过程的硬性约束。

核心设计理念

Open Code Review 的核心理念是将确定性工程与 Agent 结合，各自负责擅长的部分。

确定性工程提供硬约束

对于绝不能出错的审查步骤，工程逻辑而非语言模型保证正确性：

• 精确文件选择 — 确定哪些文件需要审查、哪些应过滤，确保不遗漏重要变更。
• 智能文件打包 — 将相关文件组成单一审查单元（如 message_en.properties 和 message_zh.properties 打包在一起），每个包作为独立上下文的子 Agent 运行。这种分治策略在超大变更集上保持稳定，天然支持并发审查。
• 细粒度规则匹配 — 将审查规则匹配到每个文件的特征，使模型注意力高度聚焦，从源头消除信息噪声。相比纯语言驱动的规则引导，模板引擎驱动的规则匹配更稳定、可预测。
• 外部定位与反思模块 — 独立的评论定位和评论反思模块系统性提升 AI 反馈的位置准确性和内容准确性。

Agent 负责动态决策

Agent 的优势集中在最需要的地方 — 动态决策和动态上下文获取：

• 场景调优提示词 — 针对代码审查深度优化的提示词模板，提升效果同时降低 Token 消耗。
• 场景调优工具集 — 从大规模生产数据的工具调用轨迹中提炼，包括调用频率分布、单工具重复率、新工具对整体调用链的影响等分析，形成专为代码审查定制的工具集，比通用 Agent 工具包更稳定可预测。

第三部分 安装与配置

安装方式

通过 NPM 安装（推荐）

bash
npm install -g @alibaba-group/open-code-review

安装后 ocr 命令全局可用。

从 GitHub Release 下载

从 GitHub Releases 下载最新二进制文件：

bash
# macOS (Apple Silicon)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

# Linux (x86_64)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

从源码编译

bash
git clone https://github.com/alibaba/open-code-review.git
cd open-code-review
make build
sudo cp dist/opencodereview /usr/local/bin/ocr

配置 LLM

方式 A：交互式配置

bash
ocr config set llm.url https://api.anthropic.com/v1/messages
ocr config set llm.auth_token your-api-key-here
ocr config set llm.model claude-opus-4-6
ocr config set llm.use_anthropic true

方式 B：环境变量（最高优先级）

bash
export OCR_LLM_URL=https://api.anthropic.com/v1/messages
export OCR_LLM_TOKEN=your-api-key-here
export OCR_LLM_MODEL=claude-opus-4-6
export OCR_USE_ANTHROPIC=true

配置存储在 ~/.opencodereview/config.json。工具兼容 Claude Code 环境变量（ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL），并解析 ~/.zshrc 和 ~/.bashrc 中的导出配置。

测试连接

bash
ocr llm test

第四部分 使用方法

CLI 基本用法

bash
cd your-project

# 工作区模式 — 审查所有已暂存、未暂存和未跟踪的变更
ocr review

# 分支范围 — 比较两个引用
ocr review --from main --to feature-branch

# 单个提交
ocr review --commit abc123

常用命令

命令	别名	说明
ocr review	ocr r	启动代码审查
ocr rules check <file>	—	预览某文件路径适用的审查规则
ocr config set <key> <value>	—	设置配置值
ocr llm test	—	测试 LLM 连接
ocr viewer	ocr v	在 localhost:5483 启动 WebUI 会话查看器
ocr version	—	显示版本信息

审查参数

ocr review 支持以下参数：

参数	简写	默认值	说明
--repo	—	当前目录	Git 仓库根目录
--from	—	—	源引用（如 main）
--to	—	—	目标引用（如 feature-branch）
--commit	-c	—	审查单个提交
--preview	-p	false	预览将审查哪些文件（不调用 LLM）
--format	-f	text	输出格式：text 或 json
--concurrency	—	8	最大并发文件审查数
--timeout	—	10	并发任务超时时间（分钟）
--audience	—	human	human 显示进度，agent 仅显示摘要
--rule	—	—	自定义 JSON 审查规则路径

使用示例

bash
# 预览将审查哪些文件（不调用 LLM）
ocr review --preview

# 使用更高并发审查分支差异
ocr review --from main --to my-feature --concurrency 4

# 审查特定提交，输出详细 JSON
ocr review --commit abc123 --format json --audience agent

# 使用自定义审查规则
ocr review --rule /path/to/my-rules.json

# 预览某文件适用的规则
ocr rules check src/main/java/com/example/Foo.java

# 在浏览器中查看审查会话历史
ocr viewer

第五部分 集成方式

集成到 Coding Agents

OCR 可无缝集成到 AI 编码 Agent 作为斜杠命令，在 Agent 工作流中直接进行代码审查。

方式 1：安装为 Skill

bash
npx skills add alibaba/open-code-review --skill open-code-review

这会从 skills registry 安装 open-code-review skill，教会编码 Agent 如何调用 ocr 进行代码审查、按优先级分类问题并可选地应用修复。

方式 2：安装为 Claude Code 插件

在 Claude Code 中执行：

bash
/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review

这会注册 /open-code-review:review 斜杠命令，运行 OCR 并自动过滤和修复问题。

方式 3：直接复制命令文件

项目级（通过 git 与团队共享）：

bash
mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md

用户级（个人全局使用）：

bash
mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/open-code-review.md \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md

CI/CD 集成

OCR 可集成到 CI/CD 流程，自动审查 Merge Request / Pull Request。

核心命令：

bash
ocr review \
  --from "origin/main" \
  --to "origin/feature-branch" \
  --format json \
  --audience agent

--format json 和 --audience agent 参数输出机器可读结果，适合 CI 脚本解析。

项目提供集成示例：

• examples/github_actions/ — GitHub Actions 集成示例
• examples/gitlab_ci/ — GitLab CI 集成示例

第六部分 审查规则体系

OCR 使用四层优先级链解析审查规则。每层采用首次匹配获胜策略：如果文件路径匹配某模式，使用该规则；否则继续下一层。

优先级	来源	路径	说明
1（最高）	--rule 参数	用户指定路径	CLI 显式覆盖
2	项目配置	<repoDir>/.opencodereview/rule.json	项目级规则，可提交到 git
3	全局配置	~/.opencodereview/rule.json	用户级个人偏好
4（最低）	系统默认	内嵌 system_rules.json	内置规则，覆盖常见语言和文件类型

规则文件格式

第 1-3 层使用相同 JSON 格式：

json
{
  "rules": [
    {
      "path": "force-api/**/*.java",
      "rule": "All new methods must validate required parameters for null values"
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "Check SQL for injection risks, parameter errors, and missing closing tags"
    }
  ]
}

• path 支持 ** 递归匹配和 {java,kt} 花括号展开
• 每层内规则按声明顺序评估 — 首次匹配获胜
• 规则文件不存在时静默跳过

第七部分 配置与遥测

配置参考

配置文件：~/.opencodereview/config.json

键	类型	示例
llm.url	string	https://api.openai.com/v1/chat/completions
llm.auth_token	string	sk-xxxxxxx
llm.model	string	claude-opus-4-6
llm.use_anthropic	boolean	true / false
language	string	English / Chinese（默认 Chinese）
telemetry.enabled	boolean	true / false
telemetry.exporter	string	console / otlp
telemetry.otlp_endpoint	string	OTLP 收集器地址
telemetry.content_logging	boolean	在遥测中包含提示词

环境变量优先级高于配置文件：

变量	用途
OCR_LLM_URL	LLM API 端点 URL
OCR_LLM_TOKEN	API 密钥 / 认证令牌
OCR_LLM_MODEL	模型名称
OCR_USE_ANTHROPIC	true = Anthropic，false = OpenAI

遥测功能

OpenTelemetry 集成提供可观测性（spans、metrics），默认禁用。

bash
ocr config set telemetry.enabled true
ocr config set telemetry.exporter otlp
ocr config set telemetry.otlp_endpoint localhost:4317

设置 telemetry.content_logging 可在导出数据中包含 LLM 提示词和响应。

Sources:

• alibaba/open-code-review - GitHub