autosnippet 3.2.3 → 3.2.6

package/lib/external/mcp/handlers/bootstrap/pipeline/orchestrator.js

@@ -21,16 +21,15 @@ import { AnalystAgent } from '../../../../../service/chat/AnalystAgent.js';
 import { EpisodicConsolidator } from '../../../../../service/chat/EpisodicConsolidator.js';
 import { ProducerAgent } from '../../../../../service/chat/ProducerAgent.js';
 import { ProjectSemanticMemory } from '../../../../../service/chat/ProjectSemanticMemory.js';
-import { WorkingMemory } from '../../../../../service/chat/WorkingMemory.js';
+import { MemoryCoordinator } from '../../../../../service/chat/memory/MemoryCoordinator.js';
+import { SessionStore } from '../../../../../service/chat/memory/SessionStore.js';
 import { clearCheckpoints, loadCheckpoints, saveDimensionCheckpoint } from './checkpoint.js';
 import { buildTierReflection, DIMENSION_CONFIGS_V3, getFullDimensionConfig } from './dimension-configs.js';
 import { getDimensionFocusKeywords } from '../shared/dimension-sop.js';
 import { DimensionContext, parseDimensionDigest } from './dimension-context.js';
-import { EpisodicMemory } from './EpisodicMemory.js';
 import { IncrementalBootstrap } from './IncrementalBootstrap.js';
-import { runNoAiFallback } from './noAiFallback.js';
-import { ToolResultCache } from './ToolResultCache.js';
 import { TierScheduler } from './tier-scheduler.js';
+import { runNoAiFallback } from './noAiFallback.js';
 import { generateSkill } from '../shared/skill-generator.js';
 import { BootstrapEventEmitter } from '../../../../../shared/BootstrapEventEmitter.js';
 
@@ -283,25 +282,25 @@ export async function fillDimensionsV3(fillContext) {
     guardSummary: guardAudit?.summary || null,
   });
 
-  // v4.0: EpisodicMemory — 替代 DimensionContext 提供更丰富的跨维度上下文
+  // v4.0: SessionStore — 替代 EpisodicMemory + ToolResultCache
   // v5.0: 增量模式下从快照恢复已完成维度的记忆
