@playcraft/cli 0.0.40 → 0.0.42

package/dist/commands/image.js

@@ -1,6 +1,8 @@
-import { mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
-import { basename, dirname, join } from 'path';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
+import { basename, dirname, extname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import sharp from 'sharp';
+import yaml from 'js-yaml';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 /** 单文件输入上限（字节），防止误处理巨型文件导致 OOM */
 const DEFAULT_MAX_INPUT_BYTES = 512 * 1024 * 1024;
@@ -48,6 +50,84 @@ function handleError(err) {
     console.error(`Error: ${msg}`);
     process.exit(1);
 }
+/**
+ * sharp 不允许 input 与 output 是同一文件（toFile 会报错）。
+ * safeToFile 自动检测同路径场景：先写临时文件，成功后原子 rename 覆盖。
+ */
+async function safeToFile(pipeline, outputPath, inputPath) {
+    ensureDir(outputPath);
+    if (inputPath && resolve(inputPath) === resolve(outputPath)) {
+        const tmpPath = outputPath + '.__tmp__';
+        try {
+            await pipeline.toFile(tmpPath);
+            renameSync(tmpPath, outputPath);
+        }
+        catch (e) {
+            try {
+                if (existsSync(tmpPath)) {
+                    const { unlinkSync } = await import('fs');
+                    unlinkSync(tmpPath);
+                }
+            }
+            catch { /* ignore */ }
+            throw e;
+        }
+    }
+    else {
+        await pipeline.toFile(outputPath);
+    }
+}
+/**
+ * 简易 glob 匹配：将 *.ext 转为正则，仅匹配文件名（不含路径分隔符）。
+ * 支持 * 和 ? 通配符，不支持深层路径通配。
+ */
+function globPattern(pattern) {
+    const ext = extname(pattern);
+    const base = basename(pattern, ext);
+    const esc = (s) => s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    const toRegex = (part) => esc(part).replace(/\\\*/g, '.*').replace(/\\\?/g, '.');
+    const nameReg = toRegex(base) + (ext ? esc(ext) : '');
+    return new RegExp(`^${nameReg}$`, 'i');
+}
+/**
+ * 从目录中按 glob 模式收集文件，按文件名自然排序。
+ * pattern 只做文件名匹配（如 "*.png"，不支持子目录 **）。
+ */
+function collectFromDir(dir, pattern = '*.png', sort = 'name') {
+    if (!existsSync(dir))
+        return [];
+    const reg = globPattern(pattern);
+    const files = readdirSync(dir)
+        .filter((f) => reg.test(f) && statSync(join(dir, f)).isFile())
+        .map((f) => join(dir, f));
+    if (sort === 'name') {
+        files.sort((a, b) => basename(a).localeCompare(basename(b), undefined, { numeric: true, sensitivity: 'base' }));
+    }
+    else if (sort === 'modified') {
+        files.sort((a, b) => statSync(a).mtimeMs - statSync(b).mtimeMs);
+    }
+    return files;
+}
+/**
+ * 展开逗号分隔的输入列表，支持简单 glob 模式（含 * 或 ?）。
+ * glob 只匹配当前目录文件（不支持子目录通配）。
+ */
+function expandInputPaths(raw) {
+    const parts = raw.split(',').map((p) => p.trim()).filter(Boolean);
+    const result = [];
+    for (const part of parts) {
+        if (part.includes('*') || part.includes('?')) {
+            const dir = dirname(part);
+            const pat = basename(part);
+            const matched = collectFromDir(dir === '.' ? process.cwd() : dir, pat, 'name');
+            result.push(...matched);
+        }
+        else {
+            result.push(part);
+        }
+    }
+    return result;
+}
 /** 多圈边缘羽化默认 alpha；若 edgeLayers 更大则自最后一档按衰减补齐。 */
 const DEFAULT_EDGE_LAYER_ALPHAS = [200, 120, 60];
 function buildEdgeLayerAlphas(edgeLayers) {
@@ -293,10 +373,418 @@ async function splitSpriteSheetToDir(inputPath, outputDir, analysis) {
     writeFileSync(join(outputDir, 'split-meta.json'), JSON.stringify(splitMeta, null, 2), 'utf-8');
     return written;
 }
+const ANIMATE_PRESETS = {
+    spin: { description: 'Y-axis rotation illusion via scale-x oscillation', example: 'coins, icons, medals' },
+    bounce: { description: 'Vertical sine-wave translation', example: 'characters, collectibles' },
+    pulse: { description: 'Scale oscillation (grow/shrink loop)', example: 'buttons, highlights, effects' },
+    shake: { description: 'Random small xy offsets', example: 'hit effects, alerts, damage' },
+    float: { description: 'Gentle up/down float with subtle rotation', example: 'floating items, power-ups' },
+    blink: { description: 'Opacity oscillation (appear/disappear)', example: 'cursors, prompts, warnings' },
+    swing: { description: 'Pendulum rotation around top-center pivot', example: 'hanging objects, lanterns' },
+    wobble: { description: 'Alternating slight rotation left/right', example: 'jelly, soft objects, blobs' },
+};
+/** Compute per-frame affine transform { scaleX, scaleY, translateX, translateY, rotate (deg), opacity } */
+function computeFrameTransforms(preset, frameCount) {
+    const frames = [];
+    for (let i = 0; i < frameCount; i++) {
+        const t = i / frameCount; // 0..1 progress
+        const sin = Math.sin(t * Math.PI * 2);
+        const cos = Math.cos(t * Math.PI * 2);
+        switch (preset) {
+            case 'spin':
+                // Y-rotation illusion: scale-x oscillates -1..1, slight y scale for depth
+                frames.push({ scaleX: cos, scaleY: 1, tx: 0, ty: 0, rotate: 0, opacity: 1 });
+                break;
+            case 'bounce':
+                frames.push({ scaleX: 1, scaleY: 1, tx: 0, ty: Math.round(sin * -12), rotate: 0, opacity: 1 });
+                break;
+            case 'pulse': {
+                const s = 1 + Math.abs(sin) * 0.15;
+                frames.push({ scaleX: s, scaleY: s, tx: 0, ty: 0, rotate: 0, opacity: 1 });
+                break;
+            }
+            case 'shake': {
+                const r = (seed) => (((Math.sin(seed * 127.3 + i * 43.7) + 1) / 2) * 2 - 1);
+                frames.push({ scaleX: 1, scaleY: 1, tx: Math.round(r(0) * 4), ty: Math.round(r(1) * 4), rotate: 0, opacity: 1 });
+                break;
+            }
+            case 'float':
+                frames.push({ scaleX: 1, scaleY: 1, tx: 0, ty: Math.round(sin * -8), rotate: sin * 2, opacity: 1 });
+                break;
+            case 'blink':
+                frames.push({ scaleX: 1, scaleY: 1, tx: 0, ty: 0, rotate: 0, opacity: Math.max(0.2, (cos + 1) / 2) });
+                break;
+            case 'swing':
+                frames.push({ scaleX: 1, scaleY: 1, tx: 0, ty: 0, rotate: sin * 18, opacity: 1 });
+                break;
+            case 'wobble':
+                frames.push({ scaleX: 1, scaleY: 1, tx: 0, ty: 0, rotate: sin * 10, opacity: 1 });
+                break;
+        }
+    }
+    return frames;
+}
+async function renderAnimFrame(inputPath, W, H, tf) {
+    // 1. Start with RGBA source
+    let imgBuf = await sharp(inputPath).ensureAlpha().toBuffer();
+    // 2. Scale: compute target dimensions (minimum 1px)
+    const targetW = Math.max(1, Math.round(Math.abs(tf.scaleX) * W));
+    const targetH = Math.max(1, Math.round(Math.abs(tf.scaleY) * H));
+    if (targetW !== W || targetH !== H) {
+        imgBuf = await sharp(imgBuf).resize(targetW, targetH, { fit: 'fill' }).toBuffer();
+    }
+    // 3. Horizontal flip for negative scaleX (simulate Y-axis rotation)
+    if (tf.scaleX < 0) {
+        imgBuf = await sharp(imgBuf).flop().toBuffer();
+    }
+    // 4. Vertical flip for negative scaleY
+    if (tf.scaleY < 0) {
+        imgBuf = await sharp(imgBuf).flip().toBuffer();
+    }
+    // 5. Rotation (sharp.rotate adds transparent padding — resize back to fit W×H)
+    if (Math.abs(tf.rotate) > 0.1) {
+        imgBuf = await sharp(imgBuf)
+            .rotate(tf.rotate, { background: { r: 0, g: 0, b: 0, alpha: 0 } })
+            .resize(W, H, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+            .toBuffer();
+    }
+    // 6. Opacity
+    if (tf.opacity < 1) {
+        const raw = await sharp(imgBuf).raw().toBuffer({ resolveWithObject: true });
+        const px = raw.data;
+        for (let p = 3; p < px.length; p += 4) {
+            px[p] = Math.round((px[p] ?? 255) * tf.opacity);
+        }
+        imgBuf = await sharp(Buffer.from(px), {
+            raw: { width: raw.info.width, height: raw.info.height, channels: 4 },
+        })
+            .png()
+            .toBuffer();
+    }
+    // 7. Ensure final image fits within W×H before compositing
+    const fm = await sharp(imgBuf).metadata();
+    let fw = fm.width ?? targetW;
+    let fh = fm.height ?? targetH;
+    if (fw > W || fh > H) {
+        imgBuf = await sharp(imgBuf)
+            .resize(W, H, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+            .toBuffer();
+        const fm2 = await sharp(imgBuf).metadata();
+        fw = fm2.width ?? W;
+        fh = fm2.height ?? H;
+    }
+    const left = Math.round((W - fw) / 2 + tf.tx);
+    const top = Math.round((H - fh) / 2 + tf.ty);
+    return sharp({
+        create: { width: W, height: H, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
+    })
+        .composite([{ input: imgBuf, left: Math.max(0, left), top: Math.max(0, top) }])
+        .png()
+        .toBuffer();
+}
+/**
+ * Render one frame of a card flip with perspective simulation:
+ *   - scaleX: horizontal compression ratio (0..1)
+ *   - progress: 0 = face-on, 1 = fully edge-on (controls height squeeze + shadow)
+ *   - shadowSide: 'left' for front-to-edge, 'right' for edge-to-back
+ */
+/**
+ * t = 0: face-on (no rotation)
+ * t = 1: fully edge-on (90°)
+ *
+ * Physical model:
+ *   - scaleX = cos(t × π/2)  → fast initially, slow near edge (cosine ease-in)
+ *   - scaleY = 1 - t² × 0.06 → subtle height squeeze, strongest at edge
+ *   - shadow  = sin²(t × π/2) → almost zero when face-on, peaks at edge (sin² curve)
+ *   - highlight strip on the lit edge (opposite side from shadow)
+ */
+async function renderFlipFrame(srcBuf, W, H, scaleX, t, // rotation progress 0..1 (0=face-on, 1=edge-on)
+shadowSide) {
+    // Height: slight squeeze at edge-on, follows t²
+    const scaleY = Math.max(0.88, 1 - t * t * 0.06);
+    const targetW = Math.max(1, Math.round(scaleX * W));
+    const targetH = Math.max(1, Math.round(scaleY * H));
+    let imgBuf = await sharp(srcBuf)
+        .resize(targetW, targetH, { fit: 'fill' })
+        .ensureAlpha()
+        .toBuffer();
+    // Shadow + highlight overlay (only meaningful when actually rotating)
+    if (t > 0.08) {
+        // sin² curve: nearly 0 near face-on, peaks sharply near edge
+        const shadowT = Math.sin(t * Math.PI / 2);
+        const shadowAlpha = Math.min(0.80, shadowT * shadowT * 0.90);
+        const highlightAlpha = Math.min(0.25, shadowT * shadowT * 0.30);
+        const shadowX1 = shadowSide === 'left' ? '0%' : '100%';
+        const shadowX2 = shadowSide === 'left' ? '70%' : '30%';
+        const hlX1 = shadowSide === 'left' ? '100%' : '0%';
+        const hlX2 = shadowSide === 'left' ? '80%' : '20%';
+        const overlaySvg = `<svg width="${targetW}" height="${targetH}" xmlns="http://www.w3.org/2000/svg">
+      <defs>
+        <linearGradient id="sh" x1="${shadowX1}" y1="0%" x2="${shadowX2}" y2="0%">
+          <stop offset="0%" stop-color="black" stop-opacity="${shadowAlpha.toFixed(3)}"/>
+          <stop offset="100%" stop-color="black" stop-opacity="0"/>
+        </linearGradient>
+        <linearGradient id="hl" x1="${hlX1}" y1="0%" x2="${hlX2}" y2="0%">
+          <stop offset="0%" stop-color="white" stop-opacity="${highlightAlpha.toFixed(3)}"/>
+          <stop offset="100%" stop-color="white" stop-opacity="0"/>
+        </linearGradient>
+      </defs>
+      <rect width="${targetW}" height="${targetH}" fill="url(#sh)"/>
+      <rect width="${targetW}" height="${targetH}" fill="url(#hl)"/>
+    </svg>`;
+        const overlayBuf = await sharp(Buffer.from(overlaySvg)).png().toBuffer();
+        imgBuf = await sharp(imgBuf)
+            .composite([{ input: overlayBuf, blend: 'over' }])
+            .png()
+            .toBuffer();
+    }
+    const left = Math.round((W - targetW) / 2);
+    const top = Math.round((H - targetH) / 2);
+    return sharp({
+        create: { width: W, height: H, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
+    })
+        .composite([{ input: imgBuf, left, top }])
+        .png()
+        .toBuffer();
+}
+/**
+ * Two-image flip sprite sheet with 3D perspective simulation:
+ * - Height compresses slightly at midpoint (viewing angle effect)
+ * - Shadow gradient on the turning edge
+ * - Front half: scaleX 1→0 (shadow on left/trailing)
+ * - Back half:  scaleX 0→1 (shadow on right/trailing)
+ */
+async function buildFlipSpriteSheet(frontPath, backPath, frameCount, columns, outputPath) {
+    const meta = await sharp(frontPath).metadata();
+    const W = meta.width ?? 128;
+    const H = meta.height ?? 128;
+    const frontBuf = await sharp(frontPath).ensureAlpha().toBuffer();
+    const backBuf = await sharp(backPath)
+        .resize(W, H, { fit: 'fill' })
+        .ensureAlpha()
+        .png()
+        .toBuffer();
+    const half = Math.floor(frameCount / 2);
+    const frameBuffers = [];
+    // Front side: angle goes from 0° → ~90°, scaleX = cos(angle)
+    // t=0 at frame 0 (face-on), t=1 at frame half-1 (edge-on)
+    for (let i = 0; i < half; i++) {
+        const t = i / half; // 0 → ~1 (not including 1)
+        const angle = t * (Math.PI / 2);
+        const scaleX = Math.max(0.01, Math.cos(angle)); // cosine: 1 → 0
+        frameBuffers.push(await renderFlipFrame(frontBuf, W, H, scaleX, t, 'left'));
+    }
+    // Back side: angle goes from ~90° → 0°, scaleX = cos(angle) growing back
+    for (let i = 0; i < frameCount - half; i++) {
+        const t = 1 - (i + 1) / (frameCount - half); // ~1 → 0 (edge-on → face-on)
+        const angle = t * (Math.PI / 2);
+        const scaleX = Math.max(0.01, Math.cos(angle));
+        frameBuffers.push(await renderFlipFrame(backBuf, W, H, scaleX, t, 'right'));
+    }
+    // Assemble sprite sheet
+    const rows = Math.ceil(frameCount / columns);
+    const composites = frameBuffers.map((buf, i) => ({
+        input: buf,
+        left: (i % columns) * W,
+        top: Math.floor(i / columns) * H,
+    }));
+    ensureDir(outputPath);
+    await sharp({
+        create: { width: W * columns, height: H * rows, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
+    })
+        .composite(composites)
+        .png()
+        .toFile(outputPath);
+}
+async function buildAnimationSpriteSheet(inputPath, preset, frameCount, columns, outputPath) {
+    const meta = await sharp(inputPath).metadata();
+    const W = meta.width ?? 128;
+    const H = meta.height ?? 128;
+    const transforms = computeFrameTransforms(preset, frameCount);
+    const frameBuffers = [];
+    for (const tf of transforms) {
+        const buf = await renderAnimFrame(inputPath, W, H, tf);
+        frameBuffers.push(buf);
+    }
+    // Assemble sprite sheet
+    const rows = Math.ceil(frameCount / columns);
+    const sheetW = W * columns;
+    const sheetH = H * rows;
+    const composites = frameBuffers.map((buf, i) => ({
+        input: buf,
+        left: (i % columns) * W,
+        top: Math.floor(i / columns) * H,
+    }));
+    ensureDir(outputPath);
+    await sharp({
+        create: { width: sheetW, height: sheetH, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
+    })
+        .composite(composites)
+        .png()
+        .toFile(outputPath);
+}
+// ─── VFX presets ────────────────────────────────────────────────────────────
+const __vfxDir = join(dirname(fileURLToPath(import.meta.url)), '../../assets/vfx');
+const VFX_PRESETS = [
+    { name: 'explosion_small', file: 'explosion_small.png', frames: 8, columns: 4, size: '~30KB', description: 'Small explosion burst — match clear, block break' },
+    { name: 'sparkle', file: 'sparkle.png', frames: 6, columns: 3, size: '~15KB', description: 'Sparkle burst — score, reward, shine' },
+    { name: 'confetti', file: 'confetti.png', frames: 12, columns: 4, size: '~25KB', description: 'Celebration confetti rain — level complete' },
+    { name: 'starburst', file: 'starburst.png', frames: 8, columns: 4, size: '~20KB', description: 'Star burst radial — bonus, combo' },
+    { name: 'smoke', file: 'smoke.png', frames: 8, columns: 4, size: '~20KB', description: 'Smoke puff — disappear, dash, impact' },
+    { name: 'glow', file: 'glow.png', frames: 6, columns: 3, size: '~10KB', description: 'Glow pulse ring — highlight, select, power-up' },
+    { name: 'impact_ring', file: 'impact_ring.png', frames: 6, columns: 3, size: '~15KB', description: 'Impact ring expand — hit, land, drop' },
+    { name: 'coin_collect', file: 'coin_collect.png', frames: 8, columns: 4, size: '~20KB', description: 'Coin collect flash — currency pickup, reward' },
+];
+/**
+ * 在 batch 管线中执行单个步骤（复用 sharp 逻辑，无需启动子进程）。
+ */
+async function runBatchStep(cmd, args, inputPath, outputPath) {
+    const getArg = (flag) => {
+        const idx = args.indexOf(flag);
+        return idx !== -1 ? args[idx + 1] : undefined;
+    };
+    const hasFlag = (flag) => args.includes(flag);
+    ensureDir(outputPath);
+    switch (cmd) {
+        case 'remove-background': {
+            const method = getArg('--method') ?? 'floodfill';
+            if (method === 'floodfill') {
+                const tolerance = Number(getArg('--tolerance') ?? 30);
+                const edgeLayers = Number(getArg('--edge-smooth') ?? 2);
+                const { buffer } = await floodFillRemoveBg(inputPath, { tolerance, edgeLayers: Math.min(edgeLayers, 4) });
+                writeFileSync(outputPath, buffer);
+            }
+            else {
+                throw new Error('batch does not support --method ai (requires backend). Use floodfill.');
+            }
+            break;
+        }
+        case 'resize': {
+            const w = getArg('--width') ? Number(getArg('--width')) : undefined;
+            const h = getArg('--height') ? Number(getArg('--height')) : undefined;
+            const scale = getArg('--scale') ? Number(getArg('--scale')) : undefined;
+            const fit = (getArg('--fit') ?? 'cover');
+            const meta = await sharp(inputPath).metadata();
+            const targetW = scale ? Math.round((meta.width ?? 64) * scale) : w;
+            const targetH = scale ? Math.round((meta.height ?? 64) * scale) : h;
+            await safeToFile(sharp(inputPath).resize(targetW, targetH, { fit }), outputPath, inputPath);
+            break;
+        }
+        case 'convert': {
+            const fmt = (getArg('--format') ?? outputPath.split('.').pop() ?? 'png').toLowerCase();
+            const quality = Number(getArg('--quality') ?? 85);
+            const lossless = hasFlag('--lossless');
+            let pipeline = sharp(inputPath);
+            if (fmt === 'jpg' || fmt === 'jpeg')
+                pipeline = pipeline.jpeg({ quality });
+            else if (fmt === 'webp')
+                pipeline = pipeline.webp({ quality, lossless });
+            else if (fmt === 'avif')
+                pipeline = pipeline.avif({ quality, lossless });
+            else
+                pipeline = pipeline.png();
+            await safeToFile(pipeline, outputPath, inputPath);
+            break;
+        }
+        case 'grayscale':
+            await safeToFile(sharp(inputPath).grayscale(), outputPath, inputPath);
+            break;
+        case 'blur': {
+            const sigma = Number(getArg('--sigma') ?? 3);
+            await safeToFile(sharp(inputPath).blur(sigma), outputPath, inputPath);
+            break;
+        }
+        case 'tint': {
+            const color = getArg('--color') ?? '#ff0000';
+            await safeToFile(sharp(inputPath).tint(color), outputPath, inputPath);
+            break;
+        }
+        case 'trim': {
+            const threshold = Number(getArg('--threshold') ?? 10);
+            await safeToFile(sharp(inputPath).trim({ threshold }), outputPath, inputPath);
+            break;
+        }
+        case 'negate':
+            await safeToFile(sharp(inputPath).negate({ alpha: !hasFlag('--no-alpha') }), outputPath, inputPath);
+            break;
+        case 'rotate': {
+            const angle = Number(getArg('--angle') ?? 0);
+            const bg = getArg('--background') ?? '#00000000';
+            await safeToFile(sharp(inputPath).rotate(angle, { background: bg }), outputPath, inputPath);
+            break;
+        }
+        case 'flip': {
+            const dir = getArg('--direction') ?? 'horizontal';
+            let pipeline = sharp(inputPath);
+            if (dir === 'horizontal')
+                pipeline = pipeline.flop();
+            else
+                pipeline = pipeline.flip();
+            await safeToFile(pipeline, outputPath, inputPath);
+            break;
+        }
+        case 'pad': {
+            const all = getArg('--all') ? Number(getArg('--all')) : undefined;
+            const top = all ?? Number(getArg('--top') ?? 0);
+            const bottom = all ?? Number(getArg('--bottom') ?? 0);
+            const left = all ?? Number(getArg('--left') ?? 0);
+            const right = all ?? Number(getArg('--right') ?? 0);
+            const bg = getArg('--background') ?? '#00000000';
+            await safeToFile(sharp(inputPath).extend({ top, bottom, left, right, background: bg }), outputPath, inputPath);
+            break;
+        }
+        case 'pixelate': {
+            const meta = await sharp(inputPath).metadata();
+            const ps = Number(getArg('--pixel-size') ?? 8);
+            const w = meta.width ?? 64;
+            const h = meta.height ?? 64;
+            await safeToFile(sharp(inputPath).resize(Math.max(1, Math.floor(w / ps)), Math.max(1, Math.floor(h / ps)), { kernel: 'nearest' }).resize(w, h, { kernel: 'nearest' }), outputPath, inputPath);
+            break;
+        }
+        default:
+            throw new Error(`runBatchStep: unsupported command "${cmd}"`);
+    }
+}
 export function registerImageCommands(program) {
     const img = program
         .command('image')
         .description('素材工具：本地图片处理（sharp）；remove-background / sprite-split --auto-detect 可调用后端 API');
+    // ─── info ────────────────────────────────────────────────────
+    img.command('info')
+        .description('输出图片元信息（尺寸、格式、通道、文件大小、DPI）')
+        .requiredOption('--input <path>', '输入图片路径')
+        .option('--json', '以 JSON 格式输出（默认人类可读格式）')
+        .action(async (opts) => {
+        try {
+            assertInputWithinLimit(opts.input);
+            const meta = await sharp(opts.input).metadata();
+            const fileStat = statSync(opts.input);
+            const channels = meta.channels ?? 0;
+            const channelLabel = channels === 4 ? 'RGBA' : channels === 3 ? 'RGB' : channels === 1 ? 'Gray' : String(channels);
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    file: opts.input,
+                    format: meta.format,
+                    width: meta.width,
+                    height: meta.height,
+                    channels,
+                    space: meta.space,
+                    density: meta.density,
+                    hasAlpha: meta.hasAlpha,
+                    fileSize: fileStat.size,
+                    fileSizeLabel: sizeLabelBytes(fileStat.size),
+                }, null, 2));
+            }
+            else {
+                const dpiStr = meta.density ? ` | DPI: ${meta.density}` : '';
+                console.log(`File: ${opts.input}`);
+                console.log(`Format: ${meta.format ?? 'unknown'} | Size: ${meta.width ?? '?'}x${meta.height ?? '?'} | Channels: ${channels} (${channelLabel}) | File: ${sizeLabelBytes(fileStat.size)}${dpiStr}`);
+            }
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
     // ─── resize ──────────────────────────────────────────────────
     img.command('resize')
         .description('缩放图片（按比例或指定宽高）')
@@ -327,10 +815,7 @@ export function registerImageCommands(program) {
                 process.exit(1);
             }
             const fit = parseResizeFitOption(opts.fit);
-            ensureDir(opts.output);
-            await sharp(opts.input)
-                .resize(targetW, targetH, { fit })
-                .toFile(opts.output);
+            await safeToFile(sharp(opts.input).resize(targetW, targetH, { fit }), opts.output, opts.input);
             const outSz = statSync(opts.output).size;
             console.log(`Resized ${w}x${h} → ${targetW ?? '?'}x${targetH ?? '?'} — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
@@ -350,10 +835,7 @@ export function registerImageCommands(program) {
         .action(async (opts) => {
         try {
             assertInputWithinLimit(opts.input);
-            ensureDir(opts.output);
-            await sharp(opts.input)
-                .extract({ left: opts.x, top: opts.y, width: opts.width, height: opts.height })
-                .toFile(opts.output);
+            await safeToFile(sharp(opts.input).extract({ left: opts.x, top: opts.y, width: opts.width, height: opts.height }), opts.output, opts.input);
             const outSz = statSync(opts.output).size;
             console.log(`Cropped to ${opts.width}x${opts.height} at (${opts.x},${opts.y}) — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
@@ -371,10 +853,7 @@ export function registerImageCommands(program) {
         .action(async (opts) => {
         try {
             assertInputWithinLimit(opts.input);
-            ensureDir(opts.output);
-            await sharp(opts.input)
-                .rotate(opts.angle, { background: opts.background })
-                .toFile(opts.output);
+            await safeToFile(sharp(opts.input).rotate(opts.angle, { background: opts.background }), opts.output, opts.input);
             const outSz = statSync(opts.output).size;
             console.log(`Rotated ${opts.angle}° — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
@@ -402,8 +881,7 @@ export function registerImageCommands(program) {
                 console.error('Error: --direction must be horizontal or vertical');
                 process.exit(1);
             }
-            ensureDir(opts.output);
-            await pipeline.toFile(opts.output);
+            await safeToFile(pipeline, opts.output, opts.input);
             const outSz = statSync(opts.output).size;
             console.log(`Flipped ${opts.direction} — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
@@ -428,10 +906,7 @@ export function registerImageCommands(program) {
             const pad = opts.all !== undefined
                 ? { top: opts.all, bottom: opts.all, left: opts.all, right: opts.all }
                 : { top: opts.top, bottom: opts.bottom, left: opts.left, right: opts.right };
-            ensureDir(opts.output);
-            await sharp(opts.input)
-                .extend({ ...pad, background: opts.background })
-                .toFile(opts.output);
+            await safeToFile(sharp(opts.input).extend({ ...pad, background: opts.background }), opts.output, opts.input);
             const meta = await sharp(opts.output).metadata();
             const outSz = statSync(opts.output).size;
             console.log(`Padded to ${meta.width}x${meta.height} — ${opts.output} (${sizeLabelBytes(outSz)})`);
@@ -470,8 +945,7 @@ export function registerImageCommands(program) {
                     pipeline = pipeline.png();
                     break;
             }
-            ensureDir(opts.output);
-            await pipeline.toFile(opts.output);
+            await safeToFile(pipeline, opts.output, opts.input);
             const outSz = statSync(opts.output).size;
             const ratio = origSize > 0 ? ((1 - outSz / origSize) * 100).toFixed(1) : '0.0';
             console.log(`Converted to ${fmt} — ${opts.output} (${sizeLabelBytes(outSz)}, ${ratio}% reduction)`);
@@ -488,8 +962,7 @@ export function registerImageCommands(program) {
         .action(async (opts) => {
         try {
             assertInputWithinLimit(opts.input);
-            ensureDir(opts.output);
-            await sharp(opts.input).grayscale().toFile(opts.output);
+            await safeToFile(sharp(opts.input).grayscale(), opts.output, opts.input);
             const outSz = statSync(opts.output).size;
             console.log(`Grayscale — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
@@ -506,8 +979,7 @@ export function registerImageCommands(program) {
         .action(async (opts) => {
         try {
             assertInputWithinLimit(opts.input);
-            ensureDir(opts.output);
-            await sharp(opts.input).blur(opts.sigma).toFile(opts.output);
+            await safeToFile(sharp(opts.input).blur(opts.sigma), opts.output, opts.input);
             const outSz = statSync(opts.output).size;
             console.log(`Blurred (sigma=${opts.sigma}) — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
@@ -524,8 +996,7 @@ export function registerImageCommands(program) {
         .action(async (opts) => {
         try {
             assertInputWithinLimit(opts.input);
-            ensureDir(opts.output);
-            await sharp(opts.input).tint(opts.color).toFile(opts.output);
+            await safeToFile(sharp(opts.input).tint(opts.color), opts.output, opts.input);
             const outSz = statSync(opts.output).size;
             console.log(`Tinted with ${opts.color} — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
@@ -543,8 +1014,7 @@ export function registerImageCommands(program) {
         try {
             assertInputWithinLimit(opts.input);
             const before = await sharp(opts.input).metadata();
-            ensureDir(opts.output);
-            await sharp(opts.input).trim({ threshold: opts.threshold }).toFile(opts.output);
+            await safeToFile(sharp(opts.input).trim({ threshold: opts.threshold }), opts.output, opts.input);
             const after = await sharp(opts.output).metadata();
             const outSz = statSync(opts.output).size;
             console.log(`Trimmed ${before.width}x${before.height} → ${after.width}x${after.height} — ${opts.output} (${sizeLabelBytes(outSz)})`);
@@ -562,8 +1032,7 @@ export function registerImageCommands(program) {
         .action(async (opts) => {
         try {
             assertInputWithinLimit(opts.input);
-            ensureDir(opts.output);
-            await sharp(opts.input).negate({ alpha: opts.alpha !== false }).toFile(opts.output);
+            await safeToFile(sharp(opts.input).negate({ alpha: opts.alpha !== false }), opts.output, opts.input);
             const outSz = statSync(opts.output).size;
             console.log(`Negated — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
@@ -592,8 +1061,7 @@ export function registerImageCommands(program) {
             else {
                 overlayOpts.gravity = opts.gravity;
             }
-            ensureDir(opts.output);
-            await sharp(opts.base).composite([overlayOpts]).toFile(opts.output);
+            await safeToFile(sharp(opts.base).composite([overlayOpts]), opts.output, opts.base);
             const meta = await sharp(opts.output).metadata();
             const outSz = statSync(opts.output).size;
             console.log(`Composited — ${meta.width}x${meta.height} — ${opts.output} (${sizeLabelBytes(outSz)})`);
@@ -616,11 +1084,7 @@ export function registerImageCommands(program) {
             const h = meta.height ?? 64;
             const smallW = Math.max(1, Math.floor(w / opts.pixelSize));
             const smallH = Math.max(1, Math.floor(h / opts.pixelSize));
-            ensureDir(opts.output);
-            await sharp(opts.input)
-                .resize(smallW, smallH, { kernel: 'nearest' })
-                .resize(w, h, { kernel: 'nearest' })
-                .toFile(opts.output);
+            await safeToFile(sharp(opts.input).resize(smallW, smallH, { kernel: 'nearest' }).resize(w, h, { kernel: 'nearest' }), opts.output, opts.input);
             const outSz = statSync(opts.output).size;
             console.log(`Pixelated (block=${opts.pixelSize}px) — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }
@@ -696,17 +1160,31 @@ export function registerImageCommands(program) {
     // ─── sprite-sheet ────────────────────────────────────────────
     img.command('sprite-sheet')
         .description('将多张图合并为精灵图，并输出帧坐标 JSON（完整本地实现）')
-        .requiredOption('--inputs <paths>', '输入图片路径列表，逗号分隔')
+        .option('--inputs <paths>', '输入图片路径，逗号分隔，支持 glob 模式（如 "tiles/*.png"）')
+        .option('--input-dir <dir>', '从目录读取所有图片（与 --inputs 二选一）')
+        .option('--glob <pattern>', '配合 --input-dir 使用的文件匹配模式（默认 "*.png"）', '*.png')
+        .option('--sort <mode>', '排序方式：name（默认，自然排序）| modified | none', 'name')
         .requiredOption('--output <basePath>', '输出基路径（自动生成 .png 和 .json）')
         .option('--columns <n>', '列数（默认自动按平方根计算）', cliParseInt)
         .option('--padding <n>', '帧间距（像素，默认 0）', cliParseInt, 0)
         .option('--cell-width <n>', '统一格子宽度（不填则用第一张图宽度）', cliParseInt)
         .option('--cell-height <n>', '统一格子高度（不填则用第一张图高度）', cliParseInt)
+        .option('--background <color>', '精灵图背景色：transparent（默认）| white | black | #RRGGBB。某些引擎透明区域会显示为黑色，此时用 white 更安全', 'transparent')
         .action(async (opts) => {
         try {
-            const paths = opts.inputs.split(',').map((p) => p.trim()).filter(Boolean);
+            let paths;
+            if (opts.inputDir) {
+                paths = collectFromDir(opts.inputDir, opts.glob ?? '*.png', opts.sort ?? 'name');
+            }
+            else if (opts.inputs) {
+                paths = expandInputPaths(opts.inputs);
+            }
+            else {
+                console.error('Error: provide --inputs or --input-dir');
+                process.exit(1);
+            }
             if (!paths.length) {
-                console.error('Error: --inputs is empty');
+                console.error('Error: no input files found');
                 process.exit(1);
             }
             for (let i = 0; i < paths.length; i++) {
@@ -732,8 +1210,29 @@ export function registerImageCommands(program) {
                 composites.push({ input: resized, left: x, top: y });
                 frames[frameName] = { x, y, w: cellW, h: cellH };
             }
+            // 解析背景色：transparent → alpha=0 黑色画布；其他颜色 → 用 sharp 解析
+            const bgColor = opts.background ?? 'transparent';
+            let canvasBackground;
+            if (bgColor === 'transparent') {
+                canvasBackground = { r: 0, g: 0, b: 0, alpha: 0 };
+            }
+            else if (bgColor === 'white') {
+                canvasBackground = { r: 255, g: 255, b: 255, alpha: 1 };
+            }
+            else if (bgColor === 'black') {
+                canvasBackground = { r: 0, g: 0, b: 0, alpha: 1 };
+            }
+            else {
+                // 支持 #RRGGBB / #RRGGBBAA 十六进制
+                const hex = bgColor.replace('#', '');
+                const r = parseInt(hex.slice(0, 2), 16) || 0;
+                const g = parseInt(hex.slice(2, 4), 16) || 0;
+                const b = parseInt(hex.slice(4, 6), 16) || 0;
+                const a = hex.length >= 8 ? (parseInt(hex.slice(6, 8), 16) || 0) / 255 : 1;
+                canvasBackground = { r, g, b, alpha: a };
+            }
             const canvas = await sharp({
-                create: { width: totalW, height: totalH, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
+                create: { width: totalW, height: totalH, channels: 4, background: canvasBackground },
             }).png().toBuffer();
             const sheetBuf = await sharp(canvas).composite(composites).png().toBuffer();
             const basePath = opts.output.replace(/\.(png|json)$/i, '');
@@ -748,6 +1247,337 @@ export function registerImageCommands(program) {
             handleError(e);
         }
     });
+    // ─── batch ───────────────────────────────────────────────────
+    img.command('batch')
+        .description([
+        '对一批图片执行相同的处理步骤（声明式管线）',
+        '',
+        '  示例：去背 + 统一尺寸',
+        '    playcraft image batch \\',
+        '      --input-dir assets/images/raw/ \\',
+        '      --output-dir assets/images/processed/ \\',
+        '      --steps "remove-background,resize --width 128 --height 128"',
+        '',
+        '  示例：批量转格式',
+        '    playcraft image batch \\',
+        '      --inputs "raw/*.jpg" \\',
+        '      --output-dir out/ \\',
+        '      --steps "convert --format png"',
+    ].join('\n'))
+        .option('--input-dir <dir>', '输入目录（与 --inputs 二选一）')
+        .option('--glob <pattern>', '配合 --input-dir 的文件匹配（默认 "*.png,*.jpg,*.jpeg,*.webp"）')
+        .option('--inputs <paths>', '逗号分隔的输入文件列表，支持 glob')
+        .requiredOption('--output-dir <dir>', '输出目录（保持文件名，统一输出为 PNG）')
+        .requiredOption('--steps <pipeline>', '处理步骤，逗号分隔，每步是 image 子命令 + 参数（如 "remove-background,resize --width 128 --height 128"）')
+        .option('--parallel <n>', '并发处理数（默认 4）', cliParseInt, 4)
+        .option('--skip-existing', '跳过输出目录中已存在的文件')
+        .action(async (opts) => {
+        try {
+            // 收集输入文件
+            let inputs;
+            if (opts.inputDir) {
+                const globPatterns = (opts.glob ?? '*.png,*.jpg,*.jpeg,*.webp').split(',').map((p) => p.trim());
+                const allFiles = [];
+                for (const pat of globPatterns) {
+                    const matched = collectFromDir(opts.inputDir, pat, 'name');
+                    allFiles.push(...matched);
+                }
+                inputs = [...new Set(allFiles)];
+                inputs.sort((a, b) => basename(a).localeCompare(basename(b), undefined, { numeric: true, sensitivity: 'base' }));
+            }
+            else if (opts.inputs) {
+                inputs = expandInputPaths(opts.inputs);
+            }
+            else {
+                console.error('Error: provide --input-dir or --inputs');
+                process.exit(1);
+            }
+            if (!inputs.length) {
+                console.error('Error: no input files found');
+                process.exit(1);
+            }
+            // 解析 steps 管线：逗号分隔，但要忽略参数值中的逗号（通过分割子命令名称来识别）
+            const knownSubcommands = ['remove-background', 'resize', 'crop', 'rotate', 'flip', 'pad', 'convert', 'grayscale', 'blur', 'tint', 'trim', 'negate', 'pixelate'];
+            const stepStr = opts.steps;
+            const steps = [];
+            // 按已知子命令名前缀分割
+            let remaining = stepStr;
+            while (remaining.trim()) {
+                let found = false;
+                for (const sc of knownSubcommands) {
+                    if (remaining.trim().startsWith(sc)) {
+                        const afterCmd = remaining.trim().slice(sc.length).trim();
+                        // 找下个子命令的位置（遇到已知子命令才截断）
+                        let nextCmdIdx = afterCmd.length;
+                        for (const nextSc of knownSubcommands) {
+                            // look for ",nextSc" or " nextSc" pattern
+                            const comma = afterCmd.indexOf(',' + nextSc);
+                            if (comma !== -1 && comma < nextCmdIdx)
+                                nextCmdIdx = comma;
+                        }
+                        const argsStr = afterCmd.slice(0, nextCmdIdx).trim().replace(/^,/, '').trim();
+                        // Parse args string into array (basic shell-like split)
+                        const args = [];
+                        const argRegex = /(?:[^\s"']+|"[^"]*"|'[^']*')+/g;
+                        let m;
+                        while ((m = argRegex.exec(argsStr)) !== null) {
+                            args.push(m[0].replace(/^["']|["']$/g, ''));
+                        }
+                        steps.push({ cmd: sc, args });
+                        remaining = afterCmd.slice(nextCmdIdx).trim().replace(/^,/, '').trim();
+                        found = true;
+                        break;
+                    }
+                }
+                if (!found) {
+                    console.error(`Error: unknown step in --steps: "${remaining.trim()}"`);
+                    console.error(`Known subcommands: ${knownSubcommands.join(', ')}`);
+                    process.exit(1);
+                }
+            }
+            if (!steps.length) {
+                console.error('Error: --steps is empty or invalid');
+                process.exit(1);
+            }
+            mkdirSync(opts.outputDir, { recursive: true });
+            let done = 0, skipped = 0, failed = 0;
+            const total = inputs.length;
+            const concurrency = Math.max(1, opts.parallel);
+            const processOne = async (inputPath) => {
+                const outName = basename(inputPath).replace(/\.[^.]+$/, '.png');
+                const outPath = join(opts.outputDir, outName);
+                if (opts.skipExisting && existsSync(outPath)) {
+                    skipped++;
+                    process.stdout.write(`\r[${done + skipped + failed}/${total}] skipping ${outName} (exists)`);
+                    return;
+                }
+                // Apply each step sequentially using a temp file chain
+                let currentPath = inputPath;
+                let tmpFiles = [];
+                try {
+                    for (let si = 0; si < steps.length; si++) {
+                        const step = steps[si];
+                        const isLast = si === steps.length - 1;
+                        const stepOut = isLast ? outPath : `${outPath}.step${si}.tmp`;
+                        if (!isLast)
+                            tmpFiles.push(stepOut);
+                        // Build a minimal CLI-like invocation by manipulating sharp directly
+                        await runBatchStep(step.cmd, step.args, currentPath, stepOut);
+                        currentPath = stepOut;
+                    }
+                    done++;
+                    process.stdout.write(`\r[${done + skipped + failed}/${total}] done: ${outName}           `);
+                }
+                catch (e) {
+                    failed++;
+                    const msg = e instanceof Error ? e.message : String(e);
+                    process.stdout.write(`\n[${done + skipped + failed}/${total}] FAILED: ${outName} — ${msg}\n`);
+                }
+                finally {
+                    for (const tmp of tmpFiles) {
+                        try {
+                            if (existsSync(tmp)) {
+                                const { unlinkSync } = await import('fs');
+                                unlinkSync(tmp);
+                            }
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+            };
+            // Process with concurrency limit
+            const queue = [...inputs];
+            const workers = [];
+            const runWorker = async () => {
+                while (queue.length) {
+                    const item = queue.shift();
+                    if (item)
+                        await processOne(item);
+                }
+            };
+            for (let i = 0; i < Math.min(concurrency, inputs.length); i++) {
+                workers.push(runWorker());
+            }
+            await Promise.all(workers);
+            console.log(`\n\nBatch complete: ${done} done, ${skipped} skipped, ${failed} failed (${total} total)`);
+            console.log(`Output: ${opts.outputDir}`);
+            if (failed > 0)
+                process.exit(1);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── pipeline ────────────────────────────────────────────────
+    img.command('pipeline')
+        .description([
+        '从 YAML/JSON 配置文件驱动的多步图片处理管线',
+        '',
+        '  示例：',
+        '    playcraft image pipeline --config pipeline.yaml',
+        '',
+        '  配置文件格式（YAML）：',
+        '    input:',
+        '      dir: assets/images/raw/',
+        '      glob: "*.png"',
+        '    steps:',
+        '      - command: remove-background',
+        '        method: floodfill',
+        '      - command: resize',
+        '        width: 128',
+        '        height: 128',
+        '    output:',
+        '      dir: assets/images/processed/',
+        '    assemble:        # 可选：最后合并为精灵图',
+        '      sprite-sheet:',
+        '        output: assets/bundles/tiles',
+        '        columns: 9',
+        '        padding: 2',
+    ].join('\n'))
+        .requiredOption('--config <path>', '配置文件路径（.yaml / .yml / .json）')
+        .option('--dry-run', '只打印将执行的操作，不实际处理')
+        .action(async (opts) => {
+        try {
+            const configRaw = readFileSync(opts.config, 'utf-8');
+            const ext = extname(opts.config).toLowerCase();
+            let config;
+            if (ext === '.json') {
+                config = JSON.parse(configRaw);
+            }
+            else {
+                config = yaml.load(configRaw);
+            }
+            // 收集输入文件
+            let inputs = [];
+            if (config.input?.dir) {
+                const globPat = config.input.glob ?? '*.png';
+                inputs = collectFromDir(config.input.dir, globPat, 'name');
+            }
+            else if (config.input?.files) {
+                for (const f of config.input.files) {
+                    inputs.push(...expandInputPaths(f));
+                }
+            }
+            if (!inputs.length) {
+                console.error('Error: no input files found from config.input');
+                process.exit(1);
+            }
+            const outputDir = config.output?.dir ?? './pipeline-output';
+            const steps = config.steps ?? [];
+            if (!steps.length) {
+                console.error('Error: config.steps is empty');
+                process.exit(1);
+            }
+            // Convert config steps to batch-compatible format
+            const batchSteps = steps.map((step) => {
+                const { command: cmd, ...rest } = step;
+                const args = [];
+                for (const [k, v] of Object.entries(rest)) {
+                    if (v !== undefined && v !== null && v !== false) {
+                        args.push(`--${k}`);
+                        if (v !== true)
+                            args.push(String(v));
+                    }
+                }
+                return { cmd, args };
+            });
+            console.log(`Pipeline config: ${opts.config}`);
+            console.log(`Input: ${inputs.length} file(s) from ${config.input?.dir ?? 'files list'}`);
+            console.log(`Steps: ${batchSteps.map((s) => s.cmd).join(' → ')}`);
+            console.log(`Output: ${outputDir}`);
+            if (opts.dryRun) {
+                console.log('\n[dry-run] Steps that would execute:');
+                for (const s of batchSteps) {
+                    console.log(`  ${s.cmd} ${s.args.join(' ')}`);
+                }
+                console.log(`[dry-run] ${inputs.length} file(s) would be processed.`);
+                return;
+            }
+            mkdirSync(outputDir, { recursive: true });
+            let done = 0, failed = 0;
+            const total = inputs.length;
+            for (const inputPath of inputs) {
+                const outName = basename(inputPath).replace(/\.[^.]+$/, '.png');
+                const outPath = join(outputDir, outName);
+                let currentPath = inputPath;
+                const tmpFiles = [];
+                try {
+                    for (let si = 0; si < batchSteps.length; si++) {
+                        const step = batchSteps[si];
+                        const isLast = si === batchSteps.length - 1;
+                        const stepOut = isLast ? outPath : `${outPath}.step${si}.tmp`;
+                        if (!isLast)
+                            tmpFiles.push(stepOut);
+                        await runBatchStep(step.cmd, step.args, currentPath, stepOut);
+                        currentPath = stepOut;
+                    }
+                    done++;
+                    process.stdout.write(`\r[${done + failed}/${total}] done: ${outName}           `);
+                }
+                catch (e) {
+                    failed++;
+                    const msg = e instanceof Error ? e.message : String(e);
+                    process.stdout.write(`\n[${done + failed}/${total}] FAILED: ${outName} — ${msg}\n`);
+                }
+                finally {
+                    for (const tmp of tmpFiles) {
+                        try {
+                            if (existsSync(tmp)) {
+                                const { unlinkSync } = await import('fs');
+                                unlinkSync(tmp);
+                            }
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+            }
+            console.log(`\n\nPipeline complete: ${done} done, ${failed} failed (${total} total)`);
+            console.log(`Output: ${outputDir}`);
+            // Optional assemble step
+            const assembleConfig = config.assemble?.['sprite-sheet'];
+            if (assembleConfig && done > 0) {
+                console.log('\nRunning assemble: sprite-sheet...');
+                const sheetFiles = collectFromDir(outputDir, '*.png', 'name');
+                if (sheetFiles.length) {
+                    const outBase = assembleConfig.output ?? join(outputDir, 'sprite-sheet');
+                    const cols = assembleConfig.columns ?? Math.ceil(Math.sqrt(sheetFiles.length));
+                    const padding = assembleConfig.padding ?? 0;
+                    const firstMeta = await sharp(sheetFiles[0]).metadata();
+                    const cellW = firstMeta.width ?? 64;
+                    const cellH = firstMeta.height ?? 64;
+                    const rows = Math.ceil(sheetFiles.length / cols);
+                    const totalW = cols * cellW + (cols - 1) * padding;
+                    const totalH = rows * cellH + (rows - 1) * padding;
+                    const composites = [];
+                    const frames = {};
+                    for (let i = 0; i < sheetFiles.length; i++) {
+                        const col = i % cols;
+                        const row = Math.floor(i / cols);
+                        const x = col * (cellW + padding);
+                        const y = row * (cellH + padding);
+                        const frameName = basename(sheetFiles[i]);
+                        const resized = await sharp(sheetFiles[i]).resize(cellW, cellH).toBuffer();
+                        composites.push({ input: resized, left: x, top: y });
+                        frames[frameName] = { x, y, w: cellW, h: cellH };
+                    }
+                    const canvas = await sharp({ create: { width: totalW, height: totalH, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } }).png().toBuffer();
+                    const sheetBuf = await sharp(canvas).composite(composites).png().toBuffer();
+                    const pngPath = `${outBase}.png`;
+                    const jsonPath = `${outBase}.json`;
+                    ensureDir(pngPath);
+                    writeFileSync(pngPath, sheetBuf);
+                    writeFileSync(jsonPath, JSON.stringify({ frames, meta: { image: pngPath, size: { w: totalW, h: totalH }, scale: 1 } }, null, 2), 'utf-8');
+                    console.log(`Sprite sheet: ${pngPath} (${cols}x${rows}, ${sheetFiles.length} frames, ${sizeLabel(sheetBuf)})`);
+                    console.log(`Frame data: ${jsonPath}`);
+                }
+            }
+            if (failed > 0)
+                process.exit(1);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
     // ─── remove-background ─────────────────────────────────────────
     img.command('remove-background')
         .description([
@@ -821,4 +1651,468 @@ export function registerImageCommands(program) {
             handleError(e);
         }
     });
+    // ─── animate ─────────────────────────────────────────────────────────────
+    img
+        .command('animate')
+        .description('Generate a sprite sheet animation from a static image using built-in presets')
+        .option('--input <path>', 'Source image path (PNG/JPG)')
+        .option('--back <path>', 'Back-side image for flip animation (enables two-image flip mode)')
+        .option('--output <path>', 'Output sprite sheet path (PNG)')
+        .option('--preset <name>', `Animation preset: ${Object.keys(ANIMATE_PRESETS).join(', ')} (default: bounce)`, 'bounce')
+        .option('--frames <n>', 'Number of animation frames (default: 8)', '8')
+        .option('--columns <n>', 'Columns in output sprite sheet (default: 4)', '4')
+        .option('--list-presets', 'List all available presets and exit')
+        .action(async (opts) => {
+        try {
+            if (opts.listPresets) {
+                console.log('\nAvailable animation presets:\n');
+                for (const [name, info] of Object.entries(ANIMATE_PRESETS)) {
+                    console.log(`  ${name.padEnd(10)} ${info.description}`);
+                    console.log(`             Best for: ${info.example}`);
+                }
+                console.log('\n  flip       Two-image card flip (requires --back <path>)');
+                console.log('             Best for: cards, tiles, board game pieces');
+                return;
+            }
+            if (!opts.input || !opts.output) {
+                console.error('Error: --input and --output are required');
+                process.exit(1);
+            }
+            if (!existsSync(opts.input)) {
+                console.error(`Error: input file not found: ${opts.input}`);
+                process.exit(1);
+            }
+            const frames = parseInt(opts.frames, 10);
+            const columns = parseInt(opts.columns, 10);
+            if (frames < 2 || frames > 64) {
+                console.error('Error: --frames must be between 2 and 64');
+                process.exit(1);
+            }
+            const t0 = Date.now();
+            // Two-image flip mode: front shrinks → back expands
+            if (opts.back || opts.preset === 'flip') {
+                if (!opts.back) {
+                    console.error('Error: --preset flip requires --back <backside-image>');
+                    process.exit(1);
+                }
+                if (!existsSync(opts.back)) {
+                    console.error(`Error: back image not found: ${opts.back}`);
+                    process.exit(1);
+                }
+                await buildFlipSpriteSheet(opts.input, opts.back, frames, columns, opts.output);
+            }
+            else {
+                const preset = opts.preset;
+                if (!ANIMATE_PRESETS[preset]) {
+                    console.error(`Error: unknown preset '${preset}'. Available: ${Object.keys(ANIMATE_PRESETS).join(', ')}, flip`);
+                    process.exit(1);
+                }
+                await buildAnimationSpriteSheet(opts.input, preset, frames, columns, opts.output);
+            }
+            const elapsed = ((Date.now() - t0) / 1000).toFixed(2);
+            const outBuf = readFileSync(opts.output);
+            const meta = await sharp(opts.input).metadata();
+            console.log(`Animation generated: ${opts.output} (${sizeLabel(outBuf)}, ${elapsed}s)`);
+            console.log(`  Preset: ${opts.back ? 'flip' : opts.preset} | Frames: ${frames} | Layout: ${columns}×${Math.ceil(frames / columns)} | Frame size: ${meta.width}×${meta.height}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── list-vfx ────────────────────────────────────────────────────────────
+    img
+        .command('list-vfx')
+        .description('List bundled VFX sprite sheet presets')
+        .option('--json', 'Output as JSON')
+        .action((opts) => {
+        if (opts.json) {
+            console.log(JSON.stringify({ vfxPresets: VFX_PRESETS }, null, 2));
+            return;
+        }
+        console.log('\nBundled VFX Sprite Sheet Presets:\n');
+        for (const vfx of VFX_PRESETS) {
+            const filePath = join(__vfxDir, vfx.file);
+            const exists = existsSync(filePath);
+            const status = exists ? vfx.size : '(not bundled — use generate-image to create)';
+            console.log(`  ${vfx.name.padEnd(20)} ${status.padEnd(10)}  ${vfx.description}`);
+            console.log(`  ${''.padEnd(20)} ${vfx.frames} frames, ${vfx.columns} columns`);
+        }
+        console.log('\nUsage: playcraft image use-vfx --preset <name> --output assets/images/vfx/<name>.png');
+    });
+    // ─── use-vfx ─────────────────────────────────────────────────────────────
+    img
+        .command('use-vfx')
+        .description('Copy a bundled VFX preset to your project')
+        .requiredOption('--preset <name>', 'VFX preset name (see list-vfx)')
+        .requiredOption('--output <path>', 'Output file path')
+        .option('--tint <hex>', 'Optional color tint to apply (e.g. "#FF4400")')
+        .option('--scale <n>', 'Optional scale factor', '1.0')
+        .action(async (opts) => {
+        try {
+            const preset = VFX_PRESETS.find((v) => v.name === opts.preset);
+            if (!preset) {
+                console.error(`Error: VFX preset '${opts.preset}' not found. Run 'playcraft image list-vfx' to see available presets.`);
+                process.exit(1);
+            }
+            const srcPath = join(__vfxDir, preset.file);
+            if (!existsSync(srcPath)) {
+                console.log(`VFX sprite '${preset.name}' is not bundled yet. Generating via AI is recommended:`);
+                console.log(`\n  playcraft tools generate-image \\`);
+                console.log(`    --prompt "${preset.description} sprite sheet ${preset.frames} frames transparent background" \\`);
+                console.log(`    --output ${opts.output}`);
+                console.log(`\nThen use: playcraft image sprite-split --input ${opts.output} --auto-detect`);
+                process.exit(1);
+            }
+            const scale = parseFloat(opts.scale);
+            const outDir = dirname(resolve(opts.output));
+            if (!existsSync(outDir))
+                mkdirSync(outDir, { recursive: true });
+            if (!opts.tint && scale === 1.0) {
+                copyFileSync(srcPath, opts.output);
+                const sz = sizeLabel(readFileSync(opts.output));
+                console.log(`VFX copied: ${opts.output} (${sz})`);
+                console.log(`  ${preset.frames} frames, ${preset.columns} cols — ${preset.description}`);
+                return;
+            }
+            // Apply tint/scale via sharp
+            let pipeline = sharp(srcPath);
+            if (scale !== 1.0) {
+                const info = await sharp(srcPath).metadata();
+                const w = Math.round((info.width ?? 256) * scale);
+                const h = Math.round((info.height ?? 256) * scale);
+                pipeline = pipeline.resize(w, h, { fit: 'fill' });
+            }
+            if (opts.tint) {
+                const hex = opts.tint.replace('#', '');
+                const r = parseInt(hex.substring(0, 2), 16);
+                const g = parseInt(hex.substring(2, 4), 16);
+                const b = parseInt(hex.substring(4, 6), 16);
+                // Tint: multiply RGB channels by tint color
+                pipeline = pipeline.tint({ r, g, b });
+            }
+            const buf = await pipeline.png().toBuffer();
+            writeOutput(opts.output, buf);
+            console.log(`VFX copied: ${opts.output} (${sizeLabel(buf)})`);
+            if (opts.tint)
+                console.log(`  Tint: ${opts.tint}`);
+            if (scale !== 1.0)
+                console.log(`  Scale: ${scale}x`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── gen-tile-back ───────────────────────────────────────────────────────
+    img
+        .command('gen-tile-back')
+        .description('Programmatically generate a clean mahjong tile back (no AI needed)')
+        .option('--output <path>', 'Output PNG path', 'tile_back.png')
+        .option('--width <n>', 'Tile width in pixels', '512')
+        .option('--height <n>', 'Tile height in pixels', '640')
+        .option('--bg-color <hex>', 'Background color', '#1a5c2e')
+        .option('--border-color <hex>', 'Border color', '#ffffff')
+        .option('--style <name>', 'Style preset: classic | minimal | ornate', 'classic')
+        .action(async (opts) => {
+        try {
+            const W = parseInt(opts.width, 10);
+            const H = parseInt(opts.height, 10);
+            const bg = opts.bgColor;
+            const border = opts.borderColor;
+            const style = opts.style;
+            const buf = await generateTileBack(W, H, bg, border, style);
+            ensureDir(opts.output);
+            writeFileSync(opts.output, buf);
+            console.log(`Tile back generated: ${opts.output} (${sizeLabel(buf)}, ${W}×${H}, style: ${style})`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── decompose-layers ──────────────────────────────────────────────────────
+    img
+        .command('decompose-layers')
+        .description([
+        '302 Qwen-Image-Layered 整图语义分层：将合成图拆成 N 个 RGBA 图层',
+        '',
+        '  示例:',
+        '    playcraft image decompose-layers --input composite.png --output-dir ./layers',
+        '    playcraft image decompose-layers --input https://example.com/a.png --num-layers 4',
+        '',
+        '  需 Admin 配置 provider=302、modelKind=image 的 API Key；耗时约 1–2 分钟。',
+        '  本地文件需 storage 公网 URL，或 --input 使用 HTTPS 直链。',
+    ].join('\n'))
+        .requiredOption('--input <path>', '输入图片路径或 HTTPS URL')
+        .option('--output-dir <dir>', '输出目录', './decompose-layers-output')
+        .option('--num-layers <n>', '分层数量 2–10', cliParseInt, 4)
+        .option('--prompt <text>', '可选分层语义引导', '')
+        .option('--no-safety-checker', '关闭安全检测')
+        .option('--output-format <fmt>', '输出格式', 'png')
+        .action(async (opts) => {
+        try {
+            const payload = {
+                numLayers: opts.numLayers,
+                prompt: opts.prompt || '',
+                enableSafetyChecker: opts.safetyChecker !== false,
+                outputFormat: opts.outputFormat,
+            };
+            const input = opts.input;
+            const isUrl = input.startsWith('http://') || input.startsWith('https://');
+            if (isUrl) {
+                payload.imageUrl = input;
+                console.log(`Using image URL: ${input}`);
+            }
+            else {
+                assertInputWithinLimit(input);
+                payload.imageBase64 = readFileSync(input).toString('base64');
+                console.log(`Uploading local image: ${input}`);
+            }
+            console.log(`Decomposing into ${payload.numLayers} layer(s) via 302 Qwen-Image-Layered (may take 1–2 min)…`);
+            const t0 = Date.now();
+            const client = new AgentApiClient();
+            const result = await client.post('/image-layered/decompose', payload);
+            const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+            const outputDir = opts.outputDir;
+            mkdirSync(outputDir, { recursive: true });
+            for (const layer of result.layers) {
+                const ext = layer.mimeType.includes('png') ? 'png' : 'png';
+                const filename = `layer_${String(layer.index).padStart(2, '0')}.${ext}`;
+                writeFileSync(join(outputDir, filename), Buffer.from(layer.imageBase64, 'base64'));
+                const dim = layer.width && layer.height ? ` ${layer.width}×${layer.height}` : '';
+                console.log(`  ${filename}${dim}`);
+            }
+            const meta = {
+                source: input,
+                requestId: result.requestId,
+                numLayers: result.numLayers,
+                elapsed: `${elapsed}s`,
+                hasNsfwConcepts: result.hasNsfwConcepts,
+                layers: result.layers.map((l) => ({
+                    index: l.index,
+                    url: l.url,
+                    width: l.width,
+                    height: l.height,
+                    seed: l.seed,
+                })),
+            };
+            writeFileSync(join(outputDir, 'decompose-layers-meta.json'), JSON.stringify(meta, null, 2), 'utf-8');
+            console.log(`\nDone in ${elapsed}s — ${result.layers.length} layer(s) → ${outputDir}/`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── segment ─────────────────────────────────────────────────────────────
+    img
+        .command('segment')
+        .description([
+        'SAM3 图片语义分割（开放词汇）：文本或框 prompt → mask + 可选 RGBA 抠图',
+        '',
+        '  单 prompt 示例:',
+        '    playcraft image segment --input banner.png --text "icon" --output-dir ./out',
+        '',
+        '  多 prompt 批量:',
+        '    playcraft image segment --input banner.png \\',
+        '      --prompts \'[{"text":"icon"},{"text":"logo"}]\' --output-dir ./out',
+        '',
+        '  注意：服务首次冷启动约需 15s，后端会自动等待就绪后再执行分割。',
+    ].join('\n'))
+        .requiredOption('--input <path>', '输入图片路径（PNG / JPG）')
+        .option('--text <prompt>', '文本 prompt（如 icon、logo、orange button）')
+        .option('--prompts <json>', '批量 prompt JSON 数组，如 \'[{"text":"icon"},{"text":"logo"}]\'（与 --text 二选一）')
+        .option('--boxes <json>', '框 prompt JSON，如 \'[[x1,y1,x2,y2],...]\' （xyxy 绝对像素）')
+        .option('--box-labels <json>', '框标签 JSON，如 \'[1,0]\'（1=positive, 0=negative）')
+        .option('--threshold <n>', '实例得分阈值（默认 0.3）', parseFloat, 0.3)
+        .option('--mask-threshold <n>', 'mask 二值化阈值（默认 0.5）', parseFloat)
+        .option('--no-rgba', '不返回 RGBA 抠图（默认开启）')
+        .option('--output-dir <dir>', '输出目录（默认 ./segment-output）', './segment-output')
+        .action(async (opts) => {
+        try {
+            assertInputWithinLimit(opts.input);
+            const imageBase64 = readFileSync(opts.input).toString('base64');
+            // 构造 prompts 列表
+            let prompts;
+            if (opts.prompts) {
+                try {
+                    prompts = JSON.parse(opts.prompts);
+                    if (!Array.isArray(prompts) || prompts.length === 0) {
+                        throw new Error('prompts must be a non-empty array');
+                    }
+                }
+                catch (err) {
+                    console.error(`Error: --prompts is not valid JSON: ${err.message}`);
+                    process.exit(1);
+                }
+            }
+            else if (opts.text || opts.boxes) {
+                const singlePrompt = {};
+                if (opts.text)
+                    singlePrompt.text = opts.text;
+                if (opts.boxes) {
+                    try {
+                        singlePrompt.boxes = JSON.parse(opts.boxes);
+                    }
+                    catch {
+                        console.error('Error: --boxes is not valid JSON');
+                        process.exit(1);
+                    }
+                }
+                if (opts.boxLabels) {
+                    try {
+                        singlePrompt.boxLabels = JSON.parse(opts.boxLabels);
+                    }
+                    catch {
+                        console.error('Error: --box-labels is not valid JSON');
+                        process.exit(1);
+                    }
+                }
+                prompts = [singlePrompt];
+            }
+            else {
+                console.error('Error: provide --text, --boxes, or --prompts');
+                process.exit(1);
+            }
+            const payload = {
+                imageBase64,
+                prompts,
+                threshold: opts.threshold,
+                returnRgba: opts.rgba !== false,
+                ...(opts.maskThreshold !== undefined ? { maskThreshold: opts.maskThreshold } : {}),
+            };
+            console.log(`Segmenting ${opts.input} with ${prompts.length} prompt(s) (threshold=${opts.threshold})...`);
+            const t0 = Date.now();
+            const client = new AgentApiClient();
+            const result = await client.post('/sam3/segment', payload);
+            const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+            // 保存结果
+            const outputDir = opts.outputDir;
+            mkdirSync(outputDir, { recursive: true });
+            const meta = {
+                source: opts.input,
+                imageSize: result.imageSize,
+                elapsed: `${elapsed}s`,
+                prompts: prompts.length,
+                results: [],
+            };
+            let totalInstances = 0;
+            for (const promptResult of result.results) {
+                const label = promptResult.prompt.text
+                    ? promptResult.prompt.text.replace(/[^a-zA-Z0-9._-]+/g, '_').slice(0, 40)
+                    : `boxes_${promptResult.promptIndex}`;
+                const promptDir = join(outputDir, `prompt_${promptResult.promptIndex}_${label}`);
+                mkdirSync(promptDir, { recursive: true });
+                const instanceSummaries = [];
+                for (let i = 0; i < promptResult.instances.length; i++) {
+                    const inst = promptResult.instances[i];
+                    const prefix = String(i).padStart(2, '0');
+                    writeFileSync(join(promptDir, `${prefix}_mask.png`), Buffer.from(inst.maskBase64, 'base64'));
+                    if (inst.rgbaBase64) {
+                        writeFileSync(join(promptDir, `${prefix}_rgba.png`), Buffer.from(inst.rgbaBase64, 'base64'));
+                    }
+                    instanceSummaries.push({
+                        index: i,
+                        score: inst.score.toFixed(3),
+                        bbox: inst.bbox,
+                        hasMask: true,
+                        hasRgba: !!inst.rgbaBase64,
+                    });
+                }
+                totalInstances += promptResult.count;
+                meta.results.push({
+                    promptIndex: promptResult.promptIndex,
+                    prompt: promptResult.prompt,
+                    count: promptResult.count,
+                    instances: instanceSummaries,
+                });
+                console.log(`  prompt[${promptResult.promptIndex}] "${promptResult.prompt.text ?? '(boxes)'}" → ${promptResult.count} instance(s) → ${promptDir}`);
+            }
+            writeFileSync(join(outputDir, 'segment-meta.json'), JSON.stringify(meta, null, 2), 'utf-8');
+            console.log(`\nDone in ${elapsed}s — ${totalInstances} total instance(s) across ${result.results.length} prompt(s)`);
+            console.log(`Output: ${outputDir}/  (segment-meta.json + per-prompt subdirs)`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+}
+// ─── Tile back SVG generator ─────────────────────────────────────────────────
+async function generateTileBack(W, H, bg, borderColor, style) {
+    const r = Math.round(W * 0.08); // corner radius
+    const ob = Math.round(W * 0.04); // outer border inset
+    const sw1 = Math.round(W * 0.025); // outer border stroke width
+    const ib = ob + sw1 + Math.round(W * 0.025); // inner border inset
+    const sw2 = Math.round(W * 0.012); // inner border stroke width
+    // Corner diamond ornament helper
+    const diamond = (cx, cy, size, color) => `<polygon points="${cx},${cy - size} ${cx + size},${cy} ${cx},${cy + size} ${cx - size},${cy}" fill="${color}"/>`;
+    // Corner flower (4 circles around a center) for ornate style
+    const flower = (cx, cy, size, color) => {
+        const r2 = size * 0.45;
+        const off = size * 0.55;
+        return [
+            `<circle cx="${cx}" cy="${cy}" r="${r2 * 0.7}" fill="${color}"/>`,
+            `<circle cx="${cx - off}" cy="${cy}" r="${r2}" fill="${color}"/>`,
+            `<circle cx="${cx + off}" cy="${cy}" r="${r2}" fill="${color}"/>`,
+            `<circle cx="${cx}" cy="${cy - off}" r="${r2}" fill="${color}"/>`,
+            `<circle cx="${cx}" cy="${cy + off}" r="${r2}" fill="${color}"/>`,
+        ].join('');
+    };
+    const ornSize = Math.round(W * 0.055);
+    const ornInset = ib + sw2 + Math.round(W * 0.06);
+    const cornerPositions = [
+        [ornInset, ornInset],
+        [W - ornInset, ornInset],
+        [ornInset, H - ornInset],
+        [W - ornInset, H - ornInset],
+    ];
+    const corners = cornerPositions
+        .map(([cx, cy]) => style === 'ornate'
+        ? flower(cx, cy, ornSize, borderColor)
+        : diamond(cx, cy, ornSize, borderColor))
+        .join('');
+    // Center pattern
+    const cx = W / 2;
+    const cy = H / 2;
+    const centerPattern = (() => {
+        if (style === 'minimal')
+            return '';
+        if (style === 'ornate') {
+            const big = Math.round(W * 0.12);
+            return flower(cx, cy, big, borderColor);
+        }
+        // classic: nested diamonds
+        const s1 = Math.round(W * 0.14);
+        const s2 = Math.round(W * 0.09);
+        return [
+            diamond(cx, cy, s1, borderColor),
+            diamond(cx, cy, s2, bg),
+            diamond(cx, cy, s2 * 0.5, borderColor),
+        ].join('');
+    })();
+    // Side mid ornaments (classic + ornate)
+    const sideOrnaments = style === 'minimal' ? '' : [
+        // top mid
+        diamond(cx, ib + sw2 + ornSize * 0.8, ornSize * 0.6, borderColor),
+        // bottom mid
+        diamond(cx, H - ib - sw2 - ornSize * 0.8, ornSize * 0.6, borderColor),
+        // left mid
+        diamond(ib + sw2 + ornSize * 0.8, cy, ornSize * 0.6, borderColor),
+        // right mid
+        diamond(W - ib - sw2 - ornSize * 0.8, cy, ornSize * 0.6, borderColor),
+    ].join('');
+    const svg = `<svg width="${W}" height="${H}" xmlns="http://www.w3.org/2000/svg">
+  <!-- background -->
+  <rect width="${W}" height="${H}" fill="${bg}" rx="${r}" ry="${r}"/>
+  <!-- outer border -->
+  <rect x="${ob}" y="${ob}" width="${W - 2 * ob}" height="${H - 2 * ob}"
+    fill="none" stroke="${borderColor}" stroke-width="${sw1}" rx="${r - ob}" ry="${r - ob}"/>
+  <!-- inner border -->
+  <rect x="${ib}" y="${ib}" width="${W - 2 * ib}" height="${H - 2 * ib}"
+    fill="none" stroke="${borderColor}" stroke-width="${sw2}" rx="${Math.max(2, r - ib)}" ry="${Math.max(2, r - ib)}"/>
+  <!-- corner ornaments -->
+  ${corners}
+  <!-- side ornaments -->
+  ${sideOrnaments}
+  <!-- center pattern -->
+  ${centerPattern}
+</svg>`;
+    return sharp(Buffer.from(svg)).png().toBuffer();
 }