@playcraft/build 0.0.17 → 0.0.21

package/dist/audio-optimizer.js

@@ -0,0 +1,226 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const AUDIO_EXTENSIONS = new Set(['.mp3', '.wav', '.ogg', '.aac', '.m4a']);
+const SPECTRAL_SUFFIX = '.spectral.json';
+/**
+ * Read SpectralAudioEngine runtime source from packages/build/src/runtime/
+ */
+async function readSpectralRuntime() {
+    const runtimePath = path.join(__dirname, 'runtime', 'spectral-audio-engine.js');
+    try {
+        return await fs.readFile(runtimePath, 'utf-8');
+    }
+    catch {
+        // Fallback minimal runtime if file not found
+        return '/* SpectralAudioEngine runtime not found */';
+    }
+}
+function formatScanError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Recursively scan a directory for audio and spectral JSON files.
+ */
+async function scanDirectory(dir, baseDir, report) {
+    const audioFiles = [];
+    const spectralFiles = [];
+    const resolvedRoot = path.resolve(dir);
+    async function walk(current) {
+        let entries;
+        try {
+            entries = (await fs.readdir(current, { withFileTypes: true }));
+        }
+        catch (err) {
+            const rel = path.relative(baseDir, current) || current;
+            if (path.resolve(current) === resolvedRoot) {
+                throw new Error(`[AudioOptimizer] Cannot read build directory "${current}": ${formatScanError(err)}`);
+            }
+            report.warn(`[AudioOptimizer] Skipping unreadable directory "${rel}": ${formatScanError(err)}`, err);
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (AUDIO_EXTENSIONS.has(ext)) {
+                    try {
+                        const st = await fs.stat(fullPath);
+                        audioFiles.push({
+                            filePath: fullPath,
+                            relativePath: path.relative(baseDir, fullPath),
+                            size: st.size,
+                            hasSpectral: false,
+                        });
+                    }
+                    catch (err) {
+                        const rel = path.relative(baseDir, fullPath);
+                        report.warn(`[AudioOptimizer] Could not stat audio file "${rel}": ${formatScanError(err)}`, err);
+                    }
+                }
+                else if (entry.name.endsWith(SPECTRAL_SUFFIX)) {
+                    spectralFiles.push(fullPath);
+                }
+            }
+        }
+    }
+    await walk(dir);
+    // Cross-reference: for each audio file, check if a spectral counterpart exists
+    const spectralSet = new Set(spectralFiles);
+    for (const audio of audioFiles) {
+        const spectralPath = audio.filePath.replace(/\.[^.]+$/, SPECTRAL_SUFFIX);
+        if (spectralSet.has(spectralPath)) {
+            audio.hasSpectral = true;
+            try {
+                const st = await fs.stat(spectralPath);
+                audio.spectralSize = st.size;
+                audio.potentialSavings = audio.size - st.size;
+            }
+            catch (err) {
+                report.warn(`[AudioOptimizer] Could not stat spectral JSON for "${audio.relativePath}" ` +
+                    `("${path.relative(baseDir, spectralPath)}"): ${formatScanError(err)}`, err);
+                audio.hasSpectral = false;
+                audio.spectralSize = undefined;
+                audio.potentialSavings = undefined;
+            }
+        }
+    }
+    return { audioFiles, spectralFiles };
+}
+/**
+ * Inject SpectralAudioEngine runtime into an HTML string.
+ * Inserts a <script> tag before </head> (or at top of <body> if no </head>).
+ */
+function injectRuntimeIntoHtml(html, runtimeCode) {
+    const scriptTag = `<script>/* SpectralAudioEngine v1 */\n${runtimeCode}\n</script>`;
+    const headCloseIdx = html.lastIndexOf('</head>');
+    if (headCloseIdx !== -1) {
+        return html.slice(0, headCloseIdx) + scriptTag + '\n' + html.slice(headCloseIdx);
+    }
+    const bodyOpenIdx = html.indexOf('<body');
+    if (bodyOpenIdx !== -1) {
+        const bodyTagEnd = html.indexOf('>', bodyOpenIdx) + 1;
+        return html.slice(0, bodyTagEnd) + '\n' + scriptTag + html.slice(bodyTagEnd);
+    }
+    return scriptTag + '\n' + html;
+}
+/**
+ * AudioOptimizer — Build-time audio analysis and optimization.
+ *
+ * Scans a build directory for audio files and .spectral.json counterparts.
+ * When spectral files are present, optionally injects the SpectralAudioEngine
+ * runtime (< 3KB) into the output HTML so the browser can synthesize them.
+ *
+ * Usage:
+ *   const optimizer = new AudioOptimizer({ buildDir: './dist', htmlOutputPath: './dist/index.html' });
+ *   const report = await optimizer.optimize();
+ *   console.log(report);
+ */
+export class AudioOptimizer {
+    constructor(options) {
+        this.options = {
+            injectRuntime: true,
+            htmlOutputPath: '',
+            verbose: false,
+            ...options,
+        };
+    }
+    /**
+     * Run the optimizer. Returns a report with audio file details and optimization results.
+     */
+    async optimize() {
+        const { buildDir, injectRuntime, htmlOutputPath, verbose } = this.options;
+        const log = (msg) => {
+            if (verbose)
+                console.log(`[AudioOptimizer] ${msg}`);
+        };
+        log(`Scanning ${buildDir} for audio files...`);
+        const warn = (message, cause) => {
+            console.warn(message);
+            if (verbose && cause !== undefined) {
+                console.warn(cause);
+            }
+        };
+        const { audioFiles, spectralFiles } = await scanDirectory(buildDir, buildDir, { warn });
+        const totalAudioSize = audioFiles.reduce((sum, f) => sum + f.size, 0);
+        const totalSpectralSize = audioFiles.reduce((sum, f) => {
+            return sum + (f.hasSpectral && f.spectralSize !== undefined ? f.spectralSize : f.size);
+        }, 0);
+        log(`Found ${audioFiles.length} audio file(s), ${spectralFiles.length} spectral JSON(s)`);
+        log(`Total audio: ${(totalAudioSize / 1024).toFixed(1)}KB → with spectral: ${(totalSpectralSize / 1024).toFixed(1)}KB`);
+        let runtimeInjected = false;
+        let runtimeSize = 0;
+        if (injectRuntime && spectralFiles.length > 0 && htmlOutputPath) {
+            log(`Injecting SpectralAudioEngine runtime into ${htmlOutputPath}...`);
+            try {
+                const [html, runtimeCode] = await Promise.all([
+                    fs.readFile(htmlOutputPath, 'utf-8'),
+                    readSpectralRuntime(),
+                ]);
+                runtimeSize = Buffer.byteLength(runtimeCode, 'utf-8');
+                const injectedHtml = injectRuntimeIntoHtml(html, runtimeCode);
+                await fs.writeFile(htmlOutputPath, injectedHtml, 'utf-8');
+                runtimeInjected = true;
+                log(`Runtime injected (${runtimeSize}B)`);
+            }
+            catch (err) {
+                log(`Warning: failed to inject runtime: ${err.message}`);
+            }
+        }
+        else if (spectralFiles.length === 0) {
+            log('No spectral files found — runtime injection skipped');
+        }
+        const netSavings = totalAudioSize - totalSpectralSize - runtimeSize;
+        if (verbose) {
+            for (const f of audioFiles) {
+                if (f.hasSpectral) {
+                    log(`  ✓ ${f.relativePath} ${(f.size / 1024).toFixed(1)}KB → spectral ${(f.spectralSize ?? 0)}B ` +
+                        `(saved ${((f.potentialSavings ?? 0) / 1024).toFixed(1)}KB)`);
+                }
+                else {
+                    log(`  - ${f.relativePath} ${(f.size / 1024).toFixed(1)}KB (no spectral counterpart)`);
+                }
+            }
+        }
+        return {
+            audioFiles,
+            spectralFiles,
+            totalAudioSize,
+            totalSpectralSize,
+            runtimeInjected,
+            runtimeSize,
+            netSavings,
+        };
+    }
+    /**
+     * Print a human-readable summary of the optimization report.
+     */
+    static printReport(report) {
+        console.log('\n── Audio Optimization Report ──────────────────────');
+        console.log(`  Audio files:    ${report.audioFiles.length}`);
+        console.log(`  Spectral JSONs: ${report.spectralFiles.length}`);
+        console.log(`  Total audio:    ${(report.totalAudioSize / 1024).toFixed(1)}KB`);
+        if (report.spectralFiles.length > 0) {
+            console.log(`  With spectral:  ${(report.totalSpectralSize / 1024).toFixed(1)}KB`);
+            if (report.runtimeInjected) {
+                console.log(`  + Runtime:     +${report.runtimeSize}B`);
+            }
+            const savings = report.netSavings;
+            const pct = report.totalAudioSize > 0
+                ? ((savings / report.totalAudioSize) * 100).toFixed(1)
+                : '0';
+            if (savings > 0) {
+                console.log(`  Net savings:    ${(savings / 1024).toFixed(1)}KB (${pct}%)`);
+            }
+        }
+        if (report.runtimeInjected) {
+            console.log('  ✓ SpectralAudioEngine runtime injected');
+        }
+        console.log('────────────────────────────────────────────────────\n');
+    }
+}

