job51-gitlab-cr-node-jt-1 2.4.7 → 2.4.9

package/docs/GITLAB_CR_NODE_TECHNICAL_DOCS.md

@@ -1,9 +1,9 @@
 # GitLab Code Review AI Tool 技术文档
 
 **项目名称**: job51-gitlab-cr-node  
-**当前版本**: 2.4.1  
+**当前版本**: 2.4.9  
 **作者**: tao.jing  
-**最后更新**: 2026-04-15  
+**最后更新**: 2026-04-16  
 **项目地址**: https://gitdev.51job.com/51jobweb/ai-agent  
 **当前分支**: jt-test-skill
 
@@ -338,7 +338,7 @@ class GitLabAPIClient {
 
 ## 4. 关键算法与流程
 
-### 4.1 严重问题判断逻辑（核心）
+### 4.1 严重问题判断逻辑（核心）（2.4.4 更新）
 
 **位置**: `index.js:55-133`
 
@@ -368,9 +368,9 @@ class GitLabAPIClient {
 │  │ const hasSeriousProblem =                             │ │
 │  │     claudeResult.includes('严重问题')                   │ │
 │  │                                                        │ │
-│  │ 如果 false → 无严重问题                                │ │
-│  │   返回：{ reportContent: claudeResult,                 │ │
-│  │           lineInfo: lineInfoContent }                  │ │
+│  │ 如果 false → 无严重问题，返回标准空格式                 │ │
+│  │   reportContent: '<REPORT>\n## 🤖 AI 代码审查结果\n\n</REPORT>'│ │
+│  │   lineInfo: '[]'                                       │ │
 │  └───────────────────────────────────────────────────────┘ │
 │                          ↓ (有严重问题)                     │
 │  步骤 4: 检查标题是否符合要求                               │
@@ -390,7 +390,7 @@ class GitLabAPIClient {
 | 判断步骤 | 检查内容 | 判断条件 | 通过时动作 | 失败时动作 |
 |----------|----------|----------|------------|------------|
 | **步骤 1** | LINE_INFO 标签存在性 | `hasLineInfoTag && hasNonEmptyLineInfo` | 进入步骤 2 | 返回空格式 |
-| **步骤 2** | 严重问题关键词 | `claudeResult.includes('严重问题')` | 进入步骤 3 | 返回原报告 |
+| **步骤 2** | 严重问题关键词 | `claudeResult.includes('严重问题')` | 进入步骤 3 | 返回空格式 |
 | **步骤 3** | 标题格式正确性 | `claudeResult.includes('🤖 AI 代码审查结果')` | 接受结果 | 重试 (最多 5 次) |
 
 **重试策略详情**:
@@ -413,6 +413,10 @@ if (attempts >= maxAttempts) {
 [DEBUG] ... 【决策】报告包含严重问题且标题正确，接受结果 (尝试 1)
 ```
 
+**v2.4.4 变更**：
+- 无严重问题时统一返回标准空格式（之前返回原始结果）
+- 达到最大重试次数时返回最后一次 AI 结果（之前返回空格式）
+
 ### 4.2 评论发布决策逻辑
 
 **位置**: `index.js:173-183`
@@ -491,11 +495,11 @@ getDiffBlocks(diffObj) {
 | 空格 | `current_line++` | 上下文代码，计入行号 |
 | `-` | 不变 | 删除代码，不计入行号 |
 
-### 4.4 评论发布核心逻辑（详细）
+### 4.4 评论发布核心逻辑（详细）（2.4.6/2.4.7 更新）
 
-**位置**: `index.js:497-589`
+**位置**: `index.js:577-665`
 
-**完整发布流程**:
+**完整发布流程**（v2.4.6 更新）:
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                        评论发布完整流程                                  │
@@ -509,54 +513,75 @@ getDiffBlocks(diffObj) {
 │  │ - start_sha: 起始提交 SHA                                          │ │
 │  └───────────────────────────────────────────────────────────────────┘ │
 │                                ↓                                        │
-│  步骤 2: 确定目标行号 (targetLine)                                       │
+│  步骤 2: 解析 LINE_INFO 中的所有问题行号                                  │
 │  ┌───────────────────────────────────────────────────────────────────┐ │
-│  │ 优先级 1: LINE_INFO 标签解析的行号 (最精确)                          │ │
-│  │ 优先级 2: diff 块起始行号 (后备方案)                                 │ │
+│  │ allLineInfo = parseAllLineInfoFromReviewResult(lineInfoTag)       │ │
 │  │                                                                    │ │
-│  │ 验证：parsedLineInfo.new_line 必须在 [new_start, new_end] 范围内   │ │
+│  │ v2.4.6 新增：支持多个问题行号                                       │ │
 │  └───────────────────────────────────────────────────────────────────┘ │
 │                                ↓                                        │
-│  步骤 3: 选择评论类型                                                   │
+│  步骤 3: 循环处理每个问题                                               │
 │  ┌───────────────────────────────────────────────────────────────────┐ │
-│  │ 有 targetLine → Diff 评论 (行级评论，定位到具体代码行)                │ │
-│  │ 无 targetLine → 一般讨论 (文件级评论)                               │ │
+│  │ for (let i = 0; i < allLineInfo.length; i++)                      │ │
+│  │   a. 提取单个问题报告内容                                          │ │
+│  │      singleProblemContent = extractSingleProblemReport(i + 1)     │ │
+│  │   b. 构建目标行号                                                  │ │
+│  │      - 删除代码：使用 old_line + old_path                         │ │
+│  │      - 新增/上下文：使用 new_line + new_path                      │ │
+│  │   c. 发布评论到对应行                                              │ │
+│  │   d. GitLab API 失败降级为一般讨论                                  │ │
 │  └───────────────────────────────────────────────────────────────────┘ │
 │                                ↓                                        │
-│  步骤 4: 调用 GitLab API 发布评论                                         │
-│  ┌───────────────────────────────────────────────────────────────────┐ │
-│  │ Diff 评论失败 → 自动降级为一般讨论                                  │ │
-│  └───────────────────────────────────────────────────────────────────┘ │
+│  步骤 4: 所有评论发布完成                                               │
 └─────────────────────────────────────────────────────────────────────────┘
 ```
 
-**targetLine 确定逻辑**:
+**targetLine 确定逻辑**（v2.4.7 更新）:
 ```javascript
-// 第一层：根据 diff 块第一行字符类型确定基础 targetLine
-let targetLine = lineInfo.firstLineFirstChar === '+'
-  ? { new_line: lineInfo.new_start, new_path: diff_info.new_path }
-  : lineInfo.firstLineFirstChar === '-'
-    ? { old_line: lineInfo.old_start, old_path: diff_info.old_path }
-    : { new_line: lineInfo.new_start, new_path: diff_info.new_path };
-
-// 第二层：尝试从 LINE_INFO 标签解析更精确的行号
-const parsedLineInfo = this.parseLineInfoFromReviewResult(lineInfoTag);
-if (parsedLineInfo) {
-  // 验证行号是否在 diff 块范围内
-  const newStart = lineInfo.new_start;
-  const newCount = lineInfo.new_count || 0;
-  const newEnd = newStart + newCount - 1;
+// v2.4.7：直接使用 AI 返回的绝对行号，不再验证范围
+for (let i = 0; i < allLineInfo.length; i++) {
+  const problemInfo = allLineInfo[i];
   
-  if (parsedLineInfo.new_line >= newStart && parsedLineInfo.new_line <= newEnd) {
-    // 行号有效，使用解析结果
-    targetLine = parsedLineInfo;
-  } else {
-    // 行号越界，使用 diff 块起始行号
-    debugLog(`解析的行号 ${parsedLineInfo.new_line} 不在 diff 块范围 [${newStart}, ${newEnd}] 内`);
+  let targetLine;
+  if (problemInfo.old_line && !problemInfo.new_line) {
+    // 删除代码，使用 old_line
+    targetLine = {
+      old_path: problemInfo.old_path,
+      old_line: problemInfo.old_line
+    };
+  } else if (problemInfo.new_line) {
+    // AI 返回的是文件中的绝对行号，直接使用
+    targetLine = {
+      new_path: problemInfo.new_path,
+      new_line: problemInfo.new_line
+    };
   }
+  
+  if (!targetLine) {
+    // 无法解析行号，使用一般讨论
+    await this.createGeneralDiscussion(...);
+    continue;
+  }
+  
+  // 发布评论到对应行
+  const payload = {
+    body: singleProblemContent,
+    position: {
+      position_type: 'text',
+      base_sha: baseSha,
+      head_sha: headSha,
+      start_sha: startSha,
+      ...targetLine
+    }
+  };
 }
 ```
 
+**v2.4.7 重要变更**：
+- **移除行号范围验证**：之前会验证 `parsedLineInfo.new_line ∈ [new_start, new_end]`
+- **直接使用绝对行号**：AI 返回的行号是文件中的绝对行号，直接使用
+- **原因**：AI 读取完整源文件后定位问题，返回的是文件实际行号，不是基于 `New Start` 计算的
+
 **GitLab API Payload 结构**:
 ```javascript
 // Diff 评论 Payload
@@ -626,38 +651,52 @@ async processWithThreadPool(tasks, processor, maxConcurrency = 3) {
 export GITLAB_CR_CONCURRENCY=5  # 默认 3
 ```
 
-### 4.6 行号解析算法
+### 4.6 行号解析算法（2.4.7 更新）
+
+**行号定义**：
+- 行号是变更后文件中的**绝对行号**（从 1 开始计数）
+- 例如：如果新增代码在变更后文件的第 43 行，则 `new_line = 43`
 
-**位置**: `index.js:435-470`
+**重要变更**（v2.4.7）：
+- **v2.4.7 之前**：使用 diff 块的 `New Start` 作为基准计算行号，并验证行号是否在 diff 块范围内
+- **v2.4.7 及之后**：AI 直接返回文件中的绝对行号，不再基于 `New Start` 计算，移除范围验证
 
-**LINE_INFO 解析函数**:
+**原因**：
+- AI 会读取完整的变更后文件来分析上下文
+- AI 在完整源文件中定位问题，返回的是文件中的绝对行号
+- 使用 `New Start` 验证行号范围会导致误判（如 diff 块 `New Start=1` 但 AI 返回行号 43）
+
+**原解析函数**：
 ```javascript
 parseLineInfoFromReviewResult(lineInfoTag) {
-  // 1. 从标签中提取 JSON 内容
+  // 从标签中提取 JSON 内容
   const jsonContent = lineInfoTag
     .replace(/<LINE_INFO>\s*/g, '')
     .replace(/\s*<\/LINE_INFO>/g, '')
     .trim();
   
-  // 2. 空数组处理 → 使用后备方案
   if (jsonContent === '[]') {
-    debugLog('LINE_INFO 为空数组，使用 diff 块起始行号作为后备方案');
-    return null;
+    return null; // 空数组使用后备方案
   }
   
-  // 3. 解析 JSON 数组
   const lineInfoArray = JSON.parse(jsonContent);
+  // 返回第一个问题的行号信息
+  return lineInfoArray[0];
+}
+```
+
+**新增解析函数**（v2.4.6）：
+```javascript
+parseAllLineInfoFromReviewResult(lineInfoTag) {
+  // 解析 LINE_INFO 中的所有问题行号
+  const jsonContent = lineInfoTag
+    .replace(/<LINE_INFO>\s*/g, '')
+    .replace(/\s*<\/LINE_INFO>/g, '')
+    .trim();
   
-  // 4. 返回第一个问题的行号信息
-  if (Array.isArray(lineInfoArray) && lineInfoArray.length > 0) {
-    const lineInfo = lineInfoArray[0];
-    return {
-      new_path: lineInfo.new_path,
-      new_line: lineInfo.new_line
-    };
-  }
+  if (jsonContent === '[]') return [];
   
-  return null; // 解析失败，使用后备方案
+  return JSON.parse(jsonContent);
 }
 ```
 
@@ -669,27 +708,7 @@ parseLineInfoFromReviewResult(lineInfoTag) {
 | 删除代码 (`-`) | 使用 `old_line` + `old_path` |
 | 上下文代码 | 使用 `new_line` + `new_path` |
 
-**行号验证逻辑**:
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    行号验证流程                              │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  1. 从 LINE_INFO 解析行号 → parsedLineInfo.new_line          │
-│                          ↓                                  │
-│  2. 计算 diff 块范围                                         │
-│     new_start = line_info.new_start                         │
-│     new_end = new_start + new_count - 1                     │
-│                          ↓                                  │
-│  3. 验证：parsedLineInfo.new_line ∈ [new_start, new_end]    │
-│                          ↓                                  │
-│  4. 判断：                                                   │
-│     - 在范围内 → 使用解析行号 (精确)                         │
-│     - 越界 → 使用 diff 块起始行号 (后备)                       │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 4.7 评论发布策略
+### 4.7 评论发布策略（2.4.6 更新）
 
 **增量发布模式** (`index.js:174-183`):
 ```javascript
@@ -701,14 +720,93 @@ if (review_result.includes('严重问题')) {
 }
 ```
 
-**行级评论定位** (`index.js:529-552`):
+**多问题评论发布**（v2.4.6 新增）：
 ```javascript
-// 优先使用 LINE_INFO 解析的行号
-const parsedLineInfo = this.parseLineInfoFromReviewResult(lineInfoTag);
-if (parsedLineInfo.new_line 在 diff 块范围内) {
-  targetLine = parsedLineInfo;
-} else {
-  targetLine = diff_block_start_line; // 后备方案
+// 一个 diff 块有多个问题时，为每个问题发布单独的评论
+for (let i = 0; i < allLineInfo.length; i++) {
+  const problemInfo = allLineInfo[i];
+  // 提取单个问题的报告内容
+  const singleProblemContent = this.extractSingleProblemReport(fullReportContent, i + 1);
+```
+
+**版本信息缓存**（v2.4.8 新增）:
+```javascript
+// 构造函数中初始化缓存
+constructor() {
+  this._versionCache = new Map();  // 缓存 MR 版本信息
+}
+
+// 获取版本信息（带缓存）
+async getVersionInfo(projectId, mergeRequestIid) {
+  const cacheKey = `${projectId}-${mergeRequestIid}`;
+  
+  // 检查缓存
+  if (this._versionCache.has(cacheKey)) {
+    return this._versionCache.get(cacheKey);
+  }
+  
+  // 从 API 获取并缓存
+  const versionInfo = await this.getMergeRequestVersions(projectId, mergeRequestIid);
+  this._versionCache.set(cacheKey, versionInfo);
+  return versionInfo;
+}
+```
+
+**缓存优化效果**:
+- **优化前**: 每个问题发布评论时都调用 `getMergeRequestVersions` API
+- **优化后**: 同一个 MR 的版本信息只获取一次，后续直接使用缓存
+- **适用场景**: 一个 diff 块有多个问题时，避免重复 API 调用
+  
+  // 构建目标行号
+  let targetLine;
+  if (problemInfo.old_line && !problemInfo.new_line) {
+    targetLine = { old_path: problemInfo.old_path, old_line: problemInfo.old_line };
+  } else if (problemInfo.new_line) {
+    // AI 返回的是文件中的绝对行号，直接使用
+    targetLine = { new_path: problemInfo.new_path, new_line: problemInfo.new_line };
+  }
+  
+  // 发布评论到对应行
+  await this.createDiffDiscussion(projectId, mergeRequestIid, {
+    body: singleProblemContent,
+    position: { ...targetLine, ...shaInfo }
+  });
+}
+```
+
+**行级评论定位**（v2.4.7 更新）：
+```javascript
+// v2.4.7：直接使用 AI 返回的绝对行号，不再验证范围
+if (problemInfo.new_line) {
+  // AI 返回的是文件中的绝对行号，直接使用
+  targetLine = {
+    new_path: problemInfo.new_path,
+    new_line: problemInfo.new_line
+  };
+}
+```
+
+**报告切分方法**（v2.4.6 新增）：
+```javascript
+extractSingleProblemReport(fullReport, problemIndex) {
+  // 使用 **问题 N**：模式来切分问题
+  const problemBlocks = [];
+  let currentBlock = [];
+  
+  for (const line of lines) {
+    const problemMatch = line.match(/\*\*问题\s*(\d+)\*\*/);
+    if (problemMatch) {
+      if (currentBlock.length > 0) {
+        problemBlocks.push(currentBlock.join('\n'));
+        currentBlock = [];
+      }
+      currentBlock.push(line);
+    } else {
+      currentBlock.push(line);
+    }
+  }
+  
+  return problemBlocks[problemIndex - 1];
 }
 ```
 
@@ -1288,6 +1386,79 @@ do {
 - 无问题的块跳过评论发布
 - 减少无效 API 调用
 
+### 11.4 性能指标收集（v2.4.8 新增）
+
+**指标收集器位置**: `utils.js:MetricsCollector`
+
+**收集的指标类型**:
+
+| 指标类型 | 具体内容 | 用途 |
+|----------|----------|------|
+| **审查统计** | 文件数、diff 块数、问题数、严重问题数、评论发布数 | 了解审查覆盖范围和问题分布 |
+| **耗时统计** | 总耗时、平均每块耗时、各块耗时明细 | 识别整体性能表现 |
+| **按 Diff 大小分析** | small (0-50 行)、medium (51-200 行)、large (200+ 行) 的块数和耗时 | 优化 diff 拆分策略，确定最佳并发粒度 |
+| **按文件类型分析** | 各文件类型（.java/.js/.vue 等）的块数和平均耗时 | 识别特定文件类型的性能特征 |
+| **慢调用分析** | 记录超过 10 秒的调用（文件、diff 大小、耗时） | 定位性能瓶颈，优化慢路径 |
+| **AI 调用统计** | 总调用数、成功数、失败数、重试数 | 评估 AI 服务稳定性，优化重试策略 |
+| **GitLab API 统计** | 总调用数、成功数、失败数 | 评估 GitLab API 可用性 |
+
+**性能分析输出示例**:
+
+```
+========== 审查统计 ==========
+审查文件数：5
+审查 diff 块数：12
+发现问题总数：3
+严重问题数：2
+发布评论数：2
+总耗时：45.32s
+平均每块耗时：3.78s
+AI 调用：12/12 (成功率：100.0%)
+AI 重试次数：2
+GitLab API: 8/8
+
+--- 按 Diff 块大小分析 ---
+small (0-50 行): 5 块，平均耗时 1.2s, 总耗时 6.0s
+medium (51-200 行): 5 块，平均耗时 3.5s, 总耗时 17.5s
+large (200+ 行): 2 块，平均耗时 10.9s, 总耗时 21.8s
+
+--- 按文件类型分析 ---
+.java: 8 块，平均耗时 4.2s
+.js: 3 块，平均耗时 2.1s
+.vue: 1 块，平均耗时 1.5s
+
+--- 慢调用分析 (>10 秒) ---
+文件：src/service/UserService.java, Diff 大小：250 行，耗时：15.3s
+文件：src/controller/UserController.java, Diff 大小：180 行，耗时：12.1s
+===============================
+```
+
+**指标使用场景**:
+
+1. **优化 diff 拆分策略**：如果 large 块平均耗时远高于 small 块，可以考虑减小 diff 块大小阈值
+2. **优化并发配置**：根据慢调用分析，调整 `GITLAB_CR_CONCURRENCY` 环境变量
+3. **识别性能瓶颈**：通过慢调用分析定位耗时最长的文件类型和 diff 大小
+4. **容量规划**：根据 diff 大小和耗时的关系，预估大规模代码审查的耗时
+
+### 11.5 日志分级（v2.4.8 新增）
+
+**日志级别**: `DEBUG < INFO < WARN < ERROR`
+
+**环境变量控制**:
+```bash
+# 设置日志级别（默认：DEBUG）
+export LOG_LEVEL=0  # DEBUG：输出所有日志
+export LOG_LEVEL=1  # INFO：输出 INFO 及以上级别
+export LOG_LEVEL=2  # WARN：输出 WARN 及以上级别
+export LOG_LEVEL=3  # ERROR：只输出 ERROR
+```
+
+**日志函数**:
+- `debugLog(message)`: 调试信息（默认输出）
+- `infoLog(message)`: 关键里程碑（审查开始/结束、统计摘要）
+- `warnLog(message)`: 可恢复的问题
+- `errorLog(message)`: 需要关注的错误
+
 ---
 
 ## 12. 扩展与维护
@@ -1323,11 +1494,13 @@ npm run dev
 
 | 版本 | 日期 | 变更说明 |
 |------|------|----------|
-| 2.4.1 | 2026-04-08 | 修复 AI 审查结果为空时的返回值 |
-### 12.3 版本历史
-
-| 版本 | 日期 | 变更说明 |
-|------|------|----------|
+| 2.4.9 | 2026-04-16 | **代码优化与性能指标收集**：(1) 删除已废弃的 `reviewDiffWithClaude` 方法，精简 79 行代码；(2) 添加 GitLab 版本信息缓存机制，避免重复 API 调用；(3) 实现日志分级系统（DEBUG/INFO/WARN/ERROR），支持通过 `LOG_LEVEL` 环境变量控制输出级别；(4) 实现完整的性能指标收集器 `MetricsCollector`，收集 diff 块大小/文件类型/耗时分布，慢调用分析 (>10 秒)，AI/API 调用成功率，评论发布统计等，输出按 diff 大小（small/medium/large）和文件类型分组的性能分析，支持识别性能瓶颈和优化审查策略 |
+| 2.4.7 | 2026-04-15 | **行号计算逻辑重大修正**：修正 AI 行号计算方式，从使用 `New Start` 基准计算改为返回文件绝对行号；移除基于 diff 块范围的行号验证逻辑；更新 `code-review-rules.md` 和 `SKILL.md` 中的行号计算规范说明 |
+| 2.4.6 | 2026-04-15 | **多问题评论发布支持**：新增 `parseAllLineInfoFromReviewResult` 方法解析所有问题行号；新增 `extractSingleProblemReport` 方法切分单个问题报告；重构 `postSingleCommentToGitLab` 方法支持循环发布多条评论，每条评论定位到对应问题的行号 |
+| 2.4.5 | 2026-04-15 | **报告模板格式优化**：更新 `SKILL.md` 输出模板，使用 `**问题 N**：` 格式替代带圈数字序号；移除问题间的 `---` 分隔符，简化报告切分逻辑 |
+| 2.4.4 | 2026-04-15 | **标题验证逻辑修复**：修复 AI 审查结果标题验证逻辑，当有严重问题但标题不符合要求时重试，达到最大重试次数后返回最后一次结果 |
+| 2.4.3 | 2026-04-15 | **调试日志增强**：在 `getDiffBlocks` 方法中添加 diff 块解析日志，记录 `new_start` 和 `new_count` 值；添加文件拆分块数日志 |
+| 2.4.2 | 2026-04-15 | **元数据增强**：在临时 diff 文件中添加 `New Start` 和 `New Count` 元数据，供 AI 参考计算行号 |
 | 2.4.1 | 2026-04-08 | 修复 AI 审查结果为空时的返回值 |
 | 2.4.0 | 2026-03-25 | 更新 MR 审查模板 |
 | 2.3.8 | 2026-03-25 | 优化 AI 审核结果处理逻辑 |