@playcraft/cli 0.0.23 → 0.0.24

package/dist/cli-root-help.js

@@ -4,7 +4,7 @@ export function getCliTopicsHelpText() {
         '命令分区（完整说明见仓库 docs/cli/capabilities.md）：',
         '',
         '  本地开发   init, start, stop, status, logs, config, sync, fix-ids',
-        '  素材       tools generate-*  |  image <子命令>  |  audio <子命令>',
+        '  素材       tools generate-*  |  image <子命令>  |  audio <子命令>  |  prefab <子命令>',
         '  平台       build, build-base, build-playable, build-all, analyze, inspect, upgrade',
         '             tools 除 generate-* 外（Git / 沙箱构建 / 发布 / 列表 / Prefab 等，需后端 API）',
         '',

package/dist/commands/build.js

@@ -434,6 +434,7 @@ export async function buildCommand(projectPath, options) {
                 clean: shouldClean && !isSameAsInput, // 清理逻辑由 BaseBuilder 内部处理
                 analyze: options.analyze, // 传递 analyze 参数
                 engine: detectedEngine, // 传递引擎类型
+                ...(options.format ? { format: options.format } : {}),
             }, {
                 usePlayableScripts: isPlayableScripts,
                 playableScriptsConfig,
@@ -685,6 +686,8 @@ export async function buildCommand(projectPath, options) {
             ...(options.esmMode ? { esmMode: options.esmMode } : {}),
             // 商店跳转地址
             ...(options.storeUrls ? { storeUrls: options.storeUrls } : {}),
+            // Tracking 埋点（默认启用，--no-tracking 可关闭）
+            ...(options.tracking === false ? { tracking: { enabled: false } } : {}),
         };
         if (fileConfig) {
             Object.assign(buildOptions, fileConfig);
@@ -746,6 +749,7 @@ export async function buildCommand(projectPath, options) {
                 analyze: buildOptions.analyze,
                 analyzeReportPath: buildOptions.analyze ? 'base-bundle-report.html' : undefined,
                 engine: detectedEngine, // 传递引擎类型
+                format: buildOptions.format,
             }, {
                 usePlayableScripts: isPlayableScripts,
                 playableScriptsConfig,

package/dist/commands/image.js

@@ -13,6 +13,10 @@ function getMaxInputBytes() {
     }
     return DEFAULT_MAX_INPUT_BYTES;
 }
+/** Commander 会把上一值/默认值作为第二参数传入，不能直接用 `parseInt`（会当作 radix）。 */
+function cliParseInt(value) {
+    return Number.parseInt(value, 10);
+}
 function assertInputWithinLimit(filePath, label = 'input') {
     const max = getMaxInputBytes();
     const st = statSync(filePath);
@@ -66,8 +70,8 @@ export function registerImageCommands(program) {
         .description('缩放图片（按比例或指定宽高）')
         .requiredOption('--input <path>', '输入图片路径')
         .requiredOption('--output <path>', '输出图片路径')
-        .option('--width <n>', '目标宽度（像素）', parseInt)
-        .option('--height <n>', '目标高度（像素）', parseInt)
+        .option('--width <n>', '目标宽度（像素）', cliParseInt)
+        .option('--height <n>', '目标高度（像素）', cliParseInt)
         .option('--scale <factor>', '缩放比例（如 0.5 = 50%）', parseFloat)
         .option('--fit <mode>', 'contain|cover|fill|inside|outside', 'cover')
         .action(async (opts) => {
@@ -107,10 +111,10 @@ export function registerImageCommands(program) {
         .description('裁剪图片（指定区域）')
         .requiredOption('--input <path>', '输入图片路径')
         .requiredOption('--output <path>', '输出图片路径')
-        .requiredOption('--x <n>', '左边距（像素）', parseInt)
-        .requiredOption('--y <n>', '上边距（像素）', parseInt)
-        .requiredOption('--width <n>', '裁剪宽度（像素）', parseInt)
-        .requiredOption('--height <n>', '裁剪高度（像素）', parseInt)
+        .requiredOption('--x <n>', '左边距（像素）', cliParseInt)
+        .requiredOption('--y <n>', '上边距（像素）', cliParseInt)
+        .requiredOption('--width <n>', '裁剪宽度（像素）', cliParseInt)
+        .requiredOption('--height <n>', '裁剪高度（像素）', cliParseInt)
         .action(async (opts) => {
         try {
             assertInputWithinLimit(opts.input);
@@ -130,7 +134,7 @@ export function registerImageCommands(program) {
         .description('旋转图片')
         .requiredOption('--input <path>', '输入图片路径')
         .requiredOption('--output <path>', '输出图片路径')
-        .requiredOption('--angle <n>', '旋转角度（顺时针，如 90/180/270 或任意整数）', parseInt)
+        .requiredOption('--angle <n>', '旋转角度（顺时针，如 90/180/270 或任意整数）', cliParseInt)
         .option('--background <color>', '旋转后露出的背景色（CSS hex，如 #000000）', '#00000000')
         .action(async (opts) => {
         try {
@@ -180,11 +184,11 @@ export function registerImageCommands(program) {
         .description('扩展画布，在图片四周添加边距（保持原图居中）')
         .requiredOption('--input <path>', '输入图片路径')
         .requiredOption('--output <path>', '输出图片路径')
-        .option('--top <n>', '上边距（像素）', parseInt, 0)
-        .option('--bottom <n>', '下边距（像素）', parseInt, 0)
-        .option('--left <n>', '左边距（像素）', parseInt, 0)
-        .option('--right <n>', '右边距（像素）', parseInt, 0)
-        .option('--all <n>', '四周统一边距（覆盖单独方向设置）', parseInt)
+        .option('--top <n>', '上边距（像素）', cliParseInt, 0)
+        .option('--bottom <n>', '下边距（像素）', cliParseInt, 0)
+        .option('--left <n>', '左边距（像素）', cliParseInt, 0)
+        .option('--right <n>', '右边距（像素）', cliParseInt, 0)
+        .option('--all <n>', '四周统一边距（覆盖单独方向设置）', cliParseInt)
         .option('--background <color>', '背景色（CSS hex）', '#00000000')
         .action(async (opts) => {
         try {
@@ -210,7 +214,7 @@ export function registerImageCommands(program) {
         .requiredOption('--input <path>', '输入图片路径')
         .requiredOption('--output <path>', '输出图片路径（扩展名决定格式，或用 --format 强制指定）')
         .option('--format <fmt>', '目标格式 (png|jpg|webp|avif)，默认从输出路径扩展名推断')
-        .option('--quality <n>', '压缩质量 1-100（jpg/webp/avif 有效）', parseInt, 85)
+        .option('--quality <n>', '压缩质量 1-100（jpg/webp/avif 有效）', cliParseInt, 85)
         .option('--lossless', '无损压缩（webp/avif 有效）')
         .action(async (opts) => {
         try {
@@ -302,7 +306,7 @@ export function registerImageCommands(program) {
         .description('自动裁掉透明或纯色边界')
         .requiredOption('--input <path>', '输入图片路径')
         .requiredOption('--output <path>', '输出图片路径')
-        .option('--threshold <n>', '颜色容差（0-255，默认 10）', parseInt, 10)
+        .option('--threshold <n>', '颜色容差（0-255，默认 10）', cliParseInt, 10)
         .action(async (opts) => {
         try {
             assertInputWithinLimit(opts.input);
@@ -341,8 +345,8 @@ export function registerImageCommands(program) {
         .requiredOption('--base <path>', '底图路径')
         .requiredOption('--overlay <path>', '叠加图路径')
         .requiredOption('--output <path>', '输出图片路径')
-        .option('--x <n>', '叠加图 X 偏移（像素，默认居中）', parseInt)
-        .option('--y <n>', '叠加图 Y 偏移（像素，默认居中）', parseInt)
+        .option('--x <n>', '叠加图 X 偏移（像素，默认居中）', cliParseInt)
+        .option('--y <n>', '叠加图 Y 偏移（像素，默认居中）', cliParseInt)
         .option('--gravity <g>', '对齐方向（center|north|south|east|west...，--x/--y 优先）', 'center')
         .action(async (opts) => {
         try {
@@ -371,7 +375,7 @@ export function registerImageCommands(program) {
         .description('像素化图片（像素风格效果）')
         .requiredOption('--input <path>', '输入图片路径')
         .requiredOption('--output <path>', '输出图片路径')
-        .option('--pixel-size <n>', '像素块大小（默认 8）', parseInt, 8)
+        .option('--pixel-size <n>', '像素块大小（默认 8）', cliParseInt, 8)
         .action(async (opts) => {
         try {
             assertInputWithinLimit(opts.input);
@@ -397,10 +401,10 @@ export function registerImageCommands(program) {
         .description('将多张图合并为精灵图，并输出帧坐标 JSON（完整本地实现）')
         .requiredOption('--inputs <paths>', '输入图片路径列表，逗号分隔')
         .requiredOption('--output <basePath>', '输出基路径（自动生成 .png 和 .json）')
-        .option('--columns <n>', '列数（默认自动按平方根计算）', parseInt)
-        .option('--padding <n>', '帧间距（像素，默认 0）', parseInt, 0)
-        .option('--cell-width <n>', '统一格子宽度（不填则用第一张图宽度）', parseInt)
-        .option('--cell-height <n>', '统一格子高度（不填则用第一张图高度）', parseInt)
+        .option('--columns <n>', '列数（默认自动按平方根计算）', cliParseInt)
+        .option('--padding <n>', '帧间距（像素，默认 0）', cliParseInt, 0)
+        .option('--cell-width <n>', '统一格子宽度（不填则用第一张图宽度）', cliParseInt)
+        .option('--cell-height <n>', '统一格子高度（不填则用第一张图高度）', cliParseInt)
         .action(async (opts) => {
         try {
             const paths = opts.inputs.split(',').map((p) => p.trim()).filter(Boolean);

package/dist/commands/prefab.js

@@ -0,0 +1,502 @@
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+import JSON5 from 'json5';
+import { THEME_SCHEMA_PATH, THEME_INDEX_PATH, THEME_DIR, DEFAULT_GAME_PATH, MANIFEST_PATH, ASSETS_JSON_PATH, LITE_CREATOR_EXTENSIONS_DIR, themeDataPath, scenePath, defaultValueFromJsonSchemaProperty, buildThemeIndexTs, parseThemeIndexImportPath, parseThemePrefabs, mergeThemeDataKey, deleteThemeDataKey, parseExtensionMetaData, parseGameConfig, buildExtensionPrefabs, updateGameConfigValue, updateGameConfigExtensions, findConfigKeyCaseInsensitive, parseConfigKey, listScenesFromManifest, resolveGameConfigPath, validateThemeValue, validateConfigValue, describeJsonSchemaFields, describeConfigSchemaFields, } from '@playcraft/common/prefab';
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function resolveProjectDir(opts) {
+    return opts.projectDir ? resolve(opts.projectDir) : process.cwd();
+}
+function readLocalFile(projectDir, relPath) {
+    return readFileSync(join(projectDir, relPath), 'utf-8');
+}
+function fileExists(projectDir, relPath) {
+    return existsSync(join(projectDir, relPath));
+}
+function detectProjectType(projectDir) {
+    if (fileExists(projectDir, THEME_SCHEMA_PATH))
+        return 'external-theme';
+    if (fileExists(projectDir, DEFAULT_GAME_PATH))
+        return 'lite-creator';
+    console.error('Error: 无法识别项目类型。当前仅支持 External（需 src/theme/theme.schema.json5）' +
+        '和 PlayCanvas（需 assets/DefaultGame.json）两种项目类型。');
+    process.exit(1);
+    throw new Error('Project type could not be detected');
+}
+function outputJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+// ─── External Theme helpers ──────────────────────────────────────────────────
+function loadThemeSchema(projectDir) {
+    const raw = readLocalFile(projectDir, THEME_SCHEMA_PATH);
+    return JSON5.parse(raw.trim());
+}
+function loadThemeData(projectDir, themeId) {
+    const path = themeDataPath(themeId);
+    if (!fileExists(projectDir, path))
+        return {};
+    const raw = readLocalFile(projectDir, path);
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return {};
+    return JSON5.parse(trimmed);
+}
+function writeThemeData(projectDir, themeId, data) {
+    const relPath = themeDataPath(themeId);
+    const content = `${JSON5.stringify(data, null, 2)}\n`;
+    writeFileSync(join(projectDir, relPath), content, 'utf-8');
+}
+function listLocalThemeIds(projectDir) {
+    const themeDir = join(projectDir, THEME_DIR);
+    if (!existsSync(themeDir))
+        return [];
+    return readdirSync(themeDir)
+        .filter((name) => {
+        if (name.startsWith('.') || name === 'node_modules')
+            return false;
+        return statSync(join(themeDir, name)).isDirectory();
+    })
+        .sort();
+}
+function resolveActiveThemeId(projectDir) {
+    if (!fileExists(projectDir, THEME_INDEX_PATH))
+        return null;
+    const content = readLocalFile(projectDir, THEME_INDEX_PATH);
+    return parseThemeIndexImportPath(content);
+}
+function resolveThemeId(projectDir, opts) {
+    if (opts.variant)
+        return opts.variant;
+    const active = resolveActiveThemeId(projectDir);
+    if (active)
+        return active;
+    const themes = listLocalThemeIds(projectDir);
+    if (themes.length > 0)
+        return themes[0];
+    console.error('Error: 没有找到可用的主题。请使用 --variant 指定主题 ID。');
+    process.exit(1);
+}
+// ─── PlayCanvas / LiteCreator helpers ────────────────────────────────────────
+function loadGameConfig(projectDir, configPath) {
+    const raw = readLocalFile(projectDir, configPath);
+    return JSON.parse(raw);
+}
+function writeGameConfig(projectDir, configPath, data) {
+    writeFileSync(join(projectDir, configPath), JSON.stringify(data, null, 2), 'utf-8');
+}
+function scanExtensionMetaData(projectDir) {
+    const map = new Map();
+    const extDir = join(projectDir, LITE_CREATOR_EXTENSIONS_DIR);
+    if (!existsSync(extDir))
+        return map;
+    for (const folder of readdirSync(extDir)) {
+        const metaPath = join(extDir, folder, 'MetaData.json');
+        if (!existsSync(metaPath))
+            continue;
+        try {
+            const raw = readFileSync(metaPath, 'utf-8');
+            const meta = parseExtensionMetaData(JSON.parse(raw));
+            if (meta)
+                map.set(meta.name, meta);
+        }
+        catch { /* skip malformed */ }
+    }
+    return map;
+}
+function resolveGameConfigPathForVariant(projectDir, variantId) {
+    if (!variantId)
+        return DEFAULT_GAME_PATH;
+    if (!fileExists(projectDir, scenePath(variantId)))
+        return DEFAULT_GAME_PATH;
+    const sceneJson = JSON.parse(readLocalFile(projectDir, scenePath(variantId)));
+    if (!fileExists(projectDir, ASSETS_JSON_PATH))
+        return DEFAULT_GAME_PATH;
+    const assetsJson = JSON.parse(readLocalFile(projectDir, ASSETS_JSON_PATH));
+    const resolved = resolveGameConfigPath(sceneJson, assetsJson);
+    return resolved ?? DEFAULT_GAME_PATH;
+}
+function listLocalScenes(projectDir) {
+    if (!fileExists(projectDir, MANIFEST_PATH))
+        return [];
+    const manifestJson = JSON.parse(readLocalFile(projectDir, MANIFEST_PATH));
+    return listScenesFromManifest(manifestJson);
+}
+// ─── Unified prefab loading ──────────────────────────────────────────────────
+function loadPrefabs(projectDir, systemType, opts) {
+    if (systemType === 'external-theme') {
+        const themeId = resolveThemeId(projectDir, opts);
+        const schema = loadThemeSchema(projectDir);
+        const data = loadThemeData(projectDir, themeId);
+        return parseThemePrefabs(schema, data, themeId);
+    }
+    const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+    const gameConfigJson = loadGameConfig(projectDir, configPath);
+    const { extensions, config } = parseGameConfig(gameConfigJson);
+    const metaMap = scanExtensionMetaData(projectDir);
+    return buildExtensionPrefabs(metaMap, { extensions, config }, configPath);
+}
+// ─── dotpath helper ──────────────────────────────────────────────────────────
+function getByDotPath(obj, path) {
+    const parts = path.split('.');
+    let cur = obj;
+    for (const p of parts) {
+        if (!cur || typeof cur !== 'object')
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+function setByDotPath(obj, path, value) {
+    const parts = path.split('.');
+    if (parts.length === 1) {
+        return { ...obj, [path]: value };
+    }
+    const [head, ...rest] = parts;
+    const sub = (obj[head] && typeof obj[head] === 'object' && !Array.isArray(obj[head]))
+        ? { ...obj[head] }
+        : {};
+    return { ...obj, [head]: setByDotPath(sub, rest.join('.'), value) };
+}
+function coerceValue(rawValue, fieldType) {
+    const t = fieldType.toLowerCase();
+    if (t === 'boolean' || t === 'switch') {
+        return rawValue === 'true' || rawValue === '1';
+    }
+    if (t === 'integer' || t === 'int') {
+        const n = parseInt(rawValue, 10);
+        if (Number.isNaN(n))
+            throw new Error(`Cannot parse "${rawValue}" as integer`);
+        return n;
+    }
+    if (t === 'number' || t === 'float' || t === 'range') {
+        const n = parseFloat(rawValue);
+        if (Number.isNaN(n))
+            throw new Error(`Cannot parse "${rawValue}" as number`);
+        return n;
+    }
+    try {
+        return JSON.parse(rawValue);
+    }
+    catch {
+        return rawValue;
+    }
+}
+// ─── Command registration ────────────────────────────────────────────────────
+export function registerPrefabCommands(program) {
+    const prefab = program
+        .command('prefab')
+        .description('Remix prefab 配置管理（自动检测 External Theme / PlayCanvas 项目类型）');
+    // ─── variants / themes / scenes (aliases) ────────────────────
+    const variantsHandler = (opts) => {
+        const projectDir = resolveProjectDir(opts);
+        const systemType = detectProjectType(projectDir);
+        if (systemType === 'external-theme') {
+            const themes = listLocalThemeIds(projectDir);
+            const activeId = resolveActiveThemeId(projectDir);
+            const variants = themes.map((id) => ({
+                id,
+                name: id,
+                isActive: id === activeId,
+            }));
+            outputJson({ projectType: 'external', variants });
+        }
+        else {
+            const scenes = listLocalScenes(projectDir);
+            outputJson({ projectType: 'playcanvas', variants: scenes });
+        }
+    };
+    prefab.command('variants')
+        .description('列出可用变体（External: 主题列表；PlayCanvas: 场景列表）')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action(variantsHandler);
+    prefab.command('themes')
+        .description('variants 别名（对齐前端「主题列表」术语）')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action(variantsHandler);
+    prefab.command('scenes')
+        .description('variants 别名（对齐前端「场景列表」术语）')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action(variantsHandler);
+    // ─── list ────────────────────────────────────────────────────
+    prefab.command('list')
+        .description('列出所有 prefab 及状态')
+        .option('--variant <id>', '指定变体（External: themeId；PlayCanvas: sceneId）')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action((opts) => {
+        const projectDir = resolveProjectDir(opts);
+        const systemType = detectProjectType(projectDir);
+        const prefabs = loadPrefabs(projectDir, systemType, opts);
+        outputJson({
+            projectType: systemType === 'external-theme' ? 'external' : 'playcanvas',
+            variant: opts.variant ?? null,
+            total: prefabs.length,
+            enabled: prefabs.filter((p) => p.isUsed).length,
+            prefabs: prefabs.map((p) => ({
+                key: p.key,
+                name: p.name,
+                description: p.description,
+                isUsed: p.isUsed,
+                type: p.systemType,
+            })),
+        });
+    });
+    // ─── describe ────────────────────────────────────────────────
+    prefab.command('describe <key>')
+        .description('显示 prefab 完整字段信息')
+        .option('--variant <id>', '指定变体')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action((key, opts) => {
+        const projectDir = resolveProjectDir(opts);
+        const systemType = detectProjectType(projectDir);
+        const prefabs = loadPrefabs(projectDir, systemType, opts);
+        const found = prefabs.find((p) => p.key === key);
+        if (!found) {
+            console.error(`Error: prefab "${key}" 不存在。可用的 key: ${prefabs.map((p) => p.key).join(', ')}`);
+            process.exit(1);
+        }
+        if (found.systemType === 'external-theme' && found.jsonSchema) {
+            const fields = describeJsonSchemaFields(found.jsonSchema, found.currentValue);
+            outputJson({
+                key: found.key,
+                type: found.systemType,
+                isUsed: found.isUsed,
+                description: found.description,
+                fields,
+            });
+        }
+        else if (found.configSchema) {
+            const currentValues = (found.currentValue && typeof found.currentValue === 'object')
+                ? found.currentValue
+                : {};
+            const fields = describeConfigSchemaFields(found.configSchema, currentValues);
+            outputJson({
+                key: found.key,
+                type: found.systemType,
+                isUsed: found.isUsed,
+                description: found.description,
+                configPath: found.configPath,
+                fields,
+            });
+        }
+        else {
+            outputJson({
+                key: found.key,
+                type: found.systemType,
+                isUsed: found.isUsed,
+                description: found.description,
+                currentValue: found.currentValue,
+            });
+        }
+    });
+    // ─── get ─────────────────────────────────────────────────────
+    prefab.command('get <key> [field]')
+        .description('获取 prefab 或子字段的当前值')
+        .option('--variant <id>', '指定变体')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action((key, field, opts) => {
+        const projectDir = resolveProjectDir(opts);
+        const systemType = detectProjectType(projectDir);
+        const prefabs = loadPrefabs(projectDir, systemType, opts);
+        const found = prefabs.find((p) => p.key === key);
+        if (!found) {
+            console.error(`Error: prefab "${key}" 不存在。`);
+            process.exit(1);
+        }
+        if (!found.isUsed) {
+            console.error(`Error: prefab "${key}" 当前未启用，没有值。使用 "prefab enable ${key}" 启用。`);
+            process.exit(1);
+        }
+        let value = found.currentValue;
+        if (field) {
+            value = getByDotPath(value, field);
+        }
+        outputJson({ key, field: field ?? null, value });
+    });
+    // ─── set ─────────────────────────────────────────────────────
+    prefab.command('set <key> <field> <value>')
+        .description('修改 prefab 子字段值（带校验）')
+        .option('--variant <id>', '指定变体')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action((key, field, rawValue, opts) => {
+        const projectDir = resolveProjectDir(opts);
+        const systemType = detectProjectType(projectDir);
+        if (systemType === 'external-theme') {
+            const themeId = resolveThemeId(projectDir, opts);
+            const schema = loadThemeSchema(projectDir);
+            const data = loadThemeData(projectDir, themeId);
+            const prefabs = parseThemePrefabs(schema, data, themeId);
+            const found = prefabs.find((p) => p.key === key);
+            if (!found) {
+                console.error(`Error: prefab "${key}" 不存在。`);
+                process.exit(1);
+            }
+            const fieldSchema = resolveJsonSchemaField(found.jsonSchema, field);
+            const fieldType = fieldSchema?.type ?? 'string';
+            const coerced = coerceValue(rawValue, fieldType);
+            if (fieldSchema) {
+                const result = validateThemeValue(fieldSchema, coerced);
+                if (!result.valid) {
+                    console.error(`Validation error: ${result.errors.join('; ')}`);
+                    process.exit(1);
+                }
+            }
+            const currentValue = data[key];
+            let newValue;
+            if (found.jsonSchema?.type === 'object') {
+                const obj = (currentValue && typeof currentValue === 'object' && !Array.isArray(currentValue))
+                    ? { ...currentValue }
+                    : {};
+                newValue = setByDotPath(obj, field, coerced);
+            }
+            else {
+                newValue = coerced;
+            }
+            const newData = mergeThemeDataKey(data, key, newValue);
+            writeThemeData(projectDir, themeId, newData);
+            outputJson({ success: true, key, field, value: coerced });
+        }
+        else {
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+            const gameConfigJson = loadGameConfig(projectDir, configPath);
+            const { config } = parseGameConfig(gameConfigJson);
+            const metaMap = scanExtensionMetaData(projectDir);
+            const meta = metaMap.get(key);
+            if (!meta) {
+                console.error(`Error: extension "${key}" 不存在。`);
+                process.exit(1);
+            }
+            const configKey = meta.configPath ? parseConfigKey(meta.configPath) : meta.name;
+            const existingKey = findConfigKeyCaseInsensitive(config, configKey);
+            const currentValues = (existingKey ? config[existingKey] : {}) ?? {};
+            const fieldDef = meta.configSchema?.[field];
+            const fieldType = fieldDef?.type ?? 'string';
+            const coerced = coerceValue(rawValue, fieldType);
+            if (fieldDef) {
+                const result = validateConfigValue(fieldDef, coerced);
+                if (!result.valid) {
+                    console.error(`Validation error: ${result.errors.join('; ')}`);
+                    process.exit(1);
+                }
+            }
+            const newValues = { ...currentValues, [field]: coerced };
+            const updated = updateGameConfigValue(gameConfigJson, configKey, newValues);
+            writeGameConfig(projectDir, configPath, updated);
+            outputJson({ success: true, key, field, value: coerced });
+        }
+    });
+    // ─── enable ──────────────────────────────────────────────────
+    prefab.command('enable <key>')
+        .description('启用 prefab')
+        .option('--variant <id>', '指定变体')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action((key, opts) => {
+        const projectDir = resolveProjectDir(opts);
+        const systemType = detectProjectType(projectDir);
+        if (systemType === 'external-theme') {
+            const themeId = resolveThemeId(projectDir, opts);
+            const schema = loadThemeSchema(projectDir);
+            const data = loadThemeData(projectDir, themeId);
+            const props = (schema.properties ?? {});
+            if (!props[key]) {
+                console.error(`Error: prefab "${key}" 不存在于 schema 中。`);
+                process.exit(1);
+            }
+            const defaultValue = defaultValueFromJsonSchemaProperty(props[key]);
+            const newData = mergeThemeDataKey(data, key, defaultValue);
+            writeThemeData(projectDir, themeId, newData);
+            outputJson({ success: true, key, enabled: true, defaultValue });
+        }
+        else {
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+            const gameConfigJson = loadGameConfig(projectDir, configPath);
+            const { extensions } = parseGameConfig(gameConfigJson);
+            if (extensions.includes(key)) {
+                outputJson({ success: true, key, enabled: true, message: 'Already enabled' });
+                return;
+            }
+            const updated = updateGameConfigExtensions(gameConfigJson, [...extensions, key]);
+            writeGameConfig(projectDir, configPath, updated);
+            outputJson({ success: true, key, enabled: true });
+        }
+    });
+    // ─── disable ─────────────────────────────────────────────────
+    prefab.command('disable <key>')
+        .description('禁用 prefab')
+        .option('--variant <id>', '指定变体')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action((key, opts) => {
+        const projectDir = resolveProjectDir(opts);
+        const systemType = detectProjectType(projectDir);
+        if (systemType === 'external-theme') {
+            const themeId = resolveThemeId(projectDir, opts);
+            const data = loadThemeData(projectDir, themeId);
+            if (!Object.prototype.hasOwnProperty.call(data, key)) {
+                outputJson({ success: true, key, enabled: false, message: 'Already disabled' });
+                return;
+            }
+            const newData = deleteThemeDataKey(data, key);
+            writeThemeData(projectDir, themeId, newData);
+            outputJson({ success: true, key, enabled: false });
+        }
+        else {
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+            const gameConfigJson = loadGameConfig(projectDir, configPath);
+            const { extensions } = parseGameConfig(gameConfigJson);
+            const filtered = extensions.filter((n) => n !== key);
+            if (filtered.length === extensions.length) {
+                outputJson({ success: true, key, enabled: false, message: 'Already disabled' });
+                return;
+            }
+            const updated = updateGameConfigExtensions(gameConfigJson, filtered);
+            writeGameConfig(projectDir, configPath, updated);
+            outputJson({ success: true, key, enabled: false });
+        }
+    });
+    // ─── switch ──────────────────────────────────────────────────
+    prefab.command('switch <variant>')
+        .description('切换活跃变体（External: 修改 index.ts；PlayCanvas: 指定场景上下文）')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action((variant, opts) => {
+        const projectDir = resolveProjectDir(opts);
+        const systemType = detectProjectType(projectDir);
+        if (systemType === 'external-theme') {
+            const themes = listLocalThemeIds(projectDir);
+            if (!themes.includes(variant)) {
+                console.error(`Error: 主题 "${variant}" 不存在。可用: ${themes.join(', ')}`);
+                process.exit(1);
+            }
+            const content = buildThemeIndexTs(variant);
+            writeFileSync(join(projectDir, THEME_INDEX_PATH), content, 'utf-8');
+            outputJson({ success: true, activeVariant: variant, message: `Switched to theme "${variant}"` });
+        }
+        else {
+            const scenes = listLocalScenes(projectDir);
+            const found = scenes.find((s) => s.id === variant || s.name === variant);
+            if (!found) {
+                console.error(`Error: 场景 "${variant}" 不存在。可用: ${scenes.map((s) => `${s.name}(${s.id})`).join(', ')}`);
+                process.exit(1);
+            }
+            outputJson({
+                success: true,
+                activeVariant: found.id,
+                message: `PlayCanvas 场景上下文已设为 "${found.name}"。后续命令使用 --variant ${found.id} 来操作此场景的配置。`,
+            });
+        }
+    });
+}
+// ─── JSON Schema field resolver ──────────────────────────────────────────────
+function resolveJsonSchemaField(schema, dotPath) {
+    const parts = dotPath.split('.');
+    let cur = schema;
+    for (const p of parts) {
+        if (cur.type === 'object' && cur.properties?.[p]) {
+            cur = cur.properties[p];
+        }
+        else if (cur.properties?.[p]) {
+            cur = cur.properties[p];
+        }
+        else {
+            return null;
+        }
+    }
+    return cur;
+}

package/dist/commands/tools.js

@@ -1,5 +1,5 @@
 import { writeFileSync, mkdirSync, readFileSync } from 'fs';
-import { dirname, join } from 'path';
+import { dirname, join, parse } from 'path';
 import { tmpdir } from 'os';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 const TMP_DIR = join(tmpdir(), 'playcraft');
@@ -20,6 +20,77 @@ function handleError(err) {
     console.error(`Error: ${msg}`);
     process.exit(1);
 }
+/** Fallback extension from API mime when magic-byte sniff fails. */
+function extensionForImageMime(mimeType) {
+    const base = mimeType.toLowerCase().split(';')[0]?.trim() ?? '';
+    switch (base) {
+        case 'image/png':
+            return '.png';
+        case 'image/jpeg':
+        case 'image/jpg':
+            return '.jpg';
+        case 'image/webp':
+            return '.webp';
+        case 'image/gif':
+            return '.gif';
+        case 'image/bmp':
+            return '.bmp';
+        default:
+            return '.png';
+    }
+}
+/**
+ * Detect container from decoded bytes (magic). Prefer this over MIME alone.
+ */
+function sniffImageExtension(buf) {
+    // PNG (8-byte signature)
+    if (buf.length >= 8 &&
+        buf[0] === 0x89 &&
+        buf[1] === 0x50 &&
+        buf[2] === 0x4e &&
+        buf[3] === 0x47) {
+        return '.png';
+    }
+    // JPEG (SOI marker)
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+        return '.jpg';
+    }
+    // GIF87a / GIF89a
+    if (buf.length >= 6 &&
+        buf[0] === 0x47 &&
+        buf[1] === 0x49 &&
+        buf[2] === 0x46 &&
+        buf[3] === 0x38 &&
+        (buf[4] === 0x37 || buf[4] === 0x39) &&
+        buf[5] === 0x61) {
+        return '.gif';
+    }
+    // WebP: RIFF .... WEBP
+    if (buf.length >= 12 &&
+        buf[0] === 0x52 &&
+        buf[1] === 0x49 &&
+        buf[2] === 0x46 &&
+        buf[3] === 0x46 &&
+        buf[8] === 0x57 &&
+        buf[9] === 0x45 &&
+        buf[10] === 0x42 &&
+        buf[11] === 0x50) {
+        return '.webp';
+    }
+    // BMP
+    if (buf.length >= 2 && buf[0] === 0x42 && buf[1] === 0x4d) {
+        return '.bmp';
+    }
+    return null;
+}
+/** Replace output extension when it does not match the chosen format extension. */
+function resolveImageOutputPath(outputPath, wantExt) {
+    const { dir, name, ext } = parse(outputPath);
+    if (ext.toLowerCase() === wantExt) {
+        return outputPath;
+    }
+    return join(dir, `${name}${wantExt}`);
+}
 export function registerToolsCommands(program) {
     const tools = program
         .command('tools')
@@ -51,11 +122,25 @@ export function registerToolsCommands(program) {
                 referenceImageBase64,
                 referenceImageMimeType,
             });
-            mkdirSync(dirname(opts.output), { recursive: true });
             const buf = Buffer.from(result.imageBase64, 'base64');
-            writeFileSync(opts.output, buf);
+            const sniffed = sniffImageExtension(buf);
+            const fromMime = extensionForImageMime(result.mimeType);
+            const wantExt = sniffed ?? fromMime;
+            if (!sniffed) {
+                console.warn('Could not detect image format from file signature; using Content-Type from API for extension.');
+            }
+            else if (sniffed !== fromMime) {
+                console.warn(`Image bytes look like ${sniffed.slice(1).toUpperCase()} but API reported ${result.mimeType}; ` +
+                    'extension follows file signature.');
+            }
+            const outputPath = resolveImageOutputPath(opts.output, wantExt);
+            if (outputPath !== opts.output) {
+                console.log(`Output path adjusted to ${wantExt} payload: ${outputPath}`);
+            }
+            mkdirSync(dirname(outputPath), { recursive: true });
+            writeFileSync(outputPath, buf);
             const sizeKB = Math.round(buf.length / 1024);
-            console.log(`Image saved to ${opts.output} (${sizeKB}KB, ${result.mimeType})`);
+            console.log(`Image saved to ${outputPath} (${sizeKB}KB, ${wantExt.slice(1)})`);
         }
         catch (e) {
             handleError(e);

package/dist/index.js

@@ -18,6 +18,7 @@ import { fixIdsCommand } from './commands/fix-ids.js';
 import { registerToolsCommands } from './commands/tools.js';
 import { registerImageCommands } from './commands/image.js';
 import { registerAudioCommands } from './commands/audio.js';
+import { registerPrefabCommands } from './commands/prefab.js';
 import { CLI_ROOT_DESCRIPTION, getCliTopicsHelpText, registerRootProgramHelp, } from './cli-root-help.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -162,6 +163,7 @@ program
     .option('--no-compress-models', '禁用模型压缩')
     .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);
 });
@@ -211,6 +213,7 @@ program
     .option('--no-compress-models', '禁用模型压缩')
     .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) => {
     await buildCommand(projectPath, {
         ...options,
@@ -248,6 +251,7 @@ program
     .option('--no-compress-models', '禁用模型压缩')
     .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) => {
     await buildCommand(baseBuildDir, {
         ...options,
@@ -289,6 +293,7 @@ program
     .option('--esm-mode <mode>', 'ESM 模块处理模式 (auto|enabled|disabled)', 'auto')
     .option('--use-playable-scripts', '使用 @playcraft/devkit 构建工具打包（可玩广告项目专用）', false)
     .option('--theme <theme>', '指定要构建的主题（devkit 项目专用）')
+    .option('--no-tracking', '禁用埋点 tracking adapter 注入（默认启用）')
     .action(async (projectPath, options) => {
     await buildAllCommand(projectPath, options);
 });
@@ -322,4 +327,6 @@ registerToolsCommands(program);
 registerImageCommands(program);
 // Local audio processing (playcraft audio <command>)
 registerAudioCommands(program);
+// Remix prefab management (playcraft prefab <command>)
+registerPrefabCommands(program);
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "private": false,
   "type": "module",
   "bin": {
@@ -22,8 +22,8 @@
     "release": "node scripts/release.js"
   },
   "dependencies": {
-    "@playcraft/build": "^0.0.23",
-    "@playcraft/common": "^0.0.12",
+    "@playcraft/build": "^0.0.24",
+    "@playcraft/common": "^0.0.13",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",
@@ -34,6 +34,7 @@
     "express": "^5.2.1",
     "fluent-ffmpeg": "^2.1.3",
     "inquirer": "^9.3.8",
+    "json5": "^2.2.3",
     "latest-version": "^7.0.0",
     "music-metadata": "^11.12.3",
     "ora": "^8.2.0",