@playcraft/cli 0.1.63 → 0.1.65

package/README.md

@@ -258,16 +258,16 @@ PLAYCRAFT_TOOL_REQUEST_ID=<错误中显示的请求编号> playcraft tools build
 
 ### 构建相关
 
-| 命令             | 说明                                     | 示例                                                   |
-| ---------------- | ---------------------------------------- | ------------------------------------------------------ |
-| `build`          | 完整打包（阶段1 + 阶段2）                | `playcraft build --platform facebook`                  |
-| `build-base`     | 仅执行阶段1（生成多文件产物）            | `playcraft build-base ./src --output ./build`          |
-| `build-playable` | 仅执行阶段2（从多文件产物生成 Playable） | `playcraft build-playable ./build --platform facebook` |
-| `analyze`        | 生成打包分析报告                         | `playcraft analyze --platform facebook`                |
+| 命令             | 说明                                           | 示例                                                   |
+| ---------------- | ---------------------------------------------- | ------------------------------------------------------ |
+| `build`          | 本地构建预览，产物为 `dist/preview/index.html` | `playcraft build`                                      |
+| `build-base`     | 仅执行阶段1（生成多文件产物）                  | `playcraft build-base ./src --output ./build`          |
+| `build-playable` | 仅执行阶段2（从多文件产物生成 Playable）       | `playcraft build-playable ./build --platform facebook` |
+| `analyze`        | 生成打包分析报告                               | `playcraft analyze --platform facebook`                |
 
 ## 🎯 支持的平台
 
-现已支持 **10 个主流广告平台**：
+平台导出支持以下主流广告平台（渠道包通过平台导出生成，`playcraft build` 只做本地预览构建）：
 
 | 平台              | 格式     | 大小限制             | SDK/API      |
 | ----------------- | -------- | -------------------- | ------------ |
@@ -296,45 +296,39 @@ playcraft start --project your-project-id
 # 3. 在本地 IDE 编辑代码，云端编辑器自动同步
 ```
 
-### 打包 Playable Ads
+### 本地构建预览
 
 ```bash
-# Facebook 平台（ZIP，Phaser 产物格式）
-playcraft build --platform facebook --format zip --output ./dist/facebook
-
-# Snapchat 平台（ZIP）
-playcraft build --platform snapchat --format zip --output ./dist/snapchat
-
-# 批量打包所有平台
-for platform in facebook snapchat ironsource applovin google tiktok unity liftoff moloco bigo; do
-  playcraft build --platform $platform --output ./dist/$platform
-done
+# 在项目根目录构建，产物固定为 dist/preview/index.html
+playcraft build
 ```
 
+`playcraft build` 不提供渠道、格式和输出目录参数，各广告平台的渠道包请通过平台导出生成。下方的优化参数只影响本地预览，平台导出不会读取它们。
+
 ### 构建优化
 
 ```bash
 # 🎬 场景选择（推荐！可减小 30-60% 文件大小）
 # 交互式选择（自动检测多个场景并提示）
-playcraft build --platform facebook
+playcraft build
 
 # 指定特定场景
-playcraft build --platform facebook --scenes BallGame
+playcraft build --scenes BallGame
 
 # 指定多个场景
-playcraft build --platform facebook --scenes "MainMenu,Gameplay,Settings"
+playcraft build --scenes "MainMenu,Gameplay,Settings"
 
 # 启用图片压缩
-playcraft build --platform facebook --compress-images --image-quality 75
+playcraft build --compress-images --image-quality 75
 
 # 启用模型压缩
-playcraft build --platform facebook --compress-models --model-compression draco
+playcraft build --compress-models --model-compression draco
 
 # 生成分析报告
-playcraft build --platform facebook --analyze
+playcraft build --analyze
 
 # 组合使用（场景选择 + 图片压缩 + 分析）
