open-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Open Code Review

A skill for invoking open-code-review (

ocr

) — an open-source AI code review CLI that reads Git diffs and generates structured, line-level review comments.

这是一个用于调用open-code-review（

ocr

）的技能——open-code-review是一款开源AI代码审查CLI工具，可读取Git diff并生成结构化的行级审查评论。

Prerequisites check

前置条件检查

Before starting a review, verify the environment:

bash

undefined

开始审查前，请验证环境：

bash

undefined

1. Check the CLI is installed

1. 检查CLI是否已安装

which ocr || echo "NOT INSTALLED"

2. Verify LLM connectivity

2. 验证LLM连通性

ocr llm test


If `ocr` is not installed, install it first:

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

ocr llm test

fails, the user must configure an LLM. Guide them with one of these options:

Option A — Environment variables (highest priority, recommended for CI):

bash

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

Option B — Persistent config:

bash

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

Stop here and ask the user to provide credentials — never invent or hardcode API keys.

ocr llm test


若未安装`ocr`，请先执行安装：

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

若

ocr llm test

执行失败，用户需配置LLM。可引导用户选择以下方案之一：

方案A — 环境变量（优先级最高，推荐CI环境使用）：

bash

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

方案B — 持久化配置：

bash

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

在此步骤停止并请求用户提供凭证——切勿编造或硬编码API密钥。

Workflow

工作流程

Step 1: Gather Business Context

步骤1：收集业务上下文

Analyze the review target (commits, branch, or changes) to extract concise business context. Pass this context via

--background

to improve review quality.

分析审查目标（提交记录、分支或变更）以提取简洁的业务上下文。通过

--background

参数传递该上下文，以提升审查质量。

Step 2: Run Code Review

步骤2：执行代码审查

Run the OCR command with appropriate flags. Always pass business context via
--background
when available:

bash

ocr review --audience agent --background "business context here" [user-args]

Argument handling:

Background context (RECOMMENDED): use
```
--background "context"
```
or
```
-b "context"
```
to provide business context for better review quality
Default (no user arguments): reviews staged, unstaged, and untracked changes (workspace mode)
Specific commit: use
```
--commit
```
or
```
-c
```
to review a single commit against its parent
Branch comparison: use
```
--from <ref>
```
and
```
--to <ref>
```
to review diff between two refs
Timeout: default timeout is 10 minutes per file; adjust with
```
--timeout <minutes>
```
Concurrency: default concurrency is 8 file workers; reduce with
```
--concurrency <n>
```
if rate limits are hit
Preview mode: use
```
--preview
```
or
```
-p
```
to preview which files will be reviewed without running the LLM
Installation: if
```
ocr
```
command is not found, install it by running
```
npm i -g @alibaba-group/open-code-review
```

Common invocation patterns:

User says	Command to run
"review my changes" / "review the working copy"	`ocr review --audience agent -b "context"`
"review this PR" / "review feature branch"	`ocr review --audience agent -b "context" --from main --to <branch>`
"review commit abc123"	`ocr review --audience agent -b "context" --commit abc123`
"what would be reviewed?" (dry-run)	`ocr review --preview`

Output mode:

Always use
```
--audience agent
```
to suppress progress UI and emit only the final summary

使用合适的标志运行OCR命令。若存在业务上下文，请始终通过
--background
传递：

bash

ocr review --audience agent --background "业务上下文内容" [用户参数]

参数处理规则：

业务上下文（推荐）：使用
```
--background "上下文内容"
```
或
```
-b "上下文内容"
```
提供业务上下文，以提升审查质量
默认情况（无用户参数）：审查暂存、未暂存及未跟踪的变更（工作区模式）
指定提交记录：使用
```
--commit
```
或
```
-c
```
审查单个提交记录与其父提交的差异
分支对比：使用
```
--from <引用>
```
和
```
--to <引用>
```
审查两个引用之间的差异
超时设置：默认每个文件超时时间为10分钟；可通过
```
--timeout <分钟数>
```
调整
并发设置：默认并发数为8个文件处理进程；若触发速率限制，可通过
```
--concurrency <数量>
```
降低并发数
预览模式：使用
```
--preview
```
或
```
-p
```
预览将被审查的文件，无需运行LLM
安装提示：若未找到
```
ocr
```
命令，执行
```
npm i -g @alibaba-group/open-code-review
```
进行安装

常见调用场景：

