@playcraft/skills 0.0.2

package/skills/playcraft-sprite-generation/SKILL.md

@@ -0,0 +1,534 @@
+---
+name: playcraft-sprite-generation
+description: 从概念图/示意图出发，通过 AI 文生图/图生图批量生成完整精灵图集（如 34 张麻将牌、54 张扑克牌、棋子集等），再智能切割为逐帧资产并组装精灵图。核心理念：信任现代生图模型（GPT-Image-2 等）的文字/符号精度，走「AI 直接生成 → 智能切割 → 组装」路径，不做分层合成。
+compatibility: agent,opencode
+triggers: 精灵图生成, sprite generation, 批量生成, 牌面生成, 完整套, tile set, card set, 从概念图, from concept, 全套素材, batch asset, mahjong set, poker set, chess set
+---
+
+## Skill Definition
+tools:
+  - bash
+  - read
+prompt_extension: |
+  你是批量精灵图生成工程师。从一张概念图/示意图出发，利用 AI 生图模型批量生成完整游戏资产集，再通过智能切割提取逐帧资产，最终组装为生产级精灵图。
+  不得向 /project/ 写入；所有中间产物与最终输出必须在会话 .../sessions/{id}/ta-workspace/ 下。
+  核心原则：信任现代生图模型的符号/文字精度，优先让 AI 直接生成带正确内容的资产，不搞"底板+符号"分层合成。
+  通过 bash 调用 playcraft CLI：tools generate-image、image sprite-split、image sprite-sheet、image remove-background、image resize 等。
+
+## 我做什么
+
+- 从一张概念图/示意图推导出完整资产集的生成计划（例：一张麻将牌 → 全部 34 种牌面）
+- 利用 AI 生图模型（GPT-Image-2、Gemini 等）批量生成完整资产，保持风格一致性
+- 智能切割 AI 生成的批量图（规则网格 / Vision 自动检测 / 未来 SAM 语义分割）
+- 后处理（去背景、统一尺寸、质量检查）后组装为生产级精灵图 + JSON 帧坐标
+
+## 何时用我
+
+- 拿到一张概念图/示意图，需要生成**完整套**的同类元素（牌、棋子、图标集等）
+- 元素上有**精确符号/文字/图案**（中文字符、数字、花色等），需要 AI 模型直接生成正确内容
+- 需要保持全套元素**风格高度统一**
+- 最终交付物是可用于游戏引擎的精灵图 + JSON 元数据
+
+## 不用我的场景
+
+- 已有完整精灵图只需换肤/风格变换 → 用 `playcraft-sprite-remix`
+- 已有逐帧图片只需合并 → 用 `playcraft-sprite-sheet`
+- 需要 3D 翻转动画 → 用 `playcraft-3d-flip-sprite`
+- 单张图片生成（非批量套） → 用 `playcraft-image-generation`
+
+---
+
+## 核心流程
+
+```
+概念图/示意图
+  ↓
+Step 1: 分析 — 推导完整资产集清单
+  ↓
+Step 2: 选择生成策略 — 逐张 vs 批量拼板
+  ↓
+Step 3: AI 批量生成（图生图 + reference-image 保持风格）
+  ↓
+Step 4: 智能切割（grid / auto-detect / 未来 SAM）
+  ↓
+Step 5: 后处理（去背景、统一尺寸、质量校验）
+  ↓
+Step 6: 组装精灵图 + JSON 帧坐标
+```
+
+---
+
+## Step 1: 分析概念图，推导完整资产清单
+
+拿到概念图后，先明确**完整集合的定义**：
+
+```bash
+# 查看概念图
+playcraft image info ta-workspace/concept.png
+```
+
+常见集合清单（TA 应根据项目 atom-plan / layout-spec 确定）：
+
+| 游戏类型 | 集合 | 元素数 | 每元素特征 |
+|----------|------|--------|-----------|
+| 麻将 | 万条筒风箭 | 34 | 每张牌有独特中文字符/图案 |
+| 扑克 | A-K × 4花色 + 大小王 | 54 | 数字+花色，大小王特殊 |
+| 象棋 | 红黑各 16 子 | 32 | 中文棋子名，红黑双色 |
+| UNO | 数字牌+功能牌+万能牌 | 108 | 数字+颜色+功能符号 |
+| Match-3 元素 | 按主题 | 6-8 | 各不相同的图案 |
+| 图标集 | UI 元素 | N | 各不相同的图标 |
+
+输出：**资产清单表**（记录在 ta-workspace/asset-manifest.json）
+
+```json
+{
+  "setName": "mahjong-tiles",
+  "conceptRef": "ta-workspace/concept.png",
+  "style": "ice crystal, frosted glass, blue-white cold theme",
+  "totalCount": 34,
+  "groups": [
+    { "name": "wan", "items": ["一万","二万","三万","四万","五万","六万","七万","八万","九万"] },
+    { "name": "tiao", "items": ["一条","二条","三条","四条","五条","六条","七条","八条","九条"] },
+    { "name": "tong", "items": ["一筒","二筒","三筒","四筒","五筒","六筒","七筒","八筒","九筒"] },
+    { "name": "feng", "items": ["东","南","西","北"] },
+    { "name": "jian", "items": ["中","发","白"] }
+  ]
+}
+```
+
+---
+
+## Step 2: 选择生成策略
+
+### 策略 A：逐张生成（推荐，精度最高）
+
+每个元素单独调用一次 `generate-image`，用概念图作为 `--reference-image` 锁定风格。
+
+**优点**：每张有完整 prompt 描述符号，精度最高
+**缺点**：API 调用次数多（N 次）
+**适用**：元素数 < 50，每个元素有独特符号/文字
+
+### 策略 B：批量拼板生成（省 API 调用）
+
+让 AI 在一张大图中生成多个元素（如 "generate a 3×3 grid of mahjong tiles: 一万 through 九万"），然后切割。
+
+**优点**：一次生成多个元素，风格自然一致
+**缺点**：符号精度随密度下降；布局可能不够规则
+**适用**：元素数多、符号相对简单（如 Match-3 的几何图案）
+
+### 策略 C：分组生成（平衡方案）
+
+按逻辑分组，每组生成一张拼板图。如麻将"万"字组 9 张一板、"条"组 9 张一板。
+
+**优点**：组内风格 100% 一致，API 调用降到 4-5 次
+**缺点**：需要切割步骤
+**适用**：有自然分组的大集合（推荐麻将、扑克使用此策略）
+
+### 策略选择决策
+
+```
+元素数量？
+├── < 10 → 策略 A（逐张生成）
+├── 10-50 且有自然分组 → 策略 C（分组生成）
+├── 10-50 无分组 → 策略 A 或 B
+└── > 50 → 策略 C（必须分组，否则太慢）
+```
+
+---
+
+## Step 3: AI 批量生成
+
+### 策略 A — 逐张生成
+
+```bash
+# 关键：使用同一模型 + 同一 reference-image，保证风格一致
+
+# 先确认可用模型
+playcraft tools list-image-models --json
+
+# GPT-Image-2（符号精度最高，推荐用于带文字/符号的资产）
+# 生成第一张（建立风格锚点）
+playcraft tools generate-image \
+  --prompt "mahjong tile, ice crystal frosted glass style, tile shows Chinese character 一万 (yi wan), game asset, white background, front view, single tile centered" \
+  --reference-image ta-workspace/concept.png \
+  --aspect-ratio 1:1 \
+  --image-model iegg-litellm/gpt-image-2 \
+  --output ta-workspace/tiles/wan_1.png
+
+# 后续用第一张作为额外 reference，双重锁定风格
+playcraft tools generate-image \
+  --prompt "mahjong tile, ice crystal frosted glass style, tile shows Chinese character 二万 (er wan), game asset, white background, front view, single tile centered" \
+  --reference-image ta-workspace/concept.png \
+  --reference-image ta-workspace/tiles/wan_1.png \
+  --aspect-ratio 1:1 \
+  --image-model iegg-litellm/gpt-image-2 \
+  --output ta-workspace/tiles/wan_2.png
+
+# 循环生成剩余元素...（同一模型、同样的 reference 组合）
+```
+
+**风格锁定技巧**：
+
+1. **双 reference**：概念图 + 前一张成品，双重约束风格
+2. **同一模型**：全套元素必须用同一个 `--image-model`
+3. **prompt 模板化**：只替换符号描述部分，其余措辞完全一致
+4. **先验证后批量**：先生成 2-3 张检查风格，确认后再跑全套
+
+### 策略 C — 分组生成（以麻将为例）
+
+```bash
+# 万字组：9 张一板
+playcraft tools generate-image \
+  --prompt "3x3 grid of mahjong tiles, ice crystal frosted glass style. Top row left to right: 一万, 二万, 三万. Middle row: 四万, 五万, 六万. Bottom row: 七万, 八万, 九万. Each tile clearly shows its Chinese character. Game assets, white background, uniform size, evenly spaced grid" \
+  --reference-image ta-workspace/concept.png \
+  --aspect-ratio 1:1 \
+  --image-model iegg-litellm/gpt-image-2 \
+  --output ta-workspace/sheets/wan_grid.png
+
+# 条子组
+playcraft tools generate-image \
+  --prompt "3x3 grid of mahjong tiles, ice crystal frosted glass style. Top row: 一条, 二条, 三条. Middle row: 四条, 五条, 六条. Bottom row: 七条, 八条, 九条. Each tile clearly shows its bamboo pattern. Game assets, white background, uniform size, evenly spaced grid" \
+  --reference-image ta-workspace/concept.png \
+  --reference-image ta-workspace/sheets/wan_grid.png \
+  --aspect-ratio 1:1 \
+  --image-model iegg-litellm/gpt-image-2 \
+  --output ta-workspace/sheets/tiao_grid.png
+
+# 筒子组、风箭组（2x2 即可）...类似
+```
+
+---
+
+## Step 4: 智能切割
+
+根据生成策略选择切割方式：
+
+### 策略 A 的产物 — 逐张生成，无需切割
+
+每张图已经是单独元素，跳到 Step 5。
+
+### 策略 B/C 的产物 — 需要切割
+
+```bash
+# ── 方法 1：已知网格（最快、零 API 消耗）──
+# 适用于 prompt 中明确指定了网格排列的生成结果
+playcraft image sprite-split \
+  --input ta-workspace/sheets/wan_grid.png \
+  --output-dir ta-workspace/split/wan \
+  --rows 3 --columns 3 \
+  --frame-width 200 --frame-height 260 \
+  --padding 10
+
+# ── 方法 2：Vision 自动检测（需 token）──
+# 适用于 AI 生成的网格不够规则、间距不均匀时
+playcraft image sprite-split \
+  --input ta-workspace/sheets/wan_grid.png \
+  --output-dir ta-workspace/split/wan \
+  --auto-detect \
+  --hint "3x3 grid of mahjong tiles, uniform cells"
+
+# 检查切割结果
+ls ta-workspace/split/wan/
+cat ta-workspace/split/wan/split-meta.json
+```
+
+**切割质量检查**：
+
+```bash
+# 逐张检查尺寸是否一致
+for f in ta-workspace/split/wan/frame_r*.png; do
+  playcraft image info "$f"
+done
+```
+
+如果 auto-detect 结果不理想（帧偏移、尺寸不一），退回手动参数模式，
+根据 `split-meta.json` 中报告的实际检测结果微调 `--rows --columns --frame-width --frame-height --padding`。
+
+### 方法 3：SAM3 语义分割（不规则布局首选）
+
+当 AI 生成的拼板图**不是规则网格**（元素散落、大小不一、间距不均），用 SAM3 语义分割精确提取每个对象。
+SAM3 已集成到 CLI，通过 `playcraft image segment` 调用，冷启动约 15s，热启动约 5-10s。
+
+```bash
+# ── 从散乱拼板中提取所有麻将牌 ──
+playcraft image segment \
+  --input ta-workspace/sheets/wan_grid.png \
+  --text "mahjong tile" \
+  --threshold 0.2 \
+  --output-dir ta-workspace/split/wan_sam
+
+# 输出结构：
+# ta-workspace/split/wan_sam/
+#   prompt_0_mahjong_tile/
+#     00_rgba.png   ← 已抠好透明背景，可直接用
+#     00_mask.png
+#     01_rgba.png
+#     ...
+#   segment-meta.json   ← 含每个实例的 bbox 坐标（可用于自动排序）
+
+# ── 多类型同时提取（如带底板文字 + 图案的牌）──
+playcraft image segment \
+  --input ta-workspace/sheets/mixed_layout.png \
+  --prompts '[{"text":"mahjong tile"},{"text":"game icon"}]' \
+  --threshold 0.25 \
+  --output-dir ta-workspace/split/mixed_sam
+```
+
+**SAM3 分割后的后处理**：
+
+```bash
+# SAM3 输出的 rgba.png 已是透明背景，直接统一尺寸即可（无需再跑 remove-background）
+for f in ta-workspace/split/wan_sam/prompt_0_mahjong_tile/*_rgba.png; do
+  base=$(basename "$f" _rgba.png)
+  playcraft image resize \
+    --input "$f" \
+    --output "ta-workspace/final/wan_${base}.png" \
+    --width 128 --height 168 \
+    --fit contain
+done
+```
+
+**三种切割方法对比**：
+
+| 方法 | 适用场景 | 精度 | API 消耗 |
+|------|---------|------|---------|
+| 规则网格（`--rows --columns`） | prompt 中明确指定了 NxM 网格 | 高（前提是 AI 生成规则） | 零 |
+| Vision 自动检测（`--auto-detect`） | 轻微不规则、大致网格排列 | 中 | 低（Vision API） |
+| **SAM3 语义分割**（`image segment`） | **散乱布局、不规则间距、大小不一** | **最高** | 中（SAM3 API） |
+
+**决策规则**：
+- AI 生成时用了明确的网格 prompt → 先试规则网格；失败再用 `--auto-detect`
+- 生成结果明显不规则 → 直接用 SAM3，一步到位
+- SAM3 是抠图而非坐标切割，输出直接是带透明通道的 RGBA，省去 remove-background 步骤
+
+---
+
+## Step 5: 后处理
+
+对每张切割/生成的资产做标准化处理：
+
+```bash
+# 1. 去背景（AI 生成图通常有白底/灰底）
+playcraft image remove-background \
+  --input ta-workspace/split/wan/frame_r0_c0.png \
+  --output ta-workspace/clean/wan_1.png
+
+# 复杂背景时用 AI 方法
+playcraft image remove-background \
+  --input ta-workspace/split/wan/frame_r0_c0.png \
+  --output ta-workspace/clean/wan_1.png \
+  --method ai
+
+# 2. 统一尺寸（所有元素必须完全相同的 width × height）
+playcraft image resize \
+  --input ta-workspace/clean/wan_1.png \
+  --output ta-workspace/final/wan_1.png \
+  --width 128 --height 168 \
+  --fit contain
+
+# 3. 质量校验
+playcraft image info ta-workspace/final/wan_1.png
+# → 确认：dimensions 正确、文件大小合理
+```
+
+**批量脚本模式**（TA 可用 `Bash(node:*)` 写批量处理脚本）：
+
+```bash
+# 批量去背景 + 统一尺寸
+for f in ta-workspace/split/wan/frame_r*.png; do
+  base=$(basename "$f" .png)
+  playcraft image remove-background --input "$f" --output "ta-workspace/clean/${base}.png"
+  playcraft image resize --input "ta-workspace/clean/${base}.png" --output "ta-workspace/final/${base}.png" --width 128 --height 168 --fit contain
+done
+```
+
+---
+
+## Step 6: 组装精灵图
+
+```bash
+# 将所有最终帧合并为精灵图 + JSON 帧坐标
+playcraft image sprite-sheet \
+  --inputs ta-workspace/final/wan_1.png,ta-workspace/final/wan_2.png,ta-workspace/final/wan_3.png,ta-workspace/final/wan_4.png,ta-workspace/final/wan_5.png,ta-workspace/final/wan_6.png,ta-workspace/final/wan_7.png,ta-workspace/final/wan_8.png,ta-workspace/final/wan_9.png \
+  --output ta-workspace/output/wan_sheet \
+  --columns 3 \
+  --cell-width 128 --cell-height 168 \
+  --padding 2
+
+# 结果：
+# ta-workspace/output/wan_sheet.png  — 精灵图
+# ta-workspace/output/wan_sheet.json — 帧坐标元数据
+
+# 也可以把全部 34 张合成一张总图
+playcraft image sprite-sheet \
+  --inputs ta-workspace/final/wan_1.png,...,ta-workspace/final/jian_3.png \
+  --output ta-workspace/output/mahjong_full \
+  --columns 9 \
+  --cell-width 128 --cell-height 168 \
+  --padding 2
+```
+
+---
+
+## Prompt 工程要点
+
+### 符号精度技巧
+
+现代生图模型（GPT-Image-2 等）中文字符精度已达 90%+，但仍需注意：
+
+1. **明确标注拼音**：`Chinese character 一万 (yi wan)` 比纯写 `一万` 准确率更高
+2. **单元素大图优先**：1:1 比例的单元素图比密集网格中的小元素精度高
+3. **简单背景**：`white background` 或 `plain background` 减少干扰
+4. **先验证再批量**：生成 2-3 张，人工确认符号正确后再跑全套
+
+### 风格一致性技巧
+
+1. **固定 prompt 模板**：只替换符号描述，其他措辞字字相同
+2. **双 reference-image**：概念图 + 同批已确认的成品
+3. **同一模型**：整套元素绝对不能中途换模型
+4. **同一 aspect-ratio**：保持一致避免比例偏移
+
+### Prompt 模板示例
+
+```
+单元素模板：
+"[STYLE_DESC] mahjong tile, tile shows [SYMBOL_CN] ([SYMBOL_PINYIN]),
+ game asset, [BG_DESC], front view, single tile centered, [EXTRA]"
+
+网格模板：
+"[ROWS]x[COLS] grid of [STYLE_DESC] mahjong tiles.
+ Row 1 left to right: [SYM1], [SYM2], [SYM3].
+ Row 2: [SYM4], [SYM5], [SYM6].
+ ...
+ Each tile clearly shows its symbol. Game assets, white background,
+ uniform size, evenly spaced grid, [EXTRA]"
+```
+
+---
+
+## 完整示例：从概念图生成全套麻将牌
+
+```bash
+# === Step 1: 概念图已由 Designer 提供 ===
+# ta-workspace/concept.png — 一张冰风格麻将牌示意图
+
+# === Step 2: 选择策略 C（分组生成）===
+# 34 牌 → 万(9) + 条(9) + 筒(9) + 风(4) + 箭(3) → 5 组
+
+# === Step 3: 分组生成 ===
+
+# 万字组（3×3 网格）
+playcraft tools generate-image \
+  --prompt "3x3 grid of mahjong tiles, ice crystal frosted glass style, blue-white cold translucent material. Top row left to right: 一万 (yi wan), 二万 (er wan), 三万 (san wan). Middle row: 四万 (si wan), 五万 (wu wan), 六万 (liu wan). Bottom row: 七万 (qi wan), 八万 (ba wan), 九万 (jiu wan). Each tile clearly shows red Chinese characters. Game assets, white background, uniform size, evenly spaced" \
+  --reference-image ta-workspace/concept.png \
+  --aspect-ratio 1:1 \
+  --image-model iegg-litellm/gpt-image-2 \
+  --output ta-workspace/sheets/wan_grid.png
+
+# 条子组（同样模式，reference 加上万字组成品锁定风格）
+playcraft tools generate-image \
+  --prompt "3x3 grid of mahjong tiles, ice crystal frosted glass style, blue-white cold translucent material. Top row: 一条, 二条, 三条. Middle row: 四条, 五条, 六条. Bottom row: 七条, 八条, 九条. Each tile clearly shows bamboo stick patterns. Game assets, white background, uniform size, evenly spaced" \
+  --reference-image ta-workspace/concept.png \
+  --reference-image ta-workspace/sheets/wan_grid.png \
+  --aspect-ratio 1:1 \
+  --image-model iegg-litellm/gpt-image-2 \
+  --output ta-workspace/sheets/tiao_grid.png
+
+# 筒子组
+playcraft tools generate-image \
+  --prompt "3x3 grid of mahjong tiles, ice crystal frosted glass style, blue-white cold translucent material. Top row: 一筒, 二筒, 三筒. Middle row: 四筒, 五筒, 六筒. Bottom row: 七筒, 八筒, 九筒. Each tile clearly shows circular dot patterns. Game assets, white background, uniform size, evenly spaced" \
+  --reference-image ta-workspace/concept.png \
+  --reference-image ta-workspace/sheets/wan_grid.png \
+  --aspect-ratio 1:1 \
+  --image-model iegg-litellm/gpt-image-2 \
+  --output ta-workspace/sheets/tong_grid.png
+
+# 风牌组（2×2）
+playcraft tools generate-image \
+  --prompt "2x2 grid of mahjong tiles, ice crystal frosted glass style, blue-white cold translucent material. Top row: 东 (East wind), 南 (South wind). Bottom row: 西 (West wind), 北 (North wind). Each tile clearly shows its Chinese character. Game assets, white background, uniform size, evenly spaced" \
+  --reference-image ta-workspace/concept.png \
+  --reference-image ta-workspace/sheets/wan_grid.png \
+  --aspect-ratio 1:1 \
+  --image-model iegg-litellm/gpt-image-2 \
+  --output ta-workspace/sheets/feng_grid.png
+
+# 箭牌（1×3 or 3×1）
+playcraft tools generate-image \
+  --prompt "1 row of 3 mahjong tiles, ice crystal frosted glass style, blue-white cold translucent material. Left to right: 中 (red center, zhong), 发 (green prosperity, fa), 白 (white blank, bai). Each tile clearly shows its symbol. Game assets, white background, uniform size, evenly spaced" \
+  --reference-image ta-workspace/concept.png \
+  --reference-image ta-workspace/sheets/wan_grid.png \
+  --aspect-ratio 3:1 \
+  --image-model iegg-litellm/gpt-image-2 \
+  --output ta-workspace/sheets/jian_grid.png
+
+# === Step 4: 切割 ===
+
+playcraft image sprite-split --input ta-workspace/sheets/wan_grid.png --output-dir ta-workspace/split/wan --auto-detect --hint "3x3 grid of mahjong tiles"
+playcraft image sprite-split --input ta-workspace/sheets/tiao_grid.png --output-dir ta-workspace/split/tiao --auto-detect --hint "3x3 grid of mahjong tiles"
+playcraft image sprite-split --input ta-workspace/sheets/tong_grid.png --output-dir ta-workspace/split/tong --auto-detect --hint "3x3 grid of mahjong tiles"
+playcraft image sprite-split --input ta-workspace/sheets/feng_grid.png --output-dir ta-workspace/split/feng --auto-detect --hint "2x2 grid of mahjong tiles"
+playcraft image sprite-split --input ta-workspace/sheets/jian_grid.png --output-dir ta-workspace/split/jian --auto-detect --hint "1x3 row of mahjong tiles"
+
+# === Step 5: 后处理 ===
+
+for group in wan tiao tong feng jian; do
+  for f in ta-workspace/split/$group/frame_*.png; do
+    base=$(basename "$f" .png)
+    playcraft image remove-background --input "$f" --output "ta-workspace/clean/${group}_${base}.png"
+    playcraft image resize --input "ta-workspace/clean/${group}_${base}.png" --output "ta-workspace/final/${group}_${base}.png" --width 128 --height 168 --fit contain
+  done
+done
+
+# === Step 6: 质量检查 + 组装 ===
+
+# 检查所有最终帧
+for f in ta-workspace/final/*.png; do playcraft image info "$f"; done
+
+# 组装全套精灵图（34 张, 9 列）
+playcraft image sprite-sheet \
+  --inputs $(ls ta-workspace/final/*.png | tr '\n' ',') \
+  --output ta-workspace/output/mahjong_full \
+  --columns 9 \
+  --cell-width 128 --cell-height 168 \
+  --padding 2
+
+# 最终产出：
+# ta-workspace/output/mahjong_full.png  — 全套精灵图
+# ta-workspace/output/mahjong_full.json — 帧坐标
+```
+
+---
+
+## 生图模型选择指南
+
+| 模型 | 符号/文字精度 | 风格一致性 | reference-image | 推荐场景 |
+|------|-------------|-----------|-----------------|---------|
+| `iegg-litellm/gpt-image-2` | **极高** (中文 90%+) | 极高 | ✅ | 带文字/符号的资产（麻将、扑克、棋子） |
+| `google/gemini-3.1-flash-image-preview` | 中 | 高 | ✅ 原生支持 | 图案类资产（Match-3 元素、图标） |
+| `google/gemini-2.5-flash-preview-05-20` | 中 | 高 | ✅ | 同上 |
+| `google/imagen-3.0-generate-002` | 低 | 高 | ❌ 纯文生图 | 无文字的背景/纹理 |
+
+**关键原则**：带精确文字/符号的资产 → 优先 GPT-Image-2；纯图案 → Gemini 系列即可。
+
+---
+
+## 与现有 Skill 的关系
+
+| Skill | 定位 | 本 Skill 的区别 |
+|-------|------|----------------|
+| `playcraft-image-generation` | 单张 AI 生图 | 本 Skill 覆盖「从概念到全套」的批量生成策略 |
+| `playcraft-sprite-sheet` | 多张图合并为 sheet | 本 Skill 的 Step 6 调用它 |
+| `playcraft-sprite-remix` | 已有 sheet 的换肤/重绘 | 本 Skill 是「从零生成」，不是改已有的 |
+| `playcraft-image-processing` | 单张后处理 | 本 Skill 的 Step 5 调用它 |
+| `playcraft-3d-flip-sprite` | 3D GLB 渲染精灵图 | 互补：3D 翻转动画走那边，平面批量走这边 |
+
+---
+
+## 注意事项
+
+1. **先验证再批量**：前 2-3 张生成后人工确认符号正确、风格满意，再批量跑
+2. **同一模型贯穿全套**：中途换模型会打破风格一致性
+3. **保留 raw 产物**：`ta-workspace/sheets/` 和 `ta-workspace/split/` 保留原始中间产物，方便重切
+4. **符号出错时的降级方案**：若 AI 对某个符号始终画错，该元素退回逐张生成（策略 A），其余继续批量
+5. **API 限流**：批量生成时注意 provider 的 rate limit，按需在调用间加 sleep
+6. **总资产预算**：可玩广告全部素材通常 ≤ 2-3 MB，精灵图分辨率不宜过高

