@playcraft/cli 0.1.37-beta → 0.1.39-prod

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,15 +102,72 @@ 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 时读取目标约束                                                                                                     |
+| `background`                                | **必填**。根据完整对话上下文和字段配置选择；仅用户或字段明确要求背景时选择 `opaque`，其余选择 `transparent`，不能仅按素材用途决定；Remix 未明确要求时选择 `transparent` |
+| `outputPath`                                | 后端完成交付处理后的最终预览文件路径，沿用项目工作目录约定，视觉验收后写回实际主题引用                                                                                  |
+
+背景、角色、道具、按钮、文字、发光状态、序列帧等各自遵守项目字段配置。成组状态或动画帧还需保持对象、风格、锚点与尺寸一致，不把单张静态图当成完整序列帧替换。
+
+`background: transparent` 表示需要通过验证的透明素材，不表示必须执行一次本地去背。背景优先级为字段明确规则 → 对话模型的结构化选择。每次调用前由当前 Agent 结合完整对话判断，不依赖生图提示词关键词或旧图片的不透明状态；“不需要背景”“不要保留背景”选择 `transparent`。后端直接执行选择并校验成品，只有旧调用省略背景选择时才沿用提示词推断兼容路径，不额外请求一次对话模型。保存实际 provider/model、参考图数量、请求编号、尝试次数与透明验证结论；模型清单里的默认星号不能证明本次实际使用的模型。
+
+常规生图工具的透明交付通过必填 `background: transparent`（命令行为 `--background transparent`）表达；保留背景选择 `opaque`。字段配置仍为最高约束。`prompt` 保留主体、文字、风格、构图及透明玻璃、水泡等材质；源图背景按实际模型处理：
+
+| 模型 / 流程        | 源图背景说明                                                                                                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Image 2.5          | 后端组装原生透明指令及必要的恢复请求，交付顺序见下文。调用方不追加透明、白底或色幕后缀。                                                                                                          |
+| 明确选用的其他模型 | 后端首次请求保留调用方提示词，不会自动补白底。要求透明交付时，追加单一 `on a uniform solid pure white background for subsequent background removal`，同时传透明交付开关；不要混入透明或色幕要求。 |
+| 独立色幕制作       | 仅在第 3 节的适用条件下使用；保留色幕中间图，切分后独立去背，最终仍需透明验收。                                                                                                                   |
+
+Image 2.5 的透明文生图无需参考图。生成全新素材时省略 targetAssetPath；没有参考图时直接文生图，用户提供参考图时显式传入，按用户要求传背景开关。替换现有素材时传目标路径以读取参考图和交付规格。要求透明输出时使用 PNG 或 WebP；没有格式配置的旧 .jpg 素材生成透明预览时改用 PNG。
+
+透明交付由后端完成，有参考图与无参考图采用相同规则，按入口区分：
+
+- **Remix 项目对话**：先直接生成透明图；透明验证不合格时只生成一张干净纯色原图，再把它交给支持透明编辑的模型去底；模型编辑报错或结果不合格，才对同一张纯色原图执行本地去背。模型不支持透明编辑时直接进入本地兜底。不使用失败的编辑结果做本地输入，不为本地兜底重新生成纯色图，也不在 Agent 层额外重复去背。
+- **其他生图入口**：保留原生透明优先、必要时本地去背及最终验收的原有行为，不套用 Remix 的额外模型编辑步骤。
+
+首次生成阶段最多尝试两次供应商请求；Remix 仅在收到不合格图片后保留恢复次数：一次纯色源图生成，每张源图一次模型编辑。单图正常最多三次模型请求，若首次供应商请求失败则最多四次；批量恢复最多为首次阶段两次加一次纯色源图批量请求、每张一次编辑。本地后处理不增加模型请求数。其他 Agent 生图入口的模型、供应商与重新生成合计仍最多尝试两次；命令行默认没有额外重试。
+
+返回 `transparencySource=native`、`model-edit` 或 `background-removal`，分别表示原生透明、模型去底或本地去背。对话中的 `Image preview:` 地址保存的是后端最终成品，并独立于可编辑的沙箱文件；不要把恢复过程中的纯色原图展示为最终成品。自动检查只能判断透明通道、非空前景及画入的棋盘格等问题，不能代替文字、主体完整性、孔洞及深浅背景下的视觉验收。最终仍失败时报告请求编号与失败阶段并停止，不自行换模型、关闭透明要求或把透明补边当作成功。
+
+未注册直接工具时使用下方 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" \
+  --background "$BACKGROUND_MODE" \
+  --output "$PREVIEW_OUTPUT_PATH"
+```
+
+变量填写本次素材路径、用户生成要求与工作目录中的预览路径；`BACKGROUND_MODE` 由当前对话 Agent 明确选择 `transparent` 或 `opaque`，每次生图都传入。此入口自动传递该素材的参考图和交付约束；验证通过后再应用到目标主题。新素材没有目标文件时才手动传 `--width` / `--height`、`--output-format`、`--fit-mode`、`--padding-color`。旧脚本的 `--remove-background` / `--no-remove-background` 继续兼容，新 Agent 调用统一使用 `--background`。
+
 ### 文生图（text-to-image）
 
 ```bash
 playcraft tools generate-image \
   --prompt "A golden sword icon, flat 2D vector style, centered composition" \
