@playcraft/cli 0.1.42 → 0.1.43-beta

package/project-template/.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`
 
@@ -123,20 +107,76 @@ 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 切分
@@ -189,16 +229,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 +264,7 @@ node ta-workspace/scripts/gen-<name>-variants.mjs
 
 ### 首选策略：精灵图直出（见第 1 节）
 
-**优先用本次选定的模型生成包含多个元素的网格图**，然后用 `sprite-split` 切分，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
+**优先让 gpt-image-2 直接生成包含多个元素的网格图**，然后用 `sprite-split` 切分。这是最高效的做法，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
 
 - 需要 reference-image 一致性（网格 prompt 不稳定）
 - 每个元素差异太大，一张图放不下
@@ -237,8 +295,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 +333,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 错误统计。