阿里 open-code-review （AI代码审查工具）实战：安装、四层规则链、自定义规则格式与实测避坑

结论先放这儿，方便你判断要不要往下看：

阿里把内部用了两年的 AI 代码审查助手开源了，命令行叫 ocr，npm install 两个包、12 秒装完。它跟"把 diff 丢给大模型"最大的区别是------选文件、分组、匹配规则、控 Token、定位行号全是确定性代码，模型只负责读代码和判断问题。

这篇是完整的落地记录：怎么装、怎么配、四层规则链怎么验证、自定义规则文件的确切格式（官方文档没写，我试出来的）、以及我踩的两个坑。所有命令和输出都是本机真实跑出来的。

环境：Windows / Node v22.22.2 / Git 2.55.0（它要求 Git >= 2.41）/ open-code-review v1.12.9

一、安装与验证

bash 复制代码

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

装完的反馈：

复制代码

added 2 packages in 12s

只有两个包：主包 + 平台二进制包（Windows 是 ocr-win32-x64）。它把 Go 编译好的二进制直接打进 npm 包，就是为了绕开"装完再下 GitHub Release"那一步------官方提交记录里明说国内网络下那步极慢。

验证：

bash 复制代码

$ ocr version
open-code-review v1.12.9 (bccbc15f) windows/amd64
built at: 2026-09-22T11:06:41Z

二、核心命令速查

命令	用途
`ocr review`	审查工作区改动（暂存 + 未暂存 + 未跟踪）
`ocr review --from main --to feature`	审查分支区间（按 merge-base 计算）
`ocr review --commit abc123`	审查单个提交
`ocr review --preview`	只走筛选、不调模型，不需要 Key
`ocr scan`	全文件扫描，不需要 diff
`ocr scan --path src/`	扫描指定目录
`ocr rules check <文件>`	查看某文件命中的规则及其来源
`ocr config provider` / `ocr config model`	交互式配置模型
`ocr llm providers`	列出内置 Provider
`ocr llm test`	测试端点连通性
`ocr session list`	列出历史审查会话
`ocr session export -o x.html`	导出为单文件 HTML 报告
`ocr viewer`	启动本地 Web UI（默认 5483 端口）

--preview 这个参数建议先记住：不配模型也能跑，用来确认"它到底会审哪些文件"。

三、实测：文件筛选怎么工作

我造了一个仓库，6 个文件改动，其中 2 个真该审、4 个是噪音：

bash 复制代码

$ ocr review --preview

Preview: 6 file(s) changed  |  +31  -2

Will review (2):
  [M]  src/main/java/com/example/demo/UserService.java +12   -0
  [M]  web/render.js                                   +6    -1

Excluded from review (4):
  [M]  README.md            (unsupported_ext)
  [B]  assets/logo.png      (binary)
  [M]  generated/Api.pb.go  (default_path)
  [M]  package-lock.json    (default_path)

关键是括号里那四类原因 ：扩展名不支持、二进制、命中默认排除路径、用户自定义排除（user_exclude）。它不笼统说"跳过"，而是给出理由------这是确定性筛选和模型拍脑袋的分界线。

全仓扫描是同一套逻辑：

bash 复制代码

$ ocr scan --preview

Preview: 8 file(s) changed  |  +107  -0

Will review (4):
  [S]  src/main/java/com/example/demo/Counter.java     +18   -0
  [S]  src/main/java/com/example/demo/StringUtils.java +24   -0
  [S]  src/main/java/com/example/demo/UserService.java +49   -0
  [S]  web/render.js                                   +16   -0

接 CI 用结构化输出：

bash 复制代码

ocr review --format json --audience agent --output result.json

json 复制代码

{
  "path": "README.md",
  "status": "modified",
  "insertions": 4,
  "deletions": 0,
  "will_review": false,
  "exclude_reason": "unsupported_ext"
}

四、四层规则链怎么验证

规则不是写死在提示词里，是一条四层链，命中即停：

用 ocr rules check 逐层验证。

第 4 层，内置系统规则：

bash 复制代码

$ ocr rules check src/main/java/com/example/demo/UserService.java
File: src/main/java/com/example/demo/UserService.java
Source: System built-in
Pattern: **/*.java

内置的 Java 规则覆盖这几类：拼写错误、死代码、逻辑错误（含 NPE）、严重性能问题（循环内查库、N+1）、线程安全（竞态、非原子复合操作、不安全懒加载、并发写非线程安全集合）。

换成 JS 文件，模式变成 **/*.{ts,js,tsx,jsx,mjs,cjs}。换成它不认识的扩展名，落到 default 规则------只剩通用几条：逻辑正确性、边界条件、异常处理、并发安全、SQL 注入、XSS。不认识的文件不是不管，是用更保守的通用标准管。

