@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/skills/playcraft-research/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: playcraft-research
+description: PlayCraft 网络研究协议。当本地 Skill 库不足以覆盖需求时触发——包括遇到陌生玩法机制、不熟悉的美术风格、特定音频类型、算法实现参考、需要图片参考等场景。使用 playcraft tools research / fetch-url / search-image 命令（统一鉴权，无需配置额外 key）直接搜索网络，将研究成果融入活 DAG。
+triggers: 本地skill不够,没有现成skill,找不到参考,不了解这个风格,不熟悉这个玩法,陌生机制,需要调研,搜索参考,互联网搜索,研究,需要图片参考,找参考图,视觉参考
+---
+
+# PlayCraft 网络研究协议
+
+## 可用工具（统一鉴权，无需额外配置）
+
+使用 PlayCraft CLI 提供的三个搜索工具：
+
+```bash
+# 文本研究 — Gemini + Google Search grounding，返回综合答案 + 引用来源
+playcraft tools research --query "<问题>" [--focus <领域>] [--json]
+
+# 读取 URL — Gemini 理解指定页面内容，返回结构化摘要
+playcraft tools fetch-url --url "<URL>" [--query "<具体问题>"] [--json]
+
+# 图片搜索 — Unsplash / Pexels 高质量图库，返回可直接用于 --reference-image 的 URL
+playcraft tools search-image --query "<关键词（建议英文）>" [--source unsplash|pexels|auto] [--count 6] [--orientation landscape|portrait|square] [--json]
+```
+
+`--focus` 参数（research 命令）：`gameplay` | `visual` | `audio` | `code` | `compliance`
+
+---
+
+## 何时使用网络研究
+
+**先本地，再网络**。网络研究是本地 Skill 发现的补充，不是替代。
+
+| 场景 | 应做什么 |
+|---|---|
+| `playcraft skills match` 完整匹配 | 直接用，无需研究 |
+| 部分匹配，缺少细节 | 用本地 Skill，补充网络研究缺失部分 |
+| 完全无匹配 | **触发 `research` 文本研究** |
+| 遇到陌生专业名词 | **触发 `research` 文本研究** |
+| 需要最新数据（2024+ 最佳实践） | **触发 `research` 文本研究** |
+| 需要视觉参考图（Phase 1 概念图 / 风格探索） | **触发 `search-image` 图片搜索** |
+| 生成后不满意，想用参考图引导风格 | **触发 `search-image` → 结果 URL 直接传 `--reference-image`** |
+
+---
+
+## 各角色研究标准流程
+
+### PM — 玩法机制调研
+
+```bash
+# 理解陌生的玩法类型
+playcraft tools research \
+  --query "match-3 mobile game level design best practices difficulty curve" \
+  --focus gameplay --json
+
+# 了解可玩广告设计原则
+playcraft tools research \
+  --query "playable ad game mechanics player retention 15 seconds hook" \
+  --focus gameplay --json
+
+# 读取具体设计文章
+playcraft tools fetch-url \
+  --url "https://www.gamedeveloper.com/design/..." \
+  --query "what are the key level design parameters"
+```
+
+### Designer — 视觉/音频风格调研
+
+```bash
+# 搜索艺术风格生成参数
+playcraft tools research \
+  --query "pixel art 8-bit game sprite limited color palette generation prompt keywords" \
+  --focus visual --json
+
+# 读取调色板数据库
+playcraft tools fetch-url \
+  --url "https://lospec.com/palette-list/..." \
+  --query "what are the exact hex colors and style characteristics"
+
+# 搜索音频风格
+playcraft tools research \
+  --query "chiptune BGM game music BPM range instruments characteristics" \
+  --focus audio --json
+
+# ── 图片搜索（新增）─────────────────────────────────────────────────────────
+
+# 搜索视觉参考图（用于 Phase 1 风格探索）
+playcraft tools search-image \
+  --query "pixel art 8-bit forest game background" \
+  --source pexels --orientation portrait --json
+
+# 搜索元素参考图（用于指导具体 asset 生成）
+playcraft tools search-image \
+  --query "cute cartoon fruit character icon game UI" \
+  --count 4 --json
+
+# 将搜索结果 URL 直接用作参考图（无需先下载）
+playcraft tools generate-image \
+  --prompt "pixel art forest background, 8-bit style, limited color palette" \
+  --reference-image "https://images.unsplash.com/photo-xxxxx" \
+  --output assets/images/bg/background.png \
+  --aspect-ratio 9:16
+```
+
+> **关键提示**：`search-image` 返回的 `downloadUrl` 字段可直接传给 `--reference-image`，CLI 会自动下载，无需手动保存。`--json` 模式返回结构化列表，方便批量选用。
+
+### Developer — 算法/技术实现调研
+
+```bash
+# 搜索具体实现
+playcraft tools research \
+  --query "A* pathfinding javascript tile map Phaser 3 implementation performance" \
+  --focus code --json
+
+# 读取官方文档
+playcraft tools fetch-url \
+  --url "https://phaser.io/docs/3.60.0/Phaser.Physics.html" \
+  --query "how does StaticGroup work with tilemap collision"
+
+# 搜索性能优化
+playcraft tools research \
+  --query "Phaser 3 60fps mobile performance sprite batch rendering optimization" \
+  --focus code --json
+```
+
+### Reviewer — 质量标准调研
+
+```bash
+# 平台合规要求
+playcraft tools research \
+  --query "Google Ads playable ad HTML5 policy requirements file size 2026" \
+  --focus compliance --json
+
+# 读取最新政策文档
+playcraft tools fetch-url \
+  --url "https://support.google.com/google-ads/answer/..." \
+  --query "what are the technical requirements for playable ads"
+
+# 性能基准
+playcraft tools research \
+  --query "web game 60fps performance budget mobile device HTML5 2025" \
+  --focus compliance --json
+```
+
+---
+
+## 研究结果融入活 DAG
+
+研究结果**必须写入 `atom-plan.md`**，否则其他 Agent 无法从中受益。
+
+### 写入格式
+
+```markdown
+<!-- 在对应 atom 的 Asset/Impl Skill Context 下 -->
+
+### {{atom_id}} — {{slot_name}}
+- **本地 Skill**：无匹配（playcraft skills match 返回 0 结果）
+- **文本研究结论**（若执行了 research / fetch-url）：
+  - 命令：`playcraft tools research --query "..." --focus visual --json`
+  - 核心发现：{{1-3 句话，具体且可操作}}
+  - 关键参数：{{数值、关键词、具体配置}}
+  - 引用来源：{{URL}}
+- **图片参考**（若执行了 search-image）：
+  - 命令：`playcraft tools search-image --query "..." --json`
+  - 选用图片：{{description}} — {{downloadUrl}}
+  - 使用方式：作为 `--reference-image` 传入生成命令
+- **实现/生成决策**：{{基于研究的具体方案}}
+- **候选新 Skill**：`{{建议名称}}.{{bundleType}}` — {{为什么值得沉淀}}
+```
+
+### 示例：Designer 研究波普艺术 + 搜图参考
+
+```markdown
+### bg_atom — 背景图层
+- 本地 Skill：无匹配
+- 文本研究结论：
+  - 命令：`playcraft tools research --query "pop art game sprite color palette" --focus visual --json`
+  - 核心发现：波普艺术使用 4-6 色高饱和调色板，粗黑轮廓线，网点图案填充
+  - 关键参数：饱和度 >80%，互补色对比，轮廓线 3-5px
+  - 引用来源：lospec.com/palette-list/pop-art
+- 图片参考：
+  - 命令：`playcraft tools search-image --query "pop art colorful bold graphic background" --source unsplash --json`
+  - 选用图片：Bold geometric pop art composition — https://images.unsplash.com/photo-xxxxx
+  - 使用方式：`--reference-image "https://images.unsplash.com/photo-xxxxx"`
+- 生成决策：
+  - prompt: "pop art style, bold black outlines, halftone dots, vivid colors, {{element}}"
+  - style: "vibrant, graphic, flat colors, 1960s comic style"
+  - reference: 上方 Unsplash URL（CLI 自动下载）
+- 候选新 Skill：`pop_art_sprite.aiimage`
+```
+
+---
+
+## "候选新 Skill" 贡献循环
+
+每次网络研究形成可复用方案，在 `atom-plan.md` 的 **DAG Revisions** 标注：
+
+```markdown
+### Revision N — {{Agent}} (propose-skill)
+- **atomId**: {{atom_id}}
+- **reason**: 本地无 Skill，通过网络研究形成可复用方案
+- **change**: 建议创建：`{{skill_name}}.{{bundleType}}` — {{描述}}，来源：{{URL}}
+```
+
+---
+
+## 研究质量检查
+
+| 检查项 | 要求 |
+|---|---|
+| **来源可信度** | 优先官方文档、行业权威；引用来源来自 `--json` 输出的 `citations` 字段 |
+| **信息时效** | 优先 2024-2026 年内容（在 query 中加年份可提高准确性） |
+| **可操作性** | 结论必须直接用于生成参数或代码，不能泛泛而谈 |
+| **与 StyleDirection 一致** | 视觉研究须与 design-brief 的 StyleDirection 对齐 |

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`。