@playcraft/cli 0.1.33 → 0.1.35-prod

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

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

package/project-templates/phaser/.claude/skills/playcraft-image-generation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playcraft-image-generation
-description: PlayCraft AI 图片生成核心决策指南。涵盖模型选择决策树、核心命令模板、背景处理决策树（绿幕策略）、脚本决策规则。精灵图直出/Edit 模型/错误恢复/批量实践等进阶内容见 refs/ta-image-generation-detail.md。
+description: PlayCraft AI (Artificial Intelligence, 人工智能) 图片生成与素材替换指南。默认使用可用的 Image 2.5；替换素材时读取参考图，全新素材可无参考文生图；验证背景要求、目标尺寸和最终文件。
 triggers: 生成图片,generate image,选模型,model selection,reference image,参考图,风格一致,图生图,文生图,AI生图,图片质量,模型选择,500错误,模型失败,generate-image,list-image-models,ta-workspace,batch,批量,脚本,nodejs,edit模型,变体,绿幕,去背景,透明PNG,prompt,提示词,prompt套路,提示词技巧
 ---
 
@@ -8,7 +8,13 @@ triggers: 生成图片,generate image,选模型,model selection,reference image,
 
 ## 0. 开始前必读
 
-生图前**必须先运行模型发现命令**：
+替换现有素材时先读取目标字段的 schema 配置（resolution、ratio、prompt、remove_background、reference_image）及当前素材。全新素材按用户需求确定尺寸、格式和输出路径，不假定所有素材都是透明 PNG (Portable Network Graphics, 便携式网络图形)。
+
+项目没有素材 schema 时，从目标素材的尺寸、格式和用户需求确定交付规格；参考图只提供内容和风格，不改变目标画布。不要套用其他游戏的字段、路径或尺寸。
+
+替换现有素材时传 `targetAssetPath`（命令行为 `--target-asset`）：工具在生成前自动读取字段的 reference_image、当前素材、尺寸、格式、fit_mode、remove_background 与 padding_color。字段没有参考图时使用当前素材；读取失败立即停止，不丢弃参考图后继续生成。显式 referenceImagePath / --reference-image 可以覆盖默认参考图；用户明确要求无参考生成时才设 useTargetReference=false / --no-target-reference，交付约束仍保留。查看图片或在对话中选中素材不等于传入参考图。仅调整风格时保留原有文字、构图和用途；用户要求重新命名或重做构图时再改变。
+
+生图前运行模型发现命令，核实当前账号可用的模型与透明输出能力：
 
 ```bash
 playcraft tools list-image-models
@@ -18,7 +24,8 @@ playcraft tools list-image-models
 
 ```
 MODEL                                        CAPABILITY   ALPHA  PROVIDERS
-gpt-image-2                                  text+image   no     3 (iegg-litellm, mulerouter, 302)
+gpt-image-2.5-sunburst                        text+image   yes    iegg-litellm
+gpt-image-2.5-flare                           text+image   yes    iegg-litellm
 gemini-3.1-flash-image-preview               text+image   no     2 (google, iegg-litellm)
 hy-image-v3.0                                text+image   no     1 (tencent-cloud)
 flux-kontext-pro                             text+image   no     1 (302)
@@ -29,7 +36,7 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 **列说明**：
 
 - `CAPABILITY`：`text→image` 仅文生图 / `image→image` 仅图生图 / `text+image` 两者均支持
-- `ALPHA`：`yes` = 原生透明 PNG；`no` = 需使用绿幕策略（见第 3 节）
+- `ALPHA`：`yes` = 支持原生透明输出；`no` = 透明素材才需要另行去背（见第 3 节）
 - `PROVIDERS`：支持该模型的 provider 数量，多个 provider 时后端按优先级自动 fallback（顺序尝试，首个成功即返回）
 
 **Prompt 套路速查**：[reference/prompt-cookbook.md](reference/prompt-cookbook.md)
