前端 AI 提效实战：从 0 到 1 打造团队专属 AI 代码评审工具

前端 AI 提效实战：从 0 到 1 打造团队专属 AI 代码评审工具

---

前言｜作为前端，终于受不了重复人工 CR 的内耗

做过前端 Code Review 的同学应该都懂那种感觉------

每天打开 GitLab，看到十几个待审的 MR，里面一大半是「变量命名不规范」「缺少类型定义」「import 没用到」这类低级问题。你得逐行看、逐条写评论，审完一个 MR 半小时就没了。更崩溃的是，新人下次提交代码，同样的问题再来一遍。

后来我认真想了想，这些重复性的初审工作，是不是可以让 AI 来做？于是我花了两周时间，从 0 到 1 搭了一套 AI 代码审查工具，接入了团队的 GitLab 流程。今天把整个过程的设计思路和踩坑经验整理出来，希望对想搞类似工具的同学有帮助。

---

项目初衷｜为什么决定自研一套 AI 代码审查工具

人工 CR 的真实困境

我们团队在 CR 中遇到的问题，我相信大部分前端团队都存在：

• 重复问题占比太高：命名不规范、类型错误、语法 bug、缺少空值判断......这类问题能占 CR 总量的 40% 以上，但每一轮都得人工审一遍
• CR 周期拖沓：复杂 MR 的评审经常要等半天甚至一天，评审者手头有自己的活，不一定能及时响应，直接影响开发节奏
• 精力分散导致漏审：人在审了 5 个文件之后注意力就会下降，容易忽略关键的安全问题或性能隐患
• 新人代码质量难对齐：新加入的同学不清楚团队的编码规范，需要老成员反复指导，效率很低

为什么不直接用现成的

市面上的 AI CR 工具不是没有，但我调研了一圈发现几个硬伤：

• IDE 插件型的（如 Copilot Review）只能个人用，和团队 GitLab 流程完全打通不了
• SaaS 型的工具（如 CodeRabbit）没法自定义团队规范，审查维度和你团队关注的点对不上
• 想要适配内部 GitLab + 自定义规则 + 批量处理，基本只有自研这一条路

我的目标

做一个轻量、可落地、能和团队现有流程无缝衔接的 AI CR 助手。定位很清晰------

不是替代人工评审，而是做「自动化初审 + 重复问题拦截」，把人工 CR 的精力解放出来，让开发者专注于架构和逻辑层面的讨论。

---

技术栈选型｜前端向轻量化技术架构

作为前端团队，技术选型的核心原则是轻量、易维护、团队能 hold 住：

层面	选型	选它的理由
运行时	Node.js	前端团队最熟悉，降低维护成本
Web 框架	Express	极简、够用、中间件生态丰富
HTTP 客户端	Axios	请求/响应拦截器很好用，适合做重试和日志
AI 接口协议	OpenAI 兼容格式	兼容性最好，换模型只改 URL 和 Key
容器化	Docker	团队已有 K8s 基础设施，部署零成本
CI/CD	GitLab CI	和代码仓库天然集成

整个项目的外部依赖只有 express、axios、dotenv 三个包，极致精简。

---

整体架构设计｜分层 + 适配器模式的解耦思路

架构全景图

┌──────────────────────────────────────────────────┐
│                   接入层（Gateway）                │
│          Express 路由 / 中间件 / 错误拦截          │
├──────────────────────────────────────────────────┤
│                事件分发层（Dispatcher）             │
│       GitLab 事件分发  ｜  GitHub 事件分发          │
├──────────────────────────────────────────────────┤
│              审查编排层（ReviewOrchestrator）        │
│        平台无关的统一审查流程，适配器注入            │
├─────────────┬────────────────────────────────────┤
│  AI 审查核心  │         平台适配层（Bridge）        │
│  SmartReviewer│   GitLabBridge ｜ GitHubBridge    │
├─────────────┴────────────────────────────────────┤
│                 基础设施层                          │
│   DiffAnalyzer / FileGate / FeedbackStore / Logger│
└──────────────────────────────────────────────────┘

