The open source AI code review agent.
English | 简体中文
--- ## Open Code Review 是什么？ Open Code Review 是一款 AI 驱动的代码审查 CLI 工具。它的前身是阿里集团内部官方 AI 代码审查助手，过去两年在内部服务了数万开发者，识别了数百万个代码缺陷。经过大规模充分验证后，我们将其孵化为开源项目，对社区开放。只需配置一个模型端点即可使用。 它读取 Git diff，通过具备工具调用能力的 Agent 将变更文件发送至可配置的 LLM，生成具有行级精度的结构化审查意见。Agent 可以读取完整文件内容、搜索代码库、检查其他变更文件以获取上下文，从而进行深度审查——而非仅停留在表面的 diff 反馈。  ## 为什么选择 Open Code Review？ ### 通用 Agent 的局限 如果你深度用过 Claude Code 等通用 Agent + Skills 方案做代码审查，可能对以下问题深有同感： - **覆盖不全** —— 变更较大时，Agent 倾向于"偷懒"，选择性地审查部分文件，导致遗漏。 - **位置漂移** —— 报告的问题与实际代码位置常常对不上，出现行号或文件偏移。 - **效果不稳定** —— 基于自然语言驱动的 Skills 难以调试，审查质量因提示词的细微差异而大幅波动。 这些问题的根源在于：纯语言驱动的架构缺乏对审查流程的强约束。 ### 核心设计：确定性工程 × Agent 混合驱动 Open Code Review 的核心设计理念是将确定性工程与 Agent 结合，各司其职。 **确定性工程——负责强约束** 对代码审查场景中"不能出错"的环节，由工程逻辑而非语言模型来保证： - **精准的文件筛选** —— 明确哪些文件需要审查、哪些应当过滤，确保真正重要的改动一个不漏。 - **智能的文件打包** —— 将关联文件归并为同一审查单元（例如 `message_en.properties` 与 `message_zh.properties` 会被打包在一起）。每个包会作为 sub-agent 进行任务，它们之间的上下文是隔离的——这一分治策略在超大变更场景下表现更为稳定，同时天然支持并发审查。 - **精细化规则匹配** —— 针对不同文件的特征，匹配对应的审查规则，确保模型的注意力足够聚焦，从源头规避信息噪声的干扰。相比纯语言驱动的规则引导，基于模板引擎的规则匹配行为更稳定、结果更可预期。 - **外挂的定位与反思组件** —— 独立的评论定位模块与评论反思模块，系统性地提升 AI 反馈的位置准确性与内容准确性。 **Agent——负责动态决策** 将 Agent 的优势集中发挥在它真正擅长的地方——动态决策、动态召回上下文： - **场景化提示词调优** —— 针对代码审查场景深度优化提示词模板，在提升效果的同时有效降低 Token 消耗。 - **场景化工具集沉淀** —— 基于对大量线上数据中工具调用轨迹的深入分析，包括不同工具的调用频率分布、单一工具的重复调用率、新增工具对整体调用链路的影响等多维度分析，从而对通用 Agent 工具集进行取舍与拆分，最终沉淀出一套在代码审查场景下效果更稳定、行为更可预期的专属工具集。 ## 如何使用 ### CLI #### 安装 **通过 NPM 安装（推荐）** ```bash npm install -g @alibaba-group/open-code-review ``` 安装后，`ocr` 命令即可全局使用。 **从 GitHub Release 下载** 从 [GitHub Releases](https://github.com/alibaba/open-code-review/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 # macOS (Intel) curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64 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 # Linux (ARM64) curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64 chmod +x ocr && sudo mv ocr /usr/local/bin/ocr # Windows (x86_64) — 将 ocr.exe 移动到 PATH 目录中 curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe # Windows (ARM64) — 将 ocr.exe 移动到 PATH 目录中 curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe ``` **从源码构建** ```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 ``` #### 快速开始 **1. 配置 LLM** **在审查代码之前，必须先配置 LLM。** ```bash # 方式 A：交互式配置 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：环境变量（优先级最高） 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` 中的相关导出。 **2. 测试连通性** ```bash ocr llm test ``` **3. 开始审查** ```bash cd your-project # 工作区模式 —— 审查所有暂存、未暂存和未跟踪的变更 ocr review # 分支范围 —— 比较两个引用 ocr review --from main --to feature-branch # 单个提交 ocr review --commit abc123 ``` ### 集成到编程 Agent OCR 可以无缝集成到 AI 编程 Agent 中，作为斜杠命令使用，在 Agent 工作流中直接进行代码审查。 #### 方式一：作为 Skill 安装 使用 `npx` 将 OCR skill 安装到项目中： ```bash npx skills add alibaba/open-code-review --skill open-code-review ``` 此命令从 [skills 注册表](skills/open-code-review/SKILL.md)安装 `open-code-review` skill，教会你的编程 Agent 如何调用 `ocr` 进行代码审查、按优先级分类问题，并可选择性地应用修复。 #### 方式二：作为 Claude Code Plugin 安装 对于 [Claude Code](https://docs.anthropic.com/en/docs/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 并自动过滤和修复问题。 #### 方式三：直接复制命令文件 如果不想使用任何包管理器，可以直接复制命令文件，在 Claude Code 中使用 `/open-code-review` 斜杠命令。 **项目级**（通过 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 ``` > **前置条件**：所有集成方式都需要安装 `ocr` CLI 并配置 LLM。参见上方[安装](#安装)和[配置 LLM](#1-配置-llm)。 ### CI/CD 集成 OCR 可以集成到 CI/CD 流水线中，在 Merge Request / Pull Request 时自动进行代码审查。 CI 集成的核心命令： ```bash ocr review \ --from "origin/main" \ --to "origin/feature-branch" \ --format json \ --audience agent ``` `--format json` 和 `--audience agent` 参数输出适合 CI 脚本解析的机器可读结果。 集成示例请参见 [`examples/`](./examples/) 目录： - [`github_actions/`](./examples/github_actions/) — GitHub Actions 集成示例 - [`gitlab_ci/`](./examples/gitlab_ci/) — GitLab CI 集成示例 ## 命令 | 命令 | 别名 | 描述 | |------|------|------| | `ocr review` | `ocr r` | 开始代码审查 | | `ocr rules check