@playcraft/cli 0.0.57 → 0.0.59

package/project-template-v2/.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`（每次都会损失质量）
+- 生产阶段（Artist/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-v2/.claude/skills/playcraft-image-generation/SKILL.md

@@ -0,0 +1,298 @@
+---
+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）。
+
+### Master Composite（MC）模型白名单
+
+Artist 生成 MC 时**不得**套用上方通用决策树里的 gemini / flux / hy-image 等——MC 只允许：
+
+| 允许                       | 禁止（MC）                                          |
+| -------------------------- | --------------------------------------------------- |
+| `mulerouter/gpt-image-2`   | `gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*` |
+| `mulerouter/nano-banana-2` | 裸 `gpt-image-2`（会走 iegg-litellm 压扁五格）      |
+
+完整 prompt / 尺寸规范见 **`playcraft-storyboard`** skill。ASR 双板 `--image-model` 须与已选 MC **完全一致**。
+
+**Phase 1（概念图）**：纯文生图，`--image-size 4K` + MC 白名单内模型。
+**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. 背景处理决策树
+
+> **核心原则**：先确定素材类型，再决定是否需要去背景，再按素材主色调选择色幕颜色，最后做去背景 + 深色背景验证。
+
+```
+生成的素材需要做什么？
+│
+├─ 需要透明背景的独立元素（角色、道具、图标、文字图片、HUD、VFX）？
+│   ├─ 检查模型 ALPHA 列（playcraft tools list-image-models）
+│   ├─ ALPHA = yes → prompt 加 "transparent background, PNG with alpha"
+│   └─ ALPHA = no  → 色幕策略（按素材主色调选择）：
+│       ├─ 素材为金色/黄色/橙色/绿色 → 蓝幕 #0000FF
+│       │   ├─ prompt 末尾加 "on solid bright blue #0000FF background, isolated, centered"
+│       │   └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│       ├─ 素材为蓝色/紫色/靛蓝 → 绿幕 #00FF00
+│       │   ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
+│       │   └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│       └─ 其他颜色 → 绿幕 #00FF00（默认）
+│           ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
+│           └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│
+├─ 卡牌/棋盘格子/UI 面板（本身就是矩形有边框）？
+│   ├─ 不要去背景！白色牌面就是牌的一部分
+│   ├─ prompt 加 "flat 2D, no drop shadow, no 3D effect, clean edges"
+│   └─ 后处理：直接 resize（skipRemoveBg = true）
+│
+└─ 场景背景（天空、地面、全屏图）？
+    ├─ 不做背景处理，直接 resize
+    └─ ⚠️ prompt 必须加 "full bleed, edge to edge, no vignette, no fade"
+       → 后处理验证：四角四边颜色一致，无褪色/白色
+```
+
+### 为什么需要色幕策略？
+
+**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。纯色背景 + 非撞色游戏素材 = 抠图几乎完美。与影视 chroma-key 原理相同。
+
+### 色幕选型矩阵（Color Conflict Avoidance）
+
+> ⚠️ **不要默认全用绿幕！** 金色素材 + 绿幕 = 绿色与金色色相接近，floodfill 会在边缘残留绿色，或误删金色像素。
+
+| 素材主色调            | ❌ 禁用 | ✅ 推荐          | 原因                                       |
+| --------------------- | ------- | ---------------- | ------------------------------------------ |
+| 金色/黄色/橙色/琥珀色 | 绿幕    | **蓝幕 #0000FF** | 金色与绿色色相接近（黄绿区），边缘残留绿色 |
+| 绿色/翠绿/青色        | 绿幕    | **蓝幕 #0000FF** | 同色系，无法区分边界                       |
+| 蓝色/靛蓝/紫色        | 蓝幕    | **绿幕 #00FF00** | 同色系冲突                                 |
+| 红色/粉色/白色/黑色   | —       | 绿幕或蓝幕均可   | 与两者色相距离都大                         |
+| 多色/彩虹             | —       | **品红 #FF00FF** | 品红在自然素材中最少出现（最后手段）       |
+
+### Prompt 后缀速查表
+
+| 素材类型                   | prompt 建议后缀                                                     | 后处理                                      | skipRemoveBg |
+| -------------------------- | ------------------------------------------------------------------- | ------------------------------------------- | ------------ |
+| 独立元素（需透明，非金色） | `"on solid bright green #00FF00 background, isolated, centered"`    | remove-background (tolerance 25) → 深色验证 | `false`      |
+| 独立元素（金/黄/橙/绿色）  | `"on solid bright blue #0000FF background, isolated, centered"`     | remove-background (tolerance 25) → 深色验证 | `false`      |
+| 独立元素（多色/彩虹）      | `"on solid bright magenta #FF00FF background, isolated, centered"`  | remove-background (tolerance 20) → 深色验证 | `false`      |
+| VFX 特效（发光/粒子）      | `"on solid bright blue #0000FF 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, full bleed, edge to edge, no vignette, no fade"`      | resize → 四角全覆盖检查                     | `true`       |
+
+### 去背景后必做：深色背景渲证
+
+> 每个需要透明的资产，去背景后**必须**在深色背景上叠合验证。这一步是防止白底/色幕残留/黑块的最后防线。
+
+```bash
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <processed>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
+# 目视检查：无白边、无色幕残留色、无黑色不透明块、边缘干净
+```
+
+**不通过时的修复**：见 `ta-pipeline-cookbook.md` Step 0e §3 及 Compliance Gate 失败修复表。
+
+---
+
+## 3.1 ASR 专用分支（Artist · ring 3 build）
+
+> **Read `playcraft-asset-state-sheet` Skill first.** ASR 是制作期参考板，不是 runtime 透明资产。
+
+| 阶段              | Artist                                | TA                            |
+| ----------------- | ------------------------------------- | ----------------------------- |
+| ASR 整图          | **opaque**（灰底或统一色幕）— 正常    | —                             |
+| ASR 格内元素      | **isolated** + 按色幕矩阵选 cell 背景 | `crop` 后 `remove-background` |
+| remove-background | **禁止** — Artist 不做                | production Wave 2             |
+
+**Artist ASR prompt 要点**：
+
+1. Sheet canvas：`solid flat #808080` 或整板统一绿幕（非渐变）
+2. 每格：`ONE isolated element, centered, NO white box, NO scene, NO ground shadow`
+3. 金/橙/黄/绿元素格 → cell 背景 `#0000FF`；蓝/紫 → `#00FF00`
+4. 生成后**目视**格内可抠性 — 不要求 `channels=4`（那是 TA 后处理产物）
+
+---
+
+## 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、目录约定、脚本模板一览表                          |