@playcraft/cli 0.0.39 → 0.0.41

package/project-template/.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** | 风格关键词来自 designer-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/.claude/skills/playcraft-storyboard/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: playcraft-storyboard
+description: PlayCraft Master Composite 生成指南。5 格完整 9:16 H5 竖屏拼成一张审阅图（横排或网格均可）。Designer Phase 1 必读。
+triggers: 故事板,storyboard,4帧,四帧,体验流,experience flow,合成图,composite,master composite,Hook场景,EndCard场景,故事板生成,storyboard generation,gameplay flow visual,concept panel,5面板
+---
+
+# PlayCraft Master Composite 生成指南
+
+## 0. 核心尺寸原则（只看比例）
+
+**每一格 = 一张完整 H5 竖屏，宽高比固定 9:16**（与 `layout-spec.md` 的 1080×1920 一致）。
+
+**整张输出 = 5 张完整 H5 的拼接**——可以横排，也可以 2+3 网格等；**禁止**把 5 个竖屏塞进 1:1 / 3:2 画布导致单格变形。
+
+### 单格（H5 viewport）
+
+| 字段     | 值                         |
+| -------- | -------------------------- |
+| 宽高比   | **9:16**（宽/高 = 0.5625） |
+| 合约参考 | 1080 × 1920                |
+
+### 整图（5 格横排，默认布局）
+
+```
+┌────┬────┬────┬────┬────┐
+│9:16│9:16│9:16│9:16│9:16│   每格等宽等高，互不裁切
+└────┴────┴────┴────┴────┘
+总宽高比 = 5×9 : 16 = 45:16  （≈ 2.81，不是 10:3，不是 1:1）
+```
+
+| 档位            | 单格尺寸       | 整图尺寸（5 横排）                         |
+| --------------- | -------------- | ------------------------------------------ |
+| 推荐 2K         | **720 × 1280** | **3600 × 1280**                            |
+| 4K（长边≤4096） | **819 × 1455** | **4096 × 1455**                            |
+| 合约 1:1 缩放   | 1080 × 1920    | 5400 × 1920（超 4K 宽，需 302 或接受缩小） |
+
+> **已废弃**：720×1080（2:3）、3600×1080、`--aspect-ratio 10:3` — 单格不是 H5，会压扁/拉长。
+
+### 可选布局（仍是 5 张完整 9:16）
+
+| 布局                 | 整图宽×高（单格 W×H） | 说明                                     |
+| -------------------- | --------------------- | ---------------------------------------- |
+| **1×5 横排**（默认） | `5W × H`              | Gate #2 审阅最常用                       |
+| 2+3 网格             | `3W × 2H`             | 上行 2 屏、下行 3 屏；prompt 须写明 grid |
+| 5×1 竖排             | `W × 5H`              | 过高，一般不推荐（易超 4096 高）         |
+
+选用非横排时，prompt 必须写清 **grid layout**，且 **each cell still 9:16 full mobile screen**。
+
+---
+
+## 1. 五格内容（Panel 1–5）
+
+> **术语**（与 `docs/team/collaboration.md` 一致）：**Panel 1 = concept panel**（Main Gameplay，含全部元素类型 + 静态文字 + 完整 UI，TA 主提取源）；**Panels 2–5 = storyboard panels**（体验流分镜，Developer 对照）。
+
+| #   | 面板                              | 用途               |
+| --- | --------------------------------- | ------------------ |
+| 1   | Main Gameplay (**concept panel**) | 完整游戏截屏       |
+| 2   | Key Hook                          | 高光 / combo       |
+| 3   | Onboarding HUD                    | 教学引导           |
+| 4   | End Card                          | 结算 + Install CTA |
+| 5   | CTA Always Visible                | 游戏中 CTA 常驻    |
+
+---
+
+## 2. Prompt 公式
+
+```
+Mobile game UI contact sheet: exactly 5 separate complete portrait mobile game screens.
+
+CRITICAL SIZE: Each of the 5 cells is a full 9:16 H5 playable viewport (same proportions as 1080x1920). Cells must NOT be stretched or squashed. Equal cell width and height.
+
+Layout: [five equal panels in one horizontal row | OR 2+3 grid as specified].
+
+Panel 1 '1. Main Gameplay': ...
+Panel 2 '2. Key Hook': ...
+Panel 3 '3. Onboarding HUD': ...
+Panel 4 '4. End Card': ...
+Panel 5 '5. CTA Always Visible': ...
+
+[STYLE_KEYWORDS]. Thin dividers between cells only. Numbered label on top of each cell.
+Total image exactly [3600] pixels wide by [1280] pixels tall (five 720x1280 cells in a row).
+```
+
+**必须约束词**：
+
+- `each cell is a full 9:16 H5 viewport` / `1080x1920 proportions`
+- `equal cell width and height` / `NOT stretched`
+- 总像素与布局一致（横排：`3600x1280` 或 `4096x1455`）
+
+---
+
+## 3. 生成命令
+
+```bash
+playcraft tools generate-image \
+  --prompt "<Section 2>" \
+  --output assets/images/storyboard/master_composite_option_[N].png \
+  --image-model mulerouter/gpt-image-2 \
+  --aspect-ratio 45:16 \
+  --image-size 2K \
+  --width 3600 \
+  --height 1280
+```
+
+> **必须**使用 `mulerouter/gpt-image-2`（或已配置的 `302/...`）。**禁止**裸 `gpt-image-2`——fallback 会先走 `iegg-litellm`，成功时只能出 **1536×1024**，五格竖屏会被压扁。CLI 会在保存后自动校验像素，不合格直接失败。
+
+**4K 档**：`--image-size 4K --width 4096 --height 1455`
+
+| 参数                   | 要求                                                  |
+| ---------------------- | ----------------------------------------------------- |
+| `--aspect-ratio`       | **`45:16`**（5 个 9:16 横排）；**禁止 `1:1`、`10:3`** |
+| `--width` / `--height` | **3600×1280**（2K）或 **4096×1455**（4K）             |
+| `--image-model`        | **`mulerouter/gpt-image-2`**（强制，勿用裸模型名）    |
+
+### 生成后验收（强制）
+
+```bash
+playcraft image info --input assets/images/storyboard/master_composite_option_A.png
+```
+
+| 检查项                | 横排 2K                | 横排 4K              |
+| --------------------- | ---------------------- | -------------------- |
+| 总尺寸                | 3600×1280（±3%）       | 4096×1455（±3%）     |
+| 总宽高比 width/height | **≈ 2.81**（45/16）    | **≈ 2.81**           |
+| 单格推算              | 宽/5 : 高 ≈ **9:16**   | 宽/5 : 高 ≈ **9:16** |
+| 视觉                  | 圆钮正圆、竖屏 UI 不扁 | 同左                 |
+
+不合格（1024×1024、1:1、总比例≈3.33 等）→ **必须重生成**。
+
+---
+
+## 4. 核查清单
+
+| #   | 项              | 标准                        |
+| --- | --------------- | --------------------------- |
+| 1   | 5 个 Panel 描述 | 完整                        |
+| 2   | 单格 9:16       | prompt + 像素双约束         |
+| 3   | CLI             | `45:16` + 成对 width/height |
+| 4   | image info      | 通过上表                    |
+| 5   | 方案数          | ≥2（designer.md）           |
+
+---
+
+## 5. 进阶
+
+> **Read `refs/designer-master-composite-recipes.md`**
+
+> **TA 从 MC 拆层/抠图**：读 `playcraft-masking` skill（`decompose-layers` 整图分层 vs `segment`/`crop` 单元素）。