job51-gitlab-cr-node-jt-1 3.1.2 → 3.1.4

package/.claude/rules/system_rules.json

@@ -0,0 +1,25 @@
+{
+  "default_rule": "code-review-rules.md",
+  "path_rule_map": {
+    "**/*.java": "java.md",
+    "**/*.{ts,tsx}": "typescript.md",
+    "**/*.js": "javascript.md",
+    "**/*.py": "python.md",
+    "**/*.go": "go.md",
+    "**/*.rs": "rust.md",
+    "**/pom.xml": "maven.md",
+    "**/package.json": "npm.md",
+    "**/Cargo.toml": "cargo.md",
+    "**/*.xml": "xml.md",
+    "**/*.sql": "sql.md",
+    "**/*.yaml": "yaml.md",
+    "**/*.yml": "yaml.md",
+    "**/*.json": "json.md",
+    "**/*.properties": "properties.md",
+    "**/*.md": "markdown.md",
+    ".github/workflows/**/*.{yaml,yml}": "github_workflows.md",
+    "**/Dockerfile": "dockerfile.md",
+    "**/docker-compose.{yaml,yml}": "docker_compose.md"
+  },
+  "_comment": "规则优先级: CLI覆盖 > 项目配置 > 用户配置 > 内置规则"
+}

package/.claude/rules/typescript.md

@@ -0,0 +1,229 @@
+# TypeScript/JavaScript 代码审查规则
+
+**继承通用规则**：本规则基于 `code-review-rules.md`，并补充 TypeScript/JavaScript 语言特定的审查要点。
+
+---
+
+## TypeScript/JavaScript 语言特定审查规则
+
+### 一、类型安全问题（TypeScript 特定）
+
+#### 1. any 类型滥用
+> - **检测场景**：变量、参数、返回值显式声明为 any
+> - **建议报告**：应使用具体类型或 unknown（需类型守卫）
+> - **示例**：
+    ```typescript
+    // 错误 ❌
+    function process(data: any) { ... }
+
+    // 正确 ✓
+    function process(data: unknown) {
+      if (typeof data === 'string') { ... }
+    }
+    ```
+
+#### 2. 类型断言风险
+> - **检测场景**：使用 as 进行类型断言，可能绕过类型检查
+> - **风险**：断言错误时运行时崩溃
+> - **建议报告**：类型断言后的代码应验证目标类型
+
+#### 3. 可空类型未处理
+> - **检测场景**：访问可能为 null/undefined 的对象属性
+> - **必须报告**：未使用可选链 (?.) 或非空断言 (!) 且无判空逻辑
+> - **示例**：
+    ```typescript
+    // 错误 ❌
+    const name = user.profile.name; // profile 可能为 undefined
+
+    // 正确 ✓
+    const name = user.profile?.name;
+    const name = user.profile!.name; // 明确非空断言
+    ```
+
+### 二、异步编程问题（JS/TS 特定）
+
+#### 1. Promise 未处理
+> - **检测场景**：调用 async 函数或 Promise 但未 await/catch
+> - **必须报告**：Promise rejection 未处理会导致进程退出
+> - **示例**：
+    ```typescript
+    // 错误 ❌
+    asyncFunction(); // 未 await，异常丢失
+    asyncFunction().then(data => ...); // 无 catch
+
+    // 正确 ✓
+    await asyncFunction();
+    asyncFunction().then(...).catch(err => ...);
+    ```
+
+#### 2. async/await 混用问题
+> - **检测场景**：async 函数内使用 .then() 而非 await
+> - **建议报告**：async 函数内应统一使用 await
+
+#### 3. Promise 构造函数反模式
+> - **检测场景**：new Promise 内包裹已有 Promise
+> - **必须报告**：
+    ```typescript
+    // 错误 ❌
+    return new Promise((resolve, reject) => {
+      otherPromise.then(resolve).catch(reject); // 无意义包装
+    });
+
+    // 正确 ✓
+    return otherPromise;
+    ```
+
+#### 4. 并行异步等待问题
+> - **检测场景**：顺序 await 多个独立 Promise（应并行）
+> - **建议报告**：
+    ```typescript
+    // 错误 ❌：顺序等待，浪费时间
+    const a = await fetchA();
+    const b = await fetchB(); // fetchA 和 fetchB 独立，可并行
+
+    // 正确 ✓
+    const [a, b] = await Promise.all([fetchA(), fetchB()]);
+    ```
+
+### 三、内存泄漏问题（JS/TS 特定）
+
+#### 1. 事件监听器未移除
+> - **检测场景**：addEventListener 但无对应 removeEventListener
+> - **必须报告**：组件销毁时应移除事件监听器
+> - **特别注意**：React useEffect 中的事件监听器清理
+
+#### 2. 定时器未清理
+> - **检测场景**：setInterval/setTimeout 但无对应 clearInterval/clearTimeout
+> - **必须报告**：组件销毁时未清理定时器
+
+#### 3. closure 内存泄漏
+> - **检测场景**：闭包持有大对象引用且生命周期过长
+> - **建议报告**：闭包内持有 DOM 元素、大数组等
+
+### 四、React/Vue 特定问题
+
+#### 1. React Hooks 依赖缺失
+> - **检测场景**：useEffect/useMemo/useCallback 缺少必要依赖
+> - **必须报告**：依赖数组遗漏会触发 stale closure 问题
+> - **示例**：
+    ```typescript
+    // 错误 ❌
+    useEffect(() => {
+      fetchData(userId); // userId 在依赖中
+    }, []); // 缺少 userId
+
+    // 正确 ✓
+    useEffect(() => {
+      fetchData(userId);
+    }, [userId]);
+    ```
+
+#### 2. React 状态直接修改
+> - **检测场景**：直接修改 state 对象而非 setState/useState
+> - **必须报告**：
+    ```typescript
+    // 错误 ❌
+    state.items.push(newItem);
+    state.count = state.count + 1;
+
+    // 正确 ✓
+    setState({ ...state, items: [...state.items, newItem] });
+    setState(prev => ({ count: prev.count + 1 }));
+    ```
+
+#### 3. React useEffect 无限循环
+> - **检测场景**：useEffect 内 setState 触发重新渲染
+> - **必须报告**：依赖数组包含每次渲染都变化的值（如对象引用）
+
+#### 4. Vue computed vs methods 混用
+> - **检测场景**：computed 属性内执行副作用操作
+> - **必须报告**：computed 应纯计算，methods 可执行副作用
+
+### 五、数组/对象操作问题（JS/TS 特定）
+
+#### 1. 数组遍历中修改
+> - **检测场景**：forEach/map/filter 中修改原数组
+> - **必须报告**：可能导致意外行为
+> - **示例**：
+    ```typescript
+    // 错误 ❌
+    arr.forEach(item => {
+      if (item.id === 1) arr.splice(arr.indexOf(item), 1); // 遍历中删除
+    });
+
+    // 正确 ✓
+    const newArr = arr.filter(item => item.id !== 1);
+    ```
+
+#### 2. 对象引用共享问题
+> - **检测场景**：多个变量引用同一对象，修改相互影响
+> - **建议报告**：需要独立副本时应使用深拷贝或浅拷贝
+
+#### 3. 数组 indexOf vs includes
+> - **检测场景**：使用 arr.indexOf(x) !== -1 检查存在性
+> - **建议报告**：arr.includes(x) 更语义化（非强制）
+
+### 六、错误处理问题（JS/TS 特定）
+
+#### 1. try-catch 空 catch
+> - **检测场景**：catch 块为空或仅 console.log
+> - **必须报告**：错误被吞没
+
+#### 2. throw 非错误对象
+> - **检测场景**：throw string/object 而非 Error 实例
+> - **必须报告**：应 throw new Error(message) 或自定义 Error 类
+
+#### 3. async 函数未捕获同步异常
+> - **检测场景**：async 函数内同步代码异常未包裹
+> - **建议报告**：async 函数内所有可能异常的代码应在 try-catch 内
+
+### 七、Node.js 特定问题
+
+#### 1. 回调地狱
+> - **检测场景**：多层嵌套回调函数
+> - **建议报告**：应使用 async/await 或 Promise 链
+
+#### 2. 未处理 process 事件
+> - **检测场景**：未监听 uncaughtException, unhandledRejection
+> - **建议报告**：生产环境应监听这些事件防止进程崩溃
+
+#### 3. 流未正确处理
+> - **检测场景**：ReadStream/WriteStream 未处理 error 事件
+> - **必须报告**：流操作应有错误处理
+
+#### 4. require 动态路径
+> - **检测场景**：require(variablePath) 动态加载模块
+> - **建议报告**：可能加载恶意代码，应限制路径范围
+
+### 八、安全问题（JS/TS 特定）
+
+#### 1. eval 使用
+> - **检测场景**：使用 eval, Function, setTimeout(string) 执行动态代码
+> - **必须报告**：存在 XSS/代码注入风险
+
+#### 2. 内联用户输入
+> - **检测场景**：用户输入直接拼接到 HTML/SQL/命令
+> - **必须报告**：XSS/SQL 注入/命令注入风险
+
+#### 3. localStorage 安全
+> - **检测场景**：敏感数据存储到 localStorage
+> - **必须报告**：localStorage 无加密，敏感信息泄露风险
+
+---
+
+## TypeScript/JavaScript 审查优先级
+
+| 问题类型 | 优先级 | 说明 |
+|----------|--------|------|
+| Promise 未处理 | 🔴 严重 | 进程可能崩溃 |
+| async 函数空 catch | 🔴 严重 | 错误被吞没 |
+| 事件监听器未移除 | 🔴 严重 | 内存泄漏 |
+| React 状态直接修改 | 🔴 严重 | 状态不一致 |
+| React Hooks 依赖缺失 | 🔴 严重 | stale closure |
+| 可空类型未处理 | 🔴 严重 | 运行时 TypeError |
+| 数组遍历中修改 | 🔴 严重 | 意外行为 |
+| eval 使用 | 🔴 严重 | 安全漏洞 |
+| throw 非错误对象 | 🟡 警告 | 错误追踪困难 |
+| any 类型滥用 | 🟡 警告 | 类型安全降低 |
+| 并行异步顺序等待 | 🟡 警告 | 性能问题 |
+| 回调地狱 | 🟡 警告 | 可读性差 |

