智能代码审查门禁：AI 建议不能直接变成阻塞项
一、AI Review 最怕意见很多但证据很少
智能代码审查能快速发现风险，但如果所有建议都变成阻塞项，团队会很快疲劳。模型可能把风格偏好说成缺陷，把可选优化说成严重问题，也可能漏掉真正危险的副作用。
门禁设计要区分建议、警告和阻塞。只有可复现、影响明确、风险足够高的问题，才适合阻塞合并。AI Review 的目标是降低风险，不是制造新的噪音。
二、审查结果要分级
flowchart LR
A[PR 变更] –> B[静态规则]
B –> C[AI 语义审查]
C –> D{风险等级}
D –> E[建议]
D –> F[警告]
D –> G[阻塞]
静态规则先跑，模型再看语义。比如类型错误、未通过测试、bundle 超预算，直接由工具判断。模型适合审查组件边界、状态流动、错误处理和设计系统偏离。
阻塞项必须附带证据。证据可以是具体文件、行号、复现路径、性能数据或规范条款。没有证据的“建议优化”，应该只作为评论，不应阻塞。
三、规则要可配置
review_gate:
block:
– type_error
– security_risk
– bundle_budget_exceeded
warn:
– duplicated_logic
– unclear_component_boundary
不同项目的门禁不一样。活动页可以容忍较少抽象，后台系统更关注表单可靠性，组件库更关注 API 稳定。门禁配置要按仓库和目录区分，不能一刀切。
type ReviewFinding = {
level: "suggest" | "warn" | "block"
file: string
reason: string
evidence: string
}
AI 输出要转成结构化 finding，再由门禁系统判断是否阻塞。不要直接把模型自然语言评论当成 CI 结果。结构化之后，才能统计误报率和处理时长。
四、误报要进入反馈闭环
false_positive -> 降低规则权重
true_positive -> 加入回放样本
ignored_many_times -> 改成建议
AI Review 的质量要持续校准。开发者标记误报后，样本应该进入评测集。某类建议长期被忽略，说明它可能不适合当前项目门禁。反过来，真实缺陷被发现后，要沉淀成回放案例。
还要观察合并效率。门禁太严会拉长 PR 周期，太松又挡不住事故。看板应展示阻塞数量、误报率、平均修复时间和线上缺陷关联。
门禁还要支持渐进上线。新规则刚接入时，可以先只评论不阻塞，收集一段时间的误报和命中案例。稳定后再把高风险规则升级为阻塞。这样团队能看到规则价值，也能避免新工具第一天就把主干堵死。
对模型建议要做去重。同一个根因可能被模型在多个文件里反复评论，开发者看到十几条类似建议会很烦。审查系统可以按风险类型、依赖链和代码位置聚合，只保留最能说明问题的一条。
最后要给人工保留裁决权。紧急修复、实验分支和历史迁移都可能需要临时通过。绕过门禁必须记录原因和负责人，并在后续追踪关闭。否则例外会慢慢变成默认路径。
安全相关规则要更保守。比如 XSS 风险、危险 HTML 注入、依赖漏洞和权限绕过，这些问题即使误报率略高，也应该优先进入阻塞候选。风格建议和抽象建议则可以保持非阻塞，避免把主观偏好包装成硬规则。
五、总结
智能代码审查门禁要分层：确定性规则负责硬拦截，AI 负责语义风险，阻塞项必须有证据。
AI 建议不是越多越好。真正有效的 Review，是让高风险问题更早暴露，同时不把团队淹没在噪音里。
