企业官网建设流程全解析

最近线上出了一个让我印象特别深的故障：一个灰度了半小时的后台服务突然开始疯狂弹“强制更新”的窗，用户怎么点都关不掉。事后复盘根本原因，是一个布尔判断被写反了，if (forceUpdate)变成了if (!forceUpdate)。代码评审的时候，好几个人的眼睛都扫过那一行，但没有一个人停下来问一句“这个条件是不是反了”。这件事之后我花了整整两周，把一个开源自托管的代码审查工具 open-code-review 接进了团队的主仓库，让机器在合入前先跑一轮增量扫描。这篇文章就是那段时间的完整记录：这个工具解决了什么问题、怎么部署、内部规则引擎怎么工作、接入 CI/CD 时踩过哪些坑，以及团队实际用了三个月之后的一些真实数据和反馈。

如果你正在为一个“人工 review 经常漏问题”的仓库发愁，或者想知道自托管代码审查机器人和现有平台工具（比如 SonarQube、CodeClimate、GitLab 自带 SAST）比到底值不值得折腾，这篇文章应该能给你一些参考。

1. 我为什么折腾 open-code-review：从一次漏审事故说起

1.1 事故复盘：人肉 review 的局限

那次故障里最讽刺的一点是，提交这次变更的人并不是新手，负责 review 的也是业务熟手。改动涉及一个老模块的重构，所有人的注意力都在“老逻辑是否被正确平移”上，而那个!就这样混了过去。测试用例恰好没覆盖这个分支——它依赖的是登录态被清除后的异常分支，不是正常流程。

复盘时我们把问题归成了三类：第一，人的注意力是有限的，当 review 的重点被某个大文件或复杂逻辑占据时，那些“语义正确但缺少一个感叹号”的经典型错误基本会被忽略；第二，代码评审通常在 MR 里一次性进行，面对几十个文件、几千行 diff，没有人能做到逐行保持同等注意力；第三，很多基础问题（调试语句、不安全的函数调用、明显违反团队规范的写法）实际上可以靠脚本在几分钟内发现，让机器去承担这部分，人才能把精力放在真正的架构和业务问题上。

所以我当时很明确，我需要一个能“自动看一眼 changed lines”的工具，而不是再组织一轮人工专项检查。注意，是只看变更行——全量扫描的老问题在于噪音太大，旧代码的历史遗留问题会淹没新变更本身想暴露的信息。

1.2 open-code-review 的定位：不是替代人，而是兜底

我在开源社区翻了不少项目，最终决定深度试用的就是 open-code-review。它的定位很清晰：一个自托管、增量式的代码审查机器人。它会监听代码平台的合并请求事件，拉取本次变更的 diff，针对变更行运行一组可配置的分析规则，然后把结果以评论或建议的形式回传到仓库。

这里强调“增量”两个字，是因为它和传统静态分析工具的设计哲学完全不同。传统工具倾向于全量扫描代码库，把所有符合规则的问题都列出来。这类工具在企业里落地时，往往会被海量的存量问题淹没，团队根本分不清哪些是本次新增的、哪些是老账。open-code-review 默认只对“这次改动涉及的代码”做审查，把审查的上下文严格限制在合并请求内，这就让机器给开发者的提醒有了直接可执行性——开发者不需要面对一座历史问题堆成的山，只需要处理当前这个 MR 里被指标出的问题。

当然，它不是要替代人。它解决的是“人肉 review 的注意力瓶颈”，把基础的、机械的、规则明确的检查从人那里接走，让人只关注设计、逻辑、边界和可维护性这些机器不容易判断的维度。

1.3 和常见方案的对比：为什么不是 SonarQube 或 CodeClimate

很多团队一提到代码质量工具，第一反应就是 SonarQube 或者 CodeClimate。我在这块的选择过程可能对你有参考价值。

