@playcraft/cli 0.1.42 → 0.1.43-beta

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

@@ -1,23 +1,21 @@
 # Image Generation Prompt Cookbook
 
-> 适用于 PlayCraft CLI (Command-Line Interface, 命令行工具) `playcraft tools generate-image` 及沙箱生图工具。
+> 适用于 PlayCraft CLI `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,
-isolated subject, clean crisp edges, game UI asset, high quality
+white background, clean crisp edges, game UI asset, high quality
 ```
 
 ---
@@ -28,13 +26,12 @@ isolated subject, clean crisp edges, game UI asset, high quality
 
 ```
 A [物品名] icon, flat 2D vector illustration, bold outlines,
-vibrant colors, centered composition, isolated subject,
+vibrant colors, centered composition, white background,
 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）
 
@@ -53,11 +50,12 @@ sharp clean edges, centered on white background
 ```
 A [角色描述] character, full body visible, game sprite style,
 [艺术风格: pixel art / cartoon / chibi / realistic],
-isolated subject,
+isolated on solid bright green #00FF00 background,
 centered, facing forward / side view, clean silhouette
 ```
 
-- 需要透明交付 → `background: transparent` / `--background transparent`，按主文第 2 节准备源图背景，由后端去背并完成验收。
+- 需要透明背景 → **绿幕策略**，prompt 加 `"on solid bright green #00FF00 background, isolated"`
+- 后处理：`remove-background --tolerance 25`
 
 ### 🌄 场景背景（Backgrounds）
 
@@ -122,7 +120,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, isolated subjects.
+Sprite sheet grid, 3 columns × 3 rows. Flat 2D game icon style, white background.
 [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.
@@ -131,18 +129,17 @@ Each icon centered in its cell, bold outlines, vibrant colors, no shadow.
 
 **背景选择（重要！）**：
 
-| 素材类型                            | 交付要求                                              | 切分后处理                        |
-| ----------------------------------- | ----------------------------------------------------- | --------------------------------- |
-| 独立元素（角色/车/道具/图标）需透明 | `--background transparent`，按主文第 2 节准备源图背景 | 保留透明通道，验证每格前景与边缘  |
-| 卡牌/棋子/UI 面板（矩形本体）       | 默认 `--background transparent`，保留牌面与边框       | 验证本体外透明，按目标尺寸 resize |
-| 用户/字段明确要求保留背景的最终素材 | `--background opaque`，整张图片不透明                 | 保留背景，按目标尺寸 resize       |
+| 素材类型                            | prompt 背景写法                                     | 切分后处理                         |
+| ----------------------------------- | --------------------------------------------------- | ---------------------------------- |
+| 独立元素（角色/车/道具/图标）需透明 | `isolated on solid bright green #00FF00 background` | `remove-background --tolerance 25` |
+| 卡牌/棋子/UI 面板（矩形本体）       | `white background, no shadow`                       | 直接 resize，不去背景              |
 
 **注意事项**：
 
 - 每批最多 **4×4 = 16 个元素**，超过会出现混乱
 - 每个格的描述要精确，包含特征性视觉元素
 - 切分后用 `sprite-split --rows N --columns M` 按网格切分
-- 模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)：`backgroundMode='automatic'` 为常规流程，`removeBg` 表示最终是否透明。独立色幕需显式设 `backgroundMode='chroma'`、所选模型和色幕颜色；脚本关闭整板自动去背，切分后逐格去背。
+- 模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)
 
 ---
 
@@ -186,7 +183,7 @@ gpt-image-2 是目前质量最高的文生图模型，prompt 套路略有不同
 - **英文 prompt 效果最佳**，中文理解也不错但英文更稳定
 - 对**复杂场景**、**细节描述**处理能力远超其他模型
 - 支持**图生图 edit 模式**（传 `--reference-image`），局部编辑能力强
-- 不支持原生透明 PNG (Portable Network Graphics, 便携式网络图形) 输出（ALPHA = no）；透明交付仍由工具后处理。明确选择独立色幕制作时再按主文第 3 节处理。
+- 不支持透明 PNG 输出（ALPHA = no），需绿幕策略
 
 ### prompt 格式建议
 
@@ -234,7 +231,6 @@ 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
@@ -252,7 +248,6 @@ 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
@@ -275,8 +270,6 @@ 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）
 
 ```
@@ -287,13 +280,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: No extra elements, centered, clean crisp edges,
+Constraints: Transparent background, no extra elements, centered, clean crisp edges,
   no watermark
 ```
 
 - CTA 颜色必须是游戏画面中**最少使用**的颜色（对比稀缺性原则）
 - 触控目标区域 ≥ 48×48px，生成建议尺寸 360×120px（9:3 比例）