package/dist/base-builder.d.ts

@@ -1,30 +1,42 @@
-import type { BaseBuildOptions, BaseBuildOutput } from './types.js';
+import type { BaseBuildOptions, BaseBuildOutput, PlayableScriptsConfig } from './types.js';
 /**
- * 基础构建器 - 路由到不同引擎适配器
+ * 基础构建器 - 路由到不同构建工具适配器
  *
  * 职责：
- * 1. 确定引擎类型（从 options 或自动检测）
- * 2. 路由到对应适配器执行 Base Build
+ * 1. 确定引擎类型和构建工具（从 options 或自动检测）
+ * 2. 根据构建工具路由到对应适配器执行 Base Build
  *
- * 适配器：
- * - PlayCanvasAdapter：处理 PlayCanvas 项目（官方构建产物或源代码）
- * - GenericAdapter：处理外部引擎（npm install + npm run build）
+ * 路由规则（按 buildTool）：
+ * - playcanvas-native → PlayCanvasAdapter：处理 PlayCanvas 项目
+ * - playable-scripts → PlayableScriptsAdapter：处理 @playcraft/devkit 项目
+ * - generic → GenericAdapter：处理外部引擎（npm install + npm run build）
  */
 export declare class BaseBuilder {
     private projectDir;
     private options;
-    constructor(projectDir: string, options: BaseBuildOptions);
+    private playableScriptsConfig?;
+    private usePlayableScripts?;
+    private _metadata?;
+    constructor(projectDir: string, options: BaseBuildOptions, extraOptions?: {
+        playableScriptsConfig?: PlayableScriptsConfig;
+        usePlayableScripts?: boolean;
+    });
+    /**
+     * 获取构建元数据（在 build() 完成后可用）
+     */
+    get metadata(): BaseBuildOutput['metadata'] | undefined;
     /**
      * 执行基础构建
-     * 根据引擎类型路由到对应适配器
+     * 根据构建工具路由到对应适配器
      */
     build(): Promise<BaseBuildOutput>;
     /**
-     * 解析引擎类型
+     * 解析引擎类型和构建工具
      * 优先级：
-     * 1. options.engine（用户显式指定）
-     * 2. 自动检测
+     * 1. --use-playable-scripts 显式指定
+     * 2. options.engine 用户显式指定引擎
+     * 3. 自动检测（detectFull）
      */
-    private resolveEngine;
+    private resolveDetection;
 }
 export type { BaseBuildOptions, BaseBuildOutput } from './types.js';