package/skills/playcraft-sprite-remix/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: playcraft-sprite-remix
+description: 精灵图（sprite sheet）拆解、逐帧 AI 重绘、去背景与重组装的完整流水线。适用于换肤、风格变换、牌面/图集批量处理；通过 playcraft CLI 在沙箱内执行，分析步骤可走后端 Vision API。
+compatibility: agent,opencode
+triggers: 精灵图, sprite sheet, 图集, 换肤, 风格变换, 逐帧, 麻将牌, tile sheet, atlas remix
+---
+
+## Skill Definition
+tools:
+  - bash
+  - read
+prompt_extension: |
+  你是精灵图管线工程师。不得向 /project/ 写入；中间产物与最终输出必须在会话 .../sessions/{id}/ta-workspace/ 下。
+  当用户提到精灵图、sprite sheet、图集换肤、逐帧重绘、牌面风格变换等需求时，优先采用「分析/拆分 → 逐帧生成 → 去背景 → 重组 → 对比验收」流程，而不是把整张图直接丢给生图模型。
+  通过 bash 调用 playcraft CLI：sprite-split（可选 Vision）、tools generate-image、image remove-background、image sprite-sheet。
+  需要多模态理解布局时，使用 `playcraft image sprite-split --input ... --output-dir ... --auto-detect [--hint "..."]`（消耗后端 Vision 配额）。
+  若网格行列与帧尺寸已知，用手动参数省略 Vision：`--rows --columns --frame-width --frame-height [--padding]`。
+  交付到素材库时按 docs/agent/remixable-prefab-spec.md 整理 staging 后执行 `playcraft tools publish-prefab`。
+
+## 我做什么
+
+- 将整张精灵图拆成独立帧（规则网格或不规则元素）
+- 按统一风格或用户要求对每帧做图生图（`playcraft tools generate-image` + `--reference-image`）
+- 逐帧去背景（优先 `remove-background` 默认 floodfill；复杂底用 `--method ai`）
+- 用 `playcraft image sprite-sheet` 按原拓扑拼回 PNG + JSON
+- 产出 `split-meta.json` 记录裁切与网格，便于复现与人工微调
+
+## 何时用我
+
+- 用户明确在处理 **sprite sheet / 精灵图 / 纹理图集**，且需要 **保留网格或元素位置**
+- 整张图直接文生图/图生图效果差、帧错位、风格不一致
+- 需要批量对 **每一格 / 每一元素** 单独生成或变换
+
+## 推荐工作流（6 步）
+
+### 1–2. 分析与拆分（一步 CLI）
+
+```bash
+# Vision 自动推断网格（需 PLAYCRAFT_API_URL + PLAYCRAFT_SANDBOX_TOKEN或 .playcraft.json）
+playcraft image sprite-split \
+  --input ta-workspace/source-sheet.png \
+  --output-dir ta-workspace/split_frames \
+  --auto-detect \
+  --hint "mahjong tiles, uniform grid, equal cell size"
+
+# 或已知网格时（纯本地 sharp，不调后端）
+playcraft image sprite-split \
+  --input ta-workspace/source-sheet.png \
+  --output-dir ta-workspace/split_frames \
+  --rows 4 --columns 10 --frame-width 100 --frame-height 130 --padding 2
+```
+
+输出：`split_frames/frame_r*_c*.png`（或不规则时的按元素命名）、`split_frames/split-meta.json`。
+
+### 3. 逐帧重生成
+
+对每一帧单独调用（可并行多个 bash 命令，注意 API 限流）：
+
+```bash
+playcraft tools generate-image \
+  --prompt "same tile, frozen ice style, keep symbol readable, game asset" \
+  --reference-image ta-workspace/split_frames/frame_r0_c0.png \
+  --aspect-ratio 1:1 \
+  --output ta-workspace/remix_frames/frame_r0_c0.png
+```
+
+多帧时循环处理；单帧失败只需重试该帧。
+
+### 4. 去背景
+
+```bash
+playcraft image remove-background \
+  --input ta-workspace/remix_frames/frame_r0_c0.png \
+  --output ta-workspace/remix_frames_nobg/frame_r0_c0.png
+```
+
+复杂背景再考虑 `--method ai`。
+
+### 5. 重组精灵图
+
+根据 `split-meta.json` 中的行列与 `frameWidth` / `frameHeight` / `padding` 与 `sprite-sheet` 对齐（与拆分时一致）：
+
+```bash
+playcraft image sprite-sheet \
+  --inputs ta-workspace/remix_frames_nobg/frame_r0_c0.png,ta-workspace/remix_frames_nobg/frame_r0_c1.png \
+  --output ta-workspace/remixed-sheet \
+  --columns 10 \
+  --cell-width 100 --cell-height 130 \
+  --padding 2
+```
+
+（`--inputs` 顺序须与拼图行列一致；帧数多时用脚本生成逗号列表。）
+
+### 6. Review（对比验收）
+
+将 **原图** 与 **新精灵图** 作为参考图，请求模型做一致性/对齐简述（可选，用于汇报或自检）：
+
+```bash
+playcraft tools generate-image \
+  --prompt "Compare layout: does the second image preserve the grid and approximate content of the first? Answer briefly in English." \
+  --reference-image ta-workspace/source-sheet.png \
+  --reference-image ta-workspace/remixed-sheet.png \
+  --aspect-ratio 1:1 \
+  --output ta-workspace/review_note.png
+```
+
+若仅需文字反馈，可改为由 Manager/Reviewer 角色阅读两张图；CLI 仍会生成一张图，可按项目约定使用或丢弃。
+
+## 局部 remix：不拆整张，只替换单一元素
+
+已知某个元素在原图上的 bounds（例如某个按钮位于 x=120 y=240 宽 160 高 64），想仅重绘该元素并贴回原图：
+
+```bash
+# 1) 裁出目标区域（可向外扩 ~10% 给模型一点上下文）
+playcraft image crop \
+  --input ta-workspace/source-sheet.png \
+  --output ta-workspace/region.png \
+  --x 104 --y 234 --width 192 --height 76
+
+# 2) 以裁剪片作为 reference 做 image-to-image
+playcraft tools generate-image \
+  --prompt "green rounded rectangle button with white text 'Start', flat UI" \
+  --reference-image ta-workspace/region.png \
+  --aspect-ratio 1:1 \
+  --output ta-workspace/region_remixed.png
+
+# 3) 抠掉新片段的背景/边框
+playcraft image remove-background \
+  --input ta-workspace/region_remixed.png \
+  --output ta-workspace/region_remixed_nobg.png
+
+# 4) 贴回原图（注意 x/y 是粘贴起点，这里是 104/234，而不是 bounds 原点）
+playcraft image overlay \
+  --base ta-workspace/source-sheet.png \
+  --overlay ta-workspace/region_remixed_nobg.png \
+  --output ta-workspace/source-sheet.v2.png \
+  --x 104 --y 234
+```
+
+4 步各是一个原子，可单独替换：
+- 不需要外扩时 step 1 使用原始 bounds 即可。
+- 场景融合足够好时 step 3 可跳过。
+- 多元素批量换皮时把这套流程写在一个 for 循环里，或对每个元素走一遍 step 1–4 并合到同一底图上。
+
+## 与现有 Skill 的关系
+
+- **playcraft-sprite-sheet**：仅负责「多图合并为 sheet」；本 Skill 覆盖「从 sheet 出发的完整 remix」
+- **playcraft-image-generation**：单图生成；本 Skill 强调 **逐帧** 与 **结构保持**
+- **playcraft-image-processing**：缩放、裁剪、像素化等本地处理；在本流程中可与 remix 步骤穿插使用
+
+## 注意事项
+
+- **不要**对整张 sprite sheet 一次性下「全部改成某风格」的生图指令作为主路径
+- `--auto-detect` 有成本；已知规格时务必用手动网格减少调用
+- 不规则图集（`gridType: irregular`）重组时需按 `split-meta.json` 中元素坐标逐个 `overlay` 或扩展 `sprite-sheet` 工作流；优先在 ta-workspace 用脚本或分步 composite 还原布局