@playcraft/cli 0.0.39 → 0.0.41

package/project-template/.claude/skills/playcraft-build-optimizer/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: playcraft-build-optimizer
+description: 可玩广告构建优化与平台合规验证完整指南。涵盖 playcraft build 全部优化参数（图片压缩/WebP转换/模型压缩/JS混淆）、正确的优化执行顺序（避免多次有损压缩）、各平台合规验证清单（文件大小/外部请求/CTA API/音频自动播放）、Base64 膨胀系数计算。供未来 Optimizer Agent 使用。
+triggers: 构建优化,build optimizer,压缩,compress,WebP,pngquant,文件大小,file size,合规验证,compliance,CTA API,FbPlayableAd,ExitApi,外部请求,external request,体积,5MB限制,build参数,optimize,minify
+---
+
+# 可玩广告构建优化与合规验证指南
+
+> **使用时机**：在 Developer Phase 2（集成构建）完成、产出 index.html 之后执行。优化是最后一步，不在生产阶段执行。
+
+---
+
+## 0. 关键数字速查
+
+| 约束项           | 数值                        | 说明                                     |
+| ---------------- | --------------------------- | ---------------------------------------- |
+| 最终文件大小上限 | 5 MB                        | Meta/Google/AppLovin/IronSource 统一标准 |
+| 原始资产建议上限 | 3.75 MB                     | Base64 编码后膨胀 ×1.33，需提前预留空间  |
+| 触控目标最小尺寸 | 48×48 px                    | 防止误触，符合 WCAG 可访问性标准         |
+| CTA 对比度下限   | 4.5:1                       | WCAG AA 标准（CTA 按钮与背景）           |
+| Meta CTA API     | `FbPlayableAd.onCTAClick()` | 必须实现，否则审核拒绝                   |
+| Google CTA API   | `ExitApi.exit()`            | 必须实现，否则审核拒绝                   |
+| 音频自动播放     | 禁止                        | 必须等用户交互后才能播放                 |
+
+---
+
+## 1. 合规验证清单（构建后必须执行）
+
+### 1.1 文件大小验证
+
+```bash
+# 检查最终输出文件大小
+playcraft image info --input dist/index.html --json  # 不适用，用 shell
+
+# Shell 方法：检查文件大小（字节）
+du -sh dist/index.html
+ls -lh dist/index.html
+
+# 计算：若当前原始资产总大小为 X MB
+# 预计最终 HTML 大小 ≈ X × 1.33（Base64 膨胀）
+# 若预计超过 5 MB，需要压缩
+```
+
+**Base64 膨胀系数说明**：`playcraft build` 会将所有资产（图片、音频、模型）内嵌到单个 HTML 文件中，编码为 Base64。Base64 编码会使数据体积增加约 33%。
+
+```
+原始资产总大小 × 1.33 ≈ 最终 HTML 文件大小
+→ 要保证最终 < 5 MB，原始资产须 < 3.75 MB
+```
+
+### 1.2 外部请求检查
+
+```bash
+# 在项目代码中搜索外部请求（构建前检查）
+grep -r "fetch(" game/ --include="*.js" --include="*.ts"
+grep -r "XMLHttpRequest" game/ --include="*.js" --include="*.ts"
+grep -r "https://" game/ --include="*.js" --include="*.ts"
+grep -r "http://" game/ --include="*.js" --include="*.ts"
+grep -r "<script src=" game/ --include="*.html"
+grep -r "<link href=" game/ --include="*.html"
+```
+
+**零外部请求要求**：最终 HTML 不得包含任何外部 URL（CDN、API、图片链接等）。所有资源必须内嵌。
+
+### 1.3 CTA API 实现验证
+
+```bash
+# 检查 Meta CTA API 实现
+grep -r "FbPlayableAd.onCTAClick" game/ --include="*.js" --include="*.ts"
+# 若无匹配 → CTA 功能不完整，需要 Developer 补充
+
+# 检查 Google CTA API 实现
+grep -r "ExitApi.exit" game/ --include="*.js" --include="*.ts"
+# 若无匹配 → Google Ads 版本缺少 CTA，需要 Developer 补充
+```
+
+**CTA API 标准实现**（供 Developer 参考）：
+
+```javascript
+// 多平台兼容 CTA 处理
+function handleCTAClick() {
+  // Meta / Facebook
+  if (typeof FbPlayableAd !== "undefined") {
+    FbPlayableAd.onCTAClick();
+    return;
+  }
+  // Google Ads / AdMob
+  if (typeof ExitApi !== "undefined") {
+    ExitApi.exit();
+    return;
+  }
+  // AppLovin / IronSource / 其他
+  if (typeof mraid !== "undefined") {
+    mraid.open(STORE_URL);
+    return;
+  }
+  // Fallback
+  window.open(STORE_URL, "_blank");
+}
+```
+
+### 1.4 音频自动播放检查
+
+```bash
+# 检查是否有自动播放的音频
+grep -r "autoplay" game/ --include="*.js" --include="*.ts" --include="*.html"
+grep -r "\.play()" game/ --include="*.js" --include="*.ts"
+# 所有 .play() 调用必须在用户交互事件（click/touchstart）的回调内
+```
+
+---
+
+## 2. playcraft build 优化参数
+
+### 完整优化构建命令
+
+```bash
+# 标准优化构建（Meta 平台）
+playcraft build . \
+  --platform facebook \
+  --compress-images \
+  --image-quality 85 \
+  --convert-webp \
+  --js-minify \
+  --css-minify \
+  --output dist/
+
+# 带 3D 模型压缩的构建
+playcraft build . \
+  --platform facebook \
+  --compress-images \
+  --image-quality 80 \
+  --convert-webp \
+  --compress-models \
+  --model-compression draco \
+  --js-minify \
+  --output dist/
+
+# 分析体积占用（不构建，只分析）
+playcraft build . \
+  --platform facebook \
+  --analyze
+```
+
+### 图片优化参数
+
+| 参数                      | 说明                      | 默认       |
+| ------------------------- | ------------------------- | ---------- |
+| `--compress-images`       | 启用图片压缩（pngquant）  | 需显式开启 |
+| `--image-quality <0-100>` | 压缩质量（底层 pngquant） | 85         |
+| `--convert-webp`          | 将 PNG/JPG 转换为 WebP    | 默认开启   |
+| `--no-convert-webp`       | 禁用 WebP 转换            | —          |
+
+**pngquant 说明**：`--compress-images` 使用 `imagemin-pngquant` 进行 PNG 调色板量化，可减少 30-50% 体积，无明显视觉损失（对像素艺术效果更好）。
+
+**WebP 说明**：`--convert-webp` 将图片转换为 WebP 格式，比 PNG 减少 60-75%，比 JPG 减少 25-34%，且支持透明通道。现代移动端浏览器均支持。
+
+### 模型优化参数
+
+| 参数                          | 说明                                  |
+| ----------------------------- | ------------------------------------- |
+| `--compress-models`           | 启用 3D 模型压缩                      |
+| `--model-compression draco`   | 使用 Draco 几何压缩（通用，广泛支持） |
+| `--model-compression meshopt` | 使用 MeshOptimizer（更高压缩比）      |
+
+### JS/CSS 优化参数
+
+| 参数           | 说明                          |
+| -------------- | ----------------------------- |
+| `--js-minify`  | 启用 JS 压缩（Terser + 混淆） |
+| `--css-minify` | 启用 CSS 压缩                 |
+
+### 多平台批量构建
+
+```bash
+# 同时构建多个平台版本
+playcraft build-all . \
+  --platforms facebook,google,applovin \
+  --compress-images \
+  --image-quality 85 \
+  --convert-webp \
+  --js-minify \
+  --output dist/
+
+# 或按平台组
+playcraft build-all . \
+  --group mainstream \   # 主流平台
+  --compress-images \
+  --convert-webp
+```
+
+---
+
+## 3. 正确的优化执行顺序
+
+**关键原则**：避免对同一文件多次执行有损压缩（每次有损压缩都会叠加质量损失）。
+
+```
+正确顺序：
+1. 检查原始资产总大小
+   ↓
+2. 3D 模型压缩（draco/meshopt）— 无损几何优化
+   ↓
+3. playcraft build --convert-webp — PNG→WebP（一次有损转换）
+   ↓
+4. playcraft build --compress-images --image-quality 85 — pngquant（针对非 WebP 的 PNG）
+   ↓
+5. playcraft build --js-minify --css-minify — 代码压缩
+   ↓
+6. 检查最终文件大小（必须 < 5 MB）
+   ↓
+7. 合规验证清单（§1）
+```
+
+**禁止行为**：
+
+- 不要先用 `playcraft image convert --format webp` 手动转换，再用 `--convert-webp` 构建（双重转换）
+- 不要对同一图片多次运行 `--compress-images`（每次都会损失质量）
+- 生产阶段（Designer/TA）产出应保持 PNG 格式，优化阶段统一转换
+
+---
+
+## 4. 单文件优化（构建后问题文件处理）
+
+当某个文件体积异常大时，可单独优化：
+
+```bash
+# 查看问题文件大小
+playcraft image info --input assets/images/bg/background.png --json
+
+# 单文件转 WebP（有损，质量 85）
+playcraft image convert \
+  --input assets/images/bg/background.png \
+  --output assets/images/bg/background.webp \
+  --format webp \
+  --quality 85
+
+# 单文件转 WebP（无损，适合 UI 元素和像素艺术）
+playcraft image convert \
+  --input assets/images/ui/button.png \
+  --output assets/images/ui/button.webp \
+  --format webp \
+  --lossless
+
+# 音频压缩（降低比特率）
+playcraft audio compress \
+  --input assets/audio/bgm/main_theme.mp3 \
+  --output assets/audio/bgm/main_theme_compressed.mp3 \
+  --bitrate 96k \
+  --mono
+
+# 3D 模型优化
+playcraft 3d optimize \
+  --input assets/models/character.glb \
+  --output assets/models/character_optimized.glb \
+  --texture-size 512
+```
+
+---
+
+## 5. 优化报告格式
+
+完成优化后，写入 `logs/optimizer-log.md`：
+
+```markdown
+# Optimizer Log
+
+## 构建信息
+
+- 平台：{{platform}}
+- 构建时间：{{timestamp}}
+- 最终文件大小：{{size_mb}} MB（限制：5 MB）
+- 构建状态：{{pass/fail}}
+
+## 资产优化摘要
+
+| 资产类型           | 优化前总大小  | 优化后总大小 | 压缩率     |
+| ------------------ | ------------- | ------------ | ---------- |
+| 图片（PNG → WebP） | {{before}} MB | {{after}} MB | {{ratio}}% |
+| 3D 模型            | {{before}} MB | {{after}} MB | {{ratio}}% |
+| 音频               | {{before}} MB | {{after}} MB | {{ratio}}% |
+| JS/CSS             | {{before}} KB | {{after}} KB | {{ratio}}% |
+
+## 合规验证结果
+
+- [ ] 文件大小 ≤ 5 MB
+- [ ] 零外部请求
+- [ ] Meta CTA API 实现（FbPlayableAd.onCTAClick）
+- [ ] Google CTA API 实现（ExitApi.exit）
+- [ ] 音频无自动播放
+
+## 问题与建议
+
+{{如有超限或合规问题，在此列出并给出修复建议}}
+```
+
+---
+
+## 6. 常见审核被拒原因速查
+
+| 被拒原因          | 占比 | 检查方法                 | 修复方法                                                |
+| ----------------- | ---- | ------------------------ | ------------------------------------------------------- |
+| 文件大小超过 5 MB | 45%  | `ls -lh dist/index.html` | `--compress-images --convert-webp` 或降低 image-quality |
+| 包含外部请求      | 30%  | `grep -r "https://"`     | Developer 将外部资源内嵌                                |
+| CTA 未实现        | 15%  | `grep "FbPlayableAd"`    | Developer 添加平台 CTA API                              |
+| 音频自动播放      | 10%  | `grep "autoplay"`        | Developer 改为用户交互触发                              |

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

