---
name: playcraft-image-generation
description: 可玩广告流程步骤 5。读取模板中使用的图片，根据变体需求调用 AI 生图模型生成创意替换图，直接写入文件，不产生 base64 上下文污染。后端自动竞速所有可用 provider，无需手动指定。
compatibility: agent,opencode
---

## CLI 与 Atom skill（`*.aiimage`）

- **AI 生图入口**：`playcraft tools generate-image`（需后端）。当前 CLI **不提供** `playcraft image gen`；本地处理用 `playcraft image <子命令>`（如 `convert`、`remove-background`），见 `playcraft-image-processing`。
- **参数来源**：若项目引用了某图片 Atom（例如 `lose_result_panel.aiimage`），提示词与模型等以该目录 **`manifest.json` → `generation`** 为准（如 `prompt`、`aspectRatio`、`model`、`referenceImage`），再映射到 `generate-image` 的 `--prompt`、`--aspect-ratio`、`--image-model`、`--reference-image`。

## Skill Definition
tools:
  - bash
  - read
prompt_extension: |
  你是游戏视觉设计师，专注于为可玩广告生成高质量图片素材。
  不得向 /project/ 写入；分析项目现有图片（只读），生成结果写入会话 ta-workspace。
  通过 bash 工具运行 `playcraft tools generate-image` CLI 命令生成图片（AI 调用需后端处理）。
  生成后如需后处理（缩放/裁剪/格式转换等），使用 `playcraft image <command>` 系列命令在本地处理。

## 我做什么

- 分析模板/项目中使用的图片资源（角色、背景、道具等）
- 根据用户诉求和创意方向，生成符合要求的替换图片
- 传入模型名（如 `gpt-image-2`），后端自动并发竞速所有可用 provider，返回最先成功的结果

## 何时用我

在可玩广告变体流程中，需要为替换或新增的视觉元素生成创意图片时。例如：新角色、新背景、新道具图标等。

## 工作流

1. **读取模板图片**：用 `read` 工具查看项目中的图片资源（assets 目录、manifest、场景引用等）
2. **确定生成需求**：列出需要生成的图片类型、尺寸、风格
3. **（可选）查询可用生图模型**：
   ```bash
   playcraft tools list-image-models
   ```
   输出按模型名分组的列表，`MODEL` 列的值可直接作为 `--image-model` 参数。`PROVIDERS` 列显示支持该模型的 provider 数量——多个 provider 时后端自动竞速。

4. **生成图片**（AI 调用，需 backend）：
   ```bash
   playcraft tools generate-image \
     --prompt "<详细英文描述>" \
     --output <ta-workspace内的输出路径> \
     [--aspect-ratio 1:1|16:9|9:16|3:4|4:3] \
     [--reference-image <路径> ...] \
     [--image-model <模型名>]
   ```
   - **`--image-model`**：指定模型名（如 `gpt-image-2`），后端自动竞速所有可用 provider。也可传 `provider/model`（如 `mulerouter/gpt-image-2`）直连指定 provider。不传则使用系统默认配置。
   - **`--reference-image`**：参考图路径，支持本地路径（绝对/相对于 CWD）和 HTTP(S) URL（CLI 自动下载）。可重复最多 **8** 次，出现顺序即传给模型的顺序。
     - `search-image` 返回的 `downloadUrl` 可直接用于 `--reference-image`，无需手动保存。
   - **OpenCode 工具 `playcraft-generate-image`**：第一张用参数 `referenceImagePath`；其余用 `additionalReferenceImagePaths`，值为 **英文逗号分隔**的路径列表（路径里不要含逗号），顺序在首张之后；模型用 `imageModelRef`（传模型名即可，如 `gpt-image-2`）。
5. **（可选）后处理**（本地执行，速度快）：
   ```bash
   # 缩放到目标尺寸
   playcraft image resize --input ta-workspace/raw.png --output ta-workspace/final.png --width 512 --height 512
   # 格式转换节省体积
   playcraft image convert --input ta-workspace/final.png --output ta-workspace/final.webp --quality 85
   # 裁掉多余透明边界
   playcraft image trim --input ta-workspace/raw.png --output ta-workspace/trimmed.png
   ```

