@playcraft/cli 0.1.63 → 0.1.65

package/dist/workspace-runtime/workspaces/model-preparation.js

@@ -0,0 +1,357 @@
+import { chmod, chown, lstat, mkdir, mkdtemp, readFile, readdir, realpath, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { canonicalModelAdaptation, hashOperationPayload, modelPreparationPayloadSchema, modelPreparationReceiptSchema, transitionOperation, } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRoot, revisionScope } from './registry.js';
+import { runDeveloperCommand } from './developer-command.js';
+import { openScratchToDevelopment } from './directory-access.js';
+import { stopLauncherExecution } from '../codex/launcher-client.js';
+import { assertOperationDirectoryAccess } from '../server/directory-access.js';
+import { ModelPreparationStore, promotePreparationProject, targetPreparationSnapshot } from './model-preparation-store.js';
+import { hash, hashData, preparationInventory, readPreparationFile, readPreparationJson, writePreparationJson } from '../../model-preparation/pipeline-files.js';
+const active = new WeakMap();
+const tasks = new WeakMap();
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const identity = (payload) => { const { resumeFromReceiptHash: _resume, ...value } = payload; return hashData(value); };
+const requestKey = (workspaceId, payload) => hashData({ workspaceId, pipelineId: payload.pipelineId, stepId: payload.stepId });
+export async function preparationToolManifest() {
+    const files = ['model-preparation/pipeline-worker.js', 'model-preparation/pipeline-engine.js', 'model-preparation/pipeline-files.js',
+        'model-preparation/glb.js', 'model-preparation/geometry.js', 'model-preparation/split-rigid.js', 'model-preparation/vertex-repairs.js',
+        'model-adaptation/node-inspection.js', 'model-adaptation/source.js', 'model-adaptation/project.js', 'model-adaptation/project-template.js',
+        'model-optimization/optimize.js', 'workspace-runtime/workspaces/model-preparation.js', 'workspace-runtime/workspaces/model-preparation-store.js'];
+    const common = createRequire(import.meta.url).resolve('@playcraft/common/cloud-workspace/runtime');
+    const manifest = await Promise.all(files.map(async (path) => ({ path, contentHash: hash(await readFile(new URL(`../../../dist/${path}`, import.meta.url))) })));
+    const visitCommon = async (path, prefix = '') => {
+        for (const entry of await readdir(path, { withFileTypes: true })) {
+            if (entry.isSymbolicLink())
+                throw Error('model_prepare_tool_path_unsafe');
+            const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                await visitCommon(join(path, entry.name), name);
+            else if (entry.name.endsWith('.js'))
+                manifest.push({ path: `common/${name}`, contentHash: hash(await readFile(join(path, entry.name))) });
+        }
+    };
+    await visitCommon(dirname(common));
+    const require = createRequire(import.meta.url), threeRoot = dirname(dirname(require.resolve('three')));
+    for (const [name, path] of [['three-module', join(threeRoot, 'build/three.module.js')], ['three-core', join(threeRoot, 'build/three.core.js')],
+        ['three-loader', require.resolve('three/examples/jsm/loaders/GLTFLoader.js')], ['earcut', require.resolve('earcut')],
+        ...Object.keys(require.cache).filter(path => /sharp.*\.node$/.test(path)).sort().map((path, index) => [`sharp-native-${index}`, path])])
+        manifest.push({ path: `dependency/${name}`, contentHash: hash(await readFile(path)) });
+    manifest.push({ path: 'cli/package.json', contentHash: hash(await readFile(new URL('../../../package.json', import.meta.url))) });
+    manifest.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+    return { schemaVersion: 1, files: manifest, toolHash: hashData(manifest) };
+}
+async function seal(path, groupId) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink())
+        throw Error('model_prepare_path_unsafe');
+    if (stat.gid !== groupId)
+        await chown(path, stat.uid, groupId);
+    if (stat.isDirectory()) {
+        for (const entry of await readdir(path))
+            await seal(join(path, entry), groupId);
+        await chmod(path, 0o550);
+    }
+    else
+        await chmod(path, 0o440);
+}
+async function verifyOriginalSource(root, record) {
+    for (const file of record.sourceSnapshot ?? []) {
+        const actual = await readPreparationFile(root, file.path), before = record.sourceStats?.find(item => item.path === file.path);
+        if (actual.contentHash !== file.contentHash || actual.bytes.length !== file.bytes || before &&
+            ['ino', 'dev', 'size', 'mtimeMs', 'ctimeMs'].some(key => actual.stat[key] !== before[key]))
+            throw Error('model_prepare_source_changed');
+    }
+}
+async function snapshotSource(root, store, record) {
+    const files = [], stats = [];
+    let total = 0;
+    for (const file of record.payload.source.files) {
+        if (file.path.split('/').includes('.playcraft'))
+            throw Error('model_prepare_source_path_unsafe');
+        const actual = await readPreparationFile(root, file.path);
+        total += actual.bytes.length;
+        if (actual.contentHash !== file.contentHash || total > 128 * 1024 * 1024)
+            throw Error('model_prepare_source_identity_mismatch');
+        const path = join(store.root, 'source', file.path);
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 }); // private: controller-only preparation state
+        await writeFile(path, actual.bytes, { flag: 'wx', mode: 0o600 }).catch(async (error) => { if (error.code !== 'EEXIST' || hash(await readFile(path)) !== file.contentHash)
+            throw error; }); // private: controller-only preparation state
+        files.push({ ...file, bytes: actual.bytes.length });
+        const { ino, dev, size, mtimeMs, ctimeMs } = actual.stat;
+        stats.push({ path: file.path, ino, dev, size, mtimeMs, ctimeMs });
+    }
+    record.sourceSnapshot = files;
+    record.sourceStats = stats;
+    await verifyOriginalSource(root, record);
+    record.phase = 'snapshotted';
+    await store.write(record);
+}
+function receipt(record, status, reasonCode) {
+    const result = record.result;
+    const base = { kind: 'model-preparation', schemaVersion: 1, pipelineId: record.pipelineId, stepId: record.stepId,
+        status, ...(reasonCode ? { reasonCode } : {}), inputHash: record.inputHash, sourceScope: record.payload.sourceScope, source: record.payload.source,
+        ...(status === 'prepared' && result ? { model: result.model, adaptationPath: result.adaptationPath, adaptationHash: result.adaptationHash,
+            manifestPath: '.playcraft/model-build-inputs.json', modelBytes: result.modelBytes, triangles: result.triangles,
+            lineageFiles: result.lineageFiles, writePaths: record.transaction?.files.map(file => file.path) ?? [] } : { lineageFiles: [], writePaths: record.transaction?.published ?? [] }),
+        toolHash: record.toolHash, browserValidation: 'pending', modelAcceptance: false };
+    return modelPreparationReceiptSchema.parse({ ...base, receiptHash: hashData(base) });
+}
+export async function readModelPreparation(state, workspaceId, directoryName, pipelineId, stepId) {
+    await workspaceRoot(state, workspaceId, directoryName);
+    const record = await new ModelPreparationStore(state.config.stateDir, workspaceId, directoryName, pipelineId, stepId).read();
+    return record?.receipt ?? null;
+}
+export function trackModelPreparation(state, task) {
+    const known = tasks.get(state) ?? new Set();
+    tasks.set(state, known);
+    known.add(task);
+    void task.finally(() => known.delete(task)).catch(() => undefined);
+}
+export async function stopModelPreparations(state) {
+    for (const controller of active.get(state)?.values() ?? [])
+        controller.abort();
+    await Promise.allSettled([...(tasks.get(state) ?? [])]);
+}
+/** A controlled local step creates source and receipts; it never installs, builds, infers or validates a game. */
+export async function runModelPreparation(state, operation, value, options) {
+    const payload = modelPreparationPayloadSchema.parse(value);
+    if (!operation.workspaceId || operation.directoryName !== 'basic' || payload.targetDirectoryName !== 'basic' ||
+        state.journal.getWorkspace(operation.workspaceId)?.targetKind !== 'standalone')
+        throw Error('model_prepare_target_scope_invalid');
+    const target = await workspaceRoot(state, operation.workspaceId, 'basic'), source = await workspaceRoot(state, payload.sourceScope.workspaceId, payload.sourceScope.directoryName);
+    const store = new ModelPreparationStore(state.config.stateDir, operation.workspaceId, 'basic', payload.pipelineId, payload.stepId);
+    const tools = await preparationToolManifest(), inputHash = hashOperationPayload(payload), semanticInputHash = identity(payload), key = requestKey(operation.workspaceId, payload);
+    const known = active.get(state) ?? new Map();
+    active.set(state, known);
+    if (known.has(key))
+        throw Error('model_prepare_already_running');
+    let record = await store.read();
+    if (record && (record.semanticInputHash !== semanticInputHash || record.toolHash !== tools.toolHash))
+        throw Error('model_prepare_resume_identity_mismatch');
+    if (payload.resumeFromReceiptHash && record?.receipt?.receiptHash !== payload.resumeFromReceiptHash)
+        throw Error('model_prepare_resume_receipt_mismatch');
+    if (record?.phase === 'uncertain' || record?.phase === 'running')
+        throw Error('model_prepare_recovery_required');
+    if (record?.receipt) {
+        if (record.inputHash !== inputHash) {
+            await writePreparationJson(join(store.root, 'receipts', `${record.receipt.receiptHash}.json`), record.receipt);
+            record.inputHash = inputHash;
+            record.payload = payload;
+            record.receipt = receipt(record, record.receipt.status, record.receipt.reasonCode);
+            await store.write(record);
+        }
+        return record.receipt;
+    }
+    const assertCurrent = async () => {
+        if (state.journal.destroyed() || (operation.leaseFence ?? 0) < state.acceptedLeaseFence || operation.generation !== state.config.generation || operation.runtimeEpoch !== state.runtimeEpoch)
+            throw Error('model_prepare_stale_operation');
+        await assertOperationDirectoryAccess(state, operation, 'exclusive');
+    };
+    await assertCurrent();
+    const controller = new AbortController();
+    known.set(key, controller);
+    const writeId = `model-prepare-${operation.gatewayOperationId ?? operation.operationId}`;
+    let stopped = true;
+    try {
+        const ownerPath = join(dirname(dirname(store.root)), 'target-owner.json');
+        const owner = await readPreparationJson(dirname(ownerPath), 'target-owner.json');
+        if (owner && owner.pipelineId !== payload.pipelineId)
+            throw Error('model_prepare_target_owned');
+        if (!owner)
+            await writePreparationJson(ownerPath, { pipelineId: payload.pipelineId, workspaceId: operation.workspaceId, directoryName: 'basic' });
+        if (!record) {
+            const targetSnapshot = await targetPreparationSnapshot(target);
+            if (payload.expectedTargetSnapshotHash && hashData(targetSnapshot) !== payload.expectedTargetSnapshotHash)
+                throw Error('model_prepare_target_changed');
+            record = { schemaVersion: 1, pipelineId: payload.pipelineId, stepId: payload.stepId, workspaceId: operation.workspaceId, directoryName: 'basic',
+                inputHash, semanticInputHash, toolHash: tools.toolHash, payload, phase: 'planned', createdAt: new Date().toISOString(), targetSnapshot };
+            await store.write(record);
+            await writePreparationJson(join(store.root, 'tools.json'), tools);
+        }
+        record.inputHash = inputHash;
+        record.payload = payload;
+        await store.write(record);
+        await writePreparationJson(join(state.config.stateDir, 'model-preparations', 'operations', `${operation.operationId}.json`), {
+            workspaceId: operation.workspaceId, directoryName: 'basic', pipelineId: payload.pipelineId, stepId: payload.stepId,
+        });
+        if (!record.sourceSnapshot)
+            await snapshotSource(source, store, record);
+        else
+            await verifyOriginalSource(source, record);
+        if (!record.result) {
+            let scratch = record.scratch;
+            if (scratch && !await lstat(scratch).then(value => value.isDirectory() && !value.isSymbolicLink(), () => false)) {
+                await writePreparationJson(join(store.root, 'lost-scratch', `${Date.now()}.json`), { path: scratch, reason: 'worker-scratch-unavailable', stagesRecomputedOnExplicitResume: true });
+                scratch = undefined;
+            }
+            if (!scratch) {
+                scratch = await realpath(await mkdtemp(join(tmpdir(), 'playcraft-model-prepare-')));
+                const groupId = (await lstat(target)).gid;
+                await openScratchToDevelopment(scratch, groupId);
+                await chmod(scratch, 0o750);
+                const inputRoot = join(scratch, 'input');
+                await mkdir(inputRoot);
+                for (const file of record.sourceSnapshot ?? []) {
+                    const bytes = (await readPreparationFile(join(store.root, 'source'), file.path)).bytes, destination = join(inputRoot, file.path);
+                    await mkdir(dirname(destination), { recursive: true });
+                    await writeFile(destination, bytes, { flag: 'wx' });
+                }
+                await seal(inputRoot, groupId);
+                await mkdir(join(scratch, 'output'));
+                await openScratchToDevelopment(join(scratch, 'output'), groupId);
+                const configPath = join(scratch, 'input.json');
+                await writePreparationJson(configPath, { payload, sourceRoot: inputRoot, outputRoot: join(scratch, 'output'), toolHash: tools.toolHash, tools });
+                await seal(configPath, groupId);
+                record.scratch = scratch;
+                await store.write(record);
+            }
+            const configPath = join(scratch, 'input.json'), configHash = hash(await readFile(configPath));
+            const config = JSON.parse(await readFile(configPath, 'utf8'));
+            if (identity(modelPreparationPayloadSchema.parse(config.payload)) !== semanticInputHash || config.toolHash !== tools.toolHash || hashData(config.tools) !== hashData(tools) ||
+                config.sourceRoot !== join(scratch, 'input') || config.outputRoot !== join(scratch, 'output'))
+                throw Error('model_prepare_worker_input_changed');
+            record.phase = 'running';
+            await store.write(record);
+            const outcome = await runDeveloperCommand(state, { processId: writeId, cwd: scratch,
+                command: `${quote(process.execPath)} --max-old-space-size=768 ${quote(options.workerPath ?? fileURLToPath(new URL('../../../dist/model-preparation/pipeline-worker.js', import.meta.url)))} ${quote(configPath)} ${quote(configHash)}`,
+                timeoutMs: 600_000, signal: controller.signal, onOutput: () => undefined,
+                onStarted: async (process) => {
+                    stopped = false;
+                    await state.journal.putManagedWrite({ writeId,
+                        workspaceId: revisionScope(state, operation.workspaceId, 'basic') ?? 'single', source: 'manual', directoryAccessMode: 'exclusive',
+                        startedAt: new Date().toISOString(), pid: process.pid,
+                        ...(process.launcher ? { executionMode: 'launcher', launcher: process.launcher, runtimeEpoch: state.runtimeEpoch } : { executionMode: 'local' }) });
+                } });
+            stopped = outcome.code !== undefined;
+            if (!stopped)
+                throw Error('model_prepare_process_unknown');
+            const writer = state.journal.listManagedWrites().find(item => item.writeId === writeId);
+            if (writer)
+                await state.journal.putManagedWrite({ ...writer, stoppedAt: new Date().toISOString() });
+            if (outcome.canceled)
+                throw Error('model_prepare_cancelled');
+            if (outcome.timedOut)
+                throw Error('model_prepare_timeout');
+            if (outcome.code !== 0)
+                throw Error('model_prepare_worker_failed');
+            const result = await readPreparationJson(join(scratch, 'output'), 'result.json', 8 * 1024 * 1024);
+            if (!result)
+                throw Error('model_prepare_worker_receipt_missing');
+            if (result.status === 'blocked') {
+                if (!/^([a-z]+_)+[a-z]+$/.test(result.reasonCode))
+                    throw Error('model_prepare_worker_receipt_invalid');
+                record.phase = 'blocked';
+                record.receipt = receipt(record, 'blocked', result.reasonCode);
+                await store.write(record);
+                return record.receipt;
+            }
+            if (result.status !== 'prepared' || !/^adapt-[a-f0-9-]{36}\/project$/.test(relative(join(scratch, 'output'), result.projectRoot)) ||
+                await realpath(result.projectRoot) !== result.projectRoot)
+                throw Error('model_prepare_worker_receipt_invalid');
+            const actual = await preparationInventory(result.projectRoot);
+            if (canonicalModelAdaptation(actual) !== canonicalModelAdaptation(result.files))
+                throw Error('model_prepare_worker_output_changed');
+            const produced = join(store.root, 'produced');
+            await mkdir(produced, { recursive: true, mode: 0o700 }); // private: controller-only preparation state
+            for (const file of actual) {
+                const bytes = (await readPreparationFile(result.projectRoot, file.path)).bytes, path = join(produced, file.path);
+                if (hash(bytes) !== file.contentHash)
+                    throw Error('model_prepare_worker_output_changed');
+                await mkdir(dirname(path), { recursive: true, mode: 0o700 }); // private: controller-only preparation state
+                await writeFile(path, bytes, { flag: 'wx', mode: 0o600 }).catch(async (error) => { if (error.code !== 'EEXIST' || hash(await readFile(path)) !== file.contentHash)
+                    throw error; }); // private: controller-only preparation state
+            }
+            if (canonicalModelAdaptation(await preparationInventory(produced)) !== canonicalModelAdaptation(actual))
+                throw Error('model_prepare_worker_output_changed');
+            record.result = { ...result, projectRoot: produced };
+            record.phase = 'produced';
+            await store.write(record);
+        }
+        if ((await preparationToolManifest()).toolHash !== tools.toolHash)
+            throw Error('model_prepare_tool_changed');
+        await verifyOriginalSource(source, record);
+        await assertCurrent();
+        if (payload.sourceScope.workspaceId === operation.workspaceId && payload.sourceScope.directoryName === 'basic') {
+            const writePaths = new Set(record.result.files.filter(file => !['AGENTS.md', 'README.md'].includes(file.path)).map(file => file.path));
+            if (payload.source.files.some(file => writePaths.has(file.path)))
+                throw Error('model_prepare_source_output_overlap');
+        }
+        await promotePreparationProject(store, target, record, { assertCurrent, onFile: options.onFile, signal: controller.signal });
+        await verifyOriginalSource(source, record);
+        record.phase = 'prepared';
+        record.receipt = receipt(record, 'prepared');
+        await store.write(record);
+        return record.receipt;
+    }
+    catch (error) {
+        if (record && stopped && error instanceof Error && /^model_prepare_(target_changed|source_changed|source_identity_mismatch|target_unsafe|source_output_overlap)$/.test(error.message)) {
+            record.phase = 'blocked';
+            record.receipt = receipt(record, 'blocked', error.message);
+            await store.write(record);
+            return record.receipt;
+        }
+        if (record) {
+            record.phase = stopped ? 'interrupted' : 'uncertain';
+            await store.write(record);
+        }
+        throw error;
+    }
+    finally {
+        known.delete(key);
+    }
+}
+/** Startup never relaunches a partial worker; it only confirms process termination and retains stages. */
+export async function recoverModelPreparationOperations(state, recovery) {
+    for (const { operation, scopeKey } of state.journal.listOperations()) {
+        if (operation.kind !== 'model.prepare' || !operation.workspaceId || !['dispatched', 'accepted', 'uncertain'].includes(operation.status))
+            continue;
+        const id = operation.gatewayOperationId ?? operation.operationId, writer = state.journal.listManagedWrites().find(item => item.writeId === `model-prepare-${id}`);
+        let stopped = Boolean(writer?.stoppedAt);
+        if (writer && !stopped) {
+            if (recovery.confirmStopped)
+                stopped = await recovery.confirmStopped(writer);
+            else if (writer.executionMode === 'launcher' && recovery.identityMatches && recovery.launcherSocket && writer.launcher && writer.launcher.processId === writer.writeId) {
+                if (recovery.previousRuntimeEpoch !== undefined && recovery.runtimeEpoch !== undefined && recovery.runtimeEpoch > recovery.previousRuntimeEpoch && writer.launcher.runtimeEpoch < recovery.runtimeEpoch)
+                    stopped = true;
+                else
+                    try {
+                        await stopLauncherExecution(recovery.launcherSocket, writer.launcher);
+                        stopped = true;
+                    }
+                    catch { /* retain uncertain */ }
+            }
+            else if (writer.executionMode === 'local' && writer.pid) {
+                const absent = (pid) => { try {
+                    process.kill(pid, 0);
+                    return false;
+                }
+                catch (error) {
+                    return error.code === 'ESRCH';
+                } };
+                stopped = absent(writer.pid) && absent(-writer.pid);
+            }
+        }
+        const binding = await readPreparationJson(state.config.stateDir, `model-preparations/operations/${operation.operationId}.json`);
+        const store = binding?.workspaceId === operation.workspaceId && binding.directoryName === 'basic'
+            ? new ModelPreparationStore(state.config.stateDir, binding.workspaceId, binding.directoryName, binding.pipelineId, binding.stepId) : undefined;
+        const record = await store?.read();
+        // onStarted persists the writer before opening its stdin gate; absent writer means it never ran.
+        if (!writer)
+            stopped = true;
+        if (writer && stopped && !writer.stoppedAt)
+            await state.journal.putManagedWrite({ ...writer, stoppedAt: new Date().toISOString() });
+        if (record?.receipt && stopped) {
+            await state.journal.putOperation(scopeKey, transitionOperation(operation, 'completed', { result: record.receipt }));
+            continue;
+        }
+        if (record && store) {
+            record.phase = stopped ? 'interrupted' : 'uncertain';
+            await store.write(record);
+        }
+        await state.journal.putOperation(scopeKey, transitionOperation(operation, stopped ? 'interrupted' : 'uncertain', { error: stopped ? 'model_prepare_interrupted' : 'model_prepare_process_unknown' }));
+    }
+}

