@playcraft/cli 0.0.31 → 0.0.33

package/dist/commands/prefab.js

@@ -4,6 +4,8 @@ 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, listScenesWithGameConfig, resolveGameConfigPath, validateThemeValue, validateConfigValue, describeJsonSchemaFields, describeConfigSchemaFields, getPrefabFieldDescriptors, getPrefabFieldDiffs, prefabHasSchemaDiff, } from '@playcraft/common/prefab';
 const DEFAULT_PAGE_LIMIT = 50;
+/** 场景在 manifest / CLI 中列出但解析不到 GameConfig 时的人读标签 */
+const NO_SCENE_GAMECONFIG_LABEL = '（无场景级 GameConfig）';
 /** 无法识别 External / PlayCanvas 项目类型（供测试在 mock process.exit 后通过 instanceof 识别）。 */
 export class ProjectDetectError extends Error {
     name = 'ProjectDetectError';
@@ -186,7 +188,7 @@ function resolveVariantResolved(projectDir, systemType, opts) {
     if (systemType === 'external-theme') {
         return resolveThemeId(projectDir, opts);
     }
-    return null;
+    return getMainSceneId(projectDir);
 }
 // ─── External Theme helpers ──────────────────────────────────────────────────
 function loadThemeSchema(projectDir) {
@@ -240,6 +242,39 @@ function resolveThemeId(projectDir, opts) {
     throw new Error('unreachable');
 }
 // ─── PlayCanvas / LiteCreator helpers ────────────────────────────────────────
+/**
+ * manifest 中的主场景 ID（与编辑器「当前入口场景」对齐）。
+ *
+ * 优先级：1) isMain: true  2) 仅有一个场景时自动视为当前活跃场景  3) 无法确定则 null
+ */
+function getMainSceneId(projectDir) {
+    if (!fileExists(projectDir, MANIFEST_PATH))
+        return null;
+    try {
+        const manifestJson = JSON.parse(readLocalFile(projectDir, MANIFEST_PATH));
+        const scenes = manifestJson.scenes;
+        if (!Array.isArray(scenes) || scenes.length === 0)
+            return null;
+        const mainScene = scenes.find((s) => !!s && typeof s === 'object' && s.isMain === true);
+        if (mainScene != null && (mainScene.id != null || mainScene.uniqueId != null)) {
+            return String(mainScene.id ?? mainScene.uniqueId);
+        }
+        if (scenes.length === 1) {
+            const only = scenes[0];
+            if (only && typeof only === 'object') {
+                const o = only;
+                if (o.id != null)
+                    return String(o.id);
+                if (o.uniqueId != null)
+                    return String(o.uniqueId);
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 function loadGameConfig(projectDir, configPath) {
     const raw = readLocalFile(projectDir, configPath);
     return JSON.parse(raw);
@@ -266,85 +301,71 @@ 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');
+function extensionMetaDataFile(projectDir, extensionName) {
+    return join(projectDir, LITE_CREATOR_EXTENSIONS_DIR, extensionName, 'MetaData.json');
 }
-/** 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');
+function mutateExtensionMetaData(projectDir, extensionName, apply) {
+    const metaPath = extensionMetaDataFile(projectDir, extensionName);
     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;
-        }
-    }
+    apply(configSchema);
     writeFileSync(metaPath, JSON.stringify(metaData, null, 2), 'utf-8');
 }
-/**
- * Get the main scene ID from manifest.json.
- *
- * Priority:
- * 1. Scene with isMain: true
- * 2. If only one scene exists, use that scene
- * 3. If multiple scenes without isMain, return null (caller should fallback)
- */
-function getMainSceneId(projectDir) {
-    if (!fileExists(projectDir, MANIFEST_PATH))
-        return null;
-    try {
-        const manifestJson = JSON.parse(readLocalFile(projectDir, MANIFEST_PATH));
-        const scenes = manifestJson?.scenes;
-        if (!Array.isArray(scenes) || scenes.length === 0)
-            return null;
-        // Priority 1: Find scene with isMain: true
-        const mainScene = scenes.find((s) => s.isMain === true);
-        if (mainScene?.id)
-            return String(mainScene.id);
-        // Priority 2: If only one scene, use it
-        if (scenes.length === 1 && scenes[0]?.id) {
-            return String(scenes[0].id);
+function writeMetaDataDefault(projectDir, extensionName, field, value) {
+    mutateExtensionMetaData(projectDir, extensionName, (configSchema) => {
+        if (!configSchema[field]) {
+            throw new Error(`MetaData.json for "${extensionName}" has no configSchema.${field}`);
         }
-        // Multiple scenes without isMain → cannot determine
+        configSchema[field].default = value;
+    });
+}
+function writeMetaDataDefaults(projectDir, extensionName, values) {
+    mutateExtensionMetaData(projectDir, extensionName, (configSchema) => {
+        for (const [field, value] of Object.entries(values)) {
+            if (configSchema[field]) {
+                configSchema[field].default = value;
+            }
+        }
+    });
+}
+/** 仅按场景 ID 解析 GameConfig（不查主场景）。 */
+function resolveGameConfigPathForSceneId(projectDir, sceneId) {
+    if (!fileExists(projectDir, scenePath(sceneId)))
         return null;
-    }
-    catch {
+    const sceneJson = JSON.parse(readLocalFile(projectDir, scenePath(sceneId)));
+    if (!fileExists(projectDir, ASSETS_JSON_PATH))
         return null;
-    }
+    const assetsJson = JSON.parse(readLocalFile(projectDir, ASSETS_JSON_PATH));
+    return resolveGameConfigPath(sceneJson, assetsJson);
 }
 /**
- * Resolve the GameConfig file path for a given variant (scene).
- *
- * If variantId is not provided, automatically detect the current scene:
- * 1. Scene with isMain: true in manifest.json
- * 2. If only one scene exists, use that scene
- * 3. If multiple scenes without isMain, return null (fallback to MetaData.json)
+ * 解析当前变体下的 GameConfig 路径。无法解析时返回 null（list 回退 DefaultGame 扩展；set 可写 MetaData）。
+ * 未传 variantId 时用 manifest 主场景（isMain / 单场景）。
  */
 function resolveGameConfigPathForVariant(projectDir, variantId) {
-    // Auto-detect scene if not specified
     const sceneId = variantId ?? getMainSceneId(projectDir);
     if (!sceneId)
         return null;
-    if (!fileExists(projectDir, scenePath(sceneId)))
-        return null;
-    const sceneJson = JSON.parse(readLocalFile(projectDir, scenePath(sceneId)));
-    if (!fileExists(projectDir, ASSETS_JSON_PATH))
-        return null;
-    const assetsJson = JSON.parse(readLocalFile(projectDir, ASSETS_JSON_PATH));
-    return resolveGameConfigPath(sceneJson, assetsJson);
+    return resolveGameConfigPathForSceneId(projectDir, sceneId);
+}
+/** PlayCanvas：`prefab list` 等人读「变体上下文」一行话。 */
+function liteCreatorVariantHumanNote(projectDir, explicitVariant) {
+    if (explicitVariant) {
+        const p = resolveGameConfigPathForSceneId(projectDir, explicitVariant);
+        return p != null ? `场景 ${explicitVariant} → ${p}` : `场景 ${explicitVariant}（${NO_SCENE_GAMECONFIG_LABEL}；set 可走 MetaData）`;
+    }
+    const mainId = getMainSceneId(projectDir);
+    const gc = resolveGameConfigPathForVariant(projectDir, undefined);
+    if (mainId != null) {
+        return gc != null
+            ? `主场景 ${mainId} → ${gc}`
+            : `主场景 ${mainId}（未解析到 GameConfig；list 读 ${DEFAULT_GAME_PATH} 扩展，set 写 MetaData）`;
+    }
+    return `无主场景标记 → 扩展列表：${DEFAULT_GAME_PATH}；set / set-batch：各扩展 MetaData.json`;
 }
 function listLocalScenes(projectDir) {
     if (!fileExists(projectDir, MANIFEST_PATH))
@@ -361,6 +382,21 @@ function listLocalScenes(projectDir) {
     }
     return listScenesFromManifest(manifestJson);
 }
+/** 列表展示：补全 GameConfig 路径，并用主场景 ID 标记 isActive（与未指定 --variant 的 prefab 上下文一致）。 */
+function annotatePlaycanvasScenesForMainScene(projectDir, scenes) {
+    const mainSceneId = getMainSceneId(projectDir);
+    const annotated = scenes.map((s) => {
+        const resolved = s.gameConfigPath ?? resolveGameConfigPathForSceneId(projectDir, s.id);
+        const out = {
+            ...s,
+            isActive: mainSceneId !== null && s.id === mainSceneId,
+        };
+        if (resolved != null)
+            out.gameConfigPath = resolved;
+        return out;
+    });
+    return { scenes: annotated, mainSceneId };
+}
 function loadPrefabs(projectDir, systemType, opts) {
     if (systemType === 'external-theme') {
         const themeId = resolveThemeId(projectDir, opts);
@@ -371,18 +407,15 @@ function loadPrefabs(projectDir, systemType, opts) {
     const metaMap = scanExtensionMetaData(projectDir);
     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 ──────────────────────────────────────────────────────────
@@ -510,8 +543,18 @@ export function registerPrefabCommands(program) {
             });
         }
         else {
-            const scenes = listLocalScenes(projectDir);
-            const payload = { projectType: 'playcanvas', variants: scenes };
+            const scenesRaw = listLocalScenes(projectDir);
+            const { scenes, mainSceneId } = annotatePlaycanvasScenesForMainScene(projectDir, scenesRaw);
+            const gameConfigPath = resolveGameConfigPathForVariant(projectDir, undefined);
+            const payload = {
+                projectType: 'playcanvas',
+                variants: scenes,
+                context: {
+                    mainSceneId,
+                    gameConfigPath,
+                    usesMetaDataForSet: gameConfigPath == null,
+                },
+            };
             outputResult(asJson, payload, () => {
                 console.log(`项目类型: ${projectTypeLabel('lite-creator')}`);
                 console.log('');
@@ -521,16 +564,18 @@ export function registerPrefabCommands(program) {
                 }
                 for (const s of scenes) {
                     const mark = s.isActive ? ' *' : '';
-                    const gc = s.gameConfigPath ? `  [${s.gameConfigPath}]` : '';
-                    console.log(`  ${s.name}  (${s.id})${mark}${gc}`);
+                    const pathLabel = s.gameConfigPath ?? NO_SCENE_GAMECONFIG_LABEL;
+                    console.log(`  ${s.name}  (${s.id})  [${pathLabel}]${mark}`);
                 }
-                if (scenes.some((s) => s.isActive)) {
+                if (scenes.some((v) => v.isActive)) {
                     console.log('');
-                    console.log('标 * 为 manifest 中的主场景（isMain）。其他场景请用 --variant <sceneId> 指定上下文。');
+                    console.log('标 *：manifest 主场景（isMain，或仅 1 个场景时自动认定）。' +
+                        ' 未带 --variant：优先该场景 GameConfig；若无路径则 list 读 DefaultGame 扩展、set 写 MetaData。');
                 }
                 else {
                     console.log('');
-                    console.log('（manifest 未标记主场景；操作其他场景请用 --variant <sceneId>）');
+                    console.log('无主场景：多场景请在 manifest 设 isMain。未带 --variant 时扩展来自 ' +
+                        `${DEFAULT_GAME_PATH}，set / set-batch 写入各扩展 MetaData.json。`);
                 }
             });
         }
@@ -563,6 +608,9 @@ export function registerPrefabCommands(program) {
             if (systemType === 'external-theme' && !opts.variant) {
                 variantNote = resolveThemeId(projectDir, opts);
             }
+            else if (systemType === 'lite-creator') {
+                variantNote = liteCreatorVariantHumanNote(projectDir, opts.variant);
+            }
             const summary = buildSummary(systemType, variantResolved, all);
             const filtered = filterPrefabsList(all, {
                 match: opts.match,
@@ -933,7 +981,6 @@ export function registerPrefabCommands(program) {
             }
             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;
@@ -944,7 +991,6 @@ export function registerPrefabCommands(program) {
                 writeGameConfig(projectDir, configPath, updated);
             }
             else {
-                // 无场景级 GameConfig → 写 MetaData.json 的 configSchema.{field}.default
                 writeMetaDataDefault(projectDir, key, field, coerced);
             }
             const payload = { success: true, key, field, value: coerced };
@@ -1046,7 +1092,6 @@ export function registerPrefabCommands(program) {
                 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)) {
@@ -1080,7 +1125,6 @@ export function registerPrefabCommands(program) {
                     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）`);

package/dist/commands/recommend.js

@@ -0,0 +1,227 @@
+import { writeFileSync } from 'fs';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+function handleError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${msg}`);
+    process.exit(1);
+}
+function output(data, opts) {
+    const text = JSON.stringify(data, null, opts.pretty ? 2 : 0);
+    if (opts.output) {
+        writeFileSync(opts.output, text);
+        console.error(`Wrote ${opts.output}`);
+    }
+    else {
+        process.stdout.write(text + '\n');
+    }
+}
+function parseTagsArg(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('tags must be a JSON object');
+        }
+        return parsed;
+    }
+    catch (e) {
+        throw new Error(`Invalid --tags JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+function parseIntOpt(label, raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n))
+        throw new Error(`Invalid ${label}: "${raw}" is not a valid integer`);
+    return n;
+}
+/**
+ * 注册 `playcraft recommend <subcommand>` 命令组。
+ *
+ * Subcommands(全部调 /api/agent/tools/recommend-*):
+ *   meta            打印当前数据快照的渠道 / 指标 / 维度元数据
+ *   data            下载完整 RecommendData 快照
+ *   similar         策略一: Top-N 相似 Creative + KNN 预估
+ *   improvements    策略二: R1(可选 R2) 的 Tag 改进建议 + diff
+ *   random          策略三: 批量随机生成 Tag 组合
+ *   optimal         辅助: 理论最优 Tag 组合(perDim ω² 排序)
+ *   tag-to-atom     辅助: Tag → Atom slot 映射
+ */
+export function registerRecommendCommands(program) {
+    const rec = program
+        .command('recommend')
+        .description('Tag → Atom 推荐(后端 /api/agent/tools/recommend-*);需 .playcraft.json 或环境变量');
+    // ─── meta / data ───────────────────────────────────────────
+    rec
+        .command('meta')
+        .description('打印当前数据快照的元数据(渠道 / 指标 / 维度)')
+        .option('--pretty', '美化 JSON 输出')
+        .option('--output <file>', '写入文件而非 stdout')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.get('/recommend-meta');
+            output(result, opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    rec
+        .command('data')
+        .description('下载完整 RecommendData 快照(含 creatives/channelStats/dimValueStats)')
+        .option('--pretty', '美化 JSON 输出')
+        .option('--output <file>', '写入文件而非 stdout', '')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.get('/recommend-data');
+            output(result, opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── 策略一: similar ───────────────────────────────────────
+    rec
+        .command('similar')
+        .description('策略一: 相似 Creative + KNN 预估')
+        .requiredOption('--channel <name>', '投放渠道(Applovin|Facebook|Google|Moloco|Unity)')
+        .option('--metric <name>', '指标(ctr|cvr|cpi|ipm|cost|installs)', 'ctr')
+        .option('--creative <id>', '种子素材 ID(与 --tags 二选一)')
+        .option('--tags <json>', '种子 tags JSON(与 --creative 二选一)')
+        .option('--top <n>', 'Top-N 相似数量', '5')
+        .option('--k <n>', 'KNN 邻居数', '5')
+        .option('--no-knn', '不返回 KNN 预估')
+        .option('--include-atoms', '为每个相似项返回 atoms 配置')
+        .option('--pretty', '美化 JSON 输出')
+        .option('--output <file>', '写入文件而非 stdout')
+        .action(async (opts) => {
+        try {
+            if (!opts.creative && !opts.tags) {
+                throw new Error('Either --creative <id> or --tags <json> must be provided');
+            }
+            const body = {
+                channel: opts.channel,
+                metric: opts.metric,
+                creativeId: opts.creative,
+                tags: parseTagsArg(opts.tags),
+                topN: parseIntOpt('--top', opts.top),
+                k: parseIntOpt('--k', opts.k),
+                includeKnn: opts.knn,
+                includeAtoms: !!opts.includeAtoms,
+            };
+            const client = new AgentApiClient();
+            const result = await client.post('/recommend-similar', body);
+            output(result, opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── 策略二: improvements ──────────────────────────────────
+    rec
+        .command('improvements')
+        .description('策略二: R1 的 Tag 改进建议 + 可选 R2 diff')
+        .requiredOption('--channel <name>', '投放渠道')
+        .option('--metric <name>', '指标(ctr|cvr|cpi|ipm|cost|installs)', 'ctr')
+        .requiredOption('--r1 <id>', '当前素材 ID')
+        .option('--r2 <id>', '对照标杆素材 ID(可选)')
+        .option('--pretty', '美化 JSON 输出')
+        .option('--output <file>', '写入文件而非 stdout')
+        .action(async (opts) => {
+        try {
+            const body = {
+                channel: opts.channel,
+                metric: opts.metric,
+                r1Id: opts.r1,
+                r2Id: opts.r2,
+            };
+            const client = new AgentApiClient();
+            const result = await client.post('/recommend-improvements', body);
+            output(result, opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── 策略三: random ────────────────────────────────────────
+    rec
+        .command('random')
+        .description('策略三: 批量随机生成 Tag 组合,按预估指标排序')
+        .requiredOption('--channel <name>', '投放渠道')
+        .option('--metric <name>', '指标(ctr|cvr|cpi|ipm|cost|installs)', 'ctr')
+        .option('--batch <n>', '生成数量', '10')
+        .option('--similar-top <n>', '每条结果附带的相似 Creative 数量', '5')
+        .option('--no-atoms', '不为每条结果返回 atoms')
+        .option('--seed <n>', '随机种子(可选;提供时结果可复现)')
+        .option('--pretty', '美化 JSON 输出')
+        .option('--output <file>', '写入文件而非 stdout')
+        .action(async (opts) => {
+        try {
+            const body = {
+                channel: opts.channel,
+                metric: opts.metric,
+                batchSize: parseIntOpt('--batch', opts.batch),
+                similarTopN: parseIntOpt('--similar-top', opts.similarTop),
+                includeAtoms: opts.atoms,
+                seed: opts.seed === undefined ? undefined : parseIntOpt('--seed', opts.seed),
+            };
+            const client = new AgentApiClient();
+            const result = await client.post('/recommend-random', body);
+            output(result, opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── 辅助: optimal ────────────────────────────────────────
+    rec
+        .command('optimal')
+        .description('辅助: 理论最优 Tag 组合(perDim ω² 排序)')
+        .requiredOption('--channel <name>', '投放渠道')
+        .option('--metric <name>', '指标(ctr|cvr|cpi|ipm|cost|installs)', 'ctr')
+        .option('--top <n>', 'Top-K 数量', '5')
+        .option('--include-atoms', '为每条结果附带 atoms 配置')
+        .option('--pretty', '美化 JSON 输出')
+        .option('--output <file>', '写入文件而非 stdout')
+        .action(async (opts) => {
+        try {
+            const body = {
+                channel: opts.channel,
+                metric: opts.metric,
+                topK: parseIntOpt('--top', opts.top),
+                includeAtoms: !!opts.includeAtoms,
+            };
+            const client = new AgentApiClient();
+            const result = await client.post('/recommend-optimal', body);
+            output(result, opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── 辅助: tag-to-atom ────────────────────────────────────
+    rec
+        .command('tag-to-atom')
+        .description('辅助: Tag → Atom slot 映射')
+        .requiredOption('--tags <json>', 'Tag JSON,如 \'{"玩法类型":"三消复刻","背景场景":"公园"}\'')
+        .option('--pretty', '美化 JSON 输出')
+        .option('--output <file>', '写入文件而非 stdout')
+        .action(async (opts) => {
+        try {
+            const tags = parseTagsArg(opts.tags);
+            if (!tags)
+                throw new Error('--tags is required');
+            const body = { tags };
+            const client = new AgentApiClient();
+            const result = await client.post('/recommend-tag-to-atom', body);
+            output(result, opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}

package/dist/index.js

@@ -19,6 +19,7 @@ import { registerToolsCommands } from './commands/tools.js';
 import { registerImageCommands } from './commands/image.js';
 import { registerAudioCommands } from './commands/audio.js';
 import { registerPrefabCommands } from './commands/prefab.js';
+import { registerRecommendCommands } from './commands/recommend.js';
 import { CLI_ROOT_DESCRIPTION, getCliTopicsHelpText, registerRootProgramHelp, } from './cli-root-help.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -329,4 +330,6 @@ registerImageCommands(program);
 registerAudioCommands(program);
 // Remix prefab management (playcraft prefab <command>)
 registerPrefabCommands(program);
+// Tag → Atom recommend (playcraft recommend <command>)
+registerRecommendCommands(program);
 program.parse(process.argv);

package/dist/utils/agent-api-client.js

@@ -62,24 +62,12 @@ export class AgentApiClient {
         return res.json();
     }
     static loadConfig() {
-        // 兜底覆盖三类常见沙箱运行用户：
-        //  - AGS 镜像（ccr.ccs.tencentyun.com/ags-image/sandbox-code）默认运行用户为 `user`，HOME=/home/user
-        //  - 自建 docker/Dockerfile 沙箱 runtime stage 用户为 `opencode`，HOME=/home/opencode
-        //  - 以 root 启动 CLI 的旁路场景，HOME=/root
-        // 第一条 cwd 与第二条 /project 是与运行用户无关的硬编码命中点。
         const searchPaths = [
             join(process.cwd(), '.playcraft.json'),
             '/project/.playcraft.json',
-            '/home/user/.playcraft.json',
-            '/home/opencode/.playcraft.json',
-            '/root/.playcraft.json',
             join(homedir(), '.playcraft.json'),
         ];
-        const seen = new Set();
         for (const p of searchPaths) {
-            if (seen.has(p))
-                continue;
-            seen.add(p);
             if (existsSync(p)) {
                 try {
                     return JSON.parse(readFileSync(p, 'utf-8'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "private": false,
   "type": "module",
   "bin": {
@@ -23,8 +23,8 @@
     "release": "node scripts/release.js"
   },
   "dependencies": {
-    "@playcraft/build": "^0.0.32",
-    "@playcraft/common": "^0.0.20",
+    "@playcraft/build": "^0.0.34",
+    "@playcraft/common": "^0.0.22",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",