@playcraft/cli 0.0.27 → 0.0.29

package/dist/commands/image.js

@@ -1,5 +1,5 @@
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
-import { basename, dirname } from 'path';
+import { basename, dirname, join } from 'path';
 import sharp from 'sharp';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 /** 单文件输入上限（字节），防止误处理巨型文件导致 OOM */
@@ -48,6 +48,21 @@ function handleError(err) {
     console.error(`Error: ${msg}`);
     process.exit(1);
 }
+/** 多圈边缘羽化默认 alpha；若 edgeLayers 更大则自最后一档按衰减补齐。 */
+const DEFAULT_EDGE_LAYER_ALPHAS = [200, 120, 60];
+function buildEdgeLayerAlphas(edgeLayers) {
+    const base = DEFAULT_EDGE_LAYER_ALPHAS;
+    if (edgeLayers <= base.length) {
+        return Array.from(base.slice(0, edgeLayers));
+    }
+    const out = Array.from(base);
+    let last = base[base.length - 1];
+    while (out.length < edgeLayers) {
+        last = Math.max(8, Math.round(last * 0.62));
+        out.push(last);
+    }
+    return out;
+}
 /**
  * 从图片四条边向内 BFS flood-fill，自动检测边缘主色并移除连通的同色背景区域。
  * 适用于 AI 生成的素材（纯色、灰色、棋盘格背景），前景纹理零损失。
@@ -143,7 +158,7 @@ async function floodFillRemoveBg(inputPath, opts) {
     }
     // ── 3. Edge smoothing (multi-layer alpha gradient) ──
     if (opts.edgeLayers > 0) {
-        const layerAlphas = [200, 120, 60];
+        const layerAlphas = buildEdgeLayerAlphas(opts.edgeLayers);
         let borderSet = new Set();
         for (let y = 1; y < h - 1; y++) {
             for (let x = 1; x < w - 1; x++) {
@@ -155,12 +170,13 @@ async function floodFillRemoveBg(inputPath, opts) {
                     borderSet.add(pos);
             }
         }
-        for (let layer = 0; layer < opts.edgeLayers && layer < layerAlphas.length; layer++) {
+        for (let layer = 0; layer < layerAlphas.length; layer++) {
             const alpha = layerAlphas[layer];
             for (const pos of borderSet) {
                 result[pos * 4 + 3] = Math.min(result[pos * 4 + 3], alpha);
             }
-            if (layer < opts.edgeLayers - 1) {
+            if (layer < layerAlphas.length - 1) {
+                const nextAlpha = layerAlphas[layer + 1];
                 const nextBorder = new Set();
                 for (const pos of borderSet) {
                     const x = pos % w;
@@ -172,7 +188,7 @@ async function floodFillRemoveBg(inputPath, opts) {
                             continue;
                         const npos = ny * w + nx;
                         if (result[npos * 4 + 3] === 0 && !borderSet.has(npos)) {
-                            result[npos * 4 + 3] = Math.min(60, layerAlphas[layer + 1] ?? 40);
+                            result[npos * 4 + 3] = Math.min(60, nextAlpha);
                             nextBorder.add(npos);
                         }
                     }
@@ -212,10 +228,75 @@ function parseResizeFitOption(raw) {
     console.error('Error: --fit must be contain|cover|fill|inside|outside');
     process.exit(1);
 }
+/** 不规则子图文件名（避免路径分隔符与非法字符） */
+function safeElementFileBase(name, fallback) {
+    const s = name.replace(/[^a-zA-Z0-9._-]+/g, '_').replace(/^\.+/, '').slice(0, 120);
+    const base = (s || fallback).replace(/\.png$/i, '');
+    return base || fallback;
+}
+/**
+ * 按分析结果将精灵图裁成逐帧 PNG，并写入 split-meta.json（供 sprite-sheet 重组参考）
+ */
+async function splitSpriteSheetToDir(inputPath, outputDir, analysis) {
+    mkdirSync(outputDir, { recursive: true });
+    // 与后端 analyze-sprite-sheet 一致：按 EXIF 摆正后再按 bounds 裁剪
+    const sheetBuf = await sharp(inputPath).rotate().toBuffer();
+    const sheetMeta = await sharp(sheetBuf).metadata();
+    const iw = sheetMeta.width ?? 0;
+    const ih = sheetMeta.height ?? 0;
+    const frames = [];
+    let written = 0;
+    if (analysis.gridType === 'irregular' && analysis.elements?.length) {
+        for (let i = 0; i < analysis.elements.length; i++) {
+            const el = analysis.elements[i];
+            const fname = `${safeElementFileBase(el.name, `frame_${i}`)}.png`;
+            const outPath = join(outputDir, fname);
+            const { x, y, w, h } = el.bounds;
+            await sharp(sheetBuf).extract({ left: x, top: y, width: w, height: h }).png().toFile(outPath);
+            frames.push({ path: fname, name: el.name, x, y, w, h });
+            written++;
+        }
+    }
+    else {
+        const { rows, columns, frameWidth, frameHeight, padding } = analysis;
+        for (let r = 0; r < rows; r++) {
+            for (let c = 0; c < columns; c++) {
+                const x = c * (frameWidth + padding);
+                const y = r * (frameHeight + padding);
+                if (x + frameWidth > iw || y + frameHeight > ih)
+                    continue;
+                const fname = `frame_r${r}_c${c}.png`;
+                const outPath = join(outputDir, fname);
+                await sharp(sheetBuf)
+                    .extract({ left: x, top: y, width: frameWidth, height: frameHeight })
+                    .png()
+                    .toFile(outPath);
+                frames.push({ path: fname, row: r, col: c, x, y, w: frameWidth, h: frameHeight });
+                written++;
+            }
+        }
+    }
+    const splitMeta = {
+        source: inputPath,
+        imageSize: { w: iw, h: ih },
+        gridType: analysis.gridType,
+        rows: analysis.rows,
+        columns: analysis.columns,
+        frameWidth: analysis.frameWidth,
+        frameHeight: analysis.frameHeight,
+        padding: analysis.padding,
+        frameCount: analysis.frameCount,
+        description: analysis.description,
+        elements: analysis.elements,
+        frames,
+    };
+    writeFileSync(join(outputDir, 'split-meta.json'), JSON.stringify(splitMeta, null, 2), 'utf-8');
+    return written;
+}
 export function registerImageCommands(program) {
     const img = program
         .command('image')
-        .description('素材工具：本地图片处理（sharp）；remove-background 调用后端 API');
+        .description('素材工具：本地图片处理（sharp）；remove-background / sprite-split --auto-detect 可调用后端 API');
     // ─── resize ──────────────────────────────────────────────────
     img.command('resize')
         .description('缩放图片（按比例或指定宽高）')
@@ -547,6 +628,71 @@ export function registerImageCommands(program) {
             handleError(e);
         }
     });
