autosnippet 3.2.7 → 3.2.8

package/lib/platform/ios/spm/{SpmService.js → SpmHelper.js}

@@ -1,34 +1,23 @@
 /**
- * SpmService — SPM 依赖管理门面服务
+ * SpmHelper — SPM 包结构解析与依赖操作辅助工具
  * 整合 PackageSwiftParser + DependencyGraph + PolicyEngine
+ * 由 SpmDiscoverer 持有，不作为独立 Service 使用
  */
 
 import { readFileSync, writeFileSync } from 'node:fs';
-import {
-  basename as _pathBasename,
-  dirname,
-  resolve as pathResolve,
-  relative,
-  sep,
-} from 'node:path';
+import { dirname, resolve as pathResolve, relative, sep } from 'node:path';
 import { GraphCache } from '../../../infrastructure/cache/GraphCache.js';
 import Logger from '../../../infrastructure/logging/Logger.js';
 import { DependencyGraph } from './DependencyGraph.js';
 import { PackageSwiftParser } from './PackageSwiftParser.js';
 import { PolicyEngine } from './PolicyEngine.js';
 
-export class SpmService {
+export class SpmHelper {
   #parser;
   #graph;
   #policy;
   #logger;
   #projectRoot;
-  #aiFactory;
-  #chatAgent;
-  #qualityScorer;
-  #recipeExtractor;
-  #guardCheckEngine;
-  #violationsStore;
 
   /**
    * target → { packageName, packagePath } 映射（V1 spmmap 等价）
@@ -50,12 +39,6 @@ export class SpmService {
 
   constructor(projectRoot, options = {}) {
     this.#projectRoot = projectRoot;
-    this.#aiFactory = options.aiFactory || null;
-    this.#chatAgent = options.chatAgent || null;
-    this.#qualityScorer = options.qualityScorer || null;
-    this.#recipeExtractor = options.recipeExtractor || null;
-    this.#guardCheckEngine = options.guardCheckEngine || null;
-    this.#violationsStore = options.violationsStore || null;
     this.#parser = options.parser || new PackageSwiftParser(projectRoot);
     this.#graph = options.graph || new DependencyGraph();
     this.#policy = options.policy || new PolicyEngine();
@@ -78,11 +61,28 @@ export class SpmService {
 
     // ── 收集所有 Package.swift 路径 + 联合 hash ──
     const packagePath = this.#parser.findPackageSwift(this.#projectRoot);
-    const allPaths = packagePath
-      ? [packagePath]
-      : this.#parser.findAllPackageSwifts(this.#projectRoot);
+
+    // 判断是否需要多包模式：
+    // 1. 根目录没有 Package.swift → findAllPackageSwifts
+    // 2. 根目录有 Package.swift 但 targets 为空且有 local path dependencies → 聚合根 + 子包
+    let allPaths;
+    if (packagePath) {
+      const rootParsed = this.#parser.parse(packagePath);
+      const hasNoTargets = !rootParsed?.targets || rootParsed.targets.length === 0;
+      const hasLocalDeps = (rootParsed?.dependencies || []).some(d => d.type === 'local' || d.path);
+      if (hasNoTargets && hasLocalDeps) {
+        // 聚合根模式：根 Package.swift 仅声明 local path 依赖，target 在子包里
+        allPaths = this.#parser.findAllPackageSwifts(this.#projectRoot);
+        this.#logger.info(`[SpmHelper] 聚合根检测: 根无 target 但有 ${rootParsed.dependencies.length} 个 local dep，切换多包模式`);
+      } else {
+        allPaths = [packagePath];
+      }
+    } else {
+      allPaths = this.#parser.findAllPackageSwifts(this.#projectRoot);
+    }
+
     if (allPaths.length === 0) {
-      this.#logger.warn('[SpmService] Package.swift 未找到');
+      this.#logger.warn('[SpmHelper] Package.swift 未找到');
       return null;
     }
 
@@ -93,7 +93,7 @@ export class SpmService {
     if (cached && cached.contentHash === combinedHash) {
       this.#restoreFromCache(cached.data);
       this.#logger.info(
-        `[SpmService] ⚡ 缓存命中 (${this.#graph.getNodes().length} targets, hash=${combinedHash.substring(0, 8)})`
+        `[SpmHelper] ⚡ 缓存命中 (${this.#graph.getNodes().length} targets, hash=${combinedHash.substring(0, 8)})`
       );
       return cached.data.parsedResult;
     }
@@ -102,15 +102,15 @@ export class SpmService {
     const startTime = Date.now();
     let parsedResult;
 
-    if (packagePath) {
-      // 单包模式
+    if (packagePath && allPaths.length === 1) {
+      // 单包模式（根有 target）
       const parsed = this.#parser.parse(packagePath);
       this.#graph.buildFromParsed(parsed);
       for (const t of parsed.targets || []) {
         this.#targetPackageMap.set(t.name, { packageName: parsed.name, packagePath });
       }
       this.#buildPackageDepGraph([{ path: packagePath, parsed }]);
-      this.#logger.info(`[SpmService] 加载完成: ${parsed.name} (${parsed.targets.length} targets)`);
+      this.#logger.info(`[SpmHelper] 加载完成: ${parsed.name} (${parsed.targets.length} targets)`);
       parsedResult = parsed;
     } else {
       // 多包模式
@@ -120,7 +120,7 @@ export class SpmService {
     // ── 写入缓存 ──
     if (parsedResult) {
       this.#saveToCache(combinedHash, parsedResult);
-      this.#logger.info(`[SpmService] 缓存已写入 (${Date.now() - startTime}ms 解析)`);
+      this.#logger.info(`[SpmHelper] 缓存已写入 (${Date.now() - startTime}ms 解析)`);
     }
 
     return parsedResult;
@@ -132,7 +132,7 @@ export class SpmService {
    * @returns {object|null}
    */
   #loadMultiPackage(allPaths) {
-    this.#logger.info(`[SpmService] 发现 ${allPaths.length} 个 Package.swift，逐一解析...`);
+    this.#logger.info(`[SpmHelper] 发现 ${allPaths.length} 个 Package.swift，逐一解析...`);
     const mergedTargets = [];
     let lastName = 'multi-package';
     const allParsed = [];
@@ -160,14 +160,14 @@ export class SpmService {
           lastName = parsed.name;
         }
       } catch (e) {
-        this.#logger.warn(`[SpmService] 解析失败: ${pkgPath} - ${e.message}`);
+        this.#logger.warn(`[SpmHelper] 解析失败: ${pkgPath} - ${e.message}`);
       }
     }
 
     this.#buildPackageDepGraph(allParsed);
 
     this.#logger.info(