## Prompt 建议

- **明确风格**：pixel art、flat design、3D render、cartoon 等
- **透明背景**：若需要 PNG 透明，在 prompt 中写 `transparent background`
- **尺寸比例**：可玩广告通常 9:16 竖屏（`--aspect-ratio 9:16`），或 1:1 用于图标
- **描述越具体越好**：颜色、姿势、光照方向、是否有阴影

## 示例

```bash
# 游戏背景（使用系统默认模型）
playcraft tools generate-image \
  --prompt "vibrant gradient background for a mobile game, purple to blue, cartoon style, no characters" \
  --aspect-ratio 9:16 \
  --output ta-workspace/bg_raw.png

# 高质量文生图（gpt-image-2，后端自动竞速 iegg-litellm / mulerouter / 302）
playcraft tools generate-image \
  --prompt "cute game character, flat design, white background" \
  --aspect-ratio 1:1 \
  --image-model gpt-image-2 \
  --output ta-workspace/char_raw.png

# 图生图（带参考图，使用 gpt-image-2 竞速）
playcraft tools generate-image \
  --prompt "same character style, holding a shield instead of a sword" \
  --aspect-ratio 1:1 \
  --reference-image ta-workspace/char_raw.png \
  --image-model gpt-image-2 \
  --output ta-workspace/char_shield_raw.png

# 角色精灵（透明背景）
playcraft tools generate-image \
  --prompt "cute pixel art hero character, front facing, 64x64 sprite, transparent background, warm colors" \
  --aspect-ratio 1:1 \
  --output ta-workspace/hero_raw.png

# 道具图标
playcraft tools generate-image \
  --prompt "golden coin icon for game UI, flat design, clean edges, transparent background" \
  --aspect-ratio 1:1 \
  --output ta-workspace/coin_raw.png

# 多张参考图：风格 + 构图（顺序有意义）
playcraft tools generate-image \
  --prompt "Merge the character style from first ref with the layout of second ref, flat vector, game UI" \
  --aspect-ratio 9:16 \
  --reference-image ta-workspace/ref_style.png \
  --reference-image ta-workspace/ref_layout.png \
  --output ta-workspace/merged_raw.png
```

## 解决生成图不透明的问题

Gemini 不原生支持透明背景输出。生成后用 `remove-background` 命令处理：

```bash
# 生成图（有白底或灰色/棋盘格背景）
playcraft tools generate-image --prompt "cute hero character, white background" --aspect-ratio 1:1 --output ta-workspace/hero_raw.png

# 移除背景（默认 floodfill，AI 生成素材最佳选择）
playcraft image remove-background --input ta-workspace/hero_raw.png --output ta-workspace/hero.png

# 如果背景与前景颜色接近，可增大容差
playcraft image remove-background --input ta-workspace/hero_raw.png --output ta-workspace/hero.png --tolerance 40

# 如果是复杂背景的照片，改用 AI 模型（但可能导致浅色纹理褪色）
playcraft image remove-background --input ta-workspace/photo.jpg --output ta-workspace/photo.png --method ai
```

> `remove-background` 默认使用 floodfill 方法（本地 sharp），适合 AI 生成的纯色/棋盘格背景素材，前景纹理零损失。
> 仅当背景非常复杂（真实照片）时才需要 `--method ai`（调用 backend API）。

## 生成后常用后处理

```bash
# 生成后统一尺寸 + 转 webp
playcraft image resize --input ta-workspace/hero_raw.png --output ta-workspace/hero_128.png --width 128 --height 128 --fit contain
playcraft image convert --input ta-workspace/hero_128.png --output ta-workspace/hero_128.webp --quality 85

# 做多个颜色变体
playcraft image tint --input ta-workspace/hero_128.png --output ta-workspace/hero_blue.png --color "#0055ff"
playcraft image tint --input ta-workspace/hero_128.png --output ta-workspace/hero_red.png --color "#ff2200"
```