+  --background transparent \
   --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）
@@ -107,17 +175,19 @@ playcraft tools generate-image \
 ```bash
 playcraft tools generate-image \
   --prompt "A similar style silver shield icon, same art direction" \
+  --background transparent \
   --output assets/images/shield.png \
   --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
 ```
 
 ### 参数说明
 
 | 参数                   | 值                                        | 说明                                                    |
 | ---------------------- | ----------------------------------------- | ------------------------------------------------------- |
+| `--background`         | `transparent` / `opaque`                  | Agent 调用必填，由完整对话上下文决定；字段约束优先      |
 | `--aspect-ratio`       | `1:1` / **`45:16`** / `16:9` / `9:16` / … | **Master Composite（5×9:16 横排）用 `45:16`**           |
 | `--width` / `--height` | 像素整数（成对）                          | MC 推荐 **`3600×1280`** 或 **`4096×1455`**              |
 | `--image-size`         | `1K` / `2K` / `4K`                        | 控制分辨率级别。实际像素取决于模型+比例的组合（见下表） |
@@ -183,39 +253,38 @@ 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）→ 深色背景验证
+├─ 字段有明确背景约束？
+│   └─ 严格遵守字段要求：remove_background=true → transparent；false → opaque
 │
-├─ 卡牌/棋盘格子/UI 面板（本身就是矩形有边框）？
-│   ├─ 不要去背景！白色牌面就是牌的一部分
-│   ├─ prompt 加 "flat 2D, no drop shadow, no 3D effect, clean edges"
-│   └─ 后处理：直接 resize（skipRemoveBg = true）
+├─ 字段无明确约束，且用户明确要求保留背景/完整场景？
+│   ├─ background=opaque / --background opaque，交付整张不透明图片
+│   └─ 满幅场景 prompt 加 "full bleed, edge to edge, no vignette, no fade"
 │