四个核心设计原则

1. 平台解耦：适配器模式把 GitLab / GitHub 的 API 差异封装在 Bridge 层，核心审查逻辑对平台完全无感知
2. 管道化编排：审查流程拆解为独立步骤，每一步可单独测试、替换、跳过
3. 优雅降级：批量失败降级为逐条，单条失败静默跳过，AI 不可用也不影响主流程
4. 配置驱动：审查级别、文件过滤规则、并发参数全部外置为配置项，改配置不改代码

---

核心流程梳理｜从 Webhook 触发到评论回写全链路

一句话概括整条链路：

开发者提交 MR → Webhook 触发 → 拉取代码变更 → Diff 智能分块
→ AI 分批审查 → 解析过滤结果 → 精准定位行号 → 回写行内评论

完整数据流如下图：

                    代码托管平台 (GitLab/GitHub)
                            │
                       Webhook 事件
                            │
                            ▼
                    ┌───────────────┐
                    │   接入层路由    │  ← 立即返回 200，异步处理
                    └───────┬───────┘
                            │
                    ┌───────▼───────┐
                    │   事件分发     │  ← 动作过滤 / 跳过标记检测
                    └───────┬───────┘
                            │
                    ┌───────▼───────┐
                    │  审查编排器    │  ← 适配器注入
                    └───────┬───────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
      ┌──────────┐   ┌──────────┐   ┌──────────┐
      │ 拉取变更  │   │ 拉取已有  │   │ AI 审查   │
      │ (通过适配)│   │ 评论(去重)│   │ (分批调用)│
      └──────────┘   └──────────┘   └──────────┘
            │                              │
            ▼                              ▼
   ┌─────────────────┐          ┌──────────────────┐
   │ Diff 智能解析     │          │ 结果解析 + 过滤    │
   │ → 行级拆解        │          │ → 低质量过滤       │
   │ → 邻近合并        │          │ → 去重检测         │
   │ → 上下文拼装      │          └────────┬─────────┘
   └─────────────────┘                    │
                            ┌─────────────▼─────────┐
                            │ 评论回写（通过适配器）   │
                            │ → 行号锚点校准          │
                            │ → 去重后发布            │
                            └───────────────────────┘

---

接入层实现｜Webhook 监听与事件过滤设计

路由注册

系统暴露两组 Webhook 端点，分别对接 GitLab 和 GitHub：

POST /hook/gitlab   →  接收 GitLab Merge Request 事件
POST /hook/github   →  接收 GitHub Pull Request 事件
GET  /ping          →  健康检查
GET  /tasks         →  查看审查任务执行状态

事件过滤：不是所有事件都值得审查

这是很多同学容易忽略的一步------Webhook 会推送所有事件，但只有特定动作才需要触发审查：

平台	触发审查的动作	直接忽略的
GitLab	MR open、update	close、merge、approval
GitHub	PR opened、reopened、synchronize	closed、labeled、unlabeled

跳过标记设计

团队成员可以通过在 MR 标题中加入特定标记来跳过审查（比如纯文档修改、紧急 hotfix），系统在入口处检测到就自动放行：

// 示意：基于正则的跳过规则匹配
const SKIP_REVIEW_MARKERS = [/skip[\s-]?review/i, /no[\s-]?cr/i, /忽略审查/];

function matchSkipCondition(prMeta) {
  const source = `${prMeta.heading} ${prMeta.description || ''}`;
  return SKIP_REVIEW_MARKERS.some(rule => rule.test(source));
}

安全设计：异步处理 + 立即响应

Webhook 端点收到请求后立刻返回 200，审查任务丢到异步流程中执行。原因很简单：

1. 代码托管平台通常要求 Webhook 在 10 秒内响应，否则判定超时
2. AI 审查一轮可能要 30 秒到几分钟，同步等待必然超时
3. 超时后平台会重发事件，导致重复审查