-- 后处理由工具完成，验证最终透明背景、文字与边缘。
+- 后处理：不需要去背景（直接生成透明背景或用绿幕）
 
 ---
 
@@ -306,7 +299,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: Horizontal orientation, no text labels,
+Constraints: Transparent background, horizontal orientation, no text labels,
   clean edges, no watermark
 ```
 
@@ -324,7 +317,8 @@ 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: No extra limbs or elements, finger pointing at bottom-center
+Constraints: Transparent background, PNG with alpha channel,
+  no extra limbs or elements, finger pointing at bottom-center
 ```
 
 **箭头变体**（更简洁）：
@@ -334,7 +328,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: Single clean arrow shape, no text
+Constraints: Transparent background, single clean arrow shape, no text
 ```
 
 ---
@@ -348,7 +342,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: No text inside, clean edges,
+Constraints: Transparent background, no text inside, clean edges,
   no watermark, no extra decorations
 ```
 
@@ -368,7 +362,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: Centered, isolated subject,
+Constraints: Transparent background, centered, isolated subject,
   no CTA text (added separately), warm celebratory lighting
 ```
 
@@ -379,19 +373,25 @@ Constraints: Centered, isolated subject,
 
 ### 📊 UI 元素背景处理规则速查
 
-CTA 按钮、进度条、引导手势、对话气泡与 EndCard 奖励图标都通过 `background: transparent` / `--background transparent` 要求最终透明；主体内容使用上述模板，源图背景按主文第 2 节准备。交付后验证文字、完整前景及深浅背景上的边缘。独立色幕制作沿用主文第 3 节的单一背景与独立去背流程。
+| 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） |
 
 ---
 
 ## 六、常见问题 & 修正方案
 
-| 问题               | 原因                 | 修正                                                                     |
-| ------------------ | -------------------- | ------------------------------------------------------------------------ |
-| 图标边缘有阴影     | 模型默认加立体效果   | 加 `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 或换模型                                               |
+| 问题               | 原因                 | 修正                                             |
+| ------------------ | -------------------- | ------------------------------------------------ |
+| 图标边缘有阴影     | 模型默认加立体效果   | 加 `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 或换模型                       |

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

@@ -1,25 +1,24 @@
-# TA (Technical Artist, 技术美术师) 图片生成进阶参考
+# TA 图片生成进阶参考
 
 > 本文件供 TA/Designer 在需要精灵图直出、Edit 模型变体、错误恢复等进阶场景时按需查阅。核心决策逻辑见 `playcraft-image-generation` skill。
 
 ---
 
-## 1. 精灵图直出 + 批量出图策略
+## 1. gpt-image-2 精灵图直出 + 批量出图策略
 
 ### 策略一：直接生成整张精灵图（最高效）
 
-**一次 API (Application Programming Interface, 应用程序编程接口) 调用生成包含多个元素的网格图**，后续用 `sprite-split` 切分。使用主文选定的模型，不因批量生成自动改用旧模型。
+**gpt-image-2 可以一次 API 调用就生成一张包含多个元素的网格图**，后续用 `sprite-split` 切分。避免逐个生成的低效循环。
 
-> 保留命令行默认等待时间。等待本身不表示请求失败；本地超时也不表示后端已停止，确认原请求状态后再决定下一步，避免重复计费。
+> gpt-image-2 本身就慢（单图 7-8 分钟正常，精灵图 90-150 秒正常）。**调用 gpt-image-2 时不要设 `--timeout`**，让它自然完成。"慢"不是卡死，不要中途 Ctrl+C 换模型。真正的失败是 `API 500` 或 `fetch failed`，那才需要切换 provider。
 
 #### 先判断：元素需要透明背景吗？
 
 ```
 需要透明背景（独立元素：角色、车、道具、图标）？
-├─ 常规透明交付 → --remove-background；按主文第 2 节准备源图背景
-│                切分后保留透明通道，不重复去背
-├─ 不透明牌面/场景 → --no-remove-background；白色牌面属于主体
-└─ 明确选择独立色幕 → 仅限主文第 3 节；关闭整板自动去背，切分后逐格去背
+├─ YES → 绿幕策略：prompt 所有格子加 "solid bright green #00FF00 background"
+│          切分后对每帧跑 remove-background --tolerance 25
+└─ NO  → 白底策略：prompt 加 "white background"（卡牌/棋盘/UI 面板适用）
 ```
 
 #### 白底示例（卡牌，不需要去背景）
@@ -29,8 +28,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.5-sunburst \
-  --no-remove-background
+  --image-model iegg-litellm/gpt-image-2
+  # gpt-image-2 不设 --timeout，精灵图 90-150s 正常，等待即可
 
 # 查尺寸再切分（frame-width=总宽/列数, frame-height=总高/行数）
 playcraft image info --input assets/gen/cards_sheet.png
@@ -41,51 +40,36 @@ playcraft image sprite-split \
   --frame-width <总宽/4> --frame-height <总高/2>
 ```
 
