@playcraft/build 0.1.40-beta → 0.1.42

package/README.md

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

package/dist/engines/engine-detector.js

@@ -3,17 +3,26 @@ 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 = [
-    // PlayCanvas - 优先检测（通过文件名而非 package.json）
+    // 完整游戏引擎
+    { 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 框架 / 渲染库
     { 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 },
 ];
 /**
  * 构建工具检测映射表 - 优先级高于引擎检测
@@ -40,6 +49,78 @@ 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;
+}
 /**
  * 引擎检测器
  * 根据项目文件结构自动检测引擎类型和构建工具
@@ -58,24 +139,48 @@ 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. 优先检测构建工具（BUILD_TOOL_DETECTION_MAP，优先级 200）
+        // 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 链路。
         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;
         }
-        // 4. 检测引擎类型（ENGINE_DETECTION_MAP，优先级 100）
-        const engine = this.detectFromPackageJson(pkg);
-        if (engine) {
-            console.log(`[EngineDetector] 检测到引擎: ${engine}（通过 package.json）`);
-            return { engine, buildTool: 'generic' };
+        // 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' };
         }
-        // 5. 兜底
+        // 7. 兜底
         console.log('[EngineDetector] 无法识别具体引擎，使用 generic 类型');
         return { engine: 'generic', buildTool: 'generic' };
     }

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

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

package/dist/engines/generic-adapter.js

@@ -40,11 +40,19 @@ export class GenericAdapter {
             console.log('[GenericAdapter] 执行依赖安装...');
             await this.runNpmInstall(packageManager);
         }
-        // 4. 检测构建命令
+        // 4. 检测构建命令。**必须先构建、再取产物**，不允许因为「找不到脚本」就
+        //    复用工程里现成的目录：那会把残留的 `dist/` 或 Vite 的 `public/` 当成
+        //    构建结果，用户拿到的是过期或完全不对的内容。
+        //
+        //    平台导入的工程都带 `builds.config.js`，由 playable-scripts 构建链负责
+        //    产出产物，正常路径下这里必然能拿到 build 脚本；拿不到就是工程本身有问题，
+        //    应当明确报错而不是静默降级。
         const buildScript = await this.detectBuildScript();
         if (!buildScript) {
-            throw new Error(`[GenericAdapter] 未找到 build script\n` +
-                `请确保 package.json 中包含 scripts.build 字段。`);
+            throw new Error(`[GenericAdapter] 未找到可用的构建命令，拒绝复用工程内现成的目录。\n` +
+                `项目目录: ${this.projectDir}\n` +
+                `请在 package.json 的 scripts 中声明 build（支持 build / build:prod / ` +
+                `build:production / dist / compile 之一）。`);
         }
         console.log(`[GenericAdapter] 检测到构建命令: ${buildScript}`);
         // 5. 执行构建
@@ -76,9 +84,6 @@ 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 {
@@ -140,25 +145,28 @@ export class GenericAdapter {
      * 检测 build script
      */
     async detectBuildScript() {
+        const pkgPath = path.join(this.projectDir, 'package.json');
+        // package.json 读不到 / 解析失败属于「工程本身有问题」，直接抛出并说明原因。
+        // 不能静默返回 null —— 那会让调用方以为「只是没配脚本」，掩盖真实故障。
+        let pkg;
         try {
-            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;
+            pkg = JSON.parse(await fs.readFile(pkgPath, 'utf-8'));
         }
-        catch {
+        catch (error) {
+            throw new Error(`[GenericAdapter] 无法读取或解析 package.json，构建中止。\n` +
+                `路径: ${pkgPath}\n` +
+                `原因: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        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;
     }
     /**
      * 执行 npm run build
@@ -166,7 +174,7 @@ export class GenericAdapter {
      */
     async runNpmBuild(packageManager, script) {
         const cmd = packageManager === 'npm' ? 'npm' : packageManager;
-        const args = packageManager === 'npm' || packageManager === 'bun' ? ['run', script] : [script];
+        const args = packageManager === 'npm' ? ['run', script] : [script];
         console.log(`[GenericAdapter] 运行: ${cmd} ${args.join(' ')}`);
         await this.runCommandWithTimeout(cmd, args, {
             cwd: this.projectDir,
@@ -183,10 +191,27 @@ export class GenericAdapter {
     }
     /**
      * 查找构建输出目录
-     * 按优先级搜索：dist/、build/、out/、public/
+     * 按优先级搜索：dist/、build/、out/，并兼容编辑器型引擎常见的
+     * 多一层输出目录（例如 Cocos 的 build/web-mobile/）。
+     *
+     * 刻意**不包含 `public/`**：Vite / webpack 都约定它是「直接拷贝到产物根的静态
+     * 资源目录」，放的是 favicon、robots.txt 这类原样文件，本身不是构建产物。
+     * 一旦里面有 index.html，就会被误当成构建结果整目录复制出去。
      */
     async findBuildOutputDir() {
-        const possibleDirs = ['dist', 'build', 'out', 'public'];
+        const possibleDirs = [
+            'dist',
+            'build',
+            'out',
+            'build/web-mobile',
+            'build/web-desktop',
+            'build/html5',
+            'dist/web-mobile',
+            'dist/html5',
+            'web-mobile',
+            'web-desktop',
+            'html5',
+        ];
         for (const dir of possibleDirs) {
             const fullPath = path.join(this.projectDir, dir);
             try {
@@ -204,6 +229,38 @@ 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');
@@ -285,12 +342,6 @@ 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 build/builds 命令
+ * - 通过平台内置的 devkit 调用 playable-scripts 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 build/builds
+     * 3. 调用平台内置的 playable-scripts 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 → 批量构建时自动禁用主题
+     * - themes.enabled → 未指定主题时显式禁用（避免 builds 意外产出全部主题变体）
      * - build.outputDir → 强制与 PlayCraft 输出目录一致
      */
     private mergeConfig;
@@ -69,12 +69,6 @@ export declare class PlayableScriptsAdapter {
      * 递归查找源码文件
      */
     private findSourceFiles;
-    /**
-     * 准备构建环境
-     * - 执行包名迁移
-     * - 确保项目本地 devkit 和 loader 可用
-     */
-    private prepareBuildEnvironment;
     /**
      * 调用 playable-scripts 命令
      *
@@ -82,14 +76,11 @@ export declare class PlayableScriptsAdapter {
      * 1. 准备构建环境（包名迁移、安装本地 devkit 和 loader）
      * 2. 执行构建（使用项目本地 devkit）
      *
-     * 单渠道模式: <local-devkit> build <channel> [options]
-     * 批量模式:   <local-devkit> builds [options]
+     * 单渠道与批量统一使用 `builds`：
+     * - devkit 仅在 `builds` 上持续迭代并新增特性，`build` 已停止更新
+     * - 单渠道通过 `--channels <channel>` 表达，无需再走 `build <channel>`
      */
     private executePlayableScripts;
-    /**
-     * 从参数列表中移除指定参数及其值
-     */
-    private removeArg;
     /**
      * 统一构造 pnpm CLI 参数：
      *   - 透传通用 flag（dangerouslyAllowAllBuilds / strict-peer-dependencies / reporter）
@@ -120,7 +111,7 @@ export declare class PlayableScriptsAdapter {
      */
     private ensureBuildLoaders;
     /**
-     * 确保 package.json 中有 build/builds 脚本
+     * 确保 package.json 中有 builds 脚本
      * devkit 必须通过 npm script 调用，不能直接执行 .js 文件
      */
     private ensureBuildScripts;
@@ -141,10 +132,6 @@ 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 build/builds 命令
+ * - 通过平台内置的 devkit 调用 playable-scripts 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 build/builds
+     * 3. 调用平台内置的 playable-scripts builds
      * 4. 收集构建产物
      * 5. 复制到输出目录
      * 6. 写入元数据（skipChannelBuild: true）
@@ -124,20 +124,9 @@ export class PlayableScriptsAdapter {
         const cliArgs = this.buildCLIArgs();
         // 3. 打印构建参数信息
         this.logBuildParams();
-        // 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);
-        }
+        // 4. 输出目录清理统一交给 devkit（builds 内部负责）：
+        //    预清理会与 devkit 自身的清理阶段竞争，在 Windows 上触发 EBUSY，因此这里不再处理。
+        console.log('[PlayableScriptsAdapter] 输出目录清理交由 devkit 负责...');
         // 5. 执行 playable-scripts 构建（使用平台内置的 devkit）
         console.log('[PlayableScriptsAdapter] 执行 playable-scripts 构建...');
         await this.executePlayableScripts(cliArgs);
@@ -194,13 +183,10 @@ export class PlayableScriptsAdapter {
      * 将 playcraft.config.json 的参数注入到项目的 builds.config.js
      * - storeUrls → googlePlayUrl / appStoreUrl
      * - naming → naming
-     * - themes.enabled → 批量构建时自动禁用主题
+     * - themes.enabled → 未指定主题时显式禁用（避免 builds 意外产出全部主题变体）
      * - 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;
@@ -228,29 +214,27 @@ export class PlayableScriptsAdapter {
         if (this.config?.naming) {
             injections.push(`  naming: ${JSON.stringify(this.config.naming)}`);
         }
-        // 批量构建时处理主题配置
-        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] 批量构建模式：指定主题未找到，使用默认主题');
-                }
+        // 主题配置一律显式注入：统一走 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} 个主题)`);
             }
             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 文件来合并配置
@@ -432,24 +416,6 @@ 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 命令
      *
@@ -457,8 +423,9 @@ export class PlayableScriptsAdapter {
      * 1. 准备构建环境（包名迁移、安装本地 devkit 和 loader）
      * 2. 执行构建（使用项目本地 devkit）
      *
-     * 单渠道模式: <local-devkit> build <channel> [options]
-     * 批量模式:   <local-devkit> builds [options]
+     * 单渠道与批量统一使用 `builds`：
+     * - devkit 仅在 `builds` 上持续迭代并新增特性，`build` 已停止更新
+     * - 单渠道通过 `--channels <channel>` 表达，无需再走 `build <channel>`
      */
     async executePlayableScripts(cliArgs) {
         // 1. 执行包名迁移
@@ -473,61 +440,35 @@ export class PlayableScriptsAdapter {
         // 3. 确保构建 loader 存在
         await this.ensureBuildLoaders();
         const config = this.config ?? {};
-        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 = '批量构建模式';
+        // 单渠道与批量统一使用 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(', ')}`);
         }
         else {
-            // 单渠道模式: <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 默认行为（当前 index.ts 指向的主题）
+            console.log(`[PlayableScriptsAdapter] 使用当前默认主题 (src/theme/index.ts)`);
+        }
         // devkit 必须通过 npm script 调用，不能直接执行 .js 文件
-        // 1. 确保 package.json 中有 build/builds 脚本
         await this.ensureBuildScripts();
-        // 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 和所有参数
+        const scriptName = 'builds';
+        const runArgs = args.slice(1);
         console.log(`[PlayableScriptsAdapter] 运行: pnpm run ${scriptName} ${runArgs.length > 0 ? runArgs.join(' ') : ''}`);
         try {
-            // 注意: package.json 的 scripts 已经是 "playable-scripts build/builds"
+            // 注意: package.json 的 scripts 已经是 "playable-scripts builds"
             // 所以不需要 '--' 分隔符，直接传参数即可
             const pnpmArgs = runArgs.length > 0
                 ? ['run', scriptName, ...runArgs]
@@ -566,21 +507,6 @@ 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）
@@ -971,7 +897,7 @@ export class PlayableScriptsAdapter {
         }
     }
     /**
-     * 确保 package.json 中有 build/builds 脚本
+     * 确保 package.json 中有 builds 脚本
      * devkit 必须通过 npm script 调用，不能直接执行 .js 文件
      */
     async ensureBuildScripts() {
@@ -982,21 +908,10 @@ 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';
-                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 script: builds');
                 console.log('[PlayableScriptsAdapter] ✓ package.json 已更新');
             }
         }
@@ -1125,29 +1040,6 @@ 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.40-beta",
+  "version": "0.1.42",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",