SonarQube 功能确实全面，有质量门禁、历史趋势、丰富的插件生态，但对一个小团队来说它太重了。你不但要维护一个独立的服务器、数据库实例，还要关注索引更新、版本升级，配置门槛也高。而且它默认是全量分析模式，虽然可以通过 Quality Profiles 和增量模式优化，但整个概念体系（质量域、技术债、质量门槛）在团队初期共识不足时很容易变成摆设。

CodeClimate 是 SaaS，部署确实省事，但它意味着把代码上传到第三方服务平台，很多公司这一关就过不了，涉及数据合规问题。另外它是按仓库订阅收费的，仓库一多费用会上去。

GitLab 原生自带的 SAST 也在我的考虑范围里，但它的规则覆盖偏向安全类漏洞，对于团队自定义规范（比如“禁止在业务代码里 import 某个坑爹的工具类”“接口层不允许直接返回内部实体”）支持起来要写 GitLab 自定义规则，心智负担反而更大。

我把它们整理成了一个简单的选型对比表：

简单来说，如果你要的是一个从“组织级质量保障体系”角度出发的东西，SonarQube 依然是那个最完整的答案。但如果你和我一样，只是想让每次 MR 在人工评审之前先被机器把明显的硬伤过滤一遍，那 open-code-review 这种轻量工具明显更能快速见效。

2. 部署实录：open-code-review 的最小可用配置

2.1 部署前的依赖与资源估算

我先说一下我们最终跑起来的部署环境，这个组合经过了几个版本迭代，应该是比较稳妥的基线。

服务器方面，2 核 4G 内存的 Linux 云主机就够了。open-code-review 本身并不吃资源，它内部由一个控制服务（core）、若干工作进程（worker）和队列存储组成。控制服务负责接收代码平台的 webhook 事件、维护任务状态；worker 才是真正跑静态分析和自定义规则的地方。这种设计有个好处：webhook 回调只负责“把任务丢进队列”，真正耗时的扫描在 worker 里异步完成，不会因为分析时间过长导致代码平台那边的 webhook 请求超时重试。

环境依赖就三样：Docker 和 Docker Compose（我们用 v2 语法），一个能运行 Docker 的 Linux 环境，以及代码平台的 API token。支持的代码平台，当前稳定支持 GitLab CE/EE 和 Gitea，GitHub 需要额外装一个桥接插件。我们主仓库用的是 GitLab，下面所有操作都基于 GitLab 15 以上的版本。

2.2 用 Docker Compose 快速启动

官方仓库里带了完整的 compose 模板，我把它裁剪成了最小可用版本：

version: "3.8" services: core: image: opencode/review-core:0.4.2 restart: unless-stopped environment: OC_WEBHOOK_TOKEN: "your-webhook-secret" OC_GITLAB_URL: "https://gitlab.example.com" OC_GITLAB_TOKEN: "glpat-xxxxxxxx" OC_QUEUE_DSN: "redis://redis:6379/0" OC_DB_DSN: "postgresql://review:review@db:5432/review" depends_on: - redis - db ports: - "8080:8080" worker: image: opencode/review-worker:0.4.2 restart: unless-stopped environment: OC_QUEUE_DSN: "redis://redis:6379/0" OC_DB_DSN: "postgresql://review:review@db:5432/review" OC_GITLAB_TOKEN: "glpat-xxxxxxxx" depends_on: - core redis: image: redis:7-alpine restart: unless-stopped db: image: postgres:15-alpine restart: unless-stopped environment: POSTGRES_USER: review POSTGRES_PASSWORD: review POSTGRES_DB: review volumes: - pgdata:/var/lib/postgresql/data volumes: pgdata:

需要注意几个环境变量：OC_WEBHOOK_TOKEN是用来验证请求来源的，代码平台侧也要填同一个值；OC_GITLAB_TOKEN是服务用来调用 GitLab API 的凭证，权限至少需要api和read_repository。如果你有多个仓库但不想给过大权限，建议后续按仓库分 Token，这一条在第四节踩坑记录里会展开。

