@umsai/ums-code 0.5.0-v1 → 0.6.0-v1

package/dist/src/ui/commands/reviewCommand.js

@@ -65,10 +65,29 @@ class GitUtils {
                     return `${branch1}${separator}${branch2}`;
                 }
                 return `main${separator}${branch1}`;
+            case 'commits':
+                // commits 模式不使用此方法，每个文件单独构建命令
+                throw new ReviewCommandError('Commits mode should not use buildComparisonString');
             default:
                 throw new ReviewCommandError(`Unknown review mode: ${mode}`);
         }
     }
+    /**
+     * 构建单个文件的 git diff 命令（用于 commits 模式）
+     */
+    static buildFileDiffCommand(fileChange) {
+        if (fileChange.commit) {
+            // 单个 commit
+            return `git diff ${fileChange.commit}^ ${fileChange.commit} -- ${fileChange.filePath}`;
+        }
+        else if (fileChange.commit1 && fileChange.commit2) {
+            // 两个 commit
+            return `git diff ${fileChange.commit1}^ ${fileChange.commit2} -- ${fileChange.filePath}`;
+        }
+        else {
+            throw new ReviewCommandError('Invalid file change: missing commit information');
+        }
+    }
     /**
      * 构建 git diff --stat 命令
      */
@@ -123,6 +142,8 @@ class ReviewArgumentParser {
                 return { ...this.parseCommitMode(filteredParts), ...enhanceOptions, ...noticeOption };
             case '-branch':
                 return { ...this.parseBranchMode(filteredParts), ...enhanceOptions, ...noticeOption };
+            case '-commits':
+                return { ...this.parseCommitsMode(filteredParts), ...enhanceOptions, ...noticeOption };
             default:
                 return { ...this.handleUnknownCommand(filteredParts), ...enhanceOptions, ...noticeOption };
         }
@@ -138,12 +159,6 @@ class ReviewArgumentParser {
         }
         return {};
     }
-    /**
-     * 提取 --notice 参数
-     */
-    static extractNoticeOption(parts) {
-        return { notice: parts.includes('--notice') };
-    }
     /**
      * 移除所有选项参数（--prompt-enhance 和 --notice）
      */
@@ -162,6 +177,12 @@ class ReviewArgumentParser {
         }
         return filtered;
     }
+    /**
+     * 提取 --notice 参数
+     */
+    static extractNoticeOption(parts) {
+        return { notice: parts.includes('--notice') };
+    }
     /**
      * 解析 commit 模式参数
      */
@@ -188,6 +209,24 @@ class ReviewArgumentParser {
             branch2: parts[2],
         };
     }
+    /**
+     * 解析 commits 模式参数
+     */
+    static parseCommitsMode(parts) {
+        if (parts.length < 2) {
+            throw new ReviewCommandError('Commits mode requires commit hashes', 'MISSING_COMMITS');
+        }
+        // 解析逗号分隔的 commit 列表
+        const commitsString = parts[1];
+        const commits = commitsString.split(',').map(c => c.trim()).filter(c => c.length > 0);
+        if (commits.length < 2) {
+            throw new ReviewCommandError('Commits mode requires at least 2 commit hashes (comma-separated)', 'INSUFFICIENT_COMMITS');
+        }
+        return {
+            mode: 'commits',
+            commits,
+        };
+    }
     /**
      * 处理未知命令或可能的语法错误
      */
@@ -324,6 +363,161 @@ class GitStatsAnalyzer {
     }
 }
 // ============================================================================
