@spaceflow/review 0.77.0 → 0.79.0

package/src/review-llm.ts

@@ -7,7 +7,6 @@ import {
   createStreamLoggerState,
   shouldLog,
   type VerboseLevel,
-  type LlmJsonPutSchema,
   LlmJsonPut,
   parallel,
 } from "@spaceflow/core";
@@ -23,52 +22,19 @@ import { readdir } from "fs/promises";
 import { dirname, extname } from "path";
 import micromatch from "micromatch";
 import type { FileReviewPrompt, ReviewPrompt, LLMReviewOptions } from "./types/review-llm";
-import { buildLinesWithNumbers, buildCommitsSection } from "./utils/review-llm";
+import { buildLinesWithNumbers, buildCommitsSection, extractCodeBlocks } from "./utils/review-llm";
+import { extractCodeBlockTypes, extractGlobsFromIncludes } from "./review-includes-filter";
+import {
+  REVIEW_SCHEMA,
+  buildFileReviewPrompt,
+  buildPrDescriptionPrompt,
+  buildPrTitlePrompt,
+} from "./prompt";
+import type { SystemRules } from "./review.config";
+import { applyStaticRules } from "./system-rules";
 
 export type { FileReviewPrompt, ReviewPrompt, LLMReviewOptions } from "./types/review-llm";
 
-const REVIEW_SCHEMA: LlmJsonPutSchema = {
-  type: "object",
-  properties: {
-    issues: {
-      type: "array",
-      items: {
-        type: "object",
-        properties: {
-          file: { type: "string", description: "发生问题的文件路径" },
-          line: {
-            type: "string",
-            description:
-              "问题所在的行号，只支持单行或多行 (如 123 或 123-125)，不允许使用 `,` 分隔多个行号",
-          },
-          ruleId: { type: "string", description: "违反的规则 ID（如 JsTs.FileName.UpperCamel）" },
-          specFile: {
-            type: "string",
-            description: "规则来源的规范文件名（如 js&ts.file-name.md）",
-          },
-          reason: { type: "string", description: "问题的简要概括" },
-          suggestion: {
-            type: "string",
-            description:
-              "修改后的完整代码片段。要求以代码为主体，并在代码中使用详细的中文注释解释逻辑改进点。不要包含 Markdown 反引号。",
-          },
-          commit: { type: "string", description: "相关的 7 位 commit SHA" },
-          severity: {
-            type: "string",
-            description: "问题严重程度，根据规则文档中的 severity 标记确定",
-            enum: ["error", "warn"],
-          },
-        },
-        required: ["file", "line", "ruleId", "specFile", "reason"],
-        additionalProperties: false,
-      },
-    },
-    summary: { type: "string", description: "本次代码审查的整体总结" },
-  },
-  required: ["issues", "summary"],
-  additionalProperties: false,
-};
-
 export class ReviewLlmProcessor {
   readonly llmJsonPut: LlmJsonPut<ReviewResult>;
 
@@ -109,8 +75,11 @@ export class ReviewLlmProcessor {
       }
 
       // 如果有 includes 配置，检查文件名是否匹配 includes 模式
+      // 需先提取纯 glob（去掉 added|/modified| 前缀，过滤 code-* 空串），避免 micromatch 报错
       if (spec.includes.length > 0) {
-        return micromatch.isMatch(filename, spec.includes, { matchBase: true });
+        const globs = extractGlobsFromIncludes(spec.includes);
+        if (globs.length === 0) return true;
+        return micromatch.isMatch(filename, globs, { matchBase: true });
       }
 
       // 没有 includes 配置，扩展名匹配即可
@@ -118,122 +87,121 @@ export class ReviewLlmProcessor {
     });
   }
 
