@playcraft/build 0.1.50-beta → 0.1.51

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,8 +111,18 @@ export declare class PlayableScriptsAdapter {
      */
     private ensureBuildLoaders;
     /**
-     * 确保 package.json 中有 build/builds 脚本
-     * devkit 必须通过 npm script 调用，不能直接执行 .js 文件
+     * 确保 package.json 的 `builds` 脚本存在，且**内容确实是 `playable-scripts builds`**。
+     *
+     * 为什么不能只判断"存在"：我们最终执行的是 `pnpm run builds`，如果项目里的 `builds`
+     * 还写着老命令 `playable-scripts build`（老模板 / 手工改过），即使平台代码已经统一，
+     * 实际跑的仍是单渠道 legacy 命令 —— 输出布局、默认 network/protocol、是否追加 preview
+     * 都会跟 `builds` 不一样，等于历史问题复活。
+     *
+     * 处理策略（保留前置步骤，如 `node scripts/generate-levels.js &&`）：
+     *   1. 已是 `playable-scripts builds` → 不动
+     *   2. 存在但含 `playable-scripts build` → 就地改写为 `builds`
+     *   3. 不存在 → 从 `build` 脚本推导（保留其前置步骤），否则注入纯 `playable-scripts builds`
+     *   4. 存在但完全自定义（不含 playable-scripts）→ 直接报错，避免静默跑错命令
      */
     private ensureBuildScripts;
     /**
@@ -141,15 +142,26 @@ export declare class PlayableScriptsAdapter {
      * 注意：只收集目标渠道的产物，过滤掉其他渠道
      */
     private scanOutputDir;
-    /**
-     * 清理输出目录，删除所有旧产物
-     */
-    private cleanOutputDir;
     /**
      * 递归删除目录
      */
     private removeDirRecursive;
     private copyToOutputDir;
+    /**
+     * 从同一渠道的多个产物中选出交付用的那一个。
+     *
+     * 旧实现是「文件名含 `-` 就 break，其次 HTML 优先」，在 devkit 扁平布局下会把
+     * `xxx-preview.html` 选成目标渠道产物（snapchat 构建最终交付了预览 html）。
+     *
+     * 现在的优先级（打分）：
+     *   1. 文件名命中目标渠道（devkit 命名 `<主题>-<渠道>[_L|_P].<ext>`）  +4
+     *   2. 与请求格式一致（请求 zip 优先 .zip，请求 html 优先 .html）        +2
+     *   3. zip 兜底（同为候选时优先交付压缩包）                            +1
+     *   4. 无方向后缀的基准产物优先                                        +0.5
+     *
+     * 出现多份等价产物时打印完整候选清单，避免再出现「静默挑了一个错的」。
+     */
+    private pickOutputForChannel;
     /**
      * 是否对 playable-scripts 使用 --zip。
      * 双格式渠道默认 HTML；仅在请求或配置显式选择 ZIP 时传递 --zip。

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

@@ -32,6 +32,24 @@ const UNSUPPORTED_CHANNELS = new Set([]);
 function mapChannel(playcraftPlatform) {
     return CHANNEL_MAP[playcraftPlatform] ?? playcraftPlatform;
 }
+/**
+ * 归一化 devkit 产物文件名（去掉扩展名与方向后缀），用于渠道识别。
+ *
+ * devkit 命名约定（core/batch-build.js copyTempFiles）：
+ *   `<主题>-<渠道>.zip|html`、多方向时 `<主题>-<渠道>_L.zip|html`
+ * 兼容仅渠道名的命名（`--filename` 命中渠道时，如 `preview.html`）。
+ */
+function artifactStem(fileName) {
+    return fileName
+        .replace(/\.(html|zip)$/i, '')
+        .replace(/_[LP]$/i, '')
+        .toLowerCase();
+}
+/** 判断产物文件名是否属于指定渠道（devkit 命名约定） */
+function artifactMatchesChannel(fileName, channel) {
+    const stem = artifactStem(fileName);
+    return stem === channel || stem.endsWith(`-${channel}`) || stem.endsWith(`_${channel}`);
+}
 /**
  * 需要「HTML → ZIP」兜底的渠道：交付与后端校验（PlatformValidatorService）都要求 ZIP，
  * 但 devkit（第三方）可能只产出单文件 HTML。
@@ -50,7 +68,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 +126,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 +142,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 +201,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 +232,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 文件来合并配置
@@ -290,14 +292,23 @@ export class PlayableScriptsAdapter {
         // fflate 压缩：config 指定 > 项目 builds.config.js > PlayCraft 默认 true
         const fflate = this.resolveFflateCompression();
         args.push('--fflate-compression', `${fflate}`);
-        // 渠道列表
-        if (config.channels && config.channels.length > 0) {
-            const mappedChannels = config.channels
-                .filter(ch => !UNSUPPORTED_CHANNELS.has(ch))
-                .map(ch => mapChannel(ch));
-            if (mappedChannels.length > 0) {
-                args.push('--channels', mappedChannels.join(','));
-            }
+        // 渠道列表：单渠道与多渠道统一走 `builds --channels <...>`
+        // 缺失时退回 validation.channel（沙箱 runner / worker / CLI 都会传本次渠道）；
+        // 仍为空说明调用方没给渠道 —— devkit 会按项目 builds.config.js 构建**全部**渠道，
+        // 平台侧如果只要单渠道就会多出大量产物，这里显式告警。
+        const requestedChannels = config.channels && config.channels.length > 0
+            ? config.channels
+            : this.options.validation?.channel
+                ? [this.options.validation.channel]
+                : [];
+        const mappedChannels = requestedChannels
+            .filter(ch => !UNSUPPORTED_CHANNELS.has(ch))
+            .map(ch => mapChannel(ch));
+        if (mappedChannels.length > 0) {
+            args.push('--channels', mappedChannels.join(','));
+        }
+        else {
+            console.warn('[PlayableScriptsAdapter] ⚠️ 未指定目标渠道：devkit 将按项目配置构建全部渠道');
         }
         // 商店跳转地址
         if (config.storeUrls) {
@@ -432,24 +443,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 +450,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 +467,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 +534,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,8 +924,18 @@ export class PlayableScriptsAdapter {
         }
     }
     /**
-     * 确保 package.json 中有 build/builds 脚本
-     * devkit 必须通过 npm script 调用，不能直接执行 .js 文件
+     * 确保 package.json 的 `builds` 脚本存在，且**内容确实是 `playable-scripts builds`**。
+     *
+     * 为什么不能只判断"存在"：我们最终执行的是 `pnpm run builds`，如果项目里的 `builds`
+     * 还写着老命令 `playable-scripts build`（老模板 / 手工改过），即使平台代码已经统一，
+     * 实际跑的仍是单渠道 legacy 命令 —— 输出布局、默认 network/protocol、是否追加 preview
+     * 都会跟 `builds` 不一样，等于历史问题复活。
+     *
+     * 处理策略（保留前置步骤，如 `node scripts/generate-levels.js &&`）：
+     *   1. 已是 `playable-scripts builds` → 不动
+     *   2. 存在但含 `playable-scripts build` → 就地改写为 `builds`
+     *   3. 不存在 → 从 `build` 脚本推导（保留其前置步骤），否则注入纯 `playable-scripts builds`
+     *   4. 存在但完全自定义（不含 playable-scripts）→ 直接报错，避免静默跑错命令
      */
     async ensureBuildScripts() {
         const pkgPath = path.join(this.projectDir, 'package.json');
@@ -982,25 +945,37 @@ 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');
+            // `\b` 在 build|s 之间不成立，所以 build\b 不会误匹配 builds
+            const BUILDS_CMD = /\bplayable-scripts\s+builds\b/;
+            const LEGACY_BUILD_CMD = /\bplayable-scripts\s+build\b/;
+            const currentBuilds = typeof pkg.scripts.builds === 'string' ? pkg.scripts.builds : '';
+            const currentBuild = typeof pkg.scripts.build === 'string' ? pkg.scripts.build : '';
+            if (BUILDS_CMD.test(currentBuilds)) {
+                return;
+            }
+            if (currentBuilds.trim()) {
+                if (!LEGACY_BUILD_CMD.test(currentBuilds)) {
+                    throw new Error(`[PlayableScriptsAdapter] package.json 的 scripts.builds 不是 playable-scripts builds：` +
+                        `"${currentBuilds}"。单渠道与多渠道统一要求通过 builds 构建，请修正该脚本后重试。`);
+                }
+                pkg.scripts.builds = currentBuilds.replace(LEGACY_BUILD_CMD, 'playable-scripts builds');
+                console.log(`[PlayableScriptsAdapter] 修复 legacy builds 脚本: "${currentBuilds}" -> "${pkg.scripts.builds}"`);
             }
-            if (modified) {
-                await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2), 'utf-8');
-                console.log('[PlayableScriptsAdapter] ✓ package.json 已更新');
+            else {
+                // 从 build 脚本推导，保留其前置步骤（如 node scripts/generate-levels.js &&）
+                pkg.scripts.builds = LEGACY_BUILD_CMD.test(currentBuild)
+                    ? currentBuild.replace(LEGACY_BUILD_CMD, 'playable-scripts builds')
+                    : 'playable-scripts builds';
+                console.log(`[PlayableScriptsAdapter] 注入 package.json script: builds -> "${pkg.scripts.builds}"`);
             }
+            await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2), 'utf-8');
+            console.log('[PlayableScriptsAdapter] ✓ package.json 已更新');
         }
         catch (error) {
+            // 主动抛出的错误（自定义 builds 脚本）需要冒泡，不能吞掉
+            if (error instanceof Error && error.message.includes('不是 playable-scripts builds')) {
+                throw error;
+            }
             console.warn('[PlayableScriptsAdapter] ⚠️ 无法更新 package.json:', error.message);
         }
     }