+    // ─── sprite-split ──────────────────────────────────────────────
+    img.command('sprite-split')
+        .description('拆分精灵图为逐帧 PNG + split-meta.json；--auto-detect 调用后端多模态分析网格（需 token）')
+        .requiredOption('--input <path>', '精灵图路径')
+        .requiredOption('--output-dir <dir>', '输出目录（将自动创建）')
+        .option('--auto-detect', '由后端 Vision 推断行列、帧尺寸与间距')
+        .option('--hint <text>', '传给 Vision 的上下文（如：麻将牌面，等大小网格）')
+        .option('--model <id>', '覆盖 Vision 所用 Google GenAI 模型 ID（仅与 --auto-detect 一起使用）')
+        .option('--rows <n>', '行数（手动模式必填，除非使用 --auto-detect）', cliParseInt)
+        .option('--columns <n>', '列数（手动模式必填）', cliParseInt)
+        .option('--frame-width <n>', '单帧宽度（像素，手动模式必填）', cliParseInt)
+        .option('--frame-height <n>', '单帧高度（像素，手动模式必填）', cliParseInt)
+        .option('--padding <n>', '帧间距（像素，默认 0）', cliParseInt, 0)
+        .action(async (opts) => {
+        try {
+            assertInputWithinLimit(opts.input);
+            let analysis;
+            if (opts.autoDetect) {
+                const imageBase64 = readFileSync(opts.input).toString('base64');
+                const client = new AgentApiClient();
+                analysis = await client.post('/analyze-sprite-sheet', {
+                    imageBase64,
+                    hint: typeof opts.hint === 'string' ? opts.hint : undefined,
+                    model: typeof opts.model === 'string' && opts.model.trim() ? opts.model.trim() : undefined,
+                });
+            }
+            else {
+                const rows = opts.rows;
+                const columns = opts.columns;
+                const frameWidth = opts.frameWidth;
+                const frameHeight = opts.frameHeight;
+                if (rows === undefined ||
+                    columns === undefined ||
+                    frameWidth === undefined ||
+                    frameHeight === undefined) {
+                    console.error('Error: manual mode requires --rows, --columns, --frame-width, and --frame-height (or use --auto-detect)');
+                    process.exit(1);
+                }
+                if (rows < 1 || columns < 1 || frameWidth < 1 || frameHeight < 1) {
+                    console.error('Error: rows, columns, frame-width, frame-height must be positive integers');
+                    process.exit(1);
+                }
+                const padding = opts.padding ?? 0;
+                analysis = {
+                    gridType: 'regular',
+                    rows,
+                    columns,
+                    frameWidth,
+                    frameHeight,
+                    padding,
+                    frameCount: rows * columns,
+                    description: 'Manual grid (playcraft image sprite-split)',
+                };
+            }
+            const written = await splitSpriteSheetToDir(opts.input, opts.outputDir, analysis);
+            if (written === 0) {
+                console.error('Error: no frames extracted (check grid vs image size)');
+                process.exit(1);
+            }
+            console.log(`Sprite split: ${written} frame(s) → ${opts.outputDir} (split-meta.json); grid=${analysis.gridType} ${analysis.gridType === 'regular' ? `${analysis.rows}x${analysis.columns}` : `${analysis.elements?.length ?? 0} elements`}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
     // ─── sprite-sheet ────────────────────────────────────────────
     img.command('sprite-sheet')
         .description('将多张图合并为精灵图，并输出帧坐标 JSON（完整本地实现）')

package/dist/commands/prefab.js

@@ -2,7 +2,19 @@ import { inspect } from 'node:util';
 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';
+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, listScenesWithGameConfig, resolveGameConfigPath, validateThemeValue, validateConfigValue, describeJsonSchemaFields, describeConfigSchemaFields, getPrefabFieldDescriptors, getPrefabFieldDiffs, prefabHasSchemaDiff, } from '@playcraft/common/prefab';
+const DEFAULT_PAGE_LIMIT = 50;
+/** 无法识别 External / PlayCanvas 项目类型（供测试在 mock process.exit 后通过 instanceof 识别）。 */
+export class ProjectDetectError extends Error {
+    name = 'ProjectDetectError';
+    constructor(message = 'Project type could not be detected') {
+        super(message);
+        Error.captureStackTrace?.(this, ProjectDetectError);
+    }
+}
+function isProjectDetectError(e) {
+    return e instanceof ProjectDetectError;
+}
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 function resolveProjectDir(opts) {
     return opts.projectDir ? resolve(opts.projectDir) : process.cwd();
@@ -21,11 +33,10 @@ function detectProjectType(projectDir) {
     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');
+    throw new ProjectDetectError();
 }
 const HUMAN_INSPECT = { colors: false, depth: 10, maxArrayLength: 200 };
 const JSON_OPT_DESC = '以 JSON 输出（便于脚本解析；默认为人可读文本）';
-/** 为子命令追加 `--json`（默认人类可读） */
 function withJsonOption(cmd) {
     return cmd.option('--json', JSON_OPT_DESC);
 }
@@ -67,6 +78,116 @@ function describeFieldLine(f) {
         parts.push(`默认: ${formatHumanValue(f.default)}`);
     return parts.join('  |  ');
 }
+function isFieldDescriptor(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    const o = v;
+    return typeof o.path === 'string' && typeof o.type === 'string';
+}
+/** 规范化 describe 的 fields，剔除不符合 FieldDescriptor 形态的项（避免 JSON/终端输出依赖不安全断言）。 */
+function normalizeDescribeFields(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter(isFieldDescriptor);
+}
+function isDescribeJsonWithFields(b) {
+    return 'fields' in b && Array.isArray(b.fields);
+}
+function slicePage(arr, limit, offset) {
+    const total = arr.length;
+    const slice = arr.slice(offset, offset + limit);
+    const hasMore = offset + slice.length < total;
+    return { slice, page: { limit, offset, total, hasMore } };
+}
+function tryCompileRegex(pattern, matchCase) {
+    try {
+        return new RegExp(pattern, matchCase ? '' : 'i');
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`Invalid regex pattern "${pattern}": ${msg}`);
+    }
+}
+function prefabMetaMatches(p, re) {
+    if (re.test(p.key))
+        return true;
+    if (re.test(p.name))
+        return true;
+    if (p.description && re.test(p.description))
+        return true;
+    return false;
+}
+function filterPrefabsList(all, o) {
+    let list = all;
+    if (o.usedOnly)
+        list = list.filter((p) => p.isUsed);
+    if (o.unusedOnly)
+        list = list.filter((p) => !p.isUsed);
+    if (o.changedOnly)
+        list = list.filter((p) => prefabHasSchemaDiff(p));
+    if (o.match) {
+        const re = tryCompileRegex(o.match, Boolean(o.matchCase));
+        list = list.filter((p) => prefabMetaMatches(p, re));
+    }
+    return list;
+}
+function buildSummary(systemType, variantResolved, all) {
+    const enabled = all.filter((p) => p.isUsed).length;
+    const changed = all.filter((p) => prefabHasSchemaDiff(p)).length;
+    return {
+        projectType: systemType === 'external-theme' ? 'external' : 'playcanvas',
+        variant: variantResolved,
+        total: all.length,
+        enabled,
+        disabled: all.length - enabled,
+        changed,
+    };
+}
+function buildDescribeGuide(prefabKey, isUsed) {
+    return {
+        workflow: [
+            'playcraft prefab list --json --limit 50 --offset 0',
+            `playcraft prefab diff --json --limit ${DEFAULT_PAGE_LIMIT} --offset 0`,
+            `playcraft prefab get ${prefabKey} --json`,
+        ],
+        setExample: `playcraft prefab set ${prefabKey} <field> <value>`,
+        whenDisabled: isUsed ? undefined : `playcraft prefab enable ${prefabKey}`,
+    };
+}
+function valuePreview(p, maxLen = 120) {
+    if (!p.isUsed)
+        return null;
+    const s = formatHumanValue(p.currentValue);
+    if (s.length <= maxLen)
+        return s;
+    return `${s.slice(0, maxLen)}…`;
+}
+function withPagingOptions(cmd) {
+    return cmd
+        .option('--limit <n>', '分页条数', (v) => parseInt(v, 10), DEFAULT_PAGE_LIMIT)
+        .option('--offset <n>', '分页偏移', (v) => parseInt(v, 10), 0);
+}
+function withFilterOptions(cmd) {
+    return cmd
+        .option('--match <regex>', 'prefab 级正则过滤（key/name/description）')
+        .option('--match-case', '正则区分大小写（默认忽略大小写）')
+        .option('--used-only', '仅已启用')
+        .option('--unused-only', '仅未启用')
+        .option('--changed-only', '相对 schema 默认值有差异的 prefab');
+}
+function parsePaging(opts) {
+    const limit = Number.isFinite(opts.limit) && opts.limit > 0 ? opts.limit : DEFAULT_PAGE_LIMIT;
+    const offset = Number.isFinite(opts.offset) && opts.offset >= 0 ? opts.offset : 0;
+    return { limit, offset };
+}
+function resolveVariantResolved(projectDir, systemType, opts) {
+    if (opts.variant)
+        return opts.variant;
+    if (systemType === 'external-theme') {
+        return resolveThemeId(projectDir, opts);
+    }
+    return null;
+}
 // ─── External Theme helpers ──────────────────────────────────────────────────
 function loadThemeSchema(projectDir) {
     const raw = readLocalFile(projectDir, THEME_SCHEMA_PATH);
@@ -116,6 +237,7 @@ function resolveThemeId(projectDir, opts) {
         return themes[0];
     console.error('Error: 没有找到可用的主题。请使用 --variant 指定主题 ID。');
     process.exit(1);
+    throw new Error('unreachable');
 }
 // ─── PlayCanvas / LiteCreator helpers ────────────────────────────────────────
 function loadGameConfig(projectDir, configPath) {
@@ -144,25 +266,60 @@ function scanExtensionMetaData(projectDir) {
     }
     return map;
 }
+/** Write a single field's value into MetaData.json configSchema.{field}.default */
+function writeMetaDataDefault(projectDir, extensionName, field, value) {
+    const metaPath = join(projectDir, LITE_CREATOR_EXTENSIONS_DIR, extensionName, 'MetaData.json');
+    const raw = readFileSync(metaPath, 'utf-8');
+    const metaData = JSON.parse(raw);
+    const configSchema = metaData.configSchema;
+    if (!configSchema?.[field]) {
+        throw new Error(`MetaData.json for "${extensionName}" has no configSchema.${field}`);
+    }
+    configSchema[field].default = value;
+    writeFileSync(metaPath, JSON.stringify(metaData, null, 2), 'utf-8');
+}
+/** Write multiple fields' values into MetaData.json configSchema.*.default */
+function writeMetaDataDefaults(projectDir, extensionName, values) {
+    const metaPath = join(projectDir, LITE_CREATOR_EXTENSIONS_DIR, extensionName, 'MetaData.json');
+    const raw = readFileSync(metaPath, 'utf-8');
+    const metaData = JSON.parse(raw);
+    const configSchema = metaData.configSchema;
+    if (!configSchema) {
+        throw new Error(`MetaData.json for "${extensionName}" has no configSchema`);
+    }
+    for (const [field, value] of Object.entries(values)) {
+        if (configSchema[field]) {
+            configSchema[field].default = value;
+        }
+    }
+    writeFileSync(metaPath, JSON.stringify(metaData, null, 2), 'utf-8');
+}
 function resolveGameConfigPathForVariant(projectDir, variantId) {
     if (!variantId)
-        return DEFAULT_GAME_PATH;
+        return null;
     if (!fileExists(projectDir, scenePath(variantId)))
-        return DEFAULT_GAME_PATH;
+        return null;
     const sceneJson = JSON.parse(readLocalFile(projectDir, scenePath(variantId)));
     if (!fileExists(projectDir, ASSETS_JSON_PATH))
-        return DEFAULT_GAME_PATH;
+        return null;
     const assetsJson = JSON.parse(readLocalFile(projectDir, ASSETS_JSON_PATH));
-    const resolved = resolveGameConfigPath(sceneJson, assetsJson);
-    return resolved ?? DEFAULT_GAME_PATH;
+    return resolveGameConfigPath(sceneJson, assetsJson);
 }
 function listLocalScenes(projectDir) {
     if (!fileExists(projectDir, MANIFEST_PATH))
         return [];
     const manifestJson = JSON.parse(readLocalFile(projectDir, MANIFEST_PATH));
+    if (fileExists(projectDir, ASSETS_JSON_PATH)) {
+        const assetsJson = JSON.parse(readLocalFile(projectDir, ASSETS_JSON_PATH));
+        return listScenesWithGameConfig(manifestJson, (sceneId) => {
+            const sp = scenePath(sceneId);
+            if (!fileExists(projectDir, sp))
+                return null;
+            return JSON.parse(readLocalFile(projectDir, sp));
+        }, assetsJson);
+    }
     return listScenesFromManifest(manifestJson);
 }
-// ─── Unified prefab loading ──────────────────────────────────────────────────
 function loadPrefabs(projectDir, systemType, opts) {
     if (systemType === 'external-theme') {
         const themeId = resolveThemeId(projectDir, opts);
@@ -170,11 +327,22 @@ function loadPrefabs(projectDir, systemType, opts) {
         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);
+    const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+    if (configPath) {
+        // 有场景级 GameConfig → 从中读取 extensions 和 config
+        const gameConfigJson = loadGameConfig(projectDir, configPath);
+        const { extensions, config } = parseGameConfig(gameConfigJson);
+        return buildExtensionPrefabs(metaMap, { extensions, config }, configPath);
+    }
+    // 无场景级 GameConfig → 从 DefaultGame.json 只读 Extensions 列表（不读 Config 值）
+    if (fileExists(projectDir, DEFAULT_GAME_PATH)) {
+        const defaultGameJson = loadGameConfig(projectDir, DEFAULT_GAME_PATH);
+        const { extensions } = parseGameConfig(defaultGameJson);
+        return buildExtensionPrefabs(metaMap, { extensions, config: {} }, DEFAULT_GAME_PATH);
+    }
+    // 完全无 GameConfig → 仅根据 MetaData 构建（全部标记为未启用）
+    return buildExtensionPrefabs(metaMap, { extensions: [], config: {} }, '');
 }
 // ─── dotpath helper ──────────────────────────────────────────────────────────
 function getByDotPath(obj, path) {
@@ -222,12 +390,58 @@ function coerceValue(rawValue, fieldType) {
         return rawValue;
     }
 }
+/** Coerce batch JSON value: strings go through coerceValue; other types used as-is. */
+function coerceBatchLeaf(raw, fieldType) {
+    if (typeof raw === 'string')
+        return coerceValue(raw, fieldType);
+    return raw;
+}
+function readBatchJson(filePath) {
+    if (filePath)
+        return readFileSync(filePath, 'utf-8');
+    return readFileSync(0, 'utf-8');
+}
+function buildSingleDescribeJson(found) {
+    if (found.systemType === 'external-theme' && found.jsonSchema) {
+        const fields = normalizeDescribeFields(describeJsonSchemaFields(found.jsonSchema, found.currentValue));
+        return {
+            key: found.key,
+            type: found.systemType,
+            isUsed: found.isUsed,
+            description: found.description,
+            fields,
+            guide: buildDescribeGuide(found.key, found.isUsed),
+        };
+    }
+    if (found.configSchema) {
+        const currentValues = (found.currentValue && typeof found.currentValue === 'object')
+            ? found.currentValue
+            : {};
+        const fields = normalizeDescribeFields(describeConfigSchemaFields(found.configSchema, currentValues));
+        return {
+            key: found.key,
+            type: found.systemType,
+            isUsed: found.isUsed,
+            description: found.description,
+            configPath: found.configPath,
+            fields,
+            guide: buildDescribeGuide(found.key, found.isUsed),
+        };
+    }
+    return {
+        key: found.key,
+        type: found.systemType,
+        isUsed: found.isUsed,
+        description: found.description,
+        currentValue: found.currentValue,
+        guide: buildDescribeGuide(found.key, found.isUsed),
+    };
+}
 // ─── 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);
@@ -283,144 +497,294 @@ export function registerPrefabCommands(program) {
         .description('variants 别名（对齐前端「场景列表」术语）')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
         .action(variantsHandler);
-    // ─── list ────────────────────────────────────────────────────
-    withJsonOption(prefab.command('list'))
-        .description('列出所有 prefab 及状态')
+    withPagingOptions(withFilterOptions(withJsonOption(prefab.command('list'))))
+        .description('列出 prefab 及状态（支持分页与正则过滤）')
         .option('--variant <id>', '指定变体（External: themeId；PlayCanvas: sceneId）')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .option('--with-values', '附带当前值摘要（已启用项）')
         .action((opts) => {
-        const projectDir = resolveProjectDir(opts);
-        const systemType = detectProjectType(projectDir);
-        const prefabs = loadPrefabs(projectDir, systemType, opts);
-        const asJson = Boolean(opts.json);
-        let variantNote = opts.variant ?? null;
-        if (systemType === 'external-theme' && !opts.variant) {
-            variantNote = resolveThemeId(projectDir, opts);
-        }
-        const payload = {
-            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,
-            })),
-        };
-        outputResult(asJson, payload, () => {
-            console.log(`项目类型: ${projectTypeLabel(systemType)}`);
-            console.log(`变体上下文: ${variantNote ?? '（默认）'}`);
-            console.log(`共 ${prefabs.length} 个 prefab，已启用 ${prefabs.filter((p) => p.isUsed).length} 个。`);
-            console.log('');
-            const keyW = Math.min(28, Math.max(8, ...prefabs.map((p) => p.key.length)));
-            for (let i = 0; i < prefabs.length; i++) {
-                const p = prefabs[i];
-                const status = p.isUsed ? '已启用' : '未启用';
-                const label = p.key.padEnd(keyW);
-                console.log(`  ${label}  ${status}`);
-                const detailIndent = '      ';
-                if (p.name && p.name !== p.key) {
-                    console.log(`${detailIndent}名称: ${p.name}`);
-                }
-                const desc = p.description?.trim();
-                if (desc) {
-                    console.log(`${detailIndent}说明: ${desc}`);
+        try {
+            const projectDir = resolveProjectDir(opts);
+            const systemType = detectProjectType(projectDir);
+            const all = loadPrefabs(projectDir, systemType, opts);
+            const asJson = Boolean(opts.json);
+            const variantResolved = resolveVariantResolved(projectDir, systemType, opts);
+            let variantNote = opts.variant ?? null;
+            if (systemType === 'external-theme' && !opts.variant) {
+                variantNote = resolveThemeId(projectDir, opts);
+            }
+            const summary = buildSummary(systemType, variantResolved, all);
+            const filtered = filterPrefabsList(all, {
+                match: opts.match,
+                matchCase: Boolean(opts.matchCase),
+                usedOnly: Boolean(opts.usedOnly),
+                unusedOnly: Boolean(opts.unusedOnly),
+                changedOnly: Boolean(opts.changedOnly),
+            });
+            const { limit, offset } = parsePaging(opts);
+            const { slice, page } = slicePage(filtered, limit, offset);
+            const prefabRows = slice.map((p) => {
+                const row = {
+                    key: p.key,
+                    name: p.name,
+                    description: p.description,
+                    isUsed: p.isUsed,
+                    type: p.systemType,
+                };
+                if (opts.withValues) {
+                    row.valuePreview = valuePreview(p);
                 }
-                if (i < prefabs.length - 1) {
-                    console.log('');
+                return row;
+            });
+            const payload = {
+                summary,
+                page,
+                prefabs: prefabRows,
+            };
+            outputResult(asJson, payload, () => {
+                console.log(`项目类型: ${projectTypeLabel(systemType)}`);
+                console.log(`变体上下文: ${variantNote ?? '（默认）'}`);
+                console.log(`概况: 共 ${summary.total} 个 prefab，已启用 ${summary.enabled}，未启用 ${summary.disabled}，` +
+                    `相对默认值有改动 ${summary.changed} 个。`);
+                console.log(`本页: ${filtered.length === 0 ? 0 : offset + 1}-${offset + slice.length} / 过滤后 ${page.total} 条` +
+                    (page.hasMore ? `（尚有更多，使用 --offset ${offset + limit}）` : ''));
+                console.log('');
+                const maxKeyLen = slice.reduce((m, p) => Math.max(m, p.key.length), 0);
+                const keyW = Math.min(28, Math.max(8, maxKeyLen));
+                for (let i = 0; i < slice.length; i++) {
+                    const p = slice[i];
+                    const status = p.isUsed ? '已启用' : '未启用';
+                    const label = p.key.padEnd(keyW);
+                    console.log(`  ${label}  ${status}`);
+                    const detailIndent = '      ';
+                    if (opts.withValues && p.isUsed) {
+                        const pv = valuePreview(p, 200);
+                        if (pv)
+                            console.log(`${detailIndent}值摘要: ${pv}`);
+                    }
+                    if (p.name && p.name !== p.key) {
+                        console.log(`${detailIndent}名称: ${p.name}`);
+                    }
+                    const desc = p.description?.trim();
+                    if (desc) {
+                        console.log(`${detailIndent}说明: ${desc}`);
+                    }
+                    if (i < slice.length - 1)
+                        console.log('');
                 }
-            }
-        });
+            });
+        }
+        catch (e) {
+            if (isProjectDetectError(e))
+                throw e;
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error(`Error: ${msg}`);
+            process.exit(1);
+        }
     });
-    // ─── describe ────────────────────────────────────────────────
-    withJsonOption(prefab.command('describe <key>'))
-        .description('显示 prefab 完整字段信息')
+    withPagingOptions(withFilterOptions(withJsonOption(prefab.command('diff'))))
+        .description('仅显示相对 schema 默认值有差异的字段')
         .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);
-        }
-        const asJson = Boolean(opts.json);
-        if (found.systemType === 'external-theme' && found.jsonSchema) {
-            const fields = describeJsonSchemaFields(found.jsonSchema, found.currentValue);
-            const payload = {
-                key: found.key,
-                type: found.systemType,
-                isUsed: found.isUsed,
-                description: found.description,
-                fields,
-            };
+        .action((opts) => {
+        try {
+            const projectDir = resolveProjectDir(opts);
+            const systemType = detectProjectType(projectDir);
+            const all = loadPrefabs(projectDir, systemType, opts);
+            const asJson = Boolean(opts.json);
+            const variantResolved = resolveVariantResolved(projectDir, systemType, opts);
+            const summary = buildSummary(systemType, variantResolved, all);
+            const withDiff = all.filter((p) => getPrefabFieldDiffs(p).length > 0);
+            const filtered = filterPrefabsList(withDiff, {
+                match: opts.match,
+                matchCase: Boolean(opts.matchCase),
+                usedOnly: Boolean(opts.usedOnly),
+                unusedOnly: Boolean(opts.unusedOnly),
+                changedOnly: Boolean(opts.changedOnly),
+            });
+            const { limit, offset } = parsePaging(opts);
+            const { slice, page } = slicePage(filtered, limit, offset);
+            const items = slice.map((p) => ({
+                key: p.key,
+                isUsed: p.isUsed,
+                diffs: getPrefabFieldDiffs(p),
+            }));
+            const payload = { summary, page, prefabs: items };
             outputResult(asJson, payload, () => {
-                console.log(`Prefab: ${found.key}`);
-                console.log(`类型: ${projectTypeLabel(found.systemType)}`);
-                console.log(`状态: ${found.isUsed ? '已启用' : '未启用'}`);
-                if (found.description)
-                    console.log(`说明: ${found.description}`);
+                console.log(`概况: ${summary.total} 个 prefab，其中 ${withDiff.length} 个有字段级差异。`);
+                console.log(`本页: ${page.total === 0 ? 0 : offset + 1}-${offset + slice.length} / ${page.total}`);
                 console.log('');
-                console.log('字段:');
-                for (const f of fields) {
-                    console.log(`  • ${describeFieldLine(f)}`);
+                for (const it of items) {
+                    console.log(`  ${it.key}:`);
+                    for (const d of it.diffs) {
+                        console.log(`    ${d.path}: 当前 ${formatHumanValue(d.current)}  |  默认 ${formatHumanValue(d.default)}`);
+                    }
+                    console.log('');
                 }
             });
         }
-        else if (found.configSchema) {
-            const currentValues = (found.currentValue && typeof found.currentValue === 'object')
-                ? found.currentValue
-                : {};
-            const fields = describeConfigSchemaFields(found.configSchema, currentValues);
+        catch (e) {
+            if (isProjectDetectError(e))
+                throw e;
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error(`Error: ${msg}`);
+            process.exit(1);
+        }
+    });
+    withPagingOptions(withFilterOptions(withJsonOption(prefab.command('describe [key]'))))
+        .description('显示 prefab 字段信息；省略 key 时需 --all')
+        .option('--all', '列出（过滤后）全部 prefab 的字段详情，分页输出')
+        .option('--variant <id>', '指定变体')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action((key, opts) => {
+        try {
+            const projectDir = resolveProjectDir(opts);
+            const systemType = detectProjectType(projectDir);
+            const prefabs = loadPrefabs(projectDir, systemType, opts);
+            const asJson = Boolean(opts.json);
+            const variantResolved = resolveVariantResolved(projectDir, systemType, opts);
+            const summary = buildSummary(systemType, variantResolved, prefabs);
+            const allMode = Boolean(opts.all);
+            if (allMode && key) {
+                console.error('Error: 不能同时使用位置参数 key 与 --all。');
+                process.exit(1);
+            }
+            if (!allMode && !key) {
+                console.error('Error: 请指定 <key> 或传入 --all。');
+                process.exit(1);
+            }
+            if (!allMode && key) {
+                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);
+                }
+                const payload = buildSingleDescribeJson(found);
+                outputResult(asJson, payload, () => {
+                    console.log(`Prefab: ${found.key}`);
+                    console.log(`类型: ${projectTypeLabel(found.systemType)}`);
+                    console.log(`状态: ${found.isUsed ? '已启用' : '未启用'}`);
+                    if (found.description)
+                        console.log(`说明: ${found.description}`);
+                    console.log('');
+                    if (isDescribeJsonWithFields(payload)) {
+                        console.log('字段:');
+                        for (const f of payload.fields) {
+                            console.log(`  • ${describeFieldLine(f)}`);
+                        }
+                    }
+                    else {
+                        console.log('当前值:');
+                        console.log(formatHumanValue(payload.currentValue));
+                    }
+                });
+                return;
+            }
+            const filtered = filterPrefabsList(prefabs, {
+                match: opts.match,
+                matchCase: Boolean(opts.matchCase),
+                usedOnly: Boolean(opts.usedOnly),
+                unusedOnly: Boolean(opts.unusedOnly),
+                changedOnly: Boolean(opts.changedOnly),
+            });
+            const { limit, offset } = parsePaging(opts);
+            const { slice, page } = slicePage(filtered, limit, offset);
+            const blocks = slice.map((p) => buildSingleDescribeJson(p));
             const payload = {
-                key: found.key,
-                type: found.systemType,
-                isUsed: found.isUsed,
-                description: found.description,
-                configPath: found.configPath,
-                fields,
+                summary,
+                page,
+                guide: {
+                    workflow: [
+                        'playcraft prefab list --json --limit 20 --offset 0',
+                        'playcraft prefab describe --all --json --match "<regex>" --limit 20 --offset 0',
+                    ],
+                },
+                prefabs: blocks,
             };
             outputResult(asJson, payload, () => {
-                console.log(`Prefab: ${found.key}`);
-                console.log(`类型: ${projectTypeLabel(found.systemType)}`);
-                console.log(`状态: ${found.isUsed ? '已启用' : '未启用'}`);
-                if (found.configPath)
-                    console.log(`配置: ${found.configPath}`);
-                if (found.description)
-                    console.log(`说明: ${found.description}`);
-                console.log('');
-                console.log('字段:');
-                for (const f of fields) {
-                    console.log(`  • ${describeFieldLine(f)}`);
+                console.log(`概况: ${summary.total} 个 prefab；本页描述 ${blocks.length} 个（过滤后共 ${page.total}）。`);
+                for (const b of blocks) {
+                    console.log('');
+                    console.log(`=== ${b.key} ===`);
+                    if (isDescribeJsonWithFields(b)) {
+                        for (const f of b.fields) {
+                            console.log(`  • ${describeFieldLine(f)}`);
+                        }
+                    }
+                    else {
+                        console.log(formatHumanValue(b.currentValue));
+                    }
+                }
+                if (page.hasMore) {
+                    console.log('');
+                    console.log(`下一页: --offset ${offset + limit}`);
                 }
             });
         }
-        else {
-            const payload = {
-                key: found.key,
-                type: found.systemType,
-                isUsed: found.isUsed,
-                description: found.description,
-                currentValue: found.currentValue,
-            };
+        catch (e) {
+            if (isProjectDetectError(e))
+                throw e;
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error(`Error: ${msg}`);
+            process.exit(1);
+        }
+    });
+    withPagingOptions(withJsonOption(prefab.command('search <pattern>')))
+        .description('按正则搜索字段 path /说明 / 枚举（所有 prefab）')
+        .option('--match-case', '区分大小写')
+        .option('--variant <id>', '指定变体')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action((pattern, opts) => {
+        try {
+            const projectDir = resolveProjectDir(opts);
+            const systemType = detectProjectType(projectDir);
+            const prefabs = loadPrefabs(projectDir, systemType, opts);
+            const asJson = Boolean(opts.json);
+            const variantResolved = resolveVariantResolved(projectDir, systemType, opts);
+            const summary = buildSummary(systemType, variantResolved, prefabs);
+            const re = tryCompileRegex(pattern, Boolean(opts.matchCase));
+            const hits = [];
+            for (const p of prefabs) {
+                for (const f of getPrefabFieldDescriptors(p)) {
+                    const hay = [
+                        f.path,
+                        f.description ?? '',
+                        ...(f.enumOptions ?? []),
+                    ].join('\n');
+                    if (re.test(hay)) {
+                        hits.push({
+                            prefabKey: p.key,
+                            fieldPath: f.path,
+                            type: f.type,
+                            description: f.description,
+                            currentValue: f.currentValue,
+                            default: f.default,
+                        });
+                    }
+                }
+            }
+            const { limit, offset } = parsePaging(opts);
+            const { slice, page } = slicePage(hits, limit, offset);
+            const payload = { summary, page, hits: slice };
             outputResult(asJson, payload, () => {
-                console.log(`Prefab: ${found.key}`);
-                console.log(`类型: ${projectTypeLabel(found.systemType)}`);
-                console.log(`状态: ${found.isUsed ? '已启用' : '未启用'}`);
-                if (found.description)
-                    console.log(`说明: ${found.description}`);
-                console.log('');
-                console.log('当前值:');
-                console.log(formatHumanValue(found.currentValue));
+                console.log(`命中 ${hits.length} 条字段（本页 ${slice.length} 条）`);
+                for (const h of slice) {
+                    console.log(`  ${h.prefabKey}.${h.fieldPath}  (${h.type})`);
+                    if (h.description)
+                        console.log(`    ${h.description}`);
+                }
+                if (page.hasMore)
+                    console.log(`下一页: --offset ${offset + limit}`);
             });
         }
+        catch (e) {
+            if (isProjectDetectError(e))
+                throw e;
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error(`Error: ${msg}`);
+            process.exit(1);
+        }
     });
-    // ─── get ─────────────────────────────────────────────────────
     withJsonOption(prefab.command('get <key> [field]'))
         .description('获取 prefab 或子字段的当前值')
         .option('--variant <id>', '指定变体')
@@ -454,7 +818,6 @@ export function registerPrefabCommands(program) {
             }
         });
     });
-    // ─── set ─────────────────────────────────────────────────────
     withJsonOption(prefab.command('set <key> <field> <value>'))
         .description('修改 prefab 子字段值（带校验）')
         .option('--variant <id>', '指定变体')
@@ -502,18 +865,12 @@ export function registerPrefabCommands(program) {
             });
         }
         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);
@@ -524,16 +881,192 @@ export function registerPrefabCommands(program) {
                     process.exit(1);
                 }
             }
-            const newValues = { ...currentValues, [field]: coerced };
-            const updated = updateGameConfigValue(gameConfigJson, configKey, newValues);
-            writeGameConfig(projectDir, configPath, updated);
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+            if (configPath) {
+                // 有场景级 GameConfig → 写入 GameConfig 文件
+                const gameConfigJson = loadGameConfig(projectDir, configPath);
+                const { config } = parseGameConfig(gameConfigJson);
+                const configKey = meta.configPath ? parseConfigKey(meta.configPath) : meta.name;
+                const existingKey = findConfigKeyCaseInsensitive(config, configKey);
+                const currentValues = (existingKey ? config[existingKey] : {}) ?? {};
+                const newValues = { ...currentValues, [field]: coerced };
+                const updated = updateGameConfigValue(gameConfigJson, configKey, newValues);
+                writeGameConfig(projectDir, configPath, updated);
+            }
+            else {
+                // 无场景级 GameConfig → 写 MetaData.json 的 configSchema.{field}.default
+                writeMetaDataDefault(projectDir, key, field, coerced);
+            }
             const payload = { success: true, key, field, value: coerced };
             outputResult(asJson, payload, () => {
                 console.log(`已更新 ${key}.${field} = ${formatHumanValue(coerced)}`);
             });
         }
     });
-    // ─── enable ──────────────────────────────────────────────────
+    withJsonOption(prefab.command('set-batch'))
+        .description('从文件或 stdin 读取 JSON，一次修改多个 prefab 字段（校验全部通过后写盘）')
+        .option('--file <path>', 'JSON 文件路径（默认读 stdin）')
+        .option('--variant <id>', '指定变体')
+        .option('--project-dir <path>', '项目根目录（默认 cwd）')
+        .action((opts) => {
+        const projectDir = resolveProjectDir(opts);
+        const systemType = detectProjectType(projectDir);
+        const asJson = Boolean(opts.json);
+        let raw;
+        try {
+            raw = readBatchJson(opts.file);
+        }
+        catch (e) {
+            console.error(`Error: 无法读取 batch输入: ${e instanceof Error ? e.message : e}`);
+            process.exit(1);
+        }
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            console.error('Error: batch 输入为空。请使用 --file 或管道传入 JSON。');
+            process.exit(1);
+        }
+        let batch;
+        try {
+            batch = JSON.parse(trimmed);
+        }
+        catch (e) {
+            console.error(`Error: batch JSON 解析失败: ${e instanceof Error ? e.message : e}`);
+            process.exit(1);
+        }
+        if (!batch || typeof batch !== 'object' || Array.isArray(batch)) {
+            console.error('Error: batch 必须是形如 { "prefabKey": { "field": value } } 的对象。');
+            process.exit(1);
+        }
+        try {
+            if (systemType === 'external-theme') {
+                const themeId = resolveThemeId(projectDir, opts);
+                const schema = loadThemeSchema(projectDir);
+                let data = loadThemeData(projectDir, themeId);
+                const prefabs = parseThemePrefabs(schema, data, themeId);
+                for (const [prefabKey, fieldMap] of Object.entries(batch)) {
+                    if (!fieldMap || typeof fieldMap !== 'object' || Array.isArray(fieldMap)) {
+                        throw new Error(`prefab "${prefabKey}" 的值必须是对象（字段 map）`);
+                    }
+                    const found = prefabs.find((p) => p.key === prefabKey);
+                    if (!found) {
+                        throw new Error(`prefab "${prefabKey}" 不存在`);
+                    }
+                    const currentValue = data[prefabKey];
+                    let newValue;
+                    if (found.jsonSchema?.type === 'object') {
+                        let obj = (currentValue && typeof currentValue === 'object' && !Array.isArray(currentValue))
+                            ? { ...currentValue }
+                            : {};
+                        for (const [field, rawVal] of Object.entries(fieldMap)) {
+                            const fieldSchema = resolveJsonSchemaField(found.jsonSchema, field);
+                            const fieldType = fieldSchema?.type ?? 'string';
+                            const coerced = coerceBatchLeaf(rawVal, fieldType);
+                            if (fieldSchema) {
+                                const result = validateThemeValue(fieldSchema, coerced);
+                                if (!result.valid) {
+                                    throw new Error(`${prefabKey}.${field}: ${result.errors.join('; ')}`);
+                                }
+                            }
+                            obj = setByDotPath(obj, field, coerced);
+                        }
+                        newValue = obj;
+                    }
+                    else {
+                        const entries = Object.entries(fieldMap);
+                        if (entries.length !== 1) {
+                            throw new Error(`prefab "${prefabKey}" 非 object schema，batch 内只能包含一个字段`);
+                        }
+                        const [field, rawVal] = entries[0];
+                        const fieldSchema = resolveJsonSchemaField(found.jsonSchema, field);
+                        const fieldType = fieldSchema?.type ?? 'string';
+                        const coerced = coerceBatchLeaf(rawVal, fieldType);
+                        if (fieldSchema) {
+                            const result = validateThemeValue(fieldSchema, coerced);
+                            if (!result.valid) {
+                                throw new Error(`${prefabKey}.${field}: ${result.errors.join('; ')}`);
+                            }
+                        }
+                        newValue = coerced;
+                    }
+                    data = mergeThemeDataKey(data, prefabKey, newValue);
+                }
+                writeThemeData(projectDir, themeId, data);
+            }
+            else {
+                const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+                const metaMap = scanExtensionMetaData(projectDir);
+                if (configPath) {
+                    // 有场景级 GameConfig → 写入 GameConfig 文件
+                    let gameConfigJson = loadGameConfig(projectDir, configPath);
+                    for (const [extKey, fieldMap] of Object.entries(batch)) {
+                        if (!fieldMap || typeof fieldMap !== 'object' || Array.isArray(fieldMap)) {
+                            throw new Error(`extension "${extKey}" 的值必须是对象（字段 map）`);
+                        }
+                        const meta = metaMap.get(extKey);
+                        if (!meta) {
+                            throw new Error(`extension "${extKey}" 不存在`);
+                        }
+                        const configKey = meta.configPath ? parseConfigKey(meta.configPath) : meta.name;
+                        const { config } = parseGameConfig(gameConfigJson);
+                        const existingKey = findConfigKeyCaseInsensitive(config, configKey);
+                        let currentValues = (existingKey ? config[existingKey] : {}) ?? {};
+                        currentValues = typeof currentValues === 'object' && !Array.isArray(currentValues)
+                            ? { ...currentValues }
+                            : {};
+                        for (const [field, rawVal] of Object.entries(fieldMap)) {
+                            const fieldDef = meta.configSchema?.[field];
+                            const fieldType = fieldDef?.type ?? 'string';
+                            const coerced = coerceBatchLeaf(rawVal, fieldType);
+                            if (fieldDef) {
+                                const result = validateConfigValue(fieldDef, coerced);
+                                if (!result.valid) {
+                                    throw new Error(`${extKey}.${field}: ${result.errors.join('; ')}`);
+                                }
+                            }
+                            currentValues = setByDotPath(currentValues, field, coerced);
+                        }
+                        gameConfigJson = updateGameConfigValue(gameConfigJson, configKey, currentValues);
+                    }
+                    writeGameConfig(projectDir, configPath, gameConfigJson);
+                }
+                else {
+                    // 无场景级 GameConfig → 逐个写 MetaData.json defaults
+                    for (const [extKey, fieldMap] of Object.entries(batch)) {
+                        if (!fieldMap || typeof fieldMap !== 'object' || Array.isArray(fieldMap)) {
+                            throw new Error(`extension "${extKey}" 的值必须是对象（字段 map）`);
+                        }
+                        const meta = metaMap.get(extKey);
+                        if (!meta) {
+                            throw new Error(`extension "${extKey}" 不存在`);
+                        }
+                        const coercedValues = {};
+                        for (const [field, rawVal] of Object.entries(fieldMap)) {
+                            const fieldDef = meta.configSchema?.[field];
+                            const fieldType = fieldDef?.type ?? 'string';
+                            const coerced = coerceBatchLeaf(rawVal, fieldType);
+                            if (fieldDef) {
+                                const result = validateConfigValue(fieldDef, coerced);
+                                if (!result.valid) {
+                                    throw new Error(`${extKey}.${field}: ${result.errors.join('; ')}`);
+                                }
+                            }
+                            coercedValues[field] = coerced;
+                        }
+                        writeMetaDataDefaults(projectDir, extKey, coercedValues);
+                    }
+                }
+            }
+            const payload = { success: true, updatedKeys: Object.keys(batch) };
+            outputResult(asJson, payload, () => {
+                console.log(`已批量更新: ${Object.keys(batch).join(', ')}`);
+            });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error(`Error: ${msg}`);
+            process.exit(1);
+        }
+    });
     withJsonOption(prefab.command('enable <key>'))
         .description('启用 prefab')
         .option('--variant <id>', '指定变体')
@@ -561,7 +1094,7 @@ export function registerPrefabCommands(program) {
             });
         }
         else {
-            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant) ?? DEFAULT_GAME_PATH;
             const gameConfigJson = loadGameConfig(projectDir, configPath);
             const { extensions } = parseGameConfig(gameConfigJson);
             if (extensions.includes(key)) {
@@ -579,7 +1112,6 @@ export function registerPrefabCommands(program) {
             });
         }
     });
-    // ─── disable ─────────────────────────────────────────────────
     withJsonOption(prefab.command('disable <key>'))
         .description('禁用 prefab')
         .option('--variant <id>', '指定变体')
@@ -606,7 +1138,7 @@ export function registerPrefabCommands(program) {
             });
         }
         else {
-            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant) ?? DEFAULT_GAME_PATH;
             const gameConfigJson = loadGameConfig(projectDir, configPath);
             const { extensions } = parseGameConfig(gameConfigJson);
             const filtered = extensions.filter((n) => n !== key);
@@ -625,7 +1157,6 @@ export function registerPrefabCommands(program) {
             });
         }
     });
-    // ─── switch ──────────────────────────────────────────────────
     withJsonOption(prefab.command('switch <variant>'))
         .description('切换活跃变体（External: 修改 index.ts；PlayCanvas: 指定场景上下文）')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
@@ -669,7 +1200,6 @@ export function registerPrefabCommands(program) {
         }
     });
 }
-// ─── JSON Schema field resolver ──────────────────────────────────────────────
 function resolveJsonSchemaField(schema, dotPath) {
     const parts = dotPath.split('.');
     let cur = schema;

package/dist/commands/tools.js

@@ -3,6 +3,7 @@ import { dirname, join, parse } from 'path';
 import { tmpdir } from 'os';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 const TMP_DIR = join(tmpdir(), 'playcraft');
+const MAX_REFERENCE_IMAGES = 8;
 function ensureTmpDir() {
     mkdirSync(TMP_DIR, { recursive: true });
 }
@@ -85,11 +86,18 @@ function sniffImageExtension(buf) {
 }
 /** 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) {
+    try {
+        const { dir, name, ext } = parse(outputPath);
+        if (ext.toLowerCase() === wantExt) {
+            return outputPath;
+        }
+        return join(dir, `${name}${wantExt}`);
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        console.warn(`Could not adjust output path for extension ${wantExt} (${detail}); using path as given: ${outputPath}`);
         return outputPath;
     }
-    return join(dir, `${name}${wantExt}`);
 }
 function collectReferenceImagePaths(value, previous) {
     return previous.concat([value]);
@@ -100,7 +108,37 @@ function mimeTypeForImagePath(filePath) {
         return 'image/png';
     if (ext === 'webp')
         return 'image/webp';
-    return 'image/jpeg';
+    if (ext === 'jpg' || ext === 'jpeg')
+        return 'image/jpeg';
+    if (ext === undefined || ext === '') {
+        throw new Error(`Reference image path has no file extension: ${filePath}. Use .png, .webp, .jpg, or .jpeg.`);
+    }
+    throw new Error(`Unsupported reference image extension ".${ext}" in ${filePath}. Only png, webp, jpg, and jpeg are allowed.`);
+}
+/** Load reference images for generate-image; skip unreadable paths after console.warn (same tolerance as output path resolve). */
+function collectReferenceImagePayloads(paths) {
+    if (paths.length === 0)
+        return undefined;
+    const out = [];
+    for (const p of paths) {
+        try {
+            const mimeType = mimeTypeForImagePath(p);
+            out.push({
+                base64: readFileSync(p).toString('base64'),
+                mimeType,
+            });
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            const code = e && typeof e === 'object' && 'code' in e ? String(e.code) : '';
+            const hint = code ? ` (${code})` : '';
+            console.warn(`Skipping reference image (read failed): ${p}${hint}\n  ${detail}`);
+        }
+    }
+    if (paths.length > 0 && out.length === 0) {
+        console.warn('All reference images failed to load; continuing with text-only generation.');
+    }
+    return out.length > 0 ? out : undefined;
 }
 export function registerToolsCommands(program) {
     const tools = program
@@ -117,12 +155,10 @@ export function registerToolsCommands(program) {
         .action(async (opts) => {
         try {
             const paths = opts.referenceImage ?? [];
-            const referenceImages = paths.length > 0
-                ? paths.map((p) => ({
-                    base64: readFileSync(p).toString('base64'),
-                    mimeType: mimeTypeForImagePath(p),
-                }))
-                : undefined;
+            if (paths.length > MAX_REFERENCE_IMAGES) {
+                throw new Error(`Too many reference images: ${paths.length} paths given; maximum is ${MAX_REFERENCE_IMAGES}.`);
+            }
+            const referenceImages = collectReferenceImagePayloads(paths);
             const client = new AgentApiClient();
             const result = await client.post('/generate-image', {
                 prompt: opts.prompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "private": false,
   "type": "module",
   "bin": {
@@ -17,13 +17,14 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "test": "vitest run",
+    "verify-sprite-overlay": "node scripts/verify-sprite-overlay.mjs",
     "link": "node scripts/bump-local.js && pnpm build && npm link",
     "unlink": "npm unlink -g @playcraft/cli",
     "release": "node scripts/release.js"
   },
   "dependencies": {
-    "@playcraft/build": "^0.0.27",
-    "@playcraft/common": "^0.0.16",
+    "@playcraft/build": "^0.0.29",
+    "@playcraft/common": "^0.0.18",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",