规则分级设计：blocker/warn/info 与豁免机制-编程实验室

规则分级设计：blocker/warn/info 与豁免机制

在将 AI 代码审查真正接入企业 CI/CD 门禁流水线时，很多团队最容易走入两个极端：

极端一：所有规则一律 Blocker（卡死合并）。AI 稍微发现一段代码可能存在重构优化空间，或者挑刺一个命名不够语义化，就直接把 MR（Merge Request）状态置为失败。业务线工程师为了按时上线，最后只能逼着管理员关闭门禁，AI 审查彻底被边缘化。
极端二：所有规则一律 Info（纯通知提醒）。AI 辛辛苦苦分析出的“深层异步竞态”和“内存泄漏风险”，淹没在几十条无关痛痒的 Bot 评论中。开发者顺手点个“全部标记为已解决”直接合入主干，线上故障依旧频发。

做工程化质量守门，必须建立起一套严密分级的规则判定体系（Rule Severity Tiering），并配套设计出透明可审计的豁免机制（Exemption Workflow）。

三级规则严重度模型（Rule Severity Model）

我们将所有的代码审查规则严格划分为三个层级，每一级对应不同的 CI 拦截行为与责任人契约：

[MR 提交触发审查] │ ├─ Blocker (阻断级) ──> 立即卡死 CI 门禁，禁止合入，必须修复或主管审批豁免 ├─ Warning (告警级) ──> 不卡死门禁，但要求在 MR 页面显式确认（ACK）或技术负责人复核 └─ Info (提示级) ──> 仅作为代码小贴士折叠展示，计入个人周度代码洁癖看板

1. Blocker（阻断级）：零容忍的线上红线

判定标准：一定会导致线上运行时白屏崩溃、数据污染、严重安全漏洞或重大性能回退的代码反模式。
典型案例：
- 在 SSR 顶层作用域实例化全局 Store 导致用户会话交叉泄漏；
- React/Vue 组件卸载时遗漏全局事件监听或定时器清理（确定的内存泄漏）；
- 核心接口参数未做类型收窄直接进行对象深层访问（潜在的Cannot read properties of undefined）；
- 破坏架构依赖方向（如基础 UI 组件反向依赖业务页面）。

2. Warning（告警级）：潜在的维护性与性能隐患

判定标准：当前运行可能正常，但极大增加后续维护成本、或者在特定边界场景（如弱网、低端机）下会产生性能劣化的模式。
典型案例：
- 在循环中交叉进行 DOM 几何尺寸读写（潜在的强制同步回流）；
- 复杂对象未根据场景使用shallowRef而是全量递归深层代理；
- 函数圈复杂度过高（超过 15）且未拆分；
- 遗漏关键状态机的异常兜底分支。

3. Info（提示级）：代码品味与工程洁癖倡导

判定标准：符合语法与性能要求，但存在更优雅的现代语意化写法、或有现成的公共组件可以直接复用。
典型案例：
- 推荐使用 ES2022 的Array.prototype.at()替代传统的arr[arr.length - 1]；
- 提示当前原生手写的输入框可以直接替换为团队公共的<AmountInput>；
- 建议将某些复杂的内联三元表达式提取为具名的计算属性。

规则配置 Schema：将分级与权重机器化

在规则库仓库中，我们通过标准 YAML 定义每一条规则的分级与判定置信度：

# rules/correctness/react-hooks-deps.yaml rule_id: REACT-HOOKS-DEPS-001 title: React Hooks 依赖项缺失闭包陈旧值风险 severity: blocker category: correctness confidence_threshold: 0.90 # 置信度必须大于 90% 才能触发 Blocker condition: file_extension: [".tsx", ".jsx"] ast_triggers: ["useEffect", "useCallback", "useMemo"] action_on_trigger: ci_status: "FAILED" comment_template: | 🛑 **[Blocker] 发现高危闭包陷阱** 在文件 `{file_path}` 第 `{line_number}` 行，回调函数内部引用了状态 `{variable_name}`，但未在依赖数组中声明。 这可能导致异步请求在执行时读取到旧的上下文状态。 👉 **推荐修复 Diff**： ```{diff_lang} {suggested_diff} ```

豁免机制（Exemption Workflow）设计

在真实的业务迭代中，总会存在极少量的特殊业务诉求（例如为了兼容某个特殊的第三方非标准 SDK，必须打破某种常规约束）。如果系统完全不给退路，就会演变成工程师与工具的对抗。

我们设计了双轨制豁免流程：

1. 代码级行内声明式豁免（Inline Annotation）

对于 Warning 级别的规则，允许开发者在代码行上方添加格式化注释直接静默，但必须强制写明原因与工单号：

// ai-review-ignore: VUE-SHALLOW-REF-001 -- [PROJ-4521] 该三方实例内部依赖动态属性注入，经性能测试内存可控 const specialInstance = reactive(new ThirdPartyEngine());

如果注释中未包含-- [工单号]或解释少于 10 个字符，CI 校验器仍会判定豁免语法非法并阻断提交。

2. CI 页面主管审批豁免（Manager Override）

对于 Blocker 级别的规则，代码行内注释无法直接绕过门禁。开发者必须在 GitLab / GitHub MR 页面点击[申请特殊豁免]：

系统自动抓取当前违规代码上下文与风险评估报告；
触发企业微信/钉钉 Webhook 通知前端技术负责人；
负责人点击确认后，CI 门禁自动解封，并将本次豁免记录永久持久化到《技术债务与豁免台账》中，在每季度末进行专项债务清退复盘。

落地成效与运营总结

误报阻断率清零：通过将低置信度建议降级为 Info、将真正致命隐患收敛为 Blocker，全团队对 AI 审查的有效阻断采纳率从最初的31% 提升至 94%；
研发节奏不受阻：开发者平均每处理一次 MR 审查反馈的耗时控制在2 分钟以内，既守住了质量底线，又赢得了业务团队的信任。