package/dist/workspace-runtime/workspaces/platform-export.js

@@ -123,6 +123,7 @@ export async function startPlatformExport(state, input) {
             commitHash: commit,
             platforms: input.channels,
             clientRequestId: input.clientRequestId,
+            ...(input.options && Object.keys(input.options).length ? { options: input.options } : {}),
         },
     });
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "private": false,
   "type": "module",
   "engines": {
@@ -53,8 +53,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.63",
-    "@playcraft/common": "0.1.63",
+    "@playcraft/build": "0.1.65",
+    "@playcraft/common": "0.1.65",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
@@ -62,6 +62,7 @@
     "cosmiconfig": "^9.0.0",
     "dotenv": "^17.2.3",
     "drizzle-orm": "^0.45.1",
+    "earcut": "3.2.4",
     "execa": "^9.6.1",
     "express": "^5.2.1",
     "fluent-ffmpeg": "^2.1.3",
@@ -76,11 +77,13 @@
     "picocolors": "^1.1.1",
     "playwright-core": "1.52.0",
     "sharp": "^0.34.5",
+    "three": "0.183.2",
     "update-notifier": "^7.3.1",
     "ws": "^8.19.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@noble/hashes": "2.0.1",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/fluent-ffmpeg": "^2.1.28",
@@ -91,7 +94,6 @@
     "@types/update-notifier": "^6.0.8",
     "@types/ws": "^8.18.1",
     "esbuild": "^0.28.1",
-    "three": "^0.183.2",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   }