-└─ 场景背景（天空、地面、全屏图）？
-    ├─ 不做背景处理，直接 resize
-    └─ ⚠️ prompt 必须加 "full bleed, edge to edge, no vignette, no fade"
-       → 后处理验证：四角四边颜色一致，无褪色/白色
+└─ 字段无明确约束，且用户未明确要求背景？
+    └─ background=transparent / --background transparent（包括卡牌、棋子和面板）
+        ├─ 白色牌面、边框与文字属于前景，必须保留，只移除本体外的画布背景
+        ├─ 常规工具 → 按模型准备源图背景（第 2 节）→ 原生透明或去背 → 最终透明验收
+        └─ 已明确选择独立色幕制作流程？
+            └─ 中间图 background=opaque → 单一色幕 → 切分后独立去背 → 深浅背景验证
 ```
 
 ### 为什么需要色幕策略？
 
-**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。纯色背景 + 非撞色游戏素材 = 抠图几乎完美。与影视 chroma-key 原理相同。
+只有用户或已锁定的制作流程明确选择独立色幕制作，且所选模型不支持原生透明时才采用该流程；仅指定其他模型并不等于选择色幕。下方色幕矩阵和后缀表仅用于该流程与 ASR (Asset State Reference, 资产状态参考板)，不能用作 Image 2.5 失败后的自动回退。原生透明图验证通过后直接处理尺寸，不再重复去背；发光、半透明边缘和白色前景应保留。白色背景与白色物体会让 floodfill 混淆边界。`playcraft image remove-background` 默认使用本地 floodfill，不应描述为必然调用后端去背模型。
+
+色幕**中间图**使用 `background: opaque` / `--background opaque`，让生成工具保留指定色幕，再独立去背；这不改变最终素材的透明交付要求。替换现有透明字段时，先用 `image-context` 读取参考图和交付规格，生成中间图时省略 `targetAssetPath` / `--target-asset`，显式传入已读取的参考图、尺寸与格式。字段的 `remove_background=true` 优先于调用开关，绑定该字段会提前触发自动去背；`--no-target-reference` 也不会解除字段约束。色幕去背及最终验收通过后再应用到目标字段。
+
+### 最终文件验证
+
+- 按字段 resolution 处理尺寸，透明前景用 `--fit contain`，确认执行的工具使用透明补边；旧版工具可能补入不透明黑色。验证不通过时更新工具或显式使用透明背景缩放。
+- 按实际资源扩展名编码，不把 PNG 内容写进其他格式的文件，也不擅自改变主题引用。
+- 去背、缩放、转格式后都检查透明通道与边缘，并分别在深色和浅色背景上预览。允许素材自身的黑色描边，拒绝额外黑色矩形补边或误删的发光效果。
+- 达到项目的文件大小限制后再覆盖目标文件。同一 Logo 的多个尺寸从同一张母图导出，避免重复生成导致风格漂移。
 
 ### 色幕选型矩阵（Color Conflict Avoidance）
 
@@ -231,15 +300,17 @@ playcraft image sprite-sheet \
 
 ### Prompt 后缀速查表
 
-| 素材类型                   | prompt 建议后缀                                                     | 后处理                                      | skipRemoveBg |
-| -------------------------- | ------------------------------------------------------------------- | ------------------------------------------- | ------------ |
-| 独立元素（需透明，非金色） | `"on solid bright green #00FF00 background, isolated, centered"`    | remove-background (tolerance 25) → 深色验证 | `false`      |
-| 独立元素（金/黄/橙/绿色）  | `"on solid bright blue #0000FF background, isolated, centered"`     | remove-background (tolerance 25) → 深色验证 | `false`      |
-| 独立元素（多色/彩虹）      | `"on solid bright magenta #FF00FF background, isolated, centered"`  | remove-background (tolerance 20) → 深色验证 | `false`      |
-| VFX 特效（发光/粒子）      | `"on solid bright blue #0000FF background, isolated, centered"`     | remove-background (tolerance 25) → 逐帧验证 | `false`      |
-| 卡牌/棋子（矩形本体）      | `"flat 2D, no shadow, no 3D effect, clean edges, white background"` | 只做 resize                                 | `true`       |
-| UI 按钮/面板               | `"flat UI element, no shadow, clean edges"`                         | trim + resize                               | `true`       |
-| 场景背景                   | `"full scene, full bleed, edge to edge, no vignette, no fade"`      | resize → 四角全覆盖检查                     | `true`       |
+下表的色幕后缀只用于已明确选择的独立色幕流程。卡牌、面板等最终交付仍按上方决策树选择；`skipRemoveBg` 只表示是否跳过独立去背步骤，不能据此把最终交付改为不透明。
+
+| 素材类型                    | prompt 建议后缀                                                    | 后处理                                      | skipRemoveBg            |
+| --------------------------- | ------------------------------------------------------------------ | ------------------------------------------- | ----------------------- |
+| 独立元素（需透明，非金色）  | `"on solid bright green #00FF00 background, isolated, centered"`   | remove-background (tolerance 25) → 深色验证 | `false`                 |
+| 独立元素（金/黄/橙/绿色）   | `"on solid bright blue #0000FF background, isolated, centered"`    | remove-background (tolerance 25) → 深色验证 | `false`                 |
+| 独立元素（多色/彩虹）       | `"on solid bright magenta #FF00FF background, isolated, centered"` | remove-background (tolerance 20) → 深色验证 | `false`                 |
+| VFX 特效（发光/粒子）       | `"on solid bright blue #0000FF background, isolated, centered"`    | remove-background (tolerance 25) → 逐帧验证 | `false`                 |
+| 卡牌/棋子（矩形本体）       | `"flat 2D, white card face, no shadow, clean edges"`               | 默认透明画布，保留牌面；透明已验收后 resize | 仅透明已验收后为 `true` |
+| UI 按钮/面板                | `"flat UI element, no shadow, clean edges"`                        | 默认透明画布；透明已验收后 trim + resize    | 仅透明已验收后为 `true` |
+| 用户/字段明确要求的场景背景 | `"full scene, full bleed, edge to edge, no vignette, no fade"`     | 不透明交付 → resize → 四角全覆盖检查        | `true`                  |
 
 ### 去背景后必做：深色背景渲证
 
@@ -271,6 +342,7 @@ playcraft image overlay \
 **Artist ASR prompt 要点**：
 
 1. Sheet canvas：`solid flat #808080` 或整板统一绿幕（非渐变）
