今日开源[第38期]Open Code Review (OCR)

博客园 - zhang-yd

zhang-yd · 2026-07-28 · via 博客园 - zhang-yd

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 显示仍在快速迭代中。

参考来源

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

博客园 - zhang-yd

Open Code Review (OCR) 项目分析报告

一、项目介绍

1.1 项目概述

1.2 项目信息

1.3 项目示意图

二、项目亮点

2.1 确定性工程 × Agent 混合驱动（核心创新）

2.2 Benchmark 数据：高精度 + 低成本

2.3 三种审查模式

2.4 评论处理三工序流水线

2.5 记忆压缩机制

2.6 丰富的集成生态

2.7 与同类工具的差异化优势

三、项目运行环境

3.1 基础要求

3.2 核心依赖库

3.3 安装方式

3.4 支持的 LLM Provider（14 个内置）

3.5 配置 LLM

四、项目代码介绍

4.1 代码架构图

4.2 系统架构

4.3 核心模块介绍

4.4 核心代码解析

4.4.1 五重门文件过滤（preview.go）

4.4.2 Agent 编排（agent.go）

4.4.3 记忆压缩（compression.go）

4.4.4 评论处理三工序流水线

4.4.5 规则引擎（四层优先级链）

4.4.6 模板系统（task_template.json）

五、项目应用与评价

5.1 应用场景

5.2 项目优点

5.3 项目不足

参考来源