用户需求	执行命令
"审查我的变更" / "审查工作副本"	`ocr review --audience agent -b "上下文内容"`
"审查这个PR" / "审查特性分支"	`ocr review --audience agent -b "上下文内容" --from main --to <分支名>`
"审查提交记录abc123"	`ocr review --audience agent -b "上下文内容" --commit abc123`
"会审查哪些内容？"（试运行）	`ocr review --preview`

输出模式：

始终使用
```
--audience agent
```
参数，以屏蔽进度UI，仅输出最终摘要

Step 3: Classify and Report

步骤3：分类与报告

For each comment from the review output, classify by priority and report all issues to the user:

High: Obvious bugs, security issues, clear mistakes, or well-founded suggestions with precise fix proposals
Medium: Reasonable concerns but context-dependent, style/performance suggestions, or fixes that require manual implementation
Low: Likely false positives, lacking sufficient context, nitpicks, or meaningless suggestions

Report all comments grouped by priority level.

针对审查输出中的每条评论，按优先级分类并向用户报告所有问题：

高优先级：明显的Bug、安全问题、低级错误，或带有精确修复方案的合理建议
中优先级：合理但依赖上下文的问题、风格/性能优化建议，或需手动实现的修复方案
低优先级：疑似误报、上下文不足的问题、吹毛求疵的建议或无意义的内容

按优先级分组报告所有评论。

Step 4: Fix

步骤4：修复

Before applying fixes, check whether the user requested automatic fixes:

If the user explicitly requested "review and fix" or similar, proceed with automatic fixes
If the user only requested "review" without fix intent, ask for permission before applying any changes

When fixing issues and suggestions:

Focus on High and Medium priority items
Apply fixes directly to the code when safe and well-defined
For complex fixes requiring manual intervention, clearly describe what needs to be done
Always verify fixes with the user before committing

应用修复前，需确认用户是否要求自动修复：

若用户明确要求"审查并修复"或类似需求，可执行自动修复
若用户仅要求"审查"未提及修复，需先征得用户同意再进行任何变更

修复问题与建议时：

重点处理高优先级和中优先级的内容
安全且定义明确的修复可直接应用到代码中
对于需手动干预的复杂修复，清晰描述需执行的操作
提交修复前始终与用户确认

Output Format

输出格式

Each comment contains:

```
path
```
: File path
```
content
```
: Review comment text
```
start_line
```
/
```
end_line
```
: Line range (both 0 means positioning failed)
```
suggestion_code
```
: Optional fix suggestion
```
existing_code
```
: Optional original code snippet
```
thinking
```
: Optional LLM reasoning process

After filtering comments by priority, present results using this template:

markdown

undefined

每条评论包含以下字段：

```
path
```
: 文件路径
```
content
```
: 审查评论文本
```
start_line
```
/
```
end_line
```
: 行范围（均为0表示定位失败）
```
suggestion_code
```
: 可选的修复建议代码
```
existing_code
```
: 可选的原始代码片段
```
thinking
```
: 可选的LLM推理过程

按优先级过滤评论后，使用以下模板展示结果：

markdown

undefined

Code Review Results

代码审查结果

Files reviewed: N Issues found: X high priority / Y medium priority

已审查文件数: N 发现问题数: X个高优先级 / Y个中优先级

High Priority

高优先级

path/to/file.java:42
— Brief description

Recommendation: How to fix

path/to/file.java:42
— 简要描述

修复建议：具体修复方式

Medium Priority

中优先级

path/to/file.ts:88
— Brief description

Recommendation: How to fix (if applicable)


If the review found no issues after filtering, simply state: "Review complete — no issues found in N files."

**Priority classification:**

- **High**: Obvious bugs, security issues, clear mistakes, or well-founded suggestions with precise fix proposals
- **Medium**: Reasonable concerns but context-dependent, style/performance suggestions, or fixes that require manual implementation
- **Low**: Discarded silently (likely false positives, lacking context, nitpicks, or meaningless suggestions)

**Handling mispositioned comments:**

When `start_line` and `end_line` are both `0`, the comment failed to locate the exact position in the file. In such cases:

1. Read the comment content to understand the issue
2. Examine the target file mentioned in the comment
3. Identify the relevant code section based on the comment's context
4. Apply the fix or suggestion to the correct location

path/to/file.ts:88
— 简要描述

修复建议：具体修复方式（若适用）


若过滤后未发现任何问题，只需说明："审查完成——在N个文件中未发现问题。"

**优先级分类规则：**

