open-code-review：用规则引擎和AST让代码评审聚焦真正问题

“open-code-review”这个项目名，我最早是在一次内部技术分享的选题清单里看到的。当时第一反应很简单：代码评审，不是有GitLab MR、GitHub PR自带的Review功能，再加上SonarQube这类静态扫描工具就够了？还需要什么“开源代码评审”？直到我连续三周被无效评审意见轰炸，才意识到这件事没那么简单——评审环节里真正浪费时间的地方，根本不是“看代码”本身，而是大量的“确认性劳动”：改个变量名要重新看一遍，删除一个废弃函数要确认没有别处引用，缩进风格不一致要反复讨论。这些工作，拼的是耐心，不是判断力。

open-code-review就是冲着这些“低技术含量的确认”去的。它是一个开源的、本地优先的代码评审辅助工具，核心思路是：把评审人员从重复规则校验中解放出来，让他们只盯真正需要人类判断的东西。本文就从这个项目的设计过程讲起，把整体的工作流、规则引擎、关键实现、接入方式，以及我在实测中踩过的坑完整复盘一遍。

1. 为什么我会动手写一个开源的代码评审工具

1.1 评审现场的真实痛点

先说一个我自己的数据。我抽查过所在团队过去两个月的MR评审记录，三十多个合并请求里，评审意见大致可以分三类：

也就是说，真正需要资深工程师花时间深度思考的评审意见，只占四分之一。剩下四分之三，要么是规则执行，要么是搜索确认。这两类工作非常适合自动化处理。而且有一个很微妙的点：风格和低风险确认类意见，反而最容易引发情绪摩擦。因为人看代码时偶尔会看漏，被打了“这个没看到”的标签，双方都不舒服。工具就没有这个问题——规则是稳定的，意见是统一的，没有人格受损。

open-code-review这个工具的定位，正是从这75%的重复劳动里切一刀。它不是要替代Code Review里“人”的部分，而是把人的精力重新分配到那25%上。

1.2 与商业工具的反差定位

做之前我对比过SonarQube、CodeRabbit、ESLint这类方案，它们确实是成熟产品，但实际用起来有几个让我不太舒服的地方：

• 商业平台的自动评审依赖云端跑分析，代码出网这件事在很多团队是红线。
• 通用扫描器面向“全量代码”，但评审场景实际上更关心“这次变更引入了什么问题”。
• 无论是Sonar规则还是ESLint规则，学习成本曲线很陡，普通业务团队想定制一条团队专属规则，往往要查半天文档。

open-code-review刻意做了几个反方向的选择：

• 本地优先，只在需要生成MR评论时才会调用Git平台API，代码文件本身不出本机。
• 变更感知，核心分析对象是提交的diff，不是整个代码库。
• 规则即代码，一个规则就是一个Python文件，团队想加自己的规则，直接写一个函数就行，不需要理解编译器原理。

这些取舍让它在“个人项目”和“中型团队内部工具”之间找到了一个很舒服的位置：不追求大而全，只求在评审流程的“变更检查”这个环节做得顺手。

2. open-code-review的整体工作流设计：一次评审请求如何被拆解

2.1 从git diff到评审对象的构建

整个工具的核心入口不是目录扫描，而是git diff。原因很简单：评审关注的是变化，不是全局。全量扫描一个大仓库，执行时间动辄几分钟，而且会产生大量和本次变更无关的历史噪音。

open-code-review的执行流程分成四个阶段：

1. 收集变更信息：通过git相关命令拿到本次变更涉及的变更行、变更文件列表、提交信息。
2. 构建基础对象：每条变更记录会形成一个ChangeFile对象，包含文件路径、变更前后的内容、每个变更行的具体位置、变更类型。
3. 运行规则管线：所有规则按优先级与适用语言匹配，对变更对象逐个执行。
4. 汇总输出：按规则命中情况生成结构化结果，再根据输出格式渲染成终端表格、JSON或Markdown评论。

这里最容易出错的是第一步。git diff默认输出的hunk信息只包含块头行号，但一个hunk里“被修改的行”“仅新增的行”“仅删除的行”是混在一起的。open-code-review在解析时会逐个字符对照新旧内容，把行号映射关系算清楚。这个映射表是整个工具的地基：后续所有规则做“行级分析”时，拿到的都是准确的变更行定位，不会出现“提示在第20行，实际位置在第35行”的偏移问题。

2.2 规则执行管线与输出协议

