关于大规模自定义规则文件批量审查问题

[zwlpwl]

问题描述
我们团队正在将内部积累的约上百条代码审查规则集成到 OCR 工具的自定义规则体系中。为了保证审查质量和规则的可维护性，我们计划将规则按类别（如安全、性能、代码规范等）拆分存放至多个自定义规则文件中，每个文件控制在 90 行以内。

当前遇到的问题
经过测试，多个规则文件似乎无法在同一轮审查指令下全部生效。我们理解 OCR 目前的规则匹配机制是“按声明顺序评估，第一个匹配的 path glob 获胜”，这导致多个用户规则无法同时应用于同一个文件。

期望达成的目标

1. 保证每条规则的审查质量，不因规则数量多而降低审查深度
2. Token 消耗成本不是限制因素，可以接受较高的 token 使用量
3. 希望能够在一轮审查中覆盖所有自定义规则，或找到高效的替代方案

具体问题

1. 在现有 OCR 机制下，若要保证每个规则的审查质量且不限制 token 消耗，最佳实践是什么？
2. OCR 后续是否会支持自动批量使用多个用户自定义规则文件进行审查？
3. 是否有其他更好的方案来解决规则过多的问题？

[lizhengfeng101]

Hi @zwlpwl，感谢提问。

你对匹配机制的理解是准确的 — OCR 当前的规则解析是 "first match wins"：对每个文件，在 rules 数组中按声明顺序找到第一个 glob 匹配的 entry 后即停止，不会继续应用其它 entry。这意味着如果你有多个规则文件（或多个 entry）的 path glob 都能匹配同一文件，只有第一个会生效。

当前版本下的可行方案

方案一：合并 rule 文本，按 path 归类

将所有适用于同一 path glob 的规则合并到同一个 entry 的 rule 字段中（或引用一个较长的 .md 文件）。rule 字段支持引用文件路径 — 只要值是以 .md / .txt / .markdown 结尾的单行路径，OCR 会自动读取文件内容作为规则文本（上限 512KB）。

{
  "rules": [
    {
      "path": "src/**/*.java",
      "rule": ".opencodereview/rules/java-all.md"
    }
  ]
}

你可以在 java-all.md 中用 markdown 章节组织多条规则（安全、性能、规范等）。这样一个文件匹配一个完整的规则集，不存在冲突。

注意：规则条数越多，模型在单次审查中需要逐条检查的维度越多，对每条规则的关注度可能被稀释。如果你对审查深度有严格要求且 token 不受限，建议单个规则文件中的规则条数控制在合理范围内（经验上 10-15 条以内效果较稳定），超出的可考虑方案二分轮审查。

方案二：多轮审查 + --rule 覆盖

对同一组变更执行多次 ocr review，每次用 --rule 指定不同的规则文件：

ocr review --rule .opencodereview/rules/security.json
ocr review --rule .opencodereview/rules/performance.json
ocr review --rule .opencodereview/rules/convention.json

--rule 是最高优先级（layer 1），会完全覆盖 project/global/system 层。每轮只关注一个维度，保证审查深度不被稀释。可通过 CI 脚本并行执行。

方案三：Delegation Mode 集成

如果你使用 Claude Code / Cursor 等 AI coding agent，可以利用 Delegation Mode。流程是：

1. ocr delegate preview 获取待审文件列表
2. ocr delegate rule <paths> 获取规则分组
3. 在 host agent 侧自行为每个文件注入多维度规则并审查

这种模式下规则的组合逻辑完全由你的 host agent 控制，不受 OCR "first match wins" 约束。

补充：merge_system_rule 选项

如果你希望自定义规则和系统内置规则同时生效（而非覆盖），可以在 entry 中设置 "merge_system_rule": true，OCR 会将系统规则和用户规则拼接后一起发给模型。

关于规则拆分的设计意图

"first match wins" 的 path glob 匹配并非技术限制，而是一种设计倡导 — 鼓励用户按作用域拆分规则，让每个文件只命中与其真正相关的规则集，从而控制单次审查的规则条数，避免模型注意力稀释。

框架本身不限制你在一个 entry 中放置大量规则（可以引用一个很长的 .md 文件），但实践中建议回过头审视：你的上百条规则是否真的全部适用于每一个文件？通常安全规则主要针对 API/网络层、性能规则主要针对数据处理层、规范规则可按语言拆分 — 合理利用 path glob 做作用域划分，自然可以把单文件命中的规则条数控制在有效范围内。

[zwlpwl]

多谢解答

[hwbest]

补充一个我们做过的尝试,供有同样想法的同学参考,避免重复走弯路:

讨论 #633 里提出的"把 rule 字段从单字符串扩展为 string | []string(数组按序合并多份用户 md)"——我按这个方向实现了,并提了 issue #1177 + PR #1178。维护者 @lizhengfeng101 已明确因产品方向不予内置(PR 未合并、issue 关闭为 not_planned),实现本身被肯定。

核心理由(完整版见 #1177):配置层只做选择不做构造;多文件共享引用会带来高 fan-in 且无归因、无回归基线,改一处 common.md 会静默影响所有消费方;外部构建期生成一个已提交的"有效规则文件"在可观测性上严格更优(改动以 diff 形式可 review)。

维护者给出的出路:① 作为非内置模式放进 examples/rule_composition/(需先对齐范围);② 等 OCR 具备 comment→rule 归因后再重新考虑内置。

所以短期内不必再朝"内置数组形态"方向提 PR 了。上面 @lizhengfeng101 给的三个 workaround 目前仍是可行路径,其中方案 1(合并进单个 .md)配合构建期脚本生成,基本就是维护者推荐的"外部生成"思路。