- **高优先级**：明显的Bug、安全问题、低级错误，或带有精确修复方案的合理建议
- **中优先级**：合理但依赖上下文的问题、风格/性能优化建议，或需手动实现的修复方案
- **低优先级**：直接忽略（疑似误报、上下文不足、吹毛求疵或无意义的建议）

**定位失败的评论处理：**

当`start_line`和`end_line`均为`0`时，说明评论无法定位到文件中的准确位置。此时需：

1. 阅读评论内容以理解问题
2. 查看评论中提及的目标文件
3. 根据评论上下文识别相关代码段
4. 将修复或建议应用到正确位置

Custom Review Rules

自定义审查规则

If the user wants project-specific rules, OCR resolves them in this priority order:

```
--rule <path>
```
flag (highest)
```
<repo>/.opencodereview/rule.json
```
```
~/.opencodereview/rule.json
```
Built-in system defaults (lowest)

Rule file format:

json

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

To preview which rule applies to a file before reviewing:

bash

ocr rules check src/main/java/com/example/Foo.java

若用户需要项目专属规则，OCR将按以下优先级顺序加载规则：

```
--rule <路径>
```
参数（优先级最高）

<仓库根目录>/.opencodereview/rule.json

```
~/.opencodereview/rule.json
```
内置系统默认规则（优先级最低）

规则文件格式：

json

{
  "rules": [
    {
      "path": "**/*.java",
      "rule": "所有新方法必须验证必填参数是否为空"
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "检查SQL是否存在注入风险及未闭合标签"
    }
  ]
}

审查前可预览文件适用的规则：

bash

ocr rules check src/main/java/com/example/Foo.java

Gotchas

注意事项

LLM must be configured first —
```
ocr review
```
will fail loudly if no LLM is reachable. Always run
```
ocr llm test
```
before the first review.
Working directory matters —
```
ocr review
```
operates on the Git repo at the current directory. Use
```
--repo /path/to/repo
```
to run from elsewhere.
Untracked files are reviewed in workspace mode — running bare
```
ocr review
```
includes staged, unstaged, and untracked changes. Stage selectively if you want narrower scope.
Large diffs may hit token limits — files with very large diffs may be truncated. The default
```
MAX_TOKENS
```
is 58888 per request.
Plan phase triggers at 50 lines — diffs exceeding 50 changed lines run an extra risk-analysis phase before main review. This adds latency but improves quality.
Don't pass
--audience human
— it streams progress UI that pollutes output. Always use
```
--audience agent
```
.
Comment language follows config — set
```
language
```
config to
```
English
```
or
```
Chinese
```
(default: Chinese) to control review comment language.

必须先配置LLM — 若无法连接LLM，
```
ocr review
```
会直接执行失败。首次审查前务必运行
```
ocr llm test
```
。
工作目录至关重要 —
```
ocr review
```
针对当前目录下的Git仓库操作。若需从其他目录执行，使用
```
--repo /path/to/repo
```
指定仓库路径。
工作区模式会审查未跟踪文件 — 直接运行
```
ocr review
```
会包含暂存、未暂存及未跟踪的变更。若需缩小范围，请选择性暂存文件。
大差异可能触发令牌限制 — 差异过大的文件可能被截断。默认
```
MAX_TOKENS
```
为每个请求58888。
差异超过50行时触发规划阶段 — 变更行数超过50行时，主审查前会额外执行风险分析阶段。这会增加延迟但提升审查质量。
请勿使用
--audience human
参数 — 该参数会输出进度UI，污染输出内容。请始终使用
```
--audience agent
```
。
评论语言跟随配置 — 设置
```
language
```
配置为
```
English
```
或
```
Chinese
```
（默认值：Chinese），可控制审查评论的语言。

Validation

验证步骤

After the review completes, verify success by checking:

The command exited with code 0
Comments were generated (or "No comments generated" message appears)
Warnings (if any) are displayed in stderr

If errors occurred, check the stderr warnings for details about which files failed and why.

审查完成后，通过以下方式验证是否成功：

命令退出码为0
已生成评论（或显示"No comments generated"消息）
警告信息（若有）显示在stderr中

若出现错误，查看stderr中的警告信息，了解哪些文件失败及失败原因。

References

参考资料

Full docs: https://github.com/alibaba/open-code-review
NPM package: https://www.npmjs.com/package/@alibaba-group/open-code-review
Issue tracker: https://github.com/alibaba/open-code-review/issues

完整文档：https://github.com/alibaba/open-code-review
NPM包：https://www.npmjs.com/package/@alibaba-group/open-code-review
问题追踪：https://github.com/alibaba/open-code-review/issues