-  let episodicMemory;
+  let sessionStore;
   if (isIncremental && incrementalPlan.restoredEpisodic) {
-    episodicMemory = incrementalPlan.restoredEpisodic;
-    const restoredDims = episodicMemory.getCompletedDimensions();
+    sessionStore = incrementalPlan.restoredEpisodic;
+    const restoredDims = sessionStore.getCompletedDimensions();
     logger.info(
-      `[Bootstrap-v3] Restored EpisodicMemory: ${restoredDims.length} dims [${restoredDims.join(', ')}]`
+      `[Bootstrap-v3] Restored SessionStore: ${restoredDims.length} dims [${restoredDims.join(', ')}]`
     );
 
     // 同步恢复 DimensionContext 的 digests (兼容)
     for (const dimId of restoredDims) {
-      const report = episodicMemory.getDimensionReport(dimId);
+      const report = sessionStore.getDimensionReport(dimId);
       if (report?.digest) {
         dimContext.addDimensionDigest(dimId, report.digest);
       }
     }
   } else {
-    episodicMemory = new EpisodicMemory({
+    sessionStore = new SessionStore({
       projectName: projectInfo.name,
       primaryLang: projectInfo.lang,
       fileCount: projectInfo.fileCount,
@@ -309,9 +308,6 @@ export async function fillDimensionsV3(fillContext) {
     });
   }
 
-  // v4.0: ToolResultCache — 跨维度工具结果缓存 (search/read 去重)
-  const toolResultCache = new ToolResultCache();
-
   // v4.1: ProjectSemanticMemory — 项目级永久语义记忆 (Tier 3)
   // 加载历史 bootstrap 记忆 → 注入 AnalystAgent prompt
   let semanticMemory = null;
@@ -349,6 +345,13 @@ export async function fillDimensionsV3(fillContext) {
     logger.warn(`[Bootstrap-v3] CodeEntityGraph init failed (non-blocking): ${cegErr.message}`);
   }
 
+  // v5.0: MemoryCoordinator — 统一记忆协调器 (会话级)
+  const memoryCoordinator = new MemoryCoordinator({
+    persistentMemory: semanticMemory,
+    sessionStore,
+    mode: 'bootstrap',
+  });
+
   // ═══════════════════════════════════════════════════════════
   // Step 2: 按维度分层执行 (Analyst → Gate → Producer)
   // ═══════════════════════════════════════════════════════════
@@ -393,8 +396,8 @@ export async function fillDimensionsV3(fillContext) {
       // 恢复 DimensionContext 中的 digest
       if (checkpoint.digest) {
         dimContext.addDimensionDigest(dimId, checkpoint.digest);
-        // v4.0: 同步恢复到 EpisodicMemory
-        episodicMemory.addDimensionDigest(dimId, checkpoint.digest);
+        // v4.0: 同步恢复到 SessionStore
+        sessionStore.addDimensionDigest(dimId, checkpoint.digest);
       }
       emitter.emitDimensionComplete(dimId, {
         type: 'checkpoint-restored',
@@ -415,7 +418,7 @@ export async function fillDimensionsV3(fillContext) {
   async function executeDimension(dimId) {
     // v5.0: 增量模式 — 跳过未受影响的维度 (使用历史 EpisodicMemory)
     if (incrementalSkippedDims.includes(dimId)) {
-      const report = episodicMemory.getDimensionReport(dimId);
+      const report = sessionStore.getDimensionReport(dimId);
       const dimResult = {
         candidateCount: report?.candidatesSummary?.length || 0,
         rejectedCount: 0,
@@ -462,7 +465,7 @@ export async function fillDimensionsV3(fillContext) {
           },
           producerResult: { candidateCount: cp.candidateCount || 0, toolCalls: [] },
         };
-        episodicMemory.storeDimensionReport(dimId, {
+        sessionStore.storeDimensionReport(dimId, {
           analysisText: cp.analysisText,
           findings: [],
           referencedFiles: restoredFiles,
@@ -528,18 +531,17 @@ export async function fillDimensionsV3(fillContext) {
     const dimStartTime = Date.now();
 
     try {
-      // v4.0: 为每个维度创建独立的 WorkingMemory
-      const dimWorkingMemory = new WorkingMemory({ maxRecentRounds: 3 });
+      // v5.0: 为每个维度创建独立的 ActiveContext 作用域
+      const analystScopeId = `${dimId}:analyst`;
+      memoryCoordinator.createDimensionScope(analystScopeId);
 
       // ── Phase 1: Analyst ──
       const analysisReport = await Promise.race([
         analystAgent.analyze(dimConfig, projectInfo, {
           sessionId,
           dimensionContext: dimContext,
-          // v4.0: Agent Memory 注入
-          episodicMemory,
-          workingMemory: dimWorkingMemory,
-          toolResultCache,
+          // v5.0: 统一 MemoryCoordinator
+          memoryCoordinator,
           // v4.1: Semantic Memory (历史 bootstrap 记忆)
           semanticMemory,
           // Phase E: Code Entity Graph 代码实体图谱
@@ -550,9 +552,10 @@ export async function fillDimensionsV3(fillContext) {
         ),
       ]);
 
-      // v4.0: 蒸馏 Working → Episodic
-      const distilled = dimWorkingMemory.distill();
-      episodicMemory.storeDimensionReport(dimId, {
+      // v5.0: 通过 coordinator 蒸馏 ActiveContext → SessionStore
+      const ac = memoryCoordinator.getActiveContext(analystScopeId);
+      const distilled = ac ? ac.distill() : { keyFindings: [], totalObservations: 0, toolCallSummary: [] };
+      sessionStore.storeDimensionReport(dimId, {
         analysisText: analysisReport.analysisText,
         findings: analysisReport.findings || distilled.keyFindings,
         referencedFiles: analysisReport.referencedFiles || [],
@@ -593,8 +596,15 @@ export async function fillDimensionsV3(fillContext) {
 
       if (needsCandidates && analysisReport.analysisText.length >= 100) {
         try {
+          // v5.0: 为 Producer 创建独立作用域
+          const producerScopeId = `${dimId}:producer`;
+          memoryCoordinator.createDimensionScope(producerScopeId);
+
           producerResult = await Promise.race([
-            producerAgent.produce(analysisReport, dimConfig, projectInfo, { sessionId }),
+            producerAgent.produce(analysisReport, dimConfig, projectInfo, {
+              sessionId,
+              memoryCoordinator,
+            }),
             new Promise((_, reject) =>
               setTimeout(() => reject(new Error(`Producer timeout for "${dimId}"`)), 180_000)
             ),
@@ -624,8 +634,8 @@ export async function fillDimensionsV3(fillContext) {
       };
       dimContext.addDimensionDigest(dimId, digest);
 
-      // v4.0: 同步 digest 到 EpisodicMemory
-      episodicMemory.addDimensionDigest(dimId, digest);
+      // v4.0: 同步 digest 到 SessionStore
+      sessionStore.addDimensionDigest(dimId, digest);
 
       // 记录到 DimensionContext + EpisodicMemory
       for (const tc of producerResult.toolCalls || []) {
@@ -637,8 +647,8 @@ export async function fillDimensionsV3(fillContext) {
             summary: tc.params?.summary || '',
           };
           dimContext.addSubmittedCandidate(dimId, candidateSummary);
-          // v4.0: 同步到 EpisodicMemory
-          episodicMemory.addSubmittedCandidate(dimId, candidateSummary);
+          // v4.0: 同步到 SessionStore
+          sessionStore.addSubmittedCandidate(dimId, candidateSummary);
         }
       }
 
@@ -718,8 +728,8 @@ export async function fillDimensionsV3(fillContext) {
 
         // v4.0: Tier 级 Reflection — 综合本 Tier 所有维度的发现
         try {
-          const reflection = buildTierReflection(tierIndex, tierResults, episodicMemory);
-          episodicMemory.addTierReflection(tierIndex, reflection);
+          const reflection = buildTierReflection(tierIndex, tierResults, sessionStore);
+          sessionStore.addTierReflection(tierIndex, reflection);
           logger.info(
             `[Bootstrap-v3] Tier ${tierIndex + 1} reflection: ` +
               `${reflection.topFindings.length} top findings, ` +
@@ -734,18 +744,19 @@ export async function fillDimensionsV3(fillContext) {
     logger.info(
       `[Bootstrap-v3] All tiers complete: ${results.size} dimensions in ${Date.now() - t0}ms`
     );
-    // v4.0: 记录 EpisodicMemory 统计 + ToolResultCache 效率
-    const emStats = episodicMemory.getStats();
-    const cacheStats = toolResultCache.getStats();
+    // v4.0: 记录 SessionStore 统计
+    const emStats = sessionStore.getStats();
     logger.info(
       `[Bootstrap-v3] Memory stats: ${emStats.completedDimensions} dims, ` +
         `${emStats.totalFindings} findings, ${emStats.referencedFiles} files, ` +
         `${emStats.crossReferences} cross-refs, ${emStats.tierReflections} reflections`
     );
-    logger.info(
-      `[Bootstrap-v3] Cache stats: ${cacheStats.hitRate} hit rate, ` +
-        `${cacheStats.searchCacheSize} searches, ${cacheStats.fileCacheSize} files`
-    );
+    if (emStats.cacheStats) {
+      logger.info(
+        `[Bootstrap-v3] Cache stats: ${emStats.cacheStats.hitRate} hit rate, ` +
+          `${emStats.cacheStats.searchCacheSize} searches, ${emStats.cacheStats.fileCacheSize} files`
+      );
+    }
   } else {
     // 串行: 按 TierScheduler 内部顺序逐个执行
     for (const tier of scheduler.getTiers()) {
@@ -787,8 +798,42 @@ export async function fillDimensionsV3(fillContext) {
         const analysisText = dimData.analysisReport.analysisText;
         const referencedFiles = dimData.analysisReport.referencedFiles || [];
 
+        // 从 SessionStore 获取结构化发现，供 Skill 生成使用
+        const dimReport = sessionStore.getDimensionReport(dim.id);
+        const keyFindings = (dimReport?.findings || [])
+          .sort((a, b) => (b.importance || 5) - (a.importance || 5))
+          .slice(0, 10)
+          .map((f) => f.finding);
+
+        // 当 analysisText 过短（如 force-exit 时 AI 仅输出 JSON digest 被清洗后）
+        // 从 distilled findings 合成补充文本，避免 Skill 质量门控拦截
+        let effectiveText = analysisText;
+        if (analysisText.trim().length < 100 && keyFindings.length > 0) {
+          const distilled = dimReport?.workingMemoryDistilled;
+          const synthesized = [
+            `## ${dim.label || dim.id}`,
+            '',
+            analysisText.trim(),
+            '',
+            '## 关键发现',
+            '',
+            ...keyFindings.map((f, i) => `${i + 1}. ${f}`),
+          ];
+          if (distilled?.toolCallSummary?.length > 0) {
+            synthesized.push('', '## 探索记录', '');
+            for (const s of distilled.toolCallSummary.slice(0, 10)) {
+              synthesized.push(`- ${s}`);
+            }
+          }
+          effectiveText = synthesized.join('\n');
+          logger.info(
+            `[Bootstrap-v3] Skill "${dim.id}": analysisText too short (${analysisText.trim().length} chars), ` +
+            `synthesized from ${keyFindings.length} findings → ${effectiveText.length} chars`
+          );
+        }
+
         const result = await generateSkill(
-          ctx, dim, analysisText, referencedFiles, [], 'bootstrap-v3'
+          ctx, dim, effectiveText, referencedFiles, keyFindings, 'bootstrap-v3'
         );
 
         if (result.success) {
@@ -870,7 +915,7 @@ export async function fillDimensionsV3(fillContext) {
       const semanticMemory = new ProjectSemanticMemory(db, { logger });
       const consolidator = new EpisodicConsolidator(semanticMemory, { logger });
 
-      consolidationResult = consolidator.consolidate(episodicMemory, {
+      consolidationResult = consolidator.consolidate(sessionStore, {
         bootstrapSession: sessionId,
         clearPrevious: true, // 全量冷启动: 先清除旧的 bootstrap 记忆
       });
@@ -1042,7 +1087,7 @@ export async function fillDimensionsV3(fillContext) {
         sessionId,
         allFiles,
         dimensionStats,
-        episodicMemory,
+        episodicMemory: sessionStore,
         meta: {
           durationMs: totalTimeMs,
           candidateCount: candidateResults.created,

package/lib/external/mcp/handlers/consolidated.js

@@ -127,23 +127,22 @@ export async function consolidatedGraph(ctx, args) {
   }
 }
 
-// ─── autosnippet_guard (整合 2 → 1) ─────────────────────────
+// ─── autosnippet_guard (整合 3 → 1) ─────────────────────────
 
 /**
  * Guard 检查：按参数自动路由
- *   有 code  → guardCheck()   (单文件)
- *   有 files → guardAuditFiles() (多文件)
+ *   无参数       → guardReview()    (自动 git diff 检测 + inline recipe)
+ *   有 files     → guardReview()    (指定文件 + inline recipe) — files 为 string[] 或 {path}[]
+ *   有 code      → guardCheck()     (单文件内联检查)
  */
 export async function consolidatedGuard(ctx, args) {
-  if (args.files && Array.isArray(args.files) && args.files.length > 0) {
-    return guardHandlers.guardAuditFiles(ctx, args);
-  }
+  // 有 code → 单文件检查（旧模式）
   if (args.code) {
     return guardHandlers.guardCheck(ctx, args);
   }
-  throw new Error(
-    'autosnippet_guard requires either "code" (single check) or "files" (batch audit) parameter'
-  );
+  // 有 files（string[] 或 {path}[]）或无参数 → review 模式
+  // review 模式内部处理 files 参数和自动检测
+  return guardHandlers.guardReview(ctx, args);
 }
 
 // ─── autosnippet_skill (整合 6 → 1) ─────────────────────────

package/lib/external/mcp/handlers/dimension-complete-external.js

@@ -336,11 +336,11 @@ export async function dimensionComplete(ctx, args) {
       try {
         const { EpisodicConsolidator } = await import('../../../service/chat/EpisodicConsolidator.js');
         const db = ctx.container.get?.('database') ?? ctx.container.get?.('db');
-        if (db && session.episodicMemory) {
+        if (db && session.sessionStore) {
           const { ProjectSemanticMemory } = await import('../../../service/chat/ProjectSemanticMemory.js');
           const semanticMemory = new ProjectSemanticMemory(db, { logger });
           const consolidator = new EpisodicConsolidator(semanticMemory, { logger });
-          const result = await consolidator.consolidate(session.episodicMemory, {
+          const result = await consolidator.consolidate(session.sessionStore, {
             bootstrapSession: session.id,
             clearPrevious: true,
           });
@@ -409,12 +409,12 @@ export async function dimensionComplete(ctx, args) {
         titles: s.titles,
         referencedFiles: s.referencedFiles,
       })),
-      // v3: 从 EpisodicMemory 提取前序维度分析摘要 + 关键发现（对标内部 Agent 的 buildContextForDimension）
+      // v3: 从 SessionStore 提取前序维度分析摘要 + 关键发现（对标内部 Agent 的 buildContextForDimension）
       previousDimensionAnalysis: (() => {
         try {
           const summaries = [];
           for (const dimSummary of accumulatedEvidence.completedDimSummaries) {
-            const report = session.episodicMemory.getDimensionReport(dimSummary.dimId);
+            const report = session.sessionStore.getDimensionReport(dimSummary.dimId);
             if (report) {
               summaries.push({
                 dimId: dimSummary.dimId,

package/lib/external/mcp/handlers/guard.js

@@ -1,12 +1,23 @@
 /**
  * MCP Handlers — Guard 审计 & 项目扫描
- * guardCheck, guardAuditFiles, scanProject
+ *
+ * 统一入口：autosnippet_guard
+ *   无参数         → review 模式（自动 git diff 增量文件 + inline recipe）
+ *   files: string[] → 指定文件检查（+ inline recipe）
+ *   code: string    → 单文件内联检查
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { execSync } from 'node:child_process';
 import { envelope } from '../envelope.js';
 
+// ═══ Review 轮次追踪（模块私有） ═══════════════════
+
+const _reviewRounds = new Map();      // projectRoot → round count
+const _lastReviewPassed = new Map();  // projectRoot → boolean
+const MAX_REVIEW_ROUNDS = 5;
+
 export async function guardCheck(ctx, args) {
   const { GuardCheckEngine, detectLanguage } = await import(
     '../../../service/guard/GuardCheckEngine.js'
@@ -81,11 +92,21 @@ export async function guardAuditFiles(ctx, args) {
   // 注入 Enhancement Pack Guard 规则
   await _injectEnhancementGuardRules(engine, ctx);
 
+  // 解析项目根路径（用于相对路径转绝对路径）
+  const projectRoot =
+    ctx.container?.singletons?._projectRoot ||
+    process.env.ASD_PROJECT_DIR ||
+    process.cwd();
+
   // 补充缺失的 content（从磁盘读取）
-  const filesToAudit = args.files.map((f) => ({
-    path: f.path,
-    content: f.content || (fs.existsSync(f.path) ? fs.readFileSync(f.path, 'utf8') : ''),
-  }));
+  // 相对路径自动转绝对路径，避免 MCP 进程 cwd 不在项目目录时读不到文件
+  const filesToAudit = args.files.map((f) => {
+    const absPath = path.isAbsolute(f.path) ? f.path : path.resolve(projectRoot, f.path);
+    return {
+      path: absPath,
+      content: f.content || (fs.existsSync(absPath) ? fs.readFileSync(absPath, 'utf8') : ''),
+    };
+  });
 
   const result = engine.auditFiles(filesToAudit, { scope });
 
@@ -131,6 +152,263 @@ export async function guardAuditFiles(ctx, args) {
   });
 }
 
+// ═══ Review 模式 — 编码后质量门禁（无参数 = 自动检测） ═══
+
+/**
+ * Guard Review — 编码后的代码质量检查
+ *
+ * 设计要点:
+ *   1. 无参数 → 自动从 git diff 检测增量文件（staged + unstaged + untracked）
+ *   2. files: string[] → 指定文件路径（简化，不再要求对象数组）
+ *   3. violations 内联 recipe 修复指南（doClause + coreCode）
+ *   4. 防无限循环：reviewRound 计数 + MAX_REVIEW_ROUNDS 限制
+ *   5. 不绑定 task ID — 代码检查独立于任务系统
+ *
+ * @param {object} ctx — MCP context with container
+ * @param {object} args — { files?: string[] }
+ */
+export async function guardReview(ctx, args) {
+  const { GuardCheckEngine, detectLanguage } = await import(
+    '../../../service/guard/GuardCheckEngine.js'
+  );
+
+  const projectRoot = _getProjectRoot(ctx);
+
+  // 轮次追踪（基于 projectRoot，不绑定 task）
+  const round = (_reviewRounds.get(projectRoot) || 0) + 1;
+  _reviewRounds.set(projectRoot, round);
+
+  if (round > MAX_REVIEW_ROUNDS) {
+    _reviewRounds.delete(projectRoot);
+    _lastReviewPassed.set(projectRoot, true); // 强制通过
+    return envelope({
+      success: true,
+      data: { passed: true, files: [], totalViolations: 0, reviewRound: round, maxRoundsReached: true },
+      message: `⚠️ Guard review round ${round} exceeds max ${MAX_REVIEW_ROUNDS}. Force-passing. Remaining issues should be tracked as follow-up.`,
+      meta: { tool: 'autosnippet_guard', mode: 'review' },
+    });
+  }
+
+  // 1. 确定待检查文件
+  let filePaths = [];
+  let fileSource = 'git-diff';
+
+  if (args.files && Array.isArray(args.files) && args.files.length > 0) {
+    // files 参数: string[] — 简化版，自动读取文件内容
+    filePaths = args.files
+      .map(f => typeof f === 'string' ? f : (f.path || f))
+      .map(f => path.isAbsolute(f) ? f : path.resolve(projectRoot, f))
+      .filter(f => fs.existsSync(f));
+    fileSource = 'explicit';
+  } else {
+    // 无参数 → 自动检测 git 变更文件
+    filePaths = _detectChangedFiles(projectRoot);
+  }
+
+  if (!filePaths.length) {
+    _reviewRounds.delete(projectRoot);
+    _lastReviewPassed.set(projectRoot, true);
+    return envelope({
+      success: true,
+      data: { passed: true, files: [], totalViolations: 0, reviewRound: round, fileSource },
+      message: '✅ No changed source files detected. Guard review passed.',
+      meta: { tool: 'autosnippet_guard', mode: 'review' },
+    });
+  }
+
+  // 2. 预加载 rule recipe 缓存
+  const recipeMap = _loadRuleRecipes(ctx);
+
+  // 3. 创建引擎，注入 Enhancement Pack
+  const engine = _getOrCreateEngine(ctx, GuardCheckEngine);
+  await _injectEnhancementGuardRules(engine, ctx);
+
+  // 4. 逐文件检查
+  const results = [];
+  let totalViolations = 0;
+  let totalErrors = 0;
+  let totalWarnings = 0;
+
+  for (const fp of filePaths) {
+    try {
+      const code = fs.readFileSync(fp, 'utf8');
+      const lang = detectLanguage(fp);
+      const violations = engine.checkCode(code, lang, { filePath: fp });
+
+      const fileSummary = {
+        total: violations.length,
+        errors: violations.filter(v => v.severity === 'error').length,
+        warnings: violations.filter(v => v.severity === 'warning').length,
+      };
+
+      totalViolations += violations.length;
+      totalErrors += fileSummary.errors;
+      totalWarnings += fileSummary.warnings;
+
+      // 内联 recipe 修复指南
+      const enriched = violations.map(v => {
+        const base = {
+          ruleId: v.ruleId,
+          message: v.message,
+          severity: v.severity,
+          line: v.line,
+          snippet: v.snippet,
+          fixSuggestion: v.fixSuggestion || null,
+        };
+        const recipe = recipeMap.get(v.ruleId);
+        if (recipe) {
+          base.recipe = {
+            title: recipe.title,
+            doClause: recipe.doClause || null,
+            dontClause: recipe.dontClause || null,
+            coreCode: recipe.coreCode || null,
+          };
+        }
+        return base;
+      });
+
+      results.push({ filePath: fp, language: lang, violations: enriched, summary: fileSummary });
+    } catch (err) {
+      results.push({
+        filePath: fp, error: `Cannot read: ${err.message}`,
+        violations: [], summary: { total: 0, errors: 0, warnings: 0 },
+      });
+    }
+  }
+
+  const passed = totalViolations === 0;
+
+  // 5. 更新共享状态
+  if (passed) {
+    _reviewRounds.delete(projectRoot);
+    _lastReviewPassed.set(projectRoot, true);
+  } else {
+    _lastReviewPassed.set(projectRoot, false);
+  }
+
+  // 6. 写入 ViolationsStore
+  try {
+    const violationsStore = ctx.container.get('violationsStore');
+    for (const r of results) {
+      if (r.violations.length > 0) {
+        violationsStore.appendRun({
+          filePath: r.filePath, violations: r.violations,
+          summary: `guard review round ${round}: ${r.summary.errors}E ${r.summary.warnings}W`,
+        });
+      }
+    }
+  } catch { /* optional */ }
+
+  // 7. 构造消息
+  let message;
+  if (passed) {
+    message = `✅ Guard review passed (round ${round}). ${filePaths.length} file(s) checked, 0 violations.`;
+  } else {
+    const violatingFiles = results.filter(r => r.violations.length > 0);
+    const details = violatingFiles.map(f =>
+      `  ${path.basename(f.filePath)}: ${f.violations.map(v => `L${v.line} ${v.ruleId}`).join(', ')}`
+    ).join('\n');
+
+    message = [
+      `⚠️ Guard review round ${round}: ${totalViolations} violation(s) in ${violatingFiles.length} file(s).`,
+      details,
+      '',
+      'Each violation includes inline `recipe` with doClause + coreCode — apply fixes directly.',
+      round >= MAX_REVIEW_ROUNDS - 1
+        ? `⚠️ Next round is the last (max ${MAX_REVIEW_ROUNDS}). Unresolved issues will be force-passed.`
+        : `Fix and call autosnippet_guard again (round ${round + 1}).`,
+    ].join('\n');
+  }
+
+  return envelope({
+    success: true,
+    data: {
+      passed,
+      reviewRound: round,
+      fileSource,
+      files: results,
+      totalViolations,
+      summary: { total: totalViolations, errors: totalErrors, warnings: totalWarnings, filesChecked: filePaths.length },
+    },
+    message,
+    meta: { tool: 'autosnippet_guard', mode: 'review' },
+  });
+}
+
+// ═══ Recipe 缓存 ═════════════════════════════════════════
+
+/**
+ * 预加载所有 rule 类型 recipe 的修复字段
+ * 构建 guardId → recipe 映射
+ */
+function _loadRuleRecipes(ctx) {
+  const map = new Map();
+  try {
+    const db = typeof ctx.container.get('database')?.getDb === 'function'
+      ? ctx.container.get('database').getDb()
+      : ctx.container.get('database');
+
+    const rows = db.prepare(`
+      SELECT id, title, doClause, dontClause, coreCode, constraints
+      FROM knowledge_entries
+      WHERE (kind = 'rule' OR knowledgeType = 'boundary-constraint')
+        AND lifecycle = 'active'
+    `).all();
+
+    for (const row of rows) {
+      try {
+        const constraints = JSON.parse(row.constraints || '{}');
+        const guards = constraints.guards || [];
+        for (const g of guards) {
+          if (g.id) {
+            map.set(g.id, { title: row.title, doClause: row.doClause, dontClause: row.dontClause, coreCode: row.coreCode });
+          }
+        }
+      } catch { /* skip */ }
+      map.set(row.id, { title: row.title, doClause: row.doClause, dontClause: row.dontClause, coreCode: row.coreCode });
+    }
+  } catch { /* DB not available */ }
+  return map;
+}
+
+// ═══ Git Diff 检测 ═══════════════════════════════════════
+
+function _getProjectRoot(ctx) {
+  const root = ctx.container?.singletons?._projectRoot;
+  if (root) return root;
+  return process.env.ASD_PROJECT_DIR || process.cwd();
+}
+
+const SOURCE_EXTS = new Set([
+  '.m', '.mm', '.h', '.swift',
+  '.js', '.ts', '.jsx', '.tsx',
+  '.py', '.rb', '.java', '.kt', '.go', '.rs',
+  '.c', '.cpp', '.cc', '.cs',
+  '.vue', '.svelte',
+]);
+
+function _detectChangedFiles(projectRoot) {
+  const root = projectRoot || process.env.ASD_PROJECT_DIR || process.cwd();
+  try {
+    const diffOutput = execSync(
+      'git diff --name-only HEAD 2>/dev/null; git diff --staged --name-only 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null',
+      { cwd: root, encoding: 'utf8', timeout: 5000 }
+    );
+    const files = [...new Set(
+      diffOutput.split('\n')
+        .map(f => f.trim())
+        .filter(f => f && SOURCE_EXTS.has(path.extname(f).toLowerCase()))
+    )];
+    return files
+      .map(f => path.isAbsolute(f) ? f : path.resolve(root, f))
+      .filter(f => fs.existsSync(f));
+  } catch {
+    return [];
+  }
+}
+
+// ═══ 项目扫描 ════════════════════════════════════════════
+
 export async function scanProject(ctx, args) {
   const maxFiles = args.maxFiles || 200;
   const includeContent = args.includeContent || false;