@@ -1104,13 +1079,28 @@ export class PlayableScriptsAdapter {
                         channel = firstPart;
                     }
                     else {
-                        // 可能是主题目录（没有渠道子目录）
-                        // 这种情况不太可能，但保留兼容性
+                        // devkit 正式布局是 dist/<theme>/<file>（见 core/batch-build.js copyTempFiles：
+                        // 「最终结构：outputDir/themeName/*.zip|*.html」），这里记下主题，渠道从文件名补判
                         theme = firstPart;
                     }
                 }
                 // parts.length === 1: 直接在 dist 下的文件（单渠道模式）
+                // 路径判断不出渠道时，按 devkit 命名 `<主题>-<渠道>[_L|_P].<ext>` 从文件名补判。
+                // 不做这一步会导致所有产物都是 unknown，目标渠道过滤（尤其 preview）全部失效。
+                if (channel === 'unknown') {
+                    const matched = targetChannels.find((ch) => artifactMatchesChannel(entry.name, ch));
+                    if (matched) {
+                        channel = matched;
+                    }
+                    else if (artifactMatchesChannel(entry.name, 'preview')) {
+                        // devkit 固定追加 preview 渠道产出预览文件（core/batch-build.js 无条件 push），
+                        // 文件名同样带 -preview 后缀
+                        channel = 'preview';
+                    }
+                }
                 // 过滤：只收集目标渠道的产物
