@playcraft/cli 0.1.49-beta → 0.1.51

package/dist/commands/login.js

@@ -1,8 +1,7 @@
 import http from 'http';
-import { execFile } from 'child_process';
+import { exec } from 'child_process';
 import crypto from 'crypto';
-import { loadGlobalConfig, normalizeEnvironmentBaseUrl, readEnvironmentProfile, saveEnvironmentProfile } from '../config.js';
-import { activateAccount } from '../auth/account-activation.js';
+import { saveGlobalConfig, loadGlobalConfig } from '../config.js';
 /** 默认云端 Portal（Next.js `/cli-auth` 与 API 同源时的基址；可通过 --url 或 PLAYCRAFT_URL 覆盖） */
 export const DEFAULT_PLAYCRAFT_CLOUD_BASE = 'https://playcraft.aix.intlgame.com';
 const CALLBACK_PORT = 3456;
@@ -19,11 +18,10 @@ function openBrowser(url) {
     const cmd = process.platform === 'darwin'
         ? 'open'
         : process.platform === 'win32'
-            ? 'rundll32'
+            ? 'start'
             : 'xdg-open';
     try {
-        const arguments_ = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
-        execFile(cmd, arguments_, (err, _stdout, stderr) => {
+        exec(`${cmd} "${url}"`, (err, _stdout, stderr) => {
             if (err) {
                 console.error('Failed to open browser automatically:', err.message);
                 if (stderr?.trim()) {
@@ -46,18 +44,21 @@ function resolveLoginBaseUrl(options) {
         globalConfig.url ||
         globalConfig.backendUrl ||
         DEFAULT_PLAYCRAFT_CLOUD_BASE;
-    const base = normalizeEnvironmentBaseUrl(raw);
-    if (!base)
-        throw new Error('Invalid environment address');
-    return base;
+    return raw.replace(/\/+$/, '');
 }
 function normalizeLoginEnvironmentUrl(raw) {
-    return normalizeEnvironmentBaseUrl(raw);
+    try {
+        const url = new URL(raw);
+        url.hash = '';
+        url.search = '';
+        url.pathname = url.pathname.replace(/\/+$/, '');
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        return undefined;
+    }
 }
 export function resolveExistingTokenForLoginTarget(globalConfig, backendUrl) {
-    const profile = readEnvironmentProfile(globalConfig, backendUrl);
-    if (profile)
-        return profile.token;
     const token = typeof globalConfig.token === 'string' ? globalConfig.token : undefined;
     const storedBackendUrl = typeof globalConfig.backendUrl === 'string'
         ? globalConfig.backendUrl
@@ -73,17 +74,9 @@ export function resolveExistingTokenForLoginTarget(globalConfig, backendUrl) {
         : undefined;
 }
 export function buildCliAuthUrl(options) {
-    const base = normalizeEnvironmentBaseUrl(options.backendUrl);
-    if (!base)
-        throw new Error('Invalid environment address');
-    const url = new URL(`${base}/cli-auth`);
-    url.searchParams.set('callbackUrl', options.callbackUrl);
+    const url = new URL('/cli-auth', options.backendUrl);
     url.searchParams.set('callback', options.callbackUrl);
     url.searchParams.set('state', options.state);
-    if (options.codeChallenge) {
-        url.searchParams.set('codeChallenge', options.codeChallenge);
-        url.searchParams.set('codeChallengeMethod', 'S256');
-    }
     return url.toString();
 }
 export async function renewExistingToken(options) {
@@ -94,20 +87,12 @@ export async function renewExistingToken(options) {
     try {
         const res = await fetchFn(`${options.backendUrl}/api/settings/personal-access-tokens/current/renew`, {
             method: 'PATCH',
-            redirect: 'error',
-            signal: AbortSignal.timeout(10_000),
             headers: {
                 Authorization: `Bearer ${options.token}`,
                 'Content-Type': 'application/json',
             },
             body: JSON.stringify({ expiresIn: '365d' }),
         });
-        if (res.ok && res.json && options.onRenewed) {
-            const result = await res.json();
-            if (typeof result.expiresAt === 'string' && Date.parse(result.expiresAt) > Date.now()) {
-                options.onRenewed(result.expiresAt);
-            }
-        }
         return res.ok;
     }
     catch {
@@ -115,43 +100,29 @@ export async function renewExistingToken(options) {
     }
 }
 export async function loginCommand(options) {
-    if (options.activate) {
-        await activateAccount(options, DEFAULT_PLAYCRAFT_CLOUD_BASE);
-        return;
-    }
     const backendUrl = resolveLoginBaseUrl(options);
     const callbackPort = options.callbackPort ?? CALLBACK_PORT;
     const globalConfig = loadGlobalConfig();
     const existingToken = resolveExistingTokenForLoginTarget(globalConfig, backendUrl);
     if (existingToken) {
-        let expiresAt;
-        const renewed = await renewExistingToken({ backendUrl, token: existingToken,
-            onRenewed: (value) => { expiresAt = value; } });
+        const renewed = await renewExistingToken({ backendUrl, token: existingToken });
         if (renewed) {
-            const previous = readEnvironmentProfile(globalConfig, backendUrl);
-            saveEnvironmentProfile(backendUrl, { token: existingToken,
-                ...(previous?.identity ? { identity: previous.identity } : {}),
-                ...(expiresAt ? { expiresAt } : {}) });
+            saveGlobalConfig({
+                token: existingToken,
+                url: backendUrl,
+                backendUrl,
+            });
             console.log('Existing CLI token renewed. Token saved to ~/.playcraft/config.json');
             return;
         }
     }
     const state = crypto.randomBytes(16).toString('hex');
-    const codeVerifier = crypto.randomBytes(32).toString('base64url');
-    const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
-    let callbackUrl = '';
-    let exchanging = false;
     return new Promise((resolve, reject) => {
         let timeout;
         const server = http.createServer((req, res) => {
-            res.setHeader('Access-Control-Allow-Origin', new URL(backendUrl).origin);
+            res.setHeader('Access-Control-Allow-Origin', '*');
             res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
             res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
-            if (req.headers.origin && req.headers.origin !== new URL(backendUrl).origin) {
-                res.writeHead(403);
-                res.end();
-                return;
-            }
             if (req.method === 'OPTIONS') {
                 res.writeHead(204);
                 res.end();
@@ -159,9 +130,8 @@ export async function loginCommand(options) {
             }
             if (req.url === '/callback' && req.method === 'POST') {
                 let body = '';
-                req.on('data', (chunk) => { body += chunk; if (body.length > 16_384)
-                    req.destroy(); });
-                req.on('end', async () => {
+                req.on('data', (chunk) => (body += chunk));
+                req.on('end', () => {
                     try {
                         const data = JSON.parse(body);
                         if (data.state !== state) {
@@ -169,36 +139,22 @@ export async function loginCommand(options) {
                                 'Content-Type': 'text/html',
                                 Connection: 'close',
                             });
-                            res.end('<html><body><h1>Invalid state</h1></body></html>');
-                            return;
-                        }
-                        if (exchanging) {
-                            res.writeHead(409);
-                            res.end();
+                            res.end('<html><body><h1>Invalid state</h1></body></html>', () => {
+                                closeServer(() => {
+                                    reject(new Error('State mismatch - possible CSRF attack'));
+                                });
+                            });
                             return;
                         }
-                        if (typeof data.code !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(data.code)) {
-                            throw new Error('Login callback did not include an authorization code');
+                        const callbackToken = typeof data.token === 'string' ? data.token : undefined;
+                        if (!callbackToken) {
+                            throw new Error('Login callback did not include a token');
                         }
-                        exchanging = true;
-                        const base = normalizeEnvironmentBaseUrl(backendUrl);
-                        if (!base)
-                            throw new Error('Invalid environment address');
-                        const exchange = await fetch(`${base}/api/cloud-environments/exchange`, {
-                            method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10_000),
-                            headers: { 'Content-Type': 'application/json' },
-                            body: JSON.stringify({ code: data.code, state, callbackUrl, codeVerifier }),
+                        saveGlobalConfig({
+                            token: callbackToken,
+                            url: backendUrl,
+                            backendUrl,
                         });
-                        if (!exchange.ok)
-                            throw new Error('Authorization code exchange failed');
-                        const credential = await exchange.json();
-                        if (!credential.token || !/^playcraft_pat_[A-Za-z0-9_-]{32}$/.test(credential.token)
-                            || !credential.identity?.userId || !Array.isArray(credential.identity.identities)
-                            || !credential.expiresAt || Date.parse(credential.expiresAt) <= Date.now()) {
-                            throw new Error('Invalid environment credential response');
-                        }
-                        saveEnvironmentProfile(base, { token: credential.token,
-                            identity: credential.identity, expiresAt: credential.expiresAt });
                         res.writeHead(200, {
                             'Content-Type': 'text/html',
                             Connection: 'close',
@@ -218,6 +174,9 @@ export async function loginCommand(options) {
                     catch (err) {
                         const cause = err instanceof Error ? err : new Error(String(err));
                         console.error('[playcraft login] Callback handling failed:', cause.message);
+                        if (cause.stack) {
+                            console.error(cause.stack);
+                        }
                         const userFacing = cause instanceof SyntaxError
                             ? 'Invalid JSON in login callback.'
                             : `Login callback failed: ${cause.message}`;
@@ -262,15 +221,14 @@ export async function loginCommand(options) {
             });
         });
         try {
-            server.listen(callbackPort, '127.0.0.1', () => {
+            server.listen(callbackPort, () => {
                 const address = server.address();
                 const listeningPort = typeof address === 'object' && address ? address.port : callbackPort;
-                callbackUrl = `http://127.0.0.1:${listeningPort}/callback`;
+                const callbackUrl = `http://localhost:${listeningPort}/callback`;
                 const authUrl = buildCliAuthUrl({
                     backendUrl,
                     callbackUrl,
                     state,
-                    codeChallenge,
                 });
                 console.log('Opening browser for login...');
                 console.log(`If the browser does not open, visit this URL manually:\n  ${authUrl}\n`);

package/dist/commands/skills.js

@@ -18,8 +18,6 @@
  *   3. <cwd>/node_modules/@playcraft/skills/playcraft-skills（兼容旧路径 skills）
  *   4. <CLI 自身>/../../skills/playcraft-skills（monorepo 开发时，兼容旧路径 skills）
  */
-import { registerProjectSkillsCommands } from '../project-skills/commands.js';
-import { registerRegistryCommands } from '../skill-registry/commands.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getFusionHintsForGameplayAtoms, } from '../atom-tree/fusion-hints.js';
@@ -1432,8 +1430,6 @@ export function registerSkillsCommands(program) {
     const skills = program
         .command('skills')
         .description('开发时 Skill 发现与脚手架工具（按 engine/intent 推荐 skill 集合，或将 ref 文件复制到项目）');
-    registerProjectSkillsCommands(skills);
-    registerRegistryCommands(skills);
     // 公共选项：skills 目录
     const addSkillsDirOption = (cmd) => cmd.option('--skills-dir <path>', '指定 skills 目录路径（默认自动发现）');
     // ── list ──────────────────────────────────────────────────────────────────

package/dist/commands/tools-3d.js

@@ -2,7 +2,6 @@ import { writeFileSync, mkdirSync, readFileSync } from 'fs';
 import { dirname } from 'path';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 import { mimeTypeForImagePath, handleError } from './tools-utils.js';
-import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
 const AVATAR_TEMPLATES = [
     'basketball', 'badminton', 'pingpong', 'gymnastics', 'pilidance',
     'tennis', 'athletics', 'footballboykicking1', 'footballboykicking2',
@@ -149,9 +148,6 @@ export function register3DCommands(tools) {
                 writeFileSync(opts.savePreview, previewBuf);
                 console.log(`  Preview saved: ${opts.savePreview}`);
             }
-            await captureGeneratedArtifact(opts.output, 'generate-3d', {
-                ...(opts.savePreview && result.previewImageBase64 ? { thumbnailPath: opts.savePreview } : {}),
-            });
             console.log(`\nNext steps:`);
             console.log(`  Inspect:        playcraft 3d info ${opts.output}`);
             console.log(`  Apply texture:  playcraft tools generate-texture --model-url <url> --reference-image <img> --output out.glb`);
@@ -213,7 +209,6 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
-            await captureGeneratedArtifact(opts.output, 'generate-texture');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\nTextured model saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
             if (result.resultUrl)
@@ -258,7 +253,6 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
-            await captureGeneratedArtifact(opts.output, 'retopology');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\nRetopologized model saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
         }
@@ -295,7 +289,6 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
-            await captureGeneratedArtifact(opts.output, 'uv-unwrap');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\nUV-unwrapped model saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
         }
@@ -331,7 +324,6 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
-            await captureGeneratedArtifact(opts.output, 'convert-3d');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\nConverted model saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
             console.log(`  Format: ${result.format.toUpperCase()}`);
@@ -367,7 +359,6 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
-            await captureGeneratedArtifact(opts.output, 'generate-3d-parts');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\n3D parts model saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
         }
@@ -411,7 +402,6 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
-            await captureGeneratedArtifact(opts.output, 'generate-motion');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\nMotion FBX saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
         }
@@ -473,7 +463,6 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
-            await captureGeneratedArtifact(opts.output, 'generate-avatar');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\n3D avatar saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
         }

package/dist/commands/tools-generation.js

@@ -1,9 +1,11 @@
+import { Option } from 'commander';
 import { writeFileSync, mkdirSync } from 'fs';
 import { dirname, parse, join } from 'path';
 import sharp from 'sharp';
-import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
+import { resolveImageBackgroundRequirement, validateImageDeliveryOptions } from '@playcraft/common/prefab';
+import { assertImageAssetOutputPaths, readImageAssetContext } from '../utils/image-asset-context.js';
 import { AgentApiClient } from '../utils/agent-api-client.js';
-import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
+import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, parseImageTargetFieldPath, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
 function isMasterCompositeStripRequest(opts) {
     if (opts.aspectRatio === '45:16')
         return true;
@@ -151,86 +153,140 @@ export function registerGenerationCommands(tools) {
         .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('--target-asset <path>', 'Existing asset to replace; read its schema references and delivery constraints')
+        .option('--target-field-path <path>', 'Target image field as an array of keys, e.g. ["endUI","playButton"]', parseImageTargetFieldPath)
+        .option('--no-target-reference', 'Generate without the existing asset reference only when explicitly requested')
+        .option('--output-format <format>', 'Final format: png, webp or jpeg')
+        .option('--fit-mode <mode>', 'Canvas fitting: contain, cover or fill')
+        .option('--padding-color <color>', 'Canvas padding color (transparent by default)')
+        .addOption(new Option('--background <mode>', 'Agent background decision from conversation context').choices(['transparent', 'opaque']))
+        .option('--remove-background', 'Require a verified transparent image')
+        .option('--no-remove-background', 'Keep the generated background')
         .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('--retry <n>', '额外重试轮数（默认 0；后端统一限制尝试，透明验证失败和超时不重试）', (v) => parseInt(v, 10), 0)
         .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 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 raceWithTimeout(requestPromise, opts.timeout * 1000, `Request timed out after ${opts.timeout}s. The backend task may still be running — check admin panel before re-running.`);
-        };
-        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');
-                }
+        try {
+            const explicitBackground = opts.background === undefined ? opts.removeBackground : opts.background === 'transparent';
+            if (opts.background !== undefined && opts.removeBackground !== undefined && opts.removeBackground !== explicitBackground) {
+                throw new Error('Conflicting background options. Use --background transparent or --background opaque; no image request was sent.');
             }
-            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)');
+            opts = { ...opts, removeBackground: explicitBackground };
+            if (opts.targetFieldPath && !opts.targetAsset) {
+                throw new Error('--target-field-path requires --target-asset; no image request was sent.');
             }
-            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');
+            const explicitOutputFormat = opts.outputFormat;
+            const { dir: outputDir, name: outputName, ext: outputExt } = parse(opts.output);
+            const outputCandidates = [opts.output, ...Array.from({ length: opts.count > 1 ? Math.min(opts.count, 10) : 0 }, (_, i) => join(outputDir, `${outputName}_${i + 1}${outputExt}`))];
+            const assetContext = opts.targetAsset ? await readImageAssetContext(opts.targetAsset, process.cwd(), {
+                referenceImagePaths: opts.referenceImage, useTargetReference: opts.targetReference,
+                ...(opts.targetFieldPath ? { targetFieldPath: opts.targetFieldPath } : {}),
+                outputPaths: outputCandidates,
+                prompt: opts.prompt, removeBackground: opts.removeBackground,
+            }) : undefined;
+            opts = { ...opts,
+                aspectRatio: assetContext?.aspectRatio ?? opts.aspectRatio,
+                width: assetContext?.width ?? opts.width, height: assetContext?.height ?? opts.height,
+                outputFormat: assetContext?.outputFormatFromSchema ? assetContext.outputFormat : opts.outputFormat ?? assetContext?.outputFormat,
+                fitMode: assetContext?.fitMode ?? opts.fitMode,
+                removeBackground: resolveImageBackgroundRequirement({ prompt: opts.prompt,
+                    schemaRemoveBackground: assetContext?.removeBackgroundFromSchema ? assetContext.removeBackground : undefined,
+                    removeBackground: opts.removeBackground, fallbackRemoveBackground: assetContext?.removeBackground }),
+                paddingColor: assetContext?.paddingColor ?? opts.paddingColor,
+                imageModel: opts.imageModel || assetContext?.imageModelRef,
+            };
+            const invalidDelivery = validateImageDeliveryOptions(opts);
+            if (invalidDelivery)
+                throw new Error(invalidDelivery);
+            const paths = opts.referenceImage?.length ? opts.referenceImage : assetContext?.referenceImagePaths ?? [];
+            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;
             }
-            return lines.join('\n');
-        };
-        try {
+            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 imageCount = Math.min(Math.max(1, opts.count ?? 1), 10);
+                const requestPromise = client.post('/generate-image', {
+                    prompt: opts.prompt,
+                    aspectRatio: assetContext?.aspectRatio ?? opts.aspectRatio,
+                    imageSize: opts.imageSize,
+                    width: assetContext?.width ?? opts.width,
+                    height: assetContext?.height ?? opts.height,
+                    outputFormat: opts.outputFormat,
+                    outputFormatSource: assetContext?.outputFormatFromSchema ? 'schema'
+                        : explicitOutputFormat ? 'explicit' : assetContext ? 'inferred' : undefined,
+                    fitMode: assetContext?.fitMode ?? opts.fitMode,
+                    paddingColor: assetContext?.paddingColor ?? opts.paddingColor,
+                    background: opts.background === undefined ? undefined : opts.removeBackground ? 'transparent' : 'opaque',
+                    removeBackground: opts.removeBackground,
+                    backgroundRequirementSource: assetContext?.removeBackgroundFromSchema ? 'schema'
+                        : explicitBackground !== undefined ? 'explicit' : 'inferred',
+                    referenceImages,
+                    ...(modelRef ? { imageModelRef: modelRef } : {}),
+                    ...(imageCount > 1 ? { imageCount } : {}),
+                });
+                return raceWithTimeout(requestPromise, opts.timeout * 1000, `Request timed out after ${opts.timeout}s. The backend task may still be running — check admin panel before re-running.`);
+            };
+            const enrichError = (err, modelRef) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                const lines = [`Error: ${msg}`];
+                if (/source_transparency_invalid|output_transparency_invalid|transparency_unsupported/.test(msg)) {
+                    lines.push('Hint: Transparent output was not delivered. Preserve the requested transparency, references and model; use the request id and stage to investigate.');
+                }
+                else if (/API 500\b|Internal server error/.test(msg)) {
+                    lines.push('');
+                    lines.push('Hint: API 500 error — the model may be temporarily unavailable.');
+                    lines.push('  → Inspect the request id and backend diagnostics before another generation attempt.');
+                    if (modelRef?.includes('/') && opts.removeBackground !== true) {
+                        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');
+            };
             let result = null;
             let lastError = null;
             // 重试逻辑：超时不重试（后端任务可能仍在运行，重试会导致重复提交）
-            const maxAttempts = 1 + (opts.retry ?? 1);
+            const maxAttempts = 1 + (opts.retry ?? 0);
             for (let attempt = 0; attempt < maxAttempts; attempt++) {
                 try {
-                    result = await attemptGenerate(opts.imageModel, attempt);
+                    result = await attemptGenerate(opts.imageModel || assetContext?.imageModelRef, 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).`);
+                    const cannotRetry = /source_transparency_invalid|output_transparency_invalid|transparency_unsupported|"retryable"\s*:\s*false/.test(msg);
+                    if (isTimeout || cannotRetry) {
+                        console.error(`Attempt ${attempt + 1} stopped: ${msg}`);
                         break;
                     }
                     if (attempt < maxAttempts - 1) {
@@ -255,16 +311,18 @@ export function registerGenerationCommands(tools) {
             }
             // 收集所有待保存图片（第 1 张 + 批量额外图）
             const allImages = [
-                { imageBase64: result.imageBase64, mimeType: result.mimeType },
+                { imageBase64: result.imageBase64, mimeType: result.mimeType, previewUrl: result.previewUrl },
                 ...(result.additionalImages ?? []),
             ];
             const isBatch = allImages.length > 1;
-            const modelPart = opts.imageModel ? `model: ${opts.imageModel}` : '';
+            const modelPart = result.model ? `model: ${result.model}` : '';
             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({
+            if (result.transparencySource)
+                console.log(`Transparency source: ${result.transparencySource}`);
+            const stripTarget = opts.targetAsset || result.transparentBackground ? null : resolveStripTargetDimensions({
                 aspectRatio: opts.aspectRatio,
                 width: opts.width,
                 height: opts.height,
@@ -293,6 +351,8 @@ export function registerGenerationCommands(tools) {
                         console.log(`↑ Letterbox ${generatedWidth}×${generatedHeight} → ${stripTarget.width}×${stripTarget.height}（等比 + 白边，不拉伸）`);
                     }
                 }
+                if (assetContext)
+                    assertImageAssetOutputPaths(assetContext, [resolvedPath]);
                 mkdirSync(dirname(resolvedPath), { recursive: true });
                 writeFileSync(resolvedPath, imgBuf);
                 let actualWidth = null;
@@ -309,11 +369,23 @@ export function registerGenerationCommands(tools) {
                 }
                 const sizeKB = Math.round(imgBuf.length / 1024);
                 console.log(`[${i + 1}/${allImages.length}] Image saved to ${resolvedPath} (${sizeKB}KB)${modelLabel}`);
+                if (img.previewUrl)
+                    console.log(`Image preview: ${img.previewUrl}`);
                 savedPaths.push(resolvedPath);
                 const sidecar = {
                     prompt: opts.prompt,
-                    model: opts.imageModel ?? 'default',
+                    model: result.model ?? null,
+                    requestedModel: opts.imageModel ?? null,
                     provider: result.provider ?? null,
+                    transparentBackground: result.transparentBackground ?? null,
+                    requestedBackground: opts.background ?? null,
+                    transparencySource: result.transparencySource ?? null,
+                    requestId: result.requestId ?? null,
+                    attempts: result.attempts ?? null,
+                    targetAssetPath: assetContext?.targetAssetPath ?? null,
+                    outputFormat: opts.outputFormat ?? null,
+                    fitMode: opts.fitMode ?? null,
+                    paddingColor: opts.paddingColor ?? null,
                     aspectRatio: opts.aspectRatio,
                     imageSize: opts.imageSize ?? null,
                     requestedWidth: opts.width ?? stripTarget?.width ?? null,
@@ -326,14 +398,12 @@ export function registerGenerationCommands(tools) {
                     count: opts.count ?? 1,
                     batchIndex: isBatch ? i + 1 : null,
                     output: resolvedPath,
+                    previewUrl: img.previewUrl ?? null,
                     referenceImageStatus: result.referenceImageStatus ?? null,
                     generatedAt: new Date().toISOString(),
                 };
                 const sidecarPath = resolvedPath.replace(/\.[^.]+$/, '.json');
                 writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2));
-                await captureGeneratedArtifact(resolvedPath, 'generate-image', {
-                    ...(actualWidth ? { width: actualWidth } : {}), ...(actualHeight ? { height: actualHeight } : {}),
-                });
                 console.log(`  └─ Generation metadata: ${sidecarPath}`);
             }
             if (!isBatch && opts.output !== savedPaths[0] && savedPaths[0]) {
@@ -381,7 +451,6 @@ export function registerGenerationCommands(tools) {
                 output: opts.output, generatedAt: new Date().toISOString(),
             };
             writeFileSync(opts.output.replace(/\.[^.]+$/, '.json'), JSON.stringify(sfxSidecar, null, 2));
-            await captureGeneratedArtifact(opts.output, 'generate-sfx', { duration: result.duration });
             console.log(`  └─ Generation metadata: ${opts.output.replace(/\.[^.]+$/, '.json')}`);
         }
         catch (e) {
@@ -414,7 +483,6 @@ export function registerGenerationCommands(tools) {
                 output: opts.output, generatedAt: new Date().toISOString(),
             };
             writeFileSync(opts.output.replace(/\.[^.]+$/, '.json'), JSON.stringify(bgmSidecar, null, 2));
-            await captureGeneratedArtifact(opts.output, 'generate-bgm', { duration: result.duration });
             console.log(`  └─ Generation metadata: ${opts.output.replace(/\.[^.]+$/, '.json')}`);
         }
         catch (e) {