@spaceflow/review 0.63.0 → 0.65.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.64.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@0.63.0...@spaceflow/review@0.64.0) (2026-03-03)
+
+### 测试用例
+
+* **review:** 新增 deleteExistingAiReviews、buildLineReviewBody、findExistingAiComments、syncReactionsToIssues 和 filterIssuesByValidCommits 方法的详细日志测试 ([0619e9c](https://github.com/Lydanne/spaceflow/commit/0619e9cc1e5a81d24703e2e574026a249d87f236))
+* **review:** 新增 invalidateIssuesForChangedFiles、updateIssueLineNumbers、filterIssuesByValidCommits 和 ensureClaudeCli 方法的单元测试 ([876f827](https://github.com/Lydanne/spaceflow/commit/876f82746331cf2e353b0a537b8691395e2a1084))
+
+### 其他修改
+
+* **review-summary:** released version 0.31.0 [no ci] ([9b028ce](https://github.com/Lydanne/spaceflow/commit/9b028cedd03d8c60f8c1db58b189cd022ea562cf))
+
+## [0.63.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@0.62.0...@spaceflow/review@0.63.0) (2026-03-03)
+
+### 代码重构
+
+* **review:** 为文件总结标题添加 💡 图标,增强视觉识别度 ([69cecf0](https://github.com/Lydanne/spaceflow/commit/69cecf0a6deadf1935db060800f8f110ae4b9889))
+
+### 其他修改
+
+* **review-summary:** released version 0.30.0 [no ci] ([3902c7b](https://github.com/Lydanne/spaceflow/commit/3902c7be16ceb6ab7ff2abe52e434634de12a664))
+
 ## [0.62.0](https://github.com/Lydanne/spaceflow/compare/@spaceflow/review@0.61.0...@spaceflow/review@0.62.0) (2026-03-03)
 
 ### 代码重构

package/dist/index.js

@@ -150,9 +150,9 @@ __webpack_require__.d(__webpack_exports__, {
 ;// CONCATENATED MODULE: external "@spaceflow/core"
 
 ;// CONCATENATED MODULE: ./src/locales/zh-cn/review.json
-var review_namespaceObject = JSON.parse('{"description":"代码审查命令，使用 LLM 对 PR 代码进行自动审查","options.dryRun":"仅打印将要执行的操作，不实际提交评论","options.prNumber":"PR 编号，如果不指定则从环境变量获取","options.base":"基准分支/tag，用于比较差异","options.head":"目标分支/tag，用于比较差异","options.includes":"要审查的文件 glob 模式，如 *.ts *.js（可多次指定）","options.llmMode":"使用的 LLM 模式: claude-code, openai, gemini","options.files":"仅审查指定的文件（空格分隔）","options.commits":"仅审查指定的 commits（空格分隔）","options.verifyFixes":"是否验证历史问题是否已修复（默认从配置文件读取）","options.noVerifyFixes":"禁用历史问题验证","options.verifyConcurrency":"验证历史问题的并发数（默认 10）","options.analyzeDeletions":"分析删除代码可能带来的影响 (true, false, ci, pr, terminal)","options.deletionAnalysisMode":"删除代码分析模式: openai (标准模式) 或 claude-code (Agent 模式，可使用工具)","options.deletionOnly":"仅执行删除代码分析，跳过常规代码审查","options.outputFormat":"输出格式: markdown, terminal, json。不指定则智能选择（PR 用 markdown，终端用 terminal）","options.generateDescription":"使用 AI 生成 PR 功能描述","options.showAll":"显示所有发现的问题，不过滤非变更行的问题","options.flush":"仅刷新状态（同步 reactions、resolved conversations、replies），不执行 LLM 审查","options.eventAction":"PR 事件类型（opened, synchronize, closed 等），closed 时仅收集统计不进行 AI 审查","extensionDescription":"代码审查命令，使用 LLM 对 PR 代码进行自动审查","mcp.serverDescription":"代码审查规则查询服务","mcp.listRules":"获取当前项目的所有代码审查规则，返回规则列表包含 ID、标题、描述、适用的文件扩展名等信息","mcp.getRulesForFile":"获取某个文件应该使用的代码审查规则，根据文件扩展名和 includes 配置过滤","mcp.getRuleDetail":"获取某个规则的完整详情，包括描述、示例代码等","mcp.ruleNotFound":"规则 {{ruleId}} 不存在","mcp.dto.cwd":"项目根目录路径，默认为当前工作目录","mcp.dto.filePath":"文件路径，可以是相对路径或绝对路径","mcp.dto.includeExamples":"是否包含规则示例代码，默认 false","mcp.dto.ruleId":"规则 ID，如 JsTs.Naming.FileName","mcp.getRulesFromDir":"从指定目录加载代码审查规则。读取目录下所有 .md 文件，解析为规则并按规则 ID 去重（后加载的覆盖先加载的）","mcp.dto.dirPath":"包含规则 .md 文件的目录路径，可以是相对路径或绝对路径"}')
+var review_namespaceObject = JSON.parse('{"description":"代码审查命令，使用 LLM 对 PR 代码进行自动审查","options.dryRun":"仅打印将要执行的操作，不实际提交评论","options.prNumber":"PR 编号，如果不指定则从环境变量获取","options.base":"基准分支/tag，用于比较差异","options.head":"目标分支/tag，用于比较差异","options.includes":"要审查的文件 glob 模式，如 *.ts *.js（可多次指定）","options.llmMode":"使用的 LLM 模式: claude-code, openai, gemini","options.files":"仅审查指定的文件（空格分隔）","options.commits":"仅审查指定的 commits（空格分隔）","options.verifyFixes":"是否验证历史问题是否已修复（默认从配置文件读取）","options.noVerifyFixes":"禁用历史问题验证","options.verifyConcurrency":"验证历史问题的并发数（默认 10）","options.analyzeDeletions":"分析删除代码可能带来的影响 (true, false, ci, pr, terminal)","options.deletionAnalysisMode":"删除代码分析模式: openai (标准模式) 或 claude-code (Agent 模式，可使用工具)","options.deletionOnly":"仅执行删除代码分析，跳过常规代码审查","options.outputFormat":"输出格式: markdown, terminal, json。不指定则智能选择（PR 用 markdown，终端用 terminal）","options.generateDescription":"使用 AI 生成 PR 功能描述","options.showAll":"显示所有发现的问题，不过滤非变更行的问题","options.flush":"仅刷新状态（同步 reactions、resolved conversations、replies），不执行 LLM 审查","options.eventAction":"PR 事件类型（opened, synchronize, closed 等），closed 时仅收集统计不进行 AI 审查","options.local":"审查本地未提交的代码。模式: \'uncommitted\'（默认，暂存区+工作区）或 \'staged\'（仅暂存区）","options.noLocal":"禁用本地模式，使用分支比较","extensionDescription":"代码审查命令，使用 LLM 对 PR 代码进行自动审查","mcp.serverDescription":"代码审查规则查询服务","mcp.listRules":"获取当前项目的所有代码审查规则，返回规则列表包含 ID、标题、描述、适用的文件扩展名等信息","mcp.getRulesForFile":"获取某个文件应该使用的代码审查规则，根据文件扩展名和 includes 配置过滤","mcp.getRuleDetail":"获取某个规则的完整详情，包括描述、示例代码等","mcp.ruleNotFound":"规则 {{ruleId}} 不存在","mcp.dto.cwd":"项目根目录路径，默认为当前工作目录","mcp.dto.filePath":"文件路径，可以是相对路径或绝对路径","mcp.dto.includeExamples":"是否包含规则示例代码，默认 false","mcp.dto.ruleId":"规则 ID，如 JsTs.Naming.FileName","mcp.getRulesFromDir":"从指定目录加载代码审查规则。读取目录下所有 .md 文件，解析为规则并按规则 ID 去重（后加载的覆盖先加载的）","mcp.dto.dirPath":"包含规则 .md 文件的目录路径，可以是相对路径或绝对路径"}')
 ;// CONCATENATED MODULE: ./src/locales/en/review.json
-var en_review_namespaceObject = JSON.parse('{"description":"Code review command using LLM for automated PR review","options.dryRun":"Only print actions without posting comments","options.prNumber":"PR number, auto-detected from env if not specified","options.base":"Base branch/tag for diff comparison","options.head":"Head branch/tag for diff comparison","options.includes":"File glob patterns to review, e.g. *.ts *.js (can be specified multiple times)","options.llmMode":"LLM mode: claude-code, openai, gemini","options.files":"Only review specified files (space-separated)","options.commits":"Only review specified commits (space-separated)","options.verifyFixes":"Verify if historical issues are fixed (default from config)","options.noVerifyFixes":"Disable historical issue verification","options.verifyConcurrency":"Concurrency for verifying historical issues (default 10)","options.analyzeDeletions":"Analyze impact of deleted code (true, false, ci, pr, terminal)","options.deletionAnalysisMode":"Deletion analysis mode: openai (standard) or claude-code (Agent mode with tools)","options.deletionOnly":"Only run deletion analysis, skip regular code review","options.outputFormat":"Output format: markdown, terminal, json. Auto-selected if not specified (markdown for PR, terminal for CLI)","options.generateDescription":"Generate PR description using AI","options.showAll":"Show all issues found, including those on unchanged lines","options.flush":"Only sync status (reactions, resolved conversations, replies), skip LLM review","options.eventAction":"PR event type (opened, synchronize, closed, etc.), closed only collects stats without AI review","extensionDescription":"Code review command using LLM for automated PR review","mcp.serverDescription":"Code review rules query service","mcp.listRules":"List all code review rules for the current project, returning rule list with ID, title, description, applicable file extensions, etc.","mcp.getRulesForFile":"Get applicable code review rules for a specific file, filtered by file extension and includes configuration","mcp.getRuleDetail":"Get full details of a specific rule, including description, example code, etc.","mcp.ruleNotFound":"Rule {{ruleId}} not found","mcp.dto.cwd":"Project root directory path, defaults to current working directory","mcp.dto.filePath":"File path, can be relative or absolute","mcp.dto.includeExamples":"Whether to include rule example code, defaults to false","mcp.dto.ruleId":"Rule ID, e.g. JsTs.Naming.FileName","mcp.getRulesFromDir":"Load code review rules from a specific directory. Reads all .md files in the directory, parses them into rules, and deduplicates by rule ID (later rules override earlier ones)","mcp.dto.dirPath":"Directory path containing rule .md files, can be relative or absolute"}')
+var en_review_namespaceObject = JSON.parse('{"description":"Code review command using LLM for automated PR review","options.dryRun":"Only print actions without posting comments","options.prNumber":"PR number, auto-detected from env if not specified","options.base":"Base branch/tag for diff comparison","options.head":"Head branch/tag for diff comparison","options.includes":"File glob patterns to review, e.g. *.ts *.js (can be specified multiple times)","options.llmMode":"LLM mode: claude-code, openai, gemini","options.files":"Only review specified files (space-separated)","options.commits":"Only review specified commits (space-separated)","options.verifyFixes":"Verify if historical issues are fixed (default from config)","options.noVerifyFixes":"Disable historical issue verification","options.verifyConcurrency":"Concurrency for verifying historical issues (default 10)","options.analyzeDeletions":"Analyze impact of deleted code (true, false, ci, pr, terminal)","options.deletionAnalysisMode":"Deletion analysis mode: openai (standard) or claude-code (Agent mode with tools)","options.deletionOnly":"Only run deletion analysis, skip regular code review","options.outputFormat":"Output format: markdown, terminal, json. Auto-selected if not specified (markdown for PR, terminal for CLI)","options.generateDescription":"Generate PR description using AI","options.showAll":"Show all issues found, including those on unchanged lines","options.flush":"Only sync status (reactions, resolved conversations, replies), skip LLM review","options.eventAction":"PR event type (opened, synchronize, closed, etc.), closed only collects stats without AI review","options.local":"Review local uncommitted code. Mode: \'uncommitted\' (default, staged + working) or \'staged\' (only staged)","options.noLocal":"Disable local mode, use branch comparison instead","extensionDescription":"Code review command using LLM for automated PR review","mcp.serverDescription":"Code review rules query service","mcp.listRules":"List all code review rules for the current project, returning rule list with ID, title, description, applicable file extensions, etc.","mcp.getRulesForFile":"Get applicable code review rules for a specific file, filtered by file extension and includes configuration","mcp.getRuleDetail":"Get full details of a specific rule, including description, example code, etc.","mcp.ruleNotFound":"Rule {{ruleId}} not found","mcp.dto.cwd":"Project root directory path, defaults to current working directory","mcp.dto.filePath":"File path, can be relative or absolute","mcp.dto.includeExamples":"Whether to include rule example code, defaults to false","mcp.dto.ruleId":"Rule ID, e.g. JsTs.Naming.FileName","mcp.getRulesFromDir":"Load code review rules from a specific directory. Reads all .md files in the directory, parses them into rules, and deduplicates by rule ID (later rules override earlier ones)","mcp.dto.dirPath":"Directory path containing rule .md files, can be relative or absolute"}')
 ;// CONCATENATED MODULE: ./src/locales/index.ts
 
 
@@ -1967,10 +1967,16 @@ class ReviewService {
         if (reviewConf.references?.length) {
             specSources.push(...reviewConf.references);
         }
-        // 当没有 PR 且没有指定 base/head 时，自动获取默认值
+        // 解析本地模式：非 CI、非 PR、无 base/head 时默认启用 uncommitted 模式
+        const localMode = this.resolveLocalMode(options, {
+            ci: options.ci,
+            hasPrNumber: !!prNumber,
+            hasBaseHead: !!(options.base || options.head)
+        });
+        // 当没有 PR 且没有指定 base/head 且不是本地模式时，自动获取默认值
         let baseRef = options.base;
         let headRef = options.head;
-        if (!prNumber && !baseRef && !headRef) {
+        if (!prNumber && !baseRef && !headRef && !localMode) {
             headRef = this.gitSdk.getCurrentBranch() ?? "HEAD";
             baseRef = this.gitSdk.getDefaultBranch();
             if (shouldLog(options.verbose, 1)) {
@@ -2007,10 +2013,36 @@ class ReviewService {
             generateDescription: options.generateDescription ?? reviewConf.generateDescription ?? false,
             showAll: options.showAll ?? false,
             flush: options.flush ?? false,
-            eventAction: options.eventAction
+            eventAction: options.eventAction,
+            localMode
         };
     }
     /**
+   * 解析本地代码审查模式
+   * - 显式指定 --local [mode] 时使用指定值
+   * - 显式指定 --no-local 时禁用
+   * - 非 CI、非 PR、无 base/head 时默认启用 uncommitted 模式
+   */ resolveLocalMode(options, env) {
+        // 显式指定了 --no-local
+        if (options.local === false) {
+            return false;
+        }
+        // 显式指定了 --local [mode]
+        if (options.local === "staged" || options.local === "uncommitted") {
+            return options.local;
+        }
+        // CI 或 PR 模式下不启用本地模式
+        if (env.ci || env.hasPrNumber) {
+            return false;
+        }
+        // 指定了 base/head 时不启用本地模式
+        if (env.hasBaseHead) {
+            return false;
+        }
+        // 默认启用 uncommitted 模式
+        return "uncommitted";
+    }
+    /**
    * 将文件路径规范化为相对于仓库根目录的路径
    * 支持绝对路径和相对路径输入
    */ normalizeFilePaths(files) {
@@ -2076,13 +2108,21 @@ class ReviewService {
    * @param context 审查上下文，包含 owner、repo、prNumber 等信息
    * @returns 审查结果，包含发现的问题列表和统计信息
    */ async execute(context) {
-        const { owner, repo, prNumber, baseRef, headRef, specSources, dryRun, ci, verbose, includes, llmMode, files, commits: filterCommits, deletionOnly } = context;
+        const { owner, repo, prNumber, baseRef, headRef, specSources, dryRun, ci, verbose, includes, llmMode, files, commits: filterCommits, deletionOnly, localMode } = context;
         // 直接审查文件模式：指定了 -f 文件且 base=head
         const isDirectFileMode = files && files.length > 0 && baseRef === headRef;
+        // 本地模式：审查未提交的代码（可能回退到分支比较）
+        let isLocalMode = !!localMode;
+        // 用于回退时动态计算的 base/head
+        let effectiveBaseRef = baseRef;
+        let effectiveHeadRef = headRef;
         if (shouldLog(verbose, 1)) {
             console.log(`🔍 Review 启动`);
             console.log(`   DRY-RUN mode: ${dryRun ? "enabled" : "disabled"}`);
             console.log(`   CI mode: ${ci ? "enabled" : "disabled"}`);
+            if (isLocalMode) {
+                console.log(`   Local mode: ${localMode}`);
+            }
             console.log(`   Verbose: ${verbose}`);
         }
         // 如果是 deletionOnly 模式，直接执行删除代码分析
@@ -2097,6 +2137,52 @@ class ReviewService {
         let pr;
         let commits = [];
         let changedFiles = [];
+        if (isLocalMode) {
+            // 本地模式：从 git 获取未提交/暂存区的变更
+            if (shouldLog(verbose, 1)) {
+                console.log(`📥 本地模式: 获取${localMode === "staged" ? "暂存区" : "未提交"}的代码变更`);
+            }
+            const localFiles = localMode === "staged" ? this.gitSdk.getStagedFiles() : this.gitSdk.getUncommittedFiles();
+            if (localFiles.length === 0) {
+                // 本地无变更，回退到分支比较模式
+                if (shouldLog(verbose, 1)) {
+                    console.log(`ℹ️  没有${localMode === "staged" ? "暂存区" : "未提交"}的代码变更，回退到分支比较模式`);
+                }
+                isLocalMode = false;
+                effectiveHeadRef = this.gitSdk.getCurrentBranch() ?? "HEAD";
+                effectiveBaseRef = this.gitSdk.getDefaultBranch();
+                if (shouldLog(verbose, 1)) {
+                    console.log(`📌 自动检测分支: base=${effectiveBaseRef}, head=${effectiveHeadRef}`);
+                }
+                // 同分支无法比较，提前返回
+                if (effectiveBaseRef === effectiveHeadRef) {
+                    console.log(`ℹ️  当前分支 ${effectiveHeadRef} 与默认分支相同，没有可审查的代码变更`);
+                    return {
+                        success: true,
+                        description: "",
+                        issues: [],
+                        summary: [],
+                        round: 1
+                    };
+                }
+            } else {
+                // 一次性获取所有 diff，避免每个文件调用一次 git 命令
+                const localDiffs = localMode === "staged" ? this.gitSdk.getStagedDiff() : this.gitSdk.getUncommittedDiff();
+                const diffMap = new Map(localDiffs.map((d)=>[
+                        d.filename,
+                        d.patch
+                    ]));
+                changedFiles = localFiles.map((f)=>({
+                        filename: f.filename,
+                        status: f.status,
+                        patch: diffMap.get(f.filename)
+                    }));
+                if (shouldLog(verbose, 1)) {
+                    console.log(`   Changed files: ${changedFiles.length}`);
+                }
+            }
+        }
+        // PR 模式、分支比较模式、或本地模式回退后的分支比较
         if (prNumber) {
             if (shouldLog(verbose, 1)) {
                 console.log(`📥 获取 PR #${prNumber} 信息 (owner: ${owner}, repo: ${repo})`);
@@ -2109,9 +2195,9 @@ class ReviewService {
                 console.log(`   Commits: ${commits.length}`);
                 console.log(`   Changed files: ${changedFiles.length}`);
             }
-        } else if (baseRef && headRef) {
+        } else if (effectiveBaseRef && effectiveHeadRef) {
             // 如果指定了 -f 文件且 base=head（无差异模式），直接审查指定文件
-            if (files && files.length > 0 && baseRef === headRef) {
+            if (files && files.length > 0 && effectiveBaseRef === effectiveHeadRef) {
                 if (shouldLog(verbose, 1)) {
                     console.log(`📥 直接审查指定文件模式 (${files.length} 个文件)`);
                 }
@@ -2119,18 +2205,20 @@ class ReviewService {
                         filename: f,
                         status: "modified"
                     }));
-            } else {
+            } else if (changedFiles.length === 0) {
+                // 仅当 changedFiles 为空时才获取（避免与回退逻辑重复）
                 if (shouldLog(verbose, 1)) {
-                    console.log(`📥 获取 ${baseRef}...${headRef} 的差异 (owner: ${owner}, repo: ${repo})`);
+                    console.log(`📥 获取 ${effectiveBaseRef}...${effectiveHeadRef} 的差异 (owner: ${owner}, repo: ${repo})`);
                 }
-                changedFiles = await this.getChangedFilesBetweenRefs(owner, repo, baseRef, headRef);
-                commits = await this.getCommitsBetweenRefs(baseRef, headRef);
+                changedFiles = await this.getChangedFilesBetweenRefs(owner, repo, effectiveBaseRef, effectiveHeadRef);
+                commits = await this.getCommitsBetweenRefs(effectiveBaseRef, effectiveHeadRef);
                 if (shouldLog(verbose, 1)) {
                     console.log(`   Changed files: ${changedFiles.length}`);
                     console.log(`   Commits: ${commits.length}`);
                 }
             }
-        } else {
+        } else if (!isLocalMode) {
+            // 非本地模式且无有效的 base/head
             if (shouldLog(verbose, 1)) {
                 console.log(`❌ 错误: 缺少 prNumber 或 baseRef/headRef`, {
                     prNumber,
@@ -2227,7 +2315,7 @@ class ReviewService {
             };
         }
         const headSha = pr?.head?.sha || headRef || "HEAD";
-        const fileContents = await this.getFileContents(owner, repo, changedFiles, commits, headSha, prNumber, verbose);
+        const fileContents = await this.getFileContents(owner, repo, changedFiles, commits, headSha, prNumber, verbose, isLocalMode);
         if (!llmMode) {
             throw new Error("必须指定 LLM 类型");
         }
@@ -2636,9 +2724,9 @@ class ReviewService {
     /**
    * 获取文件内容并构建行号到 commit hash 的映射
    * 返回 Map<filename, Array<[commitHash, lineCode]>>
-   */ async getFileContents(owner, repo, changedFiles, commits, ref, prNumber, verbose) {
+   */ async getFileContents(owner, repo, changedFiles, commits, ref, prNumber, verbose, isLocalMode) {
         const contents = new Map();
-        const latestCommitHash = commits[commits.length - 1]?.sha?.slice(0, 7) || "-------";
+        const latestCommitHash = commits[commits.length - 1]?.sha?.slice(0, 7) || "+local+";
         // 优先使用 changedFiles 中的 patch 字段（来自 PR 的整体 diff base...head）
         // 这样行号是相对于最终文件的，而不是每个 commit 的父 commit
         // buildLineCommitMap 遍历每个 commit 的 diff，行号可能与最终文件不一致
@@ -2649,7 +2737,10 @@ class ReviewService {
             if (file.filename && file.status !== "deleted") {
                 try {
                     let rawContent;
-                    if (prNumber) {
+                    if (isLocalMode) {
+                        // 本地模式：读取工作区文件的当前内容
+                        rawContent = this.gitSdk.getWorkingFileContent(file.filename);
+                    } else if (prNumber) {
                         rawContent = await this.gitProvider.getFileContent(owner, repo, file.filename, ref);
                     } else {
                         rawContent = await this.gitSdk.getFileContent(ref, file.filename);
@@ -5504,6 +5595,14 @@ const extension = defineExtension({
                 {
                     flags: "--event-action <action>",
                     description: t("review:options.eventAction")
+                },
+                {
+                    flags: "--local [mode]",
+                    description: t("review:options.local")
+                },
+                {
+                    flags: "--no-local",
+                    description: t("review:options.noLocal")
                 }
             ],
             run: async (_args, options, ctx)=>{
@@ -5543,8 +5642,15 @@ const extension = defineExtension({
                     generateDescription: options?.generateDescription ? true : undefined,
                     showAll: !!options?.showAll,
                     flush: isFlush,
-                    eventAction: options?.eventAction
+                    eventAction: options?.eventAction,
+                    local: parseLocalOption(options?.local)
                 };
+                function parseLocalOption(value) {
+                    if (value === false) return false;
+                    if (value === true || value === undefined || value === "") return undefined;
+                    if (value === "staged" || value === "uncommitted") return value;
+                    return undefined;
+                }
                 try {
                     const context = await reviewService.getContextFromEnv(reviewOptions);
                     await reviewService.execute(context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaceflow/review",
-  "version": "0.63.0",
+  "version": "0.65.0",
   "description": "Spaceflow 代码审查插件，使用 LLM 对 PR 代码进行自动审查",
   "license": "MIT",
   "author": "Lydanne",
@@ -28,7 +28,7 @@
     "@spaceflow/cli": "0.38.0"
   },
   "peerDependencies": {
-    "@spaceflow/core": "0.23.0"
+    "@spaceflow/core": "0.24.0"
   },
   "spaceflow": {
     "type": "flow",

package/src/index.ts

@@ -2,7 +2,13 @@ import "./locales";
 export * from "./review-spec";
 export * from "./review-report";
 import { defineExtension, t } from "@spaceflow/core";
-import type { GitProviderService, LlmProxyService, GitSdkService, LLMMode } from "@spaceflow/core";
+import type {
+  GitProviderService,
+  LlmProxyService,
+  GitSdkService,
+  LLMMode,
+  LocalReviewMode,
+} from "@spaceflow/core";
 import { parseVerbose } from "@spaceflow/core";
 import { reviewSchema, type AnalyzeDeletionsMode } from "./review.config";
 import { ReviewService } from "./review.service";
@@ -46,6 +52,8 @@ export const extension = defineExtension({
         { flags: "--show-all", description: t("review:options.showAll") },
         { flags: "--flush", description: t("review:options.flush") },
         { flags: "--event-action <action>", description: t("review:options.eventAction") },
+        { flags: "--local [mode]", description: t("review:options.local") },
+        { flags: "--no-local", description: t("review:options.noLocal") },
       ],
       run: async (_args, options, ctx) => {
         const isFlush = !!options?.flush;
@@ -104,8 +112,16 @@ export const extension = defineExtension({
           showAll: !!options?.showAll,
           flush: isFlush,
           eventAction: options?.eventAction as string,
+          local: parseLocalOption(options?.local),
         };
 
+        function parseLocalOption(value: unknown): LocalReviewMode | undefined {
+          if (value === false) return false;
+          if (value === true || value === undefined || value === "") return undefined;
+          if (value === "staged" || value === "uncommitted") return value;
+          return undefined;
+        }
+
         try {
           const context = await reviewService.getContextFromEnv(reviewOptions);
           await reviewService.execute(context);

package/src/locales/en/review.json

@@ -19,6 +19,8 @@
   "options.showAll": "Show all issues found, including those on unchanged lines",
   "options.flush": "Only sync status (reactions, resolved conversations, replies), skip LLM review",
   "options.eventAction": "PR event type (opened, synchronize, closed, etc.), closed only collects stats without AI review",
+  "options.local": "Review local uncommitted code. Mode: 'uncommitted' (default, staged + working) or 'staged' (only staged)",
+  "options.noLocal": "Disable local mode, use branch comparison instead",
   "extensionDescription": "Code review command using LLM for automated PR review",
   "mcp.serverDescription": "Code review rules query service",
   "mcp.listRules": "List all code review rules for the current project, returning rule list with ID, title, description, applicable file extensions, etc.",

package/src/locales/zh-cn/review.json

@@ -19,6 +19,8 @@
   "options.showAll": "显示所有发现的问题，不过滤非变更行的问题",
   "options.flush": "仅刷新状态（同步 reactions、resolved conversations、replies），不执行 LLM 审查",
   "options.eventAction": "PR 事件类型（opened, synchronize, closed 等），closed 时仅收集统计不进行 AI 审查",
+  "options.local": "审查本地未提交的代码。模式: 'uncommitted'（默认，暂存区+工作区）或 'staged'（仅暂存区）",
+  "options.noLocal": "禁用本地模式，使用分支比较",
   "extensionDescription": "代码审查命令，使用 LLM 对 PR 代码进行自动审查",
   "mcp.serverDescription": "代码审查规则查询服务",
   "mcp.listRules": "获取当前项目的所有代码审查规则，返回规则列表包含 ID、标题、描述、适用的文件扩展名等信息",

package/src/review.config.ts

@@ -1,5 +1,5 @@
 import { z } from "@spaceflow/core";
-import type { LLMMode, VerboseLevel } from "@spaceflow/core";
+import type { LLMMode, VerboseLevel, LocalReviewMode } from "@spaceflow/core";
 import type { ReportFormat } from "./review-report";
 
 /** LLM 模式 schema（与 core 中的 LLMMode 保持一致） */
@@ -71,6 +71,14 @@ export interface ReviewOptions {
   timeout?: number;
   retries?: number;
   retryDelay?: number;
+  /**
+   * 本地代码审查模式
+   * - 'uncommitted': 审查所有未提交的代码（暂存区 + 工作区）
+   * - 'staged': 仅审查暂存区的代码
+   * - false: 禁用本地模式
+   * 在非 CI 和非 PR 模式下默认为 'uncommitted'
+   */
+  local?: LocalReviewMode;
 }
 
 /** review 命令配置 schema（LLM 敏感配置由系统 llm.config.ts 管理） */

package/src/review.service.spec.ts

@@ -75,6 +75,7 @@ describe("ReviewService", () => {
       updateIssueComment: vi.fn().mockResolvedValue({}),
       deleteIssueComment: vi.fn().mockResolvedValue(undefined),
       updatePullReview: vi.fn().mockResolvedValue({}),
+      getTeamMembers: vi.fn().mockResolvedValue([]),
     };
 
     configService = {
@@ -1246,6 +1247,7 @@ describe("ReviewService", () => {
         invalid: 0,
         pending: 0,
         fixRate: 0,
+        resolveRate: 0,
       });
     });
 
@@ -1555,6 +1557,19 @@ describe("ReviewService", () => {
       expect(consoleSpy).toHaveBeenCalled();
       consoleSpy.mockRestore();
     });
+
+    it("should log error when deleting comment fails", async () => {
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      gitProvider.listPullReviews.mockResolvedValue([] as any);
+      gitProvider.listIssueComments.mockResolvedValue([
+        { id: 10, body: "<!-- spaceflow-review --> old comment" },
+      ] as any);
+      gitProvider.deleteIssueComment.mockRejectedValue(new Error("delete failed"));
+
+      await (service as any).deleteExistingAiReviews("o", "r", 1);
+      expect(consoleSpy).toHaveBeenCalledWith("⚠️ 删除评论 10 失败:", expect.any(Error));
+      consoleSpy.mockRestore();
+    });
   });
 
   describe("ReviewService.invalidateIssuesForChangedFiles", () => {
@@ -2381,11 +2396,48 @@ describe("ReviewService", () => {
         { content: "-1", user: { login: "random-user" } },
       ] as any);
       const result = { issues: [{ file: "test.ts", line: "10", valid: "true", reactions: [] }] };
-      await (service as any).syncReactionsToIssues("o", "r", 1, result);
       expect(result.issues[0].valid).toBe("true");
     });
   });
 
+  describe("ReviewService.buildLineReviewBody", () => {
+    it("should include previous round summary when round > 1", () => {
+      const issues = [
+        { round: 2, fixed: "2024-01-01", resolved: undefined, valid: undefined },
+        { round: 2, resolved: "2024-01-02", fixed: undefined, valid: undefined },
+        { round: 2, valid: "false", fixed: undefined, resolved: undefined },
+        { round: 2, fixed: undefined, resolved: undefined, valid: undefined },
+      ];
+      const allIssues = [
+        ...issues,
+        { round: 1, fixed: "2024-01-01" },
+        { round: 1, resolved: "2024-01-02" },
+        { round: 1, valid: "false" },
+        { round: 1 },
+      ];
+      const result = (service as any).buildLineReviewBody(issues, 2, allIssues);
+      expect(result).toContain("Round 1 回顾");
+      expect(result).toContain("🟢 已修复 | 1");
+      expect(result).toContain("⚪ 已解决 | 1");
+      expect(result).toContain("❌ 无效 | 1");
+      expect(result).toContain("⚠️ 待处理 | 1");
+    });
+
+    it("should not include previous round summary when round <= 1", () => {
+      const issues = [{ round: 1 }];
+      const allIssues = [{ round: 1 }];
+      const result = (service as any).buildLineReviewBody(issues, 1, allIssues);
+      expect(result).not.toContain("Round 1 回顾");
+    });
+
+    it("should show no issues message when issues array is empty", () => {
+      const issues = [];
+      const allIssues = [];
+      const result = (service as any).buildLineReviewBody(issues, 1, allIssues);
+      expect(result).toContain("✅ 未发现新问题");
+    });
+  });
+
   describe("ReviewService.buildReviewPrompt", () => {
     it("should build prompts for changed files", async () => {
       const specs = [{ extensions: ["ts"], includes: [], rules: [{ id: "R1" }] }];
@@ -3226,4 +3278,450 @@ describe("ReviewService", () => {
       expect(result.size).toBe(0);
     });
   });
+
+  describe("ReviewService.invalidateIssuesForChangedFiles", () => {
+    it("should return issues unchanged when no headSha", async () => {
+      const issues = [{ file: "test.ts" }];
+      const result = await (service as any).invalidateIssuesForChangedFiles(
+        issues,
+        undefined,
+        "o",
+        "r",
+      );
+      expect(result).toBe(issues);
+    });
+
+    it("should log warning when no headSha", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const issues = [{ file: "test.ts" }];
+      await (service as any).invalidateIssuesForChangedFiles(issues, undefined, "o", "r", 1);
+      expect(consoleSpy).toHaveBeenCalledWith("   ⚠️ 无法获取 PR head SHA，跳过变更文件检查");
+      consoleSpy.mockRestore();
+    });
+
+    it("should invalidate issues for changed files", async () => {
+      gitProvider.getCommitDiff = vi
+        .fn()
+        .mockResolvedValue(
+          "diff --git a/changed.ts b/changed.ts\n--- a/changed.ts\n+++ b/changed.ts\n@@ -1,1 +1,2 @@\n line1\n+new",
+        ) as any;
+      const issues = [
+        { file: "changed.ts", line: "1", ruleId: "R1" },
+        { file: "unchanged.ts", line: "2", ruleId: "R2" },
+        { file: "changed.ts", line: "3", ruleId: "R3", fixed: "2024-01-01" },
+      ];
+      const result = await (service as any).invalidateIssuesForChangedFiles(
+        issues,
+        "abc123",
+        "o",
+        "r",
+        1,
+      );
+      expect(result).toHaveLength(3);
+      expect(result[0].valid).toBe("false");
+      expect(result[1].valid).toBeUndefined();
+      expect(result[2].fixed).toBe("2024-01-01");
+    });
+
+    it("should log when files are invalidated", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      gitProvider.getCommitDiff = vi
+        .fn()
+        .mockResolvedValue(
+          "diff --git a/changed.ts b/changed.ts\n--- a/changed.ts\n+++ b/changed.ts\n@@ -1,1 +1,2 @@\n line1\n+new",
+        ) as any;
+      const issues = [{ file: "changed.ts", line: "1", ruleId: "R1" }];
+      await (service as any).invalidateIssuesForChangedFiles(issues, "abc123", "o", "r", 1);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "   🗑️ Issue changed.ts:1 所在文件有变更，标记为无效",
+      );
+      expect(consoleSpy).toHaveBeenCalledWith("   📊 共标记 1 个历史问题为无效（文件有变更）");
+      consoleSpy.mockRestore();
+    });
+
+    it("should return issues unchanged when no diff files", async () => {
+      gitProvider.getCommitDiff = vi.fn().mockResolvedValue("") as any;
+      const issues = [{ file: "test.ts", line: "1" }];
+      const result = await (service as any).invalidateIssuesForChangedFiles(
+        issues,
+        "abc123",
+        "o",
+        "r",
+        1,
+      );
+      expect(result).toBe(issues);
+    });
+
+    it("should log when no diff files", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      gitProvider.getCommitDiff = vi.fn().mockResolvedValue("") as any;
+      const issues = [{ file: "test.ts", line: "1" }];
+      await (service as any).invalidateIssuesForChangedFiles(issues, "abc123", "o", "r", 1);
+      expect(consoleSpy).toHaveBeenCalledWith("   ⏭️ 最新 commit 无文件变更");
+      consoleSpy.mockRestore();
+    });
+
+    it("should handle API error gracefully", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      gitProvider.getCommitDiff = vi.fn().mockRejectedValue(new Error("fail")) as any;
+      const issues = [{ file: "test.ts", line: "1" }];
+      const result = await (service as any).invalidateIssuesForChangedFiles(
+        issues,
+        "abc123",
+        "o",
+        "r",
+        1,
+      );
+      expect(result).toBe(issues);
+      expect(consoleSpy).toHaveBeenCalledWith("   ⚠️ 获取最新 commit 变更文件失败: Error: fail");
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe("ReviewService.updateIssueLineNumbers", () => {
+    beforeEach(() => {
+      mockReviewSpecService.parseLineRange = vi.fn().mockImplementation((lineStr: string) => {
+        const lines: number[] = [];
+        const rangeMatch = lineStr.match(/^(\d+)-(\d+)$/);
+        if (rangeMatch) {
+          const start = parseInt(rangeMatch[1], 10);
+          const end = parseInt(rangeMatch[2], 10);
+          for (let i = start; i <= end; i++) {
+            lines.push(i);
+          }
+        } else {
+          const line = parseInt(lineStr, 10);
+          if (!isNaN(line)) {
+            lines.push(line);
+          }
+        }
+        return lines;
+      });
+    });
+
+    it("should return issues unchanged when no patch for file", () => {
+      const issues = [{ file: "test.ts", line: "5", ruleId: "R1" }];
+      const filePatchMap = new Map([["other.ts", "@@ -1,1 +1,2 @@\n-old1\n+new1\n+new2"]]);
+      const result = (service as any).updateIssueLineNumbers(issues, filePatchMap);
+      expect(result).toEqual(issues);
+    });
+
+    it("should skip issues that are already fixed/resolved/invalid", () => {
+      const issues = [
+        { file: "test.ts", line: "5", ruleId: "R1", fixed: "2024-01-01" },
+        { file: "test.ts", line: "6", ruleId: "R2", resolved: "2024-01-02" },
+        { file: "test.ts", line: "7", ruleId: "R3", valid: "false" },
+      ];
+      const filePatchMap = new Map([["test.ts", "@@ -1,1 +1,2 @@\n-old1\n+new1\n+new2"]]);
+      const result = (service as any).updateIssueLineNumbers(issues, filePatchMap);
+      expect(result).toEqual(issues);
+    });
+
+    it("should mark issue as invalid when line is deleted", () => {
+      const filePatchMap = new Map([["test.ts", "@@ -1,1 +1,0 @@\n-old1"]]);
+      const issues = [{ file: "test.ts", line: "1", ruleId: "R1" }];
+      const result = (service as any).updateIssueLineNumbers(issues, filePatchMap);
+      expect(result[0].valid).toBe("false");
+      expect(result[0].originalLine).toBe("1");
+    });
+
+    it("should log when line is deleted and marked invalid", () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const filePatchMap = new Map([["test.ts", "@@ -1,1 +1,0 @@\n-old1"]]);
+      const issues = [{ file: "test.ts", line: "1", ruleId: "R1" }];
+      (service as any).updateIssueLineNumbers(issues, filePatchMap, 1);
+      expect(consoleSpy).toHaveBeenCalledWith("📍 Issue test.ts:1 对应的代码已被删除，标记为无效");
+      consoleSpy.mockRestore();
+    });
+
+    it("should log when line range is collapsed to single line", () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const filePatchMap = new Map([["test.ts", "@@ -1,2 +1,1 @@\n-old1\n-old2\n+new1"]]);
+      const issues = [{ file: "test.ts", line: "1-2", ruleId: "R1" }];
+      (service as any).updateIssueLineNumbers(issues, filePatchMap, 1);
+      expect(consoleSpy).toHaveBeenCalledWith("📍 Issue 行号更新: test.ts:1-2 -> test.ts:1");
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe("ReviewService.findExistingAiComments", () => {
+    it("should log comments when verbose level >= 2", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const mockComments = [
+        { id: 1, body: "test comment 1" },
+        { id: 2, body: "test comment 2<!-- spaceflow-review -->" },
+      ] as any;
+      gitProvider.listIssueComments.mockResolvedValue(mockComments);
+
+      await (service as any).findExistingAiComments("o", "r", 1, 2);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "[findExistingAiComments] listIssueComments returned 2 comments",
+      );
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "[findExistingAiComments] comment id=1, body starts with: test comment 1",
+      );
+      consoleSpy.mockRestore();
+    });
+
+    it("should log error when API fails", async () => {
+      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      gitProvider.listIssueComments.mockRejectedValue(new Error("API error"));
+
+      const result = await (service as any).findExistingAiComments("o", "r", 1);
+      expect(result).toEqual([]);
+      expect(consoleSpy).toHaveBeenCalledWith("[findExistingAiComments] error:", expect.any(Error));
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe("ReviewService.syncReactionsToIssues", () => {
+    it("should log when no AI review found", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      gitProvider.listPullReviews.mockResolvedValue([] as any);
+
+      await (service as any).syncReactionsToIssues("o", "r", 1, { issues: [] }, 2);
+      expect(consoleSpy).toHaveBeenCalledWith("[syncReactionsToIssues] No AI review found");
+      consoleSpy.mockRestore();
+    });
+
+    it("should log reviewers from reviews", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const mockReviews = [
+        { user: { login: "user1" }, body: "normal review" },
+        { user: { login: "bot" }, body: "<!-- spaceflow-review-lines --> AI review", id: 123 },
+      ] as any;
+      gitProvider.listPullReviews.mockResolvedValue(mockReviews);
+      gitProvider.listPullReviewComments.mockResolvedValue([] as any);
+
+      await (service as any).syncReactionsToIssues("o", "r", 1, { issues: [] }, 2);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "[syncReactionsToIssues] reviewers from reviews: user1",
+      );
+      consoleSpy.mockRestore();
+    });
+
+    it("should log requested reviewers and teams", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const mockReviews = [
+        { user: { login: "bot" }, body: "<!-- spaceflow-review-lines --> AI review", id: 123 },
+      ] as any;
+      const mockPr = {
+        requested_reviewers: [{ login: "reviewer1" }],
+        requested_reviewers_teams: [{ name: "team1", id: 123 }],
+      } as any;
+      gitProvider.listPullReviews.mockResolvedValue(mockReviews);
+      gitProvider.getPullRequest.mockResolvedValue(mockPr);
+      gitProvider.getTeamMembers.mockResolvedValue([{ login: "teamuser1" }]);
+      gitProvider.listPullReviewComments.mockResolvedValue([] as any);
+
+      await (service as any).syncReactionsToIssues("o", "r", 1, { issues: [] }, 2);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "[syncReactionsToIssues] requested_reviewers: reviewer1",
+      );
+      expect(consoleSpy).toHaveBeenCalledWith(
+        '[syncReactionsToIssues] requested_reviewers_teams: [{"name":"team1","id":123}]',
+      );
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "[syncReactionsToIssues] team team1(123) members: teamuser1",
+      );
+      consoleSpy.mockRestore();
+    });
+
+    it("should log final reviewers", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const mockReviews = [
+        { user: { login: "bot" }, body: "<!-- spaceflow-review-lines --> AI review", id: 123 },
+      ] as any;
+      gitProvider.listPullReviews.mockResolvedValue(mockReviews);
+      gitProvider.getPullRequest.mockRejectedValue(new Error("PR not found"));
+      gitProvider.listPullReviewComments.mockResolvedValue([] as any);
+
+      await (service as any).syncReactionsToIssues("o", "r", 1, { issues: [] }, 2);
+      expect(consoleSpy).toHaveBeenCalledWith("[syncReactionsToIssues] final reviewers: ");
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe("ReviewService.deleteExistingAiReviews", () => {
+    beforeEach(() => {
+      mockReviewSpecService.parseLineRange = vi.fn().mockImplementation((lineStr: string) => {
+        const lines: number[] = [];
+        const rangeMatch = lineStr.match(/^(\d+)-(\d+)$/);
+        if (rangeMatch) {
+          const start = parseInt(rangeMatch[1], 10);
+          const end = parseInt(rangeMatch[2], 10);
+          for (let i = start; i <= end; i++) {
+            lines.push(i);
+          }
+        } else {
+          const line = parseInt(lineStr, 10);
+          if (!isNaN(line)) {
+            lines.push(line);
+          }
+        }
+        return lines;
+      });
+    });
+
+    it("should filter issues by valid commit hashes", () => {
+      const commits = [{ sha: "abc1234567890" }];
+      const fileContents = new Map([
+        [
+          "test.ts",
+          [
+            ["-------", "line1"],
+            ["abc1234", "line2"],
+            ["-------", "line3"],
+          ],
+        ],
+      ]);
+      const issues = [
+        { file: "test.ts", line: "2", ruleId: "R1" }, // 应该保留，hash匹配
+        { file: "test.ts", line: "1", ruleId: "R2" }, // 应该过滤，hash不匹配
+        { file: "test.ts", line: "3", ruleId: "R3" }, // 应该过滤，hash不匹配
+      ];
+      const result = (service as any).filterIssuesByValidCommits(issues, commits, fileContents, 2);
+      expect(result).toHaveLength(1);
+      expect(result[0].ruleId).toBe("R1");
+    });
+
+    it("should log filtering summary", () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const commits = [{ sha: "abc1234567890" }];
+      const fileContents = new Map([
+        [
+          "test.ts",
+          [
+            ["-------", "line1"],
+            ["abc1234", "line2"],
+          ],
+        ],
+      ]);
+      const issues = [
+        { file: "test.ts", line: "1", ruleId: "R1" },
+        { file: "test.ts", line: "2", ruleId: "R2" },
+      ];
+      (service as any).filterIssuesByValidCommits(issues, commits, fileContents, 1);
+      expect(consoleSpy).toHaveBeenCalledWith("   过滤非本次 PR commits 问题后: 2 -> 1 个问题");
+      consoleSpy.mockRestore();
+    });
+
+    it("should keep issues when file not in fileContents", () => {
+      const commits = [{ sha: "abc1234567890" }];
+      const fileContents = new Map();
+      const issues = [{ file: "missing.ts", line: "1", ruleId: "R1" }];
+      const result = (service as any).filterIssuesByValidCommits(issues, commits, fileContents);
+      expect(result).toEqual(issues);
+    });
+
+    it("should keep issues when line range cannot be parsed", () => {
+      const commits = [{ sha: "abc1234567890" }];
+      const fileContents = new Map([["test.ts", [["-------", "line1"]]]]);
+      const issues = [{ file: "test.ts", line: "abc", ruleId: "R1" }];
+      const result = (service as any).filterIssuesByValidCommits(issues, commits, fileContents);
+      expect(result).toEqual(issues);
+    });
+
+    it("should handle range line numbers", () => {
+      const commits = [{ sha: "abc1234567890" }];
+      const fileContents = new Map([
+        [
+          "test.ts",
+          [
+            ["-------", "line1"],
+            ["abc1234", "line2"],
+            ["-------", "line3"],
+          ],
+        ],
+      ]);
+      const issues = [{ file: "test.ts", line: "1-3", ruleId: "R1" }];
+      const result = (service as any).filterIssuesByValidCommits(issues, commits, fileContents);
+      expect(result).toHaveLength(1); // 只要范围内有一行匹配就保留
+    });
+
+    it("should log when file not in fileContents at verbose level 3", () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const commits = [{ sha: "abc1234567890" }];
+      const fileContents = new Map();
+      const issues = [{ file: "missing.ts", line: "1", ruleId: "R1" }];
+      (service as any).filterIssuesByValidCommits(issues, commits, fileContents, 3);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "   ✅ Issue missing.ts:1 - 文件不在 fileContents 中，保留",
+      );
+      consoleSpy.mockRestore();
+    });
+
+    it("should log when line range cannot be parsed at verbose level 3", () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const commits = [{ sha: "abc1234567890" }];
+      const fileContents = new Map([["test.ts", [["-------", "line1"]]]]);
+      const issues = [{ file: "test.ts", line: "abc", ruleId: "R1" }];
+      (service as any).filterIssuesByValidCommits(issues, commits, fileContents, 3);
+      expect(consoleSpy).toHaveBeenCalledWith("   ✅ Issue test.ts:abc - 无法解析行号，保留");
+      consoleSpy.mockRestore();
+    });
+
+    it("should log detailed hash matching at verbose level 3", () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const commits = [{ sha: "abc1234567890" }];
+      const fileContents = new Map([
+        [
+          "test.ts",
+          [
+            ["-------", "line1"],
+            ["abc1234", "line2"],
+          ],
+        ],
+      ]);
+      const issues = [{ file: "test.ts", line: "2", ruleId: "R1" }];
+      (service as any).filterIssuesByValidCommits(issues, commits, fileContents, 3);
+      expect(consoleSpy).toHaveBeenCalledWith("   🔍 有效 commit hashes: abc1234");
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "   ✅ Issue test.ts:2 - 行 2 hash=abc1234 匹配，保留",
+      );
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe("ReviewService.ensureClaudeCli", () => {
+    it("should do nothing when claude is already installed", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      // execSync is already mocked globally
+
+      await (service as any).ensureClaudeCli();
+      expect(consoleSpy).not.toHaveBeenCalledWith("🔧 Claude CLI 未安装，正在安装...");
+      consoleSpy.mockRestore();
+    });
+
+    it("should install claude when not found", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      // Mock execSync to throw then succeed
+      const execSyncMock = vi.mocked(await import("child_process"));
+      execSyncMock.execSync
+        .mockImplementationOnce(() => {
+          throw new Error("command not found");
+        })
+        .mockImplementationOnce(() => Buffer.from(""));
+
+      await (service as any).ensureClaudeCli();
+      expect(consoleSpy).toHaveBeenCalledWith("🔧 Claude CLI 未安装，正在安装...");
+      expect(consoleSpy).toHaveBeenCalledWith("✅ Claude CLI 安装完成");
+      consoleSpy.mockRestore();
+    });
+
+    it("should throw error when installation fails", async () => {
+      const execSyncMock = vi.mocked(await import("child_process"));
+      execSyncMock.execSync
+        .mockImplementationOnce(() => {
+          throw new Error("command not found");
+        })
+        .mockImplementationOnce(() => {
+          throw new Error("install failed");
+        });
+
+      await expect((service as any).ensureClaudeCli()).rejects.toThrow(
+        "Claude CLI 安装失败: install failed",
+      );
+    });
+  });
 });

package/src/review.service.ts

@@ -22,7 +22,7 @@ import {
   parseHunksFromPatch,
   calculateNewLineNumber,
 } from "@spaceflow/core";
-import type { IConfigReader } from "@spaceflow/core";
+import type { IConfigReader, LocalReviewMode } from "@spaceflow/core";
 import { type AnalyzeDeletionsMode, type ReviewConfig } from "./review.config";
 import {
   ReviewSpecService,
@@ -73,6 +73,13 @@ export interface ReviewContext extends ReviewOptions {
   showAll?: boolean;
   /** PR 事件类型（opened, synchronize, closed 等） */
   eventAction?: string;
+  /**
+   * 本地代码审查模式（已解析）
+   * - 'uncommitted': 审查所有未提交的代码（暂存区 + 工作区）
+   * - 'staged': 仅审查暂存区的代码
+   * - false: 禁用本地模式
+   */
+  localMode?: LocalReviewMode;
 }
 
 export interface FileReviewPrompt {
@@ -239,10 +246,17 @@ export class ReviewService {
       specSources.push(...reviewConf.references);
     }
 
-    // 当没有 PR 且没有指定 base/head 时，自动获取默认值
+    // 解析本地模式：非 CI、非 PR、无 base/head 时默认启用 uncommitted 模式
+    const localMode = this.resolveLocalMode(options, {
+      ci: options.ci,
+      hasPrNumber: !!prNumber,
+      hasBaseHead: !!(options.base || options.head),
+    });
+
+    // 当没有 PR 且没有指定 base/head 且不是本地模式时，自动获取默认值
     let baseRef = options.base;
     let headRef = options.head;
-    if (!prNumber && !baseRef && !headRef) {
+    if (!prNumber && !baseRef && !headRef && !localMode) {
       headRef = this.gitSdk.getCurrentBranch() ?? "HEAD";
       baseRef = this.gitSdk.getDefaultBranch();
       if (shouldLog(options.verbose, 1)) {
@@ -291,9 +305,40 @@ export class ReviewService {
       showAll: options.showAll ?? false,
       flush: options.flush ?? false,
       eventAction: options.eventAction,
+      localMode,
     };
   }
 
+  /**
+   * 解析本地代码审查模式
+   * - 显式指定 --local [mode] 时使用指定值
+   * - 显式指定 --no-local 时禁用
+   * - 非 CI、非 PR、无 base/head 时默认启用 uncommitted 模式
+   */
+  protected resolveLocalMode(
+    options: ReviewOptions,
+    env: { ci: boolean; hasPrNumber: boolean; hasBaseHead: boolean },
+  ): "uncommitted" | "staged" | false {
+    // 显式指定了 --no-local
+    if (options.local === false) {
+      return false;
+    }
+    // 显式指定了 --local [mode]
+    if (options.local === "staged" || options.local === "uncommitted") {
+      return options.local;
+    }
+    // CI 或 PR 模式下不启用本地模式
+    if (env.ci || env.hasPrNumber) {
+      return false;
+    }
+    // 指定了 base/head 时不启用本地模式
+    if (env.hasBaseHead) {
+      return false;
+    }
+    // 默认启用 uncommitted 模式
+    return "uncommitted";
+  }
+
   /**
    * 将文件路径规范化为相对于仓库根目录的路径
    * 支持绝对路径和相对路径输入
@@ -387,15 +432,24 @@ export class ReviewService {
       files,
       commits: filterCommits,
       deletionOnly,
+      localMode,
     } = context;
 
     // 直接审查文件模式：指定了 -f 文件且 base=head
     const isDirectFileMode = files && files.length > 0 && baseRef === headRef;
+    // 本地模式：审查未提交的代码（可能回退到分支比较）
+    let isLocalMode = !!localMode;
+    // 用于回退时动态计算的 base/head
+    let effectiveBaseRef = baseRef;
+    let effectiveHeadRef = headRef;
 
     if (shouldLog(verbose, 1)) {
       console.log(`🔍 Review 启动`);
       console.log(`   DRY-RUN mode: ${dryRun ? "enabled" : "disabled"}`);
       console.log(`   CI mode: ${ci ? "enabled" : "disabled"}`);
+      if (isLocalMode) {
+        console.log(`   Local mode: ${localMode}`);
+      }
       console.log(`   Verbose: ${verbose}`);
     }
 
@@ -415,6 +469,57 @@ export class ReviewService {
     let commits: PullRequestCommit[] = [];
     let changedFiles: ChangedFile[] = [];
 
+    if (isLocalMode) {
+      // 本地模式：从 git 获取未提交/暂存区的变更
+      if (shouldLog(verbose, 1)) {
+        console.log(`📥 本地模式: 获取${localMode === "staged" ? "暂存区" : "未提交"}的代码变更`);
+      }
+      const localFiles =
+        localMode === "staged" ? this.gitSdk.getStagedFiles() : this.gitSdk.getUncommittedFiles();
+
+      if (localFiles.length === 0) {
+        // 本地无变更，回退到分支比较模式
+        if (shouldLog(verbose, 1)) {
+          console.log(
+            `ℹ️  没有${localMode === "staged" ? "暂存区" : "未提交"}的代码变更，回退到分支比较模式`,
+          );
+        }
+        isLocalMode = false;
+        effectiveHeadRef = this.gitSdk.getCurrentBranch() ?? "HEAD";
+        effectiveBaseRef = this.gitSdk.getDefaultBranch();
+        if (shouldLog(verbose, 1)) {
+          console.log(`📌 自动检测分支: base=${effectiveBaseRef}, head=${effectiveHeadRef}`);
+        }
+        // 同分支无法比较，提前返回
+        if (effectiveBaseRef === effectiveHeadRef) {
+          console.log(`ℹ️  当前分支 ${effectiveHeadRef} 与默认分支相同，没有可审查的代码变更`);
+          return {
+            success: true,
+            description: "",
+            issues: [],
+            summary: [],
+            round: 1,
+          };
+        }
+      } else {
+        // 一次性获取所有 diff，避免每个文件调用一次 git 命令
+        const localDiffs =
+          localMode === "staged" ? this.gitSdk.getStagedDiff() : this.gitSdk.getUncommittedDiff();
+        const diffMap = new Map(localDiffs.map((d) => [d.filename, d.patch]));
+
+        changedFiles = localFiles.map((f) => ({
+          filename: f.filename,
+          status: f.status as ChangedFile["status"],
+          patch: diffMap.get(f.filename),
+        }));
+
+        if (shouldLog(verbose, 1)) {
+          console.log(`   Changed files: ${changedFiles.length}`);
+        }
+      }
+    }
+
+    // PR 模式、分支比较模式、或本地模式回退后的分支比较
     if (prNumber) {
       if (shouldLog(verbose, 1)) {
         console.log(`📥 获取 PR #${prNumber} 信息 (owner: ${owner}, repo: ${repo})`);
@@ -427,25 +532,34 @@ export class ReviewService {
         console.log(`   Commits: ${commits.length}`);
         console.log(`   Changed files: ${changedFiles.length}`);
       }
-    } else if (baseRef && headRef) {
+    } else if (effectiveBaseRef && effectiveHeadRef) {
       // 如果指定了 -f 文件且 base=head（无差异模式），直接审查指定文件
-      if (files && files.length > 0 && baseRef === headRef) {
+      if (files && files.length > 0 && effectiveBaseRef === effectiveHeadRef) {
         if (shouldLog(verbose, 1)) {
           console.log(`📥 直接审查指定文件模式 (${files.length} 个文件)`);
         }
         changedFiles = files.map((f) => ({ filename: f, status: "modified" as const }));
-      } else {
+      } else if (changedFiles.length === 0) {
+        // 仅当 changedFiles 为空时才获取（避免与回退逻辑重复）
         if (shouldLog(verbose, 1)) {
-          console.log(`📥 获取 ${baseRef}...${headRef} 的差异 (owner: ${owner}, repo: ${repo})`);
+          console.log(
+            `📥 获取 ${effectiveBaseRef}...${effectiveHeadRef} 的差异 (owner: ${owner}, repo: ${repo})`,
+          );
         }
-        changedFiles = await this.getChangedFilesBetweenRefs(owner, repo, baseRef, headRef);
-        commits = await this.getCommitsBetweenRefs(baseRef, headRef);
+        changedFiles = await this.getChangedFilesBetweenRefs(
+          owner,
+          repo,
+          effectiveBaseRef,
+          effectiveHeadRef,
+        );
+        commits = await this.getCommitsBetweenRefs(effectiveBaseRef, effectiveHeadRef);
         if (shouldLog(verbose, 1)) {
           console.log(`   Changed files: ${changedFiles.length}`);
           console.log(`   Commits: ${commits.length}`);
         }
       }
-    } else {
+    } else if (!isLocalMode) {
+      // 非本地模式且无有效的 base/head
       if (shouldLog(verbose, 1)) {
         console.log(`❌ 错误: 缺少 prNumber 或 baseRef/headRef`, { prNumber, baseRef, headRef });
       }
@@ -560,6 +674,7 @@ export class ReviewService {
       headSha,
       prNumber,
       verbose,
+      isLocalMode,
     );
     if (!llmMode) {
       throw new Error("必须指定 LLM 类型");
@@ -1130,9 +1245,10 @@ export class ReviewService {
     ref: string,
     prNumber?: number,
     verbose?: VerboseLevel,
+    isLocalMode?: boolean,
   ): Promise<FileContentsMap> {
     const contents: FileContentsMap = new Map();
-    const latestCommitHash = commits[commits.length - 1]?.sha?.slice(0, 7) || "-------";
+    const latestCommitHash = commits[commits.length - 1]?.sha?.slice(0, 7) || "+local+";
 
     // 优先使用 changedFiles 中的 patch 字段（来自 PR 的整体 diff base...head）
     // 这样行号是相对于最终文件的，而不是每个 commit 的父 commit
@@ -1145,7 +1261,10 @@ export class ReviewService {
       if (file.filename && file.status !== "deleted") {
         try {
           let rawContent: string;
-          if (prNumber) {
+          if (isLocalMode) {
+            // 本地模式：读取工作区文件的当前内容
+            rawContent = this.gitSdk.getWorkingFileContent(file.filename);
+          } else if (prNumber) {
             rawContent = await this.gitProvider.getFileContent(owner, repo, file.filename, ref);
           } else {
             rawContent = await this.gitSdk.getFileContent(ref, file.filename);