@@ -40,8 +47,11 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 
 ```
 需要生图？
-├─ 追求最高质量（概念图、精品单图）？
-│  └─ gpt-image-2（3 个 provider 自动 fallback：iegg-litellm → mulerouter → 302）
+├─ 用户指定了模型，或制作流程已锁定模型？
+│  └─ 使用指定模型；失败时报告原因，不静默更换
+│
+├─ 普通图片生成 / 现有素材替换 / 含文字 Logo？
+│  └─ 优先 iegg-litellm/gpt-image-2.5-sunburst；不可用时选择清单中的 Image 2.5 并报告实际模型
 │
 ├─ 需要 --reference-image（风格一致性批量生产）？
 │  └─ 必须选 CAPABILITY = text+image 或 image→image 的模型
@@ -53,29 +63,30 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 │  └─ Edit 模型工作流（见进阶参考）
 │
 └─ 不确定？
-   └─ 先试 gpt-image-2，失败换 gemini-3.1-flash-image-preview
+   └─ 使用平台默认模型；透明素材优先清单中 ALPHA=yes 的模型
 ```
 
 ### 主要模型特性
 
-| 模型                               | 特点与优势                                                                                  | 最佳场景                                        | 速度                            | 注意事项                                                        |
-| ---------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------------------------------------- |
-| **gpt-image-2**                    | 细节最丰富、光影最真实、网格/布局理解力最强、中文字符准确率最高、3 provider fallback 容错高 | 概念图、精灵图直出、含文字素材、写实/半写实风格 | 慢(7-8min/张)，**不设 timeout** | 慢是正常的；只有 `API 500` / `fetch failed` 才切换下一 provider |
-| **gemini-3.1-flash-image-preview** | 速度快、色彩鲜艳、构图清晰、最稳定不易报错、reference-image 理解好                          | 快速迭代、扁平卡通、明亮休闲风、超时回退        | 快(<30s)                        | 精细细节和文字不如 gpt-image-2                                  |
-| **hy-image-v3.0**                  | 亚洲审美偏向、角色设计好、Q版/IP风格擅长                                                    | 中国风、Q版角色、IP 形象                        | 中等                            | 西方写实风格表现一般                                            |
-| **flux-kontext-pro**               | 艺术感强、风格独特、手绘质感好                                                              | 艺术插画、手绘风、独特画风探索                  | 中等                            | 网格理解弱，不适合精灵图                                        |
-| **nano-banana-2**                  | 最快、适合简单图形探索                                                                      | 简洁图标、平面设计、快速草稿                    | 极快                            | 中文字符不可靠、细节少                                          |
-| **qwen-image-edit-max**            | 图生图编辑能力强、局部修改精确                                                              | 换花色/换数字/换颜色等结构相似变体              | 中等                            | CAPABILITY=image→image，必须传 reference-image                  |
-| **wan2.6-image**                   | 风格迁移能力好                                                                              | 将参考图风格应用到新内容                        | 中等                            | CAPABILITY=image→image，必须传 reference-image                  |
+| 模型                               | 特点与优势                                                         | 最佳场景                                 | 速度           | 注意事项                                                          |
+| ---------------------------------- | ------------------------------------------------------------------ | ---------------------------------------- | -------------- | ----------------------------------------------------------------- |
+| **gpt-image-2.5-sunburst / flare** | 当前普通生图与素材替换的优先模型，支持参考图及原生透明输出         | Logo、角色、图标、透明素材替换           | 以实际调用为准 | 使用模型清单中的 provider/model；检查返回的实际模型和透明验证结果 |
+| **gpt-image-2**                    | 兼容已有项目和明确指定 provider 的制作流程                         | 已锁定模型的概念图、故事板、精灵图       | 以实际调用为准 | 普通素材默认优先 Image 2.5；能力和可用 provider 以模型清单为准    |
+| **gemini-3.1-flash-image-preview** | 速度快、色彩鲜艳、构图清晰、最稳定不易报错、reference-image 理解好 | 快速迭代、扁平卡通、明亮休闲风、超时回退 | 快(<30s)       | 精细细节和文字不如 gpt-image-2                                    |
+| **hy-image-v3.0**                  | 亚洲审美偏向、角色设计好、Q版/IP风格擅长                           | 中国风、Q版角色、IP 形象                 | 中等           | 西方写实风格表现一般                                              |
+| **flux-kontext-pro**               | 艺术感强、风格独特、手绘质感好                                     | 艺术插画、手绘风、独特画风探索           | 中等           | 网格理解弱，不适合精灵图                                          |
+| **nano-banana-2**                  | 最快、适合简单图形探索                                             | 简洁图标、平面设计、快速草稿             | 极快           | 中文字符不可靠、细节少                                            |
+| **qwen-image-edit-max**            | 图生图编辑能力强、局部修改精确                                     | 换花色/换数字/换颜色等结构相似变体       | 中等           | CAPABILITY=image→image，必须传 reference-image                    |
+| **wan2.6-image**                   | 风格迁移能力好                                                     | 将参考图风格应用到新内容                 | 中等           | CAPABILITY=image→image，必须传 reference-image                    |
 
 ### 选型口诀
 