规则执行不是简单地把所有规则遍历一遍这么简单。每个规则有自己的适用场景，盲目遍历会导致一个Python项目被Java规则误报。所以open-code-review在规则定义阶段就要求写明目标语言和触发条件。

规则执行管线我设计成类似Web中间件的模型。每个规则是一个独立的处理器，接收一个ChangeContext对象，可以读取变更前的旧代码、变更后的新代码、变更行集合以及配置项。规则执行完以后把结果写进一个共享的Finding数组。

整个管线的顺序很重要，它分三个阶段：

• 轻量规则先跑：命名规范、文件结构、提交规范这类只需要字符串和文件名就能判断的规则，执行成本最低，先跑完形成基础结论。
• 重量规则殿后：AST分析、语义分析、复杂度计算这类需要解析代码结构的规则，只在有增量变化时触发。
• 聚合规则收尾：有些问题单看一个点是发现不了的，比如“变量声明了但从未使用”需要跨行追踪，“重复代码片段”需要跨文件比对，这类规则依赖前面两个阶段已经产出的中间数据。

输出侧做了两层设计。底层统一输出JSON结构，每个Finding包含规则ID、严重级别、文件路径、起始行、结束行、消息、置信度、修复建议。上层通过不同的渲染器把JSON转成人类可读的格式。

正是这套“阶段化执行 + 结构化输出”的架构，让后面添加新规则变得非常轻松。我后边接入团队内的“禁止继续使用某个废弃SDK”这种规则，只用十几行代码就搞定了。

3. 规则引擎与规则定义：可配置不等于弱智能

3.1 规则的三层结构：元信息、触发器与修复建议

open-code-review的规则文件由三部分组成，这是我参考了多种Lint工具规则设计后定下来的一种“既简单又完整”的组合方式。

第一层是元信息。包含规则ID、规则名称、目标语言、严重级别、所属类别、默认开关、说明文档。这一层的作用有两个：一是方便在配置里精确开启或关闭某条规则，二是让评审意见的展示带上上下文，别只扔一句“有问题”就完事。

第二层是触发器。触发器决定这条规则在什么时候被激活。模型很直白：

• 文件级触发器：文件名匹配某种模式时触发。
• 变更级触发器：存在新增代码或删除代码时触发。
• 提交级触发器：提交信息或变更文件集合满足条件时触发。

触发器判定通过之后，规则的核心逻辑才会执行。这样设计的好处非常明显——规则逻辑只需要关注“怎么查问题”，不需要自己处理“要不要查”的判断。

第三层是修复建议。这一层容易被忽略，但实际使用时它体现的价值比检测还大。open-code-review规范要求每条规则必须提供至少一条可执行的修复建议。可以是一段示例代码，也可以是一条操作命令，甚至是“去参考哪个文件里的既有写法”。评审人员拿到报告时，不用再凭经验去猜提交者应该怎么改。

3.2 内置规则的取舍思路

工具内置的规则集合，我没有贪多，只挑了几类使用频率高、误报率低的方向：

• 变更安全规则：检测新增代码里是否出现危险API调用、硬编码秘钥、拼接执行的命令。
• 提交规范规则：检查提交信息是否符合约定式提交格式，变更是否包含调试残留。
• 命名与结构规则：检测新增文件和函数的命名风格，文件目录层级是否符合项目约定。
• 跨行逻辑规则：检测变量声明后是否被使用、导入模块后是否被引用、异常是否被吞掉。

每条内置规则都遵循一个原则：宁可漏报，不可误报。漏报最多让人疑惑“为什么没查出来”，但误报多了，工具的权威性就会被透支，最后大家干脆不看报告了。这类人心问题，比技术问题难修得多。

3.3 编写自定义规则的最小示例

自定义规则的开发方式是open-code-review最核心的扩展能力。给团队加一条“禁止新增代码中出现调试字符串”的规则，完整过程是这样的：

创建一个Python文件，放到rules/custom/目录下：

# rules/custom/debug_marker.py DEBUG_MARKERS = [ "temp_debug", "print(", "TODO_DEBUG", "debugger", ] class DebugMarkerRule: rule_id = "CUSTOM-DEBUG-MARKER" name = "检测调试残留" languages = ["python", "javascript", "typescript", "go", "java"] severity = "warning" categories = ["maintainability"] enabled = True def analyze(self, context): findings = [] if not context.has_added_lines(): return findings for line_no, line in context.iter_added_lines(): for marker in DEBUG_MARKERS: if marker in line: findings.append(context.build_finding( severity="warning", line=line_no, message=f"发现疑似调试残留: \"{marker}\"", fix_suggestion=f"确认是否还需要该语句，建议删除或替换为日志框架的正式用法", )) break return findings