部署完后我先做了一次冒烟测试：docker compose up -d，然后看两个服务的日志。正常的启动日志里 core 会打印出它在监听哪个路径，默认是/hooks/gitlab，同时会提示当前加载了多少条内置规则。如果在这一步发现“can't connect to redis”之类的报错，先检查容器网络是否正常，再检查 compose 里的服务名和 DSN 是否一致，这类基础问题占启动失败的大头。

2.3 首次接入 GitLab：webhook 与回调配置

在 GitLab 侧添加 webhook 的路径是：进入项目仓库后，找到 Settings —— Webhooks，新建一个 webhook。URL 填http://你的服务器地址:8080/hooks/gitlab，Secret Token 填 compose 里设置的同一个 secret，事件勾选 “Merge request events”，如果有需要也可以勾选 “Push events” 来支持提交时触发的轻量检查。

然后到 open-code-review 的配置文件里确认仓库映射关系。它的配置文件是一个 YAML 文件（review.yml），我截取关键片段：

webhook: server_url: "http://xxx:8080" token: "your-webhook-secret" platform: gitlab: base_url: "https://gitlab.example.com" token: "glpat-xxxxxxxx" rules: level_map: error: "block" warning: "comment" custom_paths: - "./rules/custom/*.py" reports: strategy: "line" include_summary: true

这里rules.level_map决定严重级别和合并行为的关系，error级别可以映射成“阻塞合并请求”，warning级别默认只发表评论不阻塞。建议刚开始落地时不要接阻塞门禁，让工具先“评论”跑一两周，等规则稳定、团队对它的输出建立了信任之后，再把error级别提升为真正的门禁。上来就当裁判，容易被抵触。

配置完毕后的验证流程也很简单。我新建了一个测试分支，故意在代码里加了一行会触发内置规则的问题，比如在 Python 代码里写一个print("debug")，然后提交并创建了一个 MR。十几秒后回到 MR 页面，就能看到 open-code-review 的评论，精确指出test_demo.py第几行的调试输出需要移除。这就说明从 webhook 到 worker 再到回传评论的整条链路是通的。

2.4 部署中最容易忽略的细节

有两个细节特别值得提，因为我在第一次部署时都栽过。

一个是线上环境如果走 HTTP 而非 HTTPS，GitLab 默认可能不允许向非加密地址发送 webhook 请求。GitLab 的 webhook 设置页会有一个“允许来自本地网络的请求”之类的选项，如果你的服务部署在内网，需要在 GitLab 的 Admin 区域里把“允许向本地网络发送请求”打开，否则 webhook 测试按钮会一直报错。另一个是防火墙只放行了 8080 端口，但 worker 访问代码平台 API 是出网连接，如果服务器在防火墙严格的内网里，出网规则漏掉.gitlab.example.com的域名，就会表现为“评论没回来”，但 core 日志里任务已经标记成功了。这种网络层面的问题在日志里往往不明显，需要顺着链路一段段查。

3. 规则引擎是怎么工作的：从 AST 到自定义检查

3.1 一次审查任务的完整数据流

搞懂规则引擎之前，先看一个审查任务在 open-code-review 内部是怎么流转的。

当开发者创建一个 MR，GitLab 会向 open-code-review 的/hooks/gitlab发送一个 JSON 事件。core 服务校验 Webhook 签名无误后，把任务信息（仓库地址、源分支、目标分支、合并请求编号）写进队列，并立即给 GitLab 返回 200，让 webhook 调用快速结束。worker 从队列里取到任务后，开始真正的干活：它先调用 GitLab API 获取该 MR 的 changes 列表，拿到所有变更文件以及每个文件的 diff；然后逐文件计算“变更行号集合”，这个集合是后续所有规则运行的输入。

这一步“变更行号集合”是整个增量设计的关键。比如一个文件总共 1000 行，这次只改了第 100 行和第 500 行，那 open-code-review 只会把第 100 行和第 500 行对应的代码片段交给规则执行，而不是整个文件。在底层它会把 diff 的每个 hunk 转化成一个带行号的语法片段，无论规则做的是文本匹配、AST 遍历还是数据流分析，都只作用于这些片段。