package/project-template/.claude/skills/playcraft-build-optimizer/SKILL.md

@@ -30,11 +30,11 @@ triggers: 构建优化,build optimizer,压缩,compress,WebP,pngquant,文件大
 
 ```bash
 # 检查最终输出文件大小
-playcraft image info --input dist/index.html --json  # 不适用，用 shell
+playcraft image info --input dist/preview/index.html --json  # 不适用，用 shell
 
 # Shell 方法：检查文件大小（字节）
-du -sh dist/index.html
-ls -lh dist/index.html
+du -sh dist/preview/index.html
+ls -lh dist/preview/index.html
 
 # 计算：若当前原始资产总大小为 X MB
 # 预计最终 HTML 大小 ≈ X × 1.33（Base64 膨胀）
@@ -112,34 +112,31 @@ grep -r "\.play()" game/ --include="*.js" --include="*.ts"
 
 ## 2. playcraft build 优化参数
 
+- 产物固定为单文件 `dist/preview/index.html`，用于本地 review；在云工作区中它就是产物面板里的可玩预览。
+- 下列参数只影响这份本地预览。渠道包（Meta、Google、AppLovin 等）只能通过平台导出生成，导出不会读取本地 build 的参数，渠道体积以导出时的校验为准。
+
 ### 完整优化构建命令
 
 ```bash