+   生成整板时传 `--background opaque`，保留格子布局和色幕供后续裁切。
 2. 每格：`ONE isolated element, centered, NO white box, NO scene, NO ground shadow`
 3. 金/橙/黄/绿元素格 → cell 背景 `#0000FF`；蓝/紫 → `#00FF00`
 4. 生成后**目视**格内可抠性 — 不要求 `channels=4`（那是 TA 后处理产物）
@@ -280,7 +352,7 @@ playcraft image overlay \
 ## 4. 脚本决策
 
 - **<=5 个文件** → 直接使用 CLI 命令
-- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录。
+- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录；使用本次选定的模型与参考图，不直接沿用脚本中旧的默认模型。
 
 ---
 
@@ -288,11 +360,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、目录约定、脚本模板一览表                       |

package/project-templates/phaser/.claude/skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs

@@ -1,7 +1,7 @@
 // ============================================================
-// gen-batch-sprite.template.mjs — gpt-image-2 精灵图直出脚本模板
+// gen-batch-sprite.template.mjs — 精灵图直出脚本模板
 //
-// 核心原则：让 gpt-image-2 一次 API 调用直接生成包含多个元素的
+// 核心原则：一次 API (Application Programming Interface, 应用程序编程接口) 调用生成包含多个元素的
 // 网格精灵图，然后用 sprite-split 切分。比逐个生成效率高 N 倍。
 //
 // 适用场景：