package/README.md

@@ -46,10 +46,29 @@ gitlab-cr
 - 使用 Claude AI 进行代码审查
 - 生成结构化的审查报告
 - 将审查结果发布到 GitLab MR
+- **分阶段审查**：快速扫描过滤低价值变更，减少 token 消耗
 - 自动跳过测试文件（如 `*Test.java`、`*.test.js` 等）
 - 自动跳过 DTO/VO/Query 文件（如 `*Dto.java`、`*VO.java`、`*Query.java`、`*Request.java` 等）
 - 自动跳过非代码文件（如配置文件、文档文件、资源文件等）
 
+## Token 优化
+
+### 快速扫描机制
+
+在调用 AI 完整审查前，会先进行本地快速扫描，过滤以下低价值变更：
+
+| 跳过类型 | 示例 |
+|---------|------|
+| 纯 import 变更 | `import java.util.List;` |
+| 纯注释变更 | `// 注释内容`、`/* 多行注释 */` |
+| 纯空白/格式变更 | 空行、缩进调整 |
+| 纯注解变更 | `@Override`、`@Autowired` |
+| 纯 getter/setter | `getXxx()`、`setXxx()` |
+| 纯日志打印 | `log.info()`、`console.log()` |
+| 纯常量定义 | `private static final String XXX = "xxx";` |
+
+**预计效果**：减少 30-50% 的 AI 调用，显著降低 token 消耗。
+
 ## 依赖要求
 
 - Node.js 10+