第 2 层，项目级规则。这是第一个坑，见下节。

第 1 层，命令行指定：

bash 复制代码

$ ocr rules check --rule ./custom-rule.json src/main/java/com/example/demo/UserService.java
Source: Custom (--rule)
Pattern: **/*.java

五、避坑一：项目规则文件的确切格式

按最自然的写法建 .opencodereview/rule.json：

json 复制代码

{
  "rules": {
    "**/*.java": "#### 团队规则\n- 所有 SQL 必须使用 PreparedStatement"
  }
}

报错：

csharp 复制代码

Error: load rules: unmarshal project rule: json: cannot unmarshal object
into Go struct field ProjectRule.rules of type []rules.ProjectRuleEntry

rules 得是数组。但官方文档站只讲了 config.json（模型、Provider、超时），项目规则文件的结构一个字段都没提。

我用穷举试出了字段名：

bash 复制代码

for gk in pattern glob path match file files; do
  for rk in rule content body text description prompt; do
    printf '{"rules":[{"%s":"**/*.java","%s":"MARKER_XYZ"}]}' "$gk" "$rk" \
      > .opencodereview/rule.json
    ocr rules check src/main/java/.../UserService.java | grep -q MARKER_XYZ \
      && echo "HIT => $gk / $rk"
  done
done

结果：HIT => path / rule。

正确格式：

json 复制代码

{
  "rules": [
    {
      "path": "**/*.java",
      "rule": "#### 团队 Java 规则\n- 禁止使用 String.format 处理用户输入\n- 所有 SQL 必须使用 PreparedStatement"
    }
  ],
  "exclude": ["web/*"]
}

验证生效：

bash 复制代码

$ ocr rules check src/main/java/com/example/demo/UserService.java
Source: Project (.opencodereview/rule.json)
Pattern: **/*.java

exclude 吃 gitignore 风格模式。加了 web/* 之后，render.js 的排除原因变成 user_exclude------自定义排除是独立一类，跟内置规则不混。

六、避坑二：本地端点 URL 不要带 /v1

不配模型时的报错把配置途径列得很全：

javascript 复制代码

Error: resolve LLM endpoint: no valid LLM endpoint configured; one of
OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL, ~/.opencodereview/config.json,
or ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/ANTHROPIC_MODEL must be set

注意最后三个 ANTHROPIC_*------环境变量模式默认走 Anthropic 协议 ，请求打到 /v1/messages。

我一开始把 URL 写成 http://127.0.0.1:8899/v1，结果实际路径变成 /v1/v1/messages，多一层。端点 404，它拿不到工具调用就一轮轮重试，白跑 101 轮、烧掉 13 万 Token。

去掉 /v1 后正常，Token 从 13 万降到 1.1 万。

用环境变量配本地模型：

bash 复制代码

export OCR_LLM_URL=http://127.0.0.1:8899      # 注意：不带 /v1
export OCR_LLM_TOKEN=your-key
export OCR_LLM_MODEL=your-model
ocr llm test

用配置文件配（推荐，可持久化）：

bash 复制代码

ocr config set provider                          ollama
ocr config set custom_providers.ollama.url       http://127.0.0.1:11434/v1
ocr config set custom_providers.ollama.protocol  openai
ocr config set custom_providers.ollama.model     qwen3:32b
ocr config set custom_providers.ollama.api_key   ollama

注意 custom_providers 这条路要显式指定 protocol，并且 URL 带 /v1------跟环境变量那条路的规则不一样，这点容易搞混。

内置 Provider 实测有 28 个：

bash 复制代码

$ ocr llm providers
  NAME                 PROTOCOL           BASE URL
  anthropic            anthropic          https://api.anthropic.com
  dashscope            openai             https://dashscope.aliyuncs.com/compatible-mode/v1
  deepseek             openai             https://api.deepseek.com
  kimi                 openai             https://api.moonshot.cn/v1
  z-ai                 openai             https://open.bigmodel.cn/api/paas/v4
  volcengine           openai             https://ark.cn-beijing.volces.com/api/v3
  ...

七、它到底给模型发了什么

用一个本地假端点（记录请求 + 返回合规响应）把原始请求截了下来。

工具只有 6 件：

arduino 复制代码

tools: ['task_done', 'code_comment', 'code_search',
        'file_read', 'file_read_diff', 'file_find']

工具	作用	参数
`file_read`	读文件，可指定起止行	`file_path`（必填）、`start_line`、`end_line`
`code_search`	搜文本/正则	`search_text`（必填）、`file_patterns`、`case_sensitive`、`use_perl_regexp`
`file_find`	按文件名找文件	`query_name`（必填）、`case_sensitive`
`file_read_diff`	看同组其他文件的 diff	`path_array`（必填）
`code_comment`	报问题，自动定位行	`comments`（必填）
`task_done`	结束任务	`state`（必填）

全是只读加评论------没有 shell、没有写文件、没有联网。code_comment 是唯一产出内容的出口，位置由工具负责，不由模型自己写行号。

规则按路径挂载，这是首条用户消息里的原文：

ini 复制代码

<user_task>
### Review Checklist
<rules for=".opencodereview/rule.json">
Check JSON files for spelling errors in json-keys; ignore the content of json-values.
</rules>
<rules for="src/main/java/com/example/demo/UserService.java">
#### 团队 Java 规则
- 禁止使用 String.format 处理用户输入
- 所有 SQL 必须使用 PreparedStatement
</rules>
</user_task>

同一个请求里，不同文件挂不同规则------这就是四层链的落点。

八、跑完怎么查

bash 复制代码

$ ocr session list
SESSION ID                            MODE       FILES         COMMENTS  STATUS
eb8ded5d-e82a-48e5-8c33-30bf7e1a2e81  workspace  2 (failed 2)  0         failed

$ ocr session export -o review.html
[ocr] Results written to review.html

导出的 HTML 157KB，样式脚本全内联，双击能开：

会话清单里还记了可复现性凭证：

json 复制代码

"resolved_base": "4f27709ef55b31713e7368088bbaf410d532ecd7",
"source_artifact_sha256": "cda79ce7...",
"rule_config_sha256": "91d01a7b...",
"runtime_config_sha256": "efcdeebe...",
"ocr_version": "v1.12.9"

"同样输入为什么这次报了那次没报"是可查的，接 CI 时这点很值钱。

九、性能参考：同模型换跑法的差距

官方基准 AACR-Bench：50 个开源仓库、200 个真实 PR、10 种语言、1505 条人工标注问题。

模型	跑法	F1	精确率	召回率	平均 Token
Qwen3.7-Max	OCR	21.20%	25.20%	18.30%	625K
Claude-4.8-Opus	OCR	17.90%	37.80%	11.70%	352K
Claude-4.8-Opus	通用 Agent	14.13%	15.93%	12.70%	2062K
Qwen3.7-Max	通用 Agent	12.17%	8.23%	23.37%	5153K

Token 差 6 到 8 倍，耗时差 5 到 9 倍；
精确率翻倍（15.93% → 37.80%）；
召回率确实更低，官方自己写明是刻意取舍------通用 Agent 靠广撒网多捞回一些，代价是精确率掉到 8.23%。

十、参数速查表

需求	命令
只看会审哪些文件	`ocr review --preview`
审查太浅，想加轮次	`--effort high`（默认 medium，2 轮）
接 CI，只要结构化结果	`--format json --audience agent`
排除某些路径	`--exclude '*/generated/,*.pb.go'`
注入业务背景	`--background "本次改动是修订单金额计算"`
控制成本	`--max-tokens-budget 500000`
输出 SARIF 给 GitHub Code Scanning	`--format sarif`
评论说中文	配置项 `language`
断点续跑	`--resume <session-id>`

十一、和商业方案的取舍

第三方横评把四款商业工具挂在同一个 50 万行 TypeScript 仓库跑了两周、40 个 PR（人工标 30 个真实问题）：

工具	评论数/PR	检出率	价格
CodeRabbit	15-25 条	63%	$24/人/月
Ellipsis	3-5 条	83%	$20/人/月
Qodo	8-12 条	57%	$19/人/月
Greptile	6-10 条	70%	$50/人/月

要开箱即用、覆盖全：商业 SaaS，代价是代码出仓库、按人头付费；
代码不能出内网、要嵌 CI、有团队规则要落地 ：ocr 更合适，代价是接入自己动手，且它不做风格类评论。

十二、一句话总结

这套设计里最值得学的，不是它用了哪个模型，而是它把哪些事从模型手里拿走了：选文件、控 Token、匹配规则、定位行号、失败降级，全是确定性代码。

如果这篇帮你省了踩坑时间，点个赞 + 收藏------那份项目规则文件的格式和 URL 的坑，都是我试错试出来的。