-playcraft build --platform facebook --scenes MainScene --compress-images --analyze
+playcraft build --scenes MainScene --compress-images --analyze
 ```
 
 ## ⚙️ 配置
@@ -350,9 +344,6 @@ playcraft build --platform facebook --scenes MainScene --compress-images --analy
     "dir": "./"
   },
   "build": {
-    "platform": "facebook",
-    "format": "html",
-    "outputDir": "./dist",
     "useVite": true,
     "compressImages": true,
     "imageQuality": 75,
@@ -370,6 +361,8 @@ playcraft build --platform facebook --scenes MainScene --compress-images --analy
 3. 配置文件（`playcraft.config.json`）
 4. 默认值
 
+`build` 字段只为本地构建补充命令行没有给出的优化参数。`playcraft build` 的渠道、格式和输出位置是固定的，配置文件里的 `platform`、`format`、`outputDir` 对它不起作用；渠道包请通过平台导出生成，平台导出不读取这个文件。
+
 ## 📁 数据目录
 
 CLI 会在 `~/.playcraft/` 目录下存储：
@@ -384,7 +377,7 @@ CLI 会在 `~/.playcraft/` 目录下存储：
 当项目包含多个场景时，CLI 会自动提供交互式场景选择：
 
 ```bash
-playcraft build --platform facebook
+playcraft build
 ```
 
 **交互界面**：
@@ -411,10 +404,10 @@ playcraft build --platform facebook
 
 ```bash
 # 指定单个场景
-playcraft build --platform facebook --scenes MainScene
+playcraft build --scenes MainScene
 
 # 指定多个场景
-playcraft build --platform facebook --scenes "MainScene,Gameplay"
+playcraft build --scenes "MainScene,Gameplay"
 ```
 
 详见：[场景选择功能文档](../../docs/cli/scene-selection-feature.md)

package/SKILLS_REGISTRY.md

@@ -90,7 +90,7 @@ playcraft skills registry platform push ./playcraft-video-understanding-1.0.1.ta
 playcraft skills registry platform push ./playcraft-replica-validation-1.0.1.tar.gz --changelog '更新复刻验收指引与评估用例' --json
 ```
 
-`platform push <source>` 接受完整目录或已准备的压缩包。目录必须已含原生 `manifest.json`；命令保留其文件内容，不补充托管技能默认字段。已有压缩包原样发送，不重打包。可选的 `--ref`、`--version` 必须与清单一致；可用 `--evaluation-template <templateId>` 指定初始评估模板。原生入口当前仅接受上述两个引用，要求平台类型、单一 `sandbox-agent` surface、对齐的名称与版本、无 imports/relationships；服务端执行完整校验与摘要归一化，并返回最终 `artifactHash`。登记不会自动评估、审核或发布。
+`platform push <source>` 接受完整目录或已准备的压缩包。目录必须已含原生 `manifest.json`；命令保留其文件内容，不补充托管技能默认字段。已有压缩包原样发送，不重打包。可选的 `--ref`、`--version` 必须与清单一致；可用 `--evaluation-template <templateId>` 指定初始评估模板。原生入口按公共内置技能表允许引用，包含上述两项视频指南及显式导入的 `remix/playcraft-procedural-3d`、`remix/playcraft-model-adaptation`；要求平台类型、单一 `sandbox-agent` surface、对齐的名称与版本、无 imports/relationships。服务端执行完整校验与摘要归一化，并返回最终 `artifactHash`。登记不会自动评估、审核或发布。模型适配指南的独立源版本与门禁见[发布说明](../skills/docs/model-adaptation-skill-release.md)。
 
 此入口要求具有平台管理权限的真实账号凭据；命令复用目标环境登录，不发送本地身份模拟请求头。服务端需已部署允许真实管理员个人访问令牌访问原生登记和评估接口的版本。
 

package/dist/commands/3d.js

