@playcraft/cli 0.0.27 → 0.0.28

package/dist/commands/image.js

@@ -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);
                         }
                     }

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, 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) {
@@ -162,7 +284,6 @@ function listLocalScenes(projectDir) {
     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);
@@ -222,12 +343,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 +450,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 +771,6 @@ export function registerPrefabCommands(program) {
             }
         });
     });
-    // ─── set ─────────────────────────────────────────────────────
     withJsonOption(prefab.command('set <key> <field> <value>'))
         .description('修改 prefab 子字段值（带校验）')
         .option('--variant <id>', '指定变体')
@@ -533,7 +849,141 @@ export function registerPrefabCommands(program) {
             });
         }
     });
-    // ─── 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);
+                let gameConfigJson = loadGameConfig(projectDir, configPath);
+                const metaMap = scanExtensionMetaData(projectDir);
+                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);
+            }
+            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>', '指定变体')
@@ -579,7 +1029,6 @@ export function registerPrefabCommands(program) {
             });
         }
     });
-    // ─── disable ─────────────────────────────────────────────────
     withJsonOption(prefab.command('disable <key>'))
         .description('禁用 prefab')
         .option('--variant <id>', '指定变体')
@@ -625,7 +1074,6 @@ export function registerPrefabCommands(program) {
             });
         }
     });
-    // ─── switch ──────────────────────────────────────────────────
     withJsonOption(prefab.command('switch <variant>'))
         .description('切换活跃变体（External: 修改 index.ts；PlayCanvas: 指定场景上下文）')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
@@ -669,7 +1117,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

@@ -102,6 +102,20 @@ function mimeTypeForImagePath(filePath) {
         return 'image/webp';
     return 'image/jpeg';
 }
+function readReferenceImagePayload(filePath) {
+    try {
+        return {
+            base64: readFileSync(filePath).toString('base64'),
+            mimeType: mimeTypeForImagePath(filePath),
+        };
+    }
+    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})` : '';
+        throw new Error(`Failed to read reference image: ${filePath}${hint}\n  ${detail}`);
+    }
+}
 export function registerToolsCommands(program) {
     const tools = program
         .command('tools')
@@ -117,12 +131,7 @@ 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;
+            const referenceImages = paths.length > 0 ? paths.map((p) => readReferenceImagePayload(p)) : undefined;
             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.28",
   "private": false,
   "type": "module",
   "bin": {
@@ -22,8 +22,8 @@
     "release": "node scripts/release.js"
   },
   "dependencies": {
-    "@playcraft/build": "^0.0.27",
-    "@playcraft/common": "^0.0.16",
+    "@playcraft/build": "^0.0.28",
+    "@playcraft/common": "^0.0.17",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",