规则全部执行完毕后，worker 会汇总所有分析器的返回结果，按rules.level_map的配置分派去向。error级别如果映射为block，会通过 GitLab API 的“批准/拒绝”能力或 merge request 讨论接口，在 MR 上留下一个不可通过的检查项；warning级别则直接发布为评论，或按代码平台的能力发布为行内评论。最终开发者看到的是一组“精确到行”的机器意见。

3.2 内置规则都覆盖了哪些危险模式

open-code-review 的内置规则集合算不上大，但覆盖面很讲究，我大致分成了几类：

第一类是避免低级错误的“危险模式规则”，例如在 Python 代码里检测print调试残留、在 JavaScript/TypeScript 里检测console.log残留、检测被注释掉的代码块是否夹带明显异常逻辑。这一类规则看起来简单，但实际价值最高，因为我们团队真实的健康度提升恰恰主要来自于这类规则拦截下来的问题。

第二类是资源释放和性能隐患，比如检测数据库连接是否在异常分支里遗漏了关闭，检测循环体内的潜在 N+1 查询模式。这类规则很多是启发式的，单条命中不一定是真问题，它的价值在于给开发者一个“这里值得多看一眼”的提示，触发人的判断而不是替代人的判断。

第三类是团队规范落地的自定义规则前置。内置规则只是脚手架，真正让团队觉得“这个工具是在帮我们干活”的，其实是我们自己写的那十来条自定义规则。这个我会在下一小节展开。

与内置规则配套的还有一个严重级别体系：error、warning、info。error用来表达团队共识中“任何情况下都不该出现”的问题；warning用来表达“应该修但可以不阻塞合并”的问题；info则更接近一个代码风格建议，常见用途是给新成员提示“仓库里的惯用写法是这样”。我的经验是error级规则一定要少、要狠，一旦数量多了误报率就上来，团队就会失去对门禁的信任。

3.3 亲手写一条自定义规则：Python 检查器拆解

自定义规则是 open-code-review 社区插件体系最吸引人的部分。规则本质上是一个 Python 模块，注册到一个 manifest 里，然后在rules.custom_paths中指个路径就能被 worker 加载。

我举一个实际写过的规则例子。团队曾经在某个服务里频繁出现因为time.sleep导致的请求线程阻塞问题，后来达成共识：业务代码里不允许出现time.sleep，必须改用异步等待或消息重试机制。我就把这条共识写成了一条自定义规则。

import ast RULE_ID = "CUSTOM-0001" RULE_NAME = "no-blocking-sleep-in-service" RULE_LEVEL = "error" RULE_MESSAGE = "业务代码中不允许使用 time.sleep，请改用异步等待或重试机制" def check_snippet(snippet, file_path, line_map): problems = [] try: tree = ast.parse(snippet) except SyntaxError: return problems for node in ast.walk(tree): if isinstance(node, ast.Call): func = node.func if isinstance(func, ast.Attribute) and func.attr == "sleep": if isinstance(func.value, ast.Name) and func.value.id == "time": line_num = line_map.get(node.lineno, node.lineno) problems.append({ "line": line_num, "column": node.col_offset, "rule_id": RULE_ID, "level": RULE_LEVEL, "message": RULE_MESSAGE, }) return problems

这个规则在实现上是用 Python 标准库的ast模块做语法分析。它先把 worker 传进来的代码片段解析成语法树，然后用ast.walk遍历每一个节点，寻找time.sleep这种调用模式。找到以后，通过line_map把片段内的相对行号映射回原始文件里的真实行号，最终返回一个 problem 对象，open-code-review 会把它渲染成 MR 里的行内评论。