@@ -0,0 +1,229 @@
+---
+name: playcraft-image-generation
+description: PlayCraft AI 图片生成核心决策指南。涵盖模型选择决策树、核心命令模板、背景处理决策树（绿幕策略）、脚本决策规则。精灵图直出/Edit 模型/错误恢复/批量实践等进阶内容见 refs/ta-image-generation-detail.md。
+triggers: 生成图片,generate image,选模型,model selection,reference image,参考图,风格一致,图生图,文生图,AI生图,图片质量,模型选择,500错误,模型失败,generate-image,list-image-models,ta-workspace,batch,批量,脚本,nodejs,edit模型,变体,绿幕,去背景,透明PNG,prompt,提示词,prompt套路,提示词技巧
+---
+
+# PlayCraft AI 图片生成指南
+
+## 0. 开始前必读
+
+生图前**必须先运行模型发现命令**：
+
+```bash
+playcraft tools list-image-models
+```
+
+输出示例：
+
+```
+MODEL                                        CAPABILITY   ALPHA  PROVIDERS
+gpt-image-2                                  text+image   no     3 (iegg-litellm, mulerouter, 302)
+gemini-3.1-flash-image-preview               text+image   no     2 (google, iegg-litellm)
+hy-image-v3.0                                text+image   no     1 (tencent-cloud)
+flux-kontext-pro                             text+image   no     1 (302)
+qwen-image-edit-max                          image→image  no     1 (mulerouter)
+...
+```
+
+**列说明**：
+
+- `CAPABILITY`：`text→image` 仅文生图 / `image→image` 仅图生图 / `text+image` 两者均支持
+- `ALPHA`：`yes` = 原生透明 PNG；`no` = 需使用绿幕策略（见第 3 节）
+- `PROVIDERS`：支持该模型的 provider 数量，多个 provider 时后端按优先级自动 fallback（顺序尝试，首个成功即返回）
+
+**Prompt 套路速查**：[reference/prompt-cookbook.md](reference/prompt-cookbook.md)
+
+---
+
+## 1. 模型选择决策树
+
+```
+需要生图？
+├─ 追求最高质量（概念图、精品单图）？
+│  └─ gpt-image-2（3 个 provider 自动 fallback：iegg-litellm → mulerouter → 302）
+│
+├─ 需要 --reference-image（风格一致性批量生产）？
+│  └─ 必须选 CAPABILITY = text+image 或 image→image 的模型
+│
+├─ 同类元素批量生成（<=16 个）？
+│  └─ 精灵图直出策略（见进阶参考）
+│
+├─ 结构相似的变体集（换花色/换数字/换颜色）？
+│  └─ Edit 模型工作流（见进阶参考）
+│
+└─ 不确定？
+   └─ 先试 gpt-image-2，失败换 gemini-3.1-flash-image-preview
+```
+
+### 主要模型特性
+
+| 模型                               | 特点与优势                                                                                  | 最佳场景                                        | 速度                            | 注意事项                                                        |
+| ---------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------------------------------------- |
+| **gpt-image-2**                    | 细节最丰富、光影最真实、网格/布局理解力最强、中文字符准确率最高、3 provider fallback 容错高 | 概念图、精灵图直出、含文字素材、写实/半写实风格 | 慢(7-8min/张)，**不设 timeout** | 慢是正常的；只有 `API 500` / `fetch failed` 才切换下一 provider |
+| **gemini-3.1-flash-image-preview** | 速度快、色彩鲜艳、构图清晰、最稳定不易报错、reference-image 理解好                          | 快速迭代、扁平卡通、明亮休闲风、超时回退        | 快(<30s)                        | 精细细节和文字不如 gpt-image-2                                  |
+| **hy-image-v3.0**                  | 亚洲审美偏向、角色设计好、Q版/IP风格擅长                                                    | 中国风、Q版角色、IP 形象                        | 中等                            | 西方写实风格表现一般                                            |
+| **flux-kontext-pro**               | 艺术感强、风格独特、手绘质感好                                                              | 艺术插画、手绘风、独特画风探索                  | 中等                            | 网格理解弱，不适合精灵图                                        |
+| **nano-banana-2**                  | 最快、适合简单图形探索                                                                      | 简洁图标、平面设计、快速草稿                    | 极快                            | 中文字符不可靠、细节少                                          |
+| **qwen-image-edit-max**            | 图生图编辑能力强、局部修改精确                                                              | 换花色/换数字/换颜色等结构相似变体              | 中等                            | CAPABILITY=image→image，必须传 reference-image                  |
+| **wan2.6-image**                   | 风格迁移能力好                                                                              | 将参考图风格应用到新内容                        | 中等                            | CAPABILITY=image→image，必须传 reference-image                  |
+
+### 选型口诀
+
+- 追求质量 / 含文字 / 网格图 → `gpt-image-2`
+- 快速迭代 / 扁平风格 / 回退备选 → `gemini-3.1-flash-image-preview`
+- 中国风 / Q版 / 亚洲审美 → `hy-image-v3.0`
+- 艺术/手绘探索 → `flux-kontext-pro`
+- 纯 edit 变体 → `qwen-image-edit-max`
+- 一切都失败 → `gemini-3.1-flash-image-preview`（最稳定）
+
+### 为什么精灵图直出是首选批量策略？
+
+精灵图直出（一次 API 调用生成一张包含 N 个元素的网格图，再 sprite-split 切分）优于逐个生成，原因有三：
+
+1. **成本**：一次 API 调用可包含 4-16 个元素，而逐个生成 N 个元素需要 N 次调用，成本和耗时线性增长。
+2. **风格一致性**：同一张图中的所有元素共享相同的生成上下文，天然保证色调、线条、阴影风格统一，避免逐个生成时每张图风格漂移的问题。
+3. **无逐元素偏差**：逐个生成时即使用相同 prompt，模型每次采样结果都不同，元素之间会出现肉眼可见的不一致；精灵图在一次推理中完成，消除了这种 per-element drift。
+
+详细策略与代码示例见进阶参考。
+
+---
+
+## 2. 核心命令
+
+### 文生图（text-to-image）
+
+```bash
+playcraft tools generate-image \
+  --prompt "A golden sword icon, flat 2D vector style, centered composition" \
+  --output assets/images/sword.png \
+  --aspect-ratio 1:1 \
+  --image-size 4K \
+  --image-model gpt-image-2
+```
+
+### 图生图（image-to-image / reference-image）
+
+```bash
+playcraft tools generate-image \
+  --prompt "A similar style silver shield icon, same art direction" \
+  --output assets/images/shield.png \
+  --reference-image assets/images/sword.png \
+  --aspect-ratio 1:1 \
+  --image-size 4K \
+  --image-model gpt-image-2
+```
+
+### 参数说明
+
+| 参数                   | 值                                        | 说明                                                    |
+| ---------------------- | ----------------------------------------- | ------------------------------------------------------- |
+| `--aspect-ratio`       | `1:1` / **`45:16`** / `16:9` / `9:16` / … | **Master Composite（5×9:16 横排）用 `45:16`**           |
+| `--width` / `--height` | 像素整数（成对）                          | MC 推荐 **`3600×1280`** 或 **`4096×1455`**              |
+| `--image-size`         | `1K` / `2K` / `4K`                        | 控制分辨率级别。实际像素取决于模型+比例的组合（见下表） |
+
+**`--image-size` 对 gpt-image-2 的落盘尺寸**（MuleRouter 请求 `size=auto`，由后端 letterbox 到目标像素）：
+
+| aspectRatio                   | 1K        | 2K            | 4K            |
+| ----------------------------- | --------- | ------------- | ------------- |
+| 1:1                           | 1024x1024 | 2048x2048     | 2048x2048     |
+| **45:16** (5×9:16 故事板横排) | 2048x728  | **3600x1280** | **4096x1455** |
+| 16:9                          | 2048x1152 | 2048x1152     | 3840x2160     |
+| 9:16                          | 2160x3840 | 2160x3840     | 2160x3840     |
+| 3:2 / 4:3                     | 1536x1024 | 1536x1024     | 1536x1024     |
+| 21:9                          | 2048x1152 | 3840x2160     | 3840x2160     |
+
+> **IEGG LiteLLM** 在 fallback 链中排第一，但 Azure gpt-image 最大约 1536px 宽 — 达不到 5×9:16 横排。故事板请用 **`mulerouter/gpt-image-2`**（跳过 litellm）+ `--width 3600 --height 1280`（或 4096×1455）。
+
+**Phase 1（概念图）**：纯文生图，`--image-size 4K` + 优先 gpt-image-2 追求质量。
+**Phase 2（批量生产）**：必须带 `--reference-image` 指向 Phase 1 确认的概念图，同一批次使用**相同模型 + 相同 reference image + 相同 image-size**。
+
+### --reference-image 路径支持
+
+- 本地绝对路径：`/path/to/ref.png`
+- 相对路径（相对 CWD）：`assets/images/ref.png`
+- HTTP(S) URL（CLI 自动下载）：`"https://images.unsplash.com/photo-xxx"`
+- 多张参考图（重复选项，最多 8 张）
+- 混合本地文件 + URL
+- `search-image` 返回的 `downloadUrl` 可直接使用
+
+### 常用辅助命令
+
+```bash
+# 去背景（绿幕建议 tolerance=25；默认白背景可用 15）
+playcraft image remove-background --input in.png --output out.png --tolerance 25
+
+# 缩放
+playcraft image resize --input in.png --output out.png --width 128 --height 128
+
+# 精灵图切分
+playcraft image sprite-split \
+  --input sheet.png --output-dir frames/ \
+  --rows 2 --columns 4 \
+  --frame-width <总宽/4> --frame-height <总高/2>
+
+# 合并精灵图
+playcraft image sprite-sheet \
+  --input-dir processed/ --output bundle \
+  --columns 8 --background white
+```
+
+---
+
+## 3. 背景处理决策树
+
+> **核心原则**：先确定素材类型，再决定是否需要去背景，再决定 prompt 应该写什么。
+
+```
+生成的素材需要做什么？
+│
+├─ 需要透明背景的独立元素（角色、道具、图标）？
+│   ├─ 检查模型 ALPHA 列（playcraft tools list-image-models）
+│   ├─ ALPHA = yes → prompt 加 "transparent background, PNG with alpha"
+│   └─ ALPHA = no  → 绿幕策略：
+│       ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
+│       └─ 后处理：remove-background（floodfill，tolerance 25）
+│
+├─ 卡牌/棋盘格子/UI 面板（本身就是矩形有边框）？
+│   ├─ 不要去背景！白色牌面就是牌的一部分
+│   ├─ prompt 加 "flat 2D, no drop shadow, no 3D effect, clean edges"
+│   └─ 后处理：直接 resize（skipRemoveBg = true）
+│
+└─ 场景背景（天空、地面、全屏图）？
+    └─ 不做背景处理，直接 resize
+```
+
+### 为什么需要绿幕策略？
+
+**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。绿色背景 + 任何游戏素材 = 极少撞色，抠图几乎完美。与影视 chroma-key 原理相同。
+
+### Prompt 后缀速查表
+
+| 素材类型              | prompt 建议后缀                                                     | 后处理                           | skipRemoveBg |
+| --------------------- | ------------------------------------------------------------------- | -------------------------------- | ------------ |
+| 独立元素（需透明）    | `"on solid bright green #00FF00 background, isolated, centered"`    | remove-background (tolerance 25) | `false`      |
+| 卡牌/棋子（矩形本体） | `"flat 2D, no shadow, no 3D effect, clean edges, white background"` | 只做 resize                      | `true`       |
+| UI 按钮/面板          | `"flat UI element, no shadow, clean edges"`                         | trim + resize                    | `true`       |
+| 场景背景              | `"full scene, edge to edge"`                                        | 只做 resize                      | `true`       |
+
+---
+
+## 4. 脚本决策
+
+- **<=5 个文件** → 直接使用 CLI 命令
+- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录。
+
+---
+
+## 5. 进阶参考
+
+需要以下进阶内容时，查阅 [`refs/ta-image-generation-detail.md`](../../agents/refs/ta-image-generation-detail.md)：
+
+| 主题                  | 说明                                                                |
+| --------------------- | ------------------------------------------------------------------- |
+| 精灵图直出策略        | gpt-image-2 网格图生成 + sprite-split 切分，白底/绿幕示例，分批策略 |
+| Edit 模型工作流       | 基图 → edit 变体（换花色/换数字/换颜色），prompt 写法               |
+| 错误恢复表            | 各类错误现象、原因、立即行动；模型回退顺序                          |
+| Provider 回退链       | gpt-image-2 三 provider 互为回退 + 非 gpt-image-2 稳定回退          |
+| 批量生成最佳实践      | 单张验证、Node.js 脚本推荐、脚本模板使用                            |
+| ta-workspace 脚本驱动 | 为什么用 Node.js、目录约定、脚本模板一览表                          |