+// 多 Commit 分析器
+// ============================================================================
+/**
+ * 多 Commit 文件变更分析器
+ */
+class MultiCommitAnalyzer {
+    /**
+     * 分析多个 commit 的文件变更
+     */
+    static async analyzeCommits(projectRoot, commits) {
+        const git = this.createGitInstance(projectRoot);
+        // 步骤1：收集所有commit的变更文件
+        const fileCommitMap = new Map();
+        for (const commit of commits) {
+            const files = await this.getChangedFiles(git, commit);
+            for (const file of files) {
+                if (!fileCommitMap.has(file)) {
+                    fileCommitMap.set(file, []);
+                }
+                fileCommitMap.get(file).push(commit);
+            }
+        }
+        // 步骤2：构建 changeList
+        const changeList = [];
+        fileCommitMap.forEach((commitList, filePath) => {
+            if (commitList.length === 1) {
+                // 只在一个 commit 中修改
+                changeList.push({
+                    filePath,
+                    commit: commitList[0],
+                });
+            }
+            else {
+                // 在多个 commit 中修改，保留第一个和最后一个
+                changeList.push({
+                    filePath,
+                    commit1: commitList[0],
+                    commit2: commitList[commitList.length - 1],
+                });
+            }
+        });
+        // 步骤3：统计每个文件的变更行数
+        let totalAddedLines = 0;
+        let totalDeletedLines = 0;
+        for (const fileChange of changeList) {
+            const { addedLines, deletedLines } = await this.getFileStats(git, fileChange);
+            fileChange.modifyLines = addedLines + deletedLines;
+            totalAddedLines += addedLines;
+            totalDeletedLines += deletedLines;
+        }
+        // 构建统计信息
+        const stats = {
+            fileCount: changeList.length,
+            addedLines: totalAddedLines,
+            deletedLines: totalDeletedLines,
+            totalChanges: totalAddedLines + totalDeletedLines,
+        };
+        return { changeList, stats };
+    }
+    /**
+     * 获取单个 commit 的变更文件列表
+     */
+    static async getChangedFiles(git, commit) {
+        try {
+            const output = await git.raw(['diff', '--name-only', `${commit}^`, commit]);
+            return output
+                .trim()
+                .split('\n')
+                .filter(line => line.length > 0);
+        }
+        catch (error) {
+            throw new ReviewCommandError(`Failed to get changed files for commit ${commit}: ${error instanceof Error ? error.message : String(error)}`, 'GIT_DIFF_ERROR');
+        }
+    }
+    /**
+     * 获取单个文件的变更统计
+     */
+    static async getFileStats(git, fileChange) {
+        try {
+            let output;
+            if (fileChange.commit) {
+                // 单个 commit
+                output = await git.raw([
+                    'diff',
+                    '--stat',
+                    `${fileChange.commit}^`,
+                    fileChange.commit,
+                    '--',
+                    fileChange.filePath,
+                ]);
+            }
+            else if (fileChange.commit1 && fileChange.commit2) {
+                // 两个 commit
+                output = await git.raw([
+                    'diff',
+                    '--stat',
+                    `${fileChange.commit1}^`,
+                    fileChange.commit2,
+                    '--',
+                    fileChange.filePath,
+                ]);
+            }
+            else {
+                return { addedLines: 0, deletedLines: 0 };
+            }
+            // 解析统计输出
+            return this.parseFileStatOutput(output);
+        }
+        catch (_error) {
+            // 如果获取失败，返回0
+            return { addedLines: 0, deletedLines: 0 };
+        }
+    }
+    /**
+     * 解析文件的统计输出
+     */
+    static parseFileStatOutput(output) {
+        const lines = output.trim().split('\n');
+        if (lines.length === 0) {
+            return { addedLines: 0, deletedLines: 0 };
+        }
+        // 查找包含统计信息的行
+        for (const line of lines) {
+            const match = line.match(/\|\s*(\d+)\s*([+-]+)?/);
+            if (match) {
+                const totalChanges = parseInt(match[1], 10);
+                const signs = match[2] || '';
+                const additions = (signs.match(/\+/g) || []).length;
+                const deletions = (signs.match(/-/g) || []).length;
+                if (additions === 0 && deletions === 0) {
+                    return {
+                        addedLines: Math.floor(totalChanges / 2),
+                        deletedLines: Math.ceil(totalChanges / 2),
+                    };
+                }
+                const total = additions + deletions;
+                return {
+                    addedLines: Math.round((additions / total) * totalChanges),
+                    deletedLines: Math.round((deletions / total) * totalChanges),
+                };
+            }
+        }
+        return { addedLines: 0, deletedLines: 0 };
+    }
+    /**
+     * 创建 Git 实例
+     */
+    static createGitInstance(projectRoot) {
+        return simpleGit(projectRoot, {
+            binary: 'git',
+            maxConcurrentProcesses: 1,
+        });
+    }
+}
+// ============================================================================
 // Prompt 构建器
 // ============================================================================
 /**
@@ -357,6 +551,33 @@ class ReviewPromptBuilder {
             this.buildLargeChangeCallToAction()
         ]);
     }
+    /**
+     * 构建 commits 模式小型变更的评审 prompt
+     */
+    static buildCommitsSmallChangePrompt(stats, projectRoot, changeList, options) {
+        return this.buildPromptTemplate([
+            this.buildCommitsHeader(stats, changeList),
+            this.buildExecutionFlow(options),
+            this.buildCommitsFileFilteringPhase(projectRoot, changeList),
+            this.buildCommitsCodeReviewPhase(projectRoot, changeList, options),
+            this.buildReportGenerationPhase(stats),
+            this.buildQualityCheckPhase(projectRoot, options),
+            this.buildCallToAction()
+        ]);
+    }
+    /**
+     * 构建 commits 模式大型变更的评审 prompt
+     */
+    static buildCommitsLargeChangePrompt(stats, projectRoot, changeList, options) {
+        return this.buildPromptTemplate([
+            this.buildCommitsLargeChangeHeader(stats, changeList),
+            this.buildLargeChangeExecutionFlow(options),
+            this.buildCommitsAnalysisPhase(projectRoot, changeList),
+            this.buildCommitsBatchReviewPhase(projectRoot, changeList, options),
+            this.buildSummaryPhase(stats, projectRoot, options),
+            this.buildLargeChangeCallToAction()
+        ]);
+    }
     /**
      * 构建 prompt 模板
      */
@@ -599,42 +820,31 @@ ${this.buildEnhancedRulesSection(projectRoot, options)}
 
 ## 结果检查
 
-返回结果前必须自检，剔除误报的问题，修正不准确的问题：
-
-**检查 1：文件覆盖完整性**
-- [ ] 已评审所有指定文件
-- [ ] 无法评审的文件已说明原因
+在返回结果前，要确保：
 
-**检查 2：输出格式完整性**
-- [ ] 每个问题都有 [严重性][维度] 标签
-- [ ] CRITICAL/HIGH 有：问题描述、详细分析、当前代码、建议修复
-- [ ] MEDIUM/LOW 有：问题描述、简要说明
+1. 已评审所有指定文件
 
-**检查 3：分类准确性**
-- [ ] 严重性符合 SEVERITY_GUIDELINES
-- [ ] 维度符合 REVIEW_DIMENSIONS
+如果有遗漏、未评审的文件， 请补充评审
 