-#### 自动透明示例（独立元素）
+#### 绿幕示例（独立元素，需要透明背景）
 
 ```bash
-# Step 1：Image 2.5 由后端组装源图背景并验收透明交付
+# Step 1：生成绿幕精灵图
 playcraft tools generate-image \
-  --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." \
+  --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." \
   --output assets/gen/cars_sheet.png \
   --aspect-ratio 3:2 \
-  --image-model iegg-litellm/gpt-image-2.5-sunburst \
-  --remove-background
+  --image-model iegg-litellm/gpt-image-2
+  # gpt-image-2 不设 --timeout，精灵图 90-150s 正常，等待即可
 
 # Step 2：切分
 playcraft image info --input assets/gen/cars_sheet.png
 playcraft image sprite-split \
   --input assets/gen/cars_sheet.png \
-  --output-dir assets/images/cars/ \
+  --output-dir assets/gen/cars-split/ \
   --rows 1 --columns 3 \
   --frame-width <总宽/3> --frame-height <总高>
 
-# 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
+# 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
 ```
 
-其他格同样处理，并分别验收。自动透明图使用 `backgroundMode='automatic'`；独立色幕脚本设 `backgroundMode='chroma'`、`chromaColor` 和 `chromaTolerance`，不要把两种流程混用。
+**Provider 选择**：iegg-litellm/gpt-image-2 质量最高；google/gemini-3.1-flash-image-preview 最稳定且参考图正常工作。
 
 **Prompt 关键词**：`sprite sheet grid, N columns × M rows, grid layout, equal cell size, uniform size`
 
@@ -189,16 +173,34 @@ node ta-workspace/scripts/gen-<name>-variants.mjs
 
 ## 3. 错误恢复策略
 
-后端统一限制模型、供应商与重生成的总尝试次数；命令行默认不额外重试。普通素材默认模型选择、原生透明优先与剩余一次干净底图重生成均以主文第 2 节为准，脚本不再叠加模型回退链。
+> **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 质量修饰词                                                       |
+
+### 模型回退顺序
 
-| 错误现象               | 立即行动                                                                                        |
-| ---------------------- | ----------------------------------------------------------------------------------------------- |
-| 仍在等待 / 本地超时    | 确认原请求状态，等待或核实后端已结束；不要并发重发，也不要仅因等待改模型。                      |
-| 上游错误 / 网络失败    | 记录请求编号、实际 provider/model 与尝试次数，报告后端诊断；用户或流程锁定的模型不静默更换。    |
-| 透明源图或最终验收失败 | 报告失败阶段并停止；不把棋盘格、补边或未完成的去背当成功，不自行改用色幕。                      |
-| 去背处理失败           | 报告处理错误并停止，不重复生图或降低最终透明要求。                                              |
-| 参考图 / 交付参数错误  | 修正路径或参数后再发送；保留用户及字段约束，不丢弃参考图继续生成。                              |
-| 风格或内容偏差         | 参考 prompt-cookbook 的主体模板，检查实际模型、参考图与交付规格；新一轮生成仍保留最终背景要求。 |
+```
+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，不要等待。
 
 ---
 
@@ -206,7 +208,7 @@ node ta-workspace/scripts/gen-<name>-variants.mjs
 
 ### 首选策略：精灵图直出（见第 1 节）
 
-**优先用本次选定的模型生成包含多个元素的网格图**，然后用 `sprite-split` 切分，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
+**优先让 gpt-image-2 直接生成包含多个元素的网格图**，然后用 `sprite-split` 切分。这是最高效的做法，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
 
 - 需要 reference-image 一致性（网格 prompt 不稳定）
 - 每个元素差异太大，一张图放不下
@@ -237,8 +239,6 @@ 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)     | 精灵图直出，自动透明或独立色幕 → 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                                   |
+| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------- |
+| [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/DATA/LOGIC 三段式结构、`existsSync` 幂等跳过、`appendFileSync` 日志、try/catch 错误统计。