@playcraft/cli 0.1.50-beta → 0.1.52

package/dist/utils/image-asset-context.js

@@ -0,0 +1,228 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import JSON5 from 'json5';
+import sharp from 'sharp';
+import { extractAssetFields, getByPath, resolveAiImageTargetConstraints, resolveImageBackgroundRequirement, THEME_SCHEMA_PATH, themeDataPath, } from '@playcraft/common/prefab';
+function isWithinDirectory(root, file) {
+    const relative = path.relative(root, file);
+    return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/** Resolve existing ancestors so a new workspace need not have been created yet. */
+function realPathWithParents(file) {
+    let ancestor = file;
+    while (!existsSync(ancestor)) {
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor)
+            throw new Error(`Image path has no existing ancestor: ${file}`);
+        ancestor = parent;
+    }
+    return path.resolve(realpathSync(ancestor), path.relative(ancestor, file));
+}
+/** Resolve aliases and existing parent symlinks, including for a new output file. */
+function canonicalProjectPath(root, input) {
+    const mapped = input.startsWith('/project/') ? input.slice('/project/'.length) : input;
+    const file = path.resolve(root, mapped);
+    if (!isWithinDirectory(root, file)) {
+        throw new Error(`Image asset path is outside the project: ${input}`);
+    }
+    const real = realPathWithParents(file);
+    if (!isWithinDirectory(realPathWithParents(root), real)) {
+        throw new Error(`Image asset symlink is outside the project: ${input}`);
+    }
+    return real;
+}
+/** Check every extension a writer may choose before sending a generation request. */
+export function assertImageAssetOutputPaths(context, outputPaths, projectDir = process.cwd(), allowedOutputRoots = []) {
+    if (!context.requiresSeparateOutput)
+        return;
+    const root = path.resolve(projectDir);
+    const target = canonicalProjectPath(root, context.targetAssetPath);
+    const targetStat = statSync(target);
+    const outputRoots = [root, ...allowedOutputRoots.map(outputRoot => path.resolve(root, outputRoot))];
+    for (const output of outputPaths) {
+        const mapped = output.startsWith('/project/') ? output.slice('/project/'.length) : output;
+        const { dir, name } = path.parse(mapped);
+        // The response encoding can change the requested extension.
+        const candidates = [mapped, ...['.png', '.webp', '.jpg', '.gif', '.bmp'].map(ext => path.join(dir, `${name}${ext}`))];
+        for (const candidate of candidates) {
+            const candidatePath = path.resolve(root, candidate);
+            const outputRoot = outputRoots.find(allowed => isWithinDirectory(allowed, candidatePath));
+            if (!outputRoot)
+                throw new Error(`Image output path is outside the project and allowed output roots: ${output}`);
+            const file = canonicalProjectPath(outputRoot, candidatePath);
+            const fileStat = existsSync(file) ? statSync(file) : undefined;
+            if (!path.relative(target, file) || (targetStat.ino !== 0 && fileStat?.ino === targetStat.ino && fileStat.dev === targetStat.dev)) {
+                throw new Error(`Cannot overwrite shared image asset ${context.targetAssetPath}: other fields have different requirements. Use a separate outputPath, then explicitly update the selected field reference; no shared asset was changed.`);
+            }
+        }
+    }
+}
+/** Resolve only real files in this project, including legacy /project aliases. */
+function projectFile(root, input) {
+    const mapped = input.startsWith('/project/') ? input.slice('/project/'.length) : input;
+    const file = path.resolve(root, mapped);
+    if (!isWithinDirectory(root, file))
+        throw new Error(`Image asset path is outside the project: ${input}`);
+    const real = realpathSync(file);
+    if (!isWithinDirectory(realpathSync(root), real))
+        throw new Error(`Image asset symlink is outside the project: ${input}`);
+    return file;
+}
+/** Read the same per-field constraints used by the asset image dialog. */
+export async function readImageAssetContext(assetPath, projectDir = process.cwd(), options = {}) {
+    const targetFieldPath = options.targetFieldPath;
+    if (targetFieldPath !== undefined && (!Array.isArray(targetFieldPath)
+        || !targetFieldPath.length || targetFieldPath.some(key => typeof key !== 'string' || !key.length))) {
+        throw new Error('targetFieldPath must be a non-empty array of non-empty field names.');
+    }
+    const root = path.resolve(projectDir);
+    const target = projectFile(root, assetPath);
+    const realTarget = realpathSync(target);
+    const targetStat = statSync(target);
+    const relativeTarget = path.relative(root, target).replace(/\\/g, '/');
+    const themeMatch = relativeTarget.match(/^src\/theme\/([^/]+)\/assets\//);
+    let fields = [];
+    const schemaFile = path.join(root, THEME_SCHEMA_PATH);
+    if (themeMatch && existsSync(schemaFile)) {
+        const schema = JSON5.parse(readFileSync(projectFile(root, THEME_SCHEMA_PATH), 'utf8'));
+        const dataPath = themeDataPath(themeMatch[1]);
+        const data = existsSync(path.join(root, dataPath))
+            ? JSON5.parse(readFileSync(projectFile(root, dataPath), 'utf8')) : {};
+        const themeRoot = path.dirname(path.join(root, dataPath));
+        const matches = extractAssetFields(schema, data).filter(candidate => {
+            let configured = getByPath(data, candidate.path);
+            if (configured === undefined && ['gameplay', 'gamePlay'].includes(candidate.path[0])) {
+                configured = getByPath(data, [candidate.path[0] === 'gameplay' ? 'gamePlay' : 'gameplay', ...candidate.path.slice(1)]);
+            }
+            const value = typeof configured === 'string' ? configured : candidate.schema.default;
+            if (typeof value !== 'string' || /^https?:\/\//i.test(value))
+                return false;
+            const configuredPath = value.startsWith('/project/') ? path.resolve(root, value.slice('/project/'.length))
+                : path.resolve(themeRoot, value);
+            if (configuredPath === target)
+                return true;
+            try {
+                const candidateFile = projectFile(root, configuredPath);
+                if (!path.relative(realTarget, realpathSync(candidateFile)))
+                    return true;
+                const candidateStat = statSync(candidateFile);
+                return targetStat.ino !== 0 && candidateStat.ino === targetStat.ino && candidateStat.dev === targetStat.dev;
+            }
+            catch {
+                // Other fields may reference missing files or paths outside this project.
+                return false;
+            }
+        });
+        if (!matches.length)
+            throw new Error(`No image schema field matches ${relativeTarget}; check theme.data.json5 before generating.`);
+        fields = matches;
+        if (targetFieldPath && !fields.some(candidate => candidate.path.length === targetFieldPath.length
+            && candidate.path.every((key, index) => key === targetFieldPath[index]))) {
+            throw new Error(`targetFieldPath ${JSON.stringify(targetFieldPath)} does not reference ${relativeTarget}. Matching fields: ${matches.map(candidate => JSON.stringify(candidate.path)).join(', ')}.`);
+        }
+    }
+    else if (targetFieldPath) {
+        throw new Error('targetFieldPath requires an asset with a matching theme schema.');
+    }
+    const targetMeta = await sharp(target).metadata();
+    let targetHasTransparency;
+    const contextForField = async (field) => {
+        const xp = field?.schema.xplatform;
+        const ext = xp?.ext;
+        // Schema references follow the dialog's root/theme conventions; explicit tool paths do not change.
+        const schemaReferences = Array.isArray(ext?.reference_image)
+            ? ext.reference_image.filter(ref => typeof ref === 'string' && ref.trim()).map(ref => {
+                const raw = ref.trim().replace(/\\/g, '/');
+                const normalized = raw.replace(/^\.\/+/, '').replace(/^\/+/, '').replace(/\/{2,}/g, '/');
+                if (/^\/?(?:assets|src|public)\//.test(raw) || normalized.startsWith('src/'))
+                    return normalized;
+                if (!themeMatch || path.isAbsolute(raw) || /^https?:\/\//i.test(raw))
+                    return raw;
+                return path.posix.join('src/theme', themeMatch[1], normalized);
+            }) : [];
+        const references = options.referenceImagePaths?.length ? options.referenceImagePaths
+            : options.useTargetReference === false ? [] : schemaReferences.length ? schemaReferences : [relativeTarget];
+        const referenceImagePaths = references.map(ref => /^https?:\/\//i.test(ref) ? ref
+            : path.relative(realpathSync(root), canonicalProjectPath(root, ref)).replace(/\\/g, '/'));
+        const hasSchemaBackground = typeof ext?.remove_background === 'boolean';
+        if (!hasSchemaBackground && targetHasTransparency === undefined) {
+            targetHasTransparency = !!targetMeta.hasAlpha && (await sharp(target).stats()).channels.at(-1).min < 250;
+        }
+        const removeBackground = resolveImageBackgroundRequirement({
+            prompt: options.prompt ?? '',
+            schemaRemoveBackground: hasSchemaBackground ? ext.remove_background : undefined,
+            removeBackground: options.removeBackground,
+            fallbackRemoveBackground: targetHasTransparency ?? false,
+        });
+        const delivery = resolveAiImageTargetConstraints({
+            schemaResolution: ext?.resolution,
+            schemaMimeType: xp?.mime_type,
+            schemaFitMode: xp?.fit_mode ?? ext?.fit_mode,
+            schemaRemoveBackground: removeBackground,
+            schemaPaddingColor: ext?.padding_color,
+            assetPath: relativeTarget,
+            referenceWidth: targetMeta.width,
+            referenceHeight: targetMeta.height,
+            referenceFormat: targetMeta.format,
+        });
+        if (!['png', 'webp', 'jpeg'].includes(delivery.format))
+            throw new Error('Unsupported image delivery format; use a dedicated animation or vector workflow.');
+        return {
+            targetAssetPath: relativeTarget,
+            fieldPath: field?.path,
+            referenceImagePaths,
+            width: delivery.width, height: delivery.height,
+            aspectRatio: typeof ext?.ratio === 'string' ? ext.ratio : `${delivery.width}:${delivery.height}`,
+            outputFormat: (removeBackground && delivery.format === 'jpeg' && !delivery.fromSchemaMimeType
+                ? 'png' : delivery.format),
+            outputFormatFromSchema: delivery.fromSchemaMimeType,
+            fitMode: delivery.fitMode, removeBackground: delivery.removeBackground, paddingColor: delivery.paddingColor,
+            removeBackgroundFromSchema: hasSchemaBackground,
+            imageModelRef: typeof ext?.imageModelRef === 'string' ? ext.imageModelRef : undefined,
+        };
+    };
+    const contexts = [];
+    let unresolvedSharedField = false;
+    for (const field of fields.length ? fields : [undefined]) {
+        try {
+            contexts.push(await contextForField(field));
+        }
+        catch (error) {
+            const selected = field?.path.length === targetFieldPath?.length
+                && field?.path.every((key, index) => key === targetFieldPath?.[index]);
+            if (!targetFieldPath || selected)
+                throw error;
+            // Invalid sibling requirements still protect the original shared file.
+            unresolvedSharedField = true;
+        }
+    }
+    const context = targetFieldPath ? contexts.find(candidate => candidate.fieldPath?.length === targetFieldPath.length
+        && candidate.fieldPath.every((key, index) => key === targetFieldPath[index])) : contexts[0];
+    const deliveryKey = ({ fieldPath: _fieldPath, outputFormatFromSchema: _formatSource, removeBackgroundFromSchema: _backgroundSource, aspectRatio, ...delivery }) => {
+        const ratio = aspectRatio.match(/^\s*(\d+(?:\.\d+)?)\s*:\s*(\d+(?:\.\d+)?)\s*$/);
+        return JSON.stringify({ ...delivery, aspectRatio: ratio && Number(ratio[2]) > 0 ? Number(ratio[1]) / Number(ratio[2]) : aspectRatio });
+    };
+    const conflicting = unresolvedSharedField || contexts.some(candidate => deliveryKey(candidate) !== deliveryKey(context));
+    if (conflicting && !targetFieldPath) {
+        throw new Error(`Multiple image fields use ${relativeTarget} with different references or delivery constraints. Set targetFieldPath (or --target-field-path) to one of: ${fields.map(field => JSON.stringify(field.path)).join(', ')}.`);
+    }
+    if (targetFieldPath) {
+        // A separate output retains exactly the selected field's requirements.
+        if (conflicting || contexts.some(candidate => (candidate.outputFormatFromSchema && !context.outputFormatFromSchema)
+            || (candidate.removeBackgroundFromSchema && !context.removeBackgroundFromSchema)))
+            context.requiresSeparateOutput = true;
+    }
+    else {
+        context.outputFormatFromSchema = contexts.some(candidate => candidate.outputFormatFromSchema);
+        context.removeBackgroundFromSchema = contexts.some(candidate => candidate.removeBackgroundFromSchema);
+    }
+    assertImageAssetOutputPaths(context, options.outputPaths ?? [], root, options.allowedOutputRoots);
+    if (context.referenceImagePaths.length > 8)
+        throw new Error('At most 8 reference images are allowed.');
+    for (const ref of context.referenceImagePaths) {
+        if (/^https?:\/\//i.test(ref))
+            throw new Error('Download the schema reference into the project before generating.');
+        await sharp(projectFile(root, ref)).metadata();
+    }
+    return context;
+}

package/dist/utils/playcraft-http-client.js

@@ -1,7 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
-import { pendingAccountActivationError } from '../auth/account-activation.js';
 export class PlayCraftApiError extends Error {
     code;
     status;
@@ -96,20 +95,19 @@ export class PlayCraftHttpClient {
                 }
                 if (!response.ok) {
                     const error = payload?.error;
-                    const pending = pendingAccountActivationError(response.status, payload);
-                    const code = pending?.code ?? (typeof error?.code === 'string' ? error.code : statusCode(response.status));
-                    const message = pending?.message ?? (typeof error?.message === 'string'
+                    const code = typeof error?.code === 'string' ? error.code : statusCode(response.status);
+                    const message = typeof error?.message === 'string'
                         ? error.message
                         : typeof payload?.message === 'string'
                             ? payload.message
                             : typeof payload === 'string'
                                 ? payload
-                                : response.statusText || 'PlayCraft request failed');
+                                : response.statusText || 'PlayCraft request failed';
                     throw new PlayCraftApiError({
                         code,
                         message,
                         status: response.status,
-                        details: pending ? { loginCommand: 'playcraft login --activate' } : error?.details ?? payload,
+                        details: error?.details ?? payload,
                         retryable: response.status >= 500,
                     });
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.50-beta",
+  "version": "0.1.52",
   "private": false,
   "type": "module",
   "engines": {
@@ -14,18 +14,16 @@
     "dist",
     "templates",
     "project-template",
-    "project-template-v2",
     "engine-packs",
     "project-templates",
     "REMIX.md",
-    "SKILLS_REGISTRY.md",
     "README.md"
   ],
   "scripts": {
     "dev": "tsc -w",
-    "build": "node scripts/generate-video-skills.mjs && tsc",
+    "build": "tsc",
     "start": "node dist/index.js",
-    "test": "pnpm build && vitest run",
+    "test": "vitest run",
     "test:agent": "node scripts/run-agent-tests.mjs --list",
     "test:agent:designer": "node scripts/run-agent-tests.mjs game-designer",
     "test:agent:developer": "node scripts/run-agent-tests.mjs developer",
@@ -37,10 +35,6 @@
     "test:agent:gate": "node scripts/run-agent-tests.mjs gate",
     "test:agent:vlm": "node scripts/run-agent-tests.mjs vlm",
     "test:agent:stop": "node scripts/run-agent-tests.mjs stop",
-    "generate:platform-skills": "node scripts/generate-platform-skills.mjs",
-    "verify:platform-skills": "node scripts/generate-platform-skills.mjs --check",
-    "generate:video-skills": "node scripts/generate-video-skills.mjs",
-    "verify:video-skills": "node scripts/generate-video-skills.mjs --check && node --test scripts/generate-video-skills.test.mjs",
     "verify:agent-stop": "node scripts/verify-agent-stop.mjs",
     "verify-sprite-overlay": "node scripts/verify-sprite-overlay.mjs",
     "link": "node scripts/bump-local.js && pnpm build && npm link",
@@ -51,9 +45,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.50-beta",
-    "@playcraft/common": "0.1.50-beta",
-    "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
+    "@playcraft/build": "^0.1.52",
+    "@playcraft/common": "^0.1.52",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",
@@ -69,10 +62,8 @@
     "json5": "^2.2.3",
     "latest-version": "^7.0.0",
     "music-metadata": "^11.12.3",
-    "node-pty": "1.0.0",
     "ora": "^8.2.0",
     "picocolors": "^1.1.1",
-    "playwright-core": "1.52.0",
     "sharp": "^0.34.5",
     "update-notifier": "^7.3.1",
     "ws": "^8.19.0",
@@ -88,7 +79,6 @@
     "@types/sharp": "^0.32.0",
     "@types/update-notifier": "^6.0.8",
     "@types/ws": "^8.18.1",
-    "esbuild": "^0.28.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   }

package/project-template/.claude/agents/refs/ta-image-generation-detail.md

@@ -1,24 +1,25 @@
-# TA 图片生成进阶参考
+# TA (Technical Artist, 技术美术师) 图片生成进阶参考
 
 > 本文件供 TA/Designer 在需要精灵图直出、Edit 模型变体、错误恢复等进阶场景时按需查阅。核心决策逻辑见 `playcraft-image-generation` skill。
 
 ---
 
-## 1. gpt-image-2 精灵图直出 + 批量出图策略
+## 1. 精灵图直出 + 批量出图策略
 
 ### 策略一：直接生成整张精灵图（最高效）
 
-**gpt-image-2 可以一次 API 调用就生成一张包含多个元素的网格图**，后续用 `sprite-split` 切分。避免逐个生成的低效循环。
+**一次 API (Application Programming Interface, 应用程序编程接口) 调用生成包含多个元素的网格图**，后续用 `sprite-split` 切分。使用主文选定的模型，不因批量生成自动改用旧模型。
 
-> gpt-image-2 本身就慢（单图 7-8 分钟正常，精灵图 90-150 秒正常）。**调用 gpt-image-2 时不要设 `--timeout`**，让它自然完成。"慢"不是卡死，不要中途 Ctrl+C 换模型。真正的失败是 `API 500` 或 `fetch failed`，那才需要切换 provider。
+> 保留命令行默认等待时间。等待本身不表示请求失败；本地超时也不表示后端已停止，确认原请求状态后再决定下一步，避免重复计费。
 
 #### 先判断：元素需要透明背景吗？
 
 ```
 需要透明背景（独立元素：角色、车、道具、图标）？
-├─ YES → 绿幕策略：prompt 所有格子加 "solid bright green #00FF00 background"
-│          切分后对每帧跑 remove-background --tolerance 25
-└─ NO  → 白底策略：prompt 加 "white background"（卡牌/棋盘/UI 面板适用）
+├─ 常规透明交付 → --remove-background；按主文第 2 节准备源图背景
+│                切分后保留透明通道，不重复去背
+├─ 不透明牌面/场景 → --no-remove-background；白色牌面属于主体
+└─ 明确选择独立色幕 → 仅限主文第 3 节；关闭整板自动去背，切分后逐格去背
 ```
 
 #### 白底示例（卡牌，不需要去背景）
@@ -28,8 +29,8 @@ playcraft tools generate-image \
   --prompt "Sprite sheet grid, 4 columns × 2 rows. Each cell: one playing card face, flat 2D, white card face, uniform size. Row 1: Ace of Spades, 2 of Spades, 3 of Spades, 4 of Spades. Row 2: 5 of Spades, 6 of Spades, 7 of Spades, 8 of Spades. Grid layout, equal cell size, no border between cells." \
   --output assets/gen/cards_sheet.png \
   --aspect-ratio 3:2 \
-  --image-model iegg-litellm/gpt-image-2
-  # gpt-image-2 不设 --timeout，精灵图 90-150s 正常，等待即可
+  --image-model iegg-litellm/gpt-image-2.5-sunburst \
+  --no-remove-background
 
 # 查尺寸再切分（frame-width=总宽/列数, frame-height=总高/行数）
 playcraft image info --input assets/gen/cards_sheet.png
@@ -40,36 +41,51 @@ playcraft image sprite-split \
   --frame-width <总宽/4> --frame-height <总高/2>
 ```
 
-#### 绿幕示例（独立元素，需要透明背景）
+#### 自动透明示例（独立元素）
 
 ```bash
-# Step 1：生成绿幕精灵图
+# Step 1：Image 2.5 由后端组装源图背景并验收透明交付
 playcraft tools generate-image \
-  --prompt "Sprite sheet grid, 3 columns × 1 row. Each cell: one car, flat 2D vector, bold outline, centered, isolated on solid bright green #00FF00 background. [Row1,Col1]: red sports car front view; [Row1,Col2]: blue SUV front view; [Row1,Col3]: yellow taxi front view. Grid layout, equal cell size, no border between cells." \
+  --prompt "Sprite sheet grid, 3 columns × 1 row. Each cell: one car, flat 2D vector, bold outline, centered, isolated subject. [Row1,Col1]: red sports car front view; [Row1,Col2]: blue SUV front view; [Row1,Col3]: yellow taxi front view. Grid layout, equal cell size, no border between cells." \
   --output assets/gen/cars_sheet.png \
   --aspect-ratio 3:2 \
-  --image-model iegg-litellm/gpt-image-2
-  # gpt-image-2 不设 --timeout，精灵图 90-150s 正常，等待即可
+  --image-model iegg-litellm/gpt-image-2.5-sunburst \
+  --remove-background
 
 # Step 2：切分
 playcraft image info --input assets/gen/cars_sheet.png
 playcraft image sprite-split \
   --input assets/gen/cars_sheet.png \
-  --output-dir assets/gen/cars-split/ \
+  --output-dir assets/images/cars/ \
   --rows 1 --columns 3 \
   --frame-width <总宽/3> --frame-height <总高>
 
-# Step 3：逐帧去背景（绿幕用 tolerance 25）
-for f in assets/gen/cars-split/frame_*.png; do
-  name=$(basename "$f")
-  playcraft image remove-background \
-    --input "$f" \
-    --output "assets/images/cars/$name" \
-    --tolerance 25
-done
+# Step 3：验证每格主体完整及深浅背景上的透明边缘，不重复去背
+```
+
+明确选用其他模型时，同样传 `--remove-background`，但首次 prompt 需追加单一 `on a uniform solid pure white background for subsequent background removal`；后端不会像 Image 2.5 那样自动补源图背景。
+
+#### 独立色幕示例（仅限明确选择的制作流程）
+
+先按主文第 3 节选与主体不冲突的色幕。参考图和交付规格来自目标字段时先读取，再显式传给中间图请求，省略 `--target-asset`，避免字段透明要求覆盖保留色幕的开关。
+
+```bash
+# 已明确锁定不支持原生透明的模型与品红色幕；常规流程不使用此分支
+playcraft tools generate-image \
+  --prompt "Sprite sheet grid, 3 columns × 1 row. [Row1,Col1]: red sports car; [Row1,Col2]: blue SUV; [Row1,Col3]: yellow taxi. Each car isolated, centered on a uniform solid #FF00FF background, equal cell size, no borders, no shadows." \
+  --output assets/gen/cars_chroma.png \
+  --aspect-ratio 3:2 \
+  --image-model mulerouter/gpt-image-2 \
+  --no-remove-background
+
+# 读取实际尺寸并 sprite-split 后，逐格去背；品红使用 tolerance 20
+playcraft image remove-background \
+  --input assets/gen/cars-split/frame_r0_c0.png \
+  --output assets/images/cars/red_car.png \
+  --tolerance 20
 ```
 
-**Provider 选择**：iegg-litellm/gpt-image-2 质量最高；google/gemini-3.1-flash-image-preview 最稳定且参考图正常工作。
+其他格同样处理，并分别验收。自动透明图使用 `backgroundMode='automatic'`；独立色幕脚本设 `backgroundMode='chroma'`、`chromaColor` 和 `chromaTolerance`，不要把两种流程混用。
 
 **Prompt 关键词**：`sprite sheet grid, N columns × M rows, grid layout, equal cell size, uniform size`
 
@@ -107,76 +123,20 @@ playcraft tools generate-image \
 // 52 张牌 → 4 批 × 13 = 4 张精灵图，再统一切分
 const BATCHES = [
   {
-    name: "sheet_spades",
-    cards: [
-      "A♠",
-      "2♠",
-      "3♠",
-      "4♠",
-      "5♠",
-      "6♠",
-      "7♠",
-      "8♠",
-      "9♠",
-      "10♠",
-      "J♠",
-      "Q♠",
-      "K♠",
-    ],
+    name: 'sheet_spades',
+    cards: ['A♠', '2♠', '3♠', '4♠', '5♠', '6♠', '7♠', '8♠', '9♠', '10♠', 'J♠', 'Q♠', 'K♠'],
   },
   {
-    name: "sheet_hearts",
-    cards: [
-      "A♥",
-      "2♥",
-      "3♥",
-      "4♥",
-      "5♥",
-      "6♥",
-      "7♥",
-      "8♥",
-      "9♥",
-      "10♥",
-      "J♥",
-      "Q♥",
-      "K♥",
-    ],
+    name: 'sheet_hearts',
+    cards: ['A♥', '2♥', '3♥', '4♥', '5♥', '6♥', '7♥', '8♥', '9♥', '10♥', 'J♥', 'Q♥', 'K♥'],
   },
   {
-    name: "sheet_diamonds",
-    cards: [
-      "A♦",
-      "2♦",
-      "3♦",
-      "4♦",
-      "5♦",
-      "6♦",
-      "7♦",
-      "8♦",
-      "9♦",
-      "10♦",
-      "J♦",
-      "Q♦",
-      "K♦",
-    ],
+    name: 'sheet_diamonds',
+    cards: ['A♦', '2♦', '3♦', '4♦', '5♦', '6♦', '7♦', '8♦', '9♦', '10♦', 'J♦', 'Q♦', 'K♦'],
   },
   {
-    name: "sheet_clubs",
-    cards: [
-      "A♣",
-      "2♣",
-      "3♣",
-      "4♣",
-      "5♣",
-      "6♣",
-      "7♣",
-      "8♣",
-      "9♣",
-      "10♣",
-      "J♣",
-      "Q♣",
-      "K♣",
-    ],
+    name: 'sheet_clubs',
+    cards: ['A♣', '2♣', '3♣', '4♣', '5♣', '6♣', '7♣', '8♣', '9♣', '10♣', 'J♣', 'Q♣', 'K♣'],
   },
 ];
 // 每批生成一张 13×1 精灵图，再用 sprite-split 切分
@@ -229,34 +189,16 @@ node ta-workspace/scripts/gen-<name>-variants.mjs
 
 ## 3. 错误恢复策略
 
-> **gpt-image-2 超时规则（最重要）**：gpt-image-2 慢是设计如此，不是故障。单图 7-8 分钟、精灵图 90-150 秒均属正常范围。**调用 gpt-image-2 时永远不要设 `--timeout`**，也不要因为"等了很久"就 Ctrl+C 中断。只有收到 `API 500` 或 `fetch failed` 才切换 provider。
-
-| 错误现象               | 模型                                        | 原因                                          | 立即行动                                                                                                          |
-| ---------------------- | ------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `API 500`              | 任意                                        | 该 provider 节点不可用                        | **立即换同模型的另一个 provider**（如 `iegg-litellm/gpt-image-2` → `mulerouter/gpt-image-2` → `302/gpt-image-2`） |
-| `fetch failed`         | 任意                                        | provider 网络不通                             | 换另一个 provider                                                                                                 |
-| 等待 7-8 分钟还未返回  | **gpt-image-2**                             | 正常现象，模型本身就慢                        | **继续等待，不要中断**；若超过 15 分钟仍无响应则换同模型另一 provider                                             |
-| 等待 >120s 无响应      | **非 gpt-image-2**（gemini/nano-banana 等） | 请求卡死                                      | Ctrl+C 中止，换另一个 provider 或换模型；可加 `--timeout 60` 防止下次卡住                                         |
-| 精灵图等待 90-150s     | **gpt-image-2**                             | 正常现象                                      | 继续等待；**不要设 `--timeout`**                                                                                  |
-| `--count N` 触发限流   | 任意                                        | 并发提交多任务超过 provider 限制              | 降低 count 或改用精灵图直出策略                                                                                   |
-| `reference-image` 报错 | 任意                                        | 模型 CAPABILITY 为 `text→image`，不支持参考图 | 换 CAPABILITY 为 `text+image` 或 `image→image` 的模型                                                             |
-| 风格偏差大             | 任意                                        | Prompt 不够具体                               | 参考 prompt-cookbook.md 对应素材类型模板                                                                          |
-| 质量不达标             | 非 gpt-image-2                              | 模型能力不够                                  | 换 gpt-image-2（最高质量）+ 参考 prompt-cookbook 质量修饰词                                                       |
-
-### 模型回退顺序
+后端统一限制模型、供应商与重生成的总尝试次数；命令行默认不额外重试。普通素材默认模型选择、原生透明优先与剩余一次干净底图重生成均以主文第 2 节为准，脚本不再叠加模型回退链。
 
-```
-gpt-image-2（最高质量，三个 provider 互为回退）：
-1. iegg-litellm/gpt-image-2
-2. mulerouter/gpt-image-2
-3. 302/gpt-image-2
-
-稳定回退（非 gpt-image-2）：
-4. google/gemini-3.1-flash-image-preview
-5. mulerouter/nano-banana-2
-```
-
-**同一个 provider 最多重试 1 次**，失败立即切换到同模型的另一个 provider，不要等待。
+| 错误现象               | 立即行动                                                                                        |
+| ---------------------- | ----------------------------------------------------------------------------------------------- |
+| 仍在等待 / 本地超时    | 确认原请求状态，等待或核实后端已结束；不要并发重发，也不要仅因等待改模型。                      |
+| 上游错误 / 网络失败    | 记录请求编号、实际 provider/model 与尝试次数，报告后端诊断；用户或流程锁定的模型不静默更换。    |
+| 透明源图或最终验收失败 | 报告失败阶段并停止；不把棋盘格、补边或未完成的去背当成功，不自行改用色幕。                      |
+| 去背处理失败           | 报告处理错误并停止，不重复生图或降低最终透明要求。                                              |
+| 参考图 / 交付参数错误  | 修正路径或参数后再发送；保留用户及字段约束，不丢弃参考图继续生成。                              |
+| 风格或内容偏差         | 参考 prompt-cookbook 的主体模板，检查实际模型、参考图与交付规格；新一轮生成仍保留最终背景要求。 |
 
 ---
 
@@ -264,7 +206,7 @@ gpt-image-2（最高质量，三个 provider 互为回退）：
 
 ### 首选策略：精灵图直出（见第 1 节）
 
-**优先让 gpt-image-2 直接生成包含多个元素的网格图**，然后用 `sprite-split` 切分。这是最高效的做法，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
+**优先用本次选定的模型生成包含多个元素的网格图**，然后用 `sprite-split` 切分，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
 
 - 需要 reference-image 一致性（网格 prompt 不稳定）
 - 每个元素差异太大，一张图放不下
@@ -295,6 +237,8 @@ cp .claude/skills/playcraft-image-generation/reference/process-batch.template.mj
 node ta-workspace/scripts/process-<name>.mjs
 ```
 
+已由生成工具验证透明的图使用 `skipRemoveBg=true`，保留透明边缘；不透明牌面/场景同样跳过去背。只有独立色幕中间图才设为 `false`，按所选色幕设置容差。
+
 ### 合并精灵图
 
 参见 [build-sprite-sheet.template.mjs](../../skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs)。
@@ -333,13 +277,13 @@ ta-workspace/
 
 ### 脚本模板目录
 
-| 模板                                                                                                                 | 用途                                            | 关键 CONFIG                                   |
-| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------- |
-| [gen-batch-sprite.template.mjs](../../skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs)     | 精灵图直出（gpt-image-2 网格图 → sprite-split） | `columns`, `rows`, `BATCHES[]`                |
-| [gen-batch.template.mjs](../../skills/playcraft-image-generation/reference/gen-batch.template.mjs)                   | 批量从零 AI 生图（reference-image 模式）        | `model`, `referenceImage`, `style`, `ITEMS[]` |
-| [gen-edit-variants.template.mjs](../../skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs)   | 基图 + edit 模型生成变体                        | `baseImage`, `editModel`, `VARIANTS[]`        |
-| [process-batch.template.mjs](../../skills/playcraft-image-generation/reference/process-batch.template.mjs)           | 批量去背景 / trim + resize                      | `inputDir`, `outputDir`, `skipRemoveBg`       |
-| [build-sprite-sheet.template.mjs](../../skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs) | 精灵图合并 + JSON 验证                          | `processedDir`, `columns`, `ORDERED_NAMES[]`  |
+| 模板                                                                                                                 | 用途                                          | 关键 CONFIG                                                   |
+| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
+| [gen-batch-sprite.template.mjs](../../skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs)     | 精灵图直出，自动透明或独立色幕 → sprite-split | `model`, `removeBg`, `backgroundMode`, `columns`, `BATCHES[]` |
+| [gen-batch.template.mjs](../../skills/playcraft-image-generation/reference/gen-batch.template.mjs)                   | 批量从零 AI 生图（reference-image 模式）      | `model`, `referenceImage`, `style`, `ITEMS[]`                 |
+| [gen-edit-variants.template.mjs](../../skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs)   | 基图 + edit 模型生成变体                      | `baseImage`, `editModel`, `VARIANTS[]`                        |
+| [process-batch.template.mjs](../../skills/playcraft-image-generation/reference/process-batch.template.mjs)           | 批量去背景 / trim + resize                    | `inputDir`, `outputDir`, `skipRemoveBg`                       |
+| [build-sprite-sheet.template.mjs](../../skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs) | 精灵图合并 + JSON 验证                        | `processedDir`, `columns`, `ORDERED_NAMES[]`                  |
 
 每个模板均包含：CONFIG/DATA/LOGIC 三段式结构、`existsSync` 幂等跳过、`appendFileSync` 日志、try/catch 错误统计。