// 示意：异步审查 + 立即响应
function handleWebhookEvent(req, res) {
  const payload = req.body;

  // 立即告诉平台：我收到了
  res.status(200).json({ status: 'accepted' });

  // 审查任务异步执行，不阻塞响应
  triggerReviewAsync(payload).catch(err => {
    logError('审查任务异常', err);
  });
}

---

架构核心｜适配器模式如何抹平多平台差异

这是整个系统最关键的架构设计。

问题：GitLab 和 GitHub 的 API 完全不一样

• 获取 diff：GitLab 用 /merge_requests/:id/changes，GitHub 用 /pulls/:number/files
• 发评论：GitLab 要传 position 对象（包含 base_sha / head_sha / start_sha），GitHub 只需要 commit_id + path + position
• 评论列表：GitLab 是 discussions + notes 两套体系，GitHub 是 review comments + issue comments

如果把这些平台差异直接写在业务逻辑里，后面想加一个新平台（比如 Gitee、Bitbucket）基本等于重写。

解法：Bridge 适配器

定义一套平台无关的统一接口协议，每个平台按协议实现对接：

// 平台对接协议------用对象描述而非 class 继承
function createPlatformConnector(handlers) {
  const REQUIRED_HOOKS = ['loadDiffs', 'loadHistory', 'annotate', 'summarize'];

  REQUIRED_HOOKS.forEach(hook => {
    if (typeof handlers[hook] !== 'function') {
      throw new Error(`平台适配器缺少 ${hook} 钩子`);
    }
  });

  return Object.freeze(handlers);
}

每个平台按协议实现自己的对接器，内部处理各自的 API 差异，对外暴露统一的数据格式：

// 以某个平台为例的对接器（示意）
const gitlabConnector = createPlatformConnector({
  async loadDiffs(ctx) {
    const resp = await ctx.client.getMergeDetail(ctx.repo, ctx.mergeNo);
    return resp.files.map(f => normalizeFileChange(f, resp.versionRefs));
  },

  async loadHistory(ctx) { /* 获取已有评论 */ },
  async annotate(ctx, notes) { /* 发通行内评论 */ },
  async summarize(ctx, report) { /* 发总结评论 */ },
});

// 核心归一化：把平台特有的字段映射成通用格式
function normalizeFileChange(raw, refs) {
  return {
    content: raw.patchText,
    filePath: raw.targetFile,
    priorPath: raw.sourceFile,
    versions: { from: refs.ancestor, base: refs.target, to: refs.latest },
    status: { added: raw.isNew, moved: raw.isRename, removed: raw.isDelete },
  };
}

统一数据契约

所有对接器吐出的都是同一份结构，核心审查逻辑完全不感知平台差异：

// 通用文件变更结构（所有平台统一）
const FileChangeDescriptor = {
  content: '@@ -10,5 +10,7 @@ ...',   // diff 文本
  filePath: 'src/app.js',              // 目标文件路径
  priorPath: 'src/app.js',             // 变更前路径
  versions: {
    from: 'abc123...',                 // 祖先版本
    base: 'def456...',                 // 基线版本
    to: 'ghi789...',                   // 最新版本
  },
  status: { added: false, moved: false, removed: false },
};

这样做的直接好处：审查编排器和 AI 审查核心完全不需要知道底层是 GitLab 还是 GitHub，未来新增平台只需要实现一个新的 Bridge 类。

---

智能解析｜Diff 解析与代码分块的设计巧思

这是整个 AI CR 系统中技术密度最高的模块。

核心挑战是：一个 MR 可能有几十个文件、上千行变更，但 AI 模型有上下文长度限制，不可能一次性全塞进去。怎么把 diff 拆成大小适中、上下文完整的代码块喂给 AI？

第一步：把 Diff 解析成行级数据

Unified Diff 是纯文本格式，需要先解析成结构化数据：