-**检查 4：严重性合理性**
-对每个 CRITICAL/HIGH 问题：
-- [ ] 有明确代码证据证明是 bug？
-- [ ] "会出错"还是"可能出错"？
-- [ ] 代码是否已有防御/错误处理？
-- [ ] bug 修复还是改进建议？
-- [ ] 能写测试用例重现？
+2. 每个问题都在 diff 中明确存在
+3. 没有基于"理论上可能"的问题
+4. 没有报告已被处理/修复的问题
+5. 问题是真实存在，不是幻觉、"挑毛病"
 
-**不确定或"否"→ 必须降低严重性！**
+如果有误报的问题，请剔除
 
-**检查 5：Diff 覆盖验证(重要)**
-对每个报告的问题：
-- [ ] 问题所在代码行确实是在 diff 中
-- [ ] 问题确实是本次变更引入的，而非之前就存在
+6. 每个问题都有 [严重性][维度] 标签
+7. CRITICAL/HIGH 有：问题描述、详细分析、当前代码、建议修复
+8. MEDIUM/LOW 有：问题描述、简要说明
+9. 问题严重性符合 SEVERITY_GUIDELINES
+10. 问题维度符合 REVIEW_DIMENSIONS
 
-**如果是未变更的代码，必须删除该问题！**
+如果有描述不当或者信息缺失的报告问题，请调整修正
 
