@playcraft/cli 0.1.54 → 0.1.55-beta

package/project-template-v2/.claude/skills/playcraft-image-generation/SKILL.md

@@ -0,0 +1,401 @@
+---
+name: playcraft-image-generation
+description: Use when generating or replacing playable images, reusing shared visual assets, or managing durable image tasks. AI (Artificial Intelligence, 人工智能) 图片生成与替换指南，保持参考图、背景要求、目标尺寸和交付文件一致。
+triggers: 生成图片,generate image,选模型,model selection,reference image,参考图,风格一致,图生图,文生图,AI生图,图片质量,模型选择,500错误,模型失败,generate-image,list-image-models,ta-workspace,batch,批量,脚本,nodejs,edit模型,变体,绿幕,去背景,透明PNG,prompt,提示词,prompt套路,提示词技巧
+compatibility: agent,opencode
+version: 1.1.2
+surfaces:
+  - sandbox-agent
+---
+
+# PlayCraft AI 图片生成指南
+
+## 0. 开始前必读
+
+工作素材和脚本保存在当前工程，素材通常写 `assets/` 或当前主题目录；最终交付导出到工程根目录 `dist/`。云工作区的素材检索和持久化任务使用下列入口；任务请求文件和回执保存在 `dist/` 外。
+
+### 素材复用与可恢复生成
+
+```bash
+# 需要复用已有图片时，按名称、路径和标签查找共享素材
+playcraft library search "角色" --type texture --json
+playcraft library get <assetId> --json
+playcraft library files <assetId> --json
+playcraft library download <assetId> --output ./assets/library-character
+
+# 需要持久任务、精灵图或帧动画时，提交工作区任务
+playcraft assets estimate --request image-request.json
+playcraft assets generate --request image-request.json --client-request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId> --timeout 1800
+playcraft assets download <taskId> --output ./assets/generated-character
+```
+
+`image-request.json` 使用 JSON (JavaScript Object Notation, 数据交换格式)，例如 `{"kind":"image","prompt":"A cheerful game character","removeBackground":true}`。请求中的透明背景开关由下文交付约束决定；素材替换需要读取字段参考图和规格时，继续使用下文的 `tools image-context` 与 `tools generate-image`。这两条入口没有可互换的参数表。
+
+任务命令从 `.playcraft/workspace-context.json` 推断当前工作区和工程目录；在工程外运行时传 `--workspace <workspaceId> --directory basic`，或实际变体目录。提交结果不确定时复用同一个 `--client-request-id` 与原请求；已有任务编号后通过 `get` / `wait` 恢复。等待超时以状态码 75 退出，任务仍可查询。精灵图和动画必须下载完整包并保留相对路径；`download` 保存文件不代表平台已确认采纳。
+
+普通单图生成和替换使用本技能下方的直接工具与命令；素材库检索、生成任务保存到素材库、动画草稿及版本的详细流程见当前可用的 `playcraft-workspace-assets` 技能。下载目标必须尚不存在。
+
+替换现有素材时先读取目标字段的 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
+```
+
+输出示例：
+
+```
+MODEL                                        CAPABILITY   ALPHA  PROVIDERS
+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)
+qwen-image-edit-max                          image→image  no     1 (mulerouter)
+...
+```
+
+**列说明**：
+
+- `CAPABILITY`：`text→image` 仅文生图 / `image→image` 仅图生图 / `text+image` 两者均支持
+- `ALPHA`：`yes` = 支持原生透明输出；`no` = 透明素材才需要另行去背（见第 3 节）
+- `PROVIDERS`：支持该模型的 provider 数量，多个 provider 时后端按优先级自动 fallback（顺序尝试，首个成功即返回）
+
+**Prompt 套路速查**：[reference/prompt-cookbook.md](reference/prompt-cookbook.md)
+
+---
+
+## 1. 模型选择决策树
+
+```
+需要生图？
+├─ 用户指定了模型，或制作流程已锁定模型？
+│  └─ 使用指定模型；失败时报告原因，不静默更换
+│
+├─ 普通图片生成 / 现有素材替换 / 含文字 Logo？
+│  └─ 优先 iegg-litellm/gpt-image-2.5-sunburst；不可用时选择清单中的 Image 2.5 并报告实际模型
+│
+├─ 需要 --reference-image（风格一致性批量生产）？
+│  └─ 必须选 CAPABILITY = text+image 或 image→image 的模型
+│
+├─ 同类元素批量生成（<=16 个）？
+│  └─ 精灵图直出策略（见进阶参考）
+│
+├─ 结构相似的变体集（换花色/换数字/换颜色）？
+│  └─ Edit 模型工作流（见进阶参考）
+│
+└─ 不确定？
+   └─ 使用平台默认模型；透明素材优先清单中 ALPHA=yes 的模型
+```
+
+### 主要模型特性
+
+| 模型                               | 特点与优势                                                         | 最佳场景                                 | 速度           | 注意事项                                                          |
+| ---------------------------------- | ------------------------------------------------------------------ | ---------------------------------------- | -------------- | ----------------------------------------------------------------- |
+| **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.5-sunburst`，其次 Image 2.5 系列
+- 已锁定的故事板或制作流程 → 沿用该流程指定模型，见下方 MC 专用规则
+- 中国风 / Q版 / 亚洲审美 → `hy-image-v3.0`
+- 艺术/手绘探索 → `flux-kontext-pro`
+- 纯 edit 变体 → `qwen-image-edit-max`
+- 模型失败 → 先检查返回错误；不要把原生透明失败自动改成 Gemini 白底生成
+
+### 为什么精灵图直出是首选批量策略？
+
+精灵图直出（一次 API 调用生成一张包含 N 个元素的网格图，再 sprite-split 切分）优于逐个生成，原因有三：
+
+1. **成本**：一次 API 调用可包含 4-16 个元素，而逐个生成 N 个元素需要 N 次调用，成本和耗时线性增长。
+2. **风格一致性**：同一张图中的所有元素共享相同的生成上下文，天然保证色调、线条、阴影风格统一，避免逐个生成时每张图风格漂移的问题。
+3. **无逐元素偏差**：逐个生成时即使用相同 prompt，模型每次采样结果都不同，元素之间会出现肉眼可见的不一致；精灵图在一次推理中完成，消除了这种 per-element drift。
+
+详细策略与代码示例见进阶参考。
+
+---
+
+## 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 iegg-litellm/gpt-image-2.5-sunburst
+```
+
+### 图生图（image-to-image / reference-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 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`                        | 控制分辨率级别。实际像素取决于模型+比例的组合（见下表） |
+
+**`--image-size` 对 gpt-image-2 的落盘尺寸**（MuleRouter 请求 `size=auto`，由后端 letterbox 到目标像素）：
+
+| aspectRatio                   | 1K        | 2K            | 4K            |
+| ----------------------------- | --------- | ------------- | ------------- |
+| 1:1                           | 1024x1024 | 2048x2048     | 2048x2048     |
+| **45:16** (5×9:16 故事板横排) | 2048x728  | **3600x1280** | **4096x1455** |
+| 16:9                          | 2048x1152 | 2048x1152     | 3840x2160     |
+| 9:16                          | 2160x3840 | 2160x3840     | 2160x3840     |
+| 3:2 / 4:3                     | 1536x1024 | 1536x1024     | 1536x1024     |
+| 21:9                          | 2048x1152 | 3840x2160     | 3840x2160     |
+
+> **IEGG LiteLLM** 在 fallback 链中排第一，但 Azure gpt-image 最大约 1536px 宽 — 达不到 5×9:16 横排。故事板请用 **`mulerouter/gpt-image-2`**（跳过 litellm）+ `--width 3600 --height 1280`（或 4096×1455）。
+
+### Master Composite（MC）模型白名单
+
+Artist 生成 MC 时**不得**套用上方通用决策树里的 gemini / flux / hy-image 等——MC 只允许：
+
+| 允许                       | 禁止（MC）                                          |
+| -------------------------- | --------------------------------------------------- |
+| `mulerouter/gpt-image-2`   | `gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*` |
+| `mulerouter/nano-banana-2` | 裸 `gpt-image-2`（会走 iegg-litellm 压扁五格）      |
+
+故事板的提示词与尺寸依据本节规格和当前工程的制作要求。ASR 双板 `--image-model` 须与已选 MC **完全一致**。
+
+**Phase 1（概念图）**：纯文生图，`--image-size 4K` + MC 白名单内模型。
+**Phase 2（批量生产）**：必须带 `--reference-image` 指向 Phase 1 确认的概念图，同一批次使用**相同模型 + 相同 reference image + 相同 image-size**。
+
+### --reference-image 路径支持
+
+- 本地绝对路径：`/path/to/ref.png`
+- 相对路径（相对 CWD）：`assets/images/ref.png`
+- HTTP(S) URL（CLI 自动下载）：`"https://images.unsplash.com/photo-xxx"`
+- 多张参考图（重复选项，最多 8 张）
+- 混合本地文件 + URL
+- `search-image` 返回的 `downloadUrl` 可直接使用
+
+### 常用辅助命令
+
+```bash
+# 去背景（绿幕建议 tolerance=25；默认白背景可用 15）
+playcraft image remove-background --input in.png --output out.png --tolerance 25
+
+# 缩放
+playcraft image resize --input in.png --output out.png --width 128 --height 128
+
+# 精灵图切分
+playcraft image sprite-split \
+  --input sheet.png --output-dir frames/ \
+  --rows 2 --columns 4 \
+  --frame-width <总宽/4> --frame-height <总高/2>
+
+# 合并精灵图
+playcraft image sprite-sheet \
+  --input-dir processed/ --output bundle \
+  --columns 8 --background white
+```
+
+---
+
+## 3. 背景处理决策树
+
+> **核心原则**：先读取字段明确约束，再结合完整对话判断用户是否明确要求背景；没有明确要求时默认透明，不能按素材类别推断为不透明。常规工具按第 2 节的模型规则准备源图并由后端验收，独立色幕流程才选择色幕颜色，交付后做深浅背景验证。
+
+```
+最终素材的背景要求是什么？
+│
+├─ 字段有明确背景约束？
+│   └─ 严格遵守字段要求：remove_background=true → transparent；false → opaque
+│
+├─ 字段无明确约束，且用户明确要求保留背景/完整场景？
+│   ├─ background=opaque / --background opaque，交付整张不透明图片
+│   └─ 满幅场景 prompt 加 "full bleed, edge to edge, no vignette, no fade"
+│
+└─ 字段无明确约束，且用户未明确要求背景？
+    └─ background=transparent / --background transparent（包括卡牌、棋子和面板）
+        ├─ 白色牌面、边框与文字属于前景，必须保留，只移除本体外的画布背景
+        ├─ 常规工具 → 按模型准备源图背景（第 2 节）→ 原生透明或去背 → 最终透明验收
+        └─ 已明确选择独立色幕制作流程？
+            └─ 中间图 background=opaque → 单一色幕 → 切分后独立去背 → 深浅背景验证
+```
+
+### 为什么需要色幕策略？
+
+只有用户或已锁定的制作流程明确选择独立色幕制作，且所选模型不支持原生透明时才采用该流程；仅指定其他模型并不等于选择色幕。下方色幕矩阵和后缀表仅用于该流程与 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）
+
+> ⚠️ **不要默认全用绿幕！** 金色素材 + 绿幕 = 绿色与金色色相接近，floodfill 会在边缘残留绿色，或误删金色像素。
+
+| 素材主色调            | ❌ 禁用 | ✅ 推荐          | 原因                                       |
+| --------------------- | ------- | ---------------- | ------------------------------------------ |
+| 金色/黄色/橙色/琥珀色 | 绿幕    | **蓝幕 #0000FF** | 金色与绿色色相接近（黄绿区），边缘残留绿色 |
+| 绿色/翠绿/青色        | 绿幕    | **蓝幕 #0000FF** | 同色系，无法区分边界                       |
+| 蓝色/靛蓝/紫色        | 蓝幕    | **绿幕 #00FF00** | 同色系冲突                                 |
+| 红色/粉色/白色/黑色   | —       | 绿幕或蓝幕均可   | 与两者色相距离都大                         |
+| 多色/彩虹             | —       | **品红 #FF00FF** | 品红在自然素材中最少出现（最后手段）       |
+
+### Prompt 后缀速查表
+
+下表的色幕后缀只用于已明确选择的独立色幕流程。卡牌、面板等最终交付仍按上方决策树选择；`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`                  |
+
+### 去背景后必做：深色背景渲证
+
+> 每个需要透明的资产，去背景后**必须**在深色背景上叠合验证。这一步是防止白底/色幕残留/黑块的最后防线。
+
+```bash
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <processed>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
+# 目视检查：无白边、无色幕残留色、无黑色不透明块、边缘干净
+```
+
+**不通过时的修复**：检查实际模型、源图背景和去背参数，保留原始图与失败回执；按下方进阶参考的错误恢复策略处理。透明验收仍失败时报告具体阶段并停止，不交付未通过的文件。
+
+---
+
+## 3.1 ASR 专用分支（Artist · ring 3 build）
+
+> 先核对当前工程素材状态表中的槽位、状态和交付尺寸。ASR 是制作期参考板，不是 runtime 透明资产。
+
+| 阶段              | Artist                                | TA                            |
+| ----------------- | ------------------------------------- | ----------------------------- |
+| ASR 整图          | **opaque**（灰底或统一色幕）— 正常    | —                             |
+| ASR 格内元素      | **isolated** + 按色幕矩阵选 cell 背景 | `crop` 后 `remove-background` |
+| remove-background | **禁止** — Artist 不做                | production Wave 2             |
+
+**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 后处理产物）
+
+---
+
+## 4. 脚本决策
+
+- **<=5 个文件** → 直接使用 CLI 命令
+- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录；使用本次选定的模型与参考图，不直接沿用脚本中旧的默认模型。
+
+复制模板时，`SKILL_DIR` 表示本次实际加载的 `SKILL.md` 所在目录，由技能加载回执确定。将示例中的该变量设为真实目录后再运行；项目安装与冻结安装的目录可能不同。
+
+---
+
+## 5. 进阶参考
+
+需要以下进阶内容时，查阅 [`reference/ta-image-generation-detail.md`](reference/ta-image-generation-detail.md)：
+
+| 主题                  | 说明                                                             |
+| --------------------- | ---------------------------------------------------------------- |
+| 精灵图直出策略        | 按选定模型生成网格图 + sprite-split 切分；自动透明与独立色幕示例 |
+| Edit 模型工作流       | 基图 → edit 变体（换花色/换数字/换颜色），prompt 写法            |
+| 错误恢复表            | 各类错误现象、原因、立即行动；模型回退顺序                       |
+| Provider 回退链       | gpt-image-2 三 provider 互为回退 + 非 gpt-image-2 稳定回退       |
+| 批量生成最佳实践      | 单张验证、Node.js 脚本推荐、脚本模板使用                         |
+| ta-workspace 脚本驱动 | 为什么用 Node.js、目录约定、脚本模板一览表                       |

