代码审查这个东西只要带过十来人的团队就会有体会靠人眼盯 diff既慢又不全面尤其遇到跨模块改动reviewer 经常只能凭经验猜。上个月我在一批开源工具里翻到 open-code-review它对“AI 代码审查”这件事的处理方式让我重新校准了预期。它不是简单地把 diff 丢给通用大模型然后等点评而是先把整件事拆分得很清楚用确定性流水线负责收集事实和执行可复现的规则检查只在真正需要语义判断的地方引入 LLM Agent。这种“确定性流水线 LLM Agent”的混合架构正好解决我这两年最头疼的两个问题纯静态规则太吵纯大模型太不稳定。这篇文章我想从工程实践的角度把这个混合架构一层层剥开。你会看到每个环节到底解决什么问题、关键参数怎么定、为什么这个设计能跑进 CI/CD以及落地时最容易踩哪些坑。无论你是在选型阶段还是已经跑过几轮 AI 审查这篇文章都值得收藏后慢慢对照。1. 为什么代码审查需要“工程化”纯规则与纯 LLM 的死穴1.1 静态工具的问题不是不够准而是太“吵”静态分析工具如 ESLint、golangci-lint、SpotBugs、CodeQL它们的准确度其实并不差差的是“表达方式”。这些工具擅长把一类固定模式从代码里找出来比如空指针解引用、硬编码密钥、危险函数调用。问题在于它们没有业务上下文所以经常报出一堆“理论上可能有问题但实际调用路径永远走不到”的告警。我见过很多团队第一天把规则集开到最大然后被几百条告警淹没第二天默默把大部分规则关掉。这不是工具本身不行而是没有给它们设计“谁来最终判断”的环节。静态工具适合做粗筛和前置拦截但不适合直接跟开发对话。它缺的不是规则数量而是一个能解释规则、过滤误报、判断真实影响的下游环节。1.2 纯 LLM 审查生成式模型的不确定性被低估了把 diff 直接扔给 ChatGPT 或者 Claude 让它“找问题”第一眼很惊艳用过几轮就发现不对劲。同一个 diff今天跑和明天跑输出结果可能差很多它会引用代码库里根本不存在的方法名它还会把“这里可能有隐患”表达成“这里必须改”语气笃定但理由经不起深挖。更深层的问题是可解释性。LLM 给你一条“建议引入缓存”但它不会告诉你依据的是哪条调用链、哪个历史 bug、哪种并发模型。如果审查报告中每一条都需要人去验证那 AI 审查节省的时间就被验证成本抵消了。纯 LLM 方案还面临成本失控和上下文窗口不足的问题大 diff 尤其明显。1.3 open-code-review 的设计思路把“感知”和“判断”拆开open-code-review 的核心设计哲学可以归结为一句话不要用大模型做一切事。确定性流水线负责“感知”——拿 diff、解析 AST、跑静态规则、聚合相关上下文、把信息归一化成结构化对象LLM Agent 负责“判断”——理解语义、评估风险、给出修复建议、解释规则命中到底是不是误报。这种拆法不是简单的两种工具串联而是每个环节都有严格的输入输出契约。流水线输出的是“待审事实”Agent 输出的是“带置信度的判断”。规则能覆盖的东西不交给模型模型只处理规则覆盖不了的那部分。这样做最大的好处是审查流程变得可复现、可审计、可渐进式改进。每发现一个高频误报你就能把它沉淀成一条新规则模型要处理的脏活越来越少。2. 确定性流水线承担什么从 diff 到“待审事实”2.1 主流程设计拆 diff、拆函数、拆审查单元确定性流水线的第一件事是把一次 PR 的改动拆成小颗粒度的“审查单元”。当你执行git merge-base拿到基础提交点再用git diff获取变更内容之后流水线会逐个文件扫描变更行定位这些行落在哪个函数、哪个类、哪个模块里。为什么要拆因为一个大 PR 可能涉及 30 个文件、几百个函数如果整包喂给 LLM上下文必然超限而且模型很难聚焦。拆成审查单元之后每个单元独立走审查流程结果最后再合并汇总。这跟微服务拆分的思路一样把一个大问题变成多个可以单独处理的小问题任何一个环节失败都不会拖垮整个审查任务。每个审查单元在内部会保存这些信息文件路径、变更起始行和结束行、变更所属函数签名、函数前后的完整代码片段、以及 diff 中新增和删除的行。这些东西全部用结构化 JSON 表示不包含任何主观判断。流水线在这一步只回答“改了什么”不回答“改得对不对”。2.2 规则引擎和静态扫描的位置不是用来直接阻断在拆完审查单元之后流水线会跑一遍静态规则引擎。这部分基本是确定性的规则命中就是命中没命中就是没命中没有中间态。规则覆盖的范围可以很广比如未使用变量、危险正则表达式、SQL 拼接、不安全的反序列化、依赖版本漏洞、圈复杂度超标等。关键设计在于规则引擎的输出不会直接变成“阻断合并”的红灯而是作为“标签”挂在审查单元上。例如规则检测到一个疑似硬编码的 AWS AccessKey这个标签会附带行号和匹配片段但它不会直接判定“这一定是一个泄漏事故”。这个标签会随着审查单元一起送给下游的 LLM Agent由 Agent 结合上下文判断这是真实的生产密钥还是测试环境的示例数据。这么做有一个很实际的好处如果 Agent 不在场或者模型服务超时确定性规则仍然可以作为兜底防线。规则引擎的标签体系本身也让报告更容易被开发团队理解因为每条 Agent 结论下方都能追溯到具体的规则命中记录。2.3 上下文聚合LLM 审查质量的分水岭我一直认为LLM 代码审查效果好坏七成取决于喂给它的上下文三成才取决于模型本身。如果你只给模型一段孤立的新增代码它只能基于通用编程知识推断效果自然差。open-code-review 的上下文聚合模块会为每个审查单元收集相关信息。典型的信息包括变更函数的相邻代码、直接调用方和被调用方的定义、相关测试用例、PR 描述、commit message、以及代码库中同类模式的其他实现。这里面最重要的信息是调用方和被调用方。一个函数本身看起来没问题但它的调用方在循环里高频触发或者被调用方在有锁的情况下又去拿锁问题就藏在跨函数关系里。上下文聚合还要考虑 token 预算。我给内部项目定的经验值是单个审查单元的上下文尽量控制在 6k token 以内其中 diff 原文占 1k 到 2k剩余空间给相邻代码、调用关系和规则命中标签。如果上下文太多模型注意力会被无关内容稀释反而漏掉真正的问题如果太少模型只能凭空猜测产出自然不接地气。2.4 哪些任务留在确定性侧哪些交给 Agent判断标准其实很简单凡是有标准答案的任务都留在确定性流水线里凡是需要理解业务意图、权衡取舍、解释因果关系的任务才交给 LLM Agent。举一个实际的例子。检测“循环内调用数据库查询”这种 N1 问题静态分析可以非常准确地定位到循环体里的查询语句这就是确定性部分能做的事。但“这次查询是不是真的会被执行 N 次”“这 N 次查询有没有可能命中同一个缓存”就需要 LLM 结合上下文判断。流水线先列出所有候选位置Agent 再评估其中哪些真正构成性能瓶颈这样既避免了遗漏也避免了模型漫无目的地扫描代码。这条分界线不是一成不变的。随着业务沉淀你会发现自己能总结出越来越多的确定性规则。我的经验是每周抽时间把 Agent 的高置信度误报案例转成新规则分界线会不断向确定性侧移动系统的成本也随之下降。3. LLM Agent 的语义审查环节从 prompt 到结构化报告3.1 不要让一个 Agent 干所有人的活很多人做 AI 审查时只写一个大 prompt让模型既当静态分析器、又当安全审计员、还当架构评审专家。这种“全能 Agent”看着省事实际效果很平庸。open-code-review 的做法是拆成几个职责单一的 Agent它们共同协作完成一个审查单元。我常用的角色分配是三份主审查员负责评估整体语义正确性和潜在缺陷规则解释员负责核对流水线命中的每一条静态规则判断是真阳性还是误报并给出理由修复建议员负责把高风险问题转成可执行的补丁或具体修改建议。三个 Agent 共享同一个审查单元但 prompt 侧重点完全不同输出也会被约束到同一个统一 schema。每个 Agent 的系统提示词都要强调一件事只能基于给定上下文输出结论不能脑补不存在的 API 或编程约定。我在提示词里还会加一句“如果信息不足明确说信息不足不要猜测”这句话对降低幻觉有立竿见影的效果。3.2 温度参数与输出约束稳定性的第一道锁大模型天生的随机性无法完全消除但可以把影响压缩到可接受范围。open-code-review 在处理审查任务时通常把温度设在 0.1 到 0.2 之间。温度越低输出越保守越接近确定性模式温度太高就会开始创造不存在的“风险”。但只调温度远远不够。Agent 输出必须被约束为结构化 JSON字段包括 severity、category、line_range、description、confidence、suggestion 等。所有枚举字段都必须在系统提示词里明确定义比如 severity 只能是 critical、warning、info、nitpick 四种不允许模型自创一个 high_critical。输出拿到手之后流水线还会做一层后处理校验line_range 必须与 diff 中的变更行号有交集否则丢弃suggestion 如果是代码片段必须能通过基本语法解析。这些校验规则是确定性侧对模型侧的一种“强制校准”确保模型没有跑偏。3.3 多轮工具调用让 Agent 自主补齐缺失信息单轮问答很难做好代码审查因为模型经常发现自己缺少某段代码或某个调用信息。open-code-review 的 LLM Agent 支持函数调用也就是让模型自主决定要不要继续收集信息。主审查员可以请求调用get_diff_stat、get_file_content、search_symbol、read_test_case、run_lint等工具拿回结果之后再继续分析。这套循环的退出条件非常重要。我建议每个审查单元设置最大轮数为 5 轮单次 Agent 总耗时不超过 60 秒。一旦达到上限直接把当前已收集的信息做成报告标记为“部分信息未覆盖”。不要等它自己结束因为模型天然倾向于多调用几次工具哪怕信息已经足够。工具调用日志也要记录在案这样你能复盘每个结论是基于哪些代码产生的报告才能追溯。3.4 成本与延迟控制混合架构必须算经济账聊完架构必须聊聊钱。确定性流水线部分几乎是零成本但 LLM Agent 的 token 消耗不能不算。按我的估算每个审查单元跑完多轮 Agent大约消耗 3k 到 8k token。一个改动量在 200 行左右的中型 PR拆出 30 到 60 个审查单元总消耗可能达到 20 万到 50 万 token具体取决于上下文聚合的策略。好在 open-code-review 做了三个省钱设计。第一是增量审查只审查新增和修改的行没有改动的历史代码一律不送进 Agent。第二是缓存对文件 hash 加 diff hash 做组合键审查过的单元直接命中缓存结果。第三是分级模型规则标签解释等轻量逻辑用便宜的小模型只有分析关键语义路径时用强模型。接入 CI 时还可以把 LLM 审查改成异步队列避免开发人员每次提交都干等几十秒。4. 实操记录一条 diff 走完整个流水线会发生什么4.1 环境准备与最小配置下面以一个自托管部署的 open-code-review 为例跑通一个最小可用的静态审查流程。假设你有一个 git 仓库安装了 Python 3.10并且有可用的 OpenAI 兼容 API 端点。把项目克隆下来之后先准备一份open-code-review.yml配置文件内容大致是repository: base_branch: main ignore_paths: - *.lock - vendor/** - dist/** rules: enabled: true profile: security-plus tags: [security, performance, style] llm: provider: openai-compatible model: gpt-4o-mini temperature: 0.2 max_tokens: 2048 agent: max_rounds: 5 timeout_seconds: 60 confidence_threshold: 0.6 cache: enabled: true expire_hours: 24 report: format: json output_dir: ./review-reports这里的confidence_threshold是我的个人习惯。低于 0.6 的结论不进入最终阻断判断只显示在“待人工复核”列表里。温度设成 0.2 而不是 0是为了保留一点语言多样性同时不让模型过于跳跃。刚开始接入时不要急着启用中断合并先把报告跑起来让大家适应改造后的流程。4.2 从提交到审查报告的完整命令链路配置写好后你可以在本地直接跑一次审查。我先从主干开一条分支改一个带有明显问题的函数然后提交git checkout -b fix/order-cache # 这里修改代码比如给订单查询函数加了一个本地缓存但没有做并发保护 git add . git commit -m fix: cache order list to reduce db load open-code-review review --diff main...HEAD --report json命令执行后open-code-review 会先调用git diff拿到变更内容然后进入流水线处理。处理过程中终端会打印每个审查单元的进度和状态比如规则命中数、上下文聚合耗时、Agent 调用轮数。最终结果生成到./review-reports/report.json同时会输出一个简短的摘要告诉你有多少 critical、warning、info 和 nitpick 级别的建议。如果你把 open-code-review 接入 pre-commit hook还可以在每次 commit 之前执行一次快速检查。不过我不建议 pre-commit 阶段就跑完整 LLM 审查太慢太贵更适合只跑确定性规则LLM 审查留给 CI。4.3 一次典型 review 的关键输出长什么样这里我给一个压缩过但很典型的审查输出示例。假设你改了一个订单缓存函数引入并发问题。流水线先拆出审查单元规则引擎命中了一条 data race 相关规则于是 Agent 被调用来判断。最终报告里会有下面这类条目{ unit: services/order_service.py:order_list(L109-L132), severity: critical, category: concurrency, line_range: [118, 124], rule_hits: [race-condition-detector], description: 新增的本地缓存字段 _order_dict 在并发请求下有可能被同时读写。函数 order_list 没有加锁也没有使用线程安全的 Map 实现。, confidence: 0.87, suggestion: 使用 concurrent.futures 中的 ThreadPoolExecutor 时应将缓存替换为 threading.Lock 保护的 OrderedDict或者直接用 functools.lru_cache 并指定 maxsize避免手动维护可变缓存。 }这个条目最有价值的是把规则命中标签和 Agent 的判断绑定在了一起。开发人员看到结果时不只看到“有并发风险”还能追溯到是静态规则先发现了可疑位置再由 Agent 解释来龙去脉。这种关联正是混合架构区别于纯 LLM 方案的标志。4.4 接入 GitHub Actions / GitLab CI 的注意事项本地跑通之后第二步就是接进 CI。我以 GitHub Actions 为例加一个最小化的 workflowname: ai-code-review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: Run open-code-review run: | open-code-review review --diff origin/main...HEAD --report json env: OPENAI_API_KEY: ${{ secrets.API_KEY }}注意fetch-depth: 0必须配置否则 actions/checkout 默认只拉取浅克隆流水线拿不到足够的 git 历史来算 merge-base。报告生成后要让机器人把结果贴到 PR comment而不是直接通过 exit code 阻断合并。原因很简单LLM 审查结论天然带有不确定性直接阻断会引发团队反感也会让模型误报变成流程瓶颈。我的建议是分三步走前两周只发报告不阻断让团队把置信度阈值调稳两周后对 critical 级别且置信度高于 0.85 的结论开启阻断再跑一段时间后再考虑把 warning 纳入自动阻断范围。激进的情绪可以理解但流程建设要一步步来。5. 常见问题与排查技巧实录5.1 模型输出不符合 JSON 格式 / 行号乱飞怎么办这是我在接入时遇到最多的问题。模型输出会在一段正经 JSON 后面追加解释文字或者 line_range 指向了根本没有变更的行号。处理方法分两层第一层在系统提示词里明确要求“只输出 JSON不要任何解释”并给出 schema第二层在后处理时做校验行号与 diff 变更行没有交集就直接丢弃格式校验失败则最多重试两次两次都失败就标记为 unknown不让它阻塞整个流程。5.2 大 diff 超预算切分策略比换更强模型更有效一个几千行的改动如果不切分会直接打爆上下文窗口。解决办法是把审查单元粒度调小只审查变更函数不审查未变更的外部依赖。如果单个文件确实改了上百处就按函数边界拆成多个单元串行执行同时把上下文聚合策略改为“只保留最相关的调用链”。预算还是超就降低 Agent 轮数或跳过低严重度的规则标签解释。我建议在配置里加一个max_review_units参数达到上限后剩下的部分只跑确定性规则不做 LLM 语义分析。极端情况下做到“宁可少审不要拖垮 CI”。5.3 误报和漏报怎么量化先建数据集再谈调优很多人凭感觉说“AI 审查不准”但说不清哪里不准。我给团队的笨办法是手动收集近一个月的真实 diff抽样挑 100 个人工标注出真正有问题的位置形成一个基线数据集。然后把 open-code-review 的输出跑上去计算精确率和召回率。每周花半小时看 badcase你会发现大部分误报集中在某几种模式比如模型把测试代码中的 mock 对象当成真实调用。一旦发现这个规律就把“mock 文件不参与某些判断”沉淀为确定性规则或者加入上下文过滤规则。坚持几个月后系统会越用越准成本也会下降。5.4 Agent 卡在循环里或工具调用失效Agent 最多跑 5 轮还会卡住一般是工具定义太复杂或者模型本身不支持 function calling。排查时先看日志里最近一次工具调用返回了什么如果返回的是空结果模型会反复尝试调用同一个工具。解决办法是减少工具数量只保留最常用的四个并且在返回“无结果”时附带明确提示“没有更多信息请直接做出判断”。另一个常见问题是模型把工具参数拼错了比如把文件路径斜杠写反。可以加一层参数校验把不符合路径格式的调用直接拒绝并提示模型重试。这本质上是把模型的自由发挥约束回确定性边界里。5.5 安全边界别让模型生成的补丁自动应用open-code-review 支持生成修复补丁但我的原则是补丁永远只能作为建议展示不能自动应用。原因很现实——模型的补丁在语法上可能是正确的但在业务语义上可能修改了不该改的逻辑甚至包含注入风险。如果你把补丁应用做成自动的等于把一个未经评审的变更直接送到代码库里。对于包含命令执行的代码库比如 shell 脚本、CI workflow我建议在配置里直接关掉补丁生成只允许 Agent 输出自然语言建议。安全边界的设计优先级高于审查效率这个不能妥协。一些个人的体会这套“确定性流水线 LLM Agent”的混合架构我从前年就开始在不同体量的项目里尝试。踩过最大的坑就是一开始太迷信大模型把静态规则全部关掉结果 Agent 凭感觉审查报告好看但不可追溯。后来回到确定性优先的思路把静态规则当骨架、LLM 当语义补充效果才真正稳定下来。如果你准备在自己的团队落地我的建议是先不要买任何“AI 审查一体机”先用 open-code-review 这种可拆解的架构跑两周把每个环节的数据都打出来你才会知道瓶颈到底在规则、上下文、还是模型本身。最后还有一个小技巧把每一次人工确认的“误报”和“有效发现”都记录下来隔一个月回看你会发现这套系统的可改进空间比任何大模型版本迭代都大。