-**检查 6：误报风险(重要)**
-- [ ] 问题是真实存在，而非基于假设
-
-**如果是误报的问题，必须剔除！**`;
+**质量标准**：
+- ✅ 宁可 5 个准确问题，不要 10 个含 3 个误报
+- ✅ 准确性 > 完整性
+- ✅ 不确定时：不报告或降低严重性`;
     }
     /**
      * 构建报告生成阶段
@@ -836,7 +1046,7 @@ ${gitDiffStatCommand}
 
 ---
 
-#### 步骤 2：智能过滤文件
+#### 步骤 2：智能过滤文件（重要！）
 
 **目标**：从变更文件中识别出真正需要代码评审的文件。
 
@@ -857,7 +1067,6 @@ ${this.buildFileFilteringOutputFormat()}
 
 - 如果需要评审的文件 ≤ ${REVIEW_THRESHOLDS.LARGE_FILE_THRESHOLD} 个 且 变更量 ≤ ${REVIEW_THRESHOLDS.LARGE_CHANGE_THRESHOLD} 行
   → 记录"无需分批，可以一次性评审"，跳转到阶段二（单批次评审）
-- 如果需要评审的文件≤ ${REVIEW_THRESHOLDS.LARGE_FILE_THRESHOLD} 个 且 变更量 ≤ ${REVIEW_THRESHOLDS.LARGE_CHANGE_THRESHOLD} 行， 但是存在较大的单文件变更(比如超过500行)，可视情况分批次
 
 - 否则 → 继续步骤 4 制定分批策略
 
@@ -872,7 +1081,6 @@ ${this.buildFileFilteringOutputFormat()}
 - 每批不超过 ${REVIEW_THRESHOLDS.MAX_FILES_PER_BATCH} 个文件
 - 每批不超过 ${REVIEW_THRESHOLDS.MAX_CHANGES_PER_BATCH} 行变更
 - 相关文件放在同一批（如 Service 和其对应的 Test）
-- 在每批次文件数和变更函数不超过限制的前提下，尽量减少批次
 
 **输出格式**：
 
@@ -971,46 +1179,35 @@ git diff ${GitUtils.buildComparisonString(options, 'command')} -- file1.ts file2
 
 ${this.buildEnhancedRulesSection(projectRoot, options)}
 
-## 结果检查
+## 结果检查（非常重要）
 
 在返回结果开头请注明：**批次 1/N - [批次描述]**
 
-返回结果前必须自检，剔除误报的问题，修正不准确的问题：
-
-**检查 1：文件覆盖完整性**
-- [ ] 已评审所有指定文件
-- [ ] 无法评审的文件已说明原因
+在返回结果前，要确保：
 
-**检查 2：输出格式完整性**
-- [ ] 每个问题都有 [严重性][维度] 标签
-- [ ] CRITICAL/HIGH 有：问题描述、详细分析、当前代码、建议修复
-- [ ] MEDIUM/LOW 有：问题描述、简要说明
+1. 已评审所有指定文件
 
-**检查 3：分类准确性**
-- [ ] 严重性符合 SEVERITY_GUIDELINES
-- [ ] 维度符合 REVIEW_DIMENSIONS
+如果有遗漏、未评审的文件， 请补充评审
 
-**检查 4：严重性合理性**
-对每个 CRITICAL/HIGH 问题：
-- [ ] 有明确代码证据证明是 bug？
-- [ ] "会出错"还是"可能出错"？
-- [ ] 代码是否已有防御/错误处理？
-- [ ] bug 修复还是改进建议？
-- [ ] 能写测试用例重现？
+2. 每个问题都在 diff 中明确存在
+3. 没有基于"理论上可能"的问题
+4. 没有报告已被处理/修复的问题
+5. 问题是真实存在，不是幻觉、"挑毛病"
 
-**不确定或"否"→ 必须降低严重性！**
+如果有误报的问题，请剔除
 
-**检查 5：Diff 覆盖验证(重要)**
-对每个报告的问题：
-- [ ] 问题所在代码行确实是在 diff 中
-- [ ] 问题确实是本次变更引入的，而非之前就存在
+6. 每个问题都有 [严重性][维度] 标签
+7. CRITICAL/HIGH 有：问题描述、详细分析、当前代码、建议修复
+8. MEDIUM/LOW 有：问题描述、简要说明
+9. 问题严重性符合 SEVERITY_GUIDELINES
+10. 问题维度符合 REVIEW_DIMENSIONS
 
-**如果是未变更的代码，必须删除该问题！**
+如果有描述不当或者信息缺失的报告问题，请调整修正
 
-**检查 6：误报风险(重要)**
-- [ ] 问题是真实存在，而非基于假设
-
-**如果是误报的问题，必须剔除！**\`
+**质量标准**：
+- ✅ 宁可 5 个准确问题，不要 10 个含 3 个误报
+- ✅ 准确性 > 完整性
+- ✅ 不确定时：不报告或降低严重性\`
 }
 \`\`\`
 
@@ -1051,21 +1248,7 @@ ${this.buildEnhancedRulesSection(projectRoot, options)}
 
 ---
 
-#### 步骤 2：复核评审问题
-
-**要求**：逐一复核评审问题，核对检查项
-**目标**：移除误报的问题，降低误报率
-
-**检查 1：Diff 覆盖验证**
-对每个报告的问题：
-- 问题所在代码行确实是在 diff 中
-- 问题确实是本次变更引入的，而非之前就存在
-
-**检查 2：误报风险**
-对每个报告的问题：
-- [ ] 问题是真实存在，而非基于假设
-
-#### 步骤 3：按维度和严重性重新组织
+#### 步骤 2：按维度和严重性重新组织
 
 将收集到的所有问题按照以下结构重新组织：
 
@@ -1102,7 +1285,7 @@ LOW 问题列表
 
 ---
 
-#### 步骤 4：生成最终报告
+#### 步骤 3：生成最终报告
 
 按照以下格式生成 \`CODE_REVIEW.md\`：
 
@@ -1112,7 +1295,31 @@ ${this.buildReportTemplate(stats)}
 
 ---
 
-**所有步骤完成后**：
+#### 步骤 4：汇总完整性检查（必须执行！）
+
+**目的**：确保汇总过程没有遗漏 subagent 的评审结果
+
+**检查项**：
+
+1. **数量完整性**
+   - 回顾所有批次的 subagent 返回结果
+   - 统计各批次报告的问题总数：批次1(X个) + 批次2(Y个) + ... = 总计N个
+   - 统计最终报告中的问题总数：M个
+   - 验证：N = M
+   - ❌ 如果不相等，返回步骤1重新逐条收集
+
+2. **结构正确性**
+   - [ ] 按"严重性 > 维度"组织
+   - [ ] 评审摘要表格数据与实际问题数量一致
+   - [ ] 没有批次信息残留（"批次1"、"第一批"等）
+   - ❌ 如果有误，重新组织结构或重新计算
+
+3. **内容完整性**（抽查）
+   - 随机抽查2-3个问题，确认汇总时没有删减内容
+   - 对比原始 subagent 结果与最终报告中的对应问题
+   - ❌ 如果发现删减，从原始结果中恢复完整内容
+
+**所有检查项通过后**：
 1. 将最终报告写入 \`CODE_REVIEW.md\`
 2. 标记任务为 **completed**
 3. 输出简要总结：
@@ -1167,11 +1374,402 @@ ${this.buildReportTemplate(stats)}
 
 **第四步**：基于过滤后的文件制定分批策略（如需要）
 
-**重要**：此阶段只做分析、过滤和规划，不开始评审代码！
-**重要**：此阶段后请继续执行阶段二和阶段三，不要中断，不要询问是否继续！
+**重要**：此阶段只做分析、过滤和规划，不开始评审代码
+**重要**：此阶段后请继续执行阶段二和阶段三，不要中断，不要询问是否继续
 
 请开始执行！`;
     }
+    // ============================================================================
+    // Commits 模式专用方法
+    // ============================================================================
+    /**
+     * 构建 commits 模式变更摘要头部
+     */
+    static buildCommitsHeader(stats, changeList) {
+        const commitsCount = this.getUniqueCommitsCount(changeList);
+        return `# 代码评审任务 - Commits 模式
+
+## 变更摘要
+
+- **Commits 数量**: ${commitsCount} 个
+- **文件总数**: ${stats.fileCount} 个
+- **新增行数**: ${stats.addedLines} 行
+- **删除行数**: ${stats.deletedLines} 行
+- **总变更量**: ${stats.totalChanges} 行
+
+变更规模适中，将使用 code-reviewer 一次性完成评审。`;
+    }
+    /**
+     * 构建 commits 模式大型变更头部
+     */
+    static buildCommitsLargeChangeHeader(stats, changeList) {
+        const commitsCount = this.getUniqueCommitsCount(changeList);
+        return `# 代码评审任务 - Commits 模式（大型变更）
+
+## 变更摘要
+
+- **Commits 数量**: ${commitsCount} 个
+- **文件总数**: ${stats.fileCount} 个
+- **新增行数**: ${stats.addedLines} 行
+- **删除行数**: ${stats.deletedLines} 行
+- **总变更量**: ${stats.totalChanges} 行
+
+由于这是一个**大型变更**（超过 ${REVIEW_THRESHOLDS.LARGE_FILE_THRESHOLD} 个文件或 ${REVIEW_THRESHOLDS.LARGE_CHANGE_THRESHOLD} 行代码），需要分批次进行评审。`;
+    }
+    /**
+     * 构建 commits 模式文件过滤阶段
+     */
+    static buildCommitsFileFilteringPhase(projectRoot, changeList) {
+        const changeListJson = JSON.stringify({ changeList }, null, 2);
+        return `## 第一阶段：AI 智能文件过滤
+
+### 步骤 1：查看变更文件列表并进行智能过滤
+
+以下是多个 commit 合并后的变更文件列表（changeList）：
+
+\`\`\`json
+${changeListJson}
+\`\`\`
+
+**说明**：
+- 如果文件只在一个 commit 中修改，则只有 \`commit\` 字段
+- 如果文件在多个 commit 中修改，则有 \`commit1\` 和 \`commit2\` 字段（分别表示第一个和最后一个修改它的 commit）
+- \`modifyLines\` 表示该文件的总变更行数
+
+**然后对变更文件进行 AI 智能过滤分析**：
+
+${this.buildFileFilteringRules()}
+
+${this.buildFileFilteringOutputFormat()}
+
+### 步骤 2：检查过滤结果
+
+**重要**：如果所有文件都被过滤掉（需要评审的文件为 0），则：
+1. 输出消息："✅ 本次变更无需代码评审（全部为文档、配置或自动生成文件）"
+2. 创建简单的 CODE_REVIEW.md 文件说明情况
+3. 结束评审流程
+
+如果还有需要评审的文件，继续下一步。`;
+    }
+    /**
+     * 构建 commits 模式代码评审阶段
+     */
+    static buildCommitsCodeReviewPhase(projectRoot, changeList, options) {
+        return `## 第二阶段：执行代码评审
+
+### 步骤 3：AI 智能代码评审
+
+使用 **Task tool** 调用 code-reviewer subagent，**仅对需要评审的文件进行评审**：
+
+\`\`\`typescript
+{
+  subagent_type: 'code-reviewer',
+  description: '代码评审 - Commits 模式',
+  prompt: \`${this.buildCommitsSubagentPrompt(projectRoot, changeList, options)}\`
+}
+\`\`\`
+
+### 步骤 4：等待评审完成
+
+subagent 会自动：
+1. 根据 changeList 为每个文件执行相应的 git diff 命令
+2. 使用 Read tool 读取相关文件（重点关注需要评审的文件）
+3. 按照六个维度进行深度代码评审
+4. 进行自我检查确保评审质量`;
+    }
+    /**
+     * 构建 commits 模式分析阶段
+     */
+    static buildCommitsAnalysisPhase(projectRoot, changeList) {
+        const changeListJson = JSON.stringify({ changeList }, null, 2);
+        return `#### 步骤 1：查看 changeList
+
+以下是多个 commit 合并后的变更文件列表（changeList）：
+
+\`\`\`json
+${changeListJson}
+\`\`\`
+
+**说明**：
+- 如果文件只在一个 commit 中修改，则只有 \`commit\` 字段
+- 如果文件在多个 commit 中修改，则有 \`commit1\` 和 \`commit2\` 字段（分别表示第一个和最后一个修改它的 commit）
+- \`modifyLines\` 表示该文件的总变更行数
+
+**重要提示：不要获取完整 diff！**
+- 只需要分析 changeList 中的文件列表和变更行数
+- 这将列出所有变更的文件及其变更行数
+
+---
+
+#### 步骤 2：智能过滤文件
+
+**目标**：从变更文件中识别出真正需要代码评审的文件。
+
+${this.buildFileFilteringRules()}
+
+${this.buildFileFilteringOutputFormat()}
+
+**重要**：
+- 必须列出所有变更文件，要么在"需要评审"列表，要么在"已过滤"列表
+- 每个被过滤的文件都要简要说明原因
+- 统计数据要准确
+
+---
+
+#### 步骤 3：判断评审规模
+
+基于**过滤后的文件**（即"需要评审的文件"列表），判断是否需要分批：
+
+- 如果需要评审的文件 ≤ ${REVIEW_THRESHOLDS.LARGE_FILE_THRESHOLD} 个 且 变更量 ≤ ${REVIEW_THRESHOLDS.LARGE_CHANGE_THRESHOLD} 行
+  → 记录"无需分批，可以一次性评审"，跳转到阶段二（单批次评审）
+
+- 否则 → 继续步骤 4 制定分批策略
+
+---
+
+#### 步骤 4：制定分批策略（如需分批）
+
+基于"需要评审的文件"列表，制定分批方案：
+
+**分批原则**：
+- 按功能模块、文件类型、业务关联性分组
+- 每批不超过 ${REVIEW_THRESHOLDS.MAX_FILES_PER_BATCH} 个文件
+- 每批不超过 ${REVIEW_THRESHOLDS.MAX_CHANGES_PER_BATCH} 行变更
+- 相关文件放在同一批（如 Service 和其对应的 Test）
+
+**输出格式**：
+
+\`\`\`markdown
+## 分批方案
+
+### 批次 1：[批次描述，如 "用户认证模块"]
+- 文件数：8 个
+- 预计变更行数：650 行
+- 文件列表：
+  - src/services/UserService.java
+  - src/services/AuthService.java
+  - src/utils/jwt.ts
+...
+
+### 批次 2：[批次描述]
+...
+
+### 批次 N：[批次描述]
+...
+\`\`\`
+
+---
+
+#### 步骤 5：确认完整性
+
+检查分批方案（如果分批）或单批次方案：
+- "需要评审的文件"列表中的每个文件都已分配到某个批次
+- 没有文件被遗漏
+- 没有文件被重复分配
+
+如果检查通过，更新 TodoWrite，标记步骤1-5为完成，添加后续评审任务，继续阶段二。
+
+**重要**：此阶段只做分析和规划，不开始评审代码。`;
+    }
+    /**
+     * 构建 commits 模式分批评审阶段
+     */
+    static buildCommitsBatchReviewPhase(projectRoot, changeList, options) {
+        return `### 阶段二：批次评审（完成分批后执行）
+
+分批方案确定后，更新 **TodoWrite** 任务列表：
+
+\`\`\`
+1. [completed] 分析变更文件
+2. [completed] AI 智能文件过滤
+3. [completed] AI 智能制定分批次评审策略
+4. [completed] 复核分批次评审策略
+5. 评审批次 1/N
+6. 评审批次 2/N
+...
+N+6. 汇总所有批次评审结果
+N+7. 生成最终评审报告
+\`\`\`
+
+对于每个批次：
+
+1. 标记任务为 **in_progress**
+2. 使用 **Task tool** 调用 **code-reviewer** subagent
+3. **验证返回结果**：
+   - 如果返回"未发现需要关注的问题"，记录该批次无问题
+   - 如果返回了问题列表，快速检查格式是否正确
+4. 标记为 **completed**，继续下一批次
+
+**Task tool 调用示例**：
+
+\`\`\`typescript
+{
+  subagent_type: 'code-reviewer',
+  description: '代码评审 - 批次 1/N: [批次描述]',
+  prompt: \`请按照你的标准评审流程进行全面代码评审（批次 1/N - Commits 模式）。
+
+## 批次信息
+
+- 批次描述：[描述，如 "用户认证模块"]
+- 文件数：X 个
+- 预计变更行数：Y 行
+
+## 需要评审的文件 changeList
+
+提供该批次文件的 changeList JSON：
+
+\\\`\\\`\\\`json
+{
+  "changeList": [
+    { "filePath": "file1.ts", "commit": "abc123", "modifyLines": 50 },
+    { "filePath": "file2.ts", "commit1": "abc123", "commit2": "def456", "modifyLines": 120 },
+    ...
+  ]
+}
+\\\`\\\`\\\`
+
+## 获取变更内容
+
+对于 changeList 中的每个文件，根据 commit 字段执行相应的 git diff 命令：
+
+- 如果文件只有 \\\`commit\\\` 字段，执行：
+  \\\`\\\`\\\`bash
+  git diff <commit>^ <commit> -- <filePath>
+  \\\`\\\`\\\`
+
+- 如果文件有 \\\`commit1\\\` 和 \\\`commit2\\\` 字段，执行：
+  \\\`\\\`\\\`bash
+  git diff <commit1>^ <commit2> -- <filePath>
+  \\\`\\\`\\\`
+
+${this.buildEnhancedRulesSection(projectRoot, options)}
+
+在返回结果开头请注明：**批次 1/N - [批次描述] (Commits 模式)**
+
+## 结果检查（非常重要）
+
+在返回结果前，要确保：
+
+1. 已评审所有指定文件
+
+如果有遗漏、未评审的文件， 请补充评审
+
+2. 每个问题都在 diff 中明确存在
+3. 没有基于"理论上可能"的问题
+4. 没有报告已被处理/修复的问题
+5. 问题是真实存在，不是幻觉、"挑毛病"
+
+如果有误报的问题，请剔除
+
+6. 每个问题都有 [严重性][维度] 标签
+7. CRITICAL/HIGH 有：问题描述、详细分析、当前代码、建议修复
+8. MEDIUM/LOW 有：问题描述、简要说明
+9. 问题严重性符合 SEVERITY_GUIDELINES
+10. 问题维度符合 REVIEW_DIMENSIONS
+
+如果有描述不当或者信息缺失的报告问题，请调整修正
+
+**质量标准**：
+- 宁可 5 个准确问题，不要 10 个含 3 个误报
+- 准确性 > 完整性
+- 不确定时：不报告\`
+}
+\`\`\`
+
+**关键点**：
+- 不要在主 task 中获取完整 diff，只提供 changeList 和 git diff 命令说明
+- code-reviewer subagent 会自己根据 changeList 执行相应的 git diff 命令
+- code-reviewer subagent 会自己读取所有相关文件
+- code-reviewer subagent 会自己进行深度代码评审并自检
+- code-reviewer subagent 会返回评审结果`;
+    }
+    /**
+     * 构建 commits 模式 subagent prompt
+     */
+    static buildCommitsSubagentPrompt(projectRoot, changeList, options) {
+        const changeListJson = JSON.stringify({ changeList }, null, 2);
+        return `请按照你的标准评审流程进行全面代码评审（Commits 模式）。
+
+## 变更信息
+
+- 需要评审的文件：X 个
+- 变更行数：约 Y 行
+
+## 需要评审的文件 changeList
+
+\\\`\\\`\\\`json
+${changeListJson}
+\\\`\\\`\\\`
+
+**说明**：
+- 如果文件只有 \\\`commit\\\` 字段，表示只在一个 commit 中修改
+- 如果文件有 \\\`commit1\\\` 和 \\\`commit2\\\` 字段，表示在多个 commit 中修改（第一个和最后一个）
+- \\\`modifyLines\\\` 表示该文件的总变更行数
+
+## 获取变更内容
+
+对于 changeList 中的每个文件，根据 commit 字段执行相应的 git diff 命令：
+
+- 如果文件只有 \\\`commit\\\` 字段，执行：
+  \\\`\\\`\\\`bash
+  git diff <commit>^ <commit> -- <filePath>
+  \\\`\\\`\\\`
+
+- 如果文件有 \\\`commit1\\\` 和 \\\`commit2\\\` 字段，执行：
+  \\\`\\\`\\\`bash
+  git diff <commit1>^ <commit2> -- <filePath>
+  \\\`\\\`\\\`
+
+（将 <commit>、<commit1>、<commit2>、<filePath> 替换为 changeList 中的实际值）
+
+${this.buildEnhancedRulesSection(projectRoot, options)}
+
+## 结果检查(非常重要)
+
+在返回结果前，要确保：
+
+1. 已评审所有指定文件
+
+如果有遗漏、未评审的文件， 请补充评审
+
+2. 每个问题都在 diff 中明确存在
+3. 没有基于"理论上可能"的问题
+4. 没有报告已被处理/修复的问题
+5. 问题是真实存在，不是幻觉、"挑毛病"
+
+如果有误报的问题，请剔除
+
+6. 每个问题都有 [严重性][维度] 标签
+7. CRITICAL/HIGH 有：问题描述、详细分析、当前代码、建议修复
+8. MEDIUM/LOW 有：问题描述、简要说明
+9. 问题严重性符合 SEVERITY_GUIDELINES
+10. 问题维度符合 REVIEW_DIMENSIONS
+
+如果有描述不当或者信息缺失的报告问题，请调整修正
+
+**质量标准**：
+- 宁可 5 个准确问题，不要 10 个含 3 个误报
+- 准确性 > 完整性
+- 不确定时：不报告或降低严重性`;
+    }
+    /**
+     * 获取 changeList 中的唯一 commit 数量
+     */
+    static getUniqueCommitsCount(changeList) {
+        const commits = new Set();
+        for (const file of changeList) {
+            if (file.commit) {
+                commits.add(file.commit);
+            }
+            if (file.commit1) {
+                commits.add(file.commit1);
+            }
+            if (file.commit2) {
+                commits.add(file.commit2);
+            }
+        }
+        return commits.size;
+    }
 }
 // ============================================================================
 // 评审策略选择器
