@playcraft/cli 0.1.36-beta1 → 0.1.37-beta

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

@@ -0,0 +1,300 @@
+# TA 图片生成进阶参考
+
+> 本文件供 TA/Designer 在需要精灵图直出、Edit 模型变体、错误恢复等进阶场景时按需查阅。核心决策逻辑见 `playcraft-image-generation` skill。
+
+---
+
+## 1. gpt-image-2 精灵图直出 + 批量出图策略
+
+### 策略一：直接生成整张精灵图（最高效）
+
+**gpt-image-2 可以一次 API 调用就生成一张包含多个元素的网格图**，后续用 `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 面板适用）
+```
+
+#### 白底示例（卡牌，不需要去背景）
+
+```bash
+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 正常，等待即可
+
+# 查尺寸再切分（frame-width=总宽/列数, frame-height=总高/行数）
+playcraft image info --input assets/gen/cards_sheet.png
+playcraft image sprite-split \
+  --input assets/gen/cards_sheet.png \
+  --output-dir assets/images/cards/ \
+  --rows 2 --columns 4 \
+  --frame-width <总宽/4> --frame-height <总高/2>
+```
+
+#### 绿幕示例（独立元素，需要透明背景）
+
+```bash
+# 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 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
+  # 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/gen/cars-split/ \
+  --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
+```
+
+**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`
+
+**每批推荐最多 16 个元素（4x4）**，元素太多时会出现混乱。
+
+### 策略二：批量出图（n>1，一次 API 调用返回多张候选）
+
+`--count N` 让同一个 prompt 一次返回 N 张候选图，适合 Phase 1 挑图。**谨慎使用，容易触发 provider 并发限制。**
+
+```bash
+# 一次 API 调用生成 4 张候选，选最好的
+playcraft tools generate-image \
+  --prompt "A single playing card, Ace of Hearts, flat 2D..." \
+  --output assets/gen/card \
+  --count 4 \
+  --image-model iegg-litellm/gpt-image-2
+# → 保存为 card_1.png card_2.png card_3.png card_4.png
+```
+
+> `--count N` 是"同一 prompt 出 N 张变体"，而不是"N 个不同元素"。生成 N 个不同元素请用策略一（精灵图直出）。
+
+**两种策略对比**：
+
+| 场景                       | 推荐策略                    | 说明                              |
+| -------------------------- | --------------------------- | --------------------------------- |
+| <=16 个同类元素            | 精灵图直出（策略一）        | 一张网格图 + sprite-split，最高效 |
+| 17-52 个元素               | 精灵图直出分批（每批 <=16） | 生成多张精灵图再切分              |
+| 风格变体（同构造不同内容） | 批量出图 `--count 4-6`      | 同 prompt 出多张挑最好的          |
+| 禁止                       | 逐个生成每个元素            | 效率极低，应全面避免              |
+
+### 策略三：分批生成精灵图（元素数量 > 16）
+
+```javascript
+// ta-workspace/scripts/gen-cards-batch-sheets.mjs
+// 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_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_clubs',
+    cards: ['A♣', '2♣', '3♣', '4♣', '5♣', '6♣', '7♣', '8♣', '9♣', '10♣', 'J♣', 'Q♣', 'K♣'],
+  },
+];
+// 每批生成一张 13×1 精灵图，再用 sprite-split 切分
+```
+
+参考脚本模板：[gen-batch-sprite.template.mjs](../../skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs)
+
+---
+
+## 2. Edit 模型工作流（基图 → 编辑变体）
+
+### 适用场景
+
+结构相同、只改局部的变体集合：扑克牌（换花色/换数字）、棋子（换颜色）、图标集（换内容符号）。
+
+### 工作流
+
+```
+Phase 1：高质量模型生成 1 张完美基图
+  → gpt-image-2 / gemini-flash（最佳质量）
+  → 反复生成直到满意，存为 base_xxx.png
+
+Phase 2：用参考图 + prompt 批量生成变体
+  → 任何 text+image 或 image→image 模型均可
+  → 将基图作为 --reference-image，prompt 中描述变体差异
+  → 纯 edit 场景可用 mulerouter/qwen-image-edit-max
+```
+
+### Edit Prompt 写法
+
+```
+好的写法（修改指令）：
+   "Change the rank symbol from A to 2, show two spade symbols in the center"
+
+差的写法（完整重描述）：
+   "A playing card with two spade symbols, white background..."
+   （这会让模型重新生图，而不是编辑）
+```
+
+### 使用脚本模板
+
+```bash
+cp .claude/skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs \
+   ta-workspace/scripts/gen-<name>-variants.mjs
+# 修改 CONFIG.baseImage / CONFIG.editModel / VARIANTS[] 后运行
+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 质量修饰词                                                       |
+
+### 模型回退顺序
+
+```
+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，不要等待。
+
+---
+
+## 4. 批量生成最佳实践
+
+### 首选策略：精灵图直出（见第 1 节）
+
+**优先让 gpt-image-2 直接生成包含多个元素的网格图**，然后用 `sprite-split` 切分。这是最高效的做法，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
+
+- 需要 reference-image 一致性（网格 prompt 不稳定）
+- 每个元素差异太大，一张图放不下
+
+### 单张验证后再批量
+
+先生成 1 张验证效果，满意后再运行批量脚本。
+
+### 使用 Node.js 脚本（推荐）
+
+参见 [gen-batch.template.mjs](../../skills/playcraft-image-generation/reference/gen-batch.template.mjs)，复制到 `ta-workspace/scripts/` 后修改 CONFIG 区域。
+
+```bash
+cp .claude/skills/playcraft-image-generation/reference/gen-batch.template.mjs \
+   ta-workspace/scripts/gen-<name>.mjs
+# 修改 CONFIG / ITEMS[] 后运行
+node ta-workspace/scripts/gen-<name>.mjs
+```
+
+### 批量处理
+
+参见 [process-batch.template.mjs](../../skills/playcraft-image-generation/reference/process-batch.template.mjs)。
+
+```bash
+cp .claude/skills/playcraft-image-generation/reference/process-batch.template.mjs \
+   ta-workspace/scripts/process-<name>.mjs
+# 修改 CONFIG（特别是 skipRemoveBg）后运行
+node ta-workspace/scripts/process-<name>.mjs
+```
+
+### 合并精灵图
+
+参见 [build-sprite-sheet.template.mjs](../../skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs)。
+
+```bash
+cp .claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs \
+   ta-workspace/scripts/build-<name>-atlas.mjs
+# 修改 CONFIG / ORDERED_NAMES[] 后运行
+node ta-workspace/scripts/build-<name>-atlas.mjs
+```
+
+---
+
+## 5. TA Workspace：Node.js 脚本驱动
+
+### 为什么用 Node.js 而不是 bash？
+
+| 维度     | bash              | Node.js                    |
+| -------- | ----------------- | -------------------------- |
+| 语法错误 | 引号/转义陷阱多   | 标准 ES 语法，错误立即可读 |
+| 条件逻辑 | 繁琐              | if/else/switch 简洁        |
+| 错误处理 | `set -e` 容易遗漏 | try/catch 完整覆盖         |
+| 数据驱动 | 字符串拼接        | 对象数组，结构清晰         |
+| 调试     | `bash -x` 噪声大  | `console.log` 精确定位     |
+
+**结论**：超过 5 步或超过 10 个文件，始终写 Node.js 脚本。
+
+### ta-workspace 目录约定
+
+```
+ta-workspace/
+├── scripts/    ← Node.js 脚本（.mjs）
+├── logs/       ← 脚本运行日志（自动追加）
+└── tmp/        ← 临时文件（脚本完成后自动清理）
+```
+
+### 脚本模板目录
+
+| 模板                                                                                                                 | 用途                                            | 关键 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 错误统计。
+
+### 什么时候用命令行，什么时候写脚本？
+
+| 场景                             | 命令行 | 脚本 |
+| -------------------------------- | ------ | ---- |
+| 单张图片处理 / 查看信息          | 是     | —    |
+| 3-5 个文件，步骤简单             | 是     | —    |
+| 10+ 个文件，相同步骤             | —      | 是   |
+| 需要条件逻辑（不同素材不同参数） | —      | 是   |
+| 需要验证中间结果                 | —      | 是   |
+| 需要幂等重跑（跳过已存在）       | —      | 是   |
+| 完整管线（生成 → 处理 → 打包）   | —      | 是   |