@playcraft/cli 0.1.40-beta → 0.1.41-prod

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

@@ -1,300 +0,0 @@
-# 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+ 个文件，相同步骤             | —      | 是   |
-| 需要条件逻辑（不同素材不同参数） | —      | 是   |
-| 需要验证中间结果                 | —      | 是   |
-| 需要幂等重跑（跳过已存在）       | —      | 是   |
-| 完整管线（生成 → 处理 → 打包）   | —      | 是   |