-      `[SpmService] 多包加载完成: ${mergedTargets.length} targets from ${allPaths.length} packages`
+      `[SpmHelper] 多包加载完成: ${mergedTargets.length} targets from ${allPaths.length} packages`
     );
     return {
       name: lastName,
@@ -260,7 +260,7 @@ export class SpmService {
       }
     }
 
-    this.#logger.debug(`[SpmService] 包级依赖图: ${this.#packageDepGraph.size} packages`);
+    this.#logger.debug(`[SpmHelper] 包级依赖图: ${this.#packageDepGraph.size} packages`);
   }
 
   /**
@@ -321,35 +321,6 @@ export class SpmService {
     return 'suggest'; // 默认仅提示模式
   }
 
-  /**
-   * 获取依赖图
-   */
-  getGraph() {
-    return this.#graph;
-  }
-
-  /**
-   * 检查 from 是否可达 to
-   */
-  isReachable(from, to) {
-    return this.#graph.isReachable(from, to);
-  }
-
-  /**
-   * 运行策略检查
-   * @param {{ layerOrder?: string[] }} config
-   */
-  checkPolicies(config = {}) {
-    return this.#policy.check(this.#graph, config);
-  }
-
-  /**
-   * 检查能否添加依赖
-   */
-  canAddDependency(from, to) {
-    return this.#policy.canAddDependency(this.#graph, from, to);
-  }
-
   /**
    * 确保依赖存在: 如果不存在则评估是否可以添加
    * 支持跨包循环检测：如果 from 和 to 在不同包内，额外检查包级依赖图
@@ -487,11 +458,11 @@ export class SpmService {
       this.#parser.clearCache();
 
       this.#logger.info(
-        `[SpmService] 已自动补齐依赖: ${from} -> ${to}${isCrossPackage ? ' (跨包)' : ''} (${packagePath})`
+        `[SpmHelper] 已自动补齐依赖: ${from} -> ${to}${isCrossPackage ? ' (跨包)' : ''} (${packagePath})`
       );
       return { ok: true, changed: true, file: packagePath, crossPackage: isCrossPackage };
     } catch (err) {
-      this.#logger.error(`[SpmService] addDependency failed: ${err.message}`);
+      this.#logger.error(`[SpmHelper] addDependency failed: ${err.message}`);
       return { ok: false, changed: false, error: err.message };
     }
   }
@@ -536,11 +507,11 @@ export class SpmService {
         pkgDepsRe,
         `${pkgDepsMatch[1]}${existing}${separator}${newDep}\n    ${pkgDepsMatch[3]}`
       );
-      this.#logger.info(`[SpmService] 已添加包级依赖: .package(path: "${relPath}")`);
+      this.#logger.info(`[SpmHelper] 已添加包级依赖: .package(path: "${relPath}")`);
       return { changed: true, content: patched };
     }
 
-    this.#logger.warn(`[SpmService] 未能找到包级 dependencies 数组，跳过 .package(path:) 插入`);
+    this.#logger.warn(`[SpmHelper] 未能找到包级 dependencies 数组，跳过 .package(path:) 插入`);
     return { changed: false, content };
   }
 
@@ -548,6 +519,7 @@ export class SpmService {
    * 推断文件所属 target（源自 V1 ModuleResolverV2.determineCurrentModule）
    *
    * 从文件到 Package.swift 所在目录的相对路径中，反向匹配已知 target 名。
+   * 如果文件不在任何 SPM target 的源码目录中（如 Xcode 主 App target），返回 null。
    * @param {string} filePath - 源文件绝对路径
    * @returns {string|null} target 名称，未匹配返回 null
    */