-- 追求质量 / 含文字 / 网格图 → `gpt-image-2`
-- 快速迭代 / 扁平风格 / 回退备选 → `gemini-3.1-flash-image-preview`
+- 普通素材 / 含文字 / 透明元素 → 可用的 `gpt-image-2.5-sunburst`，其次 Image 2.5 系列
+- 已锁定的故事板或制作流程 → 沿用该流程指定模型，见下方 MC 专用规则
 - 中国风 / Q版 / 亚洲审美 → `hy-image-v3.0`
 - 艺术/手绘探索 → `flux-kontext-pro`
 - 纯 edit 变体 → `qwen-image-edit-max`
-- 一切都失败 → `gemini-3.1-flash-image-preview`（最稳定）
+- 模型失败 → 先检查返回错误；不要把原生透明失败自动改成 Gemini 白底生成
 
 ### 为什么精灵图直出是首选批量策略？
 
@@ -91,6 +102,54 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 
 ## 2. 核心命令
 
+### 沙箱对话中的直接工具
+
+当前对话注册了 `playcraft-generate-image` 时，直接调用它。根据本次目标素材填写参数，不固定游戏名、素材类别、参考路径、尺寸或比例：
+
+| 参数                                        | 本次取值                                                                                           |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `prompt`                                    | 目标字段与用户要求的主体、风格、文字、构图或状态；完整场景可描述背景内容，透明交付通过背景开关表达 |
+| `targetAssetPath`                           | 被替换的现有素材路径；自动加载该字段参考图和全部交付约束，避免与素材弹窗行为不一致                 |
+| `imageModelRef`                             | 普通生图可省略，由后端优先选择可用 Image 2.5；用户明确指定、字段配置或制作流程已锁定时传指定模型   |
+| `referenceImagePath`                        | 已确认可读的项目相对参考路径；优先字段 `reference_image`，其次当前素材，新素材无参考时可省略       |
+| `additionalReferenceImagePaths`             | 确有多个参考时传入其他可读路径，顺序与用途明确                                                     |
+| `aspectRatio`                               | 新素材的构图比例；现有素材由 targetAssetPath 读取字段比例和尺寸                                    |
+| `width` / `height`                          | 新素材的成对像素尺寸；有 targetAssetPath 时字段尺寸优先                                            |
+| `outputFormat` / `fitMode` / `paddingColor` | 新素材的格式、适配方式和补边颜色；有 targetAssetPath 时读取目标约束                                |
+| `removeBackground`                          | 按字段配置与素材用途决定；透明前景为 `true`，完整背景或不透明面板为 `false`                        |
+| `outputPath`                                | 本次素材的中间文件路径，沿用项目工作目录约定，验证后写回实际主题引用                               |
+
+背景、角色、道具、按钮、文字、发光状态、序列帧等各自遵守项目字段配置。成组状态或动画帧还需保持对象、风格、锚点与尺寸一致，不把单张静态图当成完整序列帧替换。
+
+`removeBackground: true` 表示需要通过验证的透明素材，不表示必须执行一次本地去背。背景优先级为字段明确规则 → 调用开关 → 提示词背景意图 → 当前图片推断；明确的透明或不透明提示词不能被旧图片的状态覆盖。保存实际 provider/model、参考图数量、请求编号、尝试次数与透明验证结论；模型清单里的默认星号不能证明本次实际使用的模型。
+
+常规生图工具的透明交付通过字段配置或 `removeBackground: true`（命令行为 `--remove-background`）表达。`prompt` 保留主体、文字、风格、构图及透明玻璃、水泡等材质；源图背景按实际模型处理：
+
+| 模型 / 流程        | 源图背景说明                                                                                                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Image 2.5          | 后端组装原生透明指令；需要重生成时改为干净纯白底再去背。调用方不追加透明、白底或色幕后缀。                                                                                                        |
+| 明确选用的其他模型 | 后端首次请求保留调用方提示词，不会自动补白底。要求透明交付时，追加单一 `on a uniform solid pure white background for subsequent background removal`，同时传透明交付开关；不要混入透明或色幕要求。 |
+| 独立色幕制作       | 仅在第 3 节的适用条件下使用；保留色幕中间图，切分后独立去背，最终仍需透明验收。                                                                                                                   |
+
+Image 2.5 的透明文生图无需参考图。生成全新素材时省略 targetAssetPath；没有参考图时直接文生图，用户提供参考图时显式传入，按用户要求传背景开关。替换现有素材时传目标路径以读取参考图和交付规格。要求透明输出时使用 PNG 或 WebP；没有格式配置的旧 .jpg 素材生成透明预览时改用 PNG。
+
+透明素材采用原生透明优先 → 后处理去背 → 最终成品验收。有参考图与无参考图都走同一交付流程：原图不透明时由后端自动分割去背，保留主体和交付规格；发现画入的棋盘格底图时不直接去背，避免留下零散灰块。棋盘格底图或去背结果不合格时，可用剩余的一次尝试在同一模型上重生成干净底图，再去背验收。模型、供应商与重新生成合计最多尝试两次，本地后处理不增加生图次数；命令行默认没有额外重试。返回 transparencySource=native 或 background-removal，区分原生透明和后处理结果。自动检查不能代替文字、主体完整性及深浅背景下的视觉验收。最终仍失败时报告请求编号与失败阶段并停止；不要在 Agent 层自行换模型、关闭透明要求或把棋盘格、透明补边当作成功。
+
+未注册直接工具时使用下方 CLI (Command-Line Interface, 命令行工具) 入口。若返回 `Business tool protocol unavailable (501); no operation was sent`，本次没有发出生图请求：修复入口或使用已注册的直接工具，不要通过换模型反复重试。
+
+### 现有素材替换
+
+先用 `playcraft tools image-context --asset-path <现有素材路径>` 查看本地解析结果；新命令不存在时更新已固定版本的命令行工具，不能跳过上下文继续生成。
+
+```bash
+playcraft tools generate-image \
+  --target-asset "$TARGET_ASSET_PATH" \
+  --prompt "$IMAGE_PROMPT" \
+  --output "$PREVIEW_OUTPUT_PATH"
+```
+
+变量填写本次素材路径、用户生成要求与工作目录中的预览路径。此入口自动传递该素材的参考图和交付约束；验证通过后再应用到目标主题。新素材没有目标文件时才手动传 `--width` / `--height`、`--output-format`、`--fit-mode`、`--padding-color` 与 `--remove-background` 或 `--no-remove-background`。不透明背景和面板用后者，避免提示词误触发透明推断。
+
 ### 文生图（text-to-image）
 
 ```bash
@@ -99,7 +158,7 @@ playcraft tools generate-image \
   --output assets/images/sword.png \
   --aspect-ratio 1:1 \
   --image-size 4K \
-  --image-model gpt-image-2
+  --image-model iegg-litellm/gpt-image-2.5-sunburst
 ```
 
 ### 图生图（image-to-image / reference-image）