package/index.js

@@ -5,6 +5,170 @@ const path = require('path');
 const fs = require('fs');
 const { GitLabAPIClient, debugLog, infoLog, warnLog, errorLog, extractReportContent, MetricsCollector } = require('./utils');
 
+// ========== 两阶段审查配置 ==========
+// Plan 阶段触发阈值：改动行数超过此值时执行风险分析
+const PLAN_LINE_THRESHOLD = 30;
+// Plan 阶段超时时间（毫秒）
+const PLAN_TIMEOUT_MS = 60000;
+
+/**
+ * 计算 diff 内容的改动行数（新增 + 删除）
+ * @param {string} diffContent diff 内容
+ * @returns {number} 改动行数
+ */
+function countChangeLines(diffContent) {
+  if (!diffContent || diffContent.trim() === '') return 0;
+  const lines = diffContent.split('\n');
+  // 只统计 + 或 - 开头的实际变更行（排除 +++ 和 --- 头信息）
+  return lines.filter(line =>
+    (line.startsWith('+') && !line.startsWith('+++')) ||
+    (line.startsWith('-') && !line.startsWith('---'))
+  ).length;
+}
+
+/**
+ * Plan 阶段：风险分析
+ * 分析代码变更，识别高风险区域，生成审查指导
+ * @param {string} filePath 文件路径
+ * @param {string} diffContent diff 内容
+ * @param {string} blockIdentifier 块标识（用于日志）
+ * @returns {Promise<Object|null>} Plan 结果对象或 null
+ */
+async function runPlanPhase(filePath, diffContent, blockIdentifier) {
+  debugLog(`[${blockIdentifier}] 开始 Plan 阶段风险分析...`);
+
+  const planPrompt = `你是一个代码审查风险分析专家。请分析以下代码变更，识别高风险点并生成审查指导。
+
+**文件路径**：${filePath}
+
+**变更内容**：
+${diffContent}
+
+---
+
+## 分析要求
+
+1. **只分析新增和修改的代码**（+ 开头的行），忽略删除代码
+2. **识别高风险区域**，按严重程度排序
+3. **输出结构化的审查指导**，帮助后续审查重点关注
+
+## 风险类型定义
+
+- **high（严重）**：安全漏洞、数据丢失风险、系统崩溃、关键功能失效
+  - 如：SQL注入、硬编码密钥、事务边界问题、并发安全问题
+- **medium（中等）**：性能问题、边界情况、潜在兼容性问题
+  - 如：循环内重复查询、资源未释放、异常处理不当
+- **low（轻微）**：代码风格、可读性、非关键最佳实践
+  - 如：命名不规范、注释缺失、代码冗余
+
+---
+
+## 输出格式（严格 JSON）
+
+直接输出 JSON，不要包裹在代码块中，不要任何额外文本：
+
+{
+  "change_summary": "改动摘要（一句话描述改动目的）",
+  "risk_areas": [
+    {
+      "severity": "high|medium|low",
+      "area": "风险类型（如：安全、并发、事务、边界）",
+      "location_hint": "大概位置提示（如：第 X-XX 行附近）",
+      "description": "具体风险描述（为什么这里是风险点）",
+      "focus_hint": "审查时重点检查什么"
+    }
+  ],
+  "review_guidance": "整体审查建议（一句话）"
+}
+
+---
+
+**开始分析**：`;
+
+  try {
+    const planStartTime = Date.now();
+    const planResult = await runClaudeCommand(planPrompt);
+    const planDuration = Date.now() - planStartTime;
+    debugLog(`[${blockIdentifier}] Plan 阶段完成，耗时 ${planDuration}ms，结果长度 ${planResult?.length || 0}`);
+
+    if (!planResult || planResult.trim() === '') {
+      debugLog(`[${blockIdentifier}] Plan 结果为空，跳过`);
+      return null;
+    }
+
+    // 解析 JSON 结果
+    // 尝试从 markdown 代码块中提取 JSON
+    let jsonContent = planResult.trim();
+    const jsonMatch = planResult.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    if (jsonMatch) {
+      jsonContent = jsonMatch[1].trim();
+    }
+
+    try {
+      const parsed = JSON.parse(jsonContent);
+      debugLog(`[${blockIdentifier}] Plan 结果解析成功：发现 ${parsed.risk_areas?.length || 0} 个风险点`);
+
+      // 验证结果结构
+      if (!parsed.change_summary || !parsed.risk_areas) {
+        debugLog(`[${blockIdentifier}] Plan 结果结构不完整，跳过`);
+        return null;
+      }
+
+      return parsed;
+    } catch (parseError) {
+      debugLog(`[${blockIdentifier}] Plan JSON 解析失败：${parseError.message}`);
+      // 解析失败但可能有有用的文本，尝试提取关键信息
+      return {
+        change_summary: '无法解析风险分析结果',
+        review_guidance: planResult.slice(0, 200),
+        risk_areas: []
+      };
+    }
+  } catch (error) {
+    debugLog(`[${blockIdentifier}] Plan 阶段执行失败：${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * 将 Plan 结果转换为审查指导文本
+ * @param {Object} planResult Plan 结果对象
+ * @returns {string} 审查指导文本（用于注入 Main 阶段 prompt）
+ */
+function buildPlanGuidanceText(planResult) {
+  if (!planResult || !planResult.risk_areas || planResult.risk_areas.length === 0) {
+    return '';
+  }
+
+  const riskItems = planResult.risk_areas
+    .sort((a, b) => {
+      // 按严重程度排序：high > medium > low
+      const order = { high: 0, medium: 1, low: 2 };
+      return (order[a.severity] || 2) - (order[b.severity] || 2);
+    })
+    .map((r, i) => {
+      const severityIcon = r.severity === 'high' ? '🔴' : (r.severity === 'medium' ? '🟡' : '🔵');
+      return `${i + 1}. **${severityIcon} [${r.severity.toUpperCase()}] ${r.area}**
+   - 位置提示：${r.location_hint || '需自行定位'}
+   - 风险描述：${r.description}
+   - 重点检查：${r.focus_hint}`;
+    })
+    .join('\n');
+
+  return `
+### 🎯 审查指导（基于风险分析）
+
+**改动摘要**：${planResult.change_summary}
+
+**重点关注区域**：
+${riskItems}
+
+**整体建议**：${planResult.review_guidance || '请针对性审查上述风险点，不要泛泛而谈'}
+
+**⚠️ 重要**：上述风险点是预先分析得出的，请重点审查这些区域，确认问题是否真实存在。
+`;
+}
+
 class GitLabCodeReviewer {
   constructor(gitlabToken, gitlabUrl = null) {
     debugLog(`GitLab客户端初始化: ${gitlabUrl}`);
@@ -312,6 +476,181 @@ class GitLabCodeReviewer {
     return false;
   }
 
+  /**
+   * 快速扫描判断 diff 内容是否值得审查（本地分析，不调用 AI）
+   * 用于过滤低价值变更，减少 token 消耗
+   * @param {string} diffContent diff 内容
+   * @param {string} filePath 文件路径（用于日志）
+   * @returns {{ worthReviewing: boolean, reason: string }} 是否值得审查及原因
+   */
+  quickScanDiffContent(diffContent, filePath = '') {
+    if (!diffContent || diffContent.trim() === '') {
+      return { worthReviewing: false, reason: 'diff 内容为空' };
+    }
+
+    // 解析 diff 行
+    const lines = diffContent.split('\n');
+    // 只关注新增行（+ 开头）和删除行（- 开头）
+    const changedLines = lines.filter(line =>
+      line.startsWith('+') || line.startsWith('-')
+    );
+
+    // 如果没有实际变更行，跳过
+    if (changedLines.length === 0) {
+      return { worthReviewing: false, reason: '没有实际变更行' };
+    }
+
+    // 统计各类变更
+    const stats = {
+      importChanges: 0,      // import 语句变更
+      commentChanges: 0,     // 注释变更
+      whitespaceChanges: 0,  // 空白/格式变更
+      getterSetterChanges: 0, // getter/setter 变更
+      logChanges: 0,         // 日志打印变更
+      constantChanges: 0,    // 常量定义变更
+      annotationChanges: 0,  // 注解变更（如 @Override, @Autowired）
+      meaningfulChanges: 0,  // 有意义的代码变更
+    };
+
+    // 分析每行变更
+    for (const line of changedLines) {
+      // 跳过 diff 头信息行（如 +++ b/file.txt）
+      if (line.startsWith('+++') || line.startsWith('---')) {
+        continue;
+      }
+
+      // 获取实际内容（去掉 +/- 前缀）
+      const content = line.substring(1).trim();
+
+      // 空行或纯空白
+      if (content === '' || /^\s*$/.test(content)) {
+        stats.whitespaceChanges++;
+        continue;
+      }
+
+      // import 语句（Java/JavaScript/Python 等）
+      if (/^import\s/.test(content) ||
+          /^from\s+['"]/.test(content) ||
+          /^require\s*\(/.test(content)) {
+        stats.importChanges++;
+        continue;
+      }
+
+      // 注释（单行或多行注释开始）
+      if (/^\/\/.*/.test(content) ||
+          /^\/\*.*\*\/$/.test(content) ||
+          /^\/\*[\s\S]*/.test(content) ||
+          /^\*[\s\S]*/.test(content) ||
+          /^#.*$/.test(content) ||
+          content.startsWith('*') ||
+          content.startsWith('//')) {
+        stats.commentChanges++;
+        continue;
+      }
+
+      // 注解（Java/Kotlin）
+      if (/^@\w+/.test(content) ||
+          /^@\w+\(/.test(content) ||
+          /^@Override/.test(content) ||
+          /^@Autowired/.test(content) ||
+          /^@Resource/.test(content) ||
+          /^@Inject/.test(content)) {
+        stats.annotationChanges++;
+        continue;
+      }
+
+      // getter/setter 方法
+      if (/^\s*(public|private|protected)?\s*\w+\s+get\w+\s*\(/.test(content) ||
+          /^\s*(public|private|protected)?\s*\w+\s+set\w+\s*\(/.test(content) ||
+          /^\s*public\s+\w+\s+is\w+\s*\(/.test(content) ||
+          /\.get\w+\(\)/.test(content) ||
+          /\.set\w+\(/.test(content)) {
+        // 只有 getter/setter 声明才算，调用不算
+        if (/^\s*(public|private|protected)?\s*\w+\s+(get|set|is)\w+\s*\(/.test(content)) {
+          stats.getterSetterChanges++;
+          continue;
+        }
+      }
+
+      // 日志打印语句
+      if (/^\s*(log|logger|Log|Logger|console)\.\w+\s*\(/.test(content) ||
+          /^\s*System\.out\.print/.test(content) ||
+          /^\s*System\.err\.print/.test(content) ||
+          /^\s*print\(/.test(content) ||
+          /^\s*println\(/.test(content) ||
+          /^\s*printf\(/.test(content) ||
+          /^\s*debugLog\(/.test(content) ||
+          /^\s*infoLog\(/.test(content) ||
+          /^\s*warnLog\(/.test(content) ||
+          /^\s*errorLog\(/.test(content)) {
+        stats.logChanges++;
+        continue;
+      }
+
+      // 常量定义（简单的静态常量）
+      if (/^\s*(public|private|protected)?\s*(static)?\s*(final)?\s*\w+\s+\w+\s*=\s*[^;]+;/.test(content) ||
+          /^\s*const\s+\w+\s*=/.test(content) ||
+          /^\s*static\s+final\s+\w+\s+\w+\s*=/.test(content)) {
+        stats.constantChanges++;
+        continue;
+      }
+
+      // 其他变更视为有意义的代码变更
+      stats.meaningfulChanges++;
+    }
+
+    // 判断是否值得审查
+    const totalChanges = changedLines.length;
+    const lowValueChanges = stats.importChanges + stats.commentChanges +
+                            stats.whitespaceChanges + stats.annotationChanges;
+
+    // 统计低价值变更比例
+    const lowValueRatio = totalChanges > 0 ? lowValueChanges / totalChanges : 0;
+
+    debugLog(`[${filePath}] 快速扫描统计: 总变更=${totalChanges}, import=${stats.importChanges}, 注释=${stats.commentChanges}, 空白=${stats.whitespaceChanges}, 注解=${stats.annotationChanges}, getter/setter=${stats.getterSetterChanges}, 日志=${stats.logChanges}, 常量=${stats.constantChanges}, 有意义=${stats.meaningfulChanges}, 低价值比例=${lowValueRatio.toFixed(2)}`);
+
+    // 决策规则
+    // 1. 如果没有任何有意义变更，跳过
+    if (stats.meaningfulChanges === 0) {
+      // 进一步检查：如果只有 getter/setter、日志、常量变更，也跳过
+      const onlyHelperChanges = stats.getterSetterChanges + stats.logChanges + stats.constantChanges;
+      if (onlyHelperChanges === totalChanges - stats.importChanges - stats.whitespaceChanges) {
+        return {
+          worthReviewing: false,
+          reason: `仅有辅助性变更（getter/setter=${stats.getterSetterChanges}, 日志=${stats.logChanges}, 常量=${stats.constantChanges}）`
+        };
+      }
+
+      return {
+        worthReviewing: false,
+        reason: `无有意义代码变更（import=${stats.importChanges}, 注释=${stats.commentChanges}, 空白=${stats.whitespaceChanges}, 注解=${stats.annotationChanges}）`
+      };
+    }
+
+    // 2. 如果低价值变更占比超过 90%，且有意义变更少于 3 行，跳过
+    if (lowValueRatio > 0.9 && stats.meaningfulChanges < 3) {
+      return {
+        worthReviewing: false,
+        reason: `低价值变更占比过高（${(lowValueRatio * 100).toFixed(1)}%），有意义变更仅 ${stats.meaningfulChanges} 行`
+      };
+    }
+
+    // 3. 如果有意义变更少于 2 行，且主要是辅助性代码，跳过
+    if (stats.meaningfulChanges < 2 &&
+        (stats.getterSetterChanges > 0 || stats.logChanges > 0 || stats.constantChanges > 0)) {
+      return {
+        worthReviewing: false,
+        reason: `有意义变更太少（${stats.meaningfulChanges} 行），且包含辅助性代码`
+      };
+    }
+
+    // 其他情况值得审查
+    return {
+      worthReviewing: true,
+      reason: `有 ${stats.meaningfulChanges} 行有意义代码变更，值得审查`
+    };
+  }
+
   /**
    * 获取合并请求的diff信息
    * @param {number} projectId GitLab项目ID
@@ -497,6 +836,25 @@ class GitLabCodeReviewer {
         const diffLines = diffObject.diff.split('\n');
         const codeLines = diffLines.filter(line => !line.startsWith('@@')).join('\n');
 
+        // ========== 阶段1：快速扫描（本地分析，不调用 AI）==========
+        const quickScanResult = this.quickScanDiffContent(diffObject.diff, diffObject.new_path || diffObject.old_path);
+        if (!quickScanResult.worthReviewing) {
+          infoLog(`[跳过审查] ${diffObject.new_path || diffObject.old_path}#${blockIndex}: ${quickScanResult.reason}`);
+          // 记录快速扫描跳过统计
+          this.metrics.recordQuickScanSkip(quickScanResult.reason);
+          return {
+            diff_info: diffObject,
+            block_index: blockIndex,
+            review_result: { reportContent: '<REPORT>\n## 🤖 AI 代码审查结果\n\n该变更无需审查。\n</REPORT>', lineInfo: '[]' },
+            temp_file_path: null,
+            hallucination_detected: false,
+            skipped_by_quick_scan: true,
+            skip_reason: quickScanResult.reason,
+          };
+        }
+        debugLog(`[快速扫描通过] ${diffObject.new_path || diffObject.old_path}#${blockIndex}: ${quickScanResult.reason}`);
+
+        // ========== 阶段2：完整审查（调用 AI）==========
         // 构造临时文件内容：纯代码在前，元数据在后
         const diffContentWithMetadata = `${codeLines}
 
@@ -664,10 +1022,15 @@ class GitLabCodeReviewer {
   collectAllReviewReports(results) {
     let allReportsText = '';
 
-    // 遍历所有审查结果，过滤掉检测到幻觉的结果
-    const validResults = results.filter(result => !result.hallucination_detected);
+    // 遍历所有审查结果，过滤掉检测到幻觉的结果和快速扫描跳过的结果
+    const validResults = results.filter(result =>
+      !result.hallucination_detected && !result.skipped_by_quick_scan
+    );
+
+    const skippedCount = results.filter(r => r.skipped_by_quick_scan).length;
+    const hallucinationCount = results.filter(r => r.hallucination_detected).length;
 
-    debugLog(`汇总报告过滤：总共 ${results.length} 个结果，过滤掉 ${results.length - validResults.length} 个幻觉检测结果，保留 ${validResults.length} 个有效结果`);
+    debugLog(`汇总报告过滤：总共 ${results.length} 个结果，快速扫描跳过 ${skippedCount} 个，幻觉检测跳过 ${hallucinationCount} 个，保留 ${validResults.length} 个有效结果`);
 
     for (let i = 0; i < validResults.length; i++) {
       const result = validResults[i];
@@ -895,7 +1258,7 @@ ${allReportsText}
   }
 
   /**
-   * 使用Claude对单个diff文件进行代码审核
+   * 使用Claude对单个diff文件进行代码审核（两阶段：Plan + Main）
    * @param {string} filePath 临时文件路径
    * @param {string} blockIdentifier 块标识（格式：文件路径#块索引），用于日志追踪
    * @param {boolean} isLargeFile 是否为大文件审查模式
@@ -905,6 +1268,42 @@ ${allReportsText}
     debugLog(`[${blockIdentifier}] 开始审核文件: ${filePath}, isLargeFile: ${isLargeFile}`);
     const startTime = Date.now();
 
+    // ========== 读取临时文件内容，计算改动行数 ==========
+    let diffContent = '';
+    try {
+      diffContent = fs.readFileSync(filePath, 'utf-8');
+    } catch (readError) {
+      debugLog(`[${blockIdentifier}] 无法读取临时文件：${readError.message}`);
+      diffContent = '';
+    }
+
+    // 计算改动行数（排除元数据部分）
+    const codeContent = diffContent.split('\n')
+      .filter(line => !line.startsWith('#'))  // 排除元数据行
+      .join('\n');
+    const changeLines = countChangeLines(codeContent);
+
+    debugLog(`[${blockIdentifier}] 改动行数统计：${changeLines} 行`);
+
+    // ========== Phase 1: Plan 阶段（风险分析）==========
+    // 触发条件：改动行数超过阈值，且不是大文件模式
+    let planGuidanceText = '';
+
+    if (changeLines >= PLAN_LINE_THRESHOLD && !isLargeFile) {
+      debugLog(`[${blockIdentifier}] 改动 ${changeLines} 行 >= ${PLAN_LINE_THRESHOLD}，启动 Plan 阶段`);
+
+      const planResult = await runPlanPhase(filePath, codeContent, blockIdentifier);
+      if (planResult) {
+        planGuidanceText = buildPlanGuidanceText(planResult);
+        debugLog(`[${blockIdentifier}] Plan 阶段生成审查指导，长度 ${planGuidanceText.length}`);
+      } else {
+        debugLog(`[${blockIdentifier}] Plan 阶段无有效结果，跳过`);
+      }
+    } else {
+      debugLog(`[${blockIdentifier}] 改动 ${changeLines} 行 < ${PLAN_LINE_THRESHOLD}（或大文件模式），跳过 Plan 阶段`);
+    }
+
+    // ========== Phase 2: Main 阶段（执行审查）==========
     // 大文件模式下的特殊提示
     const largeFilePrompt = isLargeFile ? `
 **⚠️ 大文件审查模式 - 强制格式要求**：
@@ -914,11 +1313,22 @@ ${allReportsText}
 3. 行号基于完整文件实际行号计算
 4. **严禁在输出中写 "Let me format" 等中间过程文本**
 5. **必须在 </REPORT> 后立即输出 <LINE_INFO> 标签，包含每个问题的行号**
+` : '';
+
+    // 根据是否有 Plan 指导，构建不同的 prompt
+    const planPromptSection = planGuidanceText ? `
+${planGuidanceText}
+
+**⚠️ 上述风险分析是基于代码结构预判的，请重点验证这些风险点是否真实存在**：
+- 如果风险点确实存在问题 → 按正常格式报告
+- 如果风险点经验证不存在 → 不报告该问题（不要为了"回应"而编造问题）
+- 如果发现其他未预判的问题 → 正常报告
 ` : '';
 
     const prompt = `请调用 simple-code-review 技能审核代码变更。
 文件路径：${filePath}
 ${largeFilePrompt}
+${planPromptSection}
 **⚠️ 强制输出格式要求（违反会导致审查结果丢失）**：
 
 必须以规定格式输出，不要输出任何分析过程、思考过程或中间文本：
@@ -927,8 +1337,9 @@ ${largeFilePrompt}
 - 有严重问题时，LINE_INFO 必须包含对应行号，否则结果被丢弃
 - 无问题时输出 <LINE_INFO>[]</LINE_INFO>
 - 不要输出 "Let me analyze"、"Let me format" 等文本`;
+
     //打印
-    debugLog(`[${blockIdentifier}] Claude命令: ${prompt}`);
+    debugLog(`[${blockIdentifier}] Main 阶段 Claude 命令 prompt 长度: ${prompt.length}`);
     // 最多重试5次，直到结果包含"🤖 AI 代码审查结果"或达到最大重试次数
     let attempts = 0;
     const maxAttempts = 5;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "job51-gitlab-cr-node-jt-1",
-  "version": "3.1.2",
+  "version": "3.1.4",
   "description": "GitLab merge request code review tool with AI-powered analysis and project context support",
   "main": "index.js",
   "bin": {

package/rules-loader.js

@@ -0,0 +1,332 @@
+/**
+ * 规则加载器 - 支持四层优先级链配置
+ *
+ * 优先级顺序（从高到低）：
+ * 1. CLI 覆盖 (--rule <path>)
+ * 2. 项目配置 (<repoDir>/.opencodereview/rule.json)
+ * 3. 用户配置 (~/.opencodereview/rule.json)
+ * 4. 内置规则 (system_rules.json + rule_docs/*.md)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { debugLog, warnLog } = require('./utils');
+
+// 使用 minimatch 进行 glob 匹配（内置支持，无需额外依赖）
+function minimatch(filePath, pattern, options = {}) {
+  // 简化的 glob 匹配实现
+  // 支持 ** 和 * 通配符
+  const nocase = options.nocase !== false;
+
+  // 转换 pattern 为正则表达式
+  let regexPattern = pattern;
+
+  // 先处理 **（匹配任意深度目录）
+  regexPattern = regexPattern.replace(/\*\*/g, '{{DOUBLESTAR}}');
+
+  // 处理 *（匹配单层任意字符，不包括路径分隔符）
+  regexPattern = regexPattern.replace(/\*/g, '[^/]*');
+
+  // 恢复 **
+  regexPattern = regexPattern.replace(/\{\{DOUBLESTAR\}\}/g, '.*');
+
+  // 处理 ?（匹配单个字符）
+  regexPattern = regexPattern.replace(/\?/g, '[^/]');
+
+  // 处理 {a,b,c} 扩展
+  const braceMatch = regexPattern.match(/\{([^}]+)\}/);
+  if (braceMatch) {
+    const optionsList = braceMatch[1].split(',');
+    // 返回多个 pattern 的匹配结果
+    const patterns = optionsList.map(opt =>
+      regexPattern.replace(/\{[^}]+\}/, opt)
+    );
+    return patterns.some(p => matchRegex(filePath, p, nocase));
+  }
+
+  return matchRegex(filePath, regexPattern, nocase);
+}
+
+function matchRegex(filePath, regexPattern, nocase) {
+  // 确保从头匹配
+  if (!regexPattern.startsWith('^')) {
+    regexPattern = '^' + regexPattern;
+  }
+  // 确保匹配到结尾
+  if (!regexPattern.endsWith('$')) {
+    regexPattern = regexPattern + '$';
+  }
+
+  const flags = nocase ? 'i' : '';
+  const regex = new RegExp(regexPattern, flags);
+
+  // 标准化路径
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  return regex.test(normalizedPath);
+}
+
+/**
+ * 扩展 brace pattern（如 {ts,tsx}）
+ * @param {string} pattern 包含 brace 的 pattern
+ * @returns {string[]} 扩展后的 pattern 数组
+ */
+function expandBraces(pattern) {
+  const braceMatch = pattern.match(/\{([^}]+)\}/);
+  if (!braceMatch) {
+    return [pattern];
+  }
+
+  const prefix = pattern.substring(0, braceMatch.index);
+  const suffix = pattern.substring(braceMatch.index + braceMatch[0].length);
+  const options = braceMatch[1].split(',');
+
+  return options.map(opt => prefix + opt + suffix);
+}
+
+class RulesLoader {
+  constructor(options = {}) {
+    // 规则目录（默认为 .claude/rules）
+    this.rulesDir = options.rulesDir || path.join(__dirname, '.claude', 'rules');
+
+    // CLI 覆盖路径
+    this.cliOverride = options.cliOverride || null;
+
+    // 加载各级配置
+    this.systemRules = this.loadSystemRules();
+    this.projectRules = this.loadProjectRules(options.projectDir || process.cwd());
+    this.userRules = this.loadUserRules();
+
+    debugLog(`RulesLoader 初始化完成: rulesDir=${this.rulesDir}`);
+  }
+
+  /**
+   * 加载内置系统规则配置
+   * @returns {Object} 系统规则配置
+   */
+  loadSystemRules() {
+    const configPath = path.join(this.rulesDir, 'system_rules.json');
+
+    if (fs.existsSync(configPath)) {
+      try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        return JSON.parse(content);
+      } catch (error) {
+        warnLog(`加载系统规则配置失败: ${error.message}`);
+      }
+    }
+
+    // 默认配置
+    return {
+      default_rule: 'code-review-rules.md',
+      path_rule_map: {}
+    };
+  }
+
+  /**
+   * 加载项目级规则配置
+   * @param {string} projectDir 项目目录
+   * @returns {Object|null} 项目规则配置
+   */
+  loadProjectRules(projectDir) {
+    // 支持多种配置文件位置
+    const configPaths = [
+      path.join(projectDir, '.opencodereview', 'rule.json'),
+      path.join(projectDir, '.code-review', 'rule.json'),
+      path.join(projectDir, '.cr-node', 'rule.json')
+    ];
+
+    for (const configPath of configPaths) {
+      if (fs.existsSync(configPath)) {
+        try {
+          const content = fs.readFileSync(configPath, 'utf-8');
+          debugLog(`加载项目规则配置: ${configPath}`);
+          return JSON.parse(content);
+        } catch (error) {
+          warnLog(`加载项目规则配置失败 (${configPath}): ${error.message}`);
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 加载用户级规则配置
+   * @returns {Object|null} 用户规则配置
+   */
+  loadUserRules() {
+    const userHome = process.env.HOME || process.env.USERPROFILE || '';
+    const configPaths = [
+      path.join(userHome, '.opencodereview', 'rule.json'),
+      path.join(userHome, '.code-review', 'rule.json')
+    ];
+
+    for (const configPath of configPaths) {
+      if (fs.existsSync(configPath)) {
+        try {
+          const content = fs.readFileSync(configPath, 'utf-8');
+          debugLog(`加载用户规则配置: ${configPath}`);
+          return JSON.parse(content);
+        } catch (error) {
+          warnLog(`加载用户规则配置失败 (${configPath}): ${error.message}`);
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 四层优先级链解析规则
+   * @param {string} filePath 待审查的文件路径
+   * @returns {{rule: string, source: string, pattern: string}} 规则详情
+   */
+  resolve(filePath) {
+    // 优先级1：CLI 覆盖
+    if (this.cliOverride) {
+      try {
+        const ruleContent = fs.readFileSync(this.cliOverride, 'utf-8');
+        debugLog(`使用 CLI 覆盖规则: ${this.cliOverride}`);
+        return {
+          rule: ruleContent,
+          source: 'cli',
+          pattern: 'override'
+        };
+      } catch (error) {
+        warnLog(`CLI 规则文件读取失败: ${error.message}`);
+      }
+    }
+
+    // 优先级2：项目配置
+    if (this.projectRules) {
+      const matched = this.matchRule(filePath, this.projectRules, 'project');
+      if (matched) return matched;
+    }
+
+    // 优先级3：用户配置
+    if (this.userRules) {
+      const matched = this.matchRule(filePath, this.userRules, 'user');
+      if (matched) return matched;
+    }
+
+    // 优先级4：内置规则（按语言匹配）
+    const systemMatched = this.matchRule(filePath, this.systemRules, 'system');
+    if (systemMatched) return systemMatched;
+
+    // 最终 fallback：默认规则
+    const defaultRulePath = path.join(this.rulesDir, this.systemRules.default_rule);
+    try {
+      const ruleContent = fs.readFileSync(defaultRulePath, 'utf-8');
+      debugLog(`使用默认规则: ${this.systemRules.default_rule}`);
+      return {
+        rule: ruleContent,
+        source: 'default',
+        pattern: 'default'
+      };
+    } catch (error) {
+      warnLog(`默认规则文件读取失败: ${error.message}`);
+      return {
+        rule: '',
+        source: 'none',
+        pattern: 'none'
+      };
+    }
+  }
+
+  /**
+   * 根据 glob pattern 匹配规则
+   * @param {string} filePath 文件路径
+   * @param {Object} rulesConfig 规则配置对象
+   * @param {string} source 来源标识
+   * @returns {{rule: string, source: string, pattern: string}|null}
+   */
+  matchRule(filePath, rulesConfig, source) {
+    const pathRuleMap = rulesConfig.path_rule_map || {};
+
+    // 按顺序匹配（第一个匹配生效）
+    for (const [pattern, ruleFile] of Object.entries(pathRuleMap)) {
+      // 扩展 brace pattern
+      const expandedPatterns = expandBraces(pattern);
+
+      for (const expandedPattern of expandedPatterns) {
+        if (minimatch(filePath, expandedPattern, { nocase: true })) {
+          // 查找规则文件
+          const rulePath = this.findRuleFile(ruleFile);
+          if (rulePath && fs.existsSync(rulePath)) {
+            try {
+              const ruleContent = fs.readFileSync(rulePath, 'utf-8');
+              debugLog(`匹配规则: pattern=${expandedPattern}, file=${ruleFile}, source=${source}`);
+              return {
+                rule: ruleContent,
+                source: source,
+                pattern: expandedPattern
+              };
+            } catch (error) {
+              warnLog(`规则文件读取失败 (${rulePath}): ${error.message}`);
+            }
+          }
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 查找规则文件路径（支持多个位置）
+   * @param {string} ruleFile 规则文件名
+   * @returns {string|null} 规则文件完整路径
+   */
+  findRuleFile(ruleFile) {
+    // 搜索位置优先级
+    const searchPaths = [
+      // 项目规则目录
+      path.join(process.cwd(), '.opencodereview', 'rules', ruleFile),
+      path.join(process.cwd(), '.code-review', 'rules', ruleFile),
+      // 用户规则目录
+      path.join(process.env.HOME || process.env.USERPROFILE || '', '.opencodereview', 'rules', ruleFile),
+      // 内置规则目录
+      path.join(this.rulesDir, ruleFile)
+    ];
+
+    for (const searchPath of searchPaths) {
+      if (fs.existsSync(searchPath)) {
+        return searchPath;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 设置 CLI 覆盖规则路径
+   * @param {string} rulePath 规则文件路径
+   */
+  setCliOverride(rulePath) {
+    this.cliOverride = rulePath;
+    debugLog(`设置 CLI 覆盖规则: ${rulePath}`);
+  }
+
+  /**
+   * 获取当前配置的摘要信息
+   * @returns {Object} 配置摘要
+   */
+  getConfigSummary() {
+    return {
+      cliOverride: this.cliOverride,
+      projectRules: this.projectRules ? 'loaded' : 'none',
+      userRules: this.userRules ? 'loaded' : 'none',
+      systemRules: {
+        default: this.systemRules.default_rule,
+        patterns: Object.keys(this.systemRules.path_rule_map || {}).length
+      },
+      rulesDir: this.rulesDir
+    };
+  }
+}
+
+module.exports = {
+  RulesLoader,
+  minimatch,
+  expandBraces
+};

package/utils.js

@@ -116,6 +116,10 @@ class MetricsCollector {
       totalProblemsFound: 0,
       seriousProblemsFound: 0,
 
+      // 快速扫描跳过统计
+      quickScanSkipped: 0,          // 快速扫描跳过的 diff 块数
+      quickScanSkipReasons: {},     // 跳过原因统计
+
       // 耗时统计（毫秒）
       reviewStartTime: 0,
       reviewEndTime: 0,
@@ -271,11 +275,31 @@ class MetricsCollector {
     this.metrics.commentsPublished++;
   }
 
+  // 记录快速扫描跳过
+  recordQuickScanSkip(reason = '') {
+    this.metrics.quickScanSkipped++;
+    if (reason) {
+      // 简化原因，只保留关键信息
+      const simplifiedReason = reason.split('（')[0] || reason;
+      if (!this.metrics.quickScanSkipReasons[simplifiedReason]) {
+        this.metrics.quickScanSkipReasons[simplifiedReason] = 0;
+      }
+      this.metrics.quickScanSkipReasons[simplifiedReason]++;
+    }
+  }
+
   // 打印统计摘要
   printSummary() {
     console.log('\n========== 审查统计 ==========');
     console.log(`审查文件数：${this.metrics.totalFilesReviewed}`);
     console.log(`审查 diff 块数：${this.metrics.totalBlocksReviewed}`);
+    console.log(`快速扫描跳过：${this.metrics.quickScanSkipped} 个 diff 块（节省 AI 调用）`);
+    if (Object.keys(this.metrics.quickScanSkipReasons).length > 0) {
+      console.log('  跳过原因统计：');
+      for (const [reason, count] of Object.entries(this.metrics.quickScanSkipReasons)) {
+        console.log(`    - ${reason}: ${count} 个`);
+      }
+    }
     console.log(`发现问题总数：${this.metrics.totalProblemsFound}`);
     console.log(`严重问题数：${this.metrics.seriousProblemsFound}`);
     console.log(`发布评论数：${this.metrics.commentsPublished}`);