@playcraft/cli 0.0.57 → 0.0.58

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

@@ -0,0 +1,423 @@
+---
+name: playcraft-sprite-generation
+description: PlayCraft 批量元素一次性生成完整指南。涵盖 sprite sheet / 元素拼图 / UI 组件集等所有"多元素同图生成"场景。包含 Canvas 规格计算、五段式 Prompt 模板、9 项核查清单、全量生成命令、逐格校验与定向修补流程、切割脚本模板，以及麻将 42-tile 完整示例。TA 在进行任何批量元素生成前必读。
+triggers: sprite sheet,精灵图,批量生成,一次性生成,元素拼图,全量生成,tile sheet,icon sheet,UI组件集,grid generation,多元素同图,spritesheet,拼图生成,图标集,decompose-layers,crop,切割
+---
+
+# PlayCraft 批量元素一次性生成指南
+
+## 0. 适用场景判断
+
+**何时使用全量同图生成**：
+
+| 场景                  | 示例                                            | 推荐方式     |
+| --------------------- | ----------------------------------------------- | ------------ |
+| 同类型多元素（>3 个） | 42 张麻将牌、9 种水果、8 个图标                 | 全量同图生成 |
+| UI 组件集             | 按钮组（normal/hover/pressed × 3 种）、HUD 元素 | 全量同图生成 |
+| 角色表情/姿态集       | 6 种表情、8 个方向                              | 全量同图生成 |
+| 同风格背景变体        | 3 个关卡背景                                    | 全量同图生成 |
+
+**何时不适用**：
+
+- 单个大尺寸资产（如 1080×1920 背景）→ 直接单独生成
+- 元素间风格差异大（如写实 + 卡通混合）→ 分别生成
+- 需要精确透明度/alpha 通道 → 生成后需 remove-background 处理
+
+### 生成后从同图提取单格（与 `playcraft-masking` 对齐）
+
+| 布局                                        | 推荐提取方式                                               |
+| ------------------------------------------- | ---------------------------------------------------------- |
+| **规则网格 spritesheet**（本节主流程）      | `playcraft image crop` + 下方切割脚本                      |
+| **散乱/非网格拼图**                         | `segment --boxes` 或 SAM3（慎用纯 text prompt）            |
+| **整张 Master Composite**（非 spritesheet） | `playcraft image decompose-layers`（302 整图分层，非逐格） |
+
+> 网格图**不要**用 `decompose-layers` 代替 crop；整图分层也**不能**指定「只要第 N 格」。
+
+---
+
+## 1. Canvas 规格计算
+
+### 公式
+
+```
+totalWidth  = cols × cellWidth  + (cols - 1) × gap
+totalHeight = rows × cellHeight + (rows - 1) × gap
+
+# 对齐到 16 的倍数（对 GPU 纹理和视频编码友好）
+alignedWidth  = ceil(totalWidth / 16) × 16
+alignedHeight = ceil(totalHeight / 16) × 16
+
+# 约束：不超过模型最大分辨率
+assert alignedWidth  ≤ 4096
+assert alignedHeight ≤ 4096
+```
+
+### 快速参考表
+
+| 元素数 | 推荐网格 | 单格尺寸（gap=10） | 画布尺寸              |
+| ------ | -------- | ------------------ | --------------------- |
+| 9      | 3×3      | 1024×1024          | 3092×3092 → 3104×3104 |
+| 16     | 4×4      | 768×768            | 3102×3102 → 3104×3104 |
+| 25     | 5×5      | 680×680            | 3440×3440 → 3440×3440 |
+| 36     | 6×6      | 560×560            | 3410×3410 → 3424×3424 |
+| 42     | 7×6      | 80×100 (small)     | 624×656 → 624×656     |
+| 42     | 7×6      | 540×540            | 3840×3290 → 3840×3296 |
+
+> 建议优先使用大单格尺寸（≥540px），牺牲格数不如牺牲精度。如果元素数多（>36），可接受较小单格但不低于 80px。
+
+### gap 选择
+
+- gap=0：元素紧贴，适合最终游戏用的 sprite sheet（开发者按像素切）
+- gap=10-20：元素有间距，适合 AI 生成（防止跨格渲染污染）
+- **推荐 AI 生成时 gap=10-20px**，切割后丢弃 gap 区域
+
+---
+
+## 2. 五段式 Prompt 模板
+
+AI 生图 prompt 必须严格遵循五段式结构（Scene → Canvas → Element Set → Details → Constraints）：
+
+```
+Scene: [背景色 + hex + 用途，1-2 句].
+
+Canvas: a strict [ROWS]-row by [COLS]-column spritesheet.
+Final canvas size: [W]×[H] pixels (both multiples of 16).
+Each element is exactly [CELL_W] pixels wide and [CELL_H] pixels tall.
+Horizontal and vertical gaps between elements: [GAP] pixels.
+All rows are left-aligned.
+
+Element set: all [N] [ELEMENT_TYPE], each appearing exactly once, arranged in the following order:
+- Row 1: [id_1 (标签)], [id_2 (标签)], ..., [id_COLS (标签)]
+- Row 2: [id_COLS+1], ..., [id_2×COLS]
+- ...
+- Row [ROWS]: [remaining elements, mark empty cells if any]
+
+Details:
+- Every element is identical in size ([CELL_W]×[CELL_H] px) with [edge treatment].
+- Material/texture: [具体材质描述].
+- [Category 1] elements: [颜色 + 样式].
+- [Category 2] elements: [颜色 + 样式].
+- ...
+- Art style: [风格关键词，引用 design-brief].
+
+Constraints:
+- No [unwanted_1], no [unwanted_2], no [unwanted_3].
+- All symbols/text must be [质量要求].
+- [其他技术约束].
+```
+
+### 五段式强制规则
+
+| 段落        | 必须包含                     | 禁止                           |
+| ----------- | ---------------------------- | ------------------------------ |
+| Scene       | 背景色 hex + 用途            | 不写风格（风格在 Details 段）  |
+| Canvas      | 精确像素：画布/单格/gap/对齐 | 不写模糊尺寸如 "large"         |
+| Element Set | 逐行完整枚举 + 中文标签      | 不省略（"etc." 或 "..."）      |
+| Details     | 按分类描述材质/颜色/风格     | 不写单一笼统描述覆盖所有       |
+| Constraints | ≥3 条 "No xxx"               | 不写正面描述（正面在 Details） |
+
+---
+
+## 3. Prompt 核查清单
+
+生成前对照以下 9 项逐一核查（在 `logs/ta-log.md` 中打勾），**全部通过才可执行生成命令**：
+
+| #   | 核查项                        | 标准                                                |
+| --- | ----------------------------- | --------------------------------------------------- |
+| 1   | **Scene 段存在**              | 背景色 hex 明确                                     |
+| 2   | **Canvas 像素精确**           | 画布/单格/gap 为精确数值，且是 16 倍数              |
+| 3   | **Element Set 完整**          | 逐行枚举数量 = assetMapping 总数，无遗漏无重复      |
+| 4   | **Details 分类描述**          | 每类元素有独立的颜色/材质描述，引用 layout-spec hex |
+| 5   | **Details 引用 Style Intent** | 风格关键词来自 artist-log Style Intent Notes        |
+| 6   | **Constraints 负面约束**      | ≥3 条 "No xxx"，含 Anti-Pattern Notes 中的禁忌      |
+| 7   | **Canvas ≤ 4096px**           | 总尺寸不超过模型最大分辨率                          |
+| 8   | **--reference-image 指定**    | 指向 ASR element sheet 或 Master Composite          |
+| 9   | **Prompt 已记录**             | 完整 prompt 已写入 `logs/ta-log.md`                 |
+
+**任何一项未通过 → 修正后重新核查。不可跳过。**
+
+---
+
+## 4. 全量生成命令
+
+```bash
+playcraft tools generate-image \
+  --prompt "<五段式 prompt，已通过核查>" \
+  --output assets/images/[type]/spritesheet_[type].png \
+  --reference-image <asr-element-sheet-or-composite-path> \
+  --image-size 1K \
+  --image-model gpt-image-2
+
+# 自动生成的 .json sidecar 记录完整 prompt + 配置
+# 检查确认：
+cat assets/images/[type]/spritesheet_[type].json
+```
+
+### `--image-size` 与画布尺寸的关系
+
+`--image-size` 接受预设值 `1K`、`2K`、`4K`。实际输出像素由 `aspectRatio + imageSize` 联合决定——对 gpt-image-2: `1:1+4K`→2048x2048, `16:9+4K`→3840x2160, `1:1+1K`→1024x1024。
+
+| 情况             | `--image-size` 设置                  | 后续处理                                                 |
+| ---------------- | ------------------------------------ | -------------------------------------------------------- |
+| 画布 ≤ 1024px    | `1K`                                 | 模型输出 ~1024px，**必须 resize 到目标画布尺寸后再切割** |
+| 画布 1024–4096px | `4K`                                 | 直接切割                                                 |
+| 需要最大精度     | `4K` + 放大单格尺寸使画布接近 4096px | 直接切割                                                 |
+
+**当模型输出 > 实际画布尺寸时的处理流程**：
+
+```bash
+# 1. 生成（模型输出 ~1024px）
+playcraft tools generate-image --prompt "..." --output tmp_sheet.png --image-size 1K ...
+
+# 2. Resize 到实际画布尺寸（保持网格比例）
+playcraft image resize --input tmp_sheet.png --width [alignedWidth] --height [alignedHeight] --output assets/images/[type]/spritesheet_[type].png
+
+# 3. 然后正常切割
+```
+
+> **推荐**：优先选择大单格尺寸方案（≥540px），使画布接近 4096×4096，避免先生成再缩放的精度损失。
+
+### 模型选择
+
+| 模型          | 适用                                   | 注意               |
+| ------------- | -------------------------------------- | ------------------ |
+| gpt-image-2   | 首选——复杂布局、中文字符、多元素一致性 | 慢（~7-8 min），贵 |
+| nano-banana-2 | 备选——简单图形、无文字元素             | 快，中文字符不可靠 |
+| gemini-flash  | 备选——色彩鲜艳场景                     | 网格理解弱         |
+
+**中文字符场景（麻将/汉字标签）必须用 gpt-image-2。**
+
+### 元素数超限时的分批策略
+
+当元素总数使画布无法在 4096px 内保持 ≥ 80px 单格时，需分批生成：
+
+```
+最大可容纳元素数 ≈ (4096 ÷ (cellSize + gap))²
+# 例：cellSize=540, gap=10 → (4096÷550)² ≈ 49 个
+# 例：cellSize=256, gap=10 → (4096÷266)² ≈ 237 个（但精度低）
+```
+
+**分批原则**：
+
+- 按元素类别分 sheet（如：萬子一张、條子一张），每张 sheet 内部风格一致
+- 所有 sheet 使用**相同的 `--reference-image` + 相同模型**，保证跨 sheet 风格统一
+- 在 `logs/ta-log.md` 中标注分批策略和每张 sheet 包含的元素清单
+
+---
+
+## 5. 逐格校验 + 定向修补
+
+### 校验标准
+
+生成后逐格对照 Element Set 清单检查：
+
+| 校验项     | 通过标准                                      |
+| ---------- | --------------------------------------------- |
+| 元素存在   | 格内有完整元素，无空格、无残缺                |
+| 符号正确   | 文字/图案与清单描述一致（无笔画错误、无乱码） |
+| 尺寸一致   | 各格元素大小视觉统一（允许 ±5% 偏差）         |
+| 无跨格污染 | 元素不越界到相邻格                            |
+| 风格统一   | 颜色、材质、光照与其他格一致                  |
+
+### 修补决策
+
+| 错误比例                        | 策略                                  |
+| ------------------------------- | ------------------------------------- |
+| ≤ 30%（如 42 格中 ≤ 12 格错误） | 逐格定向修补                          |
+| > 30%                           | 修改 prompt → 重新核查 → 重新全量生成 |
+
+### 定向修补流程
+
+```bash
+# 用整张 sheet 作为 reference-image，保证修补格与其他格风格一致
+playcraft tools generate-image \
+  --prompt "Single [ELEMENT_TYPE]: [错误格子的详细描述，从原 prompt Element Set 段摘取]. Same art style as reference. On solid [BG_COLOR] background. Centered in frame." \
+  --reference-image assets/images/[type]/spritesheet_[type].png \
+  --output ta-workspace/tmp/fix_[element_id].png \
+  --image-size 1K \
+  --image-model gpt-image-2
+```
+
+**修补后**：resize 到 cellW×cellH → 替换到最终切割输出中（不修改原 sheet 文件）：
+
+```bash
+playcraft image resize \
+  --input ta-workspace/tmp/fix_[element_id].png \
+  --width [cellW] --height [cellH] \
+  --output assets/images/[type]/tile_[element_id].png
+```
+
+---
+
+## 6. 切割 + 替换 + 验证
+
+### 切割脚本模板
+
+```javascript
+// ta-workspace/scripts/split-spritesheet.mjs
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync } from 'fs';
+
+const CONFIG = {
+  input: 'assets/images/tiles/spritesheet_mahjong.png',
+  outputDir: 'assets/images/tiles/',
+  cols: 7,
+  rows: 6,
+  cellW: 80,
+  cellH: 100,
+  gap: 10,
+  names: [
+    '1wan',
+    '2wan',
+    '3wan',
+    '4wan',
+    '5wan',
+    '6wan',
+    '7wan',
+    '8wan',
+    '9wan',
+    '1tiao',
+    '2tiao',
+    '3tiao',
+    '4tiao',
+    '5tiao',
+    '6tiao',
+    '7tiao',
+    '8tiao',
+    '9tiao',
+    '1tong',
+    '2tong',
+    '3tong',
+    '4tong',
+    '5tong',
+    '6tong',
+    '7tong',
+    '8tong',
+    '9tong',
+    'east',
+    'south',
+    'west',
+    'north',
+    'red_dragon',
+    'green_dragon',
+    'white_dragon',
+    'spring',
+    'summer',
+    'autumn',
+    'winter',
+    'plum',
+    'orchid',
+    'bamboo',
+    'chrysanthemum',
+  ],
+};
+
+mkdirSync(CONFIG.outputDir, { recursive: true });
+
+for (let row = 0; row < CONFIG.rows; row++) {
+  for (let col = 0; col < CONFIG.cols; col++) {
+    const idx = row * CONFIG.cols + col;
+    if (idx >= CONFIG.names.length) break;
+
+    const x = col * (CONFIG.cellW + CONFIG.gap);
+    const y = row * (CONFIG.cellH + CONFIG.gap);
+    const name = CONFIG.names[idx];
+    const output = `${CONFIG.outputDir}tile_${name}.png`;
+
+    if (existsSync(output)) continue; // idempotent
+
+    execSync(
+      `playcraft image crop --input ${CONFIG.input} --x ${x} --y ${y} --width ${CONFIG.cellW} --height ${CONFIG.cellH} --output ${output}`,
+    );
+    console.log(`[${idx + 1}/${CONFIG.names.length}] ${output}`);
+  }
+}
+console.log('Done. Split complete.');
+```
+
+### 替换修补格
+
+```bash
+# 修补的格子直接覆盖切割输出
+cp ta-workspace/tmp/fix_east.png assets/images/tiles/tile_east.png
+cp ta-workspace/tmp/fix_red_dragon.png assets/images/tiles/tile_red_dragon.png
+```
+
+### 最终验证
+
+```bash
+# 逐文件检查尺寸一致
+playcraft image info assets/images/tiles/tile_*.png
+
+# 确认文件数量 = Element Set 清单数量
+ls assets/images/tiles/tile_*.png | wc -l
+```
+
+---
+
+## 7. 完整示例：麻将 42-tile Sprite Sheet
+
+### Define
+
+```
+总元素数: 42
+网格布局: 7 cols × 6 rows = 42 cells (all used)
+单格尺寸: 80×100 px
+Gap: 10 px
+画布尺寸: 7×80 + 6×10 = 620 → aligned 624 | 6×100 + 5×10 = 650 → aligned 656
+最终: 624×656 px
+背景: #00FF00 (green-screen)
+模型: gpt-image-2
+参考图: assets/images/storyboard/master_composite.png
+```
+
+### Prompt
+
+```
+Scene: pure green background (#00FF00) for easy keying.
+
+Canvas: a strict 6-row by 7-column spritesheet.
+Final canvas size: 624×656 pixels (both multiples of 16).
+Each tile is exactly 80 pixels wide and 100 pixels tall.
+Horizontal and vertical gaps between tiles: 10 pixels.
+All rows are left-aligned.
+
+Tile set: all 42 standard Mahjong tiles, each appearing exactly once, arranged in the following order:
+- Row 1: 1wan (一萬), 2wan (二萬), 3wan (三萬), 4wan (四萬), 5wan (五萬), 6wan (六萬), 7wan (七萬)
+- Row 2: 8wan (八萬), 9wan (九萬), 1tiao (一條), 2tiao (二條), 3tiao (三條), 4tiao (四條), 5tiao (五條)
+- Row 3: 6tiao (六條), 7tiao (七條), 8tiao (八條), 9tiao (九條), 1tong (一筒), 2tong (二筒), 3tong (三筒)
+- Row 4: 4tong (四筒), 5tong (五筒), 6tong (六筒), 7tong (七筒), 8tong (八筒), 9tong (九筒), East wind (東)
+- Row 5: South wind (南), West wind (西), North wind (北), Red dragon (中), Green dragon (發), White dragon (白), Spring (春)
+- Row 6: Summer (夏), Autumn (秋), Winter (冬), Plum (梅), Orchid (蘭), Bamboo (竹), Chrysanthemum (菊)
+
+Details:
+- Every tile is identical in size (80×100 px) with 4px rounded corners and thin 1px dark border (#333333).
+- Tile surface: brushed brass/bronze metallic texture with subtle reflections.
+- Wan (萬) suit: Chinese numeral + "萬" character in dark red (#8B0000), traditional Kaiti calligraphy.
+- Tiao (條) suit: stylized bamboo stalks in dark green (#1B5E20), count matches the number.
+- Tong (筒) suit: ornamental coin/circle patterns in dark green (#2E4E2E) with concentric ring detail.
+- Wind tiles (東南西北): large bold Chinese character in dark ink (#1A1A1A), centered.
+- Dragon tiles: 中=red character on tile, 發=green character on tile, 白=blank/framed tile.
+- Flower/Season tiles (春夏秋冬梅蘭竹菊): small botanical/seasonal illustration + Chinese character label at top.
+- Art style: Chinese traditional aesthetic, elegant and clean, premium mobile game quality.
+
+Constraints:
+- No cast shadows behind tiles, no perspective distortion, no 3D rotation.
+- No extra text, no labels outside tiles, no watermarks, no visible grid lines.
+- No background texture — pure flat #00FF00.
+- All Chinese characters must be sharp, legible, and correctly written (no garbled strokes).
+- Strictly front-on orthographic view for all 42 tiles.
+```
+
+### 执行
+
+```bash
+playcraft tools generate-image \
+  --prompt "<上述完整 prompt>" \
+  --output assets/images/tiles/spritesheet_mahjong.png \
+  --reference-image assets/images/storyboard/master_composite.png \
+  --image-size 1K \
+  --image-model gpt-image-2
+```
+
+> 注：624×656 小于模型最小输出（~1024px），模型会自动适配。如需更高精度，可将单格放大到 540×540（画布 3840×3290）并使用 `--image-size 4K`。