+                // 注：devkit 无论 `--channels` 传什么都会额外构建 preview 渠道（用于上传预览），
+                // 非 preview 构建必须把它排除，否则 preview.html 会顶掉目标渠道的 zip。
                 if (targetChannels.length > 0 && channel !== 'unknown' && !targetChannels.includes(channel)) {
                     console.log(`[PlayableScriptsAdapter] 跳过非目标渠道: ${channel} (文件: ${relativePath})`);
                     continue;
@@ -1125,29 +1115,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 {
-            // 目录不存在，无需清理
-        }
-    }
     /**
      * 递归删除目录
      */
@@ -1178,7 +1145,7 @@ export class PlayableScriptsAdapter {
         // 判断构建模式
         const isBatchMode = (this.config?.channels && this.config.channels.length > 1) ||
             (this.config?.themes?.enabled);
-        // 按渠道分组产物（每个渠道只保留一个产物，优先 HTML，其次 ZIP）
+        // 按渠道分组产物（每个渠道只保留一个交付产物，选择规则见 pickOutputForChannel）
         const channelOutputs = new Map();
         for (const output of outputs) {
             const channelList = channelOutputs.get(output.channel) || [];
@@ -1195,19 +1162,7 @@ export class PlayableScriptsAdapter {
             }
         }
         for (const [channel, channelFiles] of channelOutputs) {
-            // 选择最佳产物：优先带渠道名的文件，其次 HTML，最后 ZIP
-            let bestOutput = channelFiles[0];
-            for (const output of channelFiles) {
-                // 优先选择带有完整命名的文件（如 xxx-facebook.html）
-                if (output.fileName.includes(channel) || output.fileName.includes('-')) {
-                    bestOutput = output;
-                    break;
-                }
-                // 其次优先 HTML
-                if (output.fileName.endsWith('.html') && bestOutput.fileName.endsWith('.zip')) {
-                    bestOutput = output;
-                }
-            }
+            const bestOutput = this.pickOutputForChannel(channel, channelFiles);
             // 确定目标文件名
             let destFileName;
             // HTML 文件统一重命名为 index.html（与 PlayCanvas 项目保持一致）
@@ -1260,6 +1215,54 @@ export class PlayableScriptsAdapter {
         console.log(`[PlayableScriptsAdapter] 产物已复制到: ${this.options.outputDir}`);
         return files;
     }
+    /**
+     * 从同一渠道的多个产物中选出交付用的那一个。
+     *
+     * 旧实现是「文件名含 `-` 就 break，其次 HTML 优先」，在 devkit 扁平布局下会把
+     * `xxx-preview.html` 选成目标渠道产物（snapchat 构建最终交付了预览 html）。
+     *
+     * 现在的优先级（打分）：
+     *   1. 文件名命中目标渠道（devkit 命名 `<主题>-<渠道>[_L|_P].<ext>`）  +4
+     *   2. 与请求格式一致（请求 zip 优先 .zip，请求 html 优先 .html）        +2
+     *   3. zip 兜底（同为候选时优先交付压缩包）                            +1
+     *   4. 无方向后缀的基准产物优先                                        +0.5
+     *
+     * 出现多份等价产物时打印完整候选清单，避免再出现「静默挑了一个错的」。
+     */
+    pickOutputForChannel(channel, channelFiles) {
+        if (channelFiles.length <= 1)
+            return channelFiles[0];
+        const wantedExt = this.isZipOutput() ? '.zip' : '.html';
+        const scoreOf = (file) => {
+            const name = file.fileName.toLowerCase();
+            let score = 0;
+            if (channel !== 'unknown' && artifactMatchesChannel(file.fileName, channel.toLowerCase())) {
+                score += 4;
+            }
+            if (name.endsWith(wantedExt))
+                score += 2;
+            if (name.endsWith('.zip'))
+                score += 1;
+            if (!/_[lp]\.(html|zip)$/i.test(name))
+                score += 0.5;
+            return score;
+        };
+        const ranked = [...channelFiles].sort((a, b) => {
+            const diff = scoreOf(b) - scoreOf(a);
+            return diff !== 0 ? diff : a.fileName.localeCompare(b.fileName);
+        });
+        if (ranked.length > 1 && scoreOf(ranked[0]) === scoreOf(ranked[1])) {
+            console.warn(`[PlayableScriptsAdapter] 渠道 ${channel} 存在多份等价产物，已按文件名选择 ${ranked[0].fileName}` +
+                `（候选: ${ranked.map((file) => file.fileName).join(', ')}）`);
+        }
+        const chosen = ranked[0];
+        const expectedExt = this.isZipOutput() ? '.zip' : '.html';
+        if (!chosen.fileName.toLowerCase().endsWith(expectedExt)) {
+            console.warn(`[PlayableScriptsAdapter] 渠道 ${channel} 请求格式为 ${expectedExt.slice(1)}，` +
+                `但可用产物中没有该格式，将使用 ${chosen.fileName}（下游可能报格式不符）`);
+        }
+        return chosen;
+    }
     /**
      * 是否对 playable-scripts 使用 --zip。
      * 双格式渠道默认 HTML；仅在请求或配置显式选择 ZIP 时传递 --zip。

package/package.json

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