@playcraft/build 0.1.36-beta1 → 0.1.38-beta

package/README.md

@@ -209,4 +209,4 @@ console.log(adapter.getDefaultFormat()); // "html"
 
 - `@playcraft/cli`：CLI 工具
 - `@playcraft/worker`：队列消费与异步构建
-- `@playcraft/backend`：类型定义用于参数校验
+- `@playcraft/backend-business-server`：类型定义用于参数校验

package/dist/engines/engine-detector.js

@@ -3,26 +3,17 @@ import path from 'path';
 /**
  * 引擎检测映射表 - 从 package.json 的 dependencies 检测引擎类型
  * 复用后端 ExternalImportService 的逻辑
- *
- * 多引擎项目（如 Three.js + PixiJS：3D 场景 + 2D HUD）必须按优先级定主引擎，
- * **不能所有项同分** —— 同分时结果取决于依赖在 package.json 里的书写顺序，
- * 换个顺序识别结果就变了。分层口径与后端 `engine-detect.ts` 保持一致：
- * - 完整游戏引擎（playcanvas / cocos / layaair / egret）优先级最高
- * - 3D 渲染库（three / babylonjs）次之
- * - 2D 框架 / 渲染库（phaser / pixijs）最低
  */
 const ENGINE_DETECTION_MAP = [
-    // 完整游戏引擎
-    { match: (n) => n === 'playcanvas', engine: 'playcanvas', priority: 300 },
-    { match: (n) => n === 'cocos-creator' || n === 'cc', engine: 'cocos', priority: 300 },
-    { match: (n) => n.startsWith('laya-') || n.startsWith('@layabox/'), engine: 'layaair', priority: 300 },
-    { match: (n) => n === 'egret', engine: 'egret', priority: 300 },
-    // 3D 渲染库
-    { match: (n) => n === 'three', engine: 'threejs', priority: 200 },
-    { match: (n) => n === 'babylonjs' || n.startsWith('@babylonjs/'), engine: 'babylonjs', priority: 200 },
-    // 2D 框架 / 渲染库
+    // PlayCanvas - 优先检测（通过文件名而非 package.json）
     { match: (n) => n === 'phaser', engine: 'phaser', priority: 100 },
     { match: (n) => n === 'pixi.js' || n.startsWith('@pixi/'), engine: 'pixijs', priority: 100 },
+    { match: (n) => n === 'three', engine: 'threejs', priority: 100 },
+    { match: (n) => n === 'cocos-creator' || n === 'cc', engine: 'cocos', priority: 100 },
+    { match: (n) => n === 'playcanvas', engine: 'playcanvas', priority: 100 },
+    { match: (n) => n === 'babylonjs' || n.startsWith('@babylonjs/'), engine: 'babylonjs', priority: 100 },
+    { match: (n) => n.startsWith('laya-') || n.startsWith('@layabox/'), engine: 'layaair', priority: 100 },
+    { match: (n) => n === 'egret', engine: 'egret', priority: 100 },
 ];
 /**
  * 构建工具检测映射表 - 优先级高于引擎检测
@@ -49,78 +40,6 @@ const BUILD_TOOL_DETECTION_MAP = [
         priority: 200,
     },
 ];
-/**
- * 文件级引擎特征只做静态读取，不执行用户工程里的 JavaScript。
- *
- * 这条兜底覆盖引擎运行时由编辑器/平台内置、因此不会出现在 package.json
- * 的项目（典型是 Cocos Creator）。它也让 `packages/build` 与外部导入层的
- * 识别结果保持一致，避免导入时识别为 Cocos、真正构建时又退回 generic。
- */
-const FILE_ENGINE_LABELS = {
-    phaser: 'phaser',
-    pixi: 'pixijs',
-    pixijs: 'pixijs',
-    three: 'threejs',
-    threejs: 'threejs',
-    playcanvas: 'playcanvas',
-    cocos: 'cocos',
-    cocoscreator: 'cocos',
-    cc: 'cocos',
-    babylon: 'babylonjs',
-    babylonjs: 'babylonjs',
-    laya: 'layaair',
-    layaair: 'layaair',
-    egret: 'egret',
-};
-function normalizeFileEngineKey(value) {
-    return value.trim().toLowerCase().replace(/[\s.]/g, '');
-}
-/** 从 builds.config.js 静态读取 engine 字符串字段，不执行文件内容。 */
-function readEngineFromBuildConfig(source) {
-    // 仅移除注释，再做字段匹配；不会触发 require/import 或执行任意代码。
-    const withoutComments = source
-        .replace(/\/\*[\s\S]*?\*\//g, '')
-        .replace(/(^|\s)\/\/.*$/gm, '$1');
-    const match = /\bengine\s*:\s*['"`]([^'"`]+)['"`]/.exec(withoutComments);
-    if (!match)
-        return null;
-    return FILE_ENGINE_LABELS[normalizeFileEngineKey(match[1])] ?? null;
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-/** 校验 Cocos Creator 配置内容，避免仅凭同名文件误判。 */
-function isCocosConfig(source) {
-    try {
-        const parsed = JSON.parse(source);
-        return isRecord(parsed) && (isRecord(parsed.builder) || isRecord(parsed.engine));
-    }
-    catch {
-        return false;
-    }
-}
-async function detectEngineFromProjectFiles(projectDir) {
-    try {
-        const source = await fs.readFile(path.join(projectDir, 'builds.config.js'), 'utf8');
-        const engine = readEngineFromBuildConfig(source);
-        if (engine)
-            return engine;
-    }
-    catch {
-        // 文件不存在或不可读，继续检查 Cocos 工程标记。
-    }
-    for (const relativePath of ['settings/cocos.config.json', 'profiles/cocos.config.json']) {
-        try {
-            const source = await fs.readFile(path.join(projectDir, relativePath), 'utf8');
-            if (isCocosConfig(source))
-                return 'cocos';
-        }
-        catch {
-            // 单个标记缺失不影响另一个位置的检查。
-        }
-    }
-    return null;
-}
 /**
  * 引擎检测器
  * 根据项目文件结构自动检测引擎类型和构建工具
@@ -139,48 +58,24 @@ export class EngineDetector {
         }
         // 2. 检测 package.json
         const pkg = await this.readPackageJson(projectDir);
-        const fileEngine = await detectEngineFromProjectFiles(projectDir);
         if (!pkg) {
-            if (fileEngine) {
-                console.log(`[EngineDetector] 检测到引擎: ${fileEngine}（通过文件特征）`);
-                return { engine: fileEngine, buildTool: 'generic' };
-            }
             throw new Error(`[EngineDetector] 无法识别项目类型：找不到 package.json 或 PlayCanvas 文件结构\n` +
                 `项目目录: ${projectDir}\n` +
                 `请确保这是一个有效的项目目录。`);
         }
-        // 3. 先得到 package.json 引擎结果，用于处理「构建工具隐含引擎」与文件特征冲突。
-        const packageEngine = this.detectFromPackageJson(pkg);
-        // 4. 优先检测构建工具（BUILD_TOOL_DETECTION_MAP，优先级 200）。
-        //
-        //    **engine 与 buildTool 必须解耦**：`@playcraft/adsdk` / `@playcraft/devkit`
-        //    决定的是「用 devkit 打包」这件事，与项目是哪个引擎无关 —— Cocos 同样靠
-        //    devkit 出产物，走的是同一条链路。而 adsdk 表里的 `impliedEngine: 'phaser'`
-        //    只是「大多数 adsdk 项目是 Phaser」的经验值，一旦项目里已经能明确识别出
-        //    引擎（依赖或文件特征），就该以识别结果为准，且**不能因此把 buildTool
-        //    一起退回 generic**，否则 Cocos / Three.js 会被踢出 devkit 链路。
+        // 3. 优先检测构建工具（BUILD_TOOL_DETECTION_MAP，优先级 200）
         const buildToolResult = this.detectBuildToolFromPackageJson(pkg);
         if (buildToolResult) {
-            const knownEngine = packageEngine ?? fileEngine;
-            if (knownEngine && knownEngine !== buildToolResult.engine) {
-                console.log(`[EngineDetector] 检测到构建工具: ${buildToolResult.buildTool}；` +
-                    `引擎以识别结果 ${knownEngine} 为准（构建工具隐含 ${buildToolResult.engine} 不予采用）`);
-                return { engine: knownEngine, buildTool: buildToolResult.buildTool };
-            }
             console.log(`[EngineDetector] 检测到构建工具: ${buildToolResult.buildTool}（隐含引擎: ${buildToolResult.engine}）`);
             return buildToolResult;
         }
-        // 5. 检测引擎类型（ENGINE_DETECTION_MAP，优先级 100）
-        if (packageEngine) {
-            console.log(`[EngineDetector] 检测到引擎: ${packageEngine}（通过 package.json）`);
-            return { engine: packageEngine, buildTool: 'generic' };
-        }
-        // 6. 依赖未命中时使用文件级特征兜底。
-        if (fileEngine) {
-            console.log(`[EngineDetector] 检测到引擎: ${fileEngine}（通过文件特征）`);
-            return { engine: fileEngine, buildTool: 'generic' };
+        // 4. 检测引擎类型（ENGINE_DETECTION_MAP，优先级 100）
+        const engine = this.detectFromPackageJson(pkg);
+        if (engine) {
+            console.log(`[EngineDetector] 检测到引擎: ${engine}（通过 package.json）`);
+            return { engine, buildTool: 'generic' };
         }
-        // 7. 兜底
+        // 5. 兜底
         console.log('[EngineDetector] 无法识别具体引擎，使用 generic 类型');
         return { engine: 'generic', buildTool: 'generic' };
     }

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

@@ -47,12 +47,7 @@ export declare class GenericAdapter {
     private runNpmBuild;
     /**
      * 查找构建输出目录
-     * 按优先级搜索：dist/、build/、out/，并兼容编辑器型引擎常见的
-     * 多一层输出目录（例如 Cocos 的 build/web-mobile/）。
-     *
-     * 刻意**不包含 `public/`**：Vite / webpack 都约定它是「直接拷贝到产物根的静态
-     * 资源目录」，放的是 favicon、robots.txt 这类原样文件，本身不是构建产物。
-     * 一旦里面有 index.html，就会被误当成构建结果整目录复制出去。
+     * 按优先级搜索：dist/、build/、out/、public/
      */
     private findBuildOutputDir;
     /**

package/dist/engines/generic-adapter.js

@@ -40,19 +40,11 @@ export class GenericAdapter {
             console.log('[GenericAdapter] 执行依赖安装...');
             await this.runNpmInstall(packageManager);
         }
-        // 4. 检测构建命令。**必须先构建、再取产物**，不允许因为「找不到脚本」就
-        //    复用工程里现成的目录：那会把残留的 `dist/` 或 Vite 的 `public/` 当成
-        //    构建结果，用户拿到的是过期或完全不对的内容。
-        //
-        //    平台导入的工程都带 `builds.config.js`，由 playable-scripts 构建链负责
-        //    产出产物，正常路径下这里必然能拿到 build 脚本；拿不到就是工程本身有问题，
-        //    应当明确报错而不是静默降级。
+        // 4. 检测构建命令
         const buildScript = await this.detectBuildScript();
         if (!buildScript) {
-            throw new Error(`[GenericAdapter] 未找到可用的构建命令，拒绝复用工程内现成的目录。\n` +
-                `项目目录: ${this.projectDir}\n` +
-                `请在 package.json 的 scripts 中声明 build（支持 build / build:prod / ` +
-                `build:production / dist / compile 之一）。`);
+            throw new Error(`[GenericAdapter] 未找到 build script\n` +
+                `请确保 package.json 中包含 scripts.build 字段。`);
         }
         console.log(`[GenericAdapter] 检测到构建命令: ${buildScript}`);
         // 5. 执行构建
@@ -84,6 +76,9 @@ export class GenericAdapter {
             { file: 'pnpm-lock.yaml', manager: 'pnpm' },
             { file: 'yarn.lock', manager: 'yarn' },
             { file: 'package-lock.json', manager: 'npm' },
+            { file: 'npm-shrinkwrap.json', manager: 'npm' },
+            { file: 'bun.lock', manager: 'bun' },
+            { file: 'bun.lockb', manager: 'bun' },
         ];
         for (const { file, manager } of lockFiles) {
             try {
@@ -145,28 +140,25 @@ export class GenericAdapter {
      * 检测 build script
      */
     async detectBuildScript() {
-        const pkgPath = path.join(this.projectDir, 'package.json');
-        // package.json 读不到 / 解析失败属于「工程本身有问题」，直接抛出并说明原因。
-        // 不能静默返回 null —— 那会让调用方以为「只是没配脚本」，掩盖真实故障。
-        let pkg;
         try {
-            pkg = JSON.parse(await fs.readFile(pkgPath, 'utf-8'));
-        }
-        catch (error) {
-            throw new Error(`[GenericAdapter] 无法读取或解析 package.json，构建中止。\n` +
-                `路径: ${pkgPath}\n` +
-                `原因: ${error instanceof Error ? error.message : String(error)}`);
+            const pkgPath = path.join(this.projectDir, 'package.json');
+            const content = await fs.readFile(pkgPath, 'utf-8');
+            const pkg = JSON.parse(content);
+            if (!pkg.scripts) {
+                return null;
+            }
+            // 优先查找常见的 build 命令
+            const buildScripts = ['build', 'build:prod', 'build:production', 'dist', 'compile'];
+            for (const script of buildScripts) {
+                if (pkg.scripts[script]) {
+                    return script;
+                }
+            }
+            return null;
         }
-        if (!pkg.scripts)
+        catch {
             return null;
-        // 优先查找常见的 build 命令
-        const buildScripts = ['build', 'build:prod', 'build:production', 'dist', 'compile'];
-        for (const script of buildScripts) {
-            if (pkg.scripts[script]) {
-                return script;
-            }
         }
-        return null;
     }
     /**
      * 执行 npm run build
@@ -174,7 +166,7 @@ export class GenericAdapter {
      */
     async runNpmBuild(packageManager, script) {
         const cmd = packageManager === 'npm' ? 'npm' : packageManager;
-        const args = packageManager === 'npm' ? ['run', script] : [script];
+        const args = packageManager === 'npm' || packageManager === 'bun' ? ['run', script] : [script];
         console.log(`[GenericAdapter] 运行: ${cmd} ${args.join(' ')}`);
         await this.runCommandWithTimeout(cmd, args, {
             cwd: this.projectDir,
@@ -191,27 +183,10 @@ export class GenericAdapter {
     }
     /**
      * 查找构建输出目录
-     * 按优先级搜索：dist/、build/、out/，并兼容编辑器型引擎常见的
-     * 多一层输出目录（例如 Cocos 的 build/web-mobile/）。
-     *
-     * 刻意**不包含 `public/`**：Vite / webpack 都约定它是「直接拷贝到产物根的静态
-     * 资源目录」，放的是 favicon、robots.txt 这类原样文件，本身不是构建产物。
-     * 一旦里面有 index.html，就会被误当成构建结果整目录复制出去。
+     * 按优先级搜索：dist/、build/、out/、public/
      */
     async findBuildOutputDir() {
-        const possibleDirs = [
-            'dist',
-            'build',
-            'out',
-            'build/web-mobile',
-            'build/web-desktop',
-            'build/html5',
-            'dist/web-mobile',
-            'dist/html5',
-            'web-mobile',
-            'web-desktop',
-            'html5',
-        ];
+        const possibleDirs = ['dist', 'build', 'out', 'public'];
         for (const dir of possibleDirs) {
             const fullPath = path.join(this.projectDir, dir);
             try {
@@ -229,38 +204,6 @@ export class GenericAdapter {
                 // 目录不存在，继续检查下一个
             }
         }
-        // 最多向下搜索三层，覆盖未知引擎的嵌套产物目录；跳过依赖和 VCS 目录，
-        // 避免在大型源码树里把 node_modules 中的 index.html 当成构建结果。
-        const roots = ['dist', 'build', 'out'];
-        const ignored = new Set(['node_modules', '.git', 'library', 'temp', 'local']);
-        const search = async (root, depth) => {
-            if (depth > 3)
-                return null;
-            const fullRoot = path.join(this.projectDir, root);
-            let entries;
-            try {
-                entries = await fs.readdir(fullRoot, { withFileTypes: true });
-            }
-            catch {
-                return null;
-            }
-            if (entries.some((entry) => entry.isFile() && entry.name.toLowerCase() === 'index.html')) {
-                return fullRoot;
-            }
-            for (const entry of entries) {
-                if (!entry.isDirectory() || ignored.has(entry.name))
-                    continue;
-                const found = await search(path.join(root, entry.name), depth + 1);
-                if (found)
-                    return found;
-            }
-            return null;
-        };
-        for (const root of roots) {
-            const nested = await search(root, 1);
-            if (nested)
-                return nested;
-        }
         // 如果没找到，尝试从 package.json 读取
         try {
             const pkgPath = path.join(this.projectDir, 'package.json');
@@ -342,6 +285,12 @@ export class GenericAdapter {
         const entries = await fs.readdir(src, { withFileTypes: true });
         for (const entry of entries) {
             const srcPath = path.join(src, entry.name);
+            if (entry.name === '.playcraft.json')
+                continue;
+            if (path.basename(src) === '.playcraft' && ['skills', 'skill-artifacts', 'video-replication', 'workspace-context.json'].includes(entry.name))
+                continue;
+            if (entry.name === 'user_uploads' && path.basename(src) === '.tmp')
+                continue;
             const destPath = path.join(dest, entry.name);
             // 安全检查：确保目标路径在输出目录内
             const resolvedDest = path.resolve(destPath);

package/dist/engines/playable-scripts-adapter.d.ts

@@ -5,7 +5,7 @@ import type { BaseBuildOptions, BaseBuildOutput, PlayableScriptsConfig } from '.
  * 职责：作为 PlayCraft 和 @playcraft/devkit 之间的中间层
  * - @playcraft/devkit 是 PlayCraft 平台内置的构建工具（已集成到 @playcraft/cli）
  * - 用户项目只需依赖 @playcraft/adsdk（运行时 SDK），不需要安装构建工具
- * - 通过平台内置的 devkit 调用 playable-scripts builds 命令（单渠道与批量统一）
+ * - 通过平台内置的 devkit 调用 playable-scripts build/builds 命令
  * - 将 playcraft.config.json 的参数转换为 playable-scripts CLI 参数
  * - 收集构建产物并标记 skipChannelBuild
  *
@@ -27,7 +27,7 @@ export declare class PlayableScriptsAdapter {
      * 流程:
      * 1. 合并配置（playcraft.config.json → builds.config.js）
      * 2. 构建 CLI 参数
-     * 3. 调用平台内置的 playable-scripts builds
+     * 3. 调用平台内置的 playable-scripts build/builds
      * 4. 收集构建产物
      * 5. 复制到输出目录
      * 6. 写入元数据（skipChannelBuild: true）
@@ -45,7 +45,7 @@ export declare class PlayableScriptsAdapter {
      * 将 playcraft.config.json 的参数注入到项目的 builds.config.js
      * - storeUrls → googlePlayUrl / appStoreUrl
      * - naming → naming
-     * - themes.enabled → 未指定主题时显式禁用（避免 builds 意外产出全部主题变体）
+     * - themes.enabled → 批量构建时自动禁用主题
      * - build.outputDir → 强制与 PlayCraft 输出目录一致
      */
     private mergeConfig;
@@ -69,6 +69,12 @@ export declare class PlayableScriptsAdapter {
      * 递归查找源码文件
      */
     private findSourceFiles;
+    /**
+     * 准备构建环境
+     * - 执行包名迁移
+     * - 确保项目本地 devkit 和 loader 可用
+     */
+    private prepareBuildEnvironment;
     /**
      * 调用 playable-scripts 命令
      *
@@ -76,11 +82,14 @@ export declare class PlayableScriptsAdapter {
      * 1. 准备构建环境（包名迁移、安装本地 devkit 和 loader）
      * 2. 执行构建（使用项目本地 devkit）
      *
-     * 单渠道与批量统一使用 `builds`：
-     * - devkit 仅在 `builds` 上持续迭代并新增特性，`build` 已停止更新
-     * - 单渠道通过 `--channels <channel>` 表达，无需再走 `build <channel>`
+     * 单渠道模式: <local-devkit> build <channel> [options]
+     * 批量模式:   <local-devkit> builds [options]
      */
     private executePlayableScripts;
+    /**
+     * 从参数列表中移除指定参数及其值
+     */
+    private removeArg;
     /**
      * 统一构造 pnpm CLI 参数：
      *   - 透传通用 flag（dangerouslyAllowAllBuilds / strict-peer-dependencies / reporter）
@@ -111,7 +120,7 @@ export declare class PlayableScriptsAdapter {
      */
     private ensureBuildLoaders;
     /**
-     * 确保 package.json 中有 builds 脚本
+     * 确保 package.json 中有 build/builds 脚本
      * devkit 必须通过 npm script 调用，不能直接执行 .js 文件
      */
     private ensureBuildScripts;
@@ -132,6 +141,10 @@ export declare class PlayableScriptsAdapter {
      * 注意：只收集目标渠道的产物，过滤掉其他渠道
      */
     private scanOutputDir;
+    /**
+     * 清理输出目录，删除所有旧产物
+     */
+    private cleanOutputDir;
     /**
      * 递归删除目录
      */

package/dist/engines/playable-scripts-adapter.js

@@ -50,7 +50,7 @@ const ZIP_FALLBACK_CHANNELS = new Set(['remerge']);
  * 职责：作为 PlayCraft 和 @playcraft/devkit 之间的中间层
  * - @playcraft/devkit 是 PlayCraft 平台内置的构建工具（已集成到 @playcraft/cli）
  * - 用户项目只需依赖 @playcraft/adsdk（运行时 SDK），不需要安装构建工具
- * - 通过平台内置的 devkit 调用 playable-scripts builds 命令（单渠道与批量统一）
+ * - 通过平台内置的 devkit 调用 playable-scripts build/builds 命令
  * - 将 playcraft.config.json 的参数转换为 playable-scripts CLI 参数
  * - 收集构建产物并标记 skipChannelBuild
  *
@@ -108,7 +108,7 @@ export class PlayableScriptsAdapter {
      * 流程:
      * 1. 合并配置（playcraft.config.json → builds.config.js）
      * 2. 构建 CLI 参数
-     * 3. 调用平台内置的 playable-scripts builds
+     * 3. 调用平台内置的 playable-scripts build/builds
      * 4. 收集构建产物
      * 5. 复制到输出目录
      * 6. 写入元数据（skipChannelBuild: true）
@@ -124,9 +124,20 @@ export class PlayableScriptsAdapter {
         const cliArgs = this.buildCLIArgs();
         // 3. 打印构建参数信息
         this.logBuildParams();
-        // 4. 输出目录清理统一交给 devkit（builds 内部负责）：
-        //    预清理会与 devkit 自身的清理阶段竞争，在 Windows 上触发 EBUSY，因此这里不再处理。
-        console.log('[PlayableScriptsAdapter] 输出目录清理交由 devkit 负责...');
+        // 4. 清理输出目录（在 devkit 构建前清理，避免旧产物干扰）
+        // 判断是否为批量构建模式（多个渠道或有主题）
+        const isBatchMode = (this.config?.channels && this.config.channels.length > 1) ||
+            (this.config?.themes?.enabled);
+        if (isBatchMode) {
+            // 批量构建：不预清理，让 devkit 来清理，避免 EBUSY 错误
+            console.log('[PlayableScriptsAdapter] 批量构建模式：跳过预清理（由 devkit 负责）...');
+        }
+        else {
+            // 单渠道构建：清理项目目录下的 dist 目录（playable-scripts 实际输出目录）
+            const devkitOutputDir = path.join(this.projectDir, this.config?.outputDir ?? 'dist');
+            console.log('[PlayableScriptsAdapter] 单渠道构建模式：清理 devkit 输出目录...');
+            await this.cleanOutputDir(devkitOutputDir);
+        }
         // 5. 执行 playable-scripts 构建（使用平台内置的 devkit）
         console.log('[PlayableScriptsAdapter] 执行 playable-scripts 构建...');
         await this.executePlayableScripts(cliArgs);
@@ -183,10 +194,13 @@ export class PlayableScriptsAdapter {
      * 将 playcraft.config.json 的参数注入到项目的 builds.config.js
      * - storeUrls → googlePlayUrl / appStoreUrl
      * - naming → naming
-     * - themes.enabled → 未指定主题时显式禁用（避免 builds 意外产出全部主题变体）
+     * - themes.enabled → 批量构建时自动禁用主题
      * - build.outputDir → 强制与 PlayCraft 输出目录一致
      */
     async mergeConfig() {
+        // 判断是否为批量构建模式
+        const isBatchMode = (this.config?.channels && this.config.channels.length > 1) ||
+            (this.config?.themes?.enabled);
         // 读取或创建 builds.config.js
         const configPath = path.join(this.projectDir, 'builds.config.js');
         let configContent;
@@ -214,27 +228,29 @@ export class PlayableScriptsAdapter {
         if (this.config?.naming) {
             injections.push(`  naming: ${JSON.stringify(this.config.naming)}`);
         }
-        // 主题配置一律显式注入：统一走 builds 后，devkit 会读取项目 builds.config.js
-        // 的 themes.enabled；若在未指定主题时不显式关闭，单渠道构建会意外产出全部主题变体。
-        const availableThemes = await this.scanThemes();
-        if (this.config?.themes?.whitelist && this.config.themes.whitelist.length > 0) {
-            // 用户指定了主题白名单：启用主题切换
-            const validThemes = this.config.themes.whitelist.filter(t => availableThemes.includes(t));
-            if (validThemes.length > 0) {
-                injections.push(`  themes: { enabled: true, sourceDir: 'src/theme', entryFile: 'src/theme/index.ts' }`);
-                console.log(`[PlayableScriptsAdapter] 启用主题切换 (${validThemes.length} 个主题)`);
+        // 批量构建时处理主题配置
+        if (isBatchMode) {
+            // 扫描可用主题
+            const availableThemes = await this.scanThemes();
+            if (this.config?.themes?.whitelist && this.config.themes.whitelist.length > 0) {
+                // 用户指定了主题白名单：启用主题切换
+                const validThemes = this.config.themes.whitelist.filter(t => availableThemes.includes(t));
+                if (validThemes.length > 0) {
+                    injections.push(`  themes: { enabled: true, sourceDir: 'src/theme', entryFile: 'src/theme/index.ts' }`);
+                    console.log(`[PlayableScriptsAdapter] 批量构建模式：启用主题切换 (${validThemes.length} 个主题)`);
+                }
+                else {
+                    // 指定的主题不存在，禁用主题切换
+                    injections.push(`  themes: { enabled: false }`);
+                    console.log('[PlayableScriptsAdapter] 批量构建模式：指定主题未找到，使用默认主题');
+                }
             }
             else {
-                // 指定的主题不存在，禁用主题切换
+                // 用户未指定主题：禁用主题切换，使用当前默认主题
                 injections.push(`  themes: { enabled: false }`);
-                console.log('[PlayableScriptsAdapter] 指定主题未找到，使用默认主题');
+                console.log('[PlayableScriptsAdapter] 批量构建模式：使用当前默认主题');
             }
         }
-        else {
-            // 用户未指定主题：禁用主题切换，使用当前默认主题
-            injections.push(`  themes: { enabled: false }`);
-            console.log('[PlayableScriptsAdapter] 使用当前默认主题');
-        }
         // 始终注入配置，确保 build.outputDir 被覆盖
         // 在 module.exports 的对象末尾注入配置
         // 策略：创建一个 wrapper 文件来合并配置
@@ -416,6 +432,24 @@ export class PlayableScriptsAdapter {
         }
         return files;
     }
+    /**
+     * 准备构建环境
+     * - 执行包名迁移
+     * - 确保项目本地 devkit 和 loader 可用
+     */
+    async prepareBuildEnvironment() {
+        // 1. 执行包名迁移
+        await this.migratePackageNames();
+        // 2. 确保项目本地存在 devkit 和构建依赖
+        const localDevkit = await this.ensureLocalDevkit();
+        if (!localDevkit) {
+            throw new Error('[PlayableScriptsAdapter] 无法安装项目本地的 @playcraft/devkit。\n' +
+                '请检查网络连接或手动运行: npm install --save-dev @playcraft/devkit');
+        }
+        console.log('[PlayableScriptsAdapter] ✅ 使用项目本地 devkit');
+        // 3. 确保构建 loader 存在
+        await this.ensureBuildLoaders();
+    }
     /**
      * 调用 playable-scripts 命令
      *
@@ -423,9 +457,8 @@ export class PlayableScriptsAdapter {
      * 1. 准备构建环境（包名迁移、安装本地 devkit 和 loader）
      * 2. 执行构建（使用项目本地 devkit）
      *
-     * 单渠道与批量统一使用 `builds`：
-     * - devkit 仅在 `builds` 上持续迭代并新增特性，`build` 已停止更新
-     * - 单渠道通过 `--channels <channel>` 表达，无需再走 `build <channel>`
+     * 单渠道模式: <local-devkit> build <channel> [options]
+     * 批量模式:   <local-devkit> builds [options]
      */
     async executePlayableScripts(cliArgs) {
         // 1. 执行包名迁移
@@ -440,35 +473,61 @@ export class PlayableScriptsAdapter {
         // 3. 确保构建 loader 存在
         await this.ensureBuildLoaders();
         const config = this.config ?? {};
-        // 单渠道与批量统一使用 builds 命令：
-        // devkit 仅在 builds 上持续迭代并新增特性，build 已停止更新。
-        const args = ['builds', ...cliArgs];
-        // 扫描可用主题，命中白名单时追加 -t（devkit 的主题过滤参数）
-        const availableThemes = await this.scanThemes();
-        let selectedThemes = [];
-        if (config.themes?.whitelist && config.themes.whitelist.length > 0) {
-            // 使用配置中指定的主题白名单，清理可能的引号
-            const cleanWhitelist = config.themes.whitelist.map(t => t.replace(/^["']|["']$/g, ''));
-            selectedThemes = cleanWhitelist.filter(t => availableThemes.includes(t));
-            if (selectedThemes.length === 0) {
-                console.log(`[PlayableScriptsAdapter] ⚠️ 配置的主题未找到，使用当前默认主题`);
-            }
-        }
-        if (selectedThemes.length > 0) {
-            args.push('-t', selectedThemes.join(','));
-            console.log(`[PlayableScriptsAdapter] 构建主题: ${selectedThemes.join(', ')}`);
+        const isBatchMode = (config.channels && config.channels.length > 1) ||
+            (config.themes?.enabled);
+        // 构建命令参数
+        let args;
+        let modeLabel;
+        if (isBatchMode) {
+            // 批量模式: <devkit> builds [options]
+            args = ['builds', ...cliArgs];
+            // 扫描可用主题
+            const availableThemes = await this.scanThemes();
+            // 确定要构建的主题列表
+            let selectedThemes = [];
+            if (config.themes?.whitelist && config.themes.whitelist.length > 0) {
+                // 使用配置中指定的主题白名单，清理可能的引号
+                const cleanWhitelist = config.themes.whitelist.map(t => t.replace(/^["']|["']$/g, ''));
+                selectedThemes = cleanWhitelist.filter(t => availableThemes.includes(t));
+                if (selectedThemes.length === 0) {
+                    console.log(`[PlayableScriptsAdapter] ⚠️ 配置的主题未找到，使用当前默认主题`);
+                    selectedThemes = [];
+                }
+            }
+            // 如果有指定主题，传入 -t 参数
+            if (selectedThemes.length > 0) {
+                args.push('-t', selectedThemes.join(','));
+                console.log(`[PlayableScriptsAdapter] 构建主题: ${selectedThemes.join(', ')}`);
+            }
+            else {
+                // 未指定主题：使用 devkit 默认行为（当前 index.ts 指向的主题）
+                console.log(`[PlayableScriptsAdapter] 使用当前默认主题 (src/theme/index.ts)`);
+            }
+            modeLabel = '批量构建模式';
         }
         else {
-            // 未指定主题：使用 devkit 默认行为（当前 index.ts 指向的主题）
-            console.log(`[PlayableScriptsAdapter] 使用当前默认主题 (src/theme/index.ts)`);
-        }
+            // 单渠道模式: <devkit> build <channel> [options]
+            const channel = config.channels?.[0]
+                ? mapChannel(config.channels[0])
+                : 'google';
+            const filteredArgs = this.removeArg(cliArgs, '--channels');
+            args = ['build', channel, ...filteredArgs];
+            modeLabel = `单渠道构建模式: ${channel}`;
+        }
+        console.log(`[PlayableScriptsAdapter] ${modeLabel}`);
         // devkit 必须通过 npm script 调用，不能直接执行 .js 文件
+        // 1. 确保 package.json 中有 build/builds 脚本
         await this.ensureBuildScripts();
-        const scriptName = 'builds';
-        const runArgs = args.slice(1);
+        // 2. 通过 pnpm run 执行
+        const scriptName = isBatchMode ? 'builds' : 'build';
+        // 单渠道: args = ['build', channel, ...options]，需要传递 [channel, ...options]
+        // 批量:   args = ['builds', ...options]，需要传递 [...options]
+        const runArgs = isBatchMode
+            ? args.slice(1) // builds 命令，去掉第一个 'builds'
+            : args.slice(1); // build 命令，去掉第一个 'build'，保留 channel 和所有参数
         console.log(`[PlayableScriptsAdapter] 运行: pnpm run ${scriptName} ${runArgs.length > 0 ? runArgs.join(' ') : ''}`);
         try {
-            // 注意: package.json 的 scripts 已经是 "playable-scripts builds"
+            // 注意: package.json 的 scripts 已经是 "playable-scripts build/builds"
             // 所以不需要 '--' 分隔符，直接传参数即可
             const pnpmArgs = runArgs.length > 0
                 ? ['run', scriptName, ...runArgs]
@@ -507,6 +566,21 @@ export class PlayableScriptsAdapter {
             console.error(`[PlayableScriptsAdapter] 请检查 devkit 构建日志，确认构建是否成功`);
         }
     }
+    /**
+     * 从参数列表中移除指定参数及其值
+     */
+    removeArg(args, argName) {
+        const result = [];
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === argName) {
+                i++; // 跳过参数值
+            }
+            else {
+                result.push(args[i]);
+            }
+        }
+        return result;
+    }
     /**
      * 统一构造 pnpm CLI 参数：
      *   - 透传通用 flag（dangerouslyAllowAllBuilds / strict-peer-dependencies / reporter）
@@ -897,7 +971,7 @@ export class PlayableScriptsAdapter {
         }
     }
     /**
-     * 确保 package.json 中有 builds 脚本
+     * 确保 package.json 中有 build/builds 脚本
      * devkit 必须通过 npm script 调用，不能直接执行 .js 文件
      */
     async ensureBuildScripts() {
@@ -908,10 +982,21 @@ export class PlayableScriptsAdapter {
             if (!pkg.scripts) {
                 pkg.scripts = {};
             }
+            let modified = false;
+            // 确保有 build 脚本
+            if (!pkg.scripts.build) {
+                pkg.scripts.build = 'playable-scripts build';
+                modified = true;
+                console.log('[PlayableScriptsAdapter] 注入 package.json script: build');
+            }
+            // 确保有 builds 脚本
             if (!pkg.scripts.builds) {
                 pkg.scripts.builds = 'playable-scripts builds';
-                await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2), 'utf-8');
+                modified = true;
                 console.log('[PlayableScriptsAdapter] 注入 package.json script: builds');
+            }
+            if (modified) {
+                await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2), 'utf-8');
                 console.log('[PlayableScriptsAdapter] ✓ package.json 已更新');
             }
         }
@@ -1040,6 +1125,29 @@ export class PlayableScriptsAdapter {
         }
     }
     // ==================== 6. 复制到输出目录 ====================
+    /**
+     * 清理输出目录，删除所有旧产物
+     */
+    async cleanOutputDir(dir) {
+        try {
+            await fs.access(dir);
+            // 目录存在，递归删除所有内容
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    await this.removeDirRecursive(fullPath);
+                }
+                else {
+                    await fs.unlink(fullPath);
+                }
+            }
+            console.log(`[PlayableScriptsAdapter] 已清理输出目录: ${dir}`);
+        }
+        catch {
+            // 目录不存在，无需清理
+        }
+    }
     /**
      * 递归删除目录
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/build",
-  "version": "0.1.36-beta1",
+  "version": "0.1.38-beta",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",