job51-gitlab-cr-node-jt-1 2.4.8 → 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.7  
+**当前版本**: 2.4.9  
 **作者**: tao.jing  
-**最后更新**: 2026-04-15  
+**最后更新**: 2026-04-16  
 **项目地址**: https://gitdev.51job.com/51jobweb/ai-agent  
 **当前分支**: jt-test-skill
 
@@ -727,6 +727,35 @@ 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;
@@ -1357,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. 扩展与维护
@@ -1392,6 +1494,7 @@ npm run dev
 
 | 版本 | 日期 | 变更说明 |
 |------|------|----------|
+| 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**：` 格式替代带圈数字序号；移除问题间的 `---` 分隔符，简化报告切分逻辑 |