package/project-template/.claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs

@@ -0,0 +1,123 @@
+// ============================================================
+// build-sprite-sheet.template.mjs — 精灵图合并 + 验证脚本模板
+// 用途：将处理好的图片目录合并为精灵图（PNG + JSON 元数据）
+//
+// 使用方式：
+//   1. cp .claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs ta-workspace/scripts/build-<name>-atlas.mjs
+//   2. 修改下方 CONFIG 区域
+//   3. 如需控制帧顺序，填写 ORDERED_NAMES 数组（留空则按文件名排序）
+//   4. node ta-workspace/scripts/build-<name>-atlas.mjs
+// ============================================================
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'fs';
+import { join, extname } from 'path';
+
+// ============ CONFIG — 修改这里 ============
+const CONFIG = {
+  /** 处理好的图片目录（process-batch 的输出目录） */
+  processedDir: 'assets/images/processed',
+  /** 输出文件路径（不含扩展名，会生成 .png 和 .json 两个文件） */
+  outputBase: 'assets/bundles/atlas',
+  /** 每行帧数 */
+  columns: 8,
+  /** 帧间距（像素） */
+  padding: 2,
+  /**
+   * 精灵图背景色
+   * - 'transparent'（默认）：透明背景
+   * - 'white' / 'black' / '#RRGGBB'：固定背景色
+   *   某些引擎（如 PlayCanvas）处理透明精灵图时可能显示为黑色，此时用 'white' 更安全
+   */
+  background: 'transparent',
+  /** 文件名排序方式：'name'（字母序）或 'custom'（使用 ORDERED_NAMES） */
+  sort: 'name',
+};
+
+/**
+ * 自定义帧顺序（CONFIG.sort = 'custom' 时生效）
+ * 填写不含扩展名的文件名，按期望顺序排列
+ * 示例（扑克牌）：['spades_A', 'spades_2', 'spades_3', ...]
+ */
+const ORDERED_NAMES = [
+  // 填写文件名（不含扩展名）...
+];
+// ============ LOGIC — 通常不需要修改 ============
+
+const LOG_FILE = 'ta-workspace/logs/build-sprite-sheet.log';
+mkdirSync('ta-workspace/logs', { recursive: true });
+
+function log(msg) {
+  const line = `[${new Date().toISOString()}] ${msg}`;
+  console.log(line);
+  appendFileSync(LOG_FILE, line + '\n');
+}
+
+// 收集输入文件
+let inputFiles;
+if (CONFIG.sort === 'custom' && ORDERED_NAMES.length > 0) {
+  // 自定义顺序：按 ORDERED_NAMES 排列，找不到的文件跳过并警告
+  inputFiles = [];
+  for (const name of ORDERED_NAMES) {
+    const candidates = ['.png', '.jpg', '.webp'].map(ext => join(CONFIG.processedDir, `${name}${ext}`));
+    const found = candidates.find(p => existsSync(p));
+    if (found) {
+      inputFiles.push(found);
+    } else {
+      log(`[WARN] Ordered file not found: ${name} (skipping)`);
+    }
+  }
+} else {
+  // 文件名排序
+  inputFiles = readdirSync(CONFIG.processedDir)
+    .filter(f => ['.png', '.jpg', '.webp'].includes(extname(f).toLowerCase()))
+    .sort()
+    .map(f => join(CONFIG.processedDir, f));
+}
+
+if (inputFiles.length === 0) {
+  log('ERROR: No input files found in ' + CONFIG.processedDir);
+  process.exit(1);
+}
+
+log(`=== Build Sprite Sheet Start ===`);
+log(`Frames: ${inputFiles.length} | Columns: ${CONFIG.columns} | Padding: ${CONFIG.padding} | BG: ${CONFIG.background}`);
+
+// 构建 --inputs 参数列表
+const inputsArg = inputFiles.map(p => `"${p}"`).join(' ');
+
+const cmd =
+  `playcraft image sprite-sheet` +
+  ` --inputs ${inputsArg}` +
+  ` --output "${CONFIG.outputBase}"` +
+  ` --columns ${CONFIG.columns}` +
+  ` --padding ${CONFIG.padding}` +
+  (CONFIG.background !== 'transparent' ? ` --background "${CONFIG.background}"` : '');
+
+log(`Running: playcraft image sprite-sheet ... --output ${CONFIG.outputBase}`);
+
+try {
+  execSync(cmd, { stdio: 'inherit' });
+} catch (e) {
+  log(`ERROR: sprite-sheet command failed: ${e.message}`);
+  process.exit(1);
+}
+
+// 验证输出
+const pngPath  = `${CONFIG.outputBase}.png`;
+const jsonPath = `${CONFIG.outputBase}.json`;
+
+if (!existsSync(pngPath) || !existsSync(jsonPath)) {
+  log('ERROR: Output files missing! Expected ' + pngPath + ' and ' + jsonPath);
+  process.exit(1);
+}
+
+const meta = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+const frameCount = Object.keys(meta.frames ?? {}).length;
+
+log(`\n=== Sprite Sheet Built ===`);
+log(`  Frames  : ${frameCount}`);
+log(`  PNG     : ${pngPath}`);
+log(`  JSON    : ${jsonPath}`);
+log(`  Columns : ${CONFIG.columns}`);
+log(`  Rows    : ${Math.ceil(frameCount / CONFIG.columns)}`);