-  /**
-   * 构建 systemPrompt
-   */
-  buildSystemPrompt(specsSection: string): string {
-    return `你是一个专业的代码审查专家，负责根据团队的编码规范对代码进行严格审查。
-
-## 审查规范
-
-${specsSection}
-
-## 审查要求
-
-1. **严格遵循规范**：只按照上述审查规范进行审查，不要添加规范之外的要求
-2. **精准定位问题**：每个问题必须指明具体的行号，行号从文件内容中的 "行号|" 格式获取
-3. **避免重复报告**：如果提示词中包含"上一次审查结果"，请不要重复报告已存在的问题
-4. **提供可行建议**：对于每个问题，提供具体的修改建议代码
-
-## 注意事项
-
-- 变更文件内容已在上下文中提供，无需调用读取工具
-- 你可以读取项目中的其他文件以了解上下文
-- 不要调用编辑工具修改文件，你的职责是审查而非修改
-- 文件内容格式为 "CommitHash 行号| 代码"，输出的 line 字段应对应原始行号
-
-## 输出要求
-
-- 发现问题时：在 issues 数组中列出所有问题，每个问题包含 file、line、ruleId、specFile、reason、suggestion、severity
-- 无论是否发现问题：都必须在 summary 中提供该文件的审查总结，简要说明审查结果`;
-  }
-
   async buildReviewPrompt(
     specs: ReviewSpec[],
     changedFiles: ChangedFile[],
     fileContents: FileContentsMap,
     commits: PullRequestCommit[],
     existingResult?: ReviewResult | null,
+    whenModifiedCode?: string[],
+    verbose?: VerboseLevel,
+    systemRules?: SystemRules,
   ): Promise<ReviewPrompt> {
+    const round = (existingResult?.round ?? 0) + 1;
+    const { staticIssues, skippedFiles } = applyStaticRules(
+      changedFiles,
+      fileContents,
+      systemRules,
+      round,
+      verbose,
+    );
+
     const fileDataList = changedFiles
       .filter((f) => f.status !== "deleted" && f.filename)
       .map((file) => {
         const filename = file.filename!;
+        if (skippedFiles.has(filename)) return null;
         const contentLines = fileContents.get(filename);
         if (!contentLines) {
-          return {
-            filename,
-            file,
-            linesWithNumbers: "(无法获取内容)",
-            commitsSection: "- 无相关 commits",
-          };
+          return { filename, file, contentLines: null, commitsSection: "- 无相关 commits" };
         }
-        const linesWithNumbers = buildLinesWithNumbers(contentLines);
         const commitsSection = buildCommitsSection(contentLines, commits);
-        return { filename, file, linesWithNumbers, commitsSection };
+        return { filename, file, contentLines, commitsSection };
       });
 
-    const filePrompts: FileReviewPrompt[] = await Promise.all(
-      fileDataList.map(async ({ filename, file, linesWithNumbers, commitsSection }) => {
-        const fileDirectoryInfo = await this.getFileDirectoryInfo(filename);
-
-        // 获取该文件上一次的审查结果
-        const existingFileSummary = existingResult?.summary?.find((s) => s.file === filename);
-        const existingFileIssues = existingResult?.issues?.filter((i) => i.file === filename) ?? [];
-
-        let previousReviewSection = "";
-        if (existingFileSummary || existingFileIssues.length > 0) {
-          const parts: string[] = [];
-          if (existingFileSummary?.summary) {
-            parts.push(`**总结**:\n`);
-            parts.push(`${existingFileSummary.summary}\n`);
-          }
-          if (existingFileIssues.length > 0) {
-            parts.push(`**已发现的问题** (${existingFileIssues.length} 个):\n`);
-            for (const issue of existingFileIssues) {
-              const status = issue.fixed
-                ? "✅ 已修复"
-                : issue.valid === "false"
-                  ? "❌ 无效"
-                  : "⚠️ 待处理";
-              parts.push(`- [${status}] 行 ${issue.line}: ${issue.reason} (规则: ${issue.ruleId})`);
+    const filePrompts: (FileReviewPrompt | null)[] = await Promise.all(
+      fileDataList
+        .filter((item): item is NonNullable<typeof item> => item !== null)
+        .map(async ({ filename, file, contentLines, commitsSection }) => {
+          const fileDirectoryInfo = await this.getFileDirectoryInfo(filename);
+
+          // 根据文件过滤 specs，只注入与当前文件匹配的规则
+          const fileSpecs = this.filterSpecsForFile(specs, filename);
+
+          // 从全局 whenModifiedCode 配置中解析代码结构过滤类型
+          const codeBlockTypes = whenModifiedCode ? extractCodeBlockTypes(whenModifiedCode) : [];
+
+          // 构建带行号的内容：有 code-* 过滤时只输出匹配的代码块范围
+          let linesWithNumbers: string;
+          if (!contentLines) {
+            linesWithNumbers = "(无法获取内容)";
+          } else if (codeBlockTypes.length > 0) {
+            const visibleRanges = extractCodeBlocks(contentLines, codeBlockTypes);
+            // 如果配置了 whenModifiedCode 但没有匹配的代码块，跳过这个文件
+            if (visibleRanges.length === 0) {
+              if (shouldLog(verbose, 2)) {
+                console.log(
+                  `[buildReviewPrompt] ${filename}: 没有匹配的 ${codeBlockTypes.join(", ")} 代码块，跳过审查`,
+                );
+              }
+              return null;
             }
-            parts.push("");
-            // parts.push("请注意：不要重复报告上述已发现的问题，除非代码有新的变更导致问题复现。\n");
+            linesWithNumbers = buildLinesWithNumbers(contentLines, visibleRanges);
+          } else {
+            linesWithNumbers = buildLinesWithNumbers(contentLines);
           }
-          previousReviewSection = parts.join("\n");
-        }
 
-        const userPrompt = `## ${filename} (${file.status})
-
-### 文件内容
-
-\`\`\`
-${linesWithNumbers}
-\`\`\`
-
-### 该文件的相关 Commits
-
-${commitsSection}
-
-### 该文件所在的目录树
-
-${fileDirectoryInfo}
-
-### 上一次审查结果
-
-${previousReviewSection}`;
-
-        // 根据文件过滤 specs，只注入与当前文件匹配的规则
-        const fileSpecs = this.filterSpecsForFile(specs, filename);
-        const specsSection = this.reviewSpecService.buildSpecsSection(fileSpecs);
-        const systemPrompt = this.buildSystemPrompt(specsSection);
+          // 获取该文件上一次的审查结果
+          const existingFileSummary = existingResult?.summary?.find((s) => s.file === filename);
+          const existingFileIssues =
+            existingResult?.issues?.filter((i) => i.file === filename) ?? [];
+
+          let previousReviewSection = "";
+          if (existingFileSummary || existingFileIssues.length > 0) {
+            const parts: string[] = [];
+            if (existingFileSummary?.summary) {
+              parts.push(`**总结**:\n`);
+              parts.push(`${existingFileSummary.summary}\n`);
+            }
+            if (existingFileIssues.length > 0) {
+              parts.push(`**已发现的问题** (${existingFileIssues.length} 个):\n`);
+              for (const issue of existingFileIssues) {
+                const status = issue.fixed
+                  ? "✅ 已修复"
+                  : issue.valid === "false"
+                    ? "❌ 无效"
+                    : "⚠️ 待处理";
+                parts.push(
+                  `- [${status}] 行 ${issue.line}: ${issue.reason} (规则: ${issue.ruleId})`,
+                );
+              }
+              parts.push("");
+              // parts.push("请注意：不要重复报告上述已发现的问题，除非代码有新的变更导致问题复现。\n");
+            }
+            previousReviewSection = parts.join("\n");
+          }
 
-        return { filename, systemPrompt, userPrompt };
-      }),
+          const specsSection = this.reviewSpecService.buildSpecsSection(fileSpecs);
+          const { systemPrompt, userPrompt } = buildFileReviewPrompt({
+            filename,
+            status: file.status,
+            linesWithNumbers,
+            commitsSection,
+            fileDirectoryInfo,
+            previousReviewSection,
+            specsSection,
+          });
+
+          return { filename, systemPrompt, userPrompt };
+        }),
     );
 
-    return { filePrompts };
+    // 过滤掉 null 值（跳过的文件）
+    const validFilePrompts = filePrompts.filter((fp): fp is FileReviewPrompt => fp !== null);
+    return {
+      filePrompts: validFilePrompts,
+      staticIssues: staticIssues.length > 0 ? staticIssues : undefined,
+    };
   }
 
   async runLLMReview(
@@ -475,54 +443,14 @@ ${previousReviewSection}`;
     fileContents?: FileContentsMap,
     verbose?: VerboseLevel,
   ): Promise<{ title: string; description: string }> {
-    const commitMessages = commits
-      .map((c) => `- ${c.sha?.slice(0, 7)}: ${c.commit?.message?.split("\n")[0]}`)
-      .join("\n");
-    const fileChanges = changedFiles
-      .slice(0, 30)
-      .map((f) => `- ${f.filename} (${f.status})`)
-      .join("\n");
-    // 构建代码变更内容（只包含变更行，限制总长度）
-    let codeChangesSection = "";
-    if (fileContents && fileContents.size > 0) {
-      const codeSnippets: string[] = [];
-      let totalLength = 0;
-      const maxTotalLength = 8000; // 限制代码总长度
-      for (const [filename, lines] of fileContents) {
-        if (totalLength >= maxTotalLength) break;
-        // 只提取有变更的行（commitHash 不是 "-------"）
-        const changedLines = lines
-          .map(([hash, code], idx) => (hash !== "-------" ? `${idx + 1}: ${code}` : null))
-          .filter(Boolean);
-        if (changedLines.length > 0) {
-          const snippet = `### ${filename}\n\`\`\`\n${changedLines.slice(0, 50).join("\n")}\n\`\`\``;
-          if (totalLength + snippet.length <= maxTotalLength) {
-            codeSnippets.push(snippet);
-            totalLength += snippet.length;
-          }
-        }
-      }
-      if (codeSnippets.length > 0) {
-        codeChangesSection = `\n\n## 代码变更内容\n${codeSnippets.join("\n\n")}`;
-      }
-    }
-    const prompt = `请根据以下 PR 的 commit 记录、文件变更和代码内容，用简洁的中文总结这个 PR 实现了什么功能。
-要求：
-1. 第一行输出 PR 标题，格式必须是: Feat xxx 或 Fix xxx 或 Refactor xxx（根据变更类型选择，整体不超过 50 个字符）
-2. 空一行后输出详细描述
-3. 描述应该简明扼要，突出核心功能点
-4. 使用 Markdown 格式
-5. 不要逐条列出 commit，而是归纳总结
-6. 重点分析代码变更的实际功能
-
-## Commit 记录 (${commits.length} 个)
-${commitMessages || "无"}
-
-## 文件变更 (${changedFiles.length} 个文件)
-${fileChanges || "无"}
-${changedFiles.length > 30 ? `\n... 等 ${changedFiles.length - 30} 个文件` : ""}${codeChangesSection}`;
+    const { userPrompt } = buildPrDescriptionPrompt({
+      commits,
+      changedFiles,
+      fileContents,
+    });
+
     try {
-      const stream = this.llmProxyService.chatStream([{ role: "user", content: prompt }], {
+      const stream = this.llmProxyService.chatStream([{ role: "user", content: userPrompt }], {
         adapter: llmMode,
       });
       let content = "";
@@ -553,29 +481,10 @@ ${changedFiles.length > 30 ? `\n... 等 ${changedFiles.length - 30} 个文件` :
     commits: PullRequestCommit[],
     changedFiles: ChangedFile[],
   ): Promise<string> {
-    const commitMessages = commits
-      .slice(0, 10)
-      .map((c) => c.commit?.message?.split("\n")[0])
-      .filter(Boolean)
-      .join("\n");
-    const fileChanges = changedFiles
-      .slice(0, 20)
-      .map((f) => `${f.filename} (${f.status})`)
-      .join("\n");
-    const prompt = `请根据以下 commit 记录和文件变更，生成一个简短的 PR 标题。
-要求：
-1. 格式必须是: Feat: xxx 或 Fix: xxx 或 Refactor: xxx
-2. 根据变更内容选择合适的前缀（新功能用 Feat，修复用 Fix，重构用 Refactor）
-3. xxx 部分用简短的中文描述（整体不超过 50 个字符）
-4. 只输出标题，不要加任何解释
-
-Commit 记录:
-${commitMessages || "无"}
-
-文件变更:
-${fileChanges || "无"}`;
+    const { userPrompt } = buildPrTitlePrompt({ commits, changedFiles });
+
     try {
-      const stream = this.llmProxyService.chatStream([{ role: "user", content: prompt }], {
+      const stream = this.llmProxyService.chatStream([{ role: "user", content: userPrompt }], {
         adapter: "openai",
       });
       let title = "";

package/src/review-result-model.ts

@@ -19,7 +19,7 @@ import {
   calculateIssueStats,
   REVIEW_COMMENT_MARKER,
   REVIEW_LINE_COMMENTS_MARKER,
-} from "./review-pr-comment-utils";
+} from "./utils/review-pr-comment";
 
 export interface ReviewResultSaveOptions {
   verbose?: VerboseLevel;
@@ -325,11 +325,33 @@ export class ReviewResultModel {
       // 遍历每个评论，获取其 reactions
       for (const comment of reviewComments) {
         if (!comment.id) continue;
-        // 找到对应的 issue
-        const matchedIssue = this._result.issues.find(
-          (issue) =>
-            issue.file === comment.path && this.lineMatchesPosition(issue.line, comment.position),
-        );
+        // 找到对应的 issue：优先通过 issue-key 精确匹配，回退到 path+line 匹配
+        let matchedIssue: ReviewIssue | undefined;
+        if (comment.body) {
+          const issueKey = extractIssueKeyFromBody(comment.body);
+          if (issueKey) {
+            matchedIssue = this._result.issues.find(
+              (issue) => generateIssueKey(issue) === issueKey,
+            );
+            if (shouldLog(verbose, 3)) {
+              console.log(
+                `[syncReactionsToIssues] comment ${comment.id}: issue-key=${issueKey}, matched=${matchedIssue ? "yes" : "no"}`,
+              );
+            }
+          }
+        }
+        // 如果 issue-key 匹配失败，使用 path+position 回退匹配
+        if (!matchedIssue) {
+          matchedIssue = this._result.issues.find(
+            (issue) =>
+              issue.file === comment.path && this.lineMatchesPosition(issue.line, comment.position),
+          );
+          if (shouldLog(verbose, 3)) {
+            console.log(
+              `[syncReactionsToIssues] comment ${comment.id}: fallback matching path=${comment.path}, position=${comment.position}, matched=${matchedIssue ? "yes" : "no"}`,
+            );
+          }
+        }
         if (matchedIssue) {
           commentIdToIssue.set(comment.id, matchedIssue);
         }

package/src/review-spec/review-spec.service.ts

@@ -13,6 +13,7 @@ import { homedir } from "os";
 import { execSync } from "child_process";
 import micromatch from "micromatch";
 import { ReviewSpec, ReviewRule, RuleExample, Severity } from "./types";
+import { extractGlobsFromIncludes } from "../review-includes-filter";
 
 /** 远程规则缓存 TTL（毫秒），默认 5 分钟 */
 const REMOTE_SPEC_CACHE_TTL = 5 * 60 * 1000;
@@ -69,7 +70,23 @@ export class ReviewSpecService {
       }
     }
 
-    return specs.filter((spec) => spec.extensions.some((ext) => changedExtensions.has(ext)));
+    console.log(
+      `[filterApplicableSpecs] changedExtensions=${JSON.stringify([...changedExtensions])}, specs count=${specs.length}`,
+    );
+    const result = specs.filter((spec) => {
+      const matches = spec.extensions.some((ext) => changedExtensions.has(ext));
+      if (!matches) {
+        console.log(
+          `[filterApplicableSpecs] spec ${spec.filename} (ext: ${JSON.stringify(spec.extensions)}) NOT matched`,
+        );
+      } else {
+        console.log(
+          `[filterApplicableSpecs] spec ${spec.filename} (ext: ${JSON.stringify(spec.extensions)}) MATCHED`,
+        );
+      }
+      return matches;
+    });
+    return result;
   }
 
   async loadReviewSpecs(specDir: string): Promise<ReviewSpec[]> {
@@ -524,8 +541,10 @@ export class ReviewSpecService {
         return true;
       }
 
-      // 检查文件是否匹配 includes 模式
-      const matches = micromatch.isMatch(issue.file, includes, { matchBase: true });
+      // 检查文件是否匹配 includes 模式（转换为纯 glob，避免 status| 前缀和 code-* 空串传入 micromatch）
+      const globs = extractGlobsFromIncludes(includes);
+      if (globs.length === 0) return true;
+      const matches = micromatch.isMatch(issue.file, globs, { matchBase: true });
       if (!matches) {
         // console.log(`   Issue [${issue.ruleId}] 在文件 ${issue.file} 不匹配 includes 模式，跳过`);
       }
@@ -638,8 +657,10 @@ export class ReviewSpecService {
         if (scoped.includes.length === 0) {
           return true;
         }
-        // 使用 micromatch 检查文件是否匹配 includes 模式
-        return issueFile && micromatch.isMatch(issueFile, scoped.includes, { matchBase: true });
+        // 使用 micromatch 检查文件是否匹配 includes 模式（转换为纯 glob）
+        const globs = extractGlobsFromIncludes(scoped.includes);
+        if (globs.length === 0) return true;
+        return issueFile && micromatch.isMatch(issueFile, globs, { matchBase: true });
       });
 
       if (matched) {

package/src/review.config.ts

@@ -27,6 +27,15 @@ export type AnalyzeDeletionsMode = z.infer<typeof analyzeDeletionsModeSchema>;
 /** 审查规则严重级别 */
 export type Severity = z.infer<typeof severitySchema>;
 
+/**
+ * 系统规则配置，不依赖 LLM，在构建 prompt 前直接检查并生成系统问题。
+ * 格式为 [阈值, severity]
+ */
+export interface SystemRules {
+  /** 单文件最大审查行数，超过时跳过 LLM 并生成系统问题。格式: [maxLine, severity] */
+  maxLinesPerFile?: [number, Severity];
+}
+
 /**
  * 变更文件处理策略
  * - 'invalidate': 将变更文件的历史问题标记为无效（默认）
@@ -47,6 +56,11 @@ export interface ReviewOptions {
   references?: string[];
   verbose?: VerboseLevel;
   includes?: string[];
+  /**
+   * 代码结构过滤配置，指定在代码审查时要关注的代码结构类型
+   * 支持格式："function"、"class"、"interface"、"type"、"method"
+   */
+  whenModifiedCode?: string[];
   llmMode?: LLMMode;
   files?: string[];
   commits?: string[];
@@ -80,11 +94,12 @@ export interface ReviewOptions {
    */
   local?: LocalReviewMode;
   /**
-   * 跳过重复的 review workflow 检查
-   * - true: 启用检查，当检测到同名 workflow 正在运行时跳过审查
-   * - false: 禁用检查（默认）
+   * 处理重复 workflow 的策略
+   * - 'off': 禁用检查
+   * - 'skip': 检测到同名 workflow 正在运行时跳过审查
+   * - 'delete': 检测到同名 workflow 时删除旧的 AI Review 评论和 PR Review（默认）
    */
-  skipDuplicateWorkflow?: boolean;
+  duplicateWorkflowResolved?: "off" | "skip" | "delete";
   /**
    * 自动批准合并
    * - true: 当所有问题都已解决时，自动提交 APPROVE review
@@ -99,6 +114,8 @@ export interface ReviewOptions {
    * - 'warn+error': 有未解决的 warn 或 error 级别问题时抛出异常
    */
   failOnIssues?: "off" | "warn" | "error" | "warn+error";
+  /** 系统规则配置，不依赖 LLM，直接在检查阶段生成系统问题 */
+  systemRules?: SystemRules;
 }
 
 /** review 命令配置 schema（LLM 敏感配置由系统 llm.config.ts 管理） */
@@ -107,6 +124,7 @@ export const reviewSchema = () =>
     references: z.array(z.string()).optional(),
     llmMode: llmModeSchema.default("openai").optional(),
     includes: z.array(z.string()).optional(),
+    whenModifiedCode: z.array(z.string()).optional(),
     rules: z.record(z.string(), severitySchema).optional(),
     verifyFixes: z.boolean().default(false),
     verifyFixesConcurrency: z.number().default(10).optional(),
@@ -120,9 +138,17 @@ export const reviewSchema = () =>
     retries: z.number().default(0).optional(),
     retryDelay: z.number().default(1000).optional(),
     invalidateChangedFiles: invalidateChangedFilesSchema.default("invalidate").optional(),
-    skipDuplicateWorkflow: z.boolean().default(false).optional(),
+    duplicateWorkflowResolved: z.enum(["off", "skip", "delete"]).default("delete").optional(),
     autoApprove: z.boolean().default(false).optional(),
     failOnIssues: z.enum(["off", "warn", "error", "warn+error"]).default("off").optional(),
+    systemRules: z
+      .object({
+        maxLinesPerFile: z
+          .tuple([z.number(), severitySchema])
+          .transform((v): [number, Severity] => [v[0], v[1]])
+          .optional(),
+      })
+      .optional(),
   });
 
 /** review 配置类型（从 schema 推导） */