@playcraft/cli 0.1.53-beta → 0.1.54

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

@@ -1,300 +0,0 @@
-# TA (Technical Artist, 技术美术师) 图片生成进阶参考
-
-> 本文件供 TA/Designer 在需要精灵图直出、Edit 模型变体、错误恢复等进阶场景时按需查阅。核心决策逻辑见 `playcraft-image-generation` skill。
-
----
-
-## 1. 精灵图直出 + 批量出图策略
-
-### 策略一：直接生成整张精灵图（最高效）
-
-**一次 API (Application Programming Interface, 应用程序编程接口) 调用生成包含多个元素的网格图**，后续用 `sprite-split` 切分。使用主文选定的模型，不因批量生成自动改用旧模型。
-
-> 保留命令行默认等待时间。等待本身不表示请求失败；本地超时也不表示后端已停止，确认原请求状态后再决定下一步，避免重复计费。
-
-#### 先判断：元素需要透明背景吗？
-
-```
-需要透明背景（独立元素：角色、车、道具、图标）？
-├─ 常规透明交付 → --remove-background；按主文第 2 节准备源图背景
-│                切分后保留透明通道，不重复去背
-├─ 不透明牌面/场景 → --no-remove-background；白色牌面属于主体
-└─ 明确选择独立色幕 → 仅限主文第 3 节；关闭整板自动去背，切分后逐格去背
-```
-
-#### 白底示例（卡牌，不需要去背景）
-
-```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.5-sunburst \
-  --no-remove-background
-
-# 查尺寸再切分（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：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 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.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/images/cars/ \
-  --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
-```
-
-其他格同样处理，并分别验收。自动透明图使用 `backgroundMode='automatic'`；独立色幕脚本设 `backgroundMode='chroma'`、`chromaColor` 和 `chromaTolerance`，不要把两种流程混用。
-
-**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. 错误恢复策略
-
-后端统一限制模型、供应商与重生成的总尝试次数；命令行默认不额外重试。普通素材默认模型选择、原生透明优先与剩余一次干净底图重生成均以主文第 2 节为准，脚本不再叠加模型回退链。
-
-| 错误现象               | 立即行动                                                                                        |
-| ---------------------- | ----------------------------------------------------------------------------------------------- |
-| 仍在等待 / 本地超时    | 确认原请求状态，等待或核实后端已结束；不要并发重发，也不要仅因等待改模型。                      |
-| 上游错误 / 网络失败    | 记录请求编号、实际 provider/model 与尝试次数，报告后端诊断；用户或流程锁定的模型不静默更换。    |
-| 透明源图或最终验收失败 | 报告失败阶段并停止；不把棋盘格、补边或未完成的去背当成功，不自行改用色幕。                      |
-| 去背处理失败           | 报告处理错误并停止，不重复生图或降低最终透明要求。                                              |
-| 参考图 / 交付参数错误  | 修正路径或参数后再发送；保留用户及字段约束，不丢弃参考图继续生成。                              |
-| 风格或内容偏差         | 参考 prompt-cookbook 的主体模板，检查实际模型、参考图与交付规格；新一轮生成仍保留最终背景要求。 |
-
----
-
-## 4. 批量生成最佳实践
-
-### 首选策略：精灵图直出（见第 1 节）
-
-**优先用本次选定的模型生成包含多个元素的网格图**，然后用 `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
-```
-
-已由生成工具验证透明的图使用 `skipRemoveBg=true`，保留透明边缘；不透明牌面/场景同样跳过去背。只有独立色幕中间图才设为 `false`，按所选色幕设置容差。
-
-### 合并精灵图
-
-参见 [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)     | 精灵图直出，自动透明或独立色幕 → 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 错误统计。
-
-### 什么时候用命令行，什么时候写脚本？
-
-| 场景                             | 命令行 | 脚本 |
-| -------------------------------- | ------ | ---- |
-| 单张图片处理 / 查看信息          | 是     | —    |
-| 3-5 个文件，步骤简单             | 是     | —    |
-| 10+ 个文件，相同步骤             | —      | 是   |
-| 需要条件逻辑（不同素材不同参数） | —      | 是   |
-| 需要验证中间结果                 | —      | 是   |
-| 需要幂等重跑（跳过已存在）       | —      | 是   |
-| 完整管线（生成 → 处理 → 打包）   | —      | 是   |