-# 标准优化构建（Meta 平台）
+# 标准优化构建
 playcraft build . \
-  --platform facebook \
   --compress-images \
   --image-quality 85 \
   --convert-webp \
   --js-minify \
-  --css-minify \
-  --output dist/
+  --css-minify
 
 # 带 3D 模型压缩的构建
 playcraft build . \
-  --platform facebook \
   --compress-images \
   --image-quality 80 \
   --convert-webp \
   --compress-models \
   --model-compression draco \
-  --js-minify \
-  --output dist/
+  --js-minify
 
 # 分析体积占用（不构建，只分析）
-playcraft build . \
-  --platform facebook \
-  --analyze
+playcraft build . --analyze
 ```
 
 ### 图片优化参数
@@ -170,25 +167,6 @@ playcraft build . \
 | `--js-minify`  | 启用 JS 压缩（Terser + 混淆） |
 | `--css-minify` | 启用 CSS 压缩                 |
 
-### 多平台批量构建
-
-```bash
-# 同时构建多个平台版本
-playcraft build-all . \
-  --platforms facebook,google,applovin \
-  --compress-images \
-  --image-quality 85 \
-  --convert-webp \
-  --js-minify \
-  --output dist/
-
-# 或按平台组
-playcraft build-all . \
-  --group mainstream \   # 主流平台
-  --compress-images \
-  --convert-webp
-```
-
 ---
 
 ## 3. 正确的优化执行顺序
@@ -207,9 +185,11 @@ playcraft build-all . \
    ↓
 5. playcraft build --js-minify --css-minify — 代码压缩
    ↓
-6. 检查最终文件大小（必须 < 5 MB）
+6. 检查 dist/preview/index.html 大小（仅供参考，渠道体积以平台导出校验为准）
    ↓
 7. 合规验证清单（§1）
+   ↓
+8. 通过平台导出生成各渠道包
 ```
 
 **禁止行为**：
