OpenCodeReview Review Rules 详解四层规则优先级链、文件过滤与规则解析机制【免费下载链接】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本文以 OpenCodeReviewOCR的审查规则Review Rules体系为主题系统讲解规则如何告诉 LLM 每类文件该重点审查什么。你将掌握规则的四层优先级链、规则文件 JSON 格式与 Glob 语法、五道闸门构成的文件过滤算法、内置系统规则的映射关系以及ocr rules check调试工具和四类实战配置方案从而为任意仓库精确定制 AI 代码审查的聚焦范围。为什么需要审查规则在 LLM Agent 做代码审查时最大的难点不是能不能看懂代码而是该关注什么。同一个仓库里一份 MyBatis Mapper XML 关注的是 SQL 注入与标签闭合一个 Go 文件关注的是并发安全与错误包装一个 Solidity 合约关注的是重入漏洞——用同一套通用提示词去审查所有文件必然导致误报和漏报。OCR 用一套Review Rules机制解决这个问题为每个文件路径解析出最匹配的一条规则文本把它作为系统指令注入到 agent 的 prompt 中让模型带着该语言/文件类型专属的检查清单去审查。规则以 JSON 文件形式存放在三层配置中外加随二进制内置的一套系统默认规则。四层优先级链Priority ChainOCR 按四层优先级链解析规则。对每个文件路径依次尝试各层第一个匹配的模式获胜优先级来源路径说明1最高--rule命令行参数用户指定CLI 覆盖一旦提供总是生效2项目配置repoDir/.opencodereview/rule.json按项目定制可以提交进仓库3全局配置~/.opencodereview/rule.json用户级偏好本机所有仓库生效4最低系统默认内嵌system_rules.json覆盖常见语言的内置规则关键行为高层文件不存在时静默跳过不算错误。项目从未添加.opencodereview/rule.json就自然落到全局层 / 系统层。系统层永远存在随二进制内嵌因此任何文件最终都能解析出至少一条规则。从源码看该链由 internal/config/rules/system_rules.go 中的composedResolver实现依次尝试 custom--rule→ project → global 三个ProjectRule层全部未命中才落到被 sniffer 包装的系统层用户规则默认替换系统规则也可通过merge_system_rule字段选择与系统规则合并详见下文。规则文件格式第 13 层项目层与全局层使用统一的 JSON 结构{ 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 匹配到该文件的条目其rule即作为该文件的审查指令发送给模型。规则条目的高级能力源码补充从 internal/config/rules/system_rules.go 的实现看规则条目还有两个文档内未展开的实用细节merge_system_ruleProjectRuleEntry支持merge_system_rule布尔字段对应 JSON 键merge_system_rule。为true时用户规则不再替换系统规则而是将匹配到的系统规则与用户规则拼接成System-Specific RulesMandatory User-Specific RulesMandatory两段合并文本保证内置语言检查清单不丢失。规则文本可引用外部文件rule字段如果是一行无空格、以.md/.txt/.markdown结尾的字符串如team-review-checklist.md会被当作文件引用OCR 会读取其内容作为规则文本。读取有安全限制只允许上述三种扩展名、单文件上限 512 KB、解析符号链接且项目层的相对引用不允许逃逸仓库根目录越界会告警并拒绝相关逻辑见 internal/config/rules/system_rules.go 的readRuleFileSafe。Glob 语法规则匹配基于bmatcuk/doublestar/v4库实现*——匹配除/外的任意字符**——跨目录边界匹配src/**/*.go可覆盖任意深度{a,b,c}——花括号展开*.{ts,tsx,js,jsx}会展开为四个模式依次匹配?——匹配单个字符[abc]——字符类。匹配不区分大小写匹配前文件路径会被转成小写。拿不准时用ocr rules check path确认结果。源码佐证SystemRule.Resolve与FileFilter在匹配前都会对路径strings.ToLower并由自实现的expandBraces先做花括号展开再逐模式调用doublestar.Match实现第一个匹配获胜的语义。文件过滤五道闸门算法规则解析之前OCR 先决定这个文件要不要送审。过滤算法位于 internal/agent/preview.gowhyExcluded方法对每个 diff 依次问五个问题binary——文件是二进制排除ExcludeBinary。user_exclude——路径是否命中用户exclude模式排除ExcludeUserRule。user_include——若用户定义了include路径是否命中命中则立即保留跳过下面第 4、5 道闸门。unsupported_ext——扩展名是否在内置 allowlist 中不在则排除ExcludeExtension。default_path——路径是否命中内置测试文件排除模式**/*_test.go、**/*.test.{js,jsx,ts,tsx}、**/*_spec.rb等命中则排除ExcludeDefaultPath。只有通过全部五道闸门的文件才会发给 LLM。另外deleted状态ExcludeDeleted不是闸门而是在Preview()中单独计算的当文件新路径为/dev/null即被删除时没有新内容可审标记为排除删除文件的路径匹配使用其旧路径。ocr review --preview会在不消耗任何 token的前提下打印这套过滤的结果每个文件是否送审及其排除原因是验证规则配置的首选手段。默认路径排除清单与噪音目录内置排除清单位于 internal/config/allowlist/default_exclude_patterns.json覆盖了各语言常见测试文件模式包括但不限于**/*_test.go**/src/test/java/**/*.java**/src/test/**/*.kt含.kts**/*.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以及**/testdata/**、**/fixtures/**、**/*.generated.*、**/*.pb.go、**/kitex_gen/**/*.go等生成物与测试夹具目录噪音目录vendor/、node_modules/、target/等的过滤发生在更早的 diff 层面见 internal/diff/git.go在逐文件过滤之前就已被剔除。想审查命中了上述测试文件模式的某个文件把它加进用户的include列表即可——include会覆盖default_path这道闸门。每个文件的规则解析过滤决定要审之后OCR 按以下顺序为该文件挑选规则文本尝试--rulecustom层按声明顺序尝试repo/.opencodereview/rule.json按声明顺序尝试~/.opencodereview/rule.json按声明顺序回退到内嵌系统规则层。被解析出的规则体将成为 plan 任务与主任务提示词中的{{system_rule}}占位符参见 Architecture。内置系统规则映射表系统层由内嵌的 internal/config/rules/system_rules.json 定义其path_rule_map以键值对形式记录模式 → 规则文档default_rule指向兜底规则。完整映射如下规则文档均位于 internal/config/rules/rule_docs模式规则文档**/*.propertiesproperties.md —— i18n / 配置文件**/*{mapper,dao}*.xmlmapper_dao_xml.md —— MyBatis 风格 Mapper SQL**/pom.xmlpom_xml.md —— Maven 依赖**/build.gradlebuild_gradle.md —— Gradle 依赖**/package.jsonpackage_json.md —— NPM 依赖 / 脚本**/Cargo.tomlcargo_toml.md —— Rust 清单**/composer.jsoncomposer_json.md —— Composer 依赖、autoloading、脚本、插件与包配置**/*.{json,json5}json.md —— 通用 JSON同时命中.json5.github/workflows/**/*.{yaml,yml}github_workflows.md —— GitHub Actions 工作流 YAML.github/**/*.{yaml,yml}github_config.md —— 其他.github配置 YAML**/*.{yaml,yml}yaml.md**/*.javajava.md**/*.gogo.md —— Go 源码**/*.{ftl,ftlh,ftlx}freemarker.md —— FreeMarker 模板SSTI / XSS / 空值处理**/*.{hbs,mustache}handlebars_mustache.md —— Handlebars 与 Mustache 模板**/*.pugpug.md**/*.etsarkts.md —— ArkTS / HarmonyOS**/*.astroastro.md —— Astro 组件与 islands**/*.{ts,js,tsx,jsx,mjs,cjs}ts_js_tsx_jsx.md**/*.{kt,kts}kotlin.md**/*.rsrust.md**/*.{cpp,cc,cxx,hpp,hxx}cpp.md**/*.cc.md**/*.{py,ipynb}python.md —— Python 源码**/*.{php,phtml}php.md —— PHP 源码与模板**/*.protoprotobuf.md —— Protocol Buffers wire 兼容性**/*.popo.md —— gettext 翻译源目录**/*.potpot.md —— gettext 模板文件**/*.{graphql,gql}graphql.md —— GraphQL schema 与操作**/*.prismaprisma.md —— Prisma schema**/*.jljulia.md —— Julia 源码**/*.Rr.md**/*.{tf,hcl,tfvars}terraform.md —— Terraform / HCL**/*.bicepbicep.md —— BicepAzure模板**/*.nixnix.md**/*.{hs,lhs}haskell.md**/*.{nim,nims,nimble}nim.md**/*.swiftswift.md**/*.elmelm.md**/*.{jsonnet,libsonnet}jsonnet.md —— Jsonnet 配置模板与库**/*.zigzig.md**/*.thriftthrift.md —— Apache Thrift IDL wire 兼容性**/*.capnpcapnp.md —— Capn Proto schema wire 兼容性**/*.{ml,mli}、**/*.{re,rei}ocaml.md —— OCaml / ReScript**/*.{v,sv,vh}verilog.md —— Verilog 与 SystemVerilog RTL**/*.{vhd,vhdl}vhdl.md —— VHDL RTL**/*.mmatlab.md或经内容嗅探命中 objc.md**/*.mmobjc.md —— Objective-C 源码**/*.solsolidity.md —— Solidity 智能合约**/*.vyvyper.md —— Vyper 智能合约兜底default.md以 go.md 为例内置规则文档本身就是一份高密度的检查清单强调宁缺毋滥、精确优先聚焦错误包装%w保留错误链、typed nil 接口陷阱、sync.Once失败重试语义、goroutine 泄漏与循环变量捕获区分 Go 1.22 前后语义、锁与共享状态的并发证据等go vet/ Staticcheck /-race覆盖不到的问题——这正是内置多语言规则集的价值所在。对.m文件的内容嗅探.m同时被 MATLAB 和 Objective-C 使用。OCR 会偷看文件第一个非空行来消歧如果看起来像 Objective-C如#import、implementation、//或/*注释、#if等完整前缀清单见 internal/config/rules/sniffer.go则改用objc.md否则默认matlab.md。内容无法读取时回退到matlab.md。两个值得注意的实现细节嗅探器包装的是系统层而非整个 resolver因此用户层custom / project / global规则永远高于嗅探结果——用户自定义的.m规则不会被内容判断覆盖读取的是 review 目标 ref 上的内容git show ref:path带 5 秒超时即使该 ref 尚未 checkout 也能正确判断。稳定性提示。嗅探启发式可能在 OCR 版本间变化。若你需要确定性的.m路由请为.m路径设置显式的项目级规则——项目规则总是高于系统层。用ocr rules check检查哪条规则生效当规则表现不符合预期时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它构建与ocr review相同的rules.NewResolver调用ResolveDetail获取SourceCustom (--rule)/Project (.opencodereview/rule.json)/Global (~/.opencodereview/rule.json)/System built-in与命中的Pattern后格式化输出若规则由内容嗅探选出如.m命中 ObjC还会打印一行Note: rule selected by file content说明。对应集成测试见 cmd/opencodereview/rules_check_test.go。实战配方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/之外的文件仍走常规的扩展名 / 默认路径检查——include是绕过开关不是白名单。单次 PR 覆盖ocr review --rule ./.review-rules-only-for-this-pr.json同时绕过项目层和全局层——适合某个 PR 需要完全不同的审查清单如仅做安全审查的场景。相关 CLI 参数详见 CLI Reference。全局个人偏好放在~/.opencodereview/rule.json让本机所有仓库继承{ rules: [ { path: **/*.{ts,tsx,js,jsx}, rule: Always check for unhandled promise rejections; warn on // eslint-disable without a reason comment. } ] }注意事项Monorepo 场景项目规则文件只从 git 顶层目录读取repoRoot/.opencodereview/rule.json子目录下的局部rule.json不会被加载需要共享规则时放在仓库根目录或使用--rule显式指定。规则可复现性解析器会把各层规则文本含merge_system_rule与嗅探的 ObjC 规则以确定性顺序折叠进运行 manifest 的rule_config_sha256哈希见CanonicalConfig确保同一次运行与历史运行之间的规则配置可比对、可审计。项目规则安全边界项目层规则文件若通过符号链接指向仓库外、或引用的规则文件逃逸仓库根目录OCR 会拒绝读取并打印 WARNING避免不可信的仓库配置影响本机其他目录。延伸阅读CLI Reference ——ocr review --rule、--preview与ocr rules check的完整用法Configuration —— 配置文件位置与分层解析链Architecture —— 解析出的规则如何进入 agent 提示词【免费下载链接】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），仅供参考