@playcraft/cli 0.1.23 → 0.1.24

package/project-template/.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 时，从实际资源引用、当前图片的尺寸和用户需求确定这些参数；不要套用其他游戏的字段、路径或尺寸。
+
+替换素材时优先使用字段配置的 reference_image，没有配置时使用当前素材。查看图片或在对话中选中素材不等于把它传给生图模型：必须设置 referenceImagePath 或 --reference-image，并确认文件可读。仅调整风格时保留原有文字、构图和用途；用户要求重新命名或重做构图时再改变。
+
+生图前运行模型发现命令，核实当前账号可用的模型与透明输出能力：
 
 ```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,26 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 
 ## 2. 核心命令
 
+### 沙箱对话中的直接工具
+
+当前对话注册了 `playcraft-generate-image` 时，直接调用它。根据本次目标素材填写参数，不固定游戏名、素材类别、参考路径、尺寸或比例：
+
+| 参数                            | 本次取值                                                                                                 |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `prompt`                        | 目标字段的生成说明与用户需求；按素材用途明确背景、文字、构图或状态要求                                   |
+| `imageModelRef`                 | 当前清单中可用的模型，普通生图优先 `iegg-litellm/gpt-image-2.5-sunburst`；遵守用户或已锁定流程的模型选择 |
+| `referenceImagePath`            | 已确认可读的项目相对参考路径；优先字段 `reference_image`，其次当前素材，新素材无参考时可省略             |
+| `additionalReferenceImagePaths` | 确有多个参考时传入其他可读路径，顺序与用途明确                                                           |
+| `aspectRatio`                   | 字段比例或目标尺寸推导的比例；直接工具仅支持部分比例，生成后再按目标 resolution 精确处理                 |
+| `removeBackground`              | 按字段配置与素材用途决定；透明前景为 `true`，完整背景或不透明面板为 `false`                              |
+| `outputPath`                    | 本次素材的中间文件路径，沿用项目工作目录约定，验证后写回实际主题引用                                     |
+
+背景、角色、道具、按钮、文字、发光状态、序列帧等各自遵守项目字段配置。成组状态或动画帧还需保持对象、风格、锚点与尺寸一致，不把单张静态图当成完整序列帧替换。
+
+`removeBackground: true` 表示需要通过验证的透明素材，不表示必须执行一次本地去背。保存工具结果中的实际 provider/model、参考图数量与透明验证结论；模型清单里的默认星号不能证明本次实际用了哪个模型。
+
+未注册直接工具时使用下方 CLI (Command-Line Interface, 命令行工具) 入口。若返回 `Business tool protocol unavailable (501); no operation was sent`，本次没有发出生图请求：修复入口或使用已注册的直接工具，不要通过换模型反复重试。
+
 ### 文生图（text-to-image）
 
 ```bash
@@ -99,7 +130,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 +142,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
 ```
 
 ### 参数说明
@@ -215,7 +246,14 @@ playcraft image sprite-sheet \
 
 ### 为什么需要色幕策略？
 
-**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。纯色背景 + 非撞色游戏素材 = 抠图几乎完美。与影视 chroma-key 原理相同。
+只有选用不支持原生透明的模型且需要透明素材时才使用色幕。原生透明图验证通过后直接处理尺寸，不再重复去背；发光、半透明边缘和白色前景应保留。白色背景与白色物体会让 floodfill 混淆边界。`playcraft image remove-background` 默认使用本地 floodfill，不应描述为必然调用后端去背模型。
+
+### 最终文件验证
+
+- 按字段 resolution 处理尺寸，透明前景用 `--fit contain`，确认执行的工具使用透明补边；旧版工具可能补入不透明黑色。验证不通过时更新工具或显式使用透明背景缩放。
+- 按实际资源扩展名编码，不把 PNG 内容写进其他格式的文件，也不擅自改变主题引用。
+- 去背、缩放、转格式后都检查透明通道与边缘，并分别在深色和浅色背景上预览。允许素材自身的黑色描边，拒绝额外黑色矩形补边或误删的发光效果。
+- 达到项目的文件大小限制后再覆盖目标文件。同一 Logo 的多个尺寸从同一张母图导出，避免重复生成导致风格漂移。
 
 ### 色幕选型矩阵（Color Conflict Avoidance）
 
@@ -280,7 +318,7 @@ playcraft image overlay \
 ## 4. 脚本决策
 
 - **<=5 个文件** → 直接使用 CLI 命令
-- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录。
+- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录；使用本次选定的模型与参考图，不直接沿用脚本中旧的默认模型。
 
 ---
 

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 时，从实际资源引用、当前图片的尺寸和用户需求确定这些参数；不要套用其他游戏的字段、路径或尺寸。
+
+替换素材时优先使用字段配置的 reference_image，没有配置时使用当前素材。查看图片或在对话中选中素材不等于把它传给生图模型：必须设置 referenceImagePath 或 --reference-image，并确认文件可读。仅调整风格时保留原有文字、构图和用途；用户要求重新命名或重做构图时再改变。
+
+生图前运行模型发现命令，核实当前账号可用的模型与透明输出能力：
 
 ```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,26 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 
 ## 2. 核心命令
 