@@ -1183,7 +1781,12 @@ class ReviewStrategySelector {
     /**
      * 根据统计信息选择评审策略
      */
-    static selectStrategy(stats, projectRoot, options) {
+    static selectStrategy(stats, projectRoot, options, changeList) {
+        // commits 模式单独处理
+        if (options.mode === 'commits' && changeList) {
+            return this.selectCommitsStrategy(stats, projectRoot, changeList, options);
+        }
+        // 其他模式
         const isLargeChange = this.isLargeChange(stats);
         if (isLargeChange) {
             const gitDiffStatCommand = GitUtils.buildDiffStatCommand(options);
@@ -1194,6 +1797,18 @@ class ReviewStrategySelector {
             return ReviewPromptBuilder.buildSmallChangePrompt(stats, projectRoot, gitDiffCommand, options);
         }
     }
+    /**
+     * 选择 commits 模式的评审策略
+     */
+    static selectCommitsStrategy(stats, projectRoot, changeList, options) {
+        const isLargeChange = this.isLargeChange(stats);
+        if (isLargeChange) {
+            return ReviewPromptBuilder.buildCommitsLargeChangePrompt(stats, projectRoot, changeList, options);
+        }
+        else {
+            return ReviewPromptBuilder.buildCommitsSmallChangePrompt(stats, projectRoot, changeList, options);
+        }
+    }
     /**
      * 判断是否为大型变更
      */
@@ -1203,13 +1818,165 @@ class ReviewStrategySelector {
     }
 }
 // ============================================================================
+// 帮助信息构建器
+// ============================================================================
+/**
+ * 构建 review 命令的帮助信息
+ */
+function buildHelpMessage() {
+    return `# /review - 智能代码评审命令
+
+## 📖 功能说明
+
+执行 AI 驱动的代码评审，支持多种评审模式，自动识别变更规模并智能分批处理。
+
+## 🚀 使用方法
+
+### 基本用法
+
+\`\`\`bash
+/review                    # 评审未提交的变更（默认模式）
+/review --help            # 显示帮助信息
+/review -h                # 显示帮助信息（简写）
+\`\`\`
+
+### Commit 模式
+
+\`\`\`bash
+/review -commit <commit1>              # 评审单个 commit 的变更
+/review -commit <commit1> <commit2>    # 评审两个 commit 之间的差异
+\`\`\`
+
+**示例：**
+\`\`\`bash
+/review -commit abc1234                # 评审 commit abc1234 的变更
+/review -commit abc1234 def5678        # 评审 abc1234 到 def5678 之间的变更
+\`\`\`
+
+### Branch 模式
+
+\`\`\`bash
+/review -branch <branch1>              # 评审分支与 main 的差异
+/review -branch <branch1> <branch2>    # 评审两个分支之间的差异
+\`\`\`
+
+**示例：**
+\`\`\`bash
+/review -branch feature-login          # 评审 feature-login 分支与 main 的差异
+/review -branch dev staging            # 评审 dev 和 staging 分支之间的差异
+\`\`\`
+
+## ⚙️ 可选参数
+
+### --prompt-enhance <文件路径>
+
+指定额外的评审规则文件，补充默认的评审标准。
+
+**示例：**
+\`\`\`bash
+/review --prompt-enhance ./custom-rules.md
+/review -commit abc1234 --prompt-enhance ./team-standards.md
+\`\`\`
+
+### --notice
+
+为 CI/CD 流水线集成生成完成标志文件（\`.review-completed\`）。
+
+**示例：**
+\`\`\`bash
+/review --notice
+/review -commit abc1234 --notice
+\`\`\`
+
+**标志文件格式：**
+\`\`\`json
+{
+  "status": "completed",
+  "timestamp": "2025-01-15T10:30:00Z",
+  "report": "CODE_REVIEW.md"
+}
+\`\`\`
+
+## 📊 评审特性
+
+### 智能分批处理
+- **小型变更**（≤50 文件或 ≤3000 行）：一次性评审
+- **大型变更**（>50 文件或 >3000 行）：自动分批评审
+
+### 智能文件过滤
+自动过滤不需要评审的文件：
+- 文档文件（README.md, CHANGELOG.md）
+- 依赖锁文件（package-lock.json, yarn.lock）
+- 二进制文件和媒体文件
+- 自动生成的代码
+- IDE 配置文件
+
+### 六维度评审
+- 🐛 **正确性**：逻辑错误、边界条件、异常处理
+- 🔒 **安全性**：注入漏洞、权限控制、数据验证
+- ⚡ **性能**：算法效率、资源使用、查询优化
+- 🔧 **可维护性**：代码复杂度、命名规范、文档完整性
+- 🏗️ **架构设计**：设计模式、模块解耦、接口设计
+- ✨ **最佳实践**：代码风格、惯用法、工程规范
+
+### 四级严重性
+- 🚨 **CRITICAL**：必须立即修复的致命问题
+- ⚠️ **HIGH**：重要问题，应尽快修复
+- 🔶 **MEDIUM**：中等问题，建议修复
+- 🔷 **LOW**：轻微问题，可选择性修复
+
+## 📝 输出结果
+
+评审完成后会生成 \`CODE_REVIEW.md\` 报告，包含：
+- 变更概览和统计信息
+- 按严重性和维度分类的问题列表
+- 详细的问题分析和修复建议
+- 代码质量整体评估
+
+## 💡 使用技巧
+
+1. **首次使用**：建议先对小范围变更进行评审，熟悉评审流程
+2. **自定义规则**：使用 \`--prompt-enhance\` 添加团队特定的编码规范
+3. **CI/CD 集成**：使用 \`--notice\` 参数在流水线中检测评审完成
+4. **大型变更**：系统会自动分批处理，无需手动干预
+
+## 🔗 相关命令
+
+- \`/help\` - 查看所有可用命令
+- \`/docs\` - 查看完整文档
+
+## ❓ 常见问题
+
+**Q: 如何只评审特定文件？**
+A: 目前评审基于 git diff 结果，可以先 stage 特定文件再评审。
+
+**Q: 评审需要多长时间？**
+A: 取决于变更规模，小型变更通常 1-3 分钟，大型变更可能需要 5-15 分钟。
+
+**Q: 如何自定义评审规则？**
+A: 创建 Markdown 文件描述你的规则，然后使用 \`--prompt-enhance\` 参数指定。
+
+---
+
+💡 提示：使用 \`/review --help\` 随时查看本帮助信息`;
+}
+// ============================================================================
 // 命令导出
 // ============================================================================
 export const reviewCommand = {
     name: 'review',
-    description: 'Performs code review with multiple modes: default (uncommitted changes), commit comparison, or branch comparison.',
+    description: 'Performs code review with multiple modes: default (uncommitted changes), commit comparison, branch comparison, or multiple commits comparison.',
     kind: CommandKind.BUILT_IN,
     action: async (context, args) => {
+        // 检查是否请求帮助信息
+        const trimmedArgs = args.trim();
+        if (trimmedArgs === '--help' || trimmedArgs === '-h' || trimmedArgs === 'help') {
+            return {
+                type: 'message',
+                messageType: 'info',
+                content: buildHelpMessage(),
+            };
+        }
         // 验证服务可用性
         if (!context.services.config) {
             return {
@@ -1234,9 +2001,21 @@ export const reviewCommand = {
             };
         }
         try {
-            // 解析参数并获取统计信息
+            // 解析参数
             const options = ReviewArgumentParser.parse(args);
-            const stats = await GitStatsAnalyzer.getDiffStats(projectRoot, options);
+            let stats;
+            let changeList;
+            // 根据模式获取统计信息
+            if (options.mode === 'commits' && options.commits) {
+                // commits 模式：使用 MultiCommitAnalyzer
+                const result = await MultiCommitAnalyzer.analyzeCommits(projectRoot, options.commits);
+                stats = result.stats;
+                changeList = result.changeList;
+            }
+            else {
+                // 其他模式：使用 GitStatsAnalyzer
+                stats = await GitStatsAnalyzer.getDiffStats(projectRoot, options);
+            }
             // 检查是否有变更
             if (stats.fileCount === 0) {
                 return {
@@ -1246,7 +2025,7 @@ export const reviewCommand = {
                 };
             }
             // 根据变更规模选择评审策略
-            const reviewPrompt = ReviewStrategySelector.selectStrategy(stats, projectRoot, options);
+            const reviewPrompt = ReviewStrategySelector.selectStrategy(stats, projectRoot, options, changeList);
             return {
                 type: 'submit_prompt',
                 content: reviewPrompt,