@playcraft/cli 0.1.40-beta → 0.1.42

package/project-template/.claude/skills/playcraft-image-generation/reference/prompt-cookbook.md

@@ -1,21 +1,23 @@
 # Image Generation Prompt Cookbook
 
-> 适用于 PlayCraft CLI `playcraft tools generate-image`。
+> 适用于 PlayCraft CLI (Command-Line Interface, 命令行工具) `playcraft tools generate-image` 及沙箱生图工具。
 > 所有模型均适用；gpt-image-2 类模型对英文 prompt 理解最准确，优先写英文。
 
+透明交付通过 `background: transparent` / `--background transparent` 或目标字段配置表达。用户未明确要求背景且字段没有明确不透明约束时，默认透明，包括卡牌、棋子和面板。下方常规前景模板描述主体、文字、风格、构图与材质；源图背景遵循主文第 2 节：Image 2.5 由后端组装，不追加背景后缀；明确选用其他模型时，首次请求需追加单一 `on a uniform solid pure white background for subsequent background removal`。不要同时要求透明、白底与色幕。用户或字段明确要求完整场景时可以描述背景内容；矩形本体的白色牌面属于前景，应在透明画布上保留。独立色幕流程见主文第 3 节，中间图必须关闭自动去背。
+
 ---
 
 ## 一、Prompt 万能公式
 
 ```
-[主体描述] + [风格/介质] + [构图/视角] + [背景] + [质量修饰词]
+[主体描述] + [风格/介质] + [构图/视角] + [场景内容（如需要）] + [质量修饰词]
 ```
 
 **示例**：
 
 ```
 A golden sword icon, flat 2D vector style, centered composition,
-white background, clean crisp edges, game UI asset, high quality
+isolated subject, clean crisp edges, game UI asset, high quality
 ```
 
 ---
@@ -26,12 +28,13 @@ white background, clean crisp edges, game UI asset, high quality
 
 ```
 A [物品名] icon, flat 2D vector illustration, bold outlines,
-vibrant colors, centered composition, white background,
+vibrant colors, centered composition, isolated subject,
 no shadow, no gradient, game UI style, sharp crisp edges
 ```
 
 - 关键词：`flat 2D` / `bold outlines` / `centered` / `no shadow` / `game UI style`
 - 避免：`3D` / `realistic` / `photographic` / `drop shadow`
+- 需要透明交付时传 `background: transparent` / `--background transparent`。
 
 ### 🃏 卡牌 / 棋子 / 方块（Rectangular Tiles）
 
@@ -50,12 +53,11 @@ sharp clean edges, centered on white background
 ```
 A [角色描述] character, full body visible, game sprite style,
 [艺术风格: pixel art / cartoon / chibi / realistic],
-isolated on solid bright green #00FF00 background,
+isolated subject,
 centered, facing forward / side view, clean silhouette
 ```
 
-- 需要透明背景 → **绿幕策略**，prompt 加 `"on solid bright green #00FF00 background, isolated"`
-- 后处理：`remove-background --tolerance 25`
+- 需要透明交付 → `background: transparent` / `--background transparent`，按主文第 2 节准备源图背景，由后端去背并完成验收。
 
 ### 🌄 场景背景（Backgrounds）
 
@@ -120,7 +122,7 @@ Grid layout, equal cell size, no borders between cells. Bold black ink for spade
 **图标集示例**（一批 9 个图标）：
 
 ```
-Sprite sheet grid, 3 columns × 3 rows. Flat 2D game icon style, white background.
+Sprite sheet grid, 3 columns × 3 rows. Flat 2D game icon style, isolated subjects.
 [Row1,Col1]: sword icon; [Row1,Col2]: shield icon; [Row1,Col3]: bow and arrow icon;
 [Row2,Col1]: magic staff icon; [Row2,Col2]: potion bottle icon; [Row2,Col3]: scroll icon;
 [Row3,Col1]: coin gold icon; [Row3,Col2]: gem diamond icon; [Row3,Col3]: key icon.
@@ -129,17 +131,18 @@ Each icon centered in its cell, bold outlines, vibrant colors, no shadow.
 
 **背景选择（重要！）**：
 
-| 素材类型                            | prompt 背景写法                                     | 切分后处理                         |
-| ----------------------------------- | --------------------------------------------------- | ---------------------------------- |
-| 独立元素（角色/车/道具/图标）需透明 | `isolated on solid bright green #00FF00 background` | `remove-background --tolerance 25` |
-| 卡牌/棋子/UI 面板（矩形本体）       | `white background, no shadow`                       | 直接 resize，不去背景              |
+| 素材类型                            | 交付要求                                              | 切分后处理                        |
+| ----------------------------------- | ----------------------------------------------------- | --------------------------------- |
+| 独立元素（角色/车/道具/图标）需透明 | `--background transparent`，按主文第 2 节准备源图背景 | 保留透明通道，验证每格前景与边缘  |
+| 卡牌/棋子/UI 面板（矩形本体）       | 默认 `--background transparent`，保留牌面与边框       | 验证本体外透明，按目标尺寸 resize |
+| 用户/字段明确要求保留背景的最终素材 | `--background opaque`，整张图片不透明                 | 保留背景，按目标尺寸 resize       |
 
 **注意事项**：
 
 - 每批最多 **4×4 = 16 个元素**，超过会出现混乱
 - 每个格的描述要精确，包含特征性视觉元素
 - 切分后用 `sprite-split --rows N --columns M` 按网格切分