配置文件里认到这个类以后，它会自动出现在规则列表里。这个接口设计的核心考量是：规则作者不需要理解AST、不需要知道diff的内部结构，只要会遍历新增行、会做字符串匹配，就能写出一条有用的团队规则。

规则引擎这套“元信息—触发器—逻辑—建议”的模型，在实际使用中经受住了考验。团队里非后端背景的同事也能快速上手，这比我预想的要好得多。

4. 关键实现细节：AST扫描、污点判断与置信度计算

4.1 基于AST的增量扫描方式

字符串匹配能解决的问题非常有限，稍微复杂一点的检测，比如“新增代码里是不是有一个函数把它收到的参数直接拼接进了SQL”，就必须上AST了。但AST扫描在评审场景里有一个绕不开的问题：性能与精度的矛盾。

如果把整个仓库都解析成AST再遍历，那个耗时是任何开发流程都无法接受的。open-code-review的做法是“增量AST解析”：只对变更涉及的文件做全量解析，然后在AST树上定位变更行对应的节点，再从这些节点向上或向下收窄分析范围。

举一个实际的例子。

# 变更前 def get_user(uid): return db.query("select * from user where id = " + uid) # 变更后 def get_user(uid): sql = "select * from user where id = " + uid logging.info(f"query user, sql={sql}") return db.query(sql)

变更只加了两行，但问题其实是“用户可控参数拼进SQL”这个整体模式。open-code-review在AST上做的是：先找到新增行对应的Call节点，然后向上找它的函数定义，再找到函数参数中所有被调用点用到的变量，如果这些变量参与了SQL字符串的构造，就命中规则。

这种做法的好处是：规则理解的是代码语义，不是文本特征，所以不会因为有人在字符串里插了个空格就漏掉问题。

4.2 污点路径截断与误报治理

AST能做的另一件事，是实现简单的污点跟踪。所谓“污点”，指的是“来源不可信的数据”。在安全类规则里，用户输入、环境变量、外部API返回值都属于污点源。如果这些数据未经清洗就进入了危险函数（比如SQL执行、命令执行、文件路径拼接），就是一次潜在漏洞。

但是直接全局跟踪污点路径，在真实代码里会走火入魔。一个典型场景是：函数A拿到用户输入后没有做任何处理就传给函数B，函数B里其实有安全校验，但工具只看到了“A把数据传给了B”，就会报一个“SQL注入风险”。这就是污点路径没有被正确截断导致的误报。

open-code-review在污点跟踪里做了一个“路径截断”机制。当遇到以下情况时，污点传播自动终止：

• 数据经过加密、哈希、格式化转换等明确处理操作。
• 数据被断言为非预期类型或加入白名单校验。
• 数据被传入一个被标记为“安全处理函数”的包装函数。

这个思路有点像我后来在不少安全扫描产品里看到的“净化函数”概念：工具不得不在“发现更多问题”和“避免吓唬人”之间做平衡，而截断机制就是这种平衡的最直接体现。

4.3 置信度怎么算才不脱离实际

评审工具的一个特殊之处在于：它给出的意见不是一个二值结果，而是一个带置信度的判断。置信度高的意见可以直接进CI门禁，置信度低的意见只能作为“建议”输出。置信度设置不好，会直接影响整个工具的可信度。

open-code-review内部用一套简单的分数模型计算置信度，大致由三部分组成：

• 规则自身的确定性，比如“提交信息缺少前缀”这条规则，确定性高，置信度接近1。
• 分析的深度，比如“该调用是否危险”这类问题，纯文本匹配只能给低置信度，AST分析给中等置信度，污点路径完整跟踪可以给高置信度。
• 上下文佐证，比如检测到“新增导入了一个模块但没使用”，如果能同时确认这个模块不会再被后续代码引用，就可以给更高的置信度。

分数最后映射成三个档位：high、medium、low。CI脚本在决定是否拦截时，通常只把high级意见作为硬性门禁。这个设计非常关键——它承认了工具能力的边界，把拿不准的判断交给人类。

5. 接入Git工作流：从pre-commit到CI机器人

5.1 本地pre-commit阶段的快速检查

接入的第一步，我推荐从pre-commit钩子开始。理由很简单：一个问题在本地发现的成本，比在CI发现要低十倍——本地发现只需要改代码，CI发现还得提交、推送、等任务跑完、再看日志。

