1. 为什么一个团队最终会想自建 Code Review 工具1.1 从Code Review到Code Review流水线我们经历了什么先交代背景。我们是一个15人左右的研发团队维护着4个核心业务仓库每个仓库平均每天有8到12个Pull Request需要过审。在很长一段时间里Code Review完全依赖人肉谁有空谁看谁写的代码谁自己盯。结果就是周三下午的PR堆积成山Review意见五花八门有的评论到下周都没人回应。后来我们试过商业代码评审托管平台也试过各种开源的机器人、Lint增强工具比如直接把lint结果推到PR评论里的那些方案。坦白讲这类工具解决了一部分低级问题自动化的需求但用起来总有种隔靴搔痒的感觉。商业SaaS服务对仓库代码权限要求很高内网部署的成本也不低而且规则引擎基本被厂商锁死想定制一条贴合我们团队规范的检查项往往要等版本更新或者绕很大的弯。真正让我们下决心自研的导火索是一次事故。有个同事把环境变量的key直接硬编码到了公共工具类里Lint规则没覆盖到人工Review也没人注意到结果配置项泄漏到了前端产物中。这件事让我意识到人工评审的注意力是稀缺资源不该浪费在变量名拼写空指针防御这种静态可判定的问题上而应该集中在架构、数据流和业务语义上。于是就有了open-code-review这个项目。1.2 我们自己定义的三个核心原则项目启动之前我们内部连续开了三次讨论会最终把目标收敛成了三条原则。后续所有功能和取舍都围绕这三条展开。第一规则必须可插拔、可开源。我们不想再造一个封闭的审查系统。每一条检查逻辑都应当是一个独立插件既能开箱即用也能让任何团队按自己的规范去改改完还能回馈给社区。第二优先做确定性检查LLM辅助评论只能做补充。我们承认大模型在理解代码语义上的能力但它会幻觉会给出无根据的建议。如果让大模型主导评审团队很快会陷入AI说应该这样改的无效争论。我们坚持静态分析、复杂度计算、变更范围检查这类可验证的结果优先LLM只负责给出基于 diff 上下文的观察性评论并且明确在评论中标注置信度。第三所有结果必须可追溯。每条评论都要能说清楚出自哪条规则、哪个配置项、哪个版本。这样任何一条误报团队都能直接定位到规则本身而不是靠运气去猜。这个项目从立项到第一个可用版本我们用了大概三周。整体代码量并不大核心引擎加上默认插件大概3500行Python。它没有漂亮的管理后台也没有复杂的Web界面它解决的是最实际的问题每次提交代码时自动把值得关注的diff点讲给评审人听而不是直接指挥评审人改代码。2. 核心架构把审阅动作拆成可插拔的流水线2.1 事件驱动的基础结构早期我们想得很简单监听Webhook推送拿到PR的diff跑一遍规则然后把结果写回评论。但真正动手设计时发现拿到diff只是开始。一次完整的代码审阅至少包含变更内容获取、变更解析、规则匹配、结果聚合、评论推送这几个环节。如果把这些逻辑全部塞进一个函数里那后续每加一条规则都要动主流程维护成本会迅速失控。所以我做第一版原型的时候就把整个处理过程拆成了一条流水线collect - parse - analyze - aggregate - report。每个环节之间用数据对象传递上下文互不感知内部实现。比如collect环节只负责从Git托管平台拉取完整的diff数据把它统一转换成内部定义的ChangeSet对象parse环节再根据语言类型把代码块拆成语法树之后的analyze环节不用关心diff是从哪里来的只要处理结构化数据就行。这个抽象带来的直接好处是我们后来要支持GitLab和Gitea的时候只需要新增一个collect适配器后面四个环节一行代码都没改。如果你也在做类似的工具建议第一版就坚持这个方向千万不要图省事把远程API调用直接写在规则里。2.2 流水线五阶段的职责划分每个阶段承担的任务是严格分离的我用一张表来说明各阶段的核心职责和产出物。阶段输入核心职责输出collectWebhook事件 / CLI参数对接Git平台API或本地命令获取变更集元信息与完整diffChangeSetparseChangeSet按文件后缀命中对应解析器构建AST或结构化的行号映射ParsedFile集合analyzeParsedFile集合按注册的ReviewRule逐一运行产出候选问题ReviewFinding列表aggregateReviewFinding列表去重、按文件与行号排序、过滤噪音、计算置信度AggregatedResultreportAggregatedResult生成评论内容、推送至平台、记录审计日志ReportReceipt你可能注意到了我把聚合单独抽成了一个阶段。这是被实际教训逼出来的。一开始analyze阶段直接把结果推给report结果发现多个规则可能命中同一行代码比如一行超长且复杂度过高的代码会被可读性规则和圈复杂度规则同时报告PR里就会出现两条内容高度重叠的评论非常吵。聚合阶段做的事就是合并同类项同文件同行号的finding会合并成一条综合评论并列出所有命中的规则ID。2.3 插件协议一天学会的ReviewRule接口插件协议是整个项目的地基。我的目标是让团队里任何一名工程师花十分钟看完示例插件就能写出自己的规则。接口设计得非常简单dataclass class ReviewFinding: file_path: str line: int severity: str # error / warning / info rule_id: str message: str suggestion: str code_snippet: str class ReviewRule(ABC): rule_id: str description: str severity: str info abstractmethod def check(self, changeset: ChangeSet, parsed_files: list[ParsedFile]) - list[ReviewFinding]: pass一条规则就是一个类实现check方法即可。规则只面向数据和上下文不需要关心评论是怎么发出去的。我们团队有个后端同事之前完全没接触过这类工具照着示例插件半小时就写了一个禁止新增print调试代码的规则并成功跑通了全链路。这里有个设计细节值得分享Changeset里除了每个文件的diff还会保留本次PR新增/删除/修改的文件完整路径列表。因为很多规则不需要解析语法树只需要看路径和数据特征。比如禁止在migration目录新增文件时忘记修改版本记录这种团队规范用路径匹配就能实现完全不需要解析代码。把这类规则的门槛压低能显著提高团队参与度。3. 内置检查器的设计取舍与实现要点3.1 静态问题从AST提取上下文而不是堆正则第一类内置检查器处理的是传统的静态问题未使用的导入、不安全的字符串格式化、明显的资源泄漏隐患、可疑的宽泛异常捕获等。这类问题Lint工具也覆盖了一部分但我们的定位不是替代Lint工具而是做Lint工具不做的那部分。举一个具体的例子。Python的except Exception在很多Lint工具里默认是放行的但它经常掩盖真实的编码错误。我们要识别的不是这种语句本身而是在明知循环体内部会抛出特定异常的情况下仍用broad except包住并继续循环的模式。这种模式用正则很难稳定匹配必须解析AST拿到try块内的子节点集合、except类型列表、循环上下文然后做组合判断。实现上我们基于ast模块对每个函数体构建作用域链标记变量定义和使用位置。AST方案比正则的体积大不少但胜在可控所有能判定的结论都是精确的不存在撞运气式的命中。class BroadExceptRule(ReviewRule): rule_id py-broad-except-in-loop severity warning def check(self, changeset, parsed_files): findings [] for pf in parsed_files: if not pf.language python: continue tree pf.ast_tree for node in ast.walk(tree): if not isinstance(node, (ast.For, ast.While)): continue for sub in ast.walk(node): if isinstance(sub, ast.Try): for handler in sub.handlers: if handler.type is None: findings.append(self._finding( pf.path, handler, 循环体内捕获了所有异常容易掩盖潜在错误。请改为捕获明确异常类型。 )) return findings这段代码很直白但我用了两个小技巧第一只解析本次PR变更涉及的文件不做全仓库扫描性能上有保障第二定位到行号之后评论里会附上原始的异常处理代码片段这样评审人不用跳转文件就能理解上下文。3.2 变更风险评估让评审人先看最危险的地方第二类检查器解决的问题很现实PR里面有20个文件到底从哪看起人工评审最怕的就是把注意力平均分配到所有文件上结果在无伤大雅的工具类改动上花了20分钟真正有风险的公共模块改动却草草略过。我们实现了一个变更风险评估器输入是本次PR的所有变更文件输出是一个风险排序。核心算法不复杂主要考虑三个维度修改文件的影响范围、修改行的新增代码量、代码自身复杂度。影响范围通过依赖关系分析来计算一个工具函数被多少个模块引用它的改动就会牵连多少个潜在调用点。这部分我们直接调用现有依赖分析库没有重复造轮子。风险排序输出会以摘要表的形式出现在PR第一条评论里风险级别文件建议优先评审高core/auth/token_manager.py是中api/v1/order_handler.py是低utils/date_parser.py否我自己的使用体会是这个功能比很多花哨的自动化检查都管用。因为它不是直接告诉作者你写得不对而是帮助评审人更高效地分配自己的注意力。评审人还是拥有最终判断权但聚焦准确度提高了很多。3.3 测试变更匹配盯住改了一堆实现却没改测试的情况第三类检查器是纯规则层面的专门处理测试与实现的匹配关系。我们定义了一条硬性规则任何对src/目录下业务逻辑的修改如果同一个PR中没有对应tests/目录下的测试变更则产生一条warning级别的finding。这条规则虽然简单但效果出奇得好。实现思路是用文件路径做映射。每个业务文件我们都维护对应测试路径的候选集合。比如src/services/order.py对应的测试可能是tests/services/test_order.py也可能是tests/unit/test_order_service.py。我们在配置里允许团队维护一份路径映射表同时提供默认启发式规则把src/替换为tests/把文件名改为test_前缀。命中任意一个候选就认为该文件有测试覆盖了。刚开始我以为这条规则会被团队抵触毕竟它剥夺了我先提交代码再补测试的自由。但实际落地后大家的反馈是它减少了一大类忘了补测试的低级失误。因为人工Review的时候很少有人会逐个对比这个PR里改了哪些实现文件、有没有漏掉对应的测试文件。机器在这方面比人可靠得多。3.4 LLM辅助评论可控的关键在于范围约束关于AI生成评论这件事我们内部讨论过很多轮。结论是可以用但必须约束使用范围而且不能冒充权威。目前我们的实现是配置一个可选的LLM分析器它只被允许做三件事根据diff解释代码意图、指出潜在的数据一致性问题、给出改进建议。它不允许做的是改写代码、断言代码有bug、评价代码风格。范围约束是怎么实现的不是靠模型自觉而是靠我们给它的prompt模板加硬性要求。它的输入不是整个仓库而是当前PR的diff和变更风险评估器选出的高风险文件列表。输出也会经过一道过滤程序如果返回内容中没有引用具体的行号或具体的函数名这条评论就会被丢弃。因为我们发现LLM输出的大而化之的评论比如函数体较长建议拆分成多个函数这类废话对于团队来说没有任何信息量只会制造噪音。我觉得现在很多AI Code Review工具被吐槽核心原因就是缺少这种范围约束的设计。模型很强大但不加约束地让它在PR里长篇大论最终会让团队成员养成CR页面全是骂人的机器人的条件反射。4. 接入Git平台和CI不跑一遍看不出来的坑4.1 GitHub App模式的权限模型先说说我们用的GitHub。open-code-review的远程对接优先实现了GitHub App模式而不是传统的Personal Access Token。原因是权限边界更清晰。App可以精确控制它能读哪些仓库、不能读哪些仓库并且访问token是短时效的需要定期刷新相比PAT长期挂在一个机器人账号下的模式安全性高不少。但App模式有个入口门槛回调域名必须支持HTTPS。如果你是本地调试可以用gh repo配合smee.io这种Webhook转发服务来做内网穿透。我们早期就是这么干的把GitHub的Webhook事件转发到本地局域网的开发机端口上代码改完保存一下配置就能测试整个流程。权限配置这一块容易被忽视的是Pull requests: read/write和Checks: read/write的区分。如果你只想让机器人发评论而不需要它参与CI检查结果面板那就只需要开Pull requests的写权限。评论走的是Issues API而真正的Checks面板需要额外的权限我们第一版没开后来发现评论内容偶尔会被GitHub折叠到Show resolved里还以为是权限问题排查了半天最后发现其实是评论被作者误点掉了。这里提醒一下评论被作者resolved之后机器人下一次运行到同一行时也记得重新发评论的幂等处理。4.2 不依赖平台的统一处理方案git命令直接生成diff做完GitHub适配后我们内部发现还有一个更普遍的需求不少仓库不在GitHub上而是放在公司内网GitLab上。GitLab的API风格和GitHub很不一样Webhook的payload结构也不一样如果每种平台都写一套collect适配器工作量有点大。后来我们想了一个取巧的办法不依赖平台API获取diff而是用git命令直接从本地克隆目录里生成变更数据。在collect阶段工具会先定位到仓库的本地路径执行git fetch拉取最新远程分支然后运行git diff对比目标分支和基础分支。只要机器上有git无论是GitHub、GitLab还是Gitea甚至是纯内网仓库都能拿到同样的diff数据。平台API只负责两件事接收Webhook事件、推送评论结果。git fetch origin git diff --unified5 origin/main...origin/feature/xxx /tmp/change.diff这个方案让我们把平台适配的工作量从每个平台三套API降到了每个平台只有评论接口一套API。内网GitLab的token权限只需要read_api和write_api两个scope就够了。对于没有开放API的SVN仓库理论上也可以直接调用svn diff走同样的流程不过我们暂未实测。4.3 评论风暴与频率限制rate limit是最现实的敌人上线第一周我们就迎来了一个实际问题GitHub API的rate limit被打爆了。原因很笨——我们给每个PR一次性推送了50多条评论每个评论一次API调用再加上获取issue评论列表做幂等检查的调用一个PR就能吃掉上百次配额。GitHub的Token配额每小时只有5000次看起来很多但四个仓库跑一天很快就见底了。解决思路有两个我们两个都做了。第一是评论合并把同一文件的多个finding合并成一组评论每条评论用列表形式列出找到的所有问题而不是一个finding发一条。这样评论数量从50条降到5条左右评审人体验反而更好不用在信息流里翻几十条机器人消息。第二是按文件分块推送每个文件最多产生一条评论绝不为同一文件发多条。合并评论的具体格式是review-botreported 3 findings oncore/auth/token_manager.py:L42: [warning] 硬编码密钥建议从配置系统读取L58: [error] 过长的try块建议提取为独立函数L67: [info] 变量命名与上下文不符建议改为expired_at这样每条评论都聚焦在一个文件上而且附带文件内的问题清单。评审人点开PR页面不用滚动就能看到所有问题的大致分布体验比原来好了一个数量级。4.4 评论的幂等性让机器人反复评论同一行是灾难代码评审机器人最容易被吐槽的场景就是作者push了新commit来修复问题机器人却在旧代码的同一行又评论了一遍。用户一脸懵我明明已经改了啊问题出在我们的评论写入流程缺乏基于commit sha去重的机制。解决方案其实很直白。我们在每条评论的body末尾埋入了一个隐藏标记格式类似!-- review-comment-id: {rule_id}:{file_path}:{start_line}:{commit_sha} --。每次推送评论前先通过GitHub API读取该PR已有评论列表解析这些marker如果发现相同rule_id、相同文件、相同行号、但marker里的commit_sha不等于当前head commit的sha就会先调用resolve接口把旧评论标记为已过时然后再决定是否需要发新评论。这种做法带来的效果是评论列表始终反映最新commit的状态。过时的评论不会被删除但会明确显示已过时保留修改历史。如果作者在最新commit已经修复了问题那么就没必要再发新评论旧评论保持过时状态即可。这里面还有一个细节GitHub的评论列表API默认不会返回resolved状态需要额外加stateall参数。这个坑让我们排查了小半天后来在API文档的小字里才看到。如果你也在做类似集成建议直接把stateall写死在查询逻辑里别用默认值。5. 落地数据、团队反馈与后续规划5.1 运行两个月后的实际效果open-code-review在团队内正式运行了大概两个月我统计了一些数据说几个对团队有意义的静态问题和规范问题占比从人工评审总数的38%下降到11%。也就是说过去人工评审要花三分之一以上的时间去挑拼写、命名、异常处理的毛病现在这些大部分由机器人提前筛掉了。PR平均首次评审响应时间从6.2小时降到了1.5小时。机器人几乎在push后30秒内就给出首轮自动化反馈作者不需要等人类评审人上线。训练集外的自定义规则数达到了17条全部由团队同事通过插件协议自己编写维护成本和代码评审工具本身完全解耦。第一个数据说明自动化确实解放了人力第二个数据说明速度提升不只是因为快而是通过减少来回沟通轮次实现的第三个数据才是这个项目长期走下来的真正底气——如果规则只能由核心维护者添加那这个工具迟早会僵化。5.2 团队吐槽最多的问题误报、噪音、信任感工具跑起来之后团队反馈最多的三个问题也很有代表性。第一个是误报。比如我们不能理解业务上下文有时候会把刻意处理历史脏数据的兼容逻辑判成逻辑分支过多。解决方式是给每条规则都加了suppress指令作者可以在代码中使用特定注释让该条finding沉默并且silence记录会保留在评论里后人看的时候能知道这里为什么被放过了。第二个是评论噪音带来的狼来了效应。刚开始规则比较激进报告了很多低严重级别的风格建议没过多久团队就养成了见到review-bot的评论就点resolved的习惯。这个教训很深刻自动评审工具最怕的不是漏报而是过度报告导致的信任崩塌。后来我们做了一次大调整把所有info级别的问题默认从PR评论中去掉只保留warning和error并建议团队把风格类建议转到离线报告中去看。第三个问题是LLM分析器偶尔会脑补出bug比如把正确的并发逻辑硬说有竞态条件。我们最终加了LLM评论必须引用具体行号与变量名才能保留的过滤器之后脑补类评论少了很多。如果要在你的团队里上LLM评审我的建议是宁可让它完全闭嘴也不要让它给出无法验证的断言。5.3 后续规划规则集市、review策略和学习型阈值关于这个项目接下来的方向我们思考了三件事。第一件事是把插件体系真正做成一个规则集市团队之间可以分享自己写的检查规则。比如同一套技术栈的不同团队经常会遇到完全相同的团队规范类问题这些规则积累下来对社区的价值比单纯的静态分析工具更大。第二件事是支持更复杂的review策略比如根据文件的风险等级动态决定是否需要至少两个人类评审人、是否需要测试变更匹配率达到100%才能合入。目前这些策略更多依赖人工判断我们希望把评审的门禁规则也变成可配置的流水线节点。第三件事是给阈值系统加入学习能力。目前复杂度超过多少算高是写死的常量但不同模块的合理标准是不一样的——配置类文件天然复杂度低而调度引擎复杂度高一些也合理。我们想用历史合入代码为基线自动计算每个模块的复杂度分布然后根据偏离程度来给出告警。这个思路还在验证阶段但方向我觉得是对的。最后再分享一个小技巧。如果你也想在团队里推这类工具不要一上来就追求规则数量多。先让它安安静静地跑上一到两周只报告确定性的、严重级别为error的问题让团队把它当成一个可靠的基础设施。等信任建立起来之后再慢慢放宽规则范围和严重级别。我踩过的坑就是一次性放太多规则导致前两周团队都在疯狂点resolved而不是真的去改代码。工具的价值从来不在于评论多而在于每一句话都值得被认真对待。