-- 模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)
+- 模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)：`backgroundMode='automatic'` 为常规流程，`removeBg` 表示最终是否透明。独立色幕需显式设 `backgroundMode='chroma'`、所选模型和色幕颜色；脚本关闭整板自动去背，切分后逐格去背。
 
 ---
 
@@ -183,7 +186,7 @@ gpt-image-2 是目前质量最高的文生图模型，prompt 套路略有不同
 - **英文 prompt 效果最佳**，中文理解也不错但英文更稳定
 - 对**复杂场景**、**细节描述**处理能力远超其他模型
 - 支持**图生图 edit 模式**（传 `--reference-image`），局部编辑能力强
-- 不支持透明 PNG 输出（ALPHA = no），需绿幕策略
+- 不支持原生透明 PNG (Portable Network Graphics, 便携式网络图形) 输出（ALPHA = no）；透明交付仍由工具后处理。明确选择独立色幕制作时再按主文第 3 节处理。
 
 ### prompt 格式建议
 
@@ -231,6 +234,7 @@ elements centered in each cell, no borders between cells.
 ```bash
 playcraft tools generate-image \
   --prompt "A sword icon, flat 2D..." \
+  --background transparent \
   --output assets/gen/sword \
   --count 4 \
   --image-model iegg-litellm/gpt-image-2
@@ -248,6 +252,7 @@ playcraft tools generate-image \
 # 一次 API 调用生成 4 个候选，选最好的（比 4 次独立调用更高效）
 playcraft tools generate-image \
   --prompt "..." \
+  --background "$BACKGROUND_MODE" \
   --output "test/concept" \
   --count 4 \
   --image-model iegg-litellm/gpt-image-2
@@ -270,6 +275,8 @@ playcraft tools generate-image \
 >
 > 注意：`figer_icon.aiimage`、`win_result_panel.aiimage` 等 atom Skills 提供了带参考图的生成配方，Game Designer `playcraft skills match` 能匹配到时优先使用。本节模板用于无对应 atom Skill 的场景。
 
+下方独立界面前景通过 `background: transparent` / `--background transparent` 要求最终透明；模板描述主体，调用前按主文第 2 节补充适用于所选模型的源图背景。
+
 ### 🟠 CTA 按钮（Call-to-Action Button）
 
 ```
@@ -280,13 +287,13 @@ Important details: [bright orange / gold / green] gradient fill,
   subtle drop shadow below button, glossy highlight on top edge,
   3px white inner border, corners rounded radius 24px
 Use case: Game ad install button, isolated asset, HTML5 playable ad
-Constraints: Transparent background, no extra elements, centered, clean crisp edges,
+Constraints: No extra elements, centered, clean crisp edges,
   no watermark
 ```
 
 - CTA 颜色必须是游戏画面中**最少使用**的颜色（对比稀缺性原则）
 - 触控目标区域 ≥ 48×48px，生成建议尺寸 360×120px（9:3 比例）
-- 后处理：不需要去背景（直接生成透明背景或用绿幕）
+- 后处理由工具完成，验证最终透明背景、文字与边缘。
 
 ---
 
@@ -299,7 +306,7 @@ Important details: [color] filled portion [80% of total width], unfilled portion
   rounded end caps, thin outer frame in [darker shade],
   optional inner glow on filled section
 Use case: Game HUD progress indicator, isolated UI element
-Constraints: Transparent background, horizontal orientation, no text labels,
+Constraints: Horizontal orientation, no text labels,
   clean edges, no watermark
 ```
 
@@ -317,8 +324,7 @@ Important details: warm skin tone, white sleeve cuff visible at wrist,
   soft drop shadow beneath finger tip, friendly approachable style,
   [optional: subtle animated glow ring around fingertip]
 Use case: Tutorial overlay tap gesture for playable ad, points toward target element
-Constraints: Transparent background, PNG with alpha channel,
-  no extra limbs or elements, finger pointing at bottom-center
+Constraints: No extra limbs or elements, finger pointing at bottom-center
 ```
 
 **箭头变体**（更简洁）：
@@ -328,7 +334,7 @@ Subject: Bold cartoon arrow pointing [down / right], game tutorial UI
 Style: flat 2D, thick outline 4px, rounded arrowhead
 Important details: [bright yellow / white] fill, [dark outline],
   slight perspective tilt for depth, attention-grabbing
-Constraints: Transparent background, single clean arrow shape, no text
+Constraints: Single clean arrow shape, no text
 ```
 
 ---