写自定义规则这件事，最核心的心智模型是：你不必理解整个项目的全局上下文，你只需要精确表达“什么样的代码片段是你不希望在变更里看到的”。AST 方式适合分析“调用关系”和“语法结构”，比如禁止调用某个函数、要求使用某个上下文管理器、检查异常是否被吞掉。如果只是想做关键词匹配，open-code-review 也提供文本分析器的入口，比如检测代码里的 TODO 是否带负责人。但凡是能靠 AST 解决的，我都会用 AST，因为它的误报率显著低于文本匹配。

3.4 规则的增量匹配与行号映射

这里我要专门讲一个很多人容易忽略的机制：行号映射。

worker 拿到的是 diff 而不是整个文件，每个 hunk 里“新文件的第 N 行”和“片段内的第 M 行”存在一个偏移关系。open-code-review 在把片段交给规则执行时，会同时给一个line_map，这个映射的作用就是让自定义规则拿到片段内 AST 节点的本地行号之后，能换算回报告时需要的仓库真实行号。

我第一次写规则时没太在意这件事，结果规则输出的行号永远比真实位置少了几行，因为片段是从函数体中间开始的。后来看了示例规则才明白，返回 problem 时必须做line_map.get(node.lineno, node.lineno)这一层换算，否则行号偏移问题会让人很困惑。这个细节也是我在给团队讲自定义规则时必讲的一个点，因为 90% 的同事第一次都会在这里犯同样的小错误。

4. 接入 CI/CD 的完整踩坑记录

4.1 集成场景：GitLab + Jenkins 流水线

我们团队的 CI 基础设施是 GitLab 加 Jenkins。早期的流程里，代码推上去之后 Jenkins 负责跑单元测试、构建镜像并部署到测试环境，代码评审完全依赖人工。接入 open-code-review 之后，我把它作为一个流水线阶段放了进去：Jenkins 在 MR 事件触发流水线时，先调用 open-code-review 的 API 主动触发一次审查任务，等审查结束后再决定后续阶段是否继续。

为什么不用 webhook 被动触发，而是让 Jenkins 主动调 API？主要原因是团队希望在流水线视图里能看到“代码审查”这个阶段的状态，而不只是去 MR 页面看评论。open-code-review 对外暴露了一个 REST API，调用方式类似于：

curl -X POST "http://open-code-review:8080/api/v1/reviews" \ -H "Authorization: Bearer $OC_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "platform": "gitlab", "project_id": 42, "merge_request_iid": 128 }'

这个接口返回一个任务 ID，之后 Jenkins 轮询任务状态，直到completed或者failed。下面进入正题，记录这个阶段我遇到并解决的三个具体坑。

4.2 踩坑一：webhook 测试通过但 MR 事件触发没有任何响应

这个是排查时间最长的一个问题。现象很典型：在 GitLab webhook 设置页点击测试，open-code-review 能正常收到事件，core 日志里也能看到received webhook；但真正创建一个 MR 时，页面没有任何评论，core 日志也静悄悄的。

我一开始怀疑是事件类型勾选不对，反复检查了 “Merge request events” 是勾选状态；又怀疑是 Secret Token 校验失败，把日志级别调到 DEBUG 后依然没有任何 request 记录。就这样折腾了一下午，最后从网络层面查到了原因：GitLab 在发送 webhook 时走的出口 IP 和我们点击测试按钮时用的 IP 不在同一段。点击测试时，某些操作是从 GitLab 的 Web 进程发出的，而创建 MR 时，webhook 可能是由后台异步任务进程发出的，两者可能不在同一个网络出口。服务器安全组只放行了测试按钮对应的出口 IP 段，导致真正的 MR 事件请求在防火墙层就被丢掉了，core 服务根本看不到。

排查链路的有效步骤是这样的：先在服务器上用一个临时 HTTP 服务记录所有请求头，再用 GitLab 分别触发测试事件和真实事件，对比两者来源 IP 和请求头差异；然后检查安全组的出入口放行规则，把 GitLab 实例对应的完整网段都加入白名单。这个问题告诉我们一个老生常谈但依然值得重复的原则：webhook 类集成排查，先确认请求有没有到，再确认请求是不是被拒，不要一上来就怀疑业务签名逻辑。

