1. 为什么我要把代码审查这件事交给一条规则链
代码审查这件事，做过团队协作的人都有体会：最怕的不是没人审，而是审的人标准不一致。张三觉得命名不规范要打回，李四觉得能跑就行直接合并，同一个仓库里两套标准来回拉扯，最后代码风格全靠谁嗓门大。更麻烦的是，人总有状态起伏，今天心情好给你挑三个小问题，明天赶进度直接点通过，这种不确定性对代码质量的伤害比不审查还大。
我最初接触 open-code-review 这个工具，动机很朴素：把那些"机器能判断的、重复的、不需要人类智慧"的审查点交给它，让人的精力集中在架构设计和业务逻辑上。用下来最大的感受是，它真正有价值的地方不在于"AI 帮你审代码"这个噱头，而在于四层规则链这个设计——它把审查这件事拆成了从语法到语义、从局部到全局的递进结构，每一层解决不同粒度的问题，而不是一股脑丢给大模型让它自由发挥。
这篇内容适合三类人看：一是团队里负责搭建代码质量体系的人，想知道这套工具到底能不能落地；二是被各种审查规则折磨过的开发者，想搞清楚规则是怎么组织起来的；三是想自己写自定义规则的人，我会把规则格式和实测踩过的坑都摊开讲。全文基于我自己的部署和调优经验，涉及参数和配置的地方我会说明为什么这么选，而不是甩一份官方文档让你自己猜。
先说结论：这套东西不是装上就能用的"开箱即灵"，它的价值上限取决于你规则链设计得好不好。装完之后如果只是跑默认规则，你会发现它报的东西要么太啰嗦要么抓不住重点，真正让它变得好用，靠的是后面几节要讲的规则分层和自定义规则编写。
2. 安装部署：从零到跑通第一条审查
2.1 环境准备里最容易被忽略的两个前提
open-code-review 的安装本身不复杂，但我在两台机器上装的时候都卡在了同一个地方，值得单独拎出来说。第一个前提是代码仓库的访问权限。这个工具需要读取仓库内容才能做审查，如果你用的是私有仓库，光配好工具本身没用，还得确保运行它的账号有对应的读取权限。我见过有人装完发现一直报"无法获取文件列表"，排查半天以为是工具 bug，其实是权限没配。
第二个前提是运行环境的资源配额。因为审查过程涉及模型推理，内存占用比普通 CLI 工具高不少。我建议至少留出 4GB 可用内存，如果仓库文件多、单次审查范围大，8GB 会更稳。这一点官方文档往往一笔带过，但实际跑起来内存不够导致的进程被杀是最常见的"玄学问题"。
安装步骤大致是这样：
# 拉取工具（以常见的包管理方式为例） npm install -g open-code-review # 或者从源码构建 git clone <repo-url> cd open-code-review npm install npm run build # 验证安装 ocr --version注意：不同版本的命令入口名可能不一样，有的版本是
ocr，有的版本是open-code-review。装完先用--help确认一下实际命令名，别照着旧教程硬敲。
2.2 初始化配置：别急着改默认值
装完之后第一件事是初始化配置。我的建议是先跑一遍默认配置，观察它的行为，再动手改。很多人一上来就把各种参数调到最严，结果满屏报错，反而不知道哪些是真正有价值的信号。
初始化一般会生成一个配置文件，形如.ocrrc或ocr.config.json，里面包含模型选择、规则链开关、忽略路径等。我实测下来，第一次配置只需要关注三件事：
- 审查范围：默认可能扫全仓库，大仓库会非常慢，建议先限定到具体目录或文件类型。
- 模型端点：如果用的是本地模型或自建服务，这里要填对地址，填错了会一直超时。
- 输出格式：默认可能是纯文本，团队协作建议改成结构化输出（如 JSON），方便接入 CI。
{ "review": { "include": ["src/**/*.ts", "src/**/*.js"], "exclude": ["**/node_modules/**", "**/dist/**", "**/*.test.ts"] }, "model": { "endpoint": "http://localhost:11434", "timeout": 60000 }, "output": { "format": "json" } }这里exclude里排除测试文件是我个人的习惯，因为测试代码的审查标准和业务代码不一样，混在一起会让规则链的判断变得混乱。这个取舍后面讲规则链的时候还会展开。
2.3 跑通第一条审查：用最小样本验证链路
配置好之后，别直接对整个项目跑。找一个只有几十行的单文件先验证整条链路通不通。我一般会新建一个故意写了几个典型问题的文件，比如变量命名混乱、有个明显的空指针风险、函数太长，然后对它跑一次审查。
ocr review --file ./test-sample.ts如果这一步能正常输出结果，说明安装、配置、模型调用这条链路是通的。如果报错，按这个顺序排查：先看是不是权限问题（读不到文件），再看是不是模型端点不通（超时或连接拒绝），最后看是不是规则配置语法错误（解析失败）。这个排查顺序很重要，因为这三类错误的表象有时候很像，都是"没输出"或"报错退出"，但根因完全不同。
我第一次装的时候就是卡在模型端点上，工具报的是"审查失败"，看起来像规则问题，实际是端点地址写错了一个端口号。所以先验证链路，再调规则，这个顺序能帮你省下大量时间。
3. 四层规则链：这套工具真正的骨架
3.1 四层分别管什么：从字符到语义的递进
open-code-review 最核心的设计就是四层规则链。我把它理解成一道筛子，从粗到细、从快到慢地过滤问题。这四层大致是：
| 层级 | 关注点 | 典型问题 | 执行成本 |
|---|---|---|---|
| 第一层 | 词法与格式 | 命名规范、行长度、缩进、尾随空格 | 极低 |
| 第二层 | 语法与结构 | 未使用变量、死代码、复杂度超标 | 低 |
| 第三层 | 语义与逻辑 | 空指针风险、边界条件、资源泄漏 | 中 |
| 第四层 | 上下文与意图 | 与需求不符、架构违规、跨文件影响 | 高 |
这个分层的好处是成本可控。第一二层基本是确定性的静态检查，跑得飞快，可以在每次提交时都跑；第三四层涉及模型推理，慢且贵，适合在合并前或定时任务里跑。如果所有检查都塞进一层，要么慢得没法用，要么为了速度牺牲深度。
我见过有人抱怨"这工具太慢"，一问才知道他把四层全开在 pre-commit 钩子里，每次提交都要等模型推理。正确的做法是分层触发：提交时只跑一二层，PR 合并前跑三四层。这个策略调整之后，体验完全不一样。
3.2 为什么规则要分层而不是一锅炖
这里有个反直觉的点：把规则分层，不是为了分类好看，而是为了控制误报的传播。假设你把所有规则混在一起，一个格式问题（比如某行超长）和语义问题（比如潜在空指针）会同时出现在报告里，开发者看到一堆混杂的信息，很难判断优先级，久而久之就全部忽略了。
分层之后，你可以给每层设置不同的处理策略。第一层的问题可以自动修复或仅提示，第二层的问题要求提交前解决，第三层的问题进入人工复核队列，第四层的问题触发架构评审。这样每一层的输出都有明确的去向，而不是堆成一坨。
我在实际项目里给第一层配了自动修复，比如格式化、去尾随空格这类，工具直接改掉，开发者根本不用管。第二层做成警告，不阻塞提交但记录在案。第三层和第四层才真正需要人看。这套策略跑下来，团队对审查结果的接受度明显提高，因为大部分噪音在第一二层就被消化掉了。
3.3 层与层之间的依赖关系
四层不是完全独立的，它们之间有依赖。第三层的语义分析需要第二层先解析出正确的语法树，第四层的上下文判断又依赖第三层已经过滤掉明显的逻辑错误。如果第二层因为语法错误没能正确解析，第三层的结果就不可信。
这个依赖关系带来一个实操上的注意点：当代码本身有语法错误时，不要指望三四层给出有意义的结论。我遇到过有人拿一段编译不过的代码去跑审查，然后质疑工具"怎么没发现我的逻辑问题"——语法都没过，后面的层根本没法正常工作。所以正确的用法是，先保证代码能通过编译，再让工具做深度审查。
另外，层与层之间的规则是可以互相引用的。比如第四层的一条规则可以调用第三层已经计算出的"函数复杂度"指标，避免重复计算。这个机制在写自定义规则的时候很有用，后面会讲。
4. 自定义规则：格式、写法与调试
4.1 规则文件的基本结构
自定义规则是这套工具从"能用"到"好用"的关键。默认规则覆盖的是通用问题，但每个团队都有自己的约定，比如"禁止在业务层直接调用数据库"、"所有对外接口必须有超时设置"，这些默认规则管不到，得自己写。
一条规则的基本结构通常包含几个部分：匹配条件、判断逻辑、严重级别、提示信息。我用一个实际例子来说明，假设我们要禁止在代码里出现console.log：
{ "id": "no-console-log", "layer": 1, "severity": "warning", "match": { "type": "call_expression", "callee": "console.log" }, "message": "禁止提交 console.log，请使用统一的日志组件", "fix": "remove" }这里layer指定它属于第一层，severity是警告级别，match定义了匹配什么，message是给人看的提示，fix表示可以自动移除。这个结构看起来简单，但每个字段的选择都有讲究。
4.2 匹配条件的写法：从简单到复杂
匹配条件是规则里最需要花心思的部分。最简单的匹配是按文本或按语法节点类型，但实际需求往往更复杂。我总结了几种常用的匹配模式：
- 按节点类型匹配：比如匹配所有函数调用、所有变量声明。适合做通用性检查。
- 按名称模式匹配：比如匹配所有以
_开头的变量，用来检查私有约定。 - 按上下文匹配：比如"在 try 块之外的 await"，这类需要结合父节点判断。
- 组合条件：用 and/or 组合多个条件，比如"是函数调用 且 函数名在禁用列表里"。
{ "id": "no-direct-db-in-controller", "layer": 4, "severity": "error", "match": { "and": [ { "type": "call_expression", "callee": "db.query" }, { "ancestor": { "type": "class_declaration", "name_suffix": "Controller" } } ] }, "message": "Controller 层禁止直接访问数据库，请通过 Service 层" }这条规则就是典型的上下文匹配，它不只看调用本身，还看这个调用出现在哪个类里。这种规则用纯文本匹配是做不出来的，必须依赖语法树。
4.3 调试自定义规则：一个笨但有效的办法
写自定义规则最容易踩的坑是规则写完了不知道为什么不生效。可能是匹配条件写错了，可能是层级设错了，也可能是被更高优先级的规则覆盖了。我调试规则的办法很笨但很有效：先写一条必然命中的规则，确认链路通了，再逐步加条件。
具体做法是，先写一条匹配所有函数调用的规则，跑一遍看有没有输出。如果有，说明规则加载和匹配机制是通的；然后逐步加上你的具体条件，每加一个条件跑一次，看输出是否按预期收窄。这样一旦某一步输出突然变空，你就知道是哪个条件写错了。
提示：调试规则时把
severity临时设成最高级别，避免被其他规则的去重逻辑吞掉。我遇到过规则明明命中了，但因为和另一条规则报的是同一个位置，被合并显示，导致我以为它没生效。
另外，规则文件里的语法错误往往不会给出很明确的报错，可能只是静默跳过。所以写完规则后，建议用工具自带的校验命令（如果有的话）先检查一遍语法，别直接跑审查。
5. 实测避坑：那些文档不会告诉你的问题
5.1 误报的三种典型来源
用了一段时间之后，我统计了一下误报的来源，大致分三类，每一类的处理方式不一样。
第一类是规则本身太宽泛。比如一条"禁止使用 any 类型"的规则，在 TypeScript 项目里会命中大量合理的场景，比如处理第三方库返回的不确定类型。这种误报要靠细化规则解决，比如加上"排除类型定义文件"或"排除测试文件"。
第二类是上下文理解不足。模型在判断语义问题时，如果看不到足够的上下文，容易把正常代码判成问题。比如一个函数看起来有资源泄漏风险，但实际上调用方保证了释放。这类误报要靠扩大上下文窗口或调整规则层级来解决。
第三类是规则之间冲突。两条规则对同一段代码给出相反的建议，这种最让人头疼。我遇到过一次，一条规则要求"函数必须显式返回类型"，另一条规则要求"简单函数省略冗余类型标注"，两条同时命中一个函数，报告里自相矛盾。解决办法是给规则设置优先级，冲突时高优先级覆盖低优先级。
| 误报类型 | 根因 | 处理方式 |
|---|---|---|
| 规则太宽泛 | 匹配条件不够精确 | 细化匹配、增加排除项 |
| 上下文不足 | 模型可见范围有限 | 扩大上下文、调整层级 |
| 规则冲突 | 优先级未定义 | 设置优先级、合并规则 |
5.2 性能调优：让审查跑得快一点
审查慢是这类工具的通病，但慢的原因不一样，优化手段也不一样。我实测下来，影响速度的主要有三个因素：审查范围、模型推理量、规则数量。
审查范围是最容易优化的。默认配置可能扫全仓库，但实际你只关心改动的文件。把审查范围限定到 diff 涉及的文件，速度能提升一个数量级。这个改动在 CI 场景下尤其重要，因为每次提交都扫全仓库既慢又浪费。
模型推理量取决于第三四层开了多少规则。我的做法是把确定性的检查尽量下沉到一二层，让模型只处理真正需要语义理解的问题。比如"函数是否过长"这种完全可以用静态分析算出来，没必要让模型去判断。
规则数量本身影响不大，但如果规则之间有重复计算，就会浪费。前面提到的层间引用机制就是用来避免重复计算的，写规则时注意复用已有的计算结果。
5.3 与 CI 集成的几个细节
把 open-code-review 接进 CI 是它发挥价值的主要场景，但集成时有几个细节容易出问题。
首先是退出码的处理。工具在发现问题时返回什么退出码，直接决定了 CI 是失败还是继续。如果所有问题都返回非零退出码，那 CI 会频繁失败，团队很快就会把这条流水线关掉。我的建议是分级处理：error 级别返回非零，warning 级别返回零但输出报告。
其次是报告的存储和展示。CI 里跑出来的报告如果只打印在日志里，基本没人看。最好把结构化报告存成产物，或者推送到团队的协作工具里。我一般会把 JSON 报告存成 artifact，然后在 PR 里贴一个摘要。
最后是缓存。模型推理的结果可以缓存，同一段代码没变就不用重复审。这个优化在大仓库里效果很明显，但要注意缓存的失效策略，代码变了缓存必须失效，否则会漏报。
# CI 配置片段示例 - name: Run code review run: | ocr review --diff-only --output report.json continue-on-error: true - name: Upload report uses: actions/upload-artifact@v3 with: name: review-report path: report.json这里--diff-only是关键，只审改动的部分，continue-on-error保证审查失败不阻塞后续步骤，报告单独上传。这套配置跑下来，既有了审查能力，又不会因为审查本身的问题卡住整个流程。
6. 规则链设计的个人经验
6.1 从"能报问题"到"报对问题"的转变
刚开始用的时候，我的目标很朴素：能报出问题就行。跑了一段时间发现，报得多不等于报得对，一堆低价值的问题反而会淹没真正重要的信号。这个转变的关键是给规则分级，并且让分级和团队的实际关注点对齐。
我的做法是，先收集一段时间内所有报出的问题，人工标注哪些是真正有价值的、哪些是噪音，然后反推规则该怎么调。这个过程大概持续了两三周，之后规则链的准确率明显提升。这个投入是值得的，因为规则链一旦调好，后面就是持续受益。
6.2 规则不是越多越好
有个常见的误区是规则越多越严格越好。我一开始也是这么想的，恨不得把所有能想到的检查都加上。结果就是报告长得没人看，开发者直接忽略。后来我砍掉了将近一半的规则，只保留真正影响代码质量和团队协作的那些，效果反而更好。
判断一条规则该不该留，我的标准是：它报出的问题，是否值得开发者停下来处理。如果一个问题即使存在也不影响功能、不影响维护、不影响协作，那这条规则就是噪音。规则的价值在于精准，不在于数量。
6.3 让规则链随项目演进
规则链不是一次配好就一劳永逸的。项目在变，团队在变，规则链也得跟着变。我一般每个季度回顾一次规则链，看看哪些规则命中率极低（可能已经过时）、哪些规则误报率很高（可能需要调整）、有没有新的团队约定需要加进去。
这个回顾过程不需要很正式，就是拉一下这段时间的审查报告，看看数据。命中率低的规则考虑删掉，误报率高的规则考虑细化，新出现的代码模式考虑加规则。保持规则链和项目实际状态同步，它才能持续产生价值。
7. 写在最后的一点体会
这套工具我用下来，最大的感受是它把"代码审查"这件事从依赖个人经验，变成了可以沉淀和复用的规则资产。四层规则链的设计让不同粒度的检查各归其位，自定义规则让团队的约定能够固化下来，而实测中踩过的那些坑，本质上都是在提醒我：工具是死的，怎么用它才是活的。
如果你正准备引入这套东西，我的建议是别追求一步到位。先把链路跑通，用默认规则观察一段时间，然后根据实际报出的问题逐步调整。规则链的调优是个持续的过程，急不来。真正让它产生价值的，不是装了多少规则，而是这些规则是否真的贴合你团队的实际需求。
另外提醒一句，任何自动化审查工具都替代不了人的判断。它的定位是帮人过滤掉重复的、机械的问题，把人的精力释放到真正需要思考的地方。把它当成助手而不是裁判，用起来会舒服很多。
