@playcraft/cli 0.0.31 → 0.0.32

package/dist/commands/prefab.js

@@ -2,7 +2,7 @@ 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, listScenesWithGameConfig, resolveGameConfigPath, validateThemeValue, validateConfigValue, describeJsonSchemaFields, describeConfigSchemaFields, getPrefabFieldDescriptors, getPrefabFieldDiffs, prefabHasSchemaDiff, } 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 {
@@ -266,99 +266,22 @@ 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');
-}
-/**
- * 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);
-        }
-        // Multiple scenes without isMain → cannot determine
-        return null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * 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)
- */
 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 (!variantId)
+        return DEFAULT_GAME_PATH;
+    if (!fileExists(projectDir, scenePath(variantId)))
+        return DEFAULT_GAME_PATH;
+    const sceneJson = JSON.parse(readLocalFile(projectDir, scenePath(variantId)));
     if (!fileExists(projectDir, ASSETS_JSON_PATH))
-        return null;
+        return DEFAULT_GAME_PATH;
     const assetsJson = JSON.parse(readLocalFile(projectDir, ASSETS_JSON_PATH));
-    return resolveGameConfigPath(sceneJson, assetsJson);
+    const resolved = resolveGameConfigPath(sceneJson, assetsJson);
+    return resolved ?? DEFAULT_GAME_PATH;
 }
 function listLocalScenes(projectDir) {
     if (!fileExists(projectDir, MANIFEST_PATH))
         return [];
     const manifestJson = JSON.parse(readLocalFile(projectDir, MANIFEST_PATH));
-    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);
 }
 function loadPrefabs(projectDir, systemType, opts) {
@@ -368,22 +291,11 @@ function loadPrefabs(projectDir, systemType, opts) {
         const data = loadThemeData(projectDir, themeId);
         return parseThemePrefabs(schema, data, themeId);
     }
-    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: {} }, '');
+    const gameConfigJson = loadGameConfig(projectDir, configPath);
+    const { extensions, config } = parseGameConfig(gameConfigJson);
+    const metaMap = scanExtensionMetaData(projectDir);
+    return buildExtensionPrefabs(metaMap, { extensions, config }, configPath);
 }
 // ─── dotpath helper ──────────────────────────────────────────────────────────
 function getByDotPath(obj, path) {
@@ -520,17 +432,8 @@ export function registerPrefabCommands(program) {
                     return;
                 }
                 for (const s of scenes) {
-                    const mark = s.isActive ? ' *' : '';
                     const gc = s.gameConfigPath ? `  [${s.gameConfigPath}]` : '';
-                    console.log(`  ${s.name}  (${s.id})${mark}${gc}`);
-                }
-                if (scenes.some((s) => s.isActive)) {
-                    console.log('');
-                    console.log('标 * 为 manifest 中的主场景（isMain）。其他场景请用 --variant <sceneId> 指定上下文。');
-                }
-                else {
-                    console.log('');
-                    console.log('（manifest 未标记主场景；操作其他场景请用 --variant <sceneId>）');
+                    console.log(`  ${s.name}  (${s.id})${gc}`);
                 }
             });
         }
@@ -915,12 +818,18 @@ 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);
@@ -931,22 +840,9 @@ export function registerPrefabCommands(program) {
                     process.exit(1);
                 }
             }
-            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 newValues = { ...currentValues, [field]: coerced };
+            const updated = updateGameConfigValue(gameConfigJson, configKey, newValues);
+            writeGameConfig(projectDir, configPath, updated);
             const payload = { success: true, key, field, value: coerced };
             outputResult(asJson, payload, () => {
                 console.log(`已更新 ${key}.${field} = ${formatHumanValue(coerced)}`);
@@ -1044,67 +940,38 @@ export function registerPrefabCommands(program) {
             }
             else {
                 const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+                let gameConfigJson = loadGameConfig(projectDir, configPath);
                 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);
+                for (const [extKey, fieldMap] of Object.entries(batch)) {
+                    if (!fieldMap || typeof fieldMap !== 'object' || Array.isArray(fieldMap)) {
+                        throw new Error(`extension "${extKey}" 的值必须是对象（字段 map）`);
                     }
-                    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('; ')}`);
-                                }
+                    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('; ')}`);
                             }
-                            coercedValues[field] = coerced;
                         }
-                        writeMetaDataDefaults(projectDir, extKey, coercedValues);
+                        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, () => {
@@ -1144,7 +1011,7 @@ export function registerPrefabCommands(program) {
             });
         }
         else {
-            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant) ?? DEFAULT_GAME_PATH;
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
             const gameConfigJson = loadGameConfig(projectDir, configPath);
             const { extensions } = parseGameConfig(gameConfigJson);
             if (extensions.includes(key)) {
@@ -1188,7 +1055,7 @@ export function registerPrefabCommands(program) {
             });
         }
         else {
-            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant) ?? DEFAULT_GAME_PATH;
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
             const gameConfigJson = loadGameConfig(projectDir, configPath);
             const { extensions } = parseGameConfig(gameConfigJson);
             const filtered = extensions.filter((n) => n !== key);

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.32",
   "private": false,
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
     "release": "node scripts/release.js"
   },
   "dependencies": {
-    "@playcraft/build": "^0.0.32",
+    "@playcraft/build": "^0.0.33",
     "@playcraft/common": "^0.0.20",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",