package/project-template-v2/.claude/skills/playcraft-sprite-remix/SKILL.md

@@ -0,0 +1,158 @@
+---
+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 还原布局

package/project-template-v2/.claude/skills/playcraft-sprite-sheet/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: playcraft-sprite-sheet
+description: 可玩广告流程步骤 7（可选）。将多张图片合并为精灵图（sprite sheet），输出 PNG 及 JSON 帧坐标元数据。通过 `playcraft image sprite-sheet` 命令在沙箱本地执行，无需 backend。
+compatibility: agent,opencode
+---
+
+## Skill Definition
+
+tools:
+
+- bash
+- read
+  prompt_extension: |
+  你是精灵图合成师。不得向 /project/ 写入；所有输出必须在会话 .../sessions/{id}/ta-workspace/ 下。
+  通过 bash 工具运行 `playcraft image sprite-sheet` CLI 命令将多张图合并为 PNG + JSON 元数据，全程本地执行，无需往返 backend。
+  若需交付到素材库，先按 docs/agent/remixable-prefab-spec.md 整理 staging，再通过 bash 运行 `playcraft tools publish-prefab` CLI 命令。
+
+## 我做什么
+
+- 将多张图片合并为精灵图（sprite sheet）
+- 输出：精灵图 PNG + JSON 元数据（每帧的 x, y, w, h 及文件名索引）
+- 可与 playcraft-image-generation、playcraft-image-processing 串联使用
+
+## 何时用我
+
+当变体需要：
+
+- 角色动画（idle、walk、jump 等多帧）
+- 序列帧动画
+- 多张小图合并为图集（减少 draw call）
+
+## 命令用法
+
+```bash
+playcraft image sprite-sheet \
+  --inputs <图1>,<图2>,<图3>,... \
+  --output <ta-workspace内的基路径>   # 自动生成 .png 和 .json
+  [--columns <列数>]                  # 默认按平方根自动计算
+  [--padding <帧间距像素>]             # 默认 0
+  [--cell-width <宽>]                 # 默认用第一张图的宽
+  [--cell-height <高>]                # 默认用第一张图的高
+```
+
+### 输出文件
+
+- `<output>.png` — 精灵图 PNG
+- `<output>.json` — 帧坐标数据，格式如下：
+  ```json
+  {
+    "frames": {
+      "hero_idle_0.png": { "x": 0, "y": 0, "w": 64, "h": 64 },
+      "hero_idle_1.png": { "x": 64, "y": 0, "w": 64, "h": 64 }
+    },
+    "meta": { "image": "hero.png", "size": { "w": 256, "h": 64 }, "scale": 1 }
+  }
+  ```
+
+## 工作流
+
+1. **准备帧图片**：从 /project 只读读取参考图，或引用 ta-workspace 内已生成/处理的帧图
+2. **（可选）统一尺寸**：用 `playcraft image resize` 确保所有帧尺寸一致
+3. **合并精灵图**：
+   ```bash
+   playcraft image sprite-sheet \
+     --inputs ta-workspace/frame_0.png,ta-workspace/frame_1.png,ta-workspace/frame_2.png \
+     --output ta-workspace/hero-sheet \
+     --columns 4 \
+     --cell-width 64 --cell-height 64
+   # 生成：ta-workspace/hero-sheet.png 和 ta-workspace/hero-sheet.json
+   ```
+4. **（可选）交付到素材库**：
+   ```bash
+   playcraft tools publish-prefab \
+     --remix-project-id <ID> --template <名> --variant <名> --prefab <名> \
+     --staging-root <staging路径>
+   ```
+
+## 与步骤 5、6 融合
+
+完整流程示例：
+
+```bash
+# 步骤 5：AI 生成帧
+playcraft tools generate-image --prompt "hero idle frame 1, pixel art, transparent background" --output ta-workspace/f0.png
+playcraft tools generate-image --prompt "hero idle frame 2, pixel art, transparent background" --output ta-workspace/f1.png
+
+# 步骤 6：统一尺寸
+playcraft image resize --input ta-workspace/f0.png --output ta-workspace/f0_64.png --width 64 --height 64 --fit contain
+playcraft image resize --input ta-workspace/f1.png --output ta-workspace/f1_64.png --width 64 --height 64 --fit contain
+
+# 步骤 7：合并精灵图
+playcraft image sprite-sheet \
+  --inputs ta-workspace/f0_64.png,ta-workspace/f1_64.png \
+  --output ta-workspace/hero-idle \
+  --cell-width 64 --cell-height 64
+```
+
+## 游戏引擎兼容
+
+JSON 格式设计兼容常见引擎（Phaser、PlayCanvas 的 sprite 格式），key 为文件名，value 含 x/y/w/h 坐标。