// 示意：从 diff 文本中提取变更行
function extractModifiedLines(rawDiff) {
  const rows = rawDiff.split('\n');
  const output = [];
  let newLineCursor = 0;
  let oldLineCursor = 0;

  for (const row of rows) {
    if (row.startsWith('@@')) {
      // 从 hunk header 中解析起始行号
      const matched = row.match(/@@ -(\d+),?\d* \+(\d+),?\d* @@/);
      if (matched) {
        oldLineCursor = parseInt(matched[1]);
        newLineCursor = parseInt(matched[2]);
      }
      continue;
    }

    if (row.startsWith('+') && !row.startsWith('+++')) {
      output.push({
        kind: 'addition',
        text: row.slice(1),
        lineNum: newLineCursor++,
      });
    } else if (row.startsWith('-') && !row.startsWith('---')) {
      output.push({
        kind: 'deletion',
        text: row.slice(1),
        lineNum: oldLineCursor++,
      });
    } else if (!row.startsWith('\\')) {
      newLineCursor++;
      oldLineCursor++;
    }
  }

  return output;
}

第二步：邻近行合并------把零散变更聚合成审查单元

一个人在某个函数里改了 3 行，中间夹了 2 行没改的，这 5 行其实是一个逻辑单元。如果拆开给 AI 看，AI 会丢失上下文。所以需要一个「邻近合并」策略：

// 示意：将距离相近的变更行合并为审查单元
function clusterNearbyEdits(addedLines, proximityLimit = 3, sizeCap = 30) {
  if (addedLines.length === 0) return [];

  const clusters = [];
  let current = [addedLines[0]];

  for (let idx = 1; idx < addedLines.length; idx++) {
    const distance = addedLines[idx].lineNum - addedLines[idx - 1].lineNum;

    if (distance <= proximityLimit) {
      // 近距离，合并
      current.push(addedLines[idx]);
    } else {
      // 距离远，当前组结束
      clusters.push(buildCluster(current));
      current = [addedLines[idx]];
    }
  }
  clusters.push(buildCluster(current));

  // 超大组拆分
  return clusters.flatMap(c =>
    c.entries.length > sizeCap ? divideCluster(c, sizeCap) : [c]
  );
}

直观例子：

原始 Diff 新增行:
  行10: +const price = 100;
  行11: +const tax = 0.1;
  （2行未修改）
  行14: +const total = price * (1 + tax);

聚类结果:
  Cluster { start: 10, end: 14, lines: [...] }
  因为行14和行11的间距 = 3 <= proximityLimit(3)，所以合并为一组

第三步：上下文拼装------给 AI 看到完整语境

光看改了哪几行是不够的，AI 得知道这些代码前后的上下文才能做出准确判断。系统采用前后各取 N 行的策略：

// 示意：为审查单元拼装上下文
function assembleWithContext(cluster, sourceCode, surroundingLines = 3) {
  const aboveStart = Math.max(0, cluster.start - surroundingLines - 1);
  const belowEnd = cluster.end + surroundingLines;

  const lines = sourceCode.split('\n');
  const preceding = lines.slice(aboveStart, cluster.start - 1).join('\n');
  const succeeding = lines.slice(cluster.end, belowEnd).join('\n');

  return [
    preceding ? `/* === 上方上下文 === */\n${preceding}` : '',
    `/* === 变更内容 === */\n${cluster.entries.map(e => e.text).join('\n')}`,
    succeeding ? `/* === 下方上下文 === */\n${succeeding}` : '',
  ].filter(Boolean).join('\n\n');
}

文件级过滤------不是什么文件都值得审

在进入分块之前，还有一层文件级过滤：

// 示意：判断文件是否需要审查
function isWorthReviewing(fileChange) {
  const SKIP_EXTENSIONS = ['.lock', '.map', '.min.js', '.min.css', '.svg', '.png'];
  const SKIP_FILENAMES = ['package-lock.json', 'yarn.lock'];

  const filename = fileChange.currentPath;

  // 扩展名黑名单
  if (SKIP_EXTENSIONS.some(ext => filename.endsWith(ext))) return false;

  // 文件名黑名单
  if (SKIP_FILENAMES.includes(filename.split('/').pop())) return false;

  // 删除的文件不审
  if (fileChange.isDeleted) return false;

  return true;
}

---

AI 核心设计｜Prompt 工程与多级审查规则

Prompt 结构：角色 + 规则 + 格式约束