4.3 踩坑二：error 级规则误伤测试代码，合并请求被永久阻塞

规则接入流水线之后，我们很快遇到第二个问题：合并请求被永久阻塞了，而且阻塞它的规则看起来“没毛病”。具体场景是测试目录下的tests/文件里有人用了eval来动态构造用例数据，触发了内置的“禁止使用 eval”安全规则。这条规则是error级别，配置又映射成了阻塞合并，结果所有改过测试代码的 MR 全被堵住了，流水线红了一大片。

这件事暴露出的设计问题是：我们只设置了“规则级别”，但没有设置“规则生效范围”。open-code-review 的规则配置支持按路径收窄生效范围。我当时在配置文件里加了规则作用域限制：

rules: enabled: - id: "SECURITY-NO-EVAL" path_exclude: - "tests/**" - "**/test_*.py" level: "warning" custom_paths: - "./rules/custom/*.py"

path_exclude直接作用于规则匹配阶段，也就是说即使测试代码里出现了eval，这条规则也不会运行。另外我把它的级别降成了warning，给团队留出讨论空间。

这个坑最大的教训是：规则不分场景地“一刀切”，必然会产生误报；而误报对工具信任度的杀伤力是巨大的。开发者在 MR 里看到一条不合理的 error，他会怀疑所有机器评论的可靠性。所以规则的作用域设计，应该从一开始就和其他配置一起考虑，而不是等出了问题再补。

4.4 踩坑三：多仓库共用 Token，机器人在 MR 里刷屏

第三个坑是在接入第二个仓库时出现的。当时图省事，用同一个 Group Access Token 给所有仓库用，结果所有 MR 评论都来自同一个机器人身份，而且因为 Token 权限太大，任何拿到这个 Token 的人都能通过 API 修改仓库内容。

排查这个问题时我先审查了 Token 的权限范围：Group Access Token 的api权限可以对组内所有仓库进行写操作，而 open-code-review 需要的其实只是“读取 diff 和给 MR 发评论”的能力，这两者权限边界差很远。后来我们采取了两层方案：第一层，在 GitLab 侧为每个项目单独设置 Access Token，只有api和read_repository，且只授予特定项目；第二层，在 open-code-review 的配置里启用secret_refs，把 Token 统一放到一个专用的密钥存储服务里，代码仓库里只保存引用名，不保存明文。

这层改造花了大概大半天时间，但它解决的问题不只是安全问题：分开的 Token 也让 open-code-review 的支持范围可以按队列划分，比如你可以先让它在核心业务仓库里保持严格模式，在内部工具仓库里只开 warning。

5. 团队落地三个月：数据、反馈与调整

5.1 落地前的规则与管理约定

工具部署成功只是第一步，真正难的是让团队从“多了个机器人在评论”过渡到“习惯了机器人的兜底”。我们在正式启用前做了几条约定，我觉得挺重要，值得分享。

第一个约定是“前两周不设门禁”。open-code-review 接入后的前两周，所有规则结果都只是评论，不阻塞任何合并请求。这两周的目标是让团队熟悉它的输出，同时让我们有机会观察误报率，把明显不合理的规则先调掉。第二个约定是“规则变更要评审”，自定义规则的增加和修改也走 MR 流程，由固定的人负责 review 规则本身，避免某个人的偏好被固化成团队的强制规则。第三个约定是“报障 24 小时响应”，开发者如果认为某条评论是误报，可以在一个专门的群里艾特负责规则的同事，一天内必须给出结论：是调整规则，还是补充文档说明为什么必须改。

这三个约定看起来朴素，但它们把“工具引入”变成了一个“团队共建”的过程，而不是自上而下的强制执行。开发者不会天然欢迎一台给你挑毛病的机器，但他们会欢迎一个“先讨论、再落地、能申诉”的流程。