open-code-review在pre-commit里的角色是“守门员”，只跑耗时短、确定性高的规则，比如提交信息规范、调试残留检测、文件命名检查。我把这组子集的耗时控制在几百毫秒以内，完全不影响开发节奏。

在项目根目录的.pre-commit-config.yaml里接上：

- repo: local hooks: - id: open-code-review-fast name: Open Code Review (fast subset) entry: open-code-review precommit language: system stages: [commit] files: \.\b(py|js|ts|go|java)$

precommit子命令内部只加载category = "fast"的规则，跳过所有需要AST分析的重量规则。这样既保证了速度，又给开发者留出了一个“快速反馈循环”。

5.2 在GitHub Actions/通用CI里的接入

本地钩子拦不住所有问题，所以还得在CI里接入完整版本。在CI里的运行方式上，open-code-review支持两种模式：

一种是输出报告制作为构建步骤的产物。GitHub Actions的用法是：

- name: Run Open Code Review run: open-code-review scan --base origin/main --output sarif - name: Upload SARIF to code scanning uses: github/codeql-action/upload-sarif@v2 with: sarif_file: review-results.sarif

这个模式适合把结果直接合入GitHub原生的Code Scanning面板，问题会像普通告警一样出现在Security选项卡里。

另一种是评论模式。open-code-review解析完diff之后，调用Git平台的评论API，在变更行旁边逐条贴出评审意见。这种模式最接近人工评审的体验，团队成员在MR页面上就能讨论每条意见。需要额外配置一个带有API权限的Token供CI使用。

实际接入时我建议先只开warning级别，保持运行一周，统计误报率，确认噪声可控以后再打开error级别作为合入门禁。

5.3 评审结果在不同平台上的落地细节

GitHub和GitLab的评论接口有细节差异，这是接入时的一个小坑。

Git的评论接口审查位置信息需要提交SHA、文件路径、行号三者完全准确，只要有一点偏差，评论就挂不上去。open-code-review在提交评论前会拿着变更行号的范围去和最新版本的diff做一次交叉验证，确保行号仍然有效。因为评审期间源分支可能又有了新提交，之前算出来的行号可能已经偏移了。

另外就是评论粒度。我见过有些工具把问题一条评论一个通知，结果一次评审发出三四十条评论，直接把通知渠道淹没了。open-code-review默认按文件聚合，每个文件最多生成一条汇总评论，内部用列表逐条列出问题。评论数量降了一个数量级，大家反而更愿意看。

6. 实测中的一次误报排查：完整链路复盘

6.1 症状：评审机器人开始“暴怒”

在open-code-review接入团队的第二周，我收到一条相当刺眼的消息：一条新增规则“sql-injection-scan”开始大量命中——一次评审里报出了19条SQL注入风险。团队的人第一反应是“这不可能是真的”，因为那只是一个查询用户信息的内网工具，接口根本没有暴露到公网。

如果是人工评审，看到这条消息的第一反应往往是相信工具。但19条命中的密度太异常了，更像规则本身出了问题。我决定顺着工具的执行日志把链路一层层拆开。

6.2 定位：从规则命中到路径追踪

第一步先看规则日志。open-code-review的规则如果开启了trace模式，会记录污点传播的完整路径。打开一条命中的trace，我发现污点的来源标注是“read_config()”函数返回值。

这就很可疑了。read_config()读的是本地配置文件，配置是由运维统一维护的，根本不涉及用户输入。继续往下看污点路径，工具判定read_config()的返回值流向了SQL拼接点。但中间经过了一个clean_query()函数。按我之前设计的“路径截断”机制，经过clean_query()应当截断传播才对。可问题就出在：clean_query()没有被识别为净化函数。

第二步查原因。open-code-review识别净化函数的机制有两种：一是内置的常见净化函数库，二是配置文件中人工标记的净化函数列表。打开内置库，发现它只包含类型转换类的函数，而团队里这个clean_query()是自研的、名字里带clean但没有被识别。

第三步确认逻辑。看懂代码以后发现，clean_query()内部确实做了参数类型检查和白名单校验，符合净化函数的语义定义。工具最大的问题在于：它不知道这个函数是“安全处理过程”，只凭“字符串被传入了一个函数再返回”这个特征，就继续追踪污点。

6.3 修复：规则语义收紧与基线抑制

排查完以后，不只改了这一个案例，而是同时做了三个动作：

第一个动作是立即止损：在项目配置文件里把clean_query()显式标记为净化函数。

security: sanitizers: - "clean_query"