AI 审查的质量 80% 取决于 Prompt 怎么写。我最终采用的是结构化编号 Prompt：

┌─────────────────────────────────────┐
│  System：角色定义 + 输出格式铁律      │
│  "你是资深前端代码审查专家..."         │
│  "严格按照编号格式输出，一个块一行"     │
├─────────────────────────────────────┤
│  User：技术栈信息 + 自定义规则         │
│  "项目使用 React + TypeScript"       │
│  "团队规范：变量用驼峰，组件用 PascalCase" │
│  + 编号的代码块列表                   │
├─────────────────────────────────────┤
│  输出格式：                           │
│  <N>. PASS           ← 没问题        │
│  <N>. [类型] 标题 | 建议  ← 有问题   │
└─────────────────────────────────────┘

为什么用编号格式而不是 JSON？ 因为 AI 在严格格式约束下的 JSON 输出不稳定（容易多逗号、少引号），而编号文本格式解析容错度高得多。

// 示意：组装审查指令
function craftAuditInstructions(segments) {
  const PERSONA = [
    '你是一名严格的前端技术评审员。',
    '请逐段分析下方代码片段，每段给出一个判定：',
    '  ① 无异常 → 输出 >>OK',
    '  ② 有疑点 → 输出 >>FLAG [维度] 概要 && 修正思路',
    '维度选项：风险 / 效率 / 风格 / 正确性 / 健壮性',
    '严禁输出分析过程，只输出判定结果。',
  ].join('\n');

  const segmentsText = segments
    .map((seg, order) => `--- 片段 #${order + 1} (${seg.rowBegin}-${seg.rowEnd}) ---\n${seg.highlightedCode}`)
    .join('\n\n');

  return { persona, task: `共 ${segments.length} 段代码待审：\n\n${segmentsText}` };
}

多级审查规则：通用 → 技术栈 → 项目自定义

系统设计了三级规则叠加机制：

第一级：审查力度（Review Intensity）

力度	安全	性能	规范	可访问性
深度审查	✅	✅	✅	✅
均衡审查	✅	✅	✅	-
轻度审查	✅	✅	-	-

第二级：技术栈专属规则

根据项目使用的技术栈，动态注入特定审查要点：