@@ -1,6 +1,10 @@
 import { existsSync, mkdirSync, readFileSync, statSync, } from 'fs';
 import { basename, dirname, extname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import { inspectModelSourceFiles } from '../model-adaptation/source.js';
+import { generateModelAdaptationProject } from '../model-adaptation/project.js';
+import { optimizeModel } from '../model-optimization/optimize.js';
+import { registerModelPreparationCommands } from '../model-preparation/commands.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PRIMITIVES_DIR = join(__dirname, '../../assets/models/primitives');
 const PRIMITIVES_METADATA = join(PRIMITIVES_DIR, 'metadata.json');
@@ -302,46 +306,23 @@ function registerOptimizeCmd(parent) {
         .requiredOption('--input <path>', 'Input GLB file')
         .requiredOption('--output <path>', 'Output optimized GLB file')
         .option('--texture-size <n>', 'Max texture dimension (default: 512)', '512')
+        .option('--texture-format <format>', 'Explicit texture format: png or jpeg (opaque color textures only)')
+        .option('--quality <n>', 'JPEG texture quality, 1–100 (default: 85)', '85')
+        .option('--textures-only', 'Preserve geometry and node structure; do not deduplicate or prune')
+        .option('--max-output-bytes <n>', 'Reject output larger than this explicit byte budget')
+        .option('--lineage <path>', 'New independent optimization receipt (default: <output>.optimization.json)')
         .option('--target-size <s>', 'Target size hint (e.g. 200KB) — informational only')
         .action(async (opts) => {
         try {
-            const { NodeIO, TextureChannel } = await import('@gltf-transform/core');
-            const { dedup, prune } = await import('@gltf-transform/functions');
-            void TextureChannel; // unused but imported for type context
-            if (!existsSync(opts.input)) {
-                console.error(`Error: input file not found: ${opts.input}`);
-                process.exit(1);
-            }
-            const origSize = statSync(opts.input).size;
-            const io = new NodeIO();
-            const doc = await io.read(opts.input);
-            const maxTexSize = parseInt(opts.textureSize, 10);
-            const sharp = (await import('sharp')).default;
-            // Resize textures that exceed maxTexSize using sharp
-            const textures = doc.getRoot().listTextures();
-            for (const tex of textures) {
-                const imgData = tex.getImage();
-                if (!imgData)
-                    continue;
-                const meta = await sharp(Buffer.from(imgData)).metadata();
-                const w = meta.width ?? 0;
-                const h = meta.height ?? 0;
-                if (w > maxTexSize || h > maxTexSize) {
-                    const resized = await sharp(Buffer.from(imgData))
-                        .resize(maxTexSize, maxTexSize, { fit: 'inside', withoutEnlargement: true })
-                        .png()
-                        .toBuffer();
-                    tex.setImage(new Uint8Array(resized)).setMimeType('image/png');
-                }
-            }
-            await doc.transform(dedup(), prune());
-            ensureOutputDir(opts.output);
-            await io.write(opts.output, doc);
-            const outSize = statSync(opts.output).size;
+            const optimized = await optimizeModel({ input: opts.input, output: opts.output, textureSize: Number(opts.textureSize),
+                textureFormat: opts.textureFormat, quality: Number(opts.quality), texturesOnly: opts.texturesOnly,
+                maxOutputBytes: opts.maxOutputBytes === undefined ? undefined : Number(opts.maxOutputBytes), lineagePath: opts.lineage });
+            const origSize = optimized.lineage.before.modelBytes, outSize = optimized.lineage.after.modelBytes;
             const saving = origSize - outSize;
             const savingPct = ((saving / origSize) * 100).toFixed(1);
             console.log(`Optimized: ${opts.output}`);
             console.log(`  ${sizeLabel(origSize)} → ${sizeLabel(outSize)} (saved ${sizeLabel(saving)}, ${savingPct}%)`);
+            console.log(`  Lineage: ${optimized.lineagePath}`);
         }
         catch (e) {
             handleError(e);
@@ -360,4 +341,31 @@ export function register3DCommands(program) {
     registerApplyTextureCmd(threeD);
     registerConvertCmd(threeD);
     registerOptimizeCmd(threeD);
+    registerModelPreparationCommands(threeD);
+    threeD.command('inspect-source <model>').description('Inspect saved-model dependencies without rendering or inference')
+        .option('--project-root <directory>', 'Source project directory', process.cwd()).option('--json', 'Output structured source metadata')
+        .action(async (model, options) => {
+        try {
+            const result = await inspectModelSourceFiles({ projectRoot: options.projectRoot, modelPath: model });
+            console.log(JSON.stringify({ source: result.source, packedHash: result.packedHash, metadata: result.metadata, modelInference: false, acceptance: false }, null, 2));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    threeD.command('adapt-project').description('Prepare a new rigid-model adaptation project without building or publishing')
+        .requiredOption('--config <file>', 'Source-bound adaptation configuration').option('--project-root <directory>', 'Source project directory', process.cwd())
+        .requiredOption('--output <directory>', 'New output directory').option('--candidate-id <id>', 'Explicit source candidate identity')
+        .option('--fixture-only', 'Mark an engineering fixture without granting acceptance')
+        .action(async (options) => {
+        try {
+            const result = await generateModelAdaptationProject({ projectRoot: options.projectRoot, planPath: options.config, outputRoot: options.output,
+                candidateId: options.candidateId, fixtureOnly: options.fixtureOnly });
+            console.log(JSON.stringify({ outputRoot: result.outputRoot, source: result.manifest.source, coreHash: result.manifest.coreHash,
+                packedHash: result.manifest.packedHash, geometryValidation: result.manifest.geometryValidation, modelInference: false, acceptance: false }, null, 2));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }

package/dist/commands/build.js

@@ -8,9 +8,10 @@ import { cleanupBuildTempDirectory, createBuildTempDirectory } from './build-tem
 import inquirer from 'inquirer';
 import { tmpdir } from 'node:os';
 import { generatedWorkspace } from '../workspace-runtime/workspaces/artifact-receipts.js';
-import { isolateWorkspaceForBuild } from '../workspace-runtime/workspaces/delivery-build.js';
+import { isolateWorkspaceForBuild } from '../workspace-runtime/workspaces/build-isolation.js';
 import { finalizeWorkspacePlayable, readWorkspacePlayable, workspacePlayableSignature } from '../workspace-runtime/previews/finalize.js';
 import { AgentApiClient } from '../utils/agent-api-client.js';
+import { WORKSPACE_PLAYABLE_OUTPUT_PATH } from '@playcraft/common/cloud-workspace/runtime';
 /**
  * 类型守卫：检查对象是否符合 PlayableScriptsConfig 类型
  */
@@ -247,13 +248,52 @@ async function analyzeBaseBuild(baseBuildDir, ammoReplacement) {
         suggestedEngine: ammoCheck.suggestedEngine,
     };
 }
+/**
+ * Format and clean the former `playcraft build` flags carried. Vite and draco model compression are
+ * already the builder's defaults, and leaving them unset lets playcraft.config.json supply them.
+ */
+const BUILD_DEFAULTS = { format: 'html', clean: true };
+/**
+ * `playcraft build`: a local review build of the current project. It always produces one HTML file at
+ * `dist/preview/index.html`; channel packaging is done by platform export, not by this command. The
+ * tuning options (compression, scenes, engine, ...) apply to this preview only.
+ * `output` and `base` are internal: the preview publisher builds into its own scratch folder, and the
+ * batch runtime only needs the multi-file base build.
+ */
+export async function previewBuildCommand(projectPath, options = {}) {
+    const { output, base, ...tuning } = options;
+    const project = path.resolve(projectPath);
+    if (base)
+        return buildCommand(project, { ...BUILD_DEFAULTS, ...tuning, mode: 'base', ...(output ? { output } : {}) });
+    const preview = { ...BUILD_DEFAULTS, ...tuning, mode: 'full', platform: 'playcraft' };
+    if (output)
+        return buildCommand(project, { ...preview, output });
+    const workspace = process.env.PLAYCRAFT_BUILD_ISOLATED !== '1' ? await generatedWorkspace(project) : undefined;
+    // A workspace build isolates, validates and publishes the canonical preview itself.
+    if (workspace?.root === project)
+        return buildCommand(project, preview);
+    const scratch = await fs.mkdtemp(path.join(tmpdir(), 'playcraft-preview-build-'));
+    try {
+        await buildCommand(project, { ...preview, output: scratch });
+        const entries = await fs.readdir(scratch, { withFileTypes: true });
+        if (entries.length !== 1 || !entries[0].isFile() || !entries[0].name.endsWith('.html'))
+            throw new Error('preview_not_single_file');
+        const target = path.join(project, WORKSPACE_PLAYABLE_OUTPUT_PATH);
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.copyFile(path.join(scratch, entries[0].name), target);
+        console.log(target);
+    }
+    finally {
+        await fs.rm(scratch, { recursive: true, force: true });
+    }
+}
 export async function buildCommand(projectPath, options) {
     // 解析项目路径 - 在 spinner 之前执行以便调试
     const resolvedProjectPath = path.resolve(projectPath);
     const workspace = options.workspaceArtifact !== false && process.env.PLAYCRAFT_BUILD_ISOLATED !== '1' && options.mode === 'full' && options.platform === 'playcraft'
         && (!options.format || options.format === 'html') ? await generatedWorkspace(resolvedProjectPath) : undefined;
     const requestedOutput = options.output ? path.resolve(options.output) : path.join(resolvedProjectPath, 'dist');
-    const canonicalOutput = [path.join(resolvedProjectPath, 'dist'), path.join(resolvedProjectPath, 'dist/playable')].includes(requestedOutput);
+    const canonicalOutput = [path.join(resolvedProjectPath, 'dist'), path.join(resolvedProjectPath, path.dirname(WORKSPACE_PLAYABLE_OUTPUT_PATH))].includes(requestedOutput);
     if (workspace?.root === resolvedProjectPath) {
         const prefix = requestedOutput.endsWith(path.sep) ? requestedOutput : `${requestedOutput}${path.sep}`;
         if (requestedOutput === workspace.root || workspace.root.startsWith(prefix))
@@ -269,7 +309,7 @@ export async function buildCommand(projectPath, options) {
                 if (entries.length !== 1 || !entries[0].isFile() || !entries[0].name.endsWith('.html'))
                     throw new Error('preview_not_single_file');
                 await finalizeWorkspacePlayable(workspace.root, await fs.readFile(path.join(output, entries[0].name)), 'playcraft build', { expectedSignature: signature });
-                console.log(path.join(workspace.root, 'dist/playable/index.html'));
+                console.log(path.join(workspace.root, WORKSPACE_PLAYABLE_OUTPUT_PATH));
                 try {
                     const { bytes } = await readWorkspacePlayable(workspace.root);
                     const { previewUrl } = await new AgentApiClient().publishWorkspacePlayable({ workspaceId: workspace.workspaceId, directoryName: path.basename(workspace.root) }, bytes);
@@ -744,7 +784,32 @@ export async function buildCommand(projectPath, options) {
             ...(options.tracking === false ? { tracking: { enabled: false } } : {}),
         };
         if (fileConfig) {
-            Object.assign(buildOptions, fileConfig);
+            // playcraft.config.json 只补充调用方没有给出的参数：显式参数，以及上面已确定的渠道、格式和
+            // 输出目录始终优先（playcraft build 固定这三项，配置文件不能把它改成渠道包或别的输出位置）。
+            const explicit = {
+                platform: buildOptions.platform,
+                format: buildOptions.format,
+                outputDir: buildOptions.outputDir,
+                compressEngine: options.compress,
+                compressConfigJson: options.compressConfig,
+                compressJS: options.compressJs,
+                analyze: options.analyze,
+                useVite: options.useVite,
+                cssMinify: options.cssMinify,
+                jsMinify: options.jsMinify,
+                compressImages: options.compressImages,
+                imageQuality: options.imageQuality,
+                convertToWebP: options.convertToWebP,
+                compressModels: options.compressModels,
+                modelCompression: options.modelCompression,
+                esmMode: options.esmMode,
+                storeUrls: options.storeUrls,
+                tracking: options.tracking === false ? false : undefined,
+            };
+            for (const [key, value] of Object.entries(fileConfig)) {
+                if (explicit[key] === undefined)
+                    Object.assign(buildOptions, { [key]: value });
+            }
         }
         buildOptions.validation = {
             ...buildOptions.validation,
@@ -760,7 +825,7 @@ export async function buildCommand(projectPath, options) {
             if (isEditorProject) {
                 throw new Error('检测到这是 PlayCanvas 编辑器项目，不是多文件构建产物。\n\n' +
                     '请使用以下命令之一：\n' +
-                    '  1. playcraft build <项目路径>          # 完整构建（推荐）\n' +
+                    '  1. playcraft build <项目路径>          # 本地构建预览（推荐）\n' +
                     '  2. playcraft build-base <项目路径>     # 先生成多文件产物\n' +
                     '     playcraft build-playable <产物路径> # 再转换为 Playable\n\n' +
                     '💡 提示: build-playable 命令仅用于已有的多文件构建产物');

package/dist/commands/create.js

@@ -1067,8 +1067,8 @@ function printCreateNextSteps(template, _targetDir, name, here, worktree) {
         console.log(`  ${pc.cyan('playcraft remix init-template --from-atom-tree')}`);
         console.log(`  ${pc.cyan('npm run verify:contract && npm run dev')}`);
         console.log();
-        console.log(pc.dim('如需使用 PlayCraft CLI 打渠道包：'));
-        console.log(`  ${pc.cyan('playcraft build . -p facebook')}`);
+        console.log(pc.dim('本地构建预览（产物在 dist/preview/index.html，渠道包请使用平台导出）：'));
+        console.log(`  ${pc.cyan('playcraft build .')}`);
         console.log();
         console.log(pc.dim('正式接入 PlayCraft 后，替换项目 ID：'));
         console.log(`  ${pc.cyan('playcraft config set --key projectId --value <真实项目ID>')}`);
@@ -1081,8 +1081,8 @@ function printCreateNextSteps(template, _targetDir, name, here, worktree) {
         console.log(`  ${pc.cyan('npm run build -- google')}`);
         console.log(`  ${pc.cyan('npm run builds')}`);
         console.log();
-        console.log(pc.dim('或使用 PlayCraft CLI：'));
-        console.log(`  ${pc.cyan(`playcraft build ${here ? '.' : name} -p facebook`)}`);
+        console.log(pc.dim('或使用 PlayCraft CLI 本地构建预览（产物在 dist/preview/index.html）：'));
+        console.log(`  ${pc.cyan(`playcraft build ${here ? '.' : name}`)}`);
     }
     console.log();
 }

package/dist/commands/inspect.js

@@ -106,18 +106,16 @@ export async function inspectCommand(projectPath) {
         console.log('\n' + pc.bold('💡 建议:\n'));
         if (projectType === 'build') {
             console.log(pc.green('✅ 这是一个构建后的项目，可以直接打包为 Playable Ad'));
-            console.log(pc.dim('   运行: playcraft build --platform facebook'));
+            console.log(pc.dim('   运行: playcraft build'));
         }
         else if (projectType === 'playcraft-source' || projectType === 'playcanvas-source') {
             console.log(pc.yellow('⚠️  这是源代码项目，建议先构建再打包\n'));
             console.log(pc.cyan('方式 1 (推荐): 使用 PlayCanvas REST API 构建'));
             console.log(pc.dim('   1. 在 PlayCanvas Editor 中发布项目'));
             console.log(pc.dim('   2. 使用 REST API 下载构建'));
-            console.log(pc.dim('   3. 运行: playcraft build --platform facebook\n'));
-            console.log(pc.cyan('方式 2: 使用本地构建（实验性功能）'));
-            console.log(pc.dim('   运行: playcraft build --platform facebook --auto-build\n'));
-            console.log(pc.cyan('方式 3: 直接从源代码打包（可能不完整）'));
-            console.log(pc.dim('   运行: playcraft build --platform facebook --skip-build'));
+            console.log(pc.dim('   3. 运行: playcraft build\n'));
+            console.log(pc.cyan('方式 2: 直接本地构建'));
+            console.log(pc.dim('   运行: playcraft build'));
         }
         else {
             console.log(pc.red('❌ 无法识别项目类型，请确保:'));

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command, CommanderError } from 'commander';
+import { Command, CommanderError, Option } from 'commander';
 import { accountActivationMessage } from './auth/messages.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
@@ -11,7 +11,7 @@ import { stopCommand } from './commands/stop.js';
 import { statusCommand } from './commands/status.js';
 import { logsCommand } from './commands/logs.js';
 import { configCommand } from './commands/config.js';
-import { buildCommand } from './commands/build.js';
+import { buildCommand, previewBuildCommand } from './commands/build.js';
 import { buildAllCommand } from './commands/build-all.js';
 import { upgradeCommand } from './commands/upgrade.js';
 import { checkForUpdates } from './utils/version-checker.js';
@@ -174,28 +174,34 @@ program
         token: options.token,
     });
 });
-// build 命令 - 完整流程（阶段1 + 阶段2）
+/**
+ * 只保留命令行上显式给出的参数。commander 的默认值与构建器默认值相同，去掉后 playcraft.config.json
+ * 才能补充这些参数；否则默认值会被当成显式参数，压过配置文件。
+ */
+function explicitOptions(command) {
+    const options = command.opts();
+    return Object.fromEntries(Object.keys(options)
+        .filter(key => command.getOptionValueSource(key) !== 'default')
+        .map(key => [key, options[key]]));
+}
+/** commander 把 --convert-webp / --no-convert-webp 解析成 convertWebp，构建器使用的字段是 convertToWebP。 */
+function withConvertToWebP({ convertWebp, ...options }) {
+    return { ...options, convertToWebP: convertWebp };
+}
+// build 命令 - 本地构建当前项目用于 review，产物固定为 dist/preview/index.html；渠道导出走平台导出
 program
     .command('build')
-    .description('打包项目为 Playable Ad（自动执行基础构建和渠道打包）')
+    .description('本地构建当前项目，产物输出到 dist/preview/index.html（渠道导出请使用平台导出）')
     .argument('[project-path]', '项目路径', process.cwd())
-    .option('-p, --platform <platform>', '目标平台 (facebook|snapchat|ironsource|applovin|google|tiktok|unity|liftoff|moloco|bigo|inmobi|adikteev|remerge|mintegral)')
-    .option('-f, --format <format>', '输出格式 (html|zip)', 'html')
-    .option('-o, --output <path>', '输出目录', './dist')
     .option('-c, --config <file>', '配置文件路径')
     .option('-s, --scenes <scenes>', '选择场景: "all"=所有场景, "default"=默认场景, 或逗号分隔的场景名,如 "MainMenu,Gameplay"')
     .option('-e, --engine <engine>', '指定引擎类型 (playcanvas|phaser|pixijs|threejs|cocos|babylonjs|layaair|egret|generic)，默认自动检测')
-    .option('--clean', '构建前清理旧的输出目录（默认启用）', true)
-    .option('--no-clean', '跳过清理旧的输出目录')
     .option('--compress', '压缩引擎代码（使用 LZ4，仅 PlayCanvas）')
     .option('--compress-config', '压缩 config.json（使用 LZ4，可减少 60-70% 体积，仅 PlayCanvas）')
     .option('--compress-js', '压缩所有 JS 代码（LZ4 源码保护，浏览器中无法查看变量名和方法名）')
     .option('--analyze', '生成打包分析报告')
     .option('--replace-ammo', '检测到 Ammo 时自动替换为 p2 或 cannon（仅 PlayCanvas）')
     .option('--ammo-engine <engine>', '指定替换物理引擎 (p2|cannon)，仅 PlayCanvas')
-    .option('--auto-build', '如果是源代码项目，自动执行本地构建')
-    .option('--skip-build', '跳过本地构建，直接从源代码打包（可能不完整）')
-    .option('--mode <mode>', '构建模式 (full|base|playable)')
     .option('--use-vite', '使用 Vite 构建（默认启用）', true)
     .option('--no-use-vite', '禁用 Vite，使用旧构建器')
     .option('--css-minify', '压缩 CSS（默认根据平台配置）')
@@ -212,8 +218,10 @@ program
     .option('--model-compression <method>', '模型压缩方法 (draco|meshopt)', 'draco')
     .option('--use-playable-scripts', '使用 @playcraft/devkit 构建工具打包（可玩广告项目专用）', false)
     .option('--no-tracking', '禁用埋点 tracking adapter 注入（默认启用）')
-    .action(async (projectPath, options) => {
-    await buildCommand(projectPath, options);
+    .addOption(new Option('-o, --output <path>').hideHelp())
+    .addOption(new Option('--base').hideHelp())
+    .action(async (projectPath, _options, command) => {
+    await previewBuildCommand(projectPath, withConvertToWebP(explicitOptions(command)));
 });
 // build-base 命令 - 只执行阶段1：基础构建
 program
@@ -262,9 +270,9 @@ program
     .option('--model-compression <method>', '模型压缩方法 (draco|meshopt)', 'draco')
     .option('--esm-mode <mode>', 'ESM 模块处理模式 (auto|enabled|disabled)', 'auto')
     .option('--no-tracking', '禁用埋点 tracking adapter 注入（默认启用）')
-    .action(async (projectPath, options) => {
+    .action(async (projectPath, _options, command) => {
     await buildCommand(projectPath, {
-        ...options,
+        ...withConvertToWebP(explicitOptions(command)),
         analyze: true,
     });
 });
@@ -300,9 +308,9 @@ program
     .option('--model-compression <method>', '模型压缩方法 (draco|meshopt)', 'draco')
     .option('--esm-mode <mode>', 'ESM 模块处理模式 (auto|enabled|disabled)', 'auto')
     .option('--no-tracking', '禁用埋点 tracking adapter 注入（默认启用）')
-    .action(async (baseBuildDir, options) => {
+    .action(async (baseBuildDir, _options, command) => {
     await buildCommand(baseBuildDir, {
-        ...options,
+        ...withConvertToWebP(explicitOptions(command)),
         mode: 'playable',
     });
 });
@@ -343,7 +351,7 @@ program
     .option('--theme <theme>', '指定要构建的主题（devkit 项目专用）')
     .option('--no-tracking', '禁用埋点 tracking adapter 注入（默认启用）')
     .action(async (projectPath, options) => {
-    await buildAllCommand(projectPath, options);
+    await buildAllCommand(projectPath, withConvertToWebP(options));
 });
 // 新增：inspect 命令 - 检查项目类型
 program