@@ -298,9 +278,9 @@ playcraft 3d optimize \
 
 ## 6. 常见审核被拒原因速查
 
-| 被拒原因          | 占比 | 检查方法                 | 修复方法                                                |
-| ----------------- | ---- | ------------------------ | ------------------------------------------------------- |
-| 文件大小超过 5 MB | 45%  | `ls -lh dist/index.html` | `--compress-images --convert-webp` 或降低 image-quality |
-| 包含外部请求      | 30%  | `grep -r "https://"`     | Developer 将外部资源内嵌                                |
-| CTA 未实现        | 15%  | `grep "FbPlayableAd"`    | Developer 添加平台 CTA API                              |
-| 音频自动播放      | 10%  | `grep "autoplay"`        | Developer 改为用户交互触发                              |
+| 被拒原因          | 占比 | 检查方法                         | 修复方法                                                |
+| ----------------- | ---- | -------------------------------- | ------------------------------------------------------- |
+| 文件大小超过 5 MB | 45%  | `ls -lh dist/preview/index.html` | `--compress-images --convert-webp` 或降低 image-quality |
+| 包含外部请求      | 30%  | `grep -r "https://"`             | Developer 将外部资源内嵌                                |
+| CTA 未实现        | 15%  | `grep "FbPlayableAd"`            | Developer 添加平台 CTA API                              |
+| 音频自动播放      | 10%  | `grep "autoplay"`                | Developer 改为用户交互触发                              |

