open-code-review 评审规则体系完全指南四层优先级链、五段式文件过滤与自定义规则实战【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibabas scale. Hybrid architecture code review tool: deterministic pipelines LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review导读本文围绕 open-code-reviewOCR的评审规则Review Rules机制展开讲解它如何决定每一个被 diff 的文件该被 AI 关注什么从--rule参数、项目级.opencodereview/rule.json、全局配置到内置系统规则的四层优先级解析链再到决定文件是否进入 LLM 评审的五段式过滤算法以及 glob 匹配语法、.m文件内容嗅探和ocr rules check调试命令。读完本文你将掌握如何用项目级规则强制团队编码规范、如何跳过生成代码、如何按 PR 临时覆盖规则以及如何精确验证某条规则最终是否生效。本文以 pages/src/content/docs/ja/review-rules.md 为骨架并结合仓库源码与测试进行原理级扩充。规则是什么告诉 OCR 每个文件该看什么评审规则的本质是一组「文件路径模式 → 评审指令」的映射。OCR 在评审每个文件时会先根据文件路径匹配出一条规则再把这条规则文本注入到发给模型的 prompt 中告诉模型对这个类型的文件重点检查哪些方面。规则存放在3 层 JSON 文件中外加一个随二进制内置的系统默认规则。系统层保证任何时候都有规则可用即使项目从未配置过任何规则。四层优先级链Priority ChainOCR 使用四层优先级链解析规则。对于每一个文件路径按层从上到下依次尝试第一个匹配成功的模式生效优先级来源路径说明1最高--rule参数用户指定CLI 层覆盖。只要指定就始终生效。2项目配置repoDir/.opencodereview/rule.json项目级规则可安全提交到仓库。3全局配置~/.opencodereview/rule.json用户级偏好对机器上所有仓库生效。4最低系统默认内置system_rules.json覆盖常见语言的嵌入式规则。更高优先级的层如果文件不存在则静默跳过不算错误。因此从未添加过.opencodereview/rule.json的项目会自然落到全局 / 系统层。系统层始终存在随二进制内置所以必然能解析出某种规则。这一优先级逻辑在源码中有清晰对应composedResolver按custom → project → global → system顺序依次尝试见 internal/config/rules/system_rules.go 的Resolve方法与 NewResolver。其中还蕴含一个值得注意的工程细节项目层文件通过符号链接求值filepath.EvalSymlinks并校验最终路径必须落在仓库根目录内防止恶意软链逃逸仓库边界loadProjectRule。注monorepo 子目录执行ocr review时加载的是git 仓库根目录下的.opencodereview/rule.json规则匹配的是相对仓库根目录的 diff 路径子目录内的局部 rule.json 不会被读取——共享规则应放在仓库根或改用--rule显式指定。该行为在 loadProjectRule 的注释中有明确说明。规则文件格式层 13{ include: [src/**/*.{ts,tsx}, src/**/*.go], exclude: [**/*.test.ts, **/generated/**], rules: [ { path: src/api/**/*.go, rule: All exported handlers must validate request bodies before use. }, { path: **/*mapper*.xml, rule: Check SQL for injection risks, parameter errors, and missing closing tags. } ] }三个相互独立的字段include可选。用于绕过内置默认排除模式如测试文件排除见下的 glob 模式。它不是白名单——不匹配任何include模式的文件依然会通过unsupported_ext与default_path检查仍可能被评审。exclude可选。OCR 不评审的文件的 glob 模式。在过滤中优先级最高。rules{path, rule}条目数组按声明顺序求值。对某文件第一个匹配的pathglob 条目决定 OCR 发送给模型的 prompt。值得补充的源码细节rule字段的值不仅可以是内联文本还可以是一个指向.md/.txt/.markdown文件的相对或绝对路径加载时该文件内容会被读取并内联进规则单行、无空格、扩展名符合白名单时才被判定为文件引用见 resolveRuleEntries。同时存在安全与体积约束扩展名白名单校验、512 KB 大小上限、符号链接解析与仓库根目录围栏readRuleFileSafe适合团队把冗长的评审规范放进独立 md 文件统一维护。glob 语法能力OCR 使用 Go 生态的bmatcuk/doublestar/v4做路径匹配*匹配除/外的任意字符。**跨越目录边界匹配src/**/*.go覆盖任意深度。{a,b,c}花括号展开。*.{ts,tsx,js,jsx}展开为 4 个模式依次尝试匹配。?匹配单个字符。[abc]字符类。模式匹配不区分大小写匹配前文件路径会被统一转小写。不确定时可执行ocr rules check path验证。花括号展开在源码中由expandBraces实现internal/config/rules/system_rules.godoublestar.Match时路径与模式双方均先strings.ToLower如 resolveDetail与文档描述完全一致。文件如何被过滤五段式门控算法过滤是五段式门控算法位于 internal/agent/preview.go。对每个 diffOCR 依次提问binary文件是二进制吗→ 排除。user_exclude路径匹配任一用户exclude模式吗→ 排除。user_include用户定义了include时路径匹配它吗匹配则立即保留跳过下面的unsupported_ext与default_path门。unsupported_ext文件扩展名在白名单中吗不在 → 排除。default_path路径匹配任一内置测试文件排除模式**/*_test.go、**/*.test.{js,jsx,ts,tsx}、**/*_spec.rb……吗匹配 → 排除。只有通过全部 5 个门控的文件才会被发送给 LLM。deleted是一种独立计算的原因而非门控当新路径为/dev/null时表示文件被删除没有新内容可评审。源码中的whyExcluded方法internal/agent/preview.go正是这 5 个门控的直译返回类型化的ExcludeReasonExcludeBinary/ExcludeUserRule/ExcludeExtension/ExcludeDefaultPath等。使用ocr review --preview可以在不消耗任何 token的情况下打印过滤结果用于审计哪些文件会被评审、哪些被排除及原因对应 Preview它只加载 diff 并应用过滤不构建 session、manifest 或 runner。默认路径排除Default Path Exclusions内置排除清单见 internal/config/allowlist/default_exclude_patterns.json主要匹配测试文件模式文档中列出的核心条目**/*_test.go**/src/test/java/**/*.java**/src/test/**/*.kt**/*.test.{js,jsx,ts,tsx}**/*.spec.{js,jsx,ts,tsx}**/__tests__/****/test/**/*_test.py**/tests/**/*_test.py**/*_test.py**/*_spec.rb**/spec/**/*_spec.rb**/*Test.java**/*Tests.java**/*_test.rs**/oh_modules/****/*.test.ets实际仓库中的清单比文档示例更全面还额外覆盖了**/*Test.swift、**/Tests/**/*.swift、**/*.snap、**/testdata/**、**/fixtures/**、**/*.pb.go、**/*_test.zig、**/kitex_gen/**/*.go、**/*_capnp.rs等模式以及**/*.generated.*、**/*.gen.go之类的生成代码模式。噪声目录vendor/、node_modules/、target/……的过滤发生在更早的 diff 层internal/diff/git.go先于逐文件过滤。若希望评审这些命中测试文件模式的文件把它们加入用户include列表即可——include会覆盖 default-path 门控。逐文件规则解析Rule Resolution当一个文件经过滤被判定为要评审后OCR 会为该文件选定 agent 应遵循的规则文本按声明顺序尝试--rulecustom层。按声明顺序尝试repo/.opencodereview/rule.json。按声明顺序尝试~/.opencodereview/rule.json。回退到内置系统规则层。用户规则默认整体替换系统规则若某条用户规则设置了merge_system_rule: true则系统规则与用户规则会被合并以## System-Specific Rules (Mandatory)与## User-Specific Rules (Mandatory)两段拼接见 mergeWithSystemRule。内置系统规则与语言覆盖以下为内置 system_rules.json 中的主要模式及其对应规则文档按相对匹配顺序模式规则文档**/*.propertiesproperties.mdi18n / 配置文件。**/*{mapper,dao}*.xmlmapper_dao_xml.mdMyBatis 风格 mapper SQL。**/pom.xmlpom_xml.mdMaven 依赖。**/build.gradlebuild_gradle.mdGradle 依赖。**/package.jsonpackage_json.mdNPM 依赖 / 脚本。**/Cargo.tomlcargo_toml.mdRust manifest。**/composer.jsoncomposer_json.mdComposer 依赖、自动加载、脚本、插件、包配置。**/*.{json,json5}json.md通用 JSON同样匹配.json5。.github/workflows/**/*.{yaml,yml}github_workflows.mdGitHub Actions 工作流 YAML。.github/**/*.{yaml,yml}github_config.md其他.github配置 YAML。**/*.{yaml,yml}yaml.md**/*.javajava.md**/*.gogo.mdGo 源码。**/*.{ftl,ftlh,ftlx}freemarker.mdFreeMarker 模板SSTI / XSS / null 处理。**/*.{hbs,mustache}handlebars_mustache.mdHandlebars / Mustache 模板。**/*.etsarkts.mdArkTS / HarmonyOS。**/*.astroastro.mdAstro 组件与 islands。**/*.{ts,js,tsx,jsx,mjs,cjs}ts_js_tsx_jsx.md**/*.{kt,kts}kotlin.md**/*.rsrust.md**/*.Rr.md**/*.{cpp,cc,cxx,hpp,hxx}cpp.md**/*.cc.md**/*.{py,ipynb}python.mdPython 源码。**/*.{php,phtml}php.mdPHP 源码与 PHP 模板。**/*.protoprotobuf.mdProtocol Buffers 线格式兼容性。**/*.popo.mdgettext 翻译源目录。**/*.potpot.mdgettext 模板文件。**/*.{graphql,gql}graphql.mdGraphQL 模式与操作。**/*.prismaprisma.mdPrisma 模式。**/*.jljulia.mdJulia 源码。**/*.{tf,hcl,tfvars}terraform.mdTerraform / HCL。**/*.bicepbicep.mdBicepAzure模板。**/*.elmelm.mdElm 源码。**/*.{jsonnet,libsonnet}jsonnet.mdJsonnet 配置模板与库。**/*.thriftthrift.mdApache Thrift IDL 线格式兼容性。**/*.capnpcapnp.mdCapn Proto 模式线格式兼容性。**/*.{v,sv,vh}verilog.mdVerilog 与 SystemVerilog RTL。**/*.{vhd,vhdl}vhdl.mdVHDL RTL。**/*.mmatlab.md或经内容嗅探判定为objc.md**/*.mmobjc.mdObjective-C 源码。**/*.solsolidity.mdSolidity 智能合约。**/*.vyvyper.mdVyper 智能合约。兜底default.md此外实际 system_rules.json 还内置了**/*.pug → pug.md、**/*.nix → nix.md、**/*.{hs,lhs} → haskell.md、**/*.{nim,nims,nimble} → nim.md、**/*.swift → swift.md、**/*.zig → zig.md、**/*.{ml,mli} / **/*.{re,rei} → ocaml.md等模式全部规则文档位于 internal/config/rules/rule_docs/ 目录规则文本按path_rule_map的键顺序首个匹配优先解析——system_rules.go 专门实现了保序的UnmarshalJSON以维持先匹配先得语义。这些内置规则文档并非空泛提示。以 go.md 为例它明确给出 Go 专项检查清单错误包装需用%w保留错误链、sync.Once不适合失败重试、context必须显式传递而非存进 struct、math/rand不得用于安全敏感密钥须用crypto/rand、SQL/命令拼接需参数化、以及先取证再上报使用file_read与code_search建立调用点证据等原则。这正是文档所述内置多语言规则集NPE、线程安全、XSS、SQL 注入的具体承载。解析出的规则正文最终成为 plan 与 main task prompt 中{{system_rule}}占位符的内容见 internal/config/template/prompts/main_task_user.md 与 internal/config/template/prompts/plan_task_user.md也注入 scan_template.json 的 Review Checklist 段。.m文件的内容嗅探Content Sniffing.m扩展名被 MATLAB 与 Objective-C 共用。OCR 通过窥视文件首个非空行来区分若内容像 Objective-C如#import、implementation、C 风格注释则改用objc.md替代matlab.md若无法读取内容则回退matlab.md。源码见 internal/config/rules/sniffer.goobjcSniffPrefixes列出#import、#include、#pragma、#if、#define、import、interface、implementation、class、protocol、//、/*等判定前缀sniffer.go并刻意不把裸#当作信号以免误伤把#当注释符的 Octave/MATLAB 文件。评审模式range/commit下还会通过git show ref:path读取指定 ref 的内容而不是工作区保证未检出的 ref 也能正确解析showAtRef。稳定性提示。嗅探启发式可能随 OCR 版本变化。若需要对.m文件做确定性路由请为.m路径配置显式的项目级规则——项目规则永远优先于系统层。验证生效规则ocr rules check当某条规则没有按预期生效时用此命令查看实际生效的层与模式$ ocr rules check src/main/java/com/example/UserService.java File: src/main/java/com/example/UserService.java Source: System built-in Pattern: **/*.java Rule: ──────────────────────────────────────── …contents of java.md… ────────────────────────────────────────$ ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml File: src/main/resources/mapper/UserMapper.xml Source: Custom (--rule) Pattern: **/*mapper*.xml Rule: ──────────────────────────────────────── …contents of your custom rule… ────────────────────────────────────────命令实现位于 cmd/opencodereview/rules_cmd.go通过rules.NewResolver构建完整四层解析器再以DetailResolver.ResolveDetail取回{Rule, Source, Pattern}元数据。Source对应四种标签Custom (--rule)、Project (.opencodereview/rule.json)、Global (~/.opencodereview/rule.json)、System built-in若规则经内容嗅探选中如.m判定为 Objective-C还会额外打印Note: rule selected by file content (objc), not by path alone一行。该命令还支持--repo标志指定仓库目录。实战配方Recipes项目级强制团队编码规范保存为repo/.opencodereview/rule.json并提交到仓库{ rules: [ { path: src/api/**/*.go, rule: Every public handler must defer tx.Rollback() immediately after starting a transaction. }, { path: **/*mapper*.xml, rule: Check SQL for injection risks, missing parameter binding, and unclosed XML tags. } ] }项目级跳过生成代码聚焦 src{ include: [src/**/*.{ts,tsx,js,jsx}], exclude: [**/*.gen.ts, **/generated/**] }设置include后src/内的文件即使原本会命中内置默认排除模式如测试文件也会被保留src/之外的文件仍走常规的 ext / default 检查。再次强调include是旁路机制不是白名单。按 PR 覆盖规则ocr review --rule ./.review-rules-only-for-this-pr.json这会同时旁路项目层与全局层。适用于单个 PR 需要完全不同的评审清单例如只做安全评审的场景。--rule的 CLI 最高优先级、按声明顺序首个匹配生效均与四层链一致见 rules_cmd.go 中review命令对--rule的处理。全局个人偏好放在~/.opencodereview/rule.json本机所有仓库继承{ rules: [ { path: **/*.{ts,tsx,js,jsx}, rule: Always check for unhandled promise rejections; warn on // eslint-disable without a reason comment. } ] }与配置、架构的关联规则解析是配置系统层级化解析链的一部分解析出的规则正文会经由{{system_rule}}占位符进入 agent prompt详见 配置文档 与 架构文档。ocr review的--rule、--preview以及ocr rules check的完整参数说明见 CLI 参考。排查规则为什么没生效时推荐流程为先ocr rules check path确认命中层与模式再ocr review --preview确认文件是否通过五段式过滤最后对照本文的四层链与 glob 语法核对配置。【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibabas scale. Hybrid architecture code review tool: deterministic pipelines LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考