package/dist/base-builder.js

@@ -1,58 +1,98 @@
-import { EngineDetector, PlayCanvasAdapter, GenericAdapter } from './engines/index.js';
+import { EngineDetector, PlayCanvasAdapter, GenericAdapter, PlayableScriptsAdapter } from './engines/index.js';
 /**
- * 基础构建器 - 路由到不同引擎适配器
+ * 基础构建器 - 路由到不同构建工具适配器
  *
  * 职责：
- * 1. 确定引擎类型（从 options 或自动检测）
- * 2. 路由到对应适配器执行 Base Build
+ * 1. 确定引擎类型和构建工具（从 options 或自动检测）
+ * 2. 根据构建工具路由到对应适配器执行 Base Build
  *
- * 适配器：
- * - PlayCanvasAdapter：处理 PlayCanvas 项目（官方构建产物或源代码）
- * - GenericAdapter：处理外部引擎（npm install + npm run build）
+ * 路由规则（按 buildTool）：
+ * - playcanvas-native → PlayCanvasAdapter：处理 PlayCanvas 项目
+ * - playable-scripts → PlayableScriptsAdapter：处理 @playcraft/devkit 项目
+ * - generic → GenericAdapter：处理外部引擎（npm install + npm run build）
  */
 export class BaseBuilder {
-    constructor(projectDir, options) {
+    constructor(projectDir, options, extraOptions) {
         this.projectDir = projectDir;
         this.options = options;
+        this.playableScriptsConfig = extraOptions?.playableScriptsConfig;
+        this.usePlayableScripts = extraOptions?.usePlayableScripts;
         console.log(`[BaseBuilder] 初始化: projectDir=${projectDir}, outputDir=${options.outputDir}`);
     }
+    /**
+     * 获取构建元数据（在 build() 完成后可用）
+     */
+    get metadata() {
+        return this._metadata;
+    }
     /**
      * 执行基础构建
-     * 根据引擎类型路由到对应适配器
+     * 根据构建工具路由到对应适配器
      */
     async build() {
-        // 1. 确定引擎类型
-        const engine = await this.resolveEngine();
-        console.log(`[BaseBuilder] 使用引擎: ${engine}`);
-        // 2. 路由到对应适配器
-        if (engine === 'playcanvas') {
-            const adapter = new PlayCanvasAdapter(this.projectDir, this.options);
-            return adapter.baseBuild();
-        }
-        else {
-            const adapter = new GenericAdapter(this.projectDir, this.options, engine);
-            return adapter.baseBuild();
+        // 1. 确定引擎类型和构建工具
+        const { engine, buildTool } = await this.resolveDetection();
+        console.log(`[BaseBuilder] 使用引擎: ${engine}, 构建工具: ${buildTool}`);
+        // 2. 根据构建工具路由到对应适配器
+        let result;
+        switch (buildTool) {
+            case 'playcanvas-native': {
+                const adapter = new PlayCanvasAdapter(this.projectDir, this.options);
+                result = await adapter.baseBuild();
+                break;
+            }
+            case 'playable-scripts': {
+                const adapter = new PlayableScriptsAdapter(this.projectDir, this.options, this.playableScriptsConfig);
+                result = await adapter.baseBuild();
+                break;
+            }
+            case 'generic':
+            default: {
+                const adapter = new GenericAdapter(this.projectDir, this.options, engine);
+                result = await adapter.baseBuild();
+                break;
+            }
         }
+        // 3. 存储 metadata 供外部访问
+        this._metadata = result.metadata;
+        return result;
     }
     /**
-     * 解析引擎类型
+     * 解析引擎类型和构建工具
      * 优先级：
-     * 1. options.engine（用户显式指定）
-     * 2. 自动检测
+     * 1. --use-playable-scripts 显式指定
+     * 2. options.engine 用户显式指定引擎
+     * 3. 自动检测（detectFull）
      */
-    async resolveEngine() {
-        // 1. 用户显式指定
+    async resolveDetection() {
+        // 1. 用户显式指定 --use-playable-scripts
+        if (this.usePlayableScripts) {
+            console.log('[BaseBuilder] 用户显式指定使用 playable-scripts 构建工具');
+            return { engine: 'generic', buildTool: 'playable-scripts' };
+        }
+        // 2. 用户显式指定引擎
         if (this.options.engine) {
             const validated = EngineDetector.validateEngine(this.options.engine);
             if (validated) {
                 console.log(`[BaseBuilder] 使用用户指定的引擎: ${validated}`);
-                return validated;
+                // PlayCanvas 直接使用原生适配器
+                if (validated === 'playcanvas') {
+                    return { engine: 'playcanvas', buildTool: 'playcanvas-native' };
+                }
+                // 其他引擎：检测是否可用 playable-scripts（@playcraft/adsdk 项目）
+                const detected = await EngineDetector.detectFull(this.projectDir);
+                if (detected.buildTool === 'playable-scripts') {
+                    console.log(`[BaseBuilder] 检测到 playable-scripts 项目，优先使用 devkit 构建`);
+                    return detected;
+                }
+                // 否则使用 generic 适配器
+                return { engine: validated, buildTool: 'generic' };
             }
             console.warn(`[BaseBuilder] 无效的引擎类型: ${this.options.engine}，将自动检测`);
         }
-        // 2. 自动检测
-        const detected = await EngineDetector.detect(this.projectDir);
-        console.log(`[BaseBuilder] 自动检测引擎: ${detected}`);
+        // 3. 自动检测
+        const detected = await EngineDetector.detectFull(this.projectDir);
+        console.log(`[BaseBuilder] 自动检测结果: engine=${detected.engine}, buildTool=${detected.buildTool}`);
         return detected;
     }
 }

package/dist/engines/engine-detector.d.ts

@@ -1,14 +1,19 @@
-import type { EngineType } from '../types.js';
+import type { EngineType, DetectionResult } from '../types.js';
 /**
  * 引擎检测器
- * 根据项目文件结构自动检测引擎类型
+ * 根据项目文件结构自动检测引擎类型和构建工具
  */
 export declare class EngineDetector {
     /**
-     * 检测项目的引擎类型
+     * 完整检测：返回引擎类型 + 构建工具的二维检测结果
+     * @param projectDir 项目目录
+     * @returns 包含 engine 和 buildTool 的检测结果
+     */
+    static detectFull(projectDir: string): Promise<DetectionResult>;
+    /**
+     * 检测项目的引擎类型（向后兼容）
      * @param projectDir 项目目录
      * @returns 引擎类型
-     * @throws 如果无法识别引擎，抛出错误
      */
     static detect(projectDir: string): Promise<EngineType>;
     /**
@@ -19,6 +24,10 @@ export declare class EngineDetector {
      * 读取 package.json
      */
     private static readPackageJson;
+    /**
+     * 从 package.json 检测构建工具（优先级 200，高于引擎检测）
+     */
+    private static detectBuildToolFromPackageJson;
     /**
      * 从 package.json 检测引擎类型
      */

package/dist/engines/engine-detector.js

@@ -15,22 +15,46 @@ const ENGINE_DETECTION_MAP = [
     { match: (n) => n.startsWith('laya-') || n.startsWith('@layabox/'), engine: 'layaair', priority: 100 },
     { match: (n) => n === 'egret', engine: 'egret', priority: 100 },
 ];
+/**
+ * 构建工具检测映射表 - 优先级高于引擎检测
+ * 当检测到特定构建工具或 SDK 时，可以隐含引擎类型和构建工具
+ *
+ * 注意：@playcraft/devkit 是 PlayCraft 平台内置的构建工具（已集成到 @playcraft/cli）。
+ * 用户项目只需依赖 @playcraft/adsdk（运行时 SDK），不需要安装构建工具。
+ * 检测到 adsdk 时，自动使用平台内置的 devkit 进行构建。
+ */
+const BUILD_TOOL_DETECTION_MAP = [
+    {
+        // 检测 @playcraft/adsdk（运行时 SDK）- 使用平台内置的 devkit 构建
+        // 或旧的内部包名 @tencent/playable-sdk
+        match: (n) => n === '@playcraft/adsdk' || n === '@tencent/playable-sdk',
+        buildTool: 'playable-scripts',
+        impliedEngine: 'phaser', // adsdk 项目通常是 Phaser 游戏
+        priority: 200, // 高于引擎检测优先级（200 > 100）
+    },
+    {
+        // 向后兼容：检测旧的 devkit 包名（用户项目可能还在使用）
+        match: (n) => n === '@playcraft/devkit' || n === '@tencent/playable-scripts',
+        buildTool: 'playable-scripts',
+        impliedEngine: 'generic',
+        priority: 200,
+    },
+];
 /**
  * 引擎检测器
- * 根据项目文件结构自动检测引擎类型
+ * 根据项目文件结构自动检测引擎类型和构建工具
  */
 export class EngineDetector {
     /**
-     * 检测项目的引擎类型
+     * 完整检测：返回引擎类型 + 构建工具的二维检测结果
      * @param projectDir 项目目录
-     * @returns 引擎类型
-     * @throws 如果无法识别引擎，抛出错误
+     * @returns 包含 engine 和 buildTool 的检测结果
      */
-    static async detect(projectDir) {
+    static async detectFull(projectDir) {
         // 1. 优先检测 PlayCanvas / PlayCraft 特有文件（最快路径）
         const isPlayCanvas = await this.detectPlayCanvasFiles(projectDir);
         if (isPlayCanvas) {
-            return 'playcanvas';
+            return { engine: 'playcanvas', buildTool: 'playcanvas-native' };
         }
         // 2. 检测 package.json
         const pkg = await this.readPackageJson(projectDir);
@@ -39,15 +63,30 @@ export class EngineDetector {
                 `项目目录: ${projectDir}\n` +
                 `请确保这是一个有效的项目目录。`);
         }
-        // 3. 从 package.json 检测引擎
+        // 3. 优先检测构建工具（BUILD_TOOL_DETECTION_MAP，优先级 200）
+        const buildToolResult = this.detectBuildToolFromPackageJson(pkg);
+        if (buildToolResult) {
+            console.log(`[EngineDetector] 检测到构建工具: ${buildToolResult.buildTool}（隐含引擎: ${buildToolResult.engine}）`);
+            return buildToolResult;
+        }
+        // 4. 检测引擎类型（ENGINE_DETECTION_MAP，优先级 100）
         const engine = this.detectFromPackageJson(pkg);
         if (engine) {
             console.log(`[EngineDetector] 检测到引擎: ${engine}（通过 package.json）`);
-            return engine;
+            return { engine, buildTool: 'generic' };
         }
-        // 4. 兜底：generic（任何有 npm build 的项目）
+        // 5. 兜底
         console.log('[EngineDetector] 无法识别具体引擎，使用 generic 类型');
-        return 'generic';
+        return { engine: 'generic', buildTool: 'generic' };
+    }
+    /**
+     * 检测项目的引擎类型（向后兼容）
+     * @param projectDir 项目目录
+     * @returns 引擎类型
+     */
+    static async detect(projectDir) {
+        const result = await this.detectFull(projectDir);
+        return result.engine;
     }
     /**
      * 检测 PlayCanvas 特有文件
@@ -122,6 +161,31 @@ export class EngineDetector {
             return null;
         }
     }
+    /**
+     * 从 package.json 检测构建工具（优先级 200，高于引擎检测）
+     */
+    static detectBuildToolFromPackageJson(pkg) {
+        const allDeps = {
+            ...pkg.dependencies,
+            ...pkg.devDependencies,
+        };
+        // 收集所有匹配的构建工具，按优先级排序后返回最高优先级的项
+        const matches = [];
+        for (const [depName] of Object.entries(allDeps)) {
+            for (const { match, buildTool, impliedEngine, priority } of BUILD_TOOL_DETECTION_MAP) {
+                if (match(depName)) {
+                    matches.push({ engine: impliedEngine, buildTool, priority });
+                }
+            }
+        }
+        if (matches.length === 0) {
+            return null;
+        }
+        // 按优先级排序（数字越大优先级越高），返回最高优先级的项
+        matches.sort((a, b) => b.priority - a.priority);
+        const bestMatch = matches[0];
+        return { engine: bestMatch.engine, buildTool: bestMatch.buildTool };
+    }
     /**
      * 从 package.json 检测引擎类型
      */

package/dist/engines/generic-adapter.d.ts

@@ -13,18 +13,24 @@ export declare class GenericAdapter {
      * 执行通用基础构建
      * 流程：
      * 1. 检测包管理器
-     * 2. 执行 npm install（超时 3 分钟）
-     * 3. 检测 build script
-     * 4. 执行 npm run build（超时 5 分钟）
-     * 5. 查找构建产物目录
-     * 6. 复制构建产物到 outputDir
-     * 7. 写入 .build-metadata.json
+     * 2. 检查 node_modules（存在则跳过安装）
+     * 3. 执行 npm install（超时 3 分钟）
+     * 4. 检测 build script
+     * 5. 执行 npm run build（超时 5 分钟）
+     * 6. 查找构建产物目录
+     * 7. 复制构建产物到 outputDir
+     * 8. 写入 .build-metadata.json
      */
     baseBuild(): Promise<BaseBuildOutput>;
     /**
      * 检测包管理器
      */
     private detectPackageManager;
+    /**
+     * 检查 node_modules 是否存在且不为空
+     * 用于判断是否需要执行安装
+     */
+    private checkNodeModules;
     /**
      * 执行 npm install
      * 超时：3 分钟