今日开源[第38期]Open Code Review (OCR)
Open Code Review (OCR) 项目分析报告
分析日期：2026-07-28
一、项目介绍
1.1 项目概述
Open Code Review（OCR）是阿里巴巴集团开源的 AI 驱动代码审查 CLI 工具。其前身是阿里内部官方 AI 代码审查助手，在过去两年里服务了数万名开发者，识别了数百万个代码缺陷。经过大规模验证后，阿里巴巴将其孵化为开源项目对社区开放。OCR 的核心流程是：读取 Git diff → 通过具备工具调用能力的 Agent 将变更文件发送至可配置的 LLM → 生成具有行级精度的结构化审查意见。它不是一个代码审查平台（如 Gerrit/GitLab），而是一个专用 AI 审查管线，可与任何现有审查平台配合使用 $TRAE_REF。
1.2 项目信息
| 项目 | 详情 |
|---|---|
| 项目名称 | Open Code Review (OCR) |
| 项目地址 | https://github.com/alibaba/open-code-review |
| 项目官网/文档 | https://open-codereview.ai/docs |
| npm 包名 | @alibaba-group/open-code-review |
| 作者/组织 | Alibaba（阿里巴巴集团） |
| Stars | 14,500+（截至 2026 年 7 月，多次登上 GitHub Trending） |
| Forks | 796 |
| 当前版本 | 通过 npm 及 GitHub Releases 分发二进制 |
| 开源协议 | Apache License 2.0 |
| 主要语言 | Go（核心 CLI）、TypeScript（VSCode 扩展） |
| 创建时间 | 2026 年 5 月 |
| 提交数 | 394 commits |
| Open Issues | 32 |
1.3 项目示意图
README 和项目文档中提供了以下可视化资源：
- 项目示意图：展示 OCR 从 Git Diff → Agent 处理 → 行级评论输出的完整流程
- Benchmark 对比图：OCR vs 通用 Agent（Claude Code）在 Precision、F1、Recall、Token 消耗等维度的对比
- 配置交互界面截图：TUI 交互式配置 LLM Provider 和 Model 的终端界面
- 多语言 README：支持英文、中文、日文、韩文、俄文 5 种语言
二、项目亮点
2.1 确定性工程 × Agent 混合驱动（核心创新）
这是 OCR 最大的架构创新——将审查流程拆分为两个部分，各司其职 $TRAE_REF：
确定性工程（负责强约束）：
- 精准文件筛选：明确哪些文件需要审查、哪些应当过滤，确保重要改动不遗漏
- 智能文件打包：将关联文件（如
message_en.properties和message_zh.properties）归并为同一审查单元，每个包作为 sub-agent 独立运行，上下文隔离，天然支持并发审查 - 精细化规则匹配：基于模板引擎的规则匹配，针对不同文件特征匹配对应审查规则，从源头规避信息噪声
- 独立定位与反思组件：独立的评论定位模块和评论反思模块，系统性地提升 AI 反馈的位置准确性和内容准确性
Agent（负责动态决策）：
- 场景化提示词调优：针对代码审查场景深度优化 prompt 模板，提升效果同时降低 Token 消耗
- 场景化工具集沉淀：基于大规模线上数据中工具调用轨迹的深入分析，沉淀出专属工具集（而非通用 Agent 的万能工具集）
2.2 Benchmark 数据：高精度 + 低成本
从 50 个热门开源仓库中精选 200 个真实 PR，覆盖 10 种编程语言，由 80+ 位资深工程师交叉标注验证（共 1,505 个标注缺陷）：
| 指标 | OCR vs 通用 Agent（Claude Code） |
|---|---|
| Precision（准确率） | 显著更高 |
| F1 | 显著更高 |
| Recall（召回率） | 略低（有意设计取舍，以精准度换取低噪声） |
| Token 消耗 | 仅约 1/9 |
| 审查速度 | 更快 |
2.3 三种审查模式
| 模式 | 命令 | 说明 |
|---|---|---|
| 工作区模式 | ocr review |
审查所有 staged + unstaged + untracked 变更 |
| 分支区间模式 | ocr review --from main --to feature-branch |
比较两个 ref |
| 单 Commit 模式 | ocr review --commit abc123 |
审查单个提交 |
| 全文件扫描 | ocr scan |
审查整个文件而非 diff，适用于审计不熟悉的代码库 |
2.4 评论处理三工序流水线
code_comment 工具调用 → 行解析（滑动窗口匹配） → 重定位（失败时回退）
→ 审查过滤（REVIEW_FILTER_TASK） → 第二轮行解析 → 渲染输出
通过滑动窗口匹配 + 重定位 + 过滤三道工序，确保了评论位置的高准确性，解决了通用 Agent 常见的"位置漂移"问题。
2.5 记忆压缩机制
三分区策略管理 Token 预算（MAX_TOKENS = 58888）：
- 60% 阈值：启动异步后台压缩
- 80% 阈值：同步压缩，确保下一个请求容纳得下
- 压缩区渲染为 XML 交给 LLM 摘要，摘要包在
<previous_review_summary>标签中
2.6 丰富的集成生态
| 集成方式 | 说明 |
|---|---|
| CLI 工具 | ocr review / ocr scan / ocr config 等命令 |
| GitHub Actions | 现成工作流，PR 时自动审查并将评论回贴到 PR |
| GitLab CI | 现成工作流，MR 时自动审查 |
| VSCode 扩展 | 编辑器内直接触发审查 |
| 编码 Agent 插件 | Claude Code、Codex、Cursor、OpenCode 插件 |
| MCP Server | 通过 MCP 协议集成到 AI 编程助手 |
| Agent Skill | 可移植的 Agent 技能定义 |
| 委托模式 | 让宿主编码 Agent 使用自身的 LLM 执行审查，无需独立配置 API Key |
2.7 与同类工具的差异化优势
| 对比维度 | Open Code Review | 通用 AI Agent（Claude Code 等） | Gerrit/Phabricator | GitHub/GitLab Code Review |
|---|---|---|---|---|
| AI 驱动 | ✅ 专用 LLM Agent + 确定性工程管线 | ✅ 通用 LLM Agent | ❌ 无 AI 能力 | ⚠️ 基础 AI 辅助 |
| 覆盖完整性 | ✅ 确定性文件筛选保证不遗漏 | ❌ 大变更时倾向"偷懒"漏审 | ✅ 人工审查 | ✅ 人工审查 |
| 位置精度 | ✅ 独立定位模块保证行级精度 | ❌ 位置漂移问题频繁 | ✅ 人工标注 | ✅ 人工标注 |
| 质量稳定性 | ✅ 模板引擎驱动，行为可预测 | ❌ 提示词微调导致质量大幅波动 | ⚠️ 依赖审查者水平 | ⚠️ 依赖审查者水平 |
| Token 效率 | ✅ 约 1/9 通用 Agent 消耗 | ❌ 高消耗 | N/A | N/A |
| 并发审查 | ✅ 原生支持（默认 8 并发） | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 |
| CI/CD 集成 | ✅ 开箱即用 | ⚠️ 需自行封装 | ✅ 自身即平台 | ✅ 自身即平台 |
三、项目运行环境
3.1 基础要求
| 依赖 | 版本/说明 |
|---|---|
| Git | >= 2.41（OCR 依赖 Git 进行 diff 生成、代码搜索和仓库操作） |
| Node.js | >= 18（npm 安装方式） |
| Go | >= 1.25.5（源码构建方式） |
| LLM API Key | 需要配置 LLM 端点（使用委托模式时不需要） |
3.2 核心依赖库
| 依赖 | 用途 |
|---|---|
anthropics/anthropic-sdk-go v1.55.1 |
Anthropic Claude API |
openai/openai-go/v3 v3.41.0 |
OpenAI 兼容 API |
modelcontextprotocol/go-sdk v1.6.1 |
MCP 协议支持 |
charmbracelet/bubbletea/v2 |
TUI 交互界面 |
charmbracelet/lipgloss/v2 |
终端样式 |
bmatcuk/doublestar/v4 |
glob 模式匹配 |
pkoukk/tiktoken-go |
Token 计数 |
go.opentelemetry.io/otel |
遥测/可观测性 |
3.3 安装方式
方式一：npm 全局安装（推荐）
npm install -g @alibaba-group/open-code-review
方式二：安装脚本
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | bash
# Windows
powershell -c "irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex"
方式三：GitHub Release 二进制下载
# 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
方式四：源码构建
git clone https://github.com/alibaba/open-code-review.git && cd open-code-review
make build
3.4 支持的 LLM Provider（14 个内置）
| Provider | 协议 | 说明 |
|---|---|---|
| anthropic | anthropic | Claude 系列 |
| openai | openai | GPT 系列 |
| dashscope | openai | 阿里通义千问 |
| deepseek | openai | DeepSeek |
| volcengine | openai | 火山引擎 |
| kimi | openai | Moonshot Kimi |
| z-ai | openai | 智谱 GLM |
| minimax | openai | MiniMax |
| baidu-qianfan | openai | 百度千帆 |
| 及更多 | 腾讯混元、讯飞星火、小米 Mimo 等 |
也支持自定义 provider（含 Ollama 本地模型）。
3.5 配置 LLM
# 交互式配置
ocr config provider # 选择 provider
ocr config model # 选择模型
# 非交互式配置（适合 CI）
ocr config set provider anthropic
ocr config set model claude-opus-4-6
ocr config set providers.anthropic.api_key sk-ant-xxxxxxxxxx
# 测试连通性
ocr llm test
四、项目代码介绍
4.1 代码架构图
open-code-review/
├── .claude-plugin/ # Claude Code 插件配置
├── .claude/commands/ # Claude Code 斜杠命令
├── .github/ # GitHub 工作流配置
├── bin/ # 构建输出
│
├── cmd/opencodereview/ # ⭐ CLI 入口层（Go）
│ ├── main.go # 顶层命令分发
│ ├── flags.go # 参数解析（review/scan/config/llm 等）
│ └── review_cmd.go # review 命令实现
│
├── internal/ # 核心内部包（Go）
│ ├── agent/ # ⭐ Agent 编排引擎
│ │ ├── agent.go # 主 Agent 循环（Plan + Main 两阶段）
│ │ ├── compression.go # 三分区记忆压缩（60%/80% 阈值）
│ │ ├── preview.go # 五重门文件过滤
│ │ └── util.go # Agent 工具函数
│ │
│ ├── config/ # 配置管理
│ │ ├── rules/ # 规则引擎（20+ 文件类型内置规则）
│ │ │ └── system_rules.go # 内置规则解析
│ │ ├── template/ # Prompt 模板系统
│ │ │ └── task_template.json # 5 个 prompt 模板
│ │ ├── allowlist/ # 文件白名单
│ │ └── testconnection/ # LLM 连通性测试
│ │
│ ├── diff/ # Diff 解析与处理
│ │ ├── git.go # Git Diff Provider（Workspace/Commit/Range）
│ │ └── relocation.go # 评论行号重定位
│ │
│ ├── llm/ # LLM 端点解析
│ │ └── resolver.go # 14 个内置 Provider 解析器
│ │
│ ├── tool/ # Agent 工具注册表与实现
│ │ ├── filereader.go # 文件读取工具
│ │ ├── code_search.go # 代码搜索工具
│ │ ├── code_comment.go # 评论生成工具
│ │ └── ...
│ │
│ ├── viewer/ # Web 会话查看器
│ │ ├── server.go # HTTP 服务器
│ │ └── hostguard.go # Host 头白名单安全防护
│ │
│ ├── session/ # 会话持久化
│ │ └── persist.go # JSONL 格式会话存储
│ │
│ ├── pathutil/ # 路径安全验证
│ │ └── path.go # 路径遍历防护
│ │
│ └── stdout/ # 输出控制
│
├── extensions/vscode/ # VSCode 扩展（TypeScript）
├── examples/ # 集成示例
│ ├── github_actions/ # GitHub Actions 工作流
│ └── gitlab_ci/ # GitLab CI 工作流
├── plugins/open-code-review/ # 编码 Agent 插件
├── skills/ # 可移植 Agent Skill
├── npm/ # npm 包发布配置
├── pages/ # 文档站点页面
├── scripts/ # 构建脚本
├── imgs/ # 图片资源
│
├── go.mod / go.sum # Go 模块定义
├── Makefile # 构建脚本
├── package.json # npm 包配置
├── action.yml # GitHub Action 定义
├── install.sh / install.ps1 # 安装脚本
├── ROADMAP.md # 路线图
├── ASSURANCE_CASE.md # 安全保证案例
└── README.md # 多语言 README
4.2 系统架构
┌──────────────────────────────────────────────────────────┐
│ 用户交互层 │
│ CLI (ocr review/scan) │ VSCode 扩展 │ 编码 Agent 插件 │
└──────────────────────┬───────────────────────────────────┘
│
┌──────────────────────┴───────────────────────────────────┐
│ CLI 命令分发层 │
│ main.go → flags.go → review_cmd.go / scan_cmd.go │
└──────────────────────┬───────────────────────────────────┘
│
┌──────────────────────┴───────────────────────────────────┐
│ 确定性工程管线 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │五重门过滤 │ │智能文件打包│ │规则引擎 │ │评论定位 │ │
│ │preview.go│ │ 归并关联 │ │20+文件类型│ │滑动窗口 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────┬───────────────────────────────────┘
│
┌──────────────────────┴───────────────────────────────────┐
│ Agent 编排层 │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 阶段 1: Plan（变更 >= 50 行时触发） │ │
│ │ 阶段 2: Main 循环（最多 30 轮，6 个工具） │ │
│ │ 记忆压缩（三分区策略，60%/80% 阈值） │ │
│ └──────────────────────────────────────────────────┘ │
│ 并发审查（默认 8 个 sub-agent goroutine） │
└──────────────────────┬───────────────────────────────────┘
│
┌──────────────────────┴───────────────────────────────────┐
│ LLM 抽象层 │
│ 14 个内置 Provider │ 自定义 Provider │ Ollama 本地模型 │
└──────────────────────────────────────────────────────────┘
4.3 核心模块介绍
| 模块 | 路径 | 功能 |
|---|---|---|
| CLI 入口层 | cmd/opencodereview/ |
命令行分发：review、scan、config、llm 等子命令 |
| Agent 编排 | internal/agent/agent.go |
主 Agent 循环：Plan + Main 两阶段，每文件一个 sub-agent goroutine |
| 记忆压缩 | internal/agent/compression.go |
三分区策略管理 Token 预算，60% 异步压缩，80% 同步压缩 |
| 文件过滤 | internal/agent/preview.go |
五重门过滤：binary → exclude → include → unsupported_ext → default_path |
| Diff Provider | internal/diff/git.go |
支持 Workspace / Commit / Range 三种模式获取 diff |
| 评论重定位 | internal/diff/relocation.go |
滑动窗口匹配 + 回退重定位，保证行级精度 |
| 规则引擎 | internal/config/rules/ |
四层优先级链，内置 20+ 种文件类型审查规则 |
| 模板系统 | internal/config/template/ |
5 个 prompt 模板，支持占位符变量替换 |
| LLM 解析 | internal/llm/resolver.go |
14 个内置 Provider 的端点解析，支持自定义 Provider |
| 工具注册表 | internal/tool/ |
6 个 Agent 工具：code_search、file_read_diff、file_find、file_read、code_comment、task_done |
| 会话持久化 | internal/session/persist.go |
JSONL 格式存储每次审查的完整会话，支持回放 |
| Web 查看器 | internal/viewer/server.go |
HTTP 服务提供会话回放 UI，含 Host 头白名单安全防护 |
4.4 核心代码解析
4.4.1 五重门文件过滤（preview.go）
// 五重门文件过滤链
// binary → user_exclude → user_include → unsupported_ext → default_path
//
// 1. 二进制文件先被丢弃
// 2. 用户 exclude 模式优先（.gitignore 风格 glob）
// 3. include 模式可绕过 unsupported_ext 和 default_path 门
// 4. 内置排除测试文件（**/*_test.go、**/*.test.{js,jsx,ts,tsx} 等）
// 5. 噪声目录（vendor/、node_modules/ 等）在 diff 层即被过滤
4.4.2 Agent 编排（agent.go）
// 每个文件启动一个子 Agent goroutine（受 --concurrency 控制，默认 8）
//
// 阶段 1 — Plan（可选）：变更行数 >= 50 时触发
// 单次 LLM 调用生成审查计划清单
//
// 阶段 2 — Main 循环：最多 30 轮工具调用
// 6 个工具：
// - code_search：代码库搜索
// - file_read_diff：读取其他变更文件
// - file_find：文件查找
// - file_read：读取完整文件
// - code_comment：生成审查评论
// - task_done：标记任务完成
//
// 退出条件（满足任一）：
// - task_done 调用
// - 30 轮耗尽
// - 连续 3 轮无有效结果
// - 超时
// - Context 取消
4.4.3 记忆压缩（compression.go）
// 三分区策略管理 Token 预算（MAX_TOKENS = 58888）
//
// 60% 阈值（约 35333 tokens）：
// - 启动异步后台压缩，不阻塞主循环
//
// 80% 阈值（约 47110 tokens）：
// - 同步压缩，确保下一个请求容纳得下
// - 单文件 diff 超过此阈值时直接被跳过
//
// 压缩区渲染为 XML 交给 LLM 摘要
// 摘要包在 <previous_review_summary> 标签中传递给后续请求
4.4.4 评论处理三工序流水线
// 评论处理流水线
// code_comment 工具调用
// → 行解析（滑动窗口匹配，定位评论对应的代码行）
// → 重定位（匹配失败时回退到更宽松的匹配策略）
// → 审查过滤（REVIEW_FILTER_TASK，LLM 二次过滤低质量评论）
// → 第二轮行解析（过滤后重新定位）
// → 渲染输出（终端彩色输出或 CI 评论格式）
4.4.5 规则引擎（四层优先级链）
// 规则配置四层优先级链（从高到低）：
// 1. --rule 参数（最高优先级，CLI 直接指定）
// 2. 项目配置 <repo>/.opencodereview/rule.json
// 3. 全局配置 ~/.opencodereview/rule.json
// 4. 系统内置规则（最低优先级，内嵌 system_rules.json）
//
// 内置规则覆盖 20+ 种文件类型：
// Java、Go、TypeScript、Python、Rust、C/C++、Kotlin、
// XML、YAML、JSON、Properties、FreeMarker 等
4.4.6 模板系统（task_template.json）
// 5 个 prompt 模板：
// - PLAN_TASK：计划阶段 prompt
// - MAIN_TASK：主审查循环 prompt
// - MEMORY_COMPRESSION_TASK：记忆压缩 prompt
// - REVIEW_FILTER_TASK：评论过滤 prompt
// - RE_LOCATION_TASK：评论重定位 prompt
//
// 支持占位符变量替换：
// {{system_rule}} - 系统规则注入
// {{diff}} - 当前文件 diff
// {{change_files}} - 变更文件列表
// {{plan_guidance}} - 计划阶段输出的审查指引
五、项目应用与评价
5.1 应用场景
| 场景 | 说明 |
|---|---|
| CI/CD 流水线自动化审查 | 通过 GitHub Actions / GitLab CI 在每次 PR/MR 时自动运行，将发现作为内联评论回贴 |
| Commit 前本地自查 | 开发者提交前在工作区运行 ocr review，快速发现潜在问题 |
| 存量代码审计 | 通过 ocr scan 审计不熟悉的代码库或目录，无需 Git 历史 |
| 编码 Agent 集成 | 支持 Claude Code、Codex、Cursor、OpenCode 等 AI 编码工具插件，在编码过程中随时触发审查 |
| 委托模式 | 无需独立配置 LLM，让宿主编码 Agent 使用自身的 LLM 执行审查 |
| 安全审查 | 内置 NPE、线程安全、XSS、SQL 注入等专项规则，适合安全敏感场景 |
| 代码规范检查 | 通过规则引擎覆盖 20+ 种文件类型的编码规范，确保团队代码风格统一 |
| 大型 PR 审查辅助 | 分治策略在超大变更场景下稳定运行，辅助人工审查提高效率 |
5.2 项目优点
- 高精度 + 低成本：Benchmark 证明 Precision 和 F1 显著高于通用 Agent，Token 消耗仅约 1/9，成本优势明显。
- 确定性工程保证稳定性：文件筛选、规则匹配、位置定位等关键环节由工程逻辑保证，不受 LLM 随机性影响，结果可预测。
- 行级精确定位：通过滑动窗口匹配 + 重定位 + 过滤三道工序，确保评论位置的高准确性，解决通用 Agent 的"位置漂移"问题。
- 大变更场景稳定：分治策略（per-file 子 Agent + 智能打包 + 记忆压缩）在超大变更场景下表现稳定，不会"偷懒"漏审。
- 开箱即用的 CI/CD 集成：提供 GitHub Actions 和 GitLab CI 的现成工作流，复制即用，支持
/open-code-review评论触发重审。 - 多 Provider 支持：内置 14 个国内外 LLM provider，支持自定义 provider 和 Ollama 本地模型，灵活适配不同场景。
- 多语言文档：README 覆盖英文、中文、日文、韩文、俄文 5 种语言。
- 安全设计：CGO_ENABLED=0 静态编译、路径遍历防护、Host 头白名单、API Key 零日志泄漏，详见 ASSURANCE_CASE.md。
- 丰富的集成生态：VSCode 扩展、Claude Code/Cursor/Codex 插件、MCP Server、Agent Skill、委托模式。
- 会话可回放：每次审查以 JSONL 持久化，提供 Web UI 浏览器回放审查过程。
5.3 项目不足
- 召回率偏低：官方明确承认 Recall 低于通用 Agent，这是以精准度换取低噪声的有意设计取舍。对于安全敏感场景，官方计划在 H2 2026 推出 "Ultra Mode" 高召回模式。
- 无跨文件推理：每个文件在独立的 LLM 对话中审查，跨文件问题只能通过工具调用间接获取上下文，不能直接共享上下文进行推理。
- 子 Agent 失败不重试：单个文件失败产生警告，其余继续。重试依赖外层 CI 流水线，而非 Agent 自身。
- 不支持自动修复：OCR 定位为审查工具，虽然可以建议修复方案，但代码变更始终需要人工批准，不会自动提交 fix。
- 依赖 LLM 质量：审查效果高度依赖底层 LLM 模型的能力。本地模型（如 Ollama）需要原生支持工具调用，否则无法正常工作。
- 大文件 Token 限制：单文件 diff 超过 MAX_TOKENS 的 80%（约 47110 tokens）时会被直接跳过，超大 diff 文件（如自动生成的 lock 文件）无法审查。
- 模板不可 CLI 覆盖：Prompt 模板修改需要编辑源码并重新构建，不能通过 CLI 参数或配置文件覆盖。
- JetBrains IDE 插件未推出：当前仅支持 VSCode 扩展，JetBrains 插件计划在 H2 2026 推出。
- 创建时间较新：2026 年 5 月才开源，社区生态和第三方插件仍在早期阶段，394 commits 显示仍在快速迭代中。
浙公网安备 33010602011771号