package/project-template-v2/.claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs

@@ -0,0 +1,123 @@
+// ============================================================
+// build-sprite-sheet.template.mjs — 精灵图合并 + 验证脚本模板
+// 用途：将处理好的图片目录合并为精灵图（PNG + JSON 元数据）
+//
+// 使用方式：
+//   1. cp "$SKILL_DIR/reference/build-sprite-sheet.template.mjs" ta-workspace/scripts/build-<name>-atlas.mjs
+//   2. 修改下方 CONFIG 区域
+//   3. 如需控制帧顺序，填写 ORDERED_NAMES 数组（留空则按文件名排序）
+//   4. node ta-workspace/scripts/build-<name>-atlas.mjs
+// ============================================================
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'fs';
+import { join, extname } from 'path';
+
+// ============ CONFIG — 修改这里 ============
+const CONFIG = {
+  /** 处理好的图片目录（process-batch 的输出目录） */
+  processedDir: 'assets/images/processed',
+  /** 输出文件路径（不含扩展名，会生成 .png 和 .json 两个文件） */
+  outputBase: 'assets/bundles/atlas',
+  /** 每行帧数 */
+  columns: 8,
+  /** 帧间距（像素） */
+  padding: 2,
+  /**
+   * 精灵图背景色
+   * - 'transparent'（默认）：透明背景
+   * - 'white' / 'black' / '#RRGGBB'：固定背景色
+   *   某些引擎（如 PlayCanvas）处理透明精灵图时可能显示为黑色，此时用 'white' 更安全
+   */
+  background: 'transparent',
+  /** 文件名排序方式：'name'（字母序）或 'custom'（使用 ORDERED_NAMES） */
+  sort: 'name',
+};
+
+/**
+ * 自定义帧顺序（CONFIG.sort = 'custom' 时生效）
+ * 填写不含扩展名的文件名，按期望顺序排列
+ * 示例（扑克牌）：['spades_A', 'spades_2', 'spades_3', ...]
+ */
+const ORDERED_NAMES = [
+  // 填写文件名（不含扩展名）...
+];
+// ============ LOGIC — 通常不需要修改 ============
+
+const LOG_FILE = 'ta-workspace/logs/build-sprite-sheet.log';
+mkdirSync('ta-workspace/logs', { recursive: true });
+
+function log(msg) {
+  const line = `[${new Date().toISOString()}] ${msg}`;
+  console.log(line);
+  appendFileSync(LOG_FILE, line + '\n');
+}
+
+// 收集输入文件
+let inputFiles;
+if (CONFIG.sort === 'custom' && ORDERED_NAMES.length > 0) {
+  // 自定义顺序：按 ORDERED_NAMES 排列，找不到的文件跳过并警告
+  inputFiles = [];
+  for (const name of ORDERED_NAMES) {
+    const candidates = ['.png', '.jpg', '.webp'].map(ext => join(CONFIG.processedDir, `${name}${ext}`));
+    const found = candidates.find(p => existsSync(p));
+    if (found) {
+      inputFiles.push(found);
+    } else {
+      log(`[WARN] Ordered file not found: ${name} (skipping)`);
+    }
+  }
+} else {
+  // 文件名排序
+  inputFiles = readdirSync(CONFIG.processedDir)
+    .filter(f => ['.png', '.jpg', '.webp'].includes(extname(f).toLowerCase()))
+    .sort()
+    .map(f => join(CONFIG.processedDir, f));
+}
+
+if (inputFiles.length === 0) {
+  log('ERROR: No input files found in ' + CONFIG.processedDir);
+  process.exit(1);
+}
+
+log(`=== Build Sprite Sheet Start ===`);
+log(`Frames: ${inputFiles.length} | Columns: ${CONFIG.columns} | Padding: ${CONFIG.padding} | BG: ${CONFIG.background}`);
+
+// 构建 --inputs 参数列表
+const inputsArg = inputFiles.map(p => `"${p}"`).join(' ');
+
+const cmd =
+  `playcraft image sprite-sheet` +
+  ` --inputs ${inputsArg}` +
+  ` --output "${CONFIG.outputBase}"` +
+  ` --columns ${CONFIG.columns}` +
+  ` --padding ${CONFIG.padding}` +
+  (CONFIG.background !== 'transparent' ? ` --background "${CONFIG.background}"` : '');
+
+log(`Running: playcraft image sprite-sheet ... --output ${CONFIG.outputBase}`);
+
+try {
+  execSync(cmd, { stdio: 'inherit' });
+} catch (e) {
+  log(`ERROR: sprite-sheet command failed: ${e.message}`);
+  process.exit(1);
+}
+
+// 验证输出
+const pngPath  = `${CONFIG.outputBase}.png`;
+const jsonPath = `${CONFIG.outputBase}.json`;
+
+if (!existsSync(pngPath) || !existsSync(jsonPath)) {
+  log('ERROR: Output files missing! Expected ' + pngPath + ' and ' + jsonPath);
+  process.exit(1);
+}
+
+const meta = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+const frameCount = Object.keys(meta.frames ?? {}).length;
+
+log(`\n=== Sprite Sheet Built ===`);
+log(`  Frames  : ${frameCount}`);
+log(`  PNG     : ${pngPath}`);
+log(`  JSON    : ${jsonPath}`);
+log(`  Columns : ${CONFIG.columns}`);
+log(`  Rows    : ${Math.ceil(frameCount / CONFIG.columns)}`);