+### 沙箱对话中的直接工具
+
+当前对话注册了 `playcraft-generate-image` 时，直接调用它。根据本次目标素材填写参数，不固定游戏名、素材类别、参考路径、尺寸或比例：
+
+| 参数                            | 本次取值                                                                                                 |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `prompt`                        | 目标字段的生成说明与用户需求；按素材用途明确背景、文字、构图或状态要求                                   |
+| `imageModelRef`                 | 当前清单中可用的模型，普通生图优先 `iegg-litellm/gpt-image-2.5-sunburst`；遵守用户或已锁定流程的模型选择 |
+| `referenceImagePath`            | 已确认可读的项目相对参考路径；优先字段 `reference_image`，其次当前素材，新素材无参考时可省略             |
+| `additionalReferenceImagePaths` | 确有多个参考时传入其他可读路径，顺序与用途明确                                                           |
+| `aspectRatio`                   | 字段比例或目标尺寸推导的比例；直接工具仅支持部分比例，生成后再按目标 resolution 精确处理                 |
+| `removeBackground`              | 按字段配置与素材用途决定；透明前景为 `true`，完整背景或不透明面板为 `false`                              |
+| `outputPath`                    | 本次素材的中间文件路径，沿用项目工作目录约定，验证后写回实际主题引用                                     |
+
+背景、角色、道具、按钮、文字、发光状态、序列帧等各自遵守项目字段配置。成组状态或动画帧还需保持对象、风格、锚点与尺寸一致，不把单张静态图当成完整序列帧替换。
+
+`removeBackground: true` 表示需要通过验证的透明素材，不表示必须执行一次本地去背。保存工具结果中的实际 provider/model、参考图数量与透明验证结论；模型清单里的默认星号不能证明本次实际用了哪个模型。
+
+未注册直接工具时使用下方 CLI (Command-Line Interface, 命令行工具) 入口。若返回 `Business tool protocol unavailable (501); no operation was sent`，本次没有发出生图请求：修复入口或使用已注册的直接工具，不要通过换模型反复重试。
+
 ### 文生图（text-to-image）
 
 ```bash
@@ -99,7 +130,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 +142,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
 ```
 
 ### 参数说明
@@ -215,7 +246,14 @@ playcraft image sprite-sheet \
 
 ### 为什么需要色幕策略？
 
-**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。纯色背景 + 非撞色游戏素材 = 抠图几乎完美。与影视 chroma-key 原理相同。
+只有选用不支持原生透明的模型且需要透明素材时才使用色幕。原生透明图验证通过后直接处理尺寸，不再重复去背；发光、半透明边缘和白色前景应保留。白色背景与白色物体会让 floodfill 混淆边界。`playcraft image remove-background` 默认使用本地 floodfill，不应描述为必然调用后端去背模型。
+
+### 最终文件验证
+
+- 按字段 resolution 处理尺寸，透明前景用 `--fit contain`，确认执行的工具使用透明补边；旧版工具可能补入不透明黑色。验证不通过时更新工具或显式使用透明背景缩放。
+- 按实际资源扩展名编码，不把 PNG 内容写进其他格式的文件，也不擅自改变主题引用。
+- 去背、缩放、转格式后都检查透明通道与边缘，并分别在深色和浅色背景上预览。允许素材自身的黑色描边，拒绝额外黑色矩形补边或误删的发光效果。
+- 达到项目的文件大小限制后再覆盖目标文件。同一 Logo 的多个尺寸从同一张母图导出，避免重复生成导致风格漂移。
 
 ### 色幕选型矩阵（Color Conflict Avoidance）
 
@@ -280,7 +318,7 @@ playcraft image overlay \
 ## 4. 脚本决策
 
 - **<=5 个文件** → 直接使用 CLI 命令
-- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录。
+- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录；使用本次选定的模型与参考图，不直接沿用脚本中旧的默认模型。
 
 ---
 