@@ -111,7 +170,7 @@ playcraft tools generate-image \
   --reference-image assets/images/sword.png \
   --aspect-ratio 1:1 \
   --image-size 4K \
-  --image-model gpt-image-2
+  --image-model iegg-litellm/gpt-image-2.5-sunburst
 ```
 
 ### 参数说明
@@ -183,24 +242,16 @@ playcraft image sprite-sheet \
 
 ## 3. 背景处理决策树
 
-> **核心原则**：先确定素材类型，再决定是否需要去背景，再按素材主色调选择色幕颜色，最后做去背景 + 深色背景验证。
+> **核心原则**：先确定素材类型与最终背景要求；常规工具按第 2 节的模型规则准备源图并由后端验收，独立色幕流程才选择色幕颜色，交付后做深浅背景验证。
 
 ```
 生成的素材需要做什么？
 │
 ├─ 需要透明背景的独立元素（角色、道具、图标、文字图片、HUD、VFX）？
-│   ├─ 检查模型 ALPHA 列（playcraft tools list-image-models）
-│   ├─ ALPHA = yes → prompt 加 "transparent background, PNG with alpha"
-│   └─ ALPHA = no  → 色幕策略（按素材主色调选择）：
-│       ├─ 素材为金色/黄色/橙色/绿色 → 蓝幕 #0000FF
-│       │   ├─ prompt 末尾加 "on solid bright blue #0000FF background, isolated, centered"
-│       │   └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
-│       ├─ 素材为蓝色/紫色/靛蓝 → 绿幕 #00FF00
-│       │   ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
-│       │   └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
-│       └─ 其他颜色 → 绿幕 #00FF00（默认）
-│           ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
-│           └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│   ├─ 常规工具 → removeBackground=true / --remove-background
+│   │   └─ 按模型准备源图背景（第 2 节）→ 原生透明或去背 → 最终透明验收
+│   └─ 已明确选择独立色幕制作流程？
+│       └─ 关闭中间图自动去背 → 单一色幕 → 切分后独立去背 → 深浅背景验证
 │
 ├─ 卡牌/棋盘格子/UI 面板（本身就是矩形有边框）？
 │   ├─ 不要去背景！白色牌面就是牌的一部分