@@ -34,11 +34,11 @@ function playcraft(args, { capture = false, timeout } = {}) {
 // ============ CONFIG — 修改这里 ============
 const CONFIG = {
   /**
-   * 精灵图直出模型：永远用 gpt-image-2（图像理解 + 布局能力最强）
-   * mulerouter 质量更高（建议作为主模型），iegg 更快（备用）
-   * 注意：精灵图生成比单图慢，通常需要 90-150s，timeout 设 240 以上
+   * 使用 list-image-models 核实本次模型；默认示例为 Image 2.5。
+   * 用户或制作流程锁定其他模型时填写实际 provider/model。
+   * 请求使用命令行默认等待时间，不在脚本中提前杀死仍在运行的请求。
    */
-  model: 'mulerouter/gpt-image-2',
+  model: 'iegg-litellm/gpt-image-2.5-sunburst',
 
   /**
    * 每批精灵图的列数
@@ -64,21 +64,20 @@ const CONFIG = {
   /**
    * 通用风格描述（追加到每个批次 prompt 末尾）
    *
-   * 元素需要透明背景（独立元素：角色/车/道具/图标）→ 绿幕策略：
-   *   style: 'flat 2D illustration, isolated on solid bright green #00FF00 background, centered, no shadow'
-   *   removeBg: true  （切分后逐帧去背景）
-   *
-   * 元素本身就是矩形（卡牌/棋子/UI 面板）→ 白底策略：
-   *   style: 'flat 2D, white background, no shadow, no drop shadow, clean edges'
-   *   removeBg: false
+   * 只填写主体风格与构图，源图背景由下方流程选择。
+   * 卡牌白色牌面属于主体，应在 items.desc 中描述并设 removeBg=false。
    */
-  style: 'flat 2D illustration, isolated on solid bright green #00FF00 background, centered, no shadow',
+  style: 'flat 2D illustration, isolated subjects, centered, no shadow',
   /**
-   * 切分后是否对每帧执行 remove-background（绿幕去背景）
-   * true  → 独立元素（需透明通道）：remove-background --tolerance 25
-   * false → 卡牌/UI 面板等矩形元素：直接 resize，不去背景
+   * 最终是否需要透明：true 为独立元素，false 为不透明牌面/场景。
+   * automatic：整板由工具交付透明，切分后保留，不重复去背。
+   * chroma：保留色幕中间图，切分后逐格去背；仅限主文第 3 节明确选择的流程。
    */
   removeBg: true,
+  backgroundMode: 'automatic',
+  /** 独立色幕才使用；按主体颜色选择，金/黄/橙/绿用蓝幕，蓝/紫用绿幕。 */
+  chromaColor: '#00FF00',
+  chromaTolerance: 25,
 
   /**
    * 切分单元尺寸（像素）。留空（null）= 自动按精灵图实际像素尺寸 ÷ 网格推导（推荐）。
@@ -119,7 +118,7 @@ const BATCHES = [
 // ============ 精灵图 Prompt 构建器 ============
 /**
  * 根据 items 列表构建精灵图网格 prompt
- * 关键词组合让 gpt-image-2 理解"网格布局"意图
+ * 描述网格布局，避免重绘边框或格子标签。
  */
 /**
  * 读取精灵图实际像素尺寸（用于自动推导切分单元尺寸）。
@@ -138,7 +137,7 @@ function readSheetDims(sheetPath) {
   return null;
 }
 
-function buildSpriteSheetPrompt(items, columns, style, removeBg) {
+function buildSpriteSheetPrompt(items, columns, config) {
   const actualRows = Math.ceil(items.length / columns);
   const cellDescs = items.map((item, i) => {
     const col = (i % columns) + 1;
@@ -146,10 +145,13 @@ function buildSpriteSheetPrompt(items, columns, style, removeBg) {
     return `[Row${row},Col${col}]: ${item.desc}`;
   }).join('; ');
 
-  // 绿幕模式强制在 prompt 里明确背景色，避免模型用白底
-  const bgInstruction = removeBg
-    ? 'Each element isolated on solid bright green #00FF00 background, no shadow, no gradient background.'
-    : 'Each element on clean white background.';
+  // Image 2.5 由后端组装背景；其他模型首次请求需明确单一干净底色。
+  const modelId = config.model.trim().split('/').at(-1);
+  const nativeBackground = /^gpt-image-2\.5(?:$|-)/.test(modelId);
+  const bgInstruction = !config.removeBg ? '' : config.backgroundMode === 'chroma'
+    ? `Each element isolated on a uniform solid ${config.chromaColor} background, no shadow, no gradient background.`
+    : nativeBackground ? ''
+      : 'Render all foreground elements on a uniform solid pure white background for subsequent background removal. Preserve all elements, text, white details, colors and style.';
 
   return [
     `Sprite sheet grid layout, ${columns} columns × ${actualRows} rows.`,
@@ -157,13 +159,19 @@ function buildSpriteSheetPrompt(items, columns, style, removeBg) {
     bgInstruction,
     `Grid layout, uniform cell size, equal spacing, elements perfectly centered in each cell.`,
     `No borders between cells, no labels, no numbers on cells.`,
-    style,
-  ].join(' ');
+    config.style,
+  ].filter(Boolean).join(' ');
 }
 
 // ============ LOGIC — 通常不需要修改 ============
 
 const LOG_FILE = 'ta-workspace/logs/gen-batch-sprite.log';
+if (!['automatic', 'chroma'].includes(CONFIG.backgroundMode)) {
+  throw new Error('backgroundMode must be automatic or chroma.');
+}
+if (CONFIG.backgroundMode === 'chroma' && !/^#[\da-f]{6}$/i.test(CONFIG.chromaColor)) {
+  throw new Error('chromaColor must be one six-digit hex color.');
+}
 mkdirSync(CONFIG.sheetDir, { recursive: true });
 mkdirSync(CONFIG.outputDir, { recursive: true });
 mkdirSync('ta-workspace/logs', { recursive: true });
@@ -190,7 +198,7 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
     log(`[SKIP-SHEET] (${bi + 1}/${BATCHES.length}) ${batch.sheetName} already exists`);
   } else {
     log(`[GEN-SHEET ] (${bi + 1}/${BATCHES.length}) Generating ${batch.sheetName} (${batch.items.length} elements)`);
-    const prompt = buildSpriteSheetPrompt(batch.items, CONFIG.columns, CONFIG.style, CONFIG.removeBg);
+    const prompt = buildSpriteSheetPrompt(batch.items, CONFIG.columns, CONFIG);
 
     try {
       playcraft(
@@ -200,9 +208,9 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
           '--output', sheetPath,
           '--aspect-ratio', CONFIG.aspectRatio,
           '--image-model', CONFIG.model,
-          '--timeout', '240',
+          CONFIG.removeBg && CONFIG.backgroundMode === 'automatic'
+            ? '--remove-background' : '--no-remove-background',
         ],
-        { timeout: 300_000 },
       );
       log(`[OK-SHEET  ] ${batch.sheetName}`);
     } catch (e) {
@@ -269,10 +277,11 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
     continue;
   }
 
-  // ── Step 3: 重命名（+可选绿幕去背景）切分结果到最终位置 ─────────
+  // ── Step 3: 保留自动透明结果；独立色幕才逐格去背 ────────────────
   // 任何缺帧 / 处理失败都视为该批次失败（FAIL，不是 WARN）：一个不完整的
   // 批次绝不能被报成 OK-BATCH，否则下游会拿到缺图的资产集。
-  log(`[RENAME    ] Renaming ${batch.items.length} cells${CONFIG.removeBg ? ' + remove-background' : ''}`);
+  const removeCellBackground = CONFIG.removeBg && CONFIG.backgroundMode === 'chroma';
+  log(`[RENAME    ] Renaming ${batch.items.length} cells${removeCellBackground ? ' + remove-background' : ''}`);
   let processedOk = 0;
   let batchFailed = false;
   for (let j = 0; j < batch.items.length; j++) {
@@ -289,13 +298,13 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
       continue;
     }
     try {
-      if (CONFIG.removeBg) {
-        // 绿幕去背景（tolerance 25 适合纯绿色 #00FF00 背景）
+      if (removeCellBackground) {
+        // 只处理独立色幕，保留常规工具已经交付的透明边缘。
         playcraft([
           'image', 'remove-background',
           '--input', srcPath,
           '--output', dstPath,
-          '--tolerance', '25',
+          '--tolerance', String(CONFIG.chromaTolerance),
         ]);
       } else {
         copyFileSync(srcPath, dstPath);

package/project-templates/phaser/.claude/skills/playcraft-image-generation/reference/gen-batch.template.mjs

@@ -1,5 +1,5 @@
 // ============================================================
-// gen-batch.template.mjs — 批量 AI 生图脚本模板
+// gen-batch.template.mjs — 批量 AI (Artificial Intelligence, 人工智能) 生图脚本模板
 // 用途：从零批量生成一组风格一致的素材（reference-image 模式）
 //
 // 使用方式：
@@ -8,22 +8,18 @@
 //   3. node ta-workspace/scripts/gen-<name>.mjs
 // ============================================================
 
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { existsSync, mkdirSync, appendFileSync } from 'fs';
 
 // ============ CONFIG — 修改这里 ============
 const CONFIG = {
   /**
    * 生图模型。
-   * - Phase 1 概念图（追求质量）：用 gpt-image-2
-   *   model: 'iegg-litellm/gpt-image-2'
-   * - Phase 2 批量（reference-image 一致性）：用 google/，更稳定
-   *   model: 'google/gemini-3.1-flash-image-preview'
-   *
-   * 后端按优先级自动 fallback 多个 provider，无需手动指定 provider。
-   * text+image CAPABILITY 的模型才支持 --reference-image
+   * 先 list-image-models，再填写本次实际模型；普通素材优先 Image 2.5。
+   * 用户或制作流程锁定其他模型时保留其选择。
+   * 参考图要求模型支持 text+image 或 image→image。
    */
-  model: 'google/gemini-3.1-flash-image-preview',
+  model: 'iegg-litellm/gpt-image-2.5-sunburst',
   /** 概念图路径（确认过风格的样本，所有后续图的参考来源） */
   referenceImage: 'assets/images/concept/approved_sample.png',
   /** 输出目录 */
@@ -32,9 +28,11 @@ const CONFIG = {
   aspectRatio: '1:1',
   /**
    * 统一风格描述（从 design-brief.md 复制，粘贴到每个 prompt 末尾）
-   * 示例："flat 2D icon, vibrant colors, clean edges, white background, no shadow"
+   * 示例："flat 2D icon, vibrant colors, clean edges, no shadow"
    */
   style: '<从 design-brief 复制的统一风格描述>',
+  /** 最终透明设 true；完整场景或不透明牌面设 false。独立色幕使用精灵图模板。 */
+  removeBackground: true,
 };
 // ============ DATA — 定义要生成的素材列表 ============
 const ITEMS = [
@@ -72,17 +70,17 @@ for (let i = 0; i < ITEMS.length; i++) {
 
   log(`[GEN ] (${i + 1}/${ITEMS.length}) ${item.name}`);
 
-  const promptEscaped = `${item.desc}. ${CONFIG.style}`.replace(/"/g, '\\"');
-  const cmd =
-    `playcraft tools generate-image` +
-    ` --prompt "${promptEscaped}"` +
-    ` --output "${outPath}"` +
-    ` --aspect-ratio ${CONFIG.aspectRatio}` +
-    ` --reference-image "${CONFIG.referenceImage}"` +
-    ` --image-model "${CONFIG.model}"`;
+  const nativeBackground = /^gpt-image-2\.5(?:$|-)/.test(CONFIG.model.trim().split('/').at(-1));
+  const sourceBackground = CONFIG.removeBackground && !nativeBackground
+    ? 'on a uniform solid pure white background for subsequent background removal' : '';
+  const prompt = [item.desc, CONFIG.style, sourceBackground].filter(Boolean).join('. ');
+  const args = ['tools', 'generate-image', '--prompt', prompt, '--output', outPath,
+    '--aspect-ratio', CONFIG.aspectRatio, '--image-model', CONFIG.model,
+    CONFIG.removeBackground ? '--remove-background' : '--no-remove-background'];
+  if (CONFIG.referenceImage) args.push('--reference-image', CONFIG.referenceImage);
 
   try {
-    execSync(cmd, { stdio: 'inherit', timeout: 120_000 });
+    execFileSync('playcraft', args, { stdio: 'inherit' });
     done++;
     log(`[OK  ] ${item.name}`);
   } catch (e) {

package/project-templates/phaser/.claude/skills/playcraft-image-generation/reference/process-batch.template.mjs

@@ -8,10 +8,9 @@
 //   3. node ta-workspace/scripts/process-<name>.mjs
 //
 // 背景处理决策（修改 CONFIG.skipRemoveBg 前请阅读）：
-//   - 独立元素（角色/道具/图标）需透明背景 → skipRemoveBg = false（默认）
-//     建议生图时 prompt 加 "on solid bright green #00FF00 background, isolated"
-//   - 卡牌/棋子/UI面板（矩形本体不需透明）→ skipRemoveBg = true
-//     生图时 prompt 加 "flat 2D, no shadow, no 3D effect, clean edges"
+//   - 常规工具已验证透明 / 不透明牌面或场景 → skipRemoveBg = true（默认）
+//   - 明确选择的独立色幕中间图 → skipRemoveBg = false，按主文第 3 节选择色幕
+//     生成中间图时用 --no-remove-background，最终去背后验证透明边缘
 // ============================================================
 
 import { execSync } from 'child_process';
@@ -32,10 +31,10 @@ const CONFIG = {
   targetH: 128,
   /**
    * 跳过去背景步骤
-   * - false（默认）：执行 remove-background（绿幕素材/独立元素）
-   * - true：跳过，只做 trim + resize（卡牌/棋子等矩形本体素材）
+   * - true（默认）：保留已验证透明的结果或不透明牌面/场景，不重复去背
+   * - false：仅对独立色幕中间图执行 remove-background
    */
-  skipRemoveBg: false,
+  skipRemoveBg: true,
   /**
    * floodfill 容差（0–255）
    * 绿幕背景建议 25；默认白背景可用 15