申诉通道设计：开发者反馈如何回流成规则迭代

在很多技术团队推行 AI 代码审查（AI Code Review）的过程中，最容易导致开发者与质量委员会产生剧烈对立的根源，就是**“单向强制输出，缺乏闭环申诉反馈机制”**。

AI 审查机器人（Bot）在 Merge Request 页面给出了 5 条批评意见，甚至因为某条规则判定失败卡死了 CI 门禁。
而业务开发明明知道“这处代码因为业务特殊时序必须这么写，AI 的报错是一起典型的误报”，但由于系统没有任何反馈按钮，开发者只能：

• 跑去群里找架构师吐槽对线；
• 或者被迫写一段丑陋的临时代码去“讨好”AI 的检查；
• 架构师也无法及时获知到底是哪条规则在持续产生噪音。

一个没有“申诉反馈与负样本回流闭环”的 AI 审查系统，生命周期通常不会超过一个月。

要让审查规则持续自我进化、越来越懂业务，必须设计一套极低摩擦力的“开发者一键申诉通道”与“自动回流迭代流水线（Feedback Loop SOP）”。

申诉反馈与规则迭代闭环全景架构

[AI 审查 Bot 在 GitLab / GitHub MR 中发表评论]
                        │
                        ▼ (提供交互快捷按钮)
┌─────────────────────────────────────────────────────────────┐
│ 🟢 [采纳修复] (一键应用 Diff) ──> 记录为正样本，计入规则 ROI   │
│ 🔴 [标记误报] (一键申诉) ──────> 弹出微型快捷申诉抽屉        │
└─────────────────────────────────────────────────────────────┘
                        │ (点击标记误报)
                        ▼
[提取结构化申诉快照 (Snapshot Payload)]
  ├── 违规规则 ID (rule_id)
  ├── 触发代码片段 (Diff & Enclosing AST)
  ├── 当时的 System Prompt 与模型版本
  └── 开发者填写的 1 句话申诉理由 (或快捷勾选项)
                        │
                        ▼
[入库至企业内部《AI 审查负样本仓库 (Negative Samples DB)》]
                        │
                        ▼ (自动化触发规则微调与回归)
  ├── 自动将该样本转换为测试夹具 (bad fixture)
  ├── 调整规则 Prompt 指令或收窄 AST 触发正则
  └── 运行规则库全量回归单测 ──> 验证误报消除且不产生漏检

MR 评论区的交互卡片与 Webhook 设计

不要让开发者去另一个系统提工单！所有的交互必须在 GitLab / GitHub 的 MR 评论区内原生内嵌完成。

CI Bot 发送的标准审查评论模板（Markdown + 快捷指令）：

🤖 **AI 架构守卫审查反馈** (规则编号: \`CORR-VUE-DESTRUCTURE\`)

在文件 \`src/views/User.vue#L24\` 发现：直接解构 defineProps 导致响应式丢失风险。

👉 **推荐修复建议**：
\`\`\`typescript
const { name, role } = toRefs(props);
\`\`\`

---
💬 **开发者反馈快捷通道**（直接回复指令即可触发）：
- 回复 \`/ai-accept\`：标记为有效拦截并计入质量看板
- 回复 \`/ai-fp 理由说明\`：一键申诉误报（例如：\`/ai-fp 此处已开启 Reactivity Transform 宏编译\`）

申诉 Webhook 接收与数据清洗处理

当开发者在评论区回复 /ai-fp ... 时，GitLab Webhook 自动触发后端的轻量收集微服务：

// services/feedback-collector.ts
import fs from 'fs';
import path from 'path';

export interface FalsePositiveFeedback {
  feedbackId: string;
  ruleId: string;
  mrUrl: string;
  author: string;
  reason: string;
  codeSnippet: string;
  timestamp: string;
}

export async function handleWebhookFeedback(webhookPayload: any) {
  const commentText: string = webhookPayload.object_attributes.note;
  if (!commentText.startsWith('/ai-fp')) return;

  const reason = commentText.replace('/ai-fp', '').trim() || '未填写具体原因';
  const parentComment = await fetchParentReviewComment(webhookPayload);
  const ruleId = extractRuleIdFromComment(parentComment);

  const feedbackData: FalsePositiveFeedback = {
    feedbackId: 'FP-' + Date.now(),
    ruleId,
    mrUrl: webhookPayload.object_attributes.url,
    author: webhookPayload.user.username,
    reason,
    codeSnippet: parentComment.codeSnippet,
    timestamp: new Date().toISOString(),
  };

  // 1. 自动入库并持久化为规则测试负样本
  saveToNegativeSampleRepo(feedbackData);

  // 2. 自动在 MR 下回复开发者已受理确认
  await postBotReply(webhookPayload, `✅ 已收到您的误报申诉（工单号: ${feedbackData.feedbackId}），已将该案例入库并指派规则负责人进行针对性微调。`);
}

负样本驱动的规则自动化迭代流程

收集到真实的误报样本后，规则维护工程师（或自动化 Agent）按照以下标准化流程进行规则重构：

[收到负样本 FP-17258900]
            │
            ▼ (第一步: 将该代码片段追加到该规则的 test_cases.negative 数组中)
[运行 pnpm test:rules ── 此时单测红灯挂掉 (复现误报)]
            │
            ▼ (第二步: 针对性微调 Prompt 指令或增加触发守卫)
[微调规则 YAML: 增加特殊边界说明或增加 AST 排除条件]
            │
            ▼ (第三步: 重新运行 pnpm test:rules ── 单测全绿通过！)]
            │
            ▼ (第四步: 自动提 PR 合并，无缝热更新线上审查 Bot)

规则 YAML 中自动沉淀的负样本用例库：

# .ai-rules/categories/01-correctness/CORR-VUE-DESTRUCTURE.yaml
rule_id: CORR-VUE-DESTRUCTURE
title: Vue3 defineProps 解构丢失响应式

# 历史申诉回流沉淀的豁免场景说明
prompt_instruction: |
  检查是否在 setup 顶层解构了 defineProps。
  
  【申诉回流沉淀的合法豁免场景】
  1. 如果文件顶部包含 `// @vue-reactivity-transform` 注释，属于合法解构宏，严禁报错！
  2. 如果解构出的属性仅在当前的 `console.log` 调试语句中使用且后续无模板绑定，属于轻量调试，标记为 info 提示而非 blocker。

# 真实历史申诉回归测试集
regression_fixtures:
  - id: "FP-17258900"
    author: "zhangsan"
    code: "const { user } = defineProps<{ user: User }>(); console.log(user);"
    expected_result: "PASS_OR_INFO"

运营指标与成效

• 申诉响应时效（SLA）：所有开发者的误报申诉在 24 小时内完成归因与规则迭代；
• 全生命周期正循环：规则库在运行三个月内，通过回流吸收了 140 个真实边缘负样本，全团队误报率从最初的 38% 稳步收敛并常态化保持在 5% 以下；
• 彻底消除了工程师与工具的对抗，让每一位一线开发者都成为规则库演进的共建者。