1. 从零搭建代码评审工具：为什么我要造这个轮子
代码评审这件事，做过团队协作开发的人都懂——它既是保证代码质量最有效的手段，也是最容易流于形式的环节。我所在的团队前后用过不少方案，从最原始的邮件发patch，到后来各种平台的PR/MR流程，再到一些商业化的代码扫描服务，兜兜转转一圈下来，总觉得差点意思。要么是太重，小项目根本跑不起来；要么是太轻，只能查查格式问题，真正的逻辑漏洞一个都抓不住；要么就是绑定某个平台，换个仓库就得重新配一遍。
open-code-review这个项目，就是在这个背景下动手做的。核心目标很明确：做一个开源的、平台无关的、可插拔的代码评审工具链，既能做静态检查，也能接入大模型做语义级的评审建议，还能输出结构化的评审报告。它适合谁用？我觉得三类人最需要：一是中小团队的技术负责人，想低成本建立代码质量门禁；二是独立开发者，提交前想有个"虚拟搭档"帮忙看一眼；三是对代码评审自动化感兴趣、想自己改着玩的工程师。
这个项目不是要替代人工评审，而是把那些重复的、机械的、容易漏掉的问题先筛一遍，让人把精力集中在架构设计、业务逻辑这些真正需要人判断的地方。下面我会从整体设计、核心模块、实操配置、踩坑经验几个维度，把这个项目的来龙去脉讲清楚。
2. 整体架构设计：模块怎么拆、数据怎么流
2.1 三层架构的划分逻辑
open-code-review在架构上分了三层，这个划分不是拍脑袋定的，而是根据"职责分离"和"可替换性"两个原则推导出来的。
最底层是采集层，负责从不同来源获取代码变更。这里的"来源"可以是本地git仓库的diff、某个平台的PR接口、甚至是一个包含变更文件的压缩包。采集层的输出是一个统一的中间表示——我把它叫做ChangeSet，里面包含文件路径、变更类型（新增/修改/删除）、变更行范围、原始内容和变更后内容。为什么要做这层抽象？因为后面的分析逻辑不应该关心代码是从哪来的，只关心"变了什么"。
中间层是分析层，这是整个项目的核心。分析层又分两条线：一条是规则引擎，跑的是确定性检查，比如命名规范、圈复杂度、重复代码、敏感信息泄露等；另一条是语义引擎，把变更内容连同上下文喂给大模型，让它给出可读的评审意见。两条线的结果最终会合并成一个ReviewResult对象。
最上层是输出层，负责把ReviewResult渲染成不同格式：控制台彩色输出、Markdown报告、JSON结构化数据、或者直接回写到PR的评论里。输出层也是可插拔的，你甚至可以写一个输出插件把结果发到自己的内部系统。
2.2 数据流转的关键设计
整个数据流是这样的：ChangeSet -> Analyzer -> ReviewResult -> Reporter。看起来简单，但中间有几个设计决策值得展开说。
第一个决策是变更的粒度。我一开始想按文件分析，后来发现不行——一个文件里可能改了十处，但只有两处有问题，按文件报会让人抓不住重点。所以最终按变更块（hunk）来切分，每个hunk独立分析，最后再按文件聚合。这样既保证了定位精度，又不会让报告碎得没法看。
第二个决策是上下文的注入方式。语义引擎如果只看变更的那几行，很容易误判——比如一个变量改名，单独看可能觉得命名不规范，但结合上下文发现是为了跟接口对齐。所以我在ChangeSet里额外保留了每个hunk前后各若干行的上下文，默认是前5行后5行，这个值可以通过配置调整。上下文太多会浪费token，太少又容易误判，5行是我实测下来比较平衡的值。
第三个决策是结果的合并策略。规则引擎和语义引擎可能对同一处代码给出不同意见，比如规则引擎说"这个函数太长"，语义引擎说"这个函数逻辑清晰但可以拆分"。合并时我采用的策略是：规则引擎的结果作为"硬性发现"，语义引擎的结果作为"建议"，两者在报告里分区展示，不强行合并。这样用户能清楚知道哪些是必须改的，哪些是参考意见。
2.3 为什么选择插件化而不是一体化
市面上不少代码检查工具是一体化的，装完就能用，但想改点什么就特别费劲。open-code-review从一开始就定了插件化的路线，每个分析器、每个输出器都是独立插件，通过配置文件加载。
这么做的好处有三个。一是技术栈无关，规则引擎可以用Python写，语义引擎可以用任何能调API的语言写，只要遵守插件接口就行。二是按需加载，小项目可能只需要规则引擎，大项目才开语义引擎，不会因为装了用不到的功能拖慢速度。三是易于扩展，团队想加一条自己公司的编码规范，写个几十行的插件就行，不用动核心代码。
插件接口的设计也很简单，核心就两个方法：analyze(changeset) -> findings和report(result) -> output。前者接收变更集返回发现列表，后者接收结果返回输出内容。接口简单的好处是上手快，我让团队里一个刚毕业的同学试着写了个检查TODO注释的插件，半小时就搞定了。
3. 规则引擎：确定性检查怎么做到又快又准
3.1 规则的组织方式与优先级
规则引擎里现在内置了大概三十多条规则，分成了几个大类：代码风格（命名、缩进、行长度）、复杂度（圈复杂度、嵌套深度、函数长度）、安全（硬编码密钥、SQL拼接、危险函数调用）、可维护性（重复代码、魔法数字、注释缺失）。
每条规则都有个优先级，分error、warning、info三档。error级别的规则一旦触发，整个评审流程会返回非零退出码，可以直接用来做CI门禁。warning和info只是提示，不影响流程。这个分级很重要，因为如果把所有规则都设成error，那基本上每次提交都会失败，大家很快就会把门禁关掉，反而失去了意义。
规则的加载顺序也有讲究。我让安全类规则最先跑，因为这类问题最严重，而且通常检查成本低——比如扫一下有没有password = "xxx"这种模式，几毫秒的事。复杂度类规则放中间，因为需要解析AST，相对耗时。风格类规则放最后，因为这类问题最多但最不重要，放最后可以避免它们干扰前面的分析。
3.2 基于AST的检查为什么比正则靠谱
早期版本我用正则表达式做检查，踩了不少坑。比如检查"函数是否过长"，用正则去匹配def到下一个def之间的行数，遇到嵌套函数、装饰器、多行字符串就全乱了。后来改成基于AST（抽象语法树）的检查，准确率一下子提上来了。
以Python为例，用ast模块解析源码后，每个函数定义都是一个FunctionDef节点，节点的lineno和end_lineno属性直接给出了函数的起止行号，算长度就是一行减法的事。嵌套深度也好办，遍历AST的时候维护一个深度计数器，遇到If、For、While、Try这些节点就加一，退出时减一，记录最大值就行。
当然AST也不是万能的。有些检查用AST反而麻烦，比如"行长度超过120字符"，这个直接按行split一下就行，没必要上AST。所以我的策略是：能用简单方法解决的绝不上AST，需要理解代码结构的才用AST。这个原则让规则引擎的整体性能保持在一个不错的水平，一个中等规模的PR（大概20个文件、500行变更）跑完所有规则通常在2秒以内。
3.3 误报处理：让规则引擎不讨人嫌
规则引擎最大的敌人是误报。一条规则如果误报率高，用户很快就会把它关掉，那这条规则就等于不存在。我在误报处理上做了几件事。
第一是支持行内忽略。在代码行末尾加# ocr: ignore或者// ocr: ignore，这条行上的所有发现都会被忽略。如果只想忽略特定规则，可以写# ocr: ignore[rule-id]。这个机制给了用户一个逃生通道，遇到误报不用去改配置。
第二是支持文件级和目录级配置。项目根目录放一个.open-code-review.yml，可以针对特定路径关闭特定规则。比如测试文件通常不需要检查函数长度，就可以在配置里写tests/**路径下关闭function-too-long规则。
第三是定期review规则命中率。我在输出报告里加了一个统计，显示每条规则触发了多少次。如果某条规则长期零触发，要么是规则写错了，要么是项目里确实没这类问题，可以考虑关掉减少噪音。如果某条规则触发特别多但用户总是忽略，那说明这条规则可能太严了，需要调整阈值。
4. 语义引擎：让大模型做代码评审的正确姿势
4.1 提示词设计的核心要点
语义引擎这块，我试过不少提示词写法，最后稳定下来的版本有几个关键设计。
首先是角色设定要具体。不要只说"你是一个代码评审员"，而是说"你是一个有十年经验的Python后端工程师，正在评审一个Web服务的代码变更，关注点包括并发安全、错误处理、资源泄漏和接口兼容性"。角色越具体，模型的输出越聚焦。
其次是输出格式要约束。我要求模型按固定格式输出，每条意见包含：问题位置（文件名+行号）、问题类型（bug/性能/可读性/安全）、严重程度（高/中/低）、问题描述、修改建议。格式约束的好处是后续可以程序化解析，直接渲染成结构化报告，而不是一堆没法处理的自然语言。
第三是要提供足够的上下文。前面说过，每个hunk会带前后各5行上下文。除此之外，我还会把变更涉及的文件路径、项目使用的语言和框架版本、以及该文件的历史变更频率（从git log统计）一并传给模型。这些信息能帮模型做出更准确的判断。比如一个文件最近频繁变更，模型可能会更关注改动的稳定性。
4.2 成本控制：不是每次提交都值得调模型
大模型调用是有成本的，如果每次提交都全量分析，费用很快就上去了。我做了几层过滤来控成本。
第一层是变更规模过滤。如果变更行数少于某个阈值（默认10行），且都是注释或空行变更，直接跳过语义分析。这种变更规则引擎跑跑就够了，没必要动用大模型。
第二层是文件类型过滤。配置文件、锁文件、自动生成的代码，这些通常不需要语义评审，在配置里排除掉。
第三层是缓存机制。对同一个hunk，如果之前已经分析过且代码内容没变，直接复用之前的结果。缓存的key是hunk内容的哈希值，存在本地SQLite里。这个机制在反复评审同一个PR时特别有用，能省下大量重复调用。
第四层是批量合并。如果一次提交涉及多个小hunk，我会把它们合并成一个请求发给模型，而不是每个hunk单独调一次。合并时会在提示词里明确标注每个hunk的边界，让模型分别给出意见。实测下来，合并请求比单独请求能省30%到50%的token。
4.3 结果后处理：把模型输出变成可用的评审意见
模型返回的原始文本不能直接展示给用户，需要做几道后处理。
第一道是格式解析。按约定的格式把文本拆成结构化的意见列表。如果模型没按格式输出（偶尔会发生），就降级处理，把整段文本作为一条"综合意见"展示。
第二道是去重。模型有时会对同一处代码给出多条相似意见，需要根据位置和问题类型去重。去重逻辑是：如果两条意见的文件和行号相同，且问题类型相同，就保留严重程度更高的那条。
第三道是置信度过滤。我让模型在输出每条意见时附带一个置信度分数（0到1）。低于0.6的意见会被标记为"低置信度"，在报告里折叠显示，不干扰主流程。这个机制能有效减少模型"胡说八道"带来的噪音。
第四道是与规则引擎结果交叉验证。如果规则引擎和语义引擎对同一处代码都报了问题，那这条意见的可信度就很高，会在报告里高亮显示。如果只有语义引擎报了，就正常展示。如果只有规则引擎报了，按规则引擎的严重程度处理。
5. 实操配置：从安装到跑通第一个评审
5.1 环境准备与安装
open-code-review是用Python写的，要求Python 3.9以上。安装方式有两种，一种是pip直接装，一种是克隆源码后本地安装。推荐后者，因为方便改代码和调试。
git clone https://example.com/open-code-review.git cd open-code-review pip install -e .装完之后，用ocr --version验证一下。如果提示命令找不到，大概率是pip的bin目录没加到PATH里，检查一下~/.local/bin或者虚拟环境的bin目录。
语义引擎需要配置模型API的访问凭证。在项目根目录创建.env文件，写入：
OCR_LLM_PROVIDER=openai-compatible OCR_LLM_BASE_URL=https://your-api-endpoint/v1 OCR_LLM_API_KEY=your-key-here OCR_LLM_MODEL=your-model-name这里用的是OpenAI兼容的接口格式，市面上大部分模型服务都支持这个格式。如果你不想用语义引擎，这部分可以完全不配，规则引擎不需要任何外部依赖。
5.2 配置文件详解
项目根目录的.open-code-review.yml是主配置文件。一个典型的配置长这样：
version: 1 rules: enabled: - naming-convention - function-too-long - cyclomatic-complexity - hardcoded-secret disabled: - todo-comment config: function-too-long: max_lines: 80 cyclomatic-complexity: max_score: 15 semantic: enabled: true max_hunks_per_request: 5 min_confidence: 0.6 exclude_paths: - "**/*.lock" - "**/migrations/**" output: format: markdown show_low_confidence: false几个关键配置说明一下。rules.config下面可以针对每条规则设参数，比如函数最大行数、圈复杂度阈值。semantic.max_hunks_per_request控制每次请求合并多少个hunk，设太大可能超出模型的上下文窗口，设太小又浪费调用次数，5是我实测比较稳的值。output.show_low_confidence设为false时，低置信度的意见不会出现在报告里，但会记录在JSON输出中，方便事后分析。
5.3 跑通第一个评审
配置好之后，在git仓库里执行：
ocr review --base main --head HEAD这个命令会分析main分支到当前HEAD之间的所有变更。如果想分析暂存区的变更，用ocr review --staged。如果想分析某个具体的commit，用ocr review --commit <sha>。
第一次跑建议先只开规则引擎，确认基础流程没问题：
ocr review --base main --head HEAD --no-semantic输出会是一份Markdown格式的报告，按文件分组，每个文件下列出发现的问题。如果发现问题，退出码是1；没问题退出码是0。这个退出码可以直接用在CI脚本里做门禁。
确认规则引擎没问题后，再开启语义引擎跑一次。语义引擎会慢一些，因为要调API，一个中等规模的PR大概需要10到30秒。如果超时，可以调大semantic.timeout配置。
6. 踩坑实录：那些让我熬夜的瞬间
6.1 编码问题导致的解析失败
项目刚上线时，有个用户反馈说分析某个文件时直接崩溃。我拿到文件一看，是个包含中文注释的Python文件，文件头没有声明编码。Python 3默认用UTF-8，按理说没问题，但那个文件实际是GBK编码的，读取时就抛了UnicodeDecodeError。
这个问题让我意识到，不能假设所有源码文件都是UTF-8。修复方案是在读取文件时做编码探测：先尝试UTF-8，失败后尝试GBK，再失败就尝试latin-1（这个编码不会失败，但可能读出乱码）。同时加了个配置项encoding.fallback，允许用户指定默认编码。
这个坑的教训是：处理用户文件时，永远不要假设编码。类似的还有换行符问题，Windows的\r\n和Unix的\n混用会导致行号计算偏移，后来统一在读取时把\r\n规范成\n。
6.2 大文件导致的内存爆炸
有个用户的项目里有个自动生成的代码文件，单文件两万多行。规则引擎跑这个文件时直接把内存吃满了。排查发现是AST解析的问题——Python的ast.parse会把整个文件解析成一棵巨大的树，两万行的文件解析出来的AST节点数量是百万级的，内存占用轻松上G。
解决方案是加了个文件大小限制，默认超过5000行的文件跳过AST类检查，只做基于行的简单检查。同时在配置里允许用户调整这个阈值。对于确实需要分析的大文件，建议拆分成多个小文件，或者用--exclude排除掉。
6.3 模型返回格式不稳定
语义引擎刚接入时，模型经常不按约定的格式输出。有时候用Markdown表格，有时候用JSON，有时候干脆就是一段散文。这导致后处理解析经常失败。
我试过几种方案。一种是在提示词里加更强的格式约束，比如"必须严格按以下JSON schema输出，不要有任何额外文字"。这招有效果但不彻底，模型偶尔还是会"发挥创意"。另一种是加一个格式修复层，用正则去提取关键信息，能救回一部分。最后稳定下来的方案是双保险：提示词里给一个few-shot示例，展示期望的输出格式；后处理时如果解析失败，再调一次模型，把原始输出和格式要求一起发过去，让它重新格式化。这个二次调用的成本很低，因为输入输出都很短。
6.4 CI环境下的凭证管理
在CI里跑语义引擎时，API key的管理是个麻烦事。直接写在配置文件里肯定不行，会泄露。用环境变量是个办法，但有些CI平台的日志会打印环境变量，还是有风险。
我最后采用的方案是：配置文件里只写占位符，实际值从环境变量读取，且环境变量名可配置。比如配置里写api_key: ${OCR_LLM_API_KEY}，运行时替换。同时在CI脚本里，把key存在平台的secret管理功能里，只在运行时注入，不打印到日志。另外加了个--dry-run模式，不实际调API，只打印将要发送的请求，方便调试。
7. 扩展与定制：怎么把它改成你想要的样子
7.1 写一个自定义规则插件
假设你想加一条规则：检查所有新增的print语句，因为团队规范要求用日志库而不是直接打印。插件代码大概长这样：
from ocr.plugin import RulePlugin, Finding class NoPrintRule(RulePlugin): rule_id = "no-print" severity = "warning" description = "禁止使用print语句，请使用日志库" def check(self, changeset): findings = [] for change in changeset.changes: if change.type != "added": continue if "print(" in change.content: findings.append(Finding( file=change.file, line=change.line_number, rule_id=self.rule_id, severity=self.severity, message=self.description, suggestion="改用 logger.info() 或 logger.debug()" )) return findings把文件放到plugins/目录下，在配置里启用no-print规则就行。插件系统会自动发现并加载。
7.2 自定义输出格式
内置的输出格式有控制台、Markdown、JSON三种。如果想输出成HTML，或者发到内部系统，写个输出插件就行。输出插件的接口更简单，只有一个render(result) -> str方法。
比如要输出成Slack消息格式，可以这样写：
from ocr.plugin import ReporterPlugin class SlackReporter(ReporterPlugin): def render(self, result): lines = [f"代码评审发现 {len(result.findings)} 个问题"] for f in result.findings: lines.append(f"- [{f.severity}] {f.file}:{f.line} {f.message}") return "\n".join(lines)然后在配置里把output.format设成slack，再配一个webhook地址，就能自动发消息了。
7.3 与CI/CD流水线集成
最常见的集成方式是在CI的PR流程里加一步。以通用的CI配置为例：
code-review: stage: test script: - pip install -e . - ocr review --base $TARGET_BRANCH --head $SOURCE_BRANCH --format json > review.json - ocr report --input review.json --format markdown > review.md artifacts: paths: - review.md allow_failure: falseallow_failure: false表示如果评审发现问题（退出码非零），整个流水线失败，PR无法合并。如果只想提示不想阻断，改成true就行。
对于大型项目，建议把规则引擎和语义引擎分开跑。规则引擎快，可以每次提交都跑；语义引擎慢且费钱，可以只在PR创建时跑一次，后续提交只跑规则引擎。
8. 一些实测数据与个人体会
跑了大半年下来，积累了一些数据。在一个大概五万行的Python项目上，规则引擎全量跑一次大概1.5秒，语义引擎跑一个20文件的PR大概25秒。规则引擎的误报率（用户标记为"不是问题"的比例）大概在8%左右，语义引擎的误报率在15%左右。语义引擎的采纳率（用户实际按建议修改的比例）大概40%，规则引擎的采纳率大概65%。
这些数字说明一个事：规则引擎和语义引擎是互补的，不是替代关系。规则引擎擅长抓确定性的问题，采纳率高但覆盖面窄；语义引擎能发现更深层的问题，但噪音也大。两者结合，才能既保证质量又不至于让人烦。
我个人在实际操作中的体会是，代码评审工具最大的价值不在于抓出多少bug，而在于建立一种质量意识。当开发者知道提交的代码会被自动检查，写代码时就会更注意。这种"被看见"的感觉，比任何规则都管用。
最后分享一个小技巧：如果你的团队刚开始用这类工具，建议先把所有规则设成info级别，只提示不阻断，跑两周看看大家的反馈。等大家习惯了，再把重要的规则逐步升级到warning和error。一上来就设成error，大概率会被集体抵制，最后工具就闲置了。