@@ -575,44 +547,14 @@ export class SpmService {
         }
       }
 
-      // 兜底：第一个 target
-      return nodes[0] || null;
+      // 文件不属于任何 SPM target（如 Xcode 主 App target 下的文件）
+      // 不做错误的 fallback，返回 null 让调用方跳过依赖检查
+      return null;
     } catch {
       return null;
     }
   }
 
-  /**
-   * 获取 target 的分层信息
-   */
-  getLevels() {
-    return Object.fromEntries(this.#graph.computeLevels());
-  }
-
-  /**
-   * 拓扑排序
-   */
-  getTopologicalOrder() {
-    return this.#graph.topologicalSort();
-  }
-
-  /**
-   * 获取摘要报告
-   */
-  getSummary() {
-    const nodes = this.#graph.getNodes();
-    const levels = this.#graph.computeLevels();
-    const cycles = this.#graph.detectCycles();
-
-    return {
-      nodeCount: nodes.length,
-      edgeCount: this.#graph.edgeCount(),
-      levels: Object.fromEntries(levels),
-      cycleCount: cycles.length,
-      cycles: cycles.map((c) => c.join(' → ')),
-    };
-  }
-
   // ─────────────── Dashboard API 适配方法 ───────────────
 
   /**
@@ -688,26 +630,6 @@ export class SpmService {
     return virtualTargets;
   }
 
-  /**
-   * 获取依赖关系图（路由: GET /spm/dep-graph）
-   * @param {{ level?: 'package'|'target' }} options
-   */
-  async getDependencyGraph(options = {}) {
-    await this.#ensureLoaded();
-    const json = this.#graph.toJSON();
-
-    return {
-      nodes: json.nodes.map((name) => ({
-        id: name,
-        label: name,
-        type: options.level === 'package' ? 'package' : 'target',
-      })),
-      edges: json.edges.map((e) => ({ from: e.from, to: e.to, source: 'spm' })),
-      projectRoot: this.#projectRoot,
-      generatedAt: new Date().toISOString(),
-    };
-  }
-
   /**
    * 获取 Target 源文件列表（路由: POST /spm/target-files）
    * 支持多 Package 项目：先在 target 所属 package 目录查找
@@ -876,538 +798,6 @@ export class SpmService {
     return files;
   }
 
-  /**
-   * 共用增强管线：补充 extract_recipes handler 未覆盖的增量增强。
-   * extract_recipes handler 已负责：normalizeSemanticFields + RecipeExtractor + QualityScorer + V3 结构化。
-   * 此方法仅做以下增量处理：
-   *   - 确保 normalizeSemanticFields 已执行（幂等，防止非 ChatAgent 路径跳过）
-   *   - 若 handler 未注入质量评分，由 SpmService 补充
-   */
-  _enrichRecipes(recipes) {
-    for (const recipe of recipes) {
-      // QualityScorer 评分（程序化，仅在未评分时补充）
-      if (!recipe.quality && this.#qualityScorer) {
-        try {
-          const scoreResult = this.#qualityScorer.score(recipe);
-          recipe.quality = {
-            completeness: 0,
-            adaptation: 0,
-            documentation: 0,
-            overall: scoreResult.score ?? 0,
-            grade: scoreResult.grade || '',
-          };
-        } catch (e) {
-          this.#logger.debug(`[SpmService] QualityScorer failed: ${e.message}`);
-        }
-      }
-    }
-  }
-
-  /**
-   * AI 扫描 Target 发现候选项（路由: POST /spm/scan）
-   * 完整管线: 读文件 → AI 提取 → Header 解析 → 工具增强(语义标签/质量评分)
-   */
-  async scanTarget(target, options = {}) {
-    const targetName = typeof target === 'string' ? target : target?.name;
-    /** @type {((event: {type: string, [key:string]: any}) => void) | undefined} */
-    const onProgress = options.onProgress;
-
-    // 1. 获取源文件列表
-    onProgress?.({ type: 'scan:started', targetName });
-    const fileList = await this.getTargetFiles(target);
-    if (!fileList || fileList.length === 0) {
-      return {
-        recipes: [],
-        scannedFiles: [],
-        message: `No source files found for target: ${targetName}`,
-      };
-    }
-
-    const scannedFilesMeta = fileList.map((f) => {
-      const filePath = typeof f === 'string' ? f : f.path;
-      return { name: _pathBasename(filePath), path: f.relativePath || _pathBasename(filePath) };
-    });
-    onProgress?.({ type: 'scan:files-loaded', files: scannedFilesMeta, count: fileList.length });
-
-    // 2. 读取文件内容
-    onProgress?.({ type: 'scan:reading', count: fileList.length });
-    const { readFileSync } = await import('node:fs');
-    const { basename } = await import('node:path');
-    const files = fileList
-      .map((f) => {
-        const filePath = typeof f === 'string' ? f : f.path;
-        try {
-          return {
-            name: basename(filePath),
-            path: filePath,
-            relativePath: f.relativePath || basename(filePath),
-            content: readFileSync(filePath, 'utf8'),
-          };
-        } catch (err) {
-          this.#logger.warn(`[SpmService] 读取文件失败: ${filePath} — ${err.message}`);
-          return null;
-        }
-      })
-      .filter(Boolean);
-
-    if (files.length === 0) {
-      return { recipes: [], scannedFiles: [], message: 'All source files unreadable' };
-    }
-
-    const scannedFiles = files.map((f) => ({ name: f.name, path: f.relativePath }));
-    this.#logger.info(`[SpmService] scanTarget: ${targetName}, ${files.length} files`);
-
-    // 3. AI 提取 Recipes（通过 ChatAgent 统一入口）
-    if (!this.#chatAgent && !this.#aiFactory) {
-      return {
-        recipes: [],
-        scannedFiles,
-        message: 'AI provider not configured. Please set ASD_AI_PROVIDER.',
-      };
-    }
-
-    onProgress?.({ type: 'scan:ai-extracting', fileCount: files.length, targetName });
-    const AI_EXTRACT_TIMEOUT = 120_000; // 2 分钟 AI 提取超时
-    let recipes;
-    try {
-      if (this.#chatAgent) {
-        const extractPromise = this.#chatAgent.executeTool('extract_recipes', {
-          targetName,
-          files,
-        });
-        const timeoutPromise = new Promise((_, reject) =>
-          setTimeout(
-            () => reject(new Error(`AI extraction timeout (${AI_EXTRACT_TIMEOUT / 1000}s)`)),
-            AI_EXTRACT_TIMEOUT
-          )
-        );
-        const result = await Promise.race([extractPromise, timeoutPromise]);
-        if (result?.error) {
-          return { recipes: [], scannedFiles, message: result.error };
-        }
-        recipes = result?.recipes || [];
-      } else {
-        // 降级: 直接使用 aiFactory（兼容未注入 chatAgent 的场景）
-        const {
-          getProviderWithFallback,
-          isGeoOrProviderError,
-          getAvailableFallbacks,
-          createProvider,
-        } = this.#aiFactory;
-        let ai = await getProviderWithFallback();
-        if (!ai) {
-          return { recipes: [], scannedFiles, message: 'AI provider not available' };
-        }
-
-        try {
-          recipes = await ai.extractRecipes(targetName, files, {});
-        } catch (primaryErr) {
-          if (isGeoOrProviderError(primaryErr)) {
-            const currentProvider = (process.env.ASD_AI_PROVIDER || 'google').toLowerCase();
-            const fallbacks = getAvailableFallbacks(currentProvider);
-            let fallbackOk = false;
-            for (const fbName of fallbacks) {
-              try {
-                ai = createProvider({ provider: fbName });
-                recipes = await ai.extractRecipes(targetName, files, {});
-                fallbackOk = true;
-                break;
-              } catch (fbErr) {
-                this.#logger.warn(`[SpmService] fallback "${fbName}" failed: ${fbErr.message}`);
-              }
-            }
-            if (!fallbackOk) {
-              throw primaryErr;
-            }
-          } else {
-            throw primaryErr;
-          }
-        }
-      }
-    } catch (err) {
-      this.#logger.warn(`[SpmService] scanTarget AI extraction failed: ${err.message}`);
-      return { recipes: [], scannedFiles, message: `AI extraction failed: ${err.message}` };
-    }
-
-    if (!Array.isArray(recipes)) {
-      recipes = [];
-    }
-
-    // 3.5 Header 路径解析 + moduleName 注入
-    try {
-      const PathFinder = await import('../../../infrastructure/paths/PathFinder.js');
-      const HeaderResolver = await import('../../../infrastructure/paths/HeaderResolver.js');
-      const targetRootDir = await PathFinder.findTargetRootDir(files[0].path);
-      for (const recipe of recipes) {
-        const headerList = recipe.headers || [];
-        recipe.headerPaths = await Promise.all(
-          headerList.map((h) => HeaderResolver.resolveHeaderRelativePath(h, targetRootDir))
-        );
-        recipe.moduleName = targetName;
-      }
-    } catch (err) {
-      this.#logger.warn(`[SpmService] Header resolution failed: ${err.message}`);
-    }
-
-    // 4. 工具增强：语义标准化 + 标签 + 评分
-    onProgress?.({ type: 'scan:enriching', recipeCount: recipes.length });
-    this._enrichRecipes(recipes);
-
-    const result = { recipes, scannedFiles };
-    if (recipes.length === 0) {
-      const aiInfo = this.#aiFactory
-        ? (await import('../../../external/ai/AiFactory.js')).getAiConfigInfo()
-        : null;
-      if (aiInfo && !aiInfo.hasKey) {
-        result.noAi = true;
-        result.message = 'AI 未配置，已跳过智能提取。请在 .env 中设置 API Key 后重试。';
-      } else {
-        result.message = `AI 提取完成，但未发现可复用的代码模式（${targetName}, ${files.length} 个文件）`;
-      }
-    }
-    onProgress?.({
-      type: 'scan:completed',
-      recipeCount: recipes.length,
-      fileCount: scannedFiles.length,
-    });
-    return result;
-  }
-
-  /**
-   * 全项目扫描 — 遍历所有 Target，AI 提取候选 + Guard 审计
-   * 返回: { targets: [...], recipes: [], guardAudit: { files, summary }, scannedFiles: [] }
-   */
-  async scanProject(options = {}) {
-    this.#logger.info('[SpmService] scanProject: starting full-project scan');
-
-    const { readFileSync, existsSync, readdirSync, statSync } = await import('node:fs');
-    const { basename: bn, join, extname, relative } = await import('node:path');
-
-    // 1. 列出所有 target
-    const allTargets = await this.listTargets();
-
-    // 2. 收集所有源文件（去重）
-    const seenPaths = new Set();
-    const allFiles = []; // { name, path, relativePath, content, targetName }
-    const MAX_FILES = options.maxFiles || 200;
-
-    if (allTargets && allTargets.length > 0) {
-      // SPM 项目：从 Target 中收集
-      for (const t of allTargets) {
-        try {
-          const fileList = await this.getTargetFiles(t);
-          for (const f of fileList) {
-            const fp = typeof f === 'string' ? f : f.path;
-            if (seenPaths.has(fp)) {
-              continue;
-            }
-            seenPaths.add(fp);
-            try {
-              const content = readFileSync(fp, 'utf8');
-              allFiles.push({
-                name: bn(fp),
-                path: fp,
-                relativePath: f.relativePath || bn(fp),
-                content,
-                targetName: t.name,
-              });
-            } catch {
-              /* unreadable */
-            }
-            if (allFiles.length >= MAX_FILES) {
-              break;
-            }
-          }
-        } catch (e) {
-          this.#logger.warn(`[SpmService] scanProject: skipping target ${t.name}: ${e.message}`);
-        }
-        if (allFiles.length >= MAX_FILES) {
-          break;
-        }
-      }
-    } else {
-      // 非 SPM 项目：直接扫描常见源码目录（fallback）
-      this.#logger.info('[SpmService] scanProject: No SPM targets, falling back to directory scan');
-      const CODE_EXTS = new Set([
-        '.swift',
-        '.m',
-        '.mm',
-        '.h',
-        '.js',
-        '.ts',
-        '.tsx',
-        '.jsx',
-        '.py',
-        '.java',
-        '.kt',
-        '.go',
-        '.rs',
-        '.rb',
-        '.vue',
-        '.mjs',
-        '.cjs',
-      ]);
-      const SKIP_DIRS = new Set([
-        'node_modules',
-        '.git',
-        'dist',
-        'build',
-        '.next',
-        'Pods',
-        'Carthage',
-        '.build',
-        'DerivedData',
-        'vendor',
-        '__pycache__',
-        '.venv',
-        'target',
-      ]);
-      const srcDirs = [
-        'Sources',
-        'src',
-        'lib',
-        'app',
-        'pages',
-        'components',
-        'modules',
-        'packages',
-      ];
-
-      const walkDir = (dir, targetName) => {
-        if (allFiles.length >= MAX_FILES) {
-          return;
-        }
-        let entries;
-        try {
-          entries = readdirSync(dir, { withFileTypes: true });
-        } catch {
-          return;
-        }
-        for (const ent of entries) {
-          if (allFiles.length >= MAX_FILES) {
-            break;
-          }
-          if (ent.name.startsWith('.')) {
-            continue;
-          }
-          const fp = join(dir, ent.name);
-          if (ent.isDirectory()) {
-            if (SKIP_DIRS.has(ent.name)) {
-              continue;
-            }
-            walkDir(fp, targetName);
-          } else if (ent.isFile() && CODE_EXTS.has(extname(ent.name).toLowerCase())) {
-            if (seenPaths.has(fp)) {
-              continue;
-            }
-            seenPaths.add(fp);
-            try {
-              const st = statSync(fp);
-              if (st.size > 512 * 1024) {
-                continue; // 跳过 > 512KB
-              }
-              const content = readFileSync(fp, 'utf8');
-              if (content.split('\n').length < 5) {
-                continue; // 跳过微小文件
-              }
-              allFiles.push({
-                name: ent.name,
-                path: fp,
-                relativePath: relative(this.#projectRoot, fp),
-                content,
-                targetName,
-              });
-            } catch {
-              /* unreadable */
-            }
-          }
-        }
-      };
-
-      for (const dir of srcDirs) {
-        const dirPath = join(this.#projectRoot, dir);
-        if (existsSync(dirPath)) {
-          walkDir(dirPath, dir);
-        }
-      }
-
-      // 如果常见目录都为空，扫描根目录（浅层）
-      if (allFiles.length === 0) {
-        walkDir(this.#projectRoot, 'root');
-      }
-    }
-
-    this.#logger.info(
-      `[SpmService] scanProject: ${allFiles.length} unique files from ${allTargets?.length || 0} targets`
-    );
-
-    if (allFiles.length === 0) {
-      return {
-        targets: (allTargets || []).map((t) => t.name),
-        recipes: [],
-        guardAudit: null,
-        scannedFiles: [],
-        message: 'No readable source files',
-      };
-    }
-
-    const scannedFiles = allFiles.map((f) => ({
-      name: f.name,
-      path: f.relativePath,
-      targetName: f.targetName,
-    }));
-
-    // 3. AI 提取 Recipes（全局批量，分批避免 token 超限）— 通过 ChatAgent 统一入口
-    const allRecipes = [];
-    const PER_BATCH_TIMEOUT = options.batchTimeout || 90000; // 每批最多 90 秒
-    const startTime = Date.now();
-    const TOTAL_TIMEOUT = options.totalTimeout || 540000; // 总超时 9 分钟（留 1 分钟给 Guard）
-    let timedOut = false;
-
-    if (this.#chatAgent || this.#aiFactory) {
-      const BATCH_SIZE = options.batchSize || 20;
-
-      if (this.#chatAgent) {
-        // 通过 ChatAgent extract_recipes 工具（内置 fallback）
-        for (let i = 0; i < allFiles.length; i += BATCH_SIZE) {
-          if (Date.now() - startTime > TOTAL_TIMEOUT) {
-            this.#logger.warn(
-              `[SpmService] scanProject: total timeout reached after ${Math.floor((Date.now() - startTime) / 1000)}s, returning partial results`
-            );
-            timedOut = true;
-            break;
-          }
-          const batch = allFiles.slice(i, i + BATCH_SIZE);
-          const batchLabel = `project-batch-${Math.floor(i / BATCH_SIZE) + 1}`;
-          try {
-            const result = await Promise.race([
-              this.#chatAgent.executeTool('extract_recipes', {
-                targetName: batchLabel,
-                files: batch,
-              }),
-              new Promise((_, reject) =>
-                setTimeout(() => reject(new Error('batch timeout')), PER_BATCH_TIMEOUT)
-              ),
-            ]);
-            if (Array.isArray(result?.recipes)) {
-              allRecipes.push(...result.recipes);
-            }
-          } catch (err) {
-            this.#logger.warn(
-              `[SpmService] scanProject ChatAgent batch ${batchLabel} failed: ${err.message}`
-            );
-          }
-        }
-      } else {
-        // 降级: 直接使用 aiFactory（兼容未注入 chatAgent 的场景）
-        const {
-          getProviderWithFallback,
-          isGeoOrProviderError,
-          getAvailableFallbacks,
-          createProvider,
-        } = this.#aiFactory;
-        let ai = await getProviderWithFallback();
-
-        if (ai) {
-          for (let i = 0; i < allFiles.length; i += BATCH_SIZE) {
-            if (Date.now() - startTime > TOTAL_TIMEOUT) {
-              this.#logger.warn(
-                `[SpmService] scanProject: total timeout reached, returning partial results`
-              );
-              timedOut = true;
-              break;
-            }
-            const batch = allFiles.slice(i, i + BATCH_SIZE);
-            const batchLabel = `project-batch-${Math.floor(i / BATCH_SIZE) + 1}`;
-            try {
-              const recipes = await Promise.race([
-                ai.extractRecipes(batchLabel, batch),
-                new Promise((_, reject) =>
-                  setTimeout(() => reject(new Error('batch timeout')), PER_BATCH_TIMEOUT)
-                ),
-              ]);
-              if (Array.isArray(recipes)) {
-                allRecipes.push(...recipes);
-              }
-            } catch (err) {
-              if (isGeoOrProviderError(err)) {
-                const fallbacks = getAvailableFallbacks(
-                  (process.env.ASD_AI_PROVIDER || 'google').toLowerCase()
-                );
-                for (const fb of fallbacks) {
-                  try {
-                    ai = createProvider({ provider: fb });
-                    const recipes = await ai.extractRecipes(batchLabel, batch);
-                    if (Array.isArray(recipes)) {
-                      allRecipes.push(...recipes);
-                    }
-                    break;
-                  } catch {
-                    /* next fallback */
-                  }
-                }
-              } else {
-                this.#logger.warn(
-                  `[SpmService] scanProject AI batch ${batchLabel} failed: ${err.message}`
-                );
-              }
-            }
-          }
-        }
-      }
-
-      // 工具增强：语义标准化 + 标签 + 评分
-      this._enrichRecipes(allRecipes);
-    }
-
-    // 4. Guard 审计 — 对所有文件运行 GuardCheckEngine
-    let guardAudit = null;
-    if (this.#guardCheckEngine) {
-      try {
-        const guardFiles = allFiles.map((f) => ({ path: f.path, content: f.content }));
-        guardAudit = this.#guardCheckEngine.auditFiles(guardFiles, { scope: 'project' });
-
-        // 将有违反的文件写入 ViolationsStore
-        if (this.#violationsStore && guardAudit.files) {
-          for (const fileResult of guardAudit.files) {
-            if (fileResult.violations.length > 0) {
-              this.#violationsStore.appendRun({
-                filePath: fileResult.filePath,
-                violations: fileResult.violations,
-                summary: `Project scan: ${fileResult.summary.errors} errors, ${fileResult.summary.warnings} warnings`,
-              });
-            }
-          }
-        }
-      } catch (e) {
-        this.#logger.warn(`[SpmService] Guard audit failed: ${e.message}`);
-      }
-    }
-
-    this.#logger.info(
-      `[SpmService] scanProject complete: ${allRecipes.length} recipes, ${guardAudit?.summary?.totalViolations || 0} violations${timedOut ? ' (partial — timed out)' : ''}`
-    );
-
-    return {
-      targets: allTargets.map((t) => t.name),
-      recipes: allRecipes,
-      guardAudit,
-      scannedFiles,
-      partial: timedOut,
-    };
-  }
-
-  /**
-   * 标准化 AI 提取结果中的语义字段
-   * - preconditions (flat array) → constraints.preconditions
-   * - steps (string[]) → [{title, description}] 结构化格式
-   * - 确保 rationale / knowledgeType / complexity / scope 就位
-   */
-  static normalizeSemanticFields(recipe) {
-    // V3: AI 已输出完整结构，不再填充默认值
-    return recipe;
-  }
-
   /**
    * 确保已加载 Package.swift（惰性加载）
    */
@@ -1416,30 +806,8 @@ export class SpmService {
       try {
         await this.load();
       } catch (e) {
-        this.#logger.warn(`[SpmService] 自动加载失败: ${e.message}`);
+        this.#logger.warn(`[SpmHelper] 自动加载失败: ${e.message}`);
       }
     }
   }
-
-  /**
-   * 刷新依赖映射（路由: POST /commands/spm-map）
-   * 会主动使缓存失效并重新解析
-   */
-  async updateDependencyMap(options = {}) {
-    this.#graphCache.invalidate('spm-graph');
-    this.#targetFilesCache.clear();
-    this.#graph.clear();
-    const parsed = await this.load();
-    if (!parsed) {
-      return { success: false, message: 'Package.swift not found', targets: 0, edges: 0 };
-    }
-    const json = this.#graph.toJSON();
-    return {
-      success: true,
-      message: `Dependency map updated for ${parsed.name}`,
-      targets: json.nodes.length,
-      edges: json.edges.length,
-      projectRoot: this.#projectRoot,
-    };
-  }
 }