@@ -215,7 +266,16 @@ playcraft image sprite-sheet \
 
 ### 为什么需要色幕策略？
 
-**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。纯色背景 + 非撞色游戏素材 = 抠图几乎完美。与影视 chroma-key 原理相同。
+只有用户或已锁定的制作流程明确选择独立色幕制作，且所选模型不支持原生透明时才采用该流程；仅指定其他模型并不等于选择色幕。下方色幕矩阵和后缀表仅用于该流程与 ASR (Asset State Reference, 资产状态参考板)，不能用作 Image 2.5 失败后的自动回退。原生透明图验证通过后直接处理尺寸，不再重复去背；发光、半透明边缘和白色前景应保留。白色背景与白色物体会让 floodfill 混淆边界。`playcraft image remove-background` 默认使用本地 floodfill，不应描述为必然调用后端去背模型。
+
+色幕**中间图**使用 `removeBackground: false` / `--no-remove-background`，让生成工具保留指定色幕，再独立去背；这不改变最终素材的透明交付要求。替换现有透明字段时，先用 `image-context` 读取参考图和交付规格，生成中间图时省略 `targetAssetPath` / `--target-asset`，显式传入已读取的参考图、尺寸与格式。字段的 `remove_background=true` 优先于调用开关，绑定该字段会提前触发自动去背；`--no-target-reference` 也不会解除字段约束。色幕去背及最终验收通过后再应用到目标字段。
+
+### 最终文件验证
+
+- 按字段 resolution 处理尺寸，透明前景用 `--fit contain`，确认执行的工具使用透明补边；旧版工具可能补入不透明黑色。验证不通过时更新工具或显式使用透明背景缩放。
+- 按实际资源扩展名编码，不把 PNG 内容写进其他格式的文件，也不擅自改变主题引用。
+- 去背、缩放、转格式后都检查透明通道与边缘，并分别在深色和浅色背景上预览。允许素材自身的黑色描边，拒绝额外黑色矩形补边或误删的发光效果。
+- 达到项目的文件大小限制后再覆盖目标文件。同一 Logo 的多个尺寸从同一张母图导出，避免重复生成导致风格漂移。
 
 ### 色幕选型矩阵（Color Conflict Avoidance）
 