package/project-templates/threejs/.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 时，从实际资源引用、当前图片的尺寸和用户需求确定这些参数；不要套用其他游戏的字段、路径或尺寸。
+
+替换素材时优先使用字段配置的 reference_image，没有配置时使用当前素材。查看图片或在对话中选中素材不等于把它传给生图模型：必须设置 referenceImagePath 或 --reference-image，并确认文件可读。仅调整风格时保留原有文字、构图和用途；用户要求重新命名或重做构图时再改变。
+
+生图前运行模型发现命令，核实当前账号可用的模型与透明输出能力：
 
 ```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,26 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 
 ## 2. 核心命令
 
+### 沙箱对话中的直接工具
+
+当前对话注册了 `playcraft-generate-image` 时，直接调用它。根据本次目标素材填写参数，不固定游戏名、素材类别、参考路径、尺寸或比例：
+
+| 参数                            | 本次取值                                                                                                 |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `prompt`                        | 目标字段的生成说明与用户需求；按素材用途明确背景、文字、构图或状态要求                                   |
+| `imageModelRef`                 | 当前清单中可用的模型，普通生图优先 `iegg-litellm/gpt-image-2.5-sunburst`；遵守用户或已锁定流程的模型选择 |
+| `referenceImagePath`            | 已确认可读的项目相对参考路径；优先字段 `reference_image`，其次当前素材，新素材无参考时可省略             |
+| `additionalReferenceImagePaths` | 确有多个参考时传入其他可读路径，顺序与用途明确                                                           |
+| `aspectRatio`                   | 字段比例或目标尺寸推导的比例；直接工具仅支持部分比例，生成后再按目标 resolution 精确处理                 |
+| `removeBackground`              | 按字段配置与素材用途决定；透明前景为 `true`，完整背景或不透明面板为 `false`                              |
+| `outputPath`                    | 本次素材的中间文件路径，沿用项目工作目录约定，验证后写回实际主题引用                                     |
+
+背景、角色、道具、按钮、文字、发光状态、序列帧等各自遵守项目字段配置。成组状态或动画帧还需保持对象、风格、锚点与尺寸一致，不把单张静态图当成完整序列帧替换。
+
+`removeBackground: true` 表示需要通过验证的透明素材，不表示必须执行一次本地去背。保存工具结果中的实际 provider/model、参考图数量与透明验证结论；模型清单里的默认星号不能证明本次实际用了哪个模型。
+
+未注册直接工具时使用下方 CLI (Command-Line Interface, 命令行工具) 入口。若返回 `Business tool protocol unavailable (501); no operation was sent`，本次没有发出生图请求：修复入口或使用已注册的直接工具，不要通过换模型反复重试。
+
 ### 文生图（text-to-image）
 
 ```bash
@@ -99,7 +130,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 +142,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
 ```
 
 ### 参数说明
@@ -215,7 +246,14 @@ playcraft image sprite-sheet \
 
 ### 为什么需要色幕策略？
 
-**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。纯色背景 + 非撞色游戏素材 = 抠图几乎完美。与影视 chroma-key 原理相同。
+只有选用不支持原生透明的模型且需要透明素材时才使用色幕。原生透明图验证通过后直接处理尺寸，不再重复去背；发光、半透明边缘和白色前景应保留。白色背景与白色物体会让 floodfill 混淆边界。`playcraft image remove-background` 默认使用本地 floodfill，不应描述为必然调用后端去背模型。
+
+### 最终文件验证
+
+- 按字段 resolution 处理尺寸，透明前景用 `--fit contain`，确认执行的工具使用透明补边；旧版工具可能补入不透明黑色。验证不通过时更新工具或显式使用透明背景缩放。
+- 按实际资源扩展名编码，不把 PNG 内容写进其他格式的文件，也不擅自改变主题引用。
+- 去背、缩放、转格式后都检查透明通道与边缘，并分别在深色和浅色背景上预览。允许素材自身的黑色描边，拒绝额外黑色矩形补边或误删的发光效果。
+- 达到项目的文件大小限制后再覆盖目标文件。同一 Logo 的多个尺寸从同一张母图导出，避免重复生成导致风格漂移。
 
 ### 色幕选型矩阵（Color Conflict Avoidance）
 
@@ -280,7 +318,7 @@ playcraft image overlay \
 ## 4. 脚本决策
 
 - **<=5 个文件** → 直接使用 CLI 命令
-- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录。
+- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录；使用本次选定的模型与参考图，不直接沿用脚本中旧的默认模型。
 
 ---