// 示意：技术栈特定审查关注点
const STACK_FOCUS = {
  react: {
    keywords: [/useEffect/, /useState/, /useMemo/, /useCallback/],
    checkpoints: ['依赖数组完整性', '闭包陷阱', '不必要重渲染', 'key 使用'],
  },
  vue: {
    keywords: [/watch\(/, /computed\(/, /ref\(/, /reactive\(/],
    checkpoints: ['响应式正确性', 'watch immediate/deep', 'v-for key', 'nextTick'],
  },
  typescript: {
    keywords: [/as any/, /@ts-ignore/, /:\s*any/],
    checkpoints: ['类型安全', 'any 使用合理性', '泛型约束'],
  },
};

第三级：项目自定义规则

支持在项目根目录放一个规则文件，系统自动加载并追加到 Prompt 尾部。不同项目可以有完全不同的审查偏好------比如 A 项目严格要求所有函数都有返回类型，B 项目则不需要。

AI 调用参数的考量

参数	设定值	为什么
temperature	0.3	低温度保证稳定性，同一代码多次审查结果应一致
max_tokens	600	每个代码块只需一行结论，控制成本
stream	false	非流式方便批量解析，实现更简单

结果解析与质量过滤

AI 的输出不是都能直接用的，需要经过解析和过滤：

// 示意：解析 AI 的编号格式输出
function decodeInspectionOutput(rawText, clusters) {
  const rows = rawText.trim().split('\n');
  const findings = [];

  for (const row of rows) {
    const parsed = row.match(/^(\d+)\.\s*(.+)/);
    if (!parsed) continue;

    const sequenceNum = parseInt(parsed[1]) - 1;
    const body = parsed[2].trim();

    if (body === 'PASS') continue;

    // 低质量过滤：AI 偶尔会输出「代码看起来不错」这种废话
    if (isVagueOpinion(body)) continue;

    findings.push({
      clusterId: clusters[sequenceNum].id,
      anchorLine: clusters[sequenceNum].start,
      feedback: body,
    });
  }

  return findings;
}

function isVagueOpinion(text) {
  const VAGUE_PATTERNS = [
    /看起来不错/i,
    /没有明显问题/i,
    /^建议\s*$/,       // 只说「建议」没下文
    /可以考虑/i,        // 太模糊
  ];
  return VAGUE_PATTERNS.some(p => p.test(text));
}

---

体验优化｜评论精准定位与智能去重方案

行号锚点校准------让评论精准落到代码行上

AI 返回的审查意见要贴到具体代码行上，但 diff 里的行号和实际文件行号可能有偏差。比如 AI 说「第 15 行有问题」，但第 15 行恰好是未修改行，平台不允许在未修改行上贴评论。

解决方案是构建一个行号索引表，通过前后扫描找到最近的合法锚点：

// 示意：利用索引表做锚点校正
function resolveAnchor(requestedLine, indexMap) {
  // indexMap: 以行号为 key 的 Map，值为 true 表示该行可以贴评论
  if (indexMap.has(requestedLine)) return requestedLine;

  // 向前后双向扫描，找最近的合法行
  let offset = 1;
  while (true) {
    const above = requestedLine - offset;
    const below = requestedLine + offset;

    if (indexMap.has(above)) return above;
    if (indexMap.has(below)) return below;

    // 超出合理范围就放弃
    if (above < 0 && !indexMap.has(below)) return null;
    offset++;
  }
}

智能去重------避免刷屏

如果开发者在一次 MR 中做了多次推送，每次推送都会触发审查，容易出现重复评论。系统采用行号区间重叠 + 编辑距离双重检测：

// 示意：基于编辑距离的评论去重
function hasSimilarCommentInHistory(candidate, archive) {
  const THRESHOLD = 0.6;

  return archive.some(record => {
    // 先看行号区间是否靠近
    const lineProximity = Math.abs(candidate.line - record.line);
    if (lineProximity > 5) return false;

    // 再用编辑距离算文本相似度
    const dist = levenshtein(candidate.message, record.message);
    const maxLen = Math.max(candidate.message.length, record.message.length);
    return maxLen > 0 && (1 - dist / maxLen) > THRESHOLD;
  });
}

function levenshtein(a, b) {
  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i]);
  dp[0] = b.split('').map((_, j) => j);
  for (let i = 1; i <= a.length; i++) {
    for (let j = 1; j <= b.length; j++) {
      dp[i][j] = a[i - 1] === b[j - 1]
        ? dp[i - 1][j - 1]
        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
    }
  }
  return dp[a.length][b.length];
}

---

稳定性保障｜并发控制、缓存与降级容错策略

两级并发控制

AI API 调用是性能瓶颈，系统实现了文件级 + 批次级两层并发控制：

                   ┌──────────────────┐
                   │   文件级并发池    │  ← 同时处理 N 个文件
                   │  ┌────────────┐  │
                   │  │  文件 A     │  │
                   │  │ ┌────────┐ │  │
                   │  │ │批次并发│ │  │  ← 每文件内 M 个 cluster 一批
                   │  │ └────────┘ │  │
                   │  └────────────┘  │
                   │  ┌────────────┐  │
                   │  │  文件 B     │  │
                   │  └────────────┘  │
                   └──────────────────┘

// 示意：受控并发执行
async function runWithConcurrency(taskList, limit) {
  const pool = [];
  const outcomes = [];

  for (const task of taskList) {
    const promise = Promise.resolve().then(() => task());
    pool.push(promise);
    outcomes.push(promise);

    if (pool.length >= limit) {
      await Promise.race(pool);
      // 移除已完成的
      for (let i = pool.length - 1; i >= 0; i--) {
        if (pool[i].isSettled || /* 检查完成状态 */) {
          pool.splice(i, 1);
        }
      }
    }
  }

  return Promise.allSettled(outcomes);
}

Token 预算管理

每个批次的 Token 消耗会被预估，避免超出模型限制：

// 示意：Token 预算分配
function selectClustersWithinBudget(clusters, tokenCap, reserveAmount = 200) {
  const usable = tokenCap - reserveAmount;
  let consumed = 0;
  const selected = [];

  for (const cluster of clusters) {
    const estimate = roughTokenCount(cluster.annotatedCode);
    if (consumed + estimate > usable) break;
    consumed += estimate;
    selected.push(cluster);
  }

  return selected;
}

function roughTokenCount(str) {
  // 粗估：中文 ~1.5 字符/token，英文 ~4 字符/token
  const cjk = (str.match(/[一-鿿]/g) || []).length;
  const rest = str.length - cjk;
  return Math.ceil(cjk / 1.5 + rest / 4);
}

三级降级策略

这是保障系统「挂了也不影响开发流程」的关键设计：

正常路径:  批量审查所有 Cluster
   ↓ 批量调用失败
降级 Lv1:  逐个 Cluster 单独调用
   ↓ 单个也失败
降级 Lv2:  该 Cluster 标记 PASS，跳过
   ↓ AI 服务整体不可用
降级 Lv3:  静默跳过，仅记录日志，不中断主流程

// 示意：三级降级
async function executeInspection(clusters, aiClient) {
  try {
    return await aiClient.batchInspect(clusters);
  } catch (batchErr) {
    logger.warn('批量审查失败，降级逐条处理');

    const results = [];
    for (const cluster of clusters) {
      try {
        const r = await aiClient.inspectSingle(cluster);
        results.push(r);
      } catch (singleErr) {
        logger.warn(`Cluster ${cluster.id} 审查失败，跳过`);
        results.push({ clusterId: cluster.id, verdict: 'PASS', degraded: true });
      }
    }
    return results;
  }
}

审查结果缓存

内存缓存避免短时间内重复审查同一段代码：

// 示意：基于桶的过期缓存
function createResultBucket(maxSlots = 500, expireAfter = 3600) {
  const slots = new Map();

  setInterval(() => {
    const cutoff = Date.now() - expireAfter * 1000;
    for (const [tag, entry] of slots) {
      if (entry.born < cutoff) slots.delete(tag);
    }
  }, expireAfter * 500);

  return {
    find(identity) { const e = slots.get(identity); return e && (Date.now() - e.born < expireAfter * 1000) ? e.val : null; },
    save(identity, val) { if (slots.size >= maxSlots) slots.delete(slots.keys().next().value); slots.set(identity, { val, born: Date.now() }); },
  };
}

重试机制

所有对外调用（平台 API、AI API）都包装了指数退避 + 抖动重试：

// 示意：带抖动的指数退避重试
async function resilientCall(fn, { ceiling = 3, jitter = true } = {}) {
  let remaining = ceiling;

  while (remaining-- > 0) {
    try {
      return await fn();
    } catch (fault) {
      if (remaining <= 0) throw fault;
      const backoff = Math.pow(2, ceiling - remaining) * 1000;
      const actualWait = jitter ? backoff * (0.5 + Math.random()) : backoff;
      await new Promise(r => setTimeout(r, actualWait));
    }
  }
}

---

配置系统｜三层可配置架构，灵活适配团队规范

系统采用三层配置，优先级从高到低：

第一层：环境变量

# 核心
LLM_API_KEY=xxx
LLM_API_URL=https://your-endpoint/v1/chat/completions
LLM_MODEL_NAME=your-model

# 平台凭证
GITLAB_ACCESS_TOKEN=xxx
GITHUB_ACCESS_TOKEN=xxx

# 并发与性能
FILE_CONCURRENCY=3
CLUSTER_BATCH_SIZE=8
CLUSTER_LINE_CAP=30
AI_CONCURRENCY=5
CONTEXT_SURROUNDING_LINES=3
NEARBY_GAP_THRESHOLD=3
TOKEN_BUDGET=3000

# 服务
LISTEN_PORT=3001
LOG_VERBOSITY=info

第二层：启动校验

服务启动时严格校验必填项和参数范围，防止带病上线：

// 示意：配置校验规则
const RULES = {
  LLM_API_KEY:    { required: true },
  LLM_API_URL:    { required: true },
  LLM_MODEL_NAME: { fallback: 'default-model' },
  FILE_CONCURRENCY: { fallback: 3, min: 1, max: 10 },
  LISTEN_PORT:    { fallback: 3001, min: 1024, max: 65535 },
};

function verifyConfig(env) {
  const issues = [];
  for (const [key, rule] of Object.entries(RULES)) {
    if (rule.required && !env[key]) {
      issues.push(`缺少必填项: ${key}`);
    }
  }
  if (issues.length) {
    console.error('配置校验不通过:', issues.join('; '));
    process.exit(1);
  }
}

第三层：审查规则层

审查力度、技术栈规则、项目自定义规则独立配置，支持热加载。

---

落地部署｜Docker 容器化极简部署方案

Dockerfile

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

EXPOSE 3001
CMD ["node", "src/main.js"]

CI/CD 流程

代码合入主分支
  → CI 触发
  → npm install
  → Docker 镜像构建 & 打 Tag
  → 推送到私有镜像仓库
  → K8s 滚动更新

Webhook 配置

在 GitLab / GitHub 项目设置中添加 Webhook：

• Payload URL : https://your-service.com/hook/{platform}
• Trigger: Merge Request / Pull Request 事件
• Secret: 可选，用于验签

---

落地价值｜真实提效效果与团队收益

效率提升

经过一个多月的落地运行，主要数据变化：

• CR 周期缩短约 30%：AI 自动拦截了大部分低级问题，人工 CR 可以直接关注架构和逻辑层面
• 重复性审查工作减少约 40%：命名规范、类型错误、常见语法问题基本由 AI 兜底
• 新人代码基础错误减少约 50%：AI 在提交阶段就给出反馈，新人不再需要等人工 CR 才知道哪里写错了

团队价值

• 新人快速对齐团队编码规范：AI 审查自带团队规则，新人提交代码后立刻收到针对性反馈
• 老成员评审负担显著降低：不再需要为「变量少写了个 s」「少了个空值判断」这种事写评论
• 编码规范落地更统一：以前规范靠口口相传，现在 AI 每次审查都在强化同一套规则

---

开发复盘｜踩过的坑与设计取舍

坑 1：大 MR 直接超上下文，AI 看不完

现象：有人一次提交改了 40 个文件，直接超出 AI 上下文限制，审查效果断崖式下降。

解法 ：按文件拆分 → 每文件内再按 Cluster 拆分 → 分批调用 AI，每批控制 Token 预算。同时加了一层文件过滤，跳过 .lock、.map 等无关文件。

坑 2：AI 输出格式不稳定

现象：让 AI 返回 JSON，它时不时多打个逗号、少个引号，解析失败率居高不下。

解法 ：放弃 JSON 格式，改用编号文本格式 （1. PASS / 2. [类型] 标题 | 建议），解析容错度大幅提升。同时在解析层加了兜底逻辑，格式不对就按行号顺序映射。

坑 3：AI 审查结果和团队习惯不匹配

现象：初期 AI 经常输出一些「看起来对但不符合团队风格」的建议，团队成员吐槽「没用」。

解法 ：把团队 ESLint 规则、常见错误案例写进 Prompt 的自定义规则区。另外加了低质量过滤，把「代码看起来不错」「可以考虑改进」这种模糊输出直接过滤掉。

坑 4：评论重复刷屏，大家直接不看

现象：MR 每次更新都触发全量审查，同样的代码反复贴评论，开发者直接屏蔽通知。

解法 ：实现双重去重------发布评论前检查已有评论，行范围重叠 + 文本相似度高的直接跳过。

坑 5：AI 服务偶尔挂，整个审查就断了

现象：AI 服务一抽风，审查任务直接报错，评论一条都发不出来。

解法：三级降级 + 重试。批量失败就逐条，逐条失败就跳过，总之保证流程不中断。