package/project-templates/empty/AGENTS.md

@@ -65,7 +65,7 @@ The artifact panel shows final deliverables under `dist/` at the current project
 
 When a generated asset is ready for delivery, save or copy it into `dist/` with a stable relative path. Keep the resources required by a model or document within `dist/` and preserve their relative links. Reuse the same delivery path for a revised artifact so its versions remain grouped; the platform retains its history. Use different paths for independent candidates or deliverables.
 
-Run playable builds from the project root (`playcraft build --mode full --platform playcraft --format html .`). In a workspace this command builds in an isolated copy, validates the result, and retains the playable at `dist/playable/index.html` while preserving other deliverables. A successful agent command or turn that writes a valid self-contained HTML (HyperText Markup Language, 超文本标记语言) file at this same path is collected as the same playable preview. No separate publish action is required to view it. A base build's `dist/index.html` can still require resource files and remains a document. The page's generate-preview action rebuilds the current project through the same validation. After a successful build the command also publishes the playable and prints `Public URL: <address>`; when you report the build, link that address as the playable instead of the sandbox path, since it opens directly and can be shared. If the command prints `Public URL unavailable`, report that the build succeeded without a public address and give the reason it printed. Temporary `.playcraft-preview-out/` and `.playcraft-temp/` files are not deliverables. Preserve other artifacts already in `dist/` when rebuilding a playable.
+Run playable builds from the project root with `playcraft build`. It takes no channel or format options and always produces the review build at `dist/preview/index.html`; channel packages come only from platform export. In a workspace this command builds in an isolated copy, validates the result, and retains the playable at `dist/preview/index.html` while preserving other deliverables. A successful agent command or turn that writes a valid self-contained HTML (HyperText Markup Language, 超文本标记语言) file at this same path is collected as the same playable preview. No separate publish action is required to view it. A base build's `dist/index.html` can still require resource files and remains a document. The page's generate-preview action rebuilds the current project through the same validation. After a successful build the command also publishes the playable and prints `Public URL: <address>`; when you report the build, link that address as the playable instead of the sandbox path, since it opens directly and can be shared. If the command prints `Public URL unavailable`, report that the build succeeded without a public address and give the reason it printed. Temporary `.playcraft-preview-out/` and `.playcraft-temp/` files are not deliverables. Preserve other artifacts already in `dist/` when rebuilding a playable.
 
 Keep this convention in `AGENTS.md`, the project's standard instruction filename. Do not create a separate `AGENT.md`.
 