第二个动作是修复规则的判断逻辑。sql-injection-scan这条规则不再盲目跟踪所有“字符串拼接 + 调用执行函数”的路径，而是增加了一个“净化函数白名单校验”环节：在污点到达危险函数之前，如果经过了任意不在危险列表里的包装函数，就降低置信度等级，从high降到medium。这样即使在净化函数识别上漏了，也不至于直接触发拦截门禁。

第三个动作是建立基线抑制机制。对历史存量代码中已经存在的问题，工具不应该反复报错。open-code-review里增加了一个静态基线文件，记录“当前可接受的问题清单”。只有新出现的、不在基线里的问题才会进入评审报告。存量问题会被归档整理，由团队定期单独处理。

这次排错给我最大的启示是：误报在工具上线早期几乎是必然的。关键是工具要提供足够的观测手段——规则日志、污点路径、置信度分数——让人能在几分钟内定位到根因，而不是把整个规则库关掉了事。

7. open-code-review的性能与轻量化取舍

7.1 一次典型扫描的耗时分布

用工具最怕的是“慢”。我拿一个中小规模的仓库做了测试，一次变更涉及60个左右的变更文件，大约1100行新增代码，完整扫描的耗时分布大致是这样的：

整个流程大概在3秒左右。作为CI流水线里的一个环节是可以接受的。但去掉AST解析这个大头，结果会快很多——纯文本规则和提交规范检查完全可以在500毫秒内跑完。

7.2 缓存、并行与语言插件化的取舍

AST解析为什么占了大头？因为它涉及词法分析、语法分析，还要把代码转成内部对象模型，这个操作确实不轻松。为了优化它，我做了三件事：

• 按文件路径做缓存：同一文件在短时间内多次评审，AST结果直接复用，不用二次解析。
• 按变更文件数量做并行：变更文件多的时候，idle的CPU足够多，并行度提到4到8，可以有效压缩耗时。但并行也会带来一个问题：多个规则同时写同一个Finding列表会有竞争，所以并行时每个worker先写自己的局部列表，最后再合并。
• 语言插件化：不同语言的AST解析差异太大。open-code-review内置了Python、JavaScript、Go、Java的解析器插件，只加载当前变更文件对应的语言插件。不需要解析所有语言，速度和内存都大幅下降。

7.3 什么时候别用它

工具做出来以后，我也必须说清楚它的边界。

open-code-review不适合处理架构层面的评审。模块依赖是否合理、系统边界是否清晰、扩展点是否留对，这类问题需要结合业务上下文做价值判断，不是靠规则能推出来的。它在帮助人类评审员缩小范围——告诉你“这几个文件之间的耦合可能有问题”，但到底是不是问题、怎么重构，还是需要人来回答。

其次，它也不适合作为唯一的质量门禁。如果你把它的报告当成代码合入的唯一标准，规则会逐渐变成代码的“形状约束”，开发者会针对性地写出“让工具满意”但设计混乱的代码。这种情况在其他静态分析工具里已经出现过了：规则越来越多，代码越来越“规矩”，但真正高级的问题反而被规则文本淹没了。

open-code-review的设计哲学里反复强调了那个比例：自动化解决75%的重复确认，剩下25%的判断留给人。一旦越界，工具就会从助手变成局限。

8. 演进方向与个人体验总结

open-code-review目前的版本已经能稳定处理我所在的开发流程，但我个人最满意的一点，反而是它的“本地优先”和“规则即代码”这两条路线。这种路线选择让工具始终没有变成黑盒：任何一个评审结果，都能追溯到具体规则和执行路径。团队成员提出“这条规则为什么报错”的时候，我们直接看规则文件，问题就明朗了，不需要把工具当权威来辩解。

现在我在计划的下一个扩展方向，是把规则运行产生的中间结果导出成统一的“评审知识库”。把团队历史上被人工评审挑出的典型问题、当时的讨论结论、最终修复的代码样本，回流成规则集和修复建议库。这样每次评审就不只是一次代码检查，同时也是一次团队经验的沉淀。

做这个项目最深的体感是：开源代码评审工具的技术难度，不在于某个算法的复杂度，而在于如何克制它自身的“建议冲动”。评审工具要清楚什么事该管、什么事不该管，要知道哪些话说了会被听、哪些话说了只会变成噪声。这其实是一个工程判断问题，设计上花的心思，比写规则本身要多得多。如果你也在为团队评审噪声头疼，不妨从最痛的一条规则开始试试，先让它跑起来，再慢慢打磨。