5.2 三个月后的实际数据表现

在三个核心业务仓库启用了约三个月后，我统计了一些数据。说明一下，这些数据是内部环境的结果，不同团队结论可能有差异，但大致趋势应该可以参考。

这三个仓库加起来，三个月内创建了 612 个 MR，其中 417 个在人工 review 之前收到了 open-code-review 的至少一条评论。147 个 MR 里有至少一条 error 级问题，更改后才被通过。按这个比例算，大概 24% 的 MR 在合入之前被工具拦下了一次“至少需要改动”的问题。这些 error 级问题里，占比最高的是调试代码残留（约 38%），其次是资源未释放（约 21%）和危险函数调用（约 17%）。安全规则命中的次数反而不多，总共 9 次，但每次命中都确实是值得跟踪的问题。

最容易在合入后引发线上故障的危险模式，比如异常被吞掉、并发计数器的错误使用，在这三个月里只出现了 5 次，并且全部在 MR 阶段被 error 规则拦截。虽然我们无法准确算出工具到底避免了几次线上事故，但至少从观测数据看，这些历史上一旦漏过去就很麻烦的模式，确实在合入前被暴露出来了。

5.3 开发者的真实反馈：有用的“提醒”，讨厌的“噪音”

三个月后我做了一次简单的内部问卷，收集团队对 open-code-review 的态度。反馈里最有价值的一条是：“它像是一个永远不会困的同事，在你提交代码后第一时间帮你过一遍最容易犯的低级错误。”很多开发者提到，行内评论比那种汇总式的报告更有用，因为在 diff 上下文里看到“这里有个 sleep”和在一个 PDF 报告里看到第 17 页的问题，心理感受完全不同。

另一个高频反馈是“噪音”。主要来自两个渠道：一个是 warning 级规则太碎，比如“变量命名建议”这种主观性强的规则，连续几条出现时，开发者会觉得机器人很烦人；另一个是同一行被多个规则同时命中时，会重复发多条评论。这两个问题其实都和规则配置质量有关，后来我们把主观性强的规则收敛到只剩两三条，同时给同类规则增加了合并输出的逻辑，噪音感明显下降。

这个反馈给我们一个很实用的提醒：机器人审查工具的维护重点不在部署，而在“持续修剪规则花园”。新规则加入要克制，上线一段时间后统计命中率，长期没有命中的规则直接删掉，或者降级为info。规则库的演进战略应该是“小而准”，而不是“大而全”。

5.4 规则库的演进与扩展方向

目前团队的规则库里，内置规则和自定义规则的比例大概是 6:4，自定义规则全部写在rules/custom/目录下。每两个迭代周期，我们会例行审视一次每条规则近两个迭代的命中数据，如果某条规则在这段时间内一次都没命中，就开会讨论它是该删、该降级，还是该明确增加使用场景。

接下来的扩展方向，一个是在 open-code-review 的基础上增加结合 AST 的“架构守护”规则，比如限制某些层的代码不能直接依赖基础设施层的类；另一个是让规则能够读取仓库内的配置文件，从而对不同目录用不同规则做更精细化的治理。这些能力不一定都需要新工具，而是可以在 open-code-review 的自定义规则框架里继续长出来。

从我的实际体会来说，工具本身的开源和轻量，只是整个代码质量方案里最不重要的那部分。真正决定这类工具价值的，是你愿不愿意持续投入时间去校准规则、管理误报、和团队一起建立对机器审查的信任。机器评审不会取代人，也不该取代人。它最理想的位置，是在人开始 review 之前，先把那些“盯着看十分钟也不一定能发现、但脚本一眼就能看出来”的问题清场。这样人再看代码时，注意力反而能被解放到真正重要的地方。如果你也准备引入类似的工具，我建议你就从一个仓库、一批 error 级规则开始，跑两周，看看团队的反应，再决定往哪个方向扩展。