@@ -271,6 +331,7 @@ playcraft image overlay \
 **Artist ASR prompt 要点**：
 
 1. Sheet canvas：`solid flat #808080` 或整板统一绿幕（非渐变）
+   生成整板时传 `--no-remove-background`，保留格子布局和色幕供后续裁切。
 2. 每格：`ONE isolated element, centered, NO white box, NO scene, NO ground shadow`
 3. 金/橙/黄/绿元素格 → cell 背景 `#0000FF`；蓝/紫 → `#00FF00`
 4. 生成后**目视**格内可抠性 — 不要求 `channels=4`（那是 TA 后处理产物）
@@ -280,7 +341,7 @@ playcraft image overlay \
 ## 4. 脚本决策
 
 - **<=5 个文件** → 直接使用 CLI 命令
-- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录。
+- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录；使用本次选定的模型与参考图，不直接沿用脚本中旧的默认模型。
 
 ---
 
@@ -288,11 +349,11 @@ playcraft image overlay \
 
 需要以下进阶内容时，查阅 [`refs/ta-image-generation-detail.md`](../../agents/refs/ta-image-generation-detail.md)：
 
-| 主题                  | 说明                                                                |
-| --------------------- | ------------------------------------------------------------------- |
-| 精灵图直出策略        | gpt-image-2 网格图生成 + sprite-split 切分，白底/绿幕示例，分批策略 |
-| Edit 模型工作流       | 基图 → edit 变体（换花色/换数字/换颜色），prompt 写法               |
-| 错误恢复表            | 各类错误现象、原因、立即行动；模型回退顺序                          |
-| Provider 回退链       | gpt-image-2 三 provider 互为回退 + 非 gpt-image-2 稳定回退          |
-| 批量生成最佳实践      | 单张验证、Node.js 脚本推荐、脚本模板使用                            |
-| ta-workspace 脚本驱动 | 为什么用 Node.js、目录约定、脚本模板一览表                          |
+| 主题                  | 说明                                                             |
+| --------------------- | ---------------------------------------------------------------- |
+| 精灵图直出策略        | 按选定模型生成网格图 + sprite-split 切分；自动透明与独立色幕示例 |
+| Edit 模型工作流       | 基图 → edit 变体（换花色/换数字/换颜色），prompt 写法            |
+| 错误恢复表            | 各类错误现象、原因、立即行动；模型回退顺序                       |
+| Provider 回退链       | gpt-image-2 三 provider 互为回退 + 非 gpt-image-2 稳定回退       |
+| 批量生成最佳实践      | 单张验证、Node.js 脚本推荐、脚本模板使用                         |
+| ta-workspace 脚本驱动 | 为什么用 Node.js、目录约定、脚本模板一览表                       |