package/project-templates/phaser/.claude/skills/playcraft-build-optimizer/SKILL.md

@@ -30,11 +30,11 @@ triggers: 构建优化,build optimizer,压缩,compress,WebP,pngquant,文件大
 
 ```bash
 # 检查最终输出文件大小
-playcraft image info --input dist/index.html --json  # 不适用，用 shell
+playcraft image info --input dist/preview/index.html --json  # 不适用，用 shell
 
 # Shell 方法：检查文件大小（字节）
-du -sh dist/index.html
-ls -lh dist/index.html
+du -sh dist/preview/index.html
+ls -lh dist/preview/index.html
 
 # 计算：若当前原始资产总大小为 X MB
 # 预计最终 HTML 大小 ≈ X × 1.33（Base64 膨胀）
@@ -112,34 +112,31 @@ grep -r "\.play()" game/ --include="*.js" --include="*.ts"
 
 ## 2. playcraft build 优化参数
 
+- 产物固定为单文件 `dist/preview/index.html`，用于本地 review；在云工作区中它就是产物面板里的可玩预览。
+- 下列参数只影响这份本地预览。渠道包（Meta、Google、AppLovin 等）只能通过平台导出生成，导出不会读取本地 build 的参数，渠道体积以导出时的校验为准。
+
 ### 完整优化构建命令
 
 ```bash
-# 标准优化构建（Meta 平台）
+# 标准优化构建
 playcraft build . \
-  --platform facebook \
   --compress-images \
   --image-quality 85 \
   --convert-webp \
   --js-minify \
-  --css-minify \
-  --output dist/
+  --css-minify
 
 # 带 3D 模型压缩的构建
 playcraft build . \
-  --platform facebook \
   --compress-images \
   --image-quality 80 \
   --convert-webp \
   --compress-models \
   --model-compression draco \
-  --js-minify \
-  --output dist/
+  --js-minify
 
 # 分析体积占用（不构建，只分析）
-playcraft build . \
-  --platform facebook \
-  --analyze
+playcraft build . --analyze
 ```
 
 ### 图片优化参数
@@ -170,25 +167,6 @@ playcraft build . \
 | `--js-minify`  | 启用 JS 压缩（Terser + 混淆） |
 | `--css-minify` | 启用 CSS 压缩                 |
 
-### 多平台批量构建
-
-```bash
-# 同时构建多个平台版本
-playcraft build-all . \
-  --platforms facebook,google,applovin \
-  --compress-images \
-  --image-quality 85 \
-  --convert-webp \
-  --js-minify \
-  --output dist/
-
-# 或按平台组
-playcraft build-all . \
-  --group mainstream \   # 主流平台
-  --compress-images \
-  --convert-webp
-```
-
 ---
 
 ## 3. 正确的优化执行顺序
@@ -207,9 +185,11 @@ playcraft build-all . \
    ↓
 5. playcraft build --js-minify --css-minify — 代码压缩
    ↓
-6. 检查最终文件大小（必须 < 5 MB）
+6. 检查 dist/preview/index.html 大小（仅供参考，渠道体积以平台导出校验为准）
    ↓
 7. 合规验证清单（§1）
+   ↓
+8. 通过平台导出生成各渠道包
 ```
 
 **禁止行为**：
@@ -298,9 +278,9 @@ playcraft 3d optimize \
 
 ## 6. 常见审核被拒原因速查
 
-| 被拒原因          | 占比 | 检查方法                 | 修复方法                                                |
-| ----------------- | ---- | ------------------------ | ------------------------------------------------------- |
-| 文件大小超过 5 MB | 45%  | `ls -lh dist/index.html` | `--compress-images --convert-webp` 或降低 image-quality |
-| 包含外部请求      | 30%  | `grep -r "https://"`     | Developer 将外部资源内嵌                                |
-| CTA 未实现        | 15%  | `grep "FbPlayableAd"`    | Developer 添加平台 CTA API                              |
-| 音频自动播放      | 10%  | `grep "autoplay"`        | Developer 改为用户交互触发                              |
+| 被拒原因          | 占比 | 检查方法                         | 修复方法                                                |
+| ----------------- | ---- | -------------------------------- | ------------------------------------------------------- |
+| 文件大小超过 5 MB | 45%  | `ls -lh dist/preview/index.html` | `--compress-images --convert-webp` 或降低 image-quality |
+| 包含外部请求      | 30%  | `grep -r "https://"`             | Developer 将外部资源内嵌                                |
+| CTA 未实现        | 15%  | `grep "FbPlayableAd"`            | Developer 添加平台 CTA API                              |
+| 音频自动播放      | 10%  | `grep "autoplay"`                | Developer 改为用户交互触发                              |