@playcraft/cli 0.0.40 → 0.0.41

package/dist/commands/tools-generation.js

@@ -0,0 +1,454 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname, parse, join } from 'path';
+import sharp from 'sharp';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, } from './tools-utils.js';
+function isMasterCompositeStripRequest(opts) {
+    if (opts.aspectRatio === '45:16')
+        return true;
+    if (opts.width && opts.height) {
+        const r = opts.width / opts.height;
+        return r >= 2.5 && r <= 3.2;
+    }
+    return false;
+}
+const STRIP_TARGET_BY_PRESET = {
+    '1K': { width: 2048, height: 728 },
+    '2K': { width: 3600, height: 1280 },
+    '4K': { width: 4096, height: 1455 },
+};
+function resolveStripTargetDimensions(opts) {
+    if (!isMasterCompositeStripRequest(opts))
+        return null;
+    if (opts.width && opts.height) {
+        return { width: opts.width, height: opts.height };
+    }
+    const preset = opts.imageSize ?? '2K';
+    return STRIP_TARGET_BY_PRESET[preset] ?? STRIP_TARGET_BY_PRESET['2K'];
+}
+/** 等比缩放 + 白底 letterbox，禁止非等比拉伸 */
+async function letterboxToTarget(imgBuf, targetW, targetH) {
+    return sharp(imgBuf)
+        .resize(targetW, targetH, {
+        fit: 'contain',
+        background: { r: 255, g: 255, b: 255, alpha: 1 },
+    })
+        .png()
+        .toBuffer();
+}
+/** Best-effort dimensions for sidecar; corrupt/truncated payloads must not fail save. */
+async function readImageDimensions(imgBuf) {
+    try {
+        const meta = await sharp(imgBuf).metadata();
+        return { width: meta.width ?? null, height: meta.height ?? null };
+    }
+    catch {
+        return { width: null, height: null };
+    }
+}
+/** 故事板横条：letterbox 后验收总比例 45:16 + 单格 9:16 */
+async function verifyMasterCompositeStripSize(imgBuf, target) {
+    const meta = await sharp(imgBuf).metadata();
+    const w = meta.width ?? 0;
+    const h = meta.height ?? 0;
+    const totalRatio = w / h;
+    const cellRatio = w / 5 / h;
+    const wantTotal = target.width / target.height;
+    const wantCell = 9 / 16;
+    const totalOk = Math.abs(totalRatio - wantTotal) / wantTotal <= 0.05;
+    const cellOk = Math.abs(cellRatio - wantCell) / wantCell <= 0.05;
+    if (!totalOk || !cellOk) {
+        console.warn(`\n⚠ Master Composite 尺寸仍偏离目标: ${w}×${h}`);
+        console.warn(`   总比例 ${totalRatio.toFixed(3)}（期望 ≈${wantTotal.toFixed(3)}），单格 ${cellRatio.toFixed(3)}（期望 ≈${wantCell.toFixed(3)}）`);
+    }
+    else {
+        console.log(`✓ 尺寸合格: ${w}×${h}（总比例 ${totalRatio.toFixed(2)}，单格 ${cellRatio.toFixed(3)} ≈ 9:16）`);
+    }
+    return { width: w, height: h };
+}
+export function registerGenerationCommands(tools) {
+    // ─── Image Models ────────────────────────────────────────────
+    tools.command('list-image-models')
+        .description('列出后端已配置的可用生图模型，按模型名分组展示所有 provider（多个 provider 时按优先级自动 fallback）')
+        .option('--json', '以 JSON 格式输出（默认为人类可读表格）')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const rawModels = await client.get('/image-models');
+            if (!rawModels.length) {
+                console.log('暂无已配置的生图模型。请前往 Admin > AI Settings 添加 modelKind=image 的配置。');
+                return;
+            }
+            // 按模型名分组（同一模型名下可能有多个 provider，裸模型名时按优先级 fallback）
+            const grouped = new Map();
+            for (const m of rawModels) {
+                const key = m.model;
+                if (!grouped.has(key))
+                    grouped.set(key, []);
+                grouped.get(key).push(m);
+            }
+            // 每组取第一个 provider 的 capability/alpha（同名模型各 provider 能力相同）
+            const models = Array.from(grouped.entries()).map(([modelName, entries]) => ({
+                model: modelName,
+                providers: entries.map((e) => e.provider),
+                capability: entries[0].capability,
+                alpha: entries[0].alpha ?? false,
+                isDefault: entries.some((e) => e.isDefault),
+            }));
+            if (opts.json) {
+                console.log(JSON.stringify(models, null, 2));
+                return;
+            }
+            const capLabel = (cap) => {
+                if (cap === 'text-only')
+                    return 'text→image';
+                if (cap === 'image-only')
+                    return 'image→image';
+                return 'text+image';
+            };
+            const alphaLabel = (alpha) => (alpha ? 'yes' : 'no');
+            const MODEL_COL = 'MODEL';
+            const CAP_COL = 'CAPABILITY';
+            const ALPHA_COL = 'ALPHA';
+            const PROVIDERS_COL = 'PROVIDERS';
+            const maxModelLen = Math.max(MODEL_COL.length, ...models.map((m) => m.model.length));
+            const capColWidth = Math.max(CAP_COL.length, ...models.map((m) => capLabel(m.capability).length));
+            console.log('');
+            console.log(`${MODEL_COL.padEnd(maxModelLen)}  ${CAP_COL.padEnd(capColWidth)}  ${ALPHA_COL.padEnd(5)}  ${PROVIDERS_COL}`);
+            console.log(`${'-'.repeat(maxModelLen)}  ${'-'.repeat(capColWidth)}  -----  --------------------------------`);
+            for (const m of models) {
+                const providerSummary = m.providers.length === 1
+                    ? m.providers[0]
+                    : `${m.providers.length} (${m.providers.join(', ')})`;
+                const defaultMark = m.isDefault ? ' *' : '';
+                console.log(`${m.model.padEnd(maxModelLen)}${defaultMark.padEnd(3 - defaultMark.length)}  ${capLabel(m.capability).padEnd(capColWidth)}  ${alphaLabel(m.alpha).padEnd(5)}  ${providerSummary}`);
+            }
+            console.log('');
+            console.log('提示：传入模型名（如 gpt-image-2），后端按优先级依次 fallback 各 provider（gpt-image-2：iegg-litellm → mulerouter → 302）。');
+            console.log('      也可传入 provider/model（如 mulerouter/gpt-image-2）直连指定 provider。');
+            console.log('');
+            console.log('CAPABILITY 说明:');
+            console.log('  text→image  仅支持文生图（不可传 --reference-image）');
+            console.log('  image→image 仅支持图生图（必须传 --reference-image）');
+            console.log('  text+image  两者均支持（有无 --reference-image 均可）');
+            console.log('');
+            console.log('ALPHA 说明:');
+            console.log('  yes   模型原生支持透明 PNG 输出（background: transparent）');
+            console.log('  no    输出 opaque PNG/JPEG；需透明素材时请使用绿幕策略');
+            console.log('        （prompt 加 "on solid bright green #00FF00 background" → remove-background）');
+            console.log('');
+            console.log(`使用方式：playcraft tools generate-image --prompt "..." --output out.png --image-model <MODEL>`);
+        }
+        catch (err) {
+            console.error('获取生图模型列表失败：', err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    // ─── Generation ─────────────────────────────────────────────
+    tools.command('generate-image')
+        .description('AI 生成图片（支持多张参考图图生图；gpt-image-2 支持 --count N 批量出图）')
+        .requiredOption('--prompt <text>', '图片描述')
+        .option('--aspect-ratio <ratio>', '宽高比 (1:1|45:16|16:9|9:16|3:4|4:3|2:3|3:2|21:9)', '1:1')
+        .requiredOption('--output <path>', '保存路径（--count>1 时自动追加 _1/_2 等后缀）')
+        .option('--image-size <size>', '图片尺寸 (1K|2K|4K)')
+        .option('--width <n>', '精确宽度（像素；MC 横排 5×9:16 推荐 3600 或 4096）', (v) => parseInt(v, 10))
+        .option('--height <n>', '精确高度（像素；MC 推荐 1280 或 1455）', (v) => parseInt(v, 10))
+        .option('--reference-image <path>', '参考图路径（可重复多次，最多 8 张），支持 PNG/JPG/WEBP', collectReferenceImagePaths, [])
+        .option('--image-model <model>', '模型名（如 gpt-image-2）或 provider/model（如 mulerouter/gpt-image-2）。传模型名时后端按优先级自动 fallback；传 provider/model 则直连指定 provider')
+        .option('--retry <n>', '全部 provider 都失败时的重试轮数（默认 1；超时不计为可重试错误）', (v) => parseInt(v, 10), 1)
+        .option('--timeout <seconds>', '请求超时秒数（默认 1800，即 30 分钟；异步生图模型耗时较长，仅在后端明确报错时提前终止）', (v) => parseInt(v, 10), 1800)
+        .option('--count <n>', '一次 API 调用生成多少张图片（默认 1，最多 10；仅 gpt-image-2 实际支持批量）', (v) => parseInt(v, 10), 1)
+        .action(async (opts) => {
+        const paths = opts.referenceImage ?? [];
+        if (paths.length > MAX_REFERENCE_IMAGES) {
+            console.error(`Error: Too many reference images: ${paths.length} paths given; maximum is ${MAX_REFERENCE_IMAGES}.`);
+            process.exit(1);
+            return;
+        }
+        const hasReferenceImages = paths.length > 0;
+        const attemptGenerate = async (modelRef, attempt) => {
+            const label = modelRef ? `[${modelRef}]` : '[default model]';
+            if (attempt > 0) {
+                console.log(`Retry ${attempt}/${opts.retry} ${label}...`);
+            }
+            else {
+                console.log(`Generating image ${label}...`);
+            }
+            const referenceImages = await collectReferenceImagePayloads(paths);
+            const client = new AgentApiClient();
+            const timeoutMs = opts.timeout * 1000;
+            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Request timed out after ${opts.timeout}s. The backend task may still be running — check admin panel before re-running.`)), timeoutMs));
+            const imageCount = Math.min(Math.max(1, opts.count ?? 1), 10);
+            const requestPromise = client.post('/generate-image', {
+                prompt: opts.prompt,
+                aspectRatio: opts.aspectRatio,
+                imageSize: opts.imageSize,
+                ...(opts.width && opts.height ? { width: opts.width, height: opts.height } : {}),
+                referenceImages,
+                ...(modelRef ? { imageModelRef: modelRef } : {}),
+                ...(imageCount > 1 ? { imageCount } : {}),
+            });
+            return Promise.race([requestPromise, timeoutPromise]);
+        };
+        const enrichError = (err, modelRef) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            const lines = [`Error: ${msg}`];
+            if (msg.includes('500') || msg.includes('Internal server error')) {
+                lines.push('');
+                lines.push('Hint: API 500 error — the model may be temporarily unavailable.');
+                lines.push('  → If using a bare model name (e.g. gpt-image-2), all providers failed — try a different model');
+                if (modelRef?.includes('/')) {
+                    lines.push('  → Or try without provider prefix to auto-fallback providers: --image-model gpt-image-2');
+                }
+            }
+            else if (msg.includes('timed out')) {
+                lines.push('');
+                lines.push('Hint: Request timed out. The backend task may still be running — retries were skipped to avoid creating duplicate tasks.');
+                lines.push('  → Check the backend/admin panel for task status before re-running');
+                lines.push('  → Try --image-size 1K to reduce generation time');
+                lines.push('  → Or increase timeout with --timeout <seconds> (current default: 1800s)');
+            }
+            else if (hasReferenceImages && (msg.includes('reference') || msg.includes('image input'))) {
+                lines.push('');
+                lines.push('Hint: Reference image error — the selected model may not support --reference-image.');
+                lines.push('  → Run: playcraft tools list-image-models');
+                lines.push('  → Models with CAPABILITY=text+image support --reference-image');
+            }
+            return lines.join('\n');
+        };
+        try {
+            let result = null;
+            let lastError = null;
+            // 重试逻辑：超时不重试（后端任务可能仍在运行，重试会导致重复提交）
+            const maxAttempts = 1 + (opts.retry ?? 1);
+            for (let attempt = 0; attempt < maxAttempts; attempt++) {
+                try {
+                    result = await attemptGenerate(opts.imageModel, attempt);
+                    break;
+                }
+                catch (e) {
+                    lastError = e;
+                    const msg = e instanceof Error ? e.message : String(e);
+                    const isTimeout = msg.includes('timed out');
+                    if (isTimeout) {
+                        console.error(`Attempt ${attempt + 1} timed out — not retrying (backend task may still be running).`);
+                        break;
+                    }
+                    if (attempt < maxAttempts - 1) {
+                        console.warn(`Attempt ${attempt + 1} failed: ${msg}`);
+                    }
+                }
+            }
+            if (!result) {
+                console.error(enrichError(lastError, opts.imageModel));
+                process.exit(1);
+                return;
+            }
+            const buf = Buffer.from(result.imageBase64, 'base64');
+            const sniffed = sniffImageExtension(buf);
+            const fromMime = extensionForImageMime(result.mimeType);
+            const wantExt = sniffed ?? fromMime;
+            if (!sniffed) {
+                console.warn('Could not detect image format from file signature; using Content-Type from API for extension.');
+            }
+            else if (sniffed !== fromMime) {
+                console.warn(`Image bytes look like ${sniffed.slice(1).toUpperCase()} but API reported ${result.mimeType}; extension follows file signature.`);
+            }
+            // 收集所有待保存图片（第 1 张 + 批量额外图）
+            const allImages = [
+                { imageBase64: result.imageBase64, mimeType: result.mimeType },
+                ...(result.additionalImages ?? []),
+            ];
+            const isBatch = allImages.length > 1;
+            const modelPart = opts.imageModel ? `model: ${opts.imageModel}` : '';
+            const providerPart = result.provider ? `provider: ${result.provider}` : '';
+            const labelParts = [modelPart, providerPart].filter(Boolean);
+            const modelLabel = labelParts.length > 0 ? ` (${labelParts.join(', ')})` : '';
+            const savedPaths = [];
+            const stripTarget = resolveStripTargetDimensions({
+                aspectRatio: opts.aspectRatio,
+                width: opts.width,
+                height: opts.height,
+                imageSize: opts.imageSize,
+            });
+            for (let i = 0; i < allImages.length; i++) {
+                const img = allImages[i];
+                let imgBuf = Buffer.from(img.imageBase64, 'base64');
+                let resolvedPath = resolveImageOutputPath(opts.output, wantExt);
+                let generatedWidth = null;
+                let generatedHeight = null;
+                // 批量模式：在扩展名前插入 _1, _2, ... 后缀
+                if (isBatch) {
+                    const { dir, name } = parse(resolvedPath);
+                    resolvedPath = join(dir, `${name}_${i + 1}${wantExt}`);
+                }
+                if (stripTarget && i === 0) {
+                    const metaBefore = await readImageDimensions(imgBuf);
+                    generatedWidth = metaBefore.width;
+                    generatedHeight = metaBefore.height;
+                    if (metaBefore.width != null &&
+                        metaBefore.height != null &&
+                        (metaBefore.width !== stripTarget.width ||
+                            metaBefore.height !== stripTarget.height)) {
+                        imgBuf = Buffer.from(await letterboxToTarget(imgBuf, stripTarget.width, stripTarget.height));
+                        console.log(`↑ Letterbox ${generatedWidth}×${generatedHeight} → ${stripTarget.width}×${stripTarget.height}（等比 + 白边，不拉伸）`);
+                    }
+                }
+                mkdirSync(dirname(resolvedPath), { recursive: true });
+                writeFileSync(resolvedPath, imgBuf);
+                let actualWidth = null;
+                let actualHeight = null;
+                if (stripTarget && i === 0) {
+                    const dims = await verifyMasterCompositeStripSize(imgBuf, stripTarget);
+                    actualWidth = dims.width;
+                    actualHeight = dims.height;
+                }
+                else {
+                    const meta = await readImageDimensions(imgBuf);
+                    actualWidth = meta.width;
+                    actualHeight = meta.height;
+                }
+                const sizeKB = Math.round(imgBuf.length / 1024);
+                console.log(`[${i + 1}/${allImages.length}] Image saved to ${resolvedPath} (${sizeKB}KB)${modelLabel}`);
+                savedPaths.push(resolvedPath);
+                const sidecar = {
+                    prompt: opts.prompt,
+                    model: opts.imageModel ?? 'default',
+                    provider: result.provider ?? null,
+                    aspectRatio: opts.aspectRatio,
+                    imageSize: opts.imageSize ?? null,
+                    requestedWidth: opts.width ?? stripTarget?.width ?? null,
+                    requestedHeight: opts.height ?? stripTarget?.height ?? null,
+                    generatedWidth: i === 0 ? generatedWidth : null,
+                    generatedHeight: i === 0 ? generatedHeight : null,
+                    actualWidth,
+                    actualHeight,
+                    referenceImages: paths.length > 0 ? paths : null,
+                    count: opts.count ?? 1,
+                    batchIndex: isBatch ? i + 1 : null,
+                    output: resolvedPath,
+                    referenceImageStatus: result.referenceImageStatus ?? null,
+                    generatedAt: new Date().toISOString(),
+                };
+                const sidecarPath = resolvedPath.replace(/\.[^.]+$/, '.json');
+                writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2));
+                console.log(`  └─ Generation metadata: ${sidecarPath}`);
+            }
+            if (!isBatch && opts.output !== savedPaths[0] && savedPaths[0]) {
+                // 单图但路径被调整时给出提示
+                console.log(`Output path adjusted to ${wantExt} payload: ${savedPaths[0]}`);
+            }
+            if (isBatch) {
+                console.log(`\nBatch complete: ${allImages.length} images saved.`);
+            }
+            if (result.referenceImageStatus === 'effective') {
+                console.log('Reference image: effective (image-to-image mode)');
+            }
+            else if (result.referenceImageStatus === 'ignored') {
+                console.warn('Warning: reference image was ignored by the provider (text-to-image mode used instead).');
+                console.warn('  → Check model CAPABILITY with: playcraft tools list-image-models');
+                console.warn('  → Use a model with CAPABILITY=text+image for reference image support');
+            }
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('generate-sfx')
+        .description('AI 生成音效（SFX），使用 ElevenLabs Sound Effects')
+        .requiredOption('--prompt <text>', '音效描述，仅英文，如 "crisp UI click, short tail, no voice"')
+        .option('--duration <seconds>', '时长（秒，0.5-30）', parseFloat)
+        .option('--loop', '生成可循环的音效', false)
+        .requiredOption('--output <path>', '保存路径，如 ./assets/audio/click.mp3')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/generate-sfx', {
+                prompt: opts.prompt,
+                duration: opts.duration,
+                loop: opts.loop,
+            });
+            mkdirSync(dirname(opts.output), { recursive: true });
+            const buf = Buffer.from(result.audioBase64, 'base64');
+            writeFileSync(opts.output, buf);
+            const sizeKB = Math.round(buf.length / 1024);
+            console.log(`SFX saved to ${opts.output} (${sizeKB}KB, ${result.duration.toFixed(2)}s, provider=${result.provider})`);
+            const sfxSidecar = {
+                type: 'sfx', prompt: opts.prompt, duration: opts.duration ?? null,
+                loop: opts.loop ?? false, provider: result.provider, actualDuration: result.duration,
+                output: opts.output, generatedAt: new Date().toISOString(),
+            };
+            writeFileSync(opts.output.replace(/\.[^.]+$/, '.json'), JSON.stringify(sfxSidecar, null, 2));
+            console.log(`  └─ Generation metadata: ${opts.output.replace(/\.[^.]+$/, '.json')}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('generate-bgm')
+        .description('AI 生成 BGM（30s 循环），使用 Google Lyria 3')
+        .requiredOption('--prompt <text>', 'BGM 描述，如 "轻快休闲游戏配乐"')
+        .option('--style <style>', '音乐风格，如 casual / epic / sci-fi / retro')
+        .option('--bpm <bpm>', '目标 BPM', parseInt)
+        .requiredOption('--output <path>', '保存路径，如 ./assets/audio/bgm.mp3')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/generate-bgm', {
+                prompt: opts.prompt,
+                style: opts.style,
+                bpm: opts.bpm,
+            });
+            mkdirSync(dirname(opts.output), { recursive: true });
+            const buf = Buffer.from(result.audioBase64, 'base64');
+            writeFileSync(opts.output, buf);
+            const sizeKB = Math.round(buf.length / 1024);
+            console.log(`BGM saved to ${opts.output} (${sizeKB}KB, ${result.duration.toFixed(2)}s, provider=${result.provider})`);
+            const bgmSidecar = {
+                type: 'bgm', prompt: opts.prompt, style: opts.style ?? null,
+                bpm: opts.bpm ?? null, provider: result.provider, actualDuration: result.duration,
+                output: opts.output, generatedAt: new Date().toISOString(),
+            };
+            writeFileSync(opts.output.replace(/\.[^.]+$/, '.json'), JSON.stringify(bgmSidecar, null, 2));
+            console.log(`  └─ Generation metadata: ${opts.output.replace(/\.[^.]+$/, '.json')}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── Search Image ──────────────────────────────────────────
+    tools.command('search-image')
+        .description('搜索参考图片（Unsplash / Pexels），结果 URL 可直接用于 --reference-image')
+        .requiredOption('--query <query>', '搜索关键词（建议英文）')
+        .option('--source <source>', '图源：unsplash | pexels | auto（默认 auto）', 'auto')
+        .option('--count <count>', '返回数量（默认 6，最多 30）', '6')
+        .option('--orientation <orientation>', '方向：landscape | portrait | square')
+        .option('--json', '输出 JSON 格式（供 Agent 消费）')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/search-image', {
+                query: opts.query,
+                source: opts.source,
+                count: parseInt(opts.count, 10),
+                orientation: opts.orientation,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.log(`\nFound ${result.total} images from ${result.source} (showing ${result.results.length})\n`);
+                result.results.forEach((img, i) => {
+                    console.log(`[${i + 1}] ${img.description.slice(0, 60)}`);
+                    console.log(`    Size: ${img.width}x${img.height}`);
+                    console.log(`    URL: ${img.downloadUrl}`);
+                    console.log(`    ${img.attribution}`);
+                    console.log();
+                });
+            }
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}