先说结论我把团队代码评审流程推倒重来自己做了一个叫 open-code-review 的自托管 AI 辅助评审服务。起因是一次常规发布后的线上事故——问题代码其实在评审阶段就被同事标注过“这里要不要考虑一下并发情况”但那条评论沉在十几个 thread 里没人跟进最后带着隐患上了线。这不是人的态度问题是人肉评审的容量问题。open-code-review 不是一个普通的代码扫描工具它是一个把“评审经验”显性化、可定制、完全开源的评审服务。它能自动监听代码托管平台的事件拉取变更 diff先跑确定性规则再交给大模型做语义分析最后把意见回写到对应代码行上。这篇文章我会把从调研、设计、实现到部署的完整过程摊开讲包括踩过的坑和目前还在规划里的功能适合正在搭建团队评审流程、或者想自建 AI 评审服务的同学参考。1. 为什么我要自己写 open-code-review而不是继续用现成方案1.1 人肉评审的真正瓶颈是“容量”大部分团队的 Code Review 流程是这样的开发者提交 PR评审人打开 diff逐行看在评论里写意见。问题在于一次认真的评审需要同时理解上下文、历史约定和业务逻辑一个 300 行左右的 PR认真看完至少需要 30 分钟。一天两次以上的深度评审人会不自觉地走形式——刷一眼有没有明显语法问题看到不熟悉的模块就想跳过。我不是在批评谁我自己也一样。代码评审的瓶颈从来不是态度问题是注意力容量的不够。这带来一个很现实的结果越是经验老到的评审人越容易把时间花在“这个变量名好怪”“这里少了个空行”这种机械问题上而真正危险的逻辑漏洞、边界条件、跨模块影响反而因为精力耗尽没看到。我们那次事故就是典型评审人其实发现了问题但没有机制保证“发现的问题”一定被解决、被跟进、被沉淀下来最后全靠人肉记忆而人肉记忆是最不可靠的东西。1.2 现成工具要么管不住语义要么不可控在动手之前我把市面上的方案分了三类做对比结论都不太满意方案类型代表性做法核心问题传统静态扫描SonarQube、ESLint、各类 Linter规则固定能管格式和明显坏味道但抓不住语义级问题配置重、误报多团队容易“脱敏”商业 AI 评审助手各大厂推出的 AI Code Review 插件效果好但代码要出网合规团队直接否决按代码量收费小团队肉疼评审风格不可控不能教它“我们团队的约定”自建 open-code-review自己掌控全流程一次开发成本之后规则内化模型可替换代码可以不出网完全可控这里要特别说下“规则不可控”这件事。商业 AI 评审工具的问题不在于它不够聪明而在于它的“经验”是黑盒。团队辛辛苦苦踩坑总结出来的约定比如“金额字段一律用整数分存储”“对外接口必须有鉴权”“改了公共函数签名必须同步搜索调用方”这些工具一概不知道也没有地方让你配置。对我来说评审工具如果不能吸收团队自己的历史教训那它的价值就要打对折。1.3 从事故反推出的需求清单结合那次事故和团队日常痛点我给自己列了个需求清单能自动在 PR/MR 创建和更新时触发评审不依赖任何人记得去运行能拉取代码变更内容而不是只对单个文件做静态分析能通过规则库表达团队的长期约定并且规则要支持测试、灰度、回滚能调用大模型做语义分析但大模型只负责“发现了什么”不负责“最终判断”能区分问题严重级别避免机器人刷屏导致误报疲劳能把评审意见回写到具体代码行和人肉评审的体验一致代码不出网至少做到模型可插拔能接私有化部署的模型这些需求列完之后项目的定位就很清晰了它不是要替代人做评审而是给每位评审人配一个“先读一遍代码的实习生”。这个实习生记性好规则从不忘、读得快秒级拉完所有 diff、而且天天上班不请假。后面所有设计都是围着这个定位转的。2. open-code-review 的功能边界它能评什么、不评什么2.1 它能做四类评审确定了定位之后第一件事就是把功能边界划清楚。open-code-review 有四个评审维度对应四条完全不同的实现路径第一类确定性规则检查。比如硬编码密钥、魔法数字、console.log 残留、废弃 API 调用、文件命名不符合规范、导入顺序错误。这类问题特征是“只要出现就是问题”不需要理解业务正则和抽象语法树扫描就能搞定。第二类语义级检查。比如异常被吞掉、错误处理分支缺失、边界条件没判断空集合、零长度、超出索引、状态更新遗漏、明显的并发竞争问题。这类问题靠规则引擎只能覆盖一小部分必须让大模型来读代码这属于语义理解。第三类变更影响分析。比如改了公共接口的签名但调用方没有同步修改改了数据库字段但迁移脚本和查询语句没跟上改了配置结构但文档和示例还停在旧版。这类问题在单个文件的 diff 里看不出来必须把“改动的文件”和“仓库里引用它的文件”放在一起看。第四类仓库约定检查。提交信息是否符合规范、PR 描述是否完整、新增代码是否包含了调试用的断点、有没有包含不该提交的本地配置文件。这类规则完全是团队自己长出来的每个团队长得不一样。2.2 它明确不做什么划边界比列功能更重要。有些事我刻意没有做甚至写进了 README 的第一页不替代人做架构决策。技术选型、模块拆分、权衡取舍这类事机器人给不了答案也不该给。不自动合并代码。评审意见只是建议最终合并权始终在人手上。不承诺找出所有 bug。召回率有上限它做的是“降低漏检概率”不是“消灭 bug”。不做性能基准测试。不是不能做而是做起来动静太大容易误报不如留给专门的流水线任务。我把这个项目定位成“评审助手”而不是“评审裁判”。一旦它拥有了“批准”或“拒绝”的权力团队就会开始想办法绕过它而不是跟它协作。2.3 一次完整的用户视角使用流程在不了解技术细节之前先看它是怎么被使用的更容易建立整体印象开发者向代码托管平台提交一个 PR并指定了评审人或者只是推到已有 PR 分支代码托管平台向 open-code-review 推一个 webhook 事件机器人在 1 到 5 分钟内取决于 PR 大小在该 PR 下回复评论评论里既有“机器人总结”也有挂在具体代码行上的 inline 评论开发者看到评论后可以直接回复“这不是问题因为 XXX”机器人会记下这次对话作为后续规则的上下文这个功能还在迭代中后面会细说实测下来一个 300 行以内的 PR整体体验和人肉评审非常接近但机器人的响应速度稳定在很多评审人“有空的时候”之前。3. 技术选型是拿痛点筛出来的这套组合背后的理由3.1 编程语言和 Web 框架项目主体用的是 Python 3.11 FastAPI。这个选择不是因为它最炫而是因为痛点导向AI 生态最成熟的是 PythonLLM SDK、diff 解析、各类代码解析库基本都是 Python 优先FastAPI 原生异步适合做 webhook 这种 IO 密集入口而且自带 OpenAPI 文档后面做规则管理后台几乎不费劲。有人可能会问为什么不用 Go 或者 Node。Go 的性能确实好部署也方便但大模型调用这块的生态和开发效率跟 Python 比还是差一截。Node 的开发体验也还行但对 AI 生态的兼容性不如 Python 直白。我的原则是内部工具优先考虑“团队写起来舒服、周边生态全”性能瓶颈等到了再优化也不迟。3.2 异步任务队列为什么不是同步处理Webhook 进来不能同步执行评审。一个评审任务要拉 diff、解析、跑规则、调大模型、回写评论快则几十秒慢则几分钟。如果在 HTTP 请求里同步做代码托管平台那边会超时重试你的服务也会被慢请求拖垮。所以架构上就定了一条铁律Webhook 只负责验签、落库、投递消息立即返回 200所有重活全部进队列。异步队列选的是 Celery Redis。Celery 是我用得最熟的任务框架调度、重试、任务跟踪都很成熟Redis 做 broker 足够简单不用额外维护一套 RabbitMQ。未来如果任务量真的大到 Redis 撑不住Celery 的 broker 可以平滑切到 RabbitMQ代码改动量很小。3.3 数据存储为什么选了 PostgreSQL数据模型里最核心的几类表评审任务、PR 对象、文件变更、规则命中记录、问题去重表、评论回写记录。这些实体之间是强关联关系一个 PR 对应多个文件一个文件对应多个问题一个问题对应一条评论关系型数据库天然合适。多表关联查询配上索引几十万条评审记录也能秒回。具体到数据库品牌我选了 PostgreSQL 而不是 MySQL。核心原因是 PostgreSQL 的 JSONB 字段对规则配置这种半结构化数据太友好了。一条规则既要有固定的元数据字段id、名称、级别又要有一段灵活的匹配条件正则表达式、AST 模式、环境变量用 JSONB 存 flexible 部分用普通列存公共部分查询和扩展都舒服。3.4 Diff 解析方案如果自己用字符串处理来解析 git diff看起来简单实际上全是边缘情况二进制文件、文件重命名、新文件、空文件、diff 格式的细微差异、不同代码托管平台返回格式的差异。我曾经试过自己写结果光处理“一个文件重命名时 diff 怎么展示”就花了一天而且测不干净。后来老老实实用 unidiff 这个 Python 库解析 diff它把 diff 结构化成“文件 - hunk - 行”三层对象已经处理好了大量边缘情况。不过它只解决“格式解析”不解决“解析出来的内容怎么用”。我在此基础上封装了一个 ChangeSet 模型额外计算每个 hunk 的上下文范围、新增行列表、删除行列表以及整个 PR 的变更统计信息变更文件数、新增删除比、测试文件占比。这些统计信息直接决定后面“要不要让大模型看这个文件”。3.5 LLM Provider 适配层最后是模型接入层我把它设计成了可插拔的 Provider 接口。核心就一个方法输入 prompt或消息列表输出文本。至于底层是 OpenAI、Anthropic、还是本地部署的模型服务全部通过环境变量配置。这样设计不是因为我搞不定某个具体厂商的 SDK而是因为模型领域迭代太快绑定任何一家都是风险。今天效果最好的模型三个月后可能就被替代了今天觉得代码可以接受出网的团队明天可能因为合规要求改成私有化部署。接口定义大致长这样简化版class LLMProvider(abc.ABC): abc.abstractmethod def complete( self, messages: list[dict], temperature: float 0.2, max_tokens: int 2048, ) - str: 输入多轮消息输出模型回复文本 raise NotImplementedError实现方面第一版做了一个 OpenAI SDK 兼容实现所有提供 OpenAI 兼容 API 的服务都能直接填 base_url 接入。本地部署模型走 vLLM 或者 Ollama也都能兼容。这套接口虽然只有二十几行却把“选模型”这件事从代码里剥离了出去变成了纯配置项。4. 核心机制拆解一次评审请求从 Webhook 到评论回写的完整生命周期4.1 事件接收入口验签与幂等服务要做的第一件事是接收代码托管平台发来的 webhook 事件。以 GitHub 为例配置好 Webhook 后每次 PR 创建、PR 更新、评审请求都会向指定 URL 发一个 POST 请求。入口函数第一件必做的事是验签。GitHub 会通过X-Hub-Signature-256头给请求体算一个 HMAC-SHA256 签名用配置好的 secret 做签名密钥。验签不通过直接返回 401防止伪造请求触发昂贵的评审任务。import hashlib import hmac def verify_signature(payload_body: bytes, signature_header: str, secret: str) - bool: if not signature_header: return False expected sha256 hmac.new( secret.encode(), payload_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature_header)验签通过后先检查幂等表用“事件类型 对象 ID 事件 ID”做唯一键如果处理过就直接返回。然后解析事件类型pull_request / push / merge_request把任务投递到 Celery 队列里最后立刻返回 200。这一步的幂等非常关键。Webhook 重试、事件重复推送、或者同一 PR 的多个事件交叉到达如果没有幂等保护同一批代码会被重复评审好几遍。我第一版在这里踩了大坑第六章会专门讲。4.2 变更提取锁定评审基线任务进入队列后第一件事是拉取变更内容。这里有个非常重要的细节评审必须锁定一个固定基线。也就是说评审开始那一刻代码是什么状态后面就永远基于这个状态来评论不能因为中途开发者又推了代码导致评论行号漂移。实现方式很直接拉取 PR 的 diff 时把 ref 指定为那个 MR 对应的合并目标分支和源分支。对于 GitHub通常用GET /repos/{owner}/{repo}/pulls/{pull_number}接口拿到base.sha然后在评审任务的上下文里保存这个 SHA。后续所有跟代码内容相关的操作都基于这个固定 SHA而不是“当前最新代码”。diff 拿回来之后经过 unidiff 解析就得到了结构化的文件变更列表。我在这里还做了一步“文件评分”统计每个文件的变更行数、是否测试文件、是否涉及核心业务目录、是否在风险目录名单里。这个评分的作用是如果文件打分太低说明它只是个简单的格式修改或者文档更新直接走规则扫描就够了不用浪费大模型的上下文窗口。4.3 确定性规则扫描先跑机器能确定的事文件变更解析完成之后先跑规则引擎。执行顺序有个原则先跑高风险规则再跑普通规则先跑成本低的规则再跑成本高的规则。比如“代码里出现密钥”这种致命规则用一行正则就能扫完整个仓库而“AST 级别的异常吞噬检测”需要解析语法树耗时明显更高要放在后面。每条规则命中后会记录一条证据包括命中的文件路径、具体行号、触发片段、命中的规则 ID、严重级别。这一步不直接生成评论只把结果暂存起来后面的 LLM 评审结果会和规则命中结果做合并、去重、排序。举一条真实规则的配置示例这条规则检查“禁止在代码中硬编码访问密钥”id: security_hardcoded_secret name: 硬编码访问密钥检测 level: L0 language: [python, javascript, go] severity: critical pattern: (?i)(api[_-]?key|secret|password|token)\\s*[:]\\s*[\][^\]{8,}[\] condition: s.root)看上去很简单但这类规则的价值用三个月的数据来说明最直观命中这类规则的问题数量占全部命中问题数量的 10% 左右但这 10% 的问题是唯一一类可以稳定造成生产事故的问题。要保证这类问题绝不能被漏掉只有规则引擎能在所有模型不稳定的前提下做到这一点。4.4 LLM 语义评审把 diff 交给大模型但约束它只输出 JSON规则扫描完成后那些“文件评分超过阈值”的文件会进入 LLM 语义评审流程。这里说的语义评审不是把 diff 往模型里一扔就完事Prompt 的组装方式直接决定了输出质量。我设计的 Prompt 结构分四层系统提示固定评审原则比如“重点找逻辑缺陷、边界条件、错误处理遗漏不要评论代码风格和格式”仓库上下文仓库的 README 里写的技术栈和约定、最近几条提交信息、这次 PR 的描述变更内容当前文件的 diff按 hunk 分块控制单次输入长度规则命中结果把这个文件里规则引擎已经发现的问题一起喂给模型让它避免重复同时让它关注规则覆盖不到的语义问题Prompt 的最后要求模型只输出一个 JSON 对象不要输出任何多余的文字。这个 JSON 的结构是固定的{ issues: [ { severity: critical|warning|info, category: logic|security|error_handling|concurrency|performance, line: 42, reason: 问题描述, suggestion: 修复建议 } ] }返回结果后先做 JSON 解析。如果解析失败重试一次再失败就降级为“只保留规则引擎的结果”不让单次模型故障阻塞整个评审流程。解析成功之后把模型返回的问题和规则命中结果合并做三件事去重同一行同一类型只保留一条、排序critical 在前、截断单次评论最多 20 条避免刷屏。4.5 回写代码托管平台所有问题整理完之后通过 API 回写到代码托管平台。GitHub 的流程是先调“创建审查评论”接口把每条问题挂到对应代码行的 inline 位置再调“创建问题评论”接口写一段机器人生成的总结评论。GitLab 的流程类似用 MR discussion API。回写时有一个细节很关键如果要评论的行在旧版本的 diff 里存在、但在最新代码里已经不存在了GitHub 会返回 422 错误。处理方式是捕获这个异常把问题降级为“出现在总结评论里”而不是挂在具体行上。这样既避免了接口报错也保证问题不会被悄悄吞掉。总结评论的模板长这样## open-code-review 评审汇总基线 commit: 8f3b2aa 本次评审共发现 **N** 个问题 - 严重问题**3** 个 - 警告**7** 个 - 建议**5** 个 ### 需要重点关注 - src/payment/calculator.py:42 金额计算可能丢失精度建议改用整数分存储 - src/auth/token.py:88 异常被捕获后未记录日志丢失现场 ### 规则命中 - security_hardcoded_secret检测到硬编码密钥共 1 处 本机器人只提供建议最终决策请以人工评审为准。代码里去掉 emoji实际输出用纯文本符号。5. 规则引擎设计把团队踩过的坑变成一条条可执行的规则5.1 为什么必须有规则引擎而不是只靠大模型这是我在设计过程中被问最多的问题“你既然已经有 LLM 了为什么还要写一套规则引擎它俩做的事不是重叠的吗”答案是有重叠但只有规则引擎能提供三种大模型做不到的东西确定性、可测试性、零成本。大模型是概率模型同一个 diff 让它评两次结果可能不一样大模型没法上单测你今天发现它漏了一个问题改几行 Prompt它明天可能又漏另一个大模型每调用一次都是钱如果每一个 10 行文件的 PR 都要走一遍模型一个月下来的账单会让人清醒。规则引擎是相反的它是确定性的同一段代码跑一百次结果都一样它可测试每条规则可以绑定一组样例代码断言“这段代码要命中、那段代码不能命中”它零边际成本跑一万条规则和跑一条规则只差几毫秒。所以我的架构原则是能用规则解决的绝不用模型模型只用来处理规则解决不了、需要理解语义的问题。5.2 规则的分层与表达规则分为三层每一层表达方式和适用场景都不同层级表达方式适用场景示例L0 词法层正则表达式字符串级模式硬编码密钥、console.log 残留、TODO 未清理L1 语法层抽象语法树结构级模式catch 异常后空处理、if 判断后缺少 elseL2 策略层跨文件关联 条件判断仓库级约定新增枚举值是否同步了映射表、公共函数签名变更是否同步了调用方每条规则的通用字段定义{ id: error_handling_empty_catch, name: 捕获异常后不应留空, level: L1, language: [java, python, javascript], severity: warning, scope: { exclude_paths: [test/, examples/, docs/] }, pattern: { type: ast, module: catch_clause_empty, params: { min_body_lines: 0 } }, message: 异常被捕获后没有处理逻辑建议至少记录日志。, enabled: true }scope 字段特别重要它负责“上下文约束”。我一开始没设计这个字段结果规则库一多误报率直线上升。比如“禁止使用 alert”这条风格规则会把测试代码里的 mock alert 也报出来开发者看到之后直接忽略久而久之整条规则就失效了。加上 scope 排除掉测试目录和示例目录之后误报率立刻降下来了。5.3 从事故复盘到规则投产的完整过程规则库的建设不能靠“想起来就加一条”要把它的生命周期规范化。我们团队的标准流程是这样的第一步事故复盘。线上出问题之后复盘时所有人都会问同一个问题这个问题在评审阶段有没有可能被发现如果答案是“有可能”那它就值得沉淀成规则。第二步规则草案。把复盘的结论转成规则草案写清楚这条规则想抓什么、用什么方式抓、可能会产生哪些误报。这一步其实是在写设计文档。第三步历史回归。拿最近 100 个已经合并的 PR 跑一遍这条规则看命中率和误报率。如果一条规则在历史代码上误报率超过 30%说明它表达得太宽需要收敛条件。第四步灰度验证。规则先以只警告不评论的方式上线在后台记录命中情况。第五步正式启用。连续观察一两周数据误报率稳定之后再把它加进正式评论里。我们团队做过一次统计通过这个流程沉淀出来的规则半年内一共积累了 80 多条其中 90% 以上都来自真实的事故复盘。这些规则绑定了团队对“什么样的代码会出事”的长期观察这是任何开源工具都给不了的东西。6. 实战中踩过的坑现象、定位、修复的完整记录6.1 坑一同一问题被反复评论PR 评论区彻底刷屏现象就是字面意思开发者每次 push 一个新 commit机器人就把同样的问题重新评论一遍。一个 PR 如果 push 了五次评论区就会多出五条一模一样的评论。开发者烦到直接在群里问“能不能把这个机器人关掉”。定位过程是这样的先看日志发现每次 push 事件到达之后系统都正常创建了一个新的评审任务说明任务入队没问题。再看去重逻辑发现我第一版用的是“commit_id 文件路径 行号 规则 ID”作为去重键但 commit_id 每次 push 都会变等于去重条件里有一个必然变化的字段去重自然失效。真正的根因是去重键应该基于“问题本身”而不是“代码版本”一个在演进过程中一直存在的问题不管代码被 push 了多少次它都是同一个问题。修复方案是把去重键改成“问题指纹”文件路径 行号 规则 ID或模型 issue 类型 触发代码摘要的 hash。只要问题在指纹就不变。同时把“去重”的逻辑从“命中时检查”改成了“回写前检查”也就是说规则扫描、LLM 评审都跑完之后在最后生成评论之前先查一下这个问题之前有没有评论过如果评论过且问题还存在于最新代码里就把旧评论更新一下状态或直接跳过不产生新评论如果问题已经在旧评论中被标记为“已修复”就追加一条“看起来已解决”的回复。修完之后同一个 PR 无论 push 多少次每个问题最多只有一条评论。这是这个项目截止到目前开发者好评度提升最大的一次改动。6.2 坑二并发提交后评论指向了错误的代码行这是个特别隐蔽的竞态条件。现象是开发者收到一条评论说第 58 行有 bug他打开代码一看第 58 行根本不是代码是个空行再仔细看他怀疑机器人把评论挂错了位置。排查时我先怀疑 diff 解析出错了打印了日志里记录的原始 diff 和解析后的行号反复对比没发现异常。后来又怀疑是不是代码托管平台的 API 返回了奇怪的数据于是把同一个 PR 反复触发了几次偶尔会复现但概率不高——这类偶现问题最难查说明大概率是时序问题。最后我在回写评论的代码里加了上下文日志发现了一个关键线索评审任务开始拉取 diff 时记录的基线 commit 是 A但任务跑完、回写评论时开发者在中间又 push 了 commit B。代码托管平台的 inline 评论机制会把“第 58 行”自动偏移到新代码里对应的位置但 diff 的行号和旧代码的内容其实已经对不上了于是评论就挂在了错误的行上。修复方案分两步第一步评审开始时把基线 commit SHA 写进任务上下文回写评论时指定这个 SHA让平台知道“我评论的是这个版本的代码行号请按这个版本解析”第二步GitHub 的回写 API 本身支持在创建评论时传 commit_id 参数把它设为基线 SHA。如果平台不支持指定 commit_id退而求其次在总结评论里明确写出“本次评审基于 commit A如果代码已更新部分行号可能不准确”。这套方案上线后再也没有出现过“评论挂错行”的反馈。6.3 坑三超长 PR 的 Token 消耗失控账单直接翻了几十倍有一次团队评审一个 3000 多行的大 PR月底导账单一看那一天的模型费用是平时的 40 倍。最先怀疑是模型调用方式有 bug比如死循环调用但排查日志之后发现没有死循环问题出在更加直接的地方我把 3000 行的 diff 一次性全部塞进了模型上下文。大模型按 token 计费输入越长、费用越高而且超过一定长度之后模型的注意力还会分散输出质量明显下降。定位到根因之后我设计了一个“文件评分 分块评审”的策略文件评分每个文件根据变更行数、是否测试文件、是否核心目录、规则引擎是否命中等维度打分低于阈值的文件直接跳过 LLM只跑规则扫描分块评审需要 LLM 评审的文件如果 diff 太大按 hunk 切分成小块每块单独调用模型再合并结果上线后统计了两周数据Token 消耗降低了 75%而评审发现的真实缺陷数量没有明显下降。原因很直接大部分 PR 里的变更文件真正需要语义理解的只是其中一小部分大部分文件是格式调整、测试用例、配置文件规则引擎完全够用。把模型资源集中在高价值的文件上性价比反而更高。6.4 坑四Webhook 事件乱序导致漏评现象是某个 PR 一直没有机器人的评审回复但代码托管平台的事件记录里确实发了两次事件。起初怀疑是事件没送达但查了平台的 event log 之后发现事件顺序很奇怪用户先发了 review_request 事件然后才推了一个 commit触发了 push 事件。问题出在幂等键设计上。第一版把幂等键设置成“对象 ID”也就是 PR ID没有把事件类型考虑进去。于是当 review_request 事件先到达时系统在幂等表里写了一条记录“PR #123 已处理”紧接着 push 事件到达一看幂等表“PR #123 已处理”直接丢弃了。但 review_request 事件本身并没有触发完整的评审因为它只是一个“请求评审”的通知真正的评审应该由随后的 push 事件触发——结果就被幂等表错误拦截了。修复方案是幂等键从“对象 ID”升级为“事件类型 对象 ID 事件 ID”每个事件在流程内部都有明确的状态机已接收、已入队、已处理不同事件类型之间互不阻塞。同时加了一个兜底机制每个 PR 关联一个“待评审队列”定时巡检所有状态异常的任务发现超过 5 分钟没有评审结果的 PR 就重新触发一次评审。这个兜底虽然不能保证实时性但保证了“不遗漏”。6.5 坑五规则库膨胀之后误报率升高团队信任崩了规则库积累到七八十条的时候新的问题出现了机器人的警告越来越多但开发者点开之后发现很多是误报比如“这个路径本身就会被框架过滤为什么还要报警”。连续几次之后开发者的习惯从“每条必看”变成了“直接忽略”。这比没有规则更可怕——机器人评论成了噪声源。根因在于规则库增长太快但每条规则的“上下文条件”没有跟上。很多规则在设计时只考虑了“代码长什么样”没有考虑“这段代码在什么场景下可以豁免”。修复方案是给规则体系加了完整的 scope 条件路径排除test/、examples/、generated/、条件表达式比如“仅当方法名以 handle 开头时才适用”、以及每一条规则的“覆盖测试”强制绑定。从这次之后我规定任何新规则上线之前必须绑定至少三组测试样例一组应该命中、一组不该命中、一组边界情况。没有测试样例的规则不上线。修复之后做的第一件事是拉取最近 30 天的评论数据统计每条规则的命中总数和真实有效命中数把有效命中率低于 60% 的规则全部降级为“只记录不评论”状态。降级后的两周里开发者的反馈从“机器人又在乱叫”变成了“最近机器人的评论质量好像变高了”信任才开始慢慢恢复。7. 部署接入与实测效果从零到跑起来要多久7.1 Docker Compose 一键启动整个项目用 Docker Compose 编排包含四个服务PostgreSQL数据存储、Redis队列 broker 缓存、apiFastAPI接收 webhook、workerCelery执行评审任务。如果未来任务量上去了再拆一个 scheduler 出来跑定时巡检。docker-compose.yml 的简化版长这样version: 3.9 services: db: image: postgres:15-alpine environment: POSTGRES_DB: open_code_review POSTGRES_USER: ocr POSTGRES_PASSWORD: ocr_password volumes: - db_data:/var/lib/postgresql/data redis: image: redis:7-alpine api: build: . environment: DATABASE_URL: postgresqlpsycopg://ocr:ocr_passworddb:5432/open_code_review REDIS_URL: redis://redis:6379/0 WEBHOOK_SECRET: your_webhook_secret LLM_PROVIDER: openai_compatible LLM_MODEL: your_model_name LLM_BASE_URL: https://api.your-llm-service.example/v1 LLM_API_KEY: your_llm_api_key ports: - 8000:8000 depends_on: - db - redis worker: build: . command: celery -A app.tasks.celery_app worker --loglevelinfo environment: DATABASE_URL: postgresqlpsycopg://ocr:ocr_passworddb:5432/open_code_review REDIS_URL: redis://redis:6379/0 LLM_PROVIDER: openai_compatible LLM_MODEL: your_model_name LLM_BASE_URL: https://api.your-llm-service.example/v1 LLM_API_KEY: your_llm_api_key depends_on: - db - redis volumes: db_data:配置文件做好之后两个服务实例一键拉起docker compose up -d大概等一两分钟API 服务起来之后先跑一下健康检查接口确认服务在线。7.2 接入 GitHub 的完整步骤对接 GitHub 时建议用 GitHub App而不是个人 Token原因是权限控制更精细。配置时需要的权限如下Pull requests: Read writeChecks: Read writeWebhook events 至少勾选Pull requests、PushWebhook 配置的 URL 填 open-code-review 的 API 地址加/webhook/github路径。配置完成并注册之后GitHub 会分配一个 App ID 和一个私钥把它填入 open-code-review 的环境变量里。验证接入成功的最快方式找一个测试仓库随便改一个文件提交一个 PR然后观察代码托管平台事件记录里是否出现了 webhook 投递记录自己的服务日志里有没有对应的评审任务日志PR 回复里是否出现了机器人的总结评论如果 PR 上没有任何反应排查顺序建议是先看事件有没有到在平台端看投递记录再看 Webhook 签名和 secret 配置是否正确再看日志里有没有任务报错。大部分接入失败的问题最后都集中在验签失败和事件类型没勾选这两个点上。7.3 实测效果连续 60 天的数据项目跑了 60 天之后我统计了一组数据。说明一下这是在一个规模约 20 人、代码量约 50 万行的技术团队内部测出来的数据绝对值仅供参考但趋势很有参考价值指标数值累计评审 PR 数386规则引擎命中问题数1042LLM 发现真实缺陷数157误报数41综合准确率约 78.6%平均评审耗时3 分 12 秒评审被忽略率未 follow约 12%准确率 78.6% 不是说剩下的 21.4% 都是误报有一部分是“重复反馈”比如规则命中了但开发者已经在另一个地方做了处理。真正让我对这个项目有信心的数据是60 天里机器人累计发现了 6 个能引起生产事故级别的问题其中一个就是金额计算丢失精度恰好就是最初那次线上事故的同款问题。8. 最后说几个踩过之后才想明白的事规则引擎和 LLM 不是替代关系是分工关系。规则引擎处理 70% 的机械问题LLM 处理 20% 的语义问题人专注于最后 10% 的架构和权衡。这个分工比例不是拍脑袋定的是调了很久才调到这个平衡点。把模型放在它能发挥的地方而不是什么都扔给模型。规则库比模型更有价值。模型可以随时换今天的模型明天可能就被更好的替代但团队从事故里总结出来的规则不会变。它们是团队的长期资产是踩坑之后留下的真金白银。所以我建议每个用类似方案的团队把规则库当成一等公民来维护给它配测试、配灰度、配回滚像对待生产代码一样对待它。我把每个规则都设计成可以被质疑、被讨论、可以被 revert 的对象。这不仅仅是技术设计也是在改善团队的 Code Review 文化当一条规则的误报被反馈之后处理它的过程本身就是一种团队知识的再讨论。开发者不再对机器人骂骂咧咧而是学会了说“这条规则报错了原因是场景不在它的 scope 内我去改规则让它更精确”。当团队开始主动修改规则而不是无视规则的时候Code Review 文化的问题就解决了一大半。最后再分享一个小的使用技巧如果你刚开始搭这类系统不要一上来就追求“全自动评审”。先把机器人设定成“只报告、不评估”让人来评估机器人的意见准不准。等你积累了一两周数据、根据实际反馈调过规则之后再决定要不要让它在特定情况下“拦截合并”。机器的信任是挣来的不是配置出来的。 自托管AI代码评审服务实战：从事故复盘到规则引擎与LLM协同设计
先说结论我把团队代码评审流程推倒重来自己做了一个叫 open-code-review 的自托管 AI 辅助评审服务。起因是一次常规发布后的线上事故——问题代码其实在评审阶段就被同事标注过“这里要不要考虑一下并发情况”但那条评论沉在十几个 thread 里没人跟进最后带着隐患上了线。这不是人的态度问题是人肉评审的容量问题。open-code-review 不是一个普通的代码扫描工具它是一个把“评审经验”显性化、可定制、完全开源的评审服务。它能自动监听代码托管平台的事件拉取变更 diff先跑确定性规则再交给大模型做语义分析最后把意见回写到对应代码行上。这篇文章我会把从调研、设计、实现到部署的完整过程摊开讲包括踩过的坑和目前还在规划里的功能适合正在搭建团队评审流程、或者想自建 AI 评审服务的同学参考。1. 为什么我要自己写 open-code-review而不是继续用现成方案1.1 人肉评审的真正瓶颈是“容量”大部分团队的 Code Review 流程是这样的开发者提交 PR评审人打开 diff逐行看在评论里写意见。问题在于一次认真的评审需要同时理解上下文、历史约定和业务逻辑一个 300 行左右的 PR认真看完至少需要 30 分钟。一天两次以上的深度评审人会不自觉地走形式——刷一眼有没有明显语法问题看到不熟悉的模块就想跳过。我不是在批评谁我自己也一样。代码评审的瓶颈从来不是态度问题是注意力容量的不够。这带来一个很现实的结果越是经验老到的评审人越容易把时间花在“这个变量名好怪”“这里少了个空行”这种机械问题上而真正危险的逻辑漏洞、边界条件、跨模块影响反而因为精力耗尽没看到。我们那次事故就是典型评审人其实发现了问题但没有机制保证“发现的问题”一定被解决、被跟进、被沉淀下来最后全靠人肉记忆而人肉记忆是最不可靠的东西。1.2 现成工具要么管不住语义要么不可控在动手之前我把市面上的方案分了三类做对比结论都不太满意方案类型代表性做法核心问题传统静态扫描SonarQube、ESLint、各类 Linter规则固定能管格式和明显坏味道但抓不住语义级问题配置重、误报多团队容易“脱敏”商业 AI 评审助手各大厂推出的 AI Code Review 插件效果好但代码要出网合规团队直接否决按代码量收费小团队肉疼评审风格不可控不能教它“我们团队的约定”自建 open-code-review自己掌控全流程一次开发成本之后规则内化模型可替换代码可以不出网完全可控这里要特别说下“规则不可控”这件事。商业 AI 评审工具的问题不在于它不够聪明而在于它的“经验”是黑盒。团队辛辛苦苦踩坑总结出来的约定比如“金额字段一律用整数分存储”“对外接口必须有鉴权”“改了公共函数签名必须同步搜索调用方”这些工具一概不知道也没有地方让你配置。对我来说评审工具如果不能吸收团队自己的历史教训那它的价值就要打对折。1.3 从事故反推出的需求清单结合那次事故和团队日常痛点我给自己列了个需求清单能自动在 PR/MR 创建和更新时触发评审不依赖任何人记得去运行能拉取代码变更内容而不是只对单个文件做静态分析能通过规则库表达团队的长期约定并且规则要支持测试、灰度、回滚能调用大模型做语义分析但大模型只负责“发现了什么”不负责“最终判断”能区分问题严重级别避免机器人刷屏导致误报疲劳能把评审意见回写到具体代码行和人肉评审的体验一致代码不出网至少做到模型可插拔能接私有化部署的模型这些需求列完之后项目的定位就很清晰了它不是要替代人做评审而是给每位评审人配一个“先读一遍代码的实习生”。这个实习生记性好规则从不忘、读得快秒级拉完所有 diff、而且天天上班不请假。后面所有设计都是围着这个定位转的。2. open-code-review 的功能边界它能评什么、不评什么2.1 它能做四类评审确定了定位之后第一件事就是把功能边界划清楚。open-code-review 有四个评审维度对应四条完全不同的实现路径第一类确定性规则检查。比如硬编码密钥、魔法数字、console.log 残留、废弃 API 调用、文件命名不符合规范、导入顺序错误。这类问题特征是“只要出现就是问题”不需要理解业务正则和抽象语法树扫描就能搞定。第二类语义级检查。比如异常被吞掉、错误处理分支缺失、边界条件没判断空集合、零长度、超出索引、状态更新遗漏、明显的并发竞争问题。这类问题靠规则引擎只能覆盖一小部分必须让大模型来读代码这属于语义理解。第三类变更影响分析。比如改了公共接口的签名但调用方没有同步修改改了数据库字段但迁移脚本和查询语句没跟上改了配置结构但文档和示例还停在旧版。这类问题在单个文件的 diff 里看不出来必须把“改动的文件”和“仓库里引用它的文件”放在一起看。第四类仓库约定检查。提交信息是否符合规范、PR 描述是否完整、新增代码是否包含了调试用的断点、有没有包含不该提交的本地配置文件。这类规则完全是团队自己长出来的每个团队长得不一样。2.2 它明确不做什么划边界比列功能更重要。有些事我刻意没有做甚至写进了 README 的第一页不替代人做架构决策。技术选型、模块拆分、权衡取舍这类事机器人给不了答案也不该给。不自动合并代码。评审意见只是建议最终合并权始终在人手上。不承诺找出所有 bug。召回率有上限它做的是“降低漏检概率”不是“消灭 bug”。不做性能基准测试。不是不能做而是做起来动静太大容易误报不如留给专门的流水线任务。我把这个项目定位成“评审助手”而不是“评审裁判”。一旦它拥有了“批准”或“拒绝”的权力团队就会开始想办法绕过它而不是跟它协作。2.3 一次完整的用户视角使用流程在不了解技术细节之前先看它是怎么被使用的更容易建立整体印象开发者向代码托管平台提交一个 PR并指定了评审人或者只是推到已有 PR 分支代码托管平台向 open-code-review 推一个 webhook 事件机器人在 1 到 5 分钟内取决于 PR 大小在该 PR 下回复评论评论里既有“机器人总结”也有挂在具体代码行上的 inline 评论开发者看到评论后可以直接回复“这不是问题因为 XXX”机器人会记下这次对话作为后续规则的上下文这个功能还在迭代中后面会细说实测下来一个 300 行以内的 PR整体体验和人肉评审非常接近但机器人的响应速度稳定在很多评审人“有空的时候”之前。3. 技术选型是拿痛点筛出来的这套组合背后的理由3.1 编程语言和 Web 框架项目主体用的是 Python 3.11 FastAPI。这个选择不是因为它最炫而是因为痛点导向AI 生态最成熟的是 PythonLLM SDK、diff 解析、各类代码解析库基本都是 Python 优先FastAPI 原生异步适合做 webhook 这种 IO 密集入口而且自带 OpenAPI 文档后面做规则管理后台几乎不费劲。有人可能会问为什么不用 Go 或者 Node。Go 的性能确实好部署也方便但大模型调用这块的生态和开发效率跟 Python 比还是差一截。Node 的开发体验也还行但对 AI 生态的兼容性不如 Python 直白。我的原则是内部工具优先考虑“团队写起来舒服、周边生态全”性能瓶颈等到了再优化也不迟。3.2 异步任务队列为什么不是同步处理Webhook 进来不能同步执行评审。一个评审任务要拉 diff、解析、跑规则、调大模型、回写评论快则几十秒慢则几分钟。如果在 HTTP 请求里同步做代码托管平台那边会超时重试你的服务也会被慢请求拖垮。所以架构上就定了一条铁律Webhook 只负责验签、落库、投递消息立即返回 200所有重活全部进队列。异步队列选的是 Celery Redis。Celery 是我用得最熟的任务框架调度、重试、任务跟踪都很成熟Redis 做 broker 足够简单不用额外维护一套 RabbitMQ。未来如果任务量真的大到 Redis 撑不住Celery 的 broker 可以平滑切到 RabbitMQ代码改动量很小。3.3 数据存储为什么选了 PostgreSQL数据模型里最核心的几类表评审任务、PR 对象、文件变更、规则命中记录、问题去重表、评论回写记录。这些实体之间是强关联关系一个 PR 对应多个文件一个文件对应多个问题一个问题对应一条评论关系型数据库天然合适。多表关联查询配上索引几十万条评审记录也能秒回。具体到数据库品牌我选了 PostgreSQL 而不是 MySQL。核心原因是 PostgreSQL 的 JSONB 字段对规则配置这种半结构化数据太友好了。一条规则既要有固定的元数据字段id、名称、级别又要有一段灵活的匹配条件正则表达式、AST 模式、环境变量用 JSONB 存 flexible 部分用普通列存公共部分查询和扩展都舒服。3.4 Diff 解析方案如果自己用字符串处理来解析 git diff看起来简单实际上全是边缘情况二进制文件、文件重命名、新文件、空文件、diff 格式的细微差异、不同代码托管平台返回格式的差异。我曾经试过自己写结果光处理“一个文件重命名时 diff 怎么展示”就花了一天而且测不干净。后来老老实实用 unidiff 这个 Python 库解析 diff它把 diff 结构化成“文件 - hunk - 行”三层对象已经处理好了大量边缘情况。不过它只解决“格式解析”不解决“解析出来的内容怎么用”。我在此基础上封装了一个 ChangeSet 模型额外计算每个 hunk 的上下文范围、新增行列表、删除行列表以及整个 PR 的变更统计信息变更文件数、新增删除比、测试文件占比。这些统计信息直接决定后面“要不要让大模型看这个文件”。3.5 LLM Provider 适配层最后是模型接入层我把它设计成了可插拔的 Provider 接口。核心就一个方法输入 prompt或消息列表输出文本。至于底层是 OpenAI、Anthropic、还是本地部署的模型服务全部通过环境变量配置。这样设计不是因为我搞不定某个具体厂商的 SDK而是因为模型领域迭代太快绑定任何一家都是风险。今天效果最好的模型三个月后可能就被替代了今天觉得代码可以接受出网的团队明天可能因为合规要求改成私有化部署。接口定义大致长这样简化版class LLMProvider(abc.ABC): abc.abstractmethod def complete( self, messages: list[dict], temperature: float 0.2, max_tokens: int 2048, ) - str: 输入多轮消息输出模型回复文本 raise NotImplementedError实现方面第一版做了一个 OpenAI SDK 兼容实现所有提供 OpenAI 兼容 API 的服务都能直接填 base_url 接入。本地部署模型走 vLLM 或者 Ollama也都能兼容。这套接口虽然只有二十几行却把“选模型”这件事从代码里剥离了出去变成了纯配置项。4. 核心机制拆解一次评审请求从 Webhook 到评论回写的完整生命周期4.1 事件接收入口验签与幂等服务要做的第一件事是接收代码托管平台发来的 webhook 事件。以 GitHub 为例配置好 Webhook 后每次 PR 创建、PR 更新、评审请求都会向指定 URL 发一个 POST 请求。入口函数第一件必做的事是验签。GitHub 会通过X-Hub-Signature-256头给请求体算一个 HMAC-SHA256 签名用配置好的 secret 做签名密钥。验签不通过直接返回 401防止伪造请求触发昂贵的评审任务。import hashlib import hmac def verify_signature(payload_body: bytes, signature_header: str, secret: str) - bool: if not signature_header: return False expected sha256 hmac.new( secret.encode(), payload_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature_header)验签通过后先检查幂等表用“事件类型 对象 ID 事件 ID”做唯一键如果处理过就直接返回。然后解析事件类型pull_request / push / merge_request把任务投递到 Celery 队列里最后立刻返回 200。这一步的幂等非常关键。Webhook 重试、事件重复推送、或者同一 PR 的多个事件交叉到达如果没有幂等保护同一批代码会被重复评审好几遍。我第一版在这里踩了大坑第六章会专门讲。4.2 变更提取锁定评审基线任务进入队列后第一件事是拉取变更内容。这里有个非常重要的细节评审必须锁定一个固定基线。也就是说评审开始那一刻代码是什么状态后面就永远基于这个状态来评论不能因为中途开发者又推了代码导致评论行号漂移。实现方式很直接拉取 PR 的 diff 时把 ref 指定为那个 MR 对应的合并目标分支和源分支。对于 GitHub通常用GET /repos/{owner}/{repo}/pulls/{pull_number}接口拿到base.sha然后在评审任务的上下文里保存这个 SHA。后续所有跟代码内容相关的操作都基于这个固定 SHA而不是“当前最新代码”。diff 拿回来之后经过 unidiff 解析就得到了结构化的文件变更列表。我在这里还做了一步“文件评分”统计每个文件的变更行数、是否测试文件、是否涉及核心业务目录、是否在风险目录名单里。这个评分的作用是如果文件打分太低说明它只是个简单的格式修改或者文档更新直接走规则扫描就够了不用浪费大模型的上下文窗口。4.3 确定性规则扫描先跑机器能确定的事文件变更解析完成之后先跑规则引擎。执行顺序有个原则先跑高风险规则再跑普通规则先跑成本低的规则再跑成本高的规则。比如“代码里出现密钥”这种致命规则用一行正则就能扫完整个仓库而“AST 级别的异常吞噬检测”需要解析语法树耗时明显更高要放在后面。每条规则命中后会记录一条证据包括命中的文件路径、具体行号、触发片段、命中的规则 ID、严重级别。这一步不直接生成评论只把结果暂存起来后面的 LLM 评审结果会和规则命中结果做合并、去重、排序。举一条真实规则的配置示例这条规则检查“禁止在代码中硬编码访问密钥”id: security_hardcoded_secret name: 硬编码访问密钥检测 level: L0 language: [python, javascript, go] severity: critical pattern: (?i)(api[_-]?key|secret|password|token)\\s*[:]\\s*[\][^\]{8,}[\] condition: s.root)看上去很简单但这类规则的价值用三个月的数据来说明最直观命中这类规则的问题数量占全部命中问题数量的 10% 左右但这 10% 的问题是唯一一类可以稳定造成生产事故的问题。要保证这类问题绝不能被漏掉只有规则引擎能在所有模型不稳定的前提下做到这一点。4.4 LLM 语义评审把 diff 交给大模型但约束它只输出 JSON规则扫描完成后那些“文件评分超过阈值”的文件会进入 LLM 语义评审流程。这里说的语义评审不是把 diff 往模型里一扔就完事Prompt 的组装方式直接决定了输出质量。我设计的 Prompt 结构分四层系统提示固定评审原则比如“重点找逻辑缺陷、边界条件、错误处理遗漏不要评论代码风格和格式”仓库上下文仓库的 README 里写的技术栈和约定、最近几条提交信息、这次 PR 的描述变更内容当前文件的 diff按 hunk 分块控制单次输入长度规则命中结果把这个文件里规则引擎已经发现的问题一起喂给模型让它避免重复同时让它关注规则覆盖不到的语义问题Prompt 的最后要求模型只输出一个 JSON 对象不要输出任何多余的文字。这个 JSON 的结构是固定的{ issues: [ { severity: critical|warning|info, category: logic|security|error_handling|concurrency|performance, line: 42, reason: 问题描述, suggestion: 修复建议 } ] }返回结果后先做 JSON 解析。如果解析失败重试一次再失败就降级为“只保留规则引擎的结果”不让单次模型故障阻塞整个评审流程。解析成功之后把模型返回的问题和规则命中结果合并做三件事去重同一行同一类型只保留一条、排序critical 在前、截断单次评论最多 20 条避免刷屏。4.5 回写代码托管平台所有问题整理完之后通过 API 回写到代码托管平台。GitHub 的流程是先调“创建审查评论”接口把每条问题挂到对应代码行的 inline 位置再调“创建问题评论”接口写一段机器人生成的总结评论。GitLab 的流程类似用 MR discussion API。回写时有一个细节很关键如果要评论的行在旧版本的 diff 里存在、但在最新代码里已经不存在了GitHub 会返回 422 错误。处理方式是捕获这个异常把问题降级为“出现在总结评论里”而不是挂在具体行上。这样既避免了接口报错也保证问题不会被悄悄吞掉。总结评论的模板长这样## open-code-review 评审汇总基线 commit: 8f3b2aa 本次评审共发现 **N** 个问题 - 严重问题**3** 个 - 警告**7** 个 - 建议**5** 个 ### 需要重点关注 - src/payment/calculator.py:42 金额计算可能丢失精度建议改用整数分存储 - src/auth/token.py:88 异常被捕获后未记录日志丢失现场 ### 规则命中 - security_hardcoded_secret检测到硬编码密钥共 1 处 本机器人只提供建议最终决策请以人工评审为准。代码里去掉 emoji实际输出用纯文本符号。5. 规则引擎设计把团队踩过的坑变成一条条可执行的规则5.1 为什么必须有规则引擎而不是只靠大模型这是我在设计过程中被问最多的问题“你既然已经有 LLM 了为什么还要写一套规则引擎它俩做的事不是重叠的吗”答案是有重叠但只有规则引擎能提供三种大模型做不到的东西确定性、可测试性、零成本。大模型是概率模型同一个 diff 让它评两次结果可能不一样大模型没法上单测你今天发现它漏了一个问题改几行 Prompt它明天可能又漏另一个大模型每调用一次都是钱如果每一个 10 行文件的 PR 都要走一遍模型一个月下来的账单会让人清醒。规则引擎是相反的它是确定性的同一段代码跑一百次结果都一样它可测试每条规则可以绑定一组样例代码断言“这段代码要命中、那段代码不能命中”它零边际成本跑一万条规则和跑一条规则只差几毫秒。所以我的架构原则是能用规则解决的绝不用模型模型只用来处理规则解决不了、需要理解语义的问题。5.2 规则的分层与表达规则分为三层每一层表达方式和适用场景都不同层级表达方式适用场景示例L0 词法层正则表达式字符串级模式硬编码密钥、console.log 残留、TODO 未清理L1 语法层抽象语法树结构级模式catch 异常后空处理、if 判断后缺少 elseL2 策略层跨文件关联 条件判断仓库级约定新增枚举值是否同步了映射表、公共函数签名变更是否同步了调用方每条规则的通用字段定义{ id: error_handling_empty_catch, name: 捕获异常后不应留空, level: L1, language: [java, python, javascript], severity: warning, scope: { exclude_paths: [test/, examples/, docs/] }, pattern: { type: ast, module: catch_clause_empty, params: { min_body_lines: 0 } }, message: 异常被捕获后没有处理逻辑建议至少记录日志。, enabled: true }scope 字段特别重要它负责“上下文约束”。我一开始没设计这个字段结果规则库一多误报率直线上升。比如“禁止使用 alert”这条风格规则会把测试代码里的 mock alert 也报出来开发者看到之后直接忽略久而久之整条规则就失效了。加上 scope 排除掉测试目录和示例目录之后误报率立刻降下来了。5.3 从事故复盘到规则投产的完整过程规则库的建设不能靠“想起来就加一条”要把它的生命周期规范化。我们团队的标准流程是这样的第一步事故复盘。线上出问题之后复盘时所有人都会问同一个问题这个问题在评审阶段有没有可能被发现如果答案是“有可能”那它就值得沉淀成规则。第二步规则草案。把复盘的结论转成规则草案写清楚这条规则想抓什么、用什么方式抓、可能会产生哪些误报。这一步其实是在写设计文档。第三步历史回归。拿最近 100 个已经合并的 PR 跑一遍这条规则看命中率和误报率。如果一条规则在历史代码上误报率超过 30%说明它表达得太宽需要收敛条件。第四步灰度验证。规则先以只警告不评论的方式上线在后台记录命中情况。第五步正式启用。连续观察一两周数据误报率稳定之后再把它加进正式评论里。我们团队做过一次统计通过这个流程沉淀出来的规则半年内一共积累了 80 多条其中 90% 以上都来自真实的事故复盘。这些规则绑定了团队对“什么样的代码会出事”的长期观察这是任何开源工具都给不了的东西。6. 实战中踩过的坑现象、定位、修复的完整记录6.1 坑一同一问题被反复评论PR 评论区彻底刷屏现象就是字面意思开发者每次 push 一个新 commit机器人就把同样的问题重新评论一遍。一个 PR 如果 push 了五次评论区就会多出五条一模一样的评论。开发者烦到直接在群里问“能不能把这个机器人关掉”。定位过程是这样的先看日志发现每次 push 事件到达之后系统都正常创建了一个新的评审任务说明任务入队没问题。再看去重逻辑发现我第一版用的是“commit_id 文件路径 行号 规则 ID”作为去重键但 commit_id 每次 push 都会变等于去重条件里有一个必然变化的字段去重自然失效。真正的根因是去重键应该基于“问题本身”而不是“代码版本”一个在演进过程中一直存在的问题不管代码被 push 了多少次它都是同一个问题。修复方案是把去重键改成“问题指纹”文件路径 行号 规则 ID或模型 issue 类型 触发代码摘要的 hash。只要问题在指纹就不变。同时把“去重”的逻辑从“命中时检查”改成了“回写前检查”也就是说规则扫描、LLM 评审都跑完之后在最后生成评论之前先查一下这个问题之前有没有评论过如果评论过且问题还存在于最新代码里就把旧评论更新一下状态或直接跳过不产生新评论如果问题已经在旧评论中被标记为“已修复”就追加一条“看起来已解决”的回复。修完之后同一个 PR 无论 push 多少次每个问题最多只有一条评论。这是这个项目截止到目前开发者好评度提升最大的一次改动。6.2 坑二并发提交后评论指向了错误的代码行这是个特别隐蔽的竞态条件。现象是开发者收到一条评论说第 58 行有 bug他打开代码一看第 58 行根本不是代码是个空行再仔细看他怀疑机器人把评论挂错了位置。排查时我先怀疑 diff 解析出错了打印了日志里记录的原始 diff 和解析后的行号反复对比没发现异常。后来又怀疑是不是代码托管平台的 API 返回了奇怪的数据于是把同一个 PR 反复触发了几次偶尔会复现但概率不高——这类偶现问题最难查说明大概率是时序问题。最后我在回写评论的代码里加了上下文日志发现了一个关键线索评审任务开始拉取 diff 时记录的基线 commit 是 A但任务跑完、回写评论时开发者在中间又 push 了 commit B。代码托管平台的 inline 评论机制会把“第 58 行”自动偏移到新代码里对应的位置但 diff 的行号和旧代码的内容其实已经对不上了于是评论就挂在了错误的行上。修复方案分两步第一步评审开始时把基线 commit SHA 写进任务上下文回写评论时指定这个 SHA让平台知道“我评论的是这个版本的代码行号请按这个版本解析”第二步GitHub 的回写 API 本身支持在创建评论时传 commit_id 参数把它设为基线 SHA。如果平台不支持指定 commit_id退而求其次在总结评论里明确写出“本次评审基于 commit A如果代码已更新部分行号可能不准确”。这套方案上线后再也没有出现过“评论挂错行”的反馈。6.3 坑三超长 PR 的 Token 消耗失控账单直接翻了几十倍有一次团队评审一个 3000 多行的大 PR月底导账单一看那一天的模型费用是平时的 40 倍。最先怀疑是模型调用方式有 bug比如死循环调用但排查日志之后发现没有死循环问题出在更加直接的地方我把 3000 行的 diff 一次性全部塞进了模型上下文。大模型按 token 计费输入越长、费用越高而且超过一定长度之后模型的注意力还会分散输出质量明显下降。定位到根因之后我设计了一个“文件评分 分块评审”的策略文件评分每个文件根据变更行数、是否测试文件、是否核心目录、规则引擎是否命中等维度打分低于阈值的文件直接跳过 LLM只跑规则扫描分块评审需要 LLM 评审的文件如果 diff 太大按 hunk 切分成小块每块单独调用模型再合并结果上线后统计了两周数据Token 消耗降低了 75%而评审发现的真实缺陷数量没有明显下降。原因很直接大部分 PR 里的变更文件真正需要语义理解的只是其中一小部分大部分文件是格式调整、测试用例、配置文件规则引擎完全够用。把模型资源集中在高价值的文件上性价比反而更高。6.4 坑四Webhook 事件乱序导致漏评现象是某个 PR 一直没有机器人的评审回复但代码托管平台的事件记录里确实发了两次事件。起初怀疑是事件没送达但查了平台的 event log 之后发现事件顺序很奇怪用户先发了 review_request 事件然后才推了一个 commit触发了 push 事件。问题出在幂等键设计上。第一版把幂等键设置成“对象 ID”也就是 PR ID没有把事件类型考虑进去。于是当 review_request 事件先到达时系统在幂等表里写了一条记录“PR #123 已处理”紧接着 push 事件到达一看幂等表“PR #123 已处理”直接丢弃了。但 review_request 事件本身并没有触发完整的评审因为它只是一个“请求评审”的通知真正的评审应该由随后的 push 事件触发——结果就被幂等表错误拦截了。修复方案是幂等键从“对象 ID”升级为“事件类型 对象 ID 事件 ID”每个事件在流程内部都有明确的状态机已接收、已入队、已处理不同事件类型之间互不阻塞。同时加了一个兜底机制每个 PR 关联一个“待评审队列”定时巡检所有状态异常的任务发现超过 5 分钟没有评审结果的 PR 就重新触发一次评审。这个兜底虽然不能保证实时性但保证了“不遗漏”。6.5 坑五规则库膨胀之后误报率升高团队信任崩了规则库积累到七八十条的时候新的问题出现了机器人的警告越来越多但开发者点开之后发现很多是误报比如“这个路径本身就会被框架过滤为什么还要报警”。连续几次之后开发者的习惯从“每条必看”变成了“直接忽略”。这比没有规则更可怕——机器人评论成了噪声源。根因在于规则库增长太快但每条规则的“上下文条件”没有跟上。很多规则在设计时只考虑了“代码长什么样”没有考虑“这段代码在什么场景下可以豁免”。修复方案是给规则体系加了完整的 scope 条件路径排除test/、examples/、generated/、条件表达式比如“仅当方法名以 handle 开头时才适用”、以及每一条规则的“覆盖测试”强制绑定。从这次之后我规定任何新规则上线之前必须绑定至少三组测试样例一组应该命中、一组不该命中、一组边界情况。没有测试样例的规则不上线。修复之后做的第一件事是拉取最近 30 天的评论数据统计每条规则的命中总数和真实有效命中数把有效命中率低于 60% 的规则全部降级为“只记录不评论”状态。降级后的两周里开发者的反馈从“机器人又在乱叫”变成了“最近机器人的评论质量好像变高了”信任才开始慢慢恢复。7. 部署接入与实测效果从零到跑起来要多久7.1 Docker Compose 一键启动整个项目用 Docker Compose 编排包含四个服务PostgreSQL数据存储、Redis队列 broker 缓存、apiFastAPI接收 webhook、workerCelery执行评审任务。如果未来任务量上去了再拆一个 scheduler 出来跑定时巡检。docker-compose.yml 的简化版长这样version: 3.9 services: db: image: postgres:15-alpine environment: POSTGRES_DB: open_code_review POSTGRES_USER: ocr POSTGRES_PASSWORD: ocr_password volumes: - db_data:/var/lib/postgresql/data redis: image: redis:7-alpine api: build: . environment: DATABASE_URL: postgresqlpsycopg://ocr:ocr_passworddb:5432/open_code_review REDIS_URL: redis://redis:6379/0 WEBHOOK_SECRET: your_webhook_secret LLM_PROVIDER: openai_compatible LLM_MODEL: your_model_name LLM_BASE_URL: https://api.your-llm-service.example/v1 LLM_API_KEY: your_llm_api_key ports: - 8000:8000 depends_on: - db - redis worker: build: . command: celery -A app.tasks.celery_app worker --loglevelinfo environment: DATABASE_URL: postgresqlpsycopg://ocr:ocr_passworddb:5432/open_code_review REDIS_URL: redis://redis:6379/0 LLM_PROVIDER: openai_compatible LLM_MODEL: your_model_name LLM_BASE_URL: https://api.your-llm-service.example/v1 LLM_API_KEY: your_llm_api_key depends_on: - db - redis volumes: db_data:配置文件做好之后两个服务实例一键拉起docker compose up -d大概等一两分钟API 服务起来之后先跑一下健康检查接口确认服务在线。7.2 接入 GitHub 的完整步骤对接 GitHub 时建议用 GitHub App而不是个人 Token原因是权限控制更精细。配置时需要的权限如下Pull requests: Read writeChecks: Read writeWebhook events 至少勾选Pull requests、PushWebhook 配置的 URL 填 open-code-review 的 API 地址加/webhook/github路径。配置完成并注册之后GitHub 会分配一个 App ID 和一个私钥把它填入 open-code-review 的环境变量里。验证接入成功的最快方式找一个测试仓库随便改一个文件提交一个 PR然后观察代码托管平台事件记录里是否出现了 webhook 投递记录自己的服务日志里有没有对应的评审任务日志PR 回复里是否出现了机器人的总结评论如果 PR 上没有任何反应排查顺序建议是先看事件有没有到在平台端看投递记录再看 Webhook 签名和 secret 配置是否正确再看日志里有没有任务报错。大部分接入失败的问题最后都集中在验签失败和事件类型没勾选这两个点上。7.3 实测效果连续 60 天的数据项目跑了 60 天之后我统计了一组数据。说明一下这是在一个规模约 20 人、代码量约 50 万行的技术团队内部测出来的数据绝对值仅供参考但趋势很有参考价值指标数值累计评审 PR 数386规则引擎命中问题数1042LLM 发现真实缺陷数157误报数41综合准确率约 78.6%平均评审耗时3 分 12 秒评审被忽略率未 follow约 12%准确率 78.6% 不是说剩下的 21.4% 都是误报有一部分是“重复反馈”比如规则命中了但开发者已经在另一个地方做了处理。真正让我对这个项目有信心的数据是60 天里机器人累计发现了 6 个能引起生产事故级别的问题其中一个就是金额计算丢失精度恰好就是最初那次线上事故的同款问题。8. 最后说几个踩过之后才想明白的事规则引擎和 LLM 不是替代关系是分工关系。规则引擎处理 70% 的机械问题LLM 处理 20% 的语义问题人专注于最后 10% 的架构和权衡。这个分工比例不是拍脑袋定的是调了很久才调到这个平衡点。把模型放在它能发挥的地方而不是什么都扔给模型。规则库比模型更有价值。模型可以随时换今天的模型明天可能就被更好的替代但团队从事故里总结出来的规则不会变。它们是团队的长期资产是踩坑之后留下的真金白银。所以我建议每个用类似方案的团队把规则库当成一等公民来维护给它配测试、配灰度、配回滚像对待生产代码一样对待它。我把每个规则都设计成可以被质疑、被讨论、可以被 revert 的对象。这不仅仅是技术设计也是在改善团队的 Code Review 文化当一条规则的误报被反馈之后处理它的过程本身就是一种团队知识的再讨论。开发者不再对机器人骂骂咧咧而是学会了说“这条规则报错了原因是场景不在它的 scope 内我去改规则让它更精确”。当团队开始主动修改规则而不是无视规则的时候Code Review 文化的问题就解决了一大半。最后再分享一个小的使用技巧如果你刚开始搭这类系统不要一上来就追求“全自动评审”。先把机器人设定成“只报告、不评估”让人来评估机器人的意见准不准。等你积累了一两周数据、根据实际反馈调过规则之后再决定要不要让它在特定情况下“拦截合并”。机器的信任是挣来的不是配置出来的。