@@ -342,7 +348,7 @@ Important details: white or [light color] fill, [2–3px] dark outline,
   tail pointing [down-left / down-center], interior empty for text overlay,
   subtle inner shadow or gradient
 Use case: Game tutorial hint tooltip, isolated UI asset
-Constraints: Transparent background, no text inside, clean edges,
+Constraints: No text inside, clean edges,
   no watermark, no extra decorations
 ```
 
@@ -362,7 +368,7 @@ Important details: [treasure chest]: lid slightly ajar, golden glow escaping fro
   [gold coins]: scattered pile, gleaming highlights, not neatly stacked (implies uncollected);
   [gem crystal]: large, brilliant facets, floating above ground, clearly valuable
 Use case: EndCard reward visual, creates FOMO and drives install
-Constraints: Transparent background, centered, isolated subject,
+Constraints: Centered, isolated subject,
   no CTA text (added separately), warm celebratory lighting
 ```
 
@@ -373,25 +379,19 @@ Constraints: Transparent background, centered, isolated subject,
 
 ### 📊 UI 元素背景处理规则速查
 
-| UI 元素类型      | prompt 背景写法                                 | 后处理                         |
-| ---------------- | ----------------------------------------------- | ------------------------------ |
-| CTA 按钮         | `transparent background` 或绿幕                 | floodfill 去背                 |
-| 进度条           | `transparent background` 或绿幕                 | floodfill 去背                 |
-| 引导手势         | `transparent background, PNG with alpha`        | floodfill 去背（tolerance 25） |
-| 对话气泡         | `transparent background` 或绿幕                 | floodfill 去背                 |
-| EndCard 奖励图标 | 绿幕（`solid bright green #00FF00 background`） | floodfill 去背（tolerance 25） |
+CTA 按钮、进度条、引导手势、对话气泡与 EndCard 奖励图标都通过 `background: transparent` / `--background transparent` 要求最终透明；主体内容使用上述模板，源图背景按主文第 2 节准备。交付后验证文字、完整前景及深浅背景上的边缘。独立色幕制作沿用主文第 3 节的单一背景与独立去背流程。
 
 ---
 
 ## 六、常见问题 & 修正方案
 
-| 问题               | 原因                 | 修正                                             |
-| ------------------ | -------------------- | ------------------------------------------------ |
-| 图标边缘有阴影     | 模型默认加立体效果   | 加 `no shadow, no drop shadow, flat 2D`          |
-| 构图不居中         | 没有明确指定         | 加 `centered composition, subject centered`      |
-| 背景不干净         | 背景描述不够明确     | 加 `solid white background, isolated` 或绿幕策略 |
-| 多个物体出现       | 主体不够明确         | 加 `a single [物体]`, `only one [物体]`          |
-| 文字拼写错误       | 所有模型通病         | 尝试 gpt-image-2（最好），或多生成几张           |
-| 风格不一致（批量） | 没用 reference image | Phase 2 必须加 `--reference-image`               |
-| 细节过于复杂       | 素材尺寸小但细节太多 | 加 `simple design, minimal details, bold shapes` |
-| 生成极慢/超时      | 模型负载高           | 换另一个 provider 或换模型                       |
+| 问题               | 原因                 | 修正                                                                     |
+| ------------------ | -------------------- | ------------------------------------------------------------------------ |
+| 图标边缘有阴影     | 模型默认加立体效果   | 加 `no shadow, no drop shadow, flat 2D`                                  |
+| 构图不居中         | 没有明确指定         | 加 `centered composition, subject centered`                              |
+| 背景不干净         | 交付要求或处理不匹配 | 核对背景开关、字段配置及模型对应的源图规则；检查最终验收，不混加背景要求 |
+| 多个物体出现       | 主体不够明确         | 加 `a single [物体]`, `only one [物体]`                                  |
+| 文字拼写错误       | 所有模型通病         | 尝试 gpt-image-2（最好），或多生成几张                                   |
+| 风格不一致（批量） | 没用 reference image | Phase 2 必须加 `--reference-image`                                       |
+| 细节过于复杂       | 素材尺寸小但细节太多 | 加 `simple design, minimal details, bold shapes`                         |
+| 生成极慢/超时      | 模型负载高           | 换另一个 provider 或换模型                                               |

package/project-templates/phaser/.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`
 
@@ -173,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 的主体模板，检查实际模型、参考图与交付规格；新一轮生成仍保留最终背景要求。 |
 
 ---
 
@@ -208,7 +206,7 @@ gpt-image-2（最高质量，三个 provider 互为回退）：
 
 ### 首选策略：精灵图直出（见第 1 节）
 
-**优先让 gpt-image-2 直接生成包含多个元素的网格图**，然后用 `sprite-split` 切分。这是最高效的做法，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
+**优先用本次选定的模型生成包含多个元素的网格图**，然后用 `sprite-split` 切分，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
 
 - 需要 reference-image 一致性（网格 prompt 不稳定）
 - 每个元素差异太大，一张图放不下
@@ -239,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)。
@@ -277,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 错误统计。