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

阿里 open-code-review AI代码审查工具实战安装、四层规则链、自定义规则格式与实测避坑结论先放这儿方便你判断要不要往下看阿里把内部用了两年的 AI 代码审查助手开源了命令行叫ocrnpm install两个包、12 秒装完。它跟把 diff 丢给大模型最大的区别是——选文件、分组、匹配规则、控 Token、定位行号全是确定性代码模型只负责读代码和判断问题。这篇是完整的落地记录怎么装、怎么配、四层规则链怎么验证、自定义规则文件的确切格式官方文档没写我试出来的、以及我踩的两个坑。所有命令和输出都是本机真实跑出来的。环境Windows / Node v22.22.2 / Git 2.55.0它要求 Git 2.41/ open-code-review v1.12.9一、安装与验证npminstall-galibaba-group/open-code-review装完的反馈added 2 packages in 12s只有两个包主包 平台二进制包Windows 是ocr-win32-x64。它把 Go 编译好的二进制直接打进 npm 包就是为了绕开装完再下 GitHub Release那一步——官方提交记录里明说国内网络下那步极慢。验证$ 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只走筛选、不调模型不需要 Keyocr scan全文件扫描不需要 diffocr scan --path src/扫描指定目录ocr rules check 文件查看某文件命中的规则及其来源ocr config provider/ocr config model交互式配置模型ocr llm providers列出内置 Providerocr llm test测试端点连通性ocr session list列出历史审查会话ocr session export -o x.html导出为单文件 HTML 报告ocr viewer启动本地 Web UI默认 5483 端口--preview这个参数建议先记住不配模型也能跑用来确认它到底会审哪些文件。三、实测文件筛选怎么工作我造了一个仓库6 个文件改动其中 2 个真该审、4 个是噪音$ ocr review--previewPreview:6file(s)changed|31-2Will review(2):[M]src/main/java/com/example/demo/UserService.java 12-0[M]web/render.js 6-1Excluded 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。它不笼统说跳过而是给出理由——这是确定性筛选和模型拍脑袋的分界线。全仓扫描是同一套逻辑$ ocr scan--previewPreview:8file(s)changed|107-0Will 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 用结构化输出ocr review--formatjson--audienceagent--outputresult.json{path:README.md,status:modified,insertions:4,deletions:0,will_review:false,exclude_reason:unsupported_ext}四、四层规则链怎么验证规则不是写死在提示词里是一条四层链命中即停用ocr rules check逐层验证。第 4 层内置系统规则$ 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、严重性能问题循环内查库、N1、线程安全竞态、非原子复合操作、不安全懒加载、并发写非线程安全集合。换成 JS 文件模式变成**/*.{ts,js,tsx,jsx,mjs,cjs}。换成它不认识的扩展名落到default规则——只剩通用几条逻辑正确性、边界条件、异常处理、并发安全、SQL 注入、XSS。不认识的文件不是不管是用更保守的通用标准管。第 2 层项目级规则。这是第一个坑见下节。第 1 层命令行指定$ ocr rules check--rule./custom-rule.json src/main/java/com/example/demo/UserService.java Source: Custom(--rule)Pattern: **/*.java五、避坑一项目规则文件的确切格式按最自然的写法建.opencodereview/rule.json{rules:{**/*.java:#### 团队规则\n- 所有 SQL 必须使用 PreparedStatement}}报错Error: load rules: unmarshal project rule: json: cannot unmarshal object into Go struct field ProjectRule.rules of type []rules.ProjectRuleEntryrules得是数组。但官方文档站只讲了config.json模型、Provider、超时项目规则文件的结构一个字段都没提。我用穷举试出了字段名forgkinpattern glob path matchfilefiles;doforrkinrule content body text description prompt;doprintf{rules:[{%s:**/*.java,%s:MARKER_XYZ}]}$gk$rk\.opencodereview/rule.json ocr rules check src/main/java/.../UserService.java|grep-qMARKER_XYZ\echoHIT $gk/$rkdonedone结果HIT path / rule。正确格式{rules:[{path:**/*.java,rule:#### 团队 Java 规则\n- 禁止使用 String.format 处理用户输入\n- 所有 SQL 必须使用 PreparedStatement}],exclude:[web/*]}验证生效$ ocr rules check src/main/java/com/example/demo/UserService.java Source: Project(.opencodereview/rule.json)Pattern: **/*.javaexclude吃 gitignore 风格模式。加了web/*之后render.js的排除原因变成user_exclude——自定义排除是独立一类跟内置规则不混。六、避坑二本地端点 URL 不要带 /v1不配模型时的报错把配置途径列得很全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 万。用环境变量配本地模型exportOCR_LLM_URLhttp://127.0.0.1:8899# 注意不带 /v1exportOCR_LLM_TOKENyour-keyexportOCR_LLM_MODELyour-model ocr llmtest用配置文件配推荐可持久化ocr configsetprovider ollama ocr configsetcustom_providers.ollama.url http://127.0.0.1:11434/v1 ocr configsetcustom_providers.ollama.protocol openai ocr configsetcustom_providers.ollama.model qwen3:32b ocr configsetcustom_providers.ollama.api_key ollama注意custom_providers这条路要显式指定protocol并且 URL 带/v1——跟环境变量那条路的规则不一样这点容易搞混。内置 Provider 实测有 28 个$ 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 件tools: [task_done, code_comment, code_search, file_read, file_read_diff, file_find]工具作用参数file_read读文件可指定起止行file_path必填、start_line、end_linecode_search搜文本/正则search_text必填、file_patterns、case_sensitive、use_perl_regexpfile_find按文件名找文件query_name必填、case_sensitivefile_read_diff看同组其他文件的 diffpath_array必填code_comment报问题自动定位行comments必填task_done结束任务state必填全是只读加评论——没有 shell、没有写文件、没有联网。code_comment是唯一产出内容的出口位置由工具负责不由模型自己写行号。规则按路径挂载这是首条用户消息里的原文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 forsrc/main/java/com/example/demo/UserService.java #### 团队 Java 规则 - 禁止使用 String.format 处理用户输入 - 所有 SQL 必须使用 PreparedStatement /rules /user_task同一个请求里不同文件挂不同规则——这就是四层链的落点。八、跑完怎么查$ ocr session listSESSIONID MODE FILES COMMENTS STATUS eb8ded5d-e82a-48e5-8c33-30bf7e1a2e81 workspace2(failed2)0failed $ ocr sessionexport-oreview.html[ocr]Results written to review.html导出的 HTML 157KB样式脚本全内联双击能开会话清单里还记了可复现性凭证resolved_base: 4f27709ef55b31713e7368088bbaf410d532ecd7, source_artifact_sha256: cda79ce7..., rule_config_sha256: 91d01a7b..., runtime_config_sha256: efcdeebe..., ocr_version: v1.12.9同样输入为什么这次报了那次没报是可查的接 CI 时这点很值钱。九、性能参考同模型换跑法的差距官方基准 AACR-Bench50 个开源仓库、200 个真实 PR、10 种语言、1505 条人工标注问题。模型跑法F1精确率召回率平均 TokenQwen3.7-MaxOCR21.20%25.20%18.30%625KClaude-4.8-OpusOCR17.90%37.80%11.70%352KClaude-4.8-Opus通用 Agent14.13%15.93%12.70%2062KQwen3.7-Max通用 Agent12.17%8.23%23.37%5153KToken 差 6 到 8 倍耗时差 5 到 9 倍精确率翻倍15.93% → 37.80%召回率确实更低官方自己写明是刻意取舍——通用 Agent 靠广撒网多捞回一些代价是精确率掉到 8.23%。十、参数速查表需求命令只看会审哪些文件ocr review --preview审查太浅想加轮次--effort high默认 medium2 轮接 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检出率价格CodeRabbit15-25 条63%$24/人/月Ellipsis3-5 条83%$20/人/月Qodo8-12 条57%$19/人/月Greptile6-10 条70%$50/人/月要开箱即用、覆盖全商业 SaaS代价是代码出仓库、按人头付费代码不能出内网、要嵌 CI、有团队规则要落地ocr更合适代价是接入自己动手且它不做风格类评论。十二、一句话总结这套设计里最值得学的不是它用了哪个模型而是它把哪些事从模型手里拿走了选文件、控 Token、匹配规则、定位行号、失败降级全是确定性代码。如果这篇帮你省了踩坑时间点个赞 收藏——那份项目规则文件的格式和 URL 的坑都是我试错试出来的。