@playcraft/cli 0.1.54 → 0.1.55-beta

package/project-template-v2/.claude/skills/playcraft-batch-pipeline/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: playcraft-batch-pipeline
+description: PlayCraft 批处理管线选型与语法指南。涵盖三种批处理方式的选型决策树（Node.js 脚本 / CLI batch / CLI pipeline）、playcraft image batch 的 steps 语法与已知限制、playcraft image pipeline 的 YAML 配置结构与 assemble 精灵图组装。实用配方见 refs 文件。
+triggers: 批处理,batch,pipeline,批量操作,多文件处理,声明式管线,YAML配置,批量resize,批量转换,批量去背,assemble,精灵图组装,image batch,image pipeline,批量处理,parallel,skip-existing,断点续传
+---
+
+# PlayCraft 批处理管线指南
+
+## 0. 三种批处理方式选型
+
+```
+需要批量处理多张图片？
+│
+├─ 涉及 AI 生成（generate-image）或复杂分支逻辑？
+│   └─ → Node.js .mjs 脚本（ta-workspace/scripts/）
+│         参考：playcraft-image-generation Skill 的 reference/ 模板
+│
+├─ 纯本地图像处理（resize/convert/tint 等），需要并发加速？
+│   └─ → playcraft image batch（本节 §1）
+│
+└─ 需要最终自动打包成精灵图，或用配置文件管理管线？
+    └─ → playcraft image pipeline（本节 §2）
+```
+
+**三种方式对比**：
+
+| 特性           | Node.js 脚本 | image batch       | image pipeline          |
+| -------------- | ------------ | ----------------- | ----------------------- |
+| AI 生成        | 支持         | 不支持            | 不支持                  |
+| 并发控制       | 自定义       | `--parallel N`    | 顺序                    |
+| 断点续传       | 自实现       | `--skip-existing` | 不支持                  |
+| 配置复用       | JS 文件      | 命令行            | YAML/JSON 文件          |
+| 自动组装精灵图 | 自实现       | 不支持            | `assemble.sprite-sheet` |
+| 学习成本       | 中           | 低                | 低                      |
+
+---
+
+## 1. playcraft image batch — 声明式多步批处理
+
+对一个目录（或多个文件）中的所有图片，按顺序执行多个处理步骤。
+
+### 基础用法
+
+```bash
+playcraft image batch \
+  --input-dir assets/images/raw/ \
+  --output-dir assets/images/processed/ \
+  --steps "resize --width 256 --height 256, tint --color #FFD700" \
+  --parallel 4 --skip-existing
+```
+
+| 参数                 | 类型   | 说明                                           |
+| -------------------- | ------ | ---------------------------------------------- |
+| `--input-dir <dir>`  | string | 输入目录（与 `--inputs` 二选一）               |
+| `--inputs <paths>`   | string | 逗号分隔的文件列表（与 `--input-dir` 二选一）  |
+| `--glob <pattern>`   | string | 文件匹配模式，默认 `*.png,*.jpg,*.jpeg,*.webp` |
+| `--output-dir <dir>` | string | 输出目录（必填）**输出统一为 .png**            |
+| `--steps <pipeline>` | string | 处理步骤（必填，见下方语法）                   |
+| `--parallel <N>`     | number | 并发数，默认 4                                 |
+| `--skip-existing`    | flag   | 跳过输出目录中已存在的文件（断点续传）         |
+
+### Steps 语法
+
+`--steps` 接受逗号分隔的步骤列表，每步格式为 `子命令名 [参数...]`：
+
+```bash
+--steps "resize --width 128 --height 128, grayscale, tint --color #4488FF"
+```
+
+### 支持的步骤命令
+
+| 可用命令            | 示例                                                      |
+| ------------------- | --------------------------------------------------------- |
+| `resize`            | `resize --width 128 --height 128` 或 `resize --scale 0.5` |
+| `convert`           | `convert --format webp --quality 85`                      |
+| `grayscale`         | `grayscale`                                               |
+| `blur`              | `blur --sigma 5`                                          |
+| `tint`              | `tint --color #FFD700`                                    |
+| `trim`              | `trim --threshold 20`                                     |
+| `negate`            | `negate`                                                  |
+| `rotate`            | `rotate --angle 90`                                       |
+| `flip`              | `flip --direction horizontal`                             |
+| `pad`               | `pad --all 8`                                             |
+| `pixelate`          | `pixelate --pixel-size 8`                                 |
+| `remove-background` | `remove-background --method floodfill --tolerance 40`     |
+
+> **已知限制**：`crop`、`overlay`、`sprite-split`、`sprite-sheet`、`animate`、`use-vfx`、`segment`、`decompose-layers` 不能在 `--steps` 中使用（`segment` / `decompose-layers` 走后端 API）。需要 `crop` 或分层的批量操作请用 for 循环或 Node.js 脚本。
+
+---
+
+## 2. playcraft image pipeline — YAML/JSON 声明式管线
+
+比 `batch` 更强大：支持配置文件复用、可选自动组装精灵图。
+
+### YAML 配置结构
+
+```yaml
+# ta-workspace/pipeline_config.yaml
+input:
+  dir: assets/images/raw_tiles/
+  glob: '*.png'
+
+steps:
+  - command: resize
+    width: 128
+    height: 128
+  - command: trim
+    threshold: 15
+
+output:
+  dir: assets/images/tiles/
+
+assemble: # 可选：处理完后自动组装精灵图
+  sprite-sheet:
+    output: assets/images/tiles_sprite.png
+    columns: 4
+    padding: 2
+```
+
+执行：`playcraft image pipeline --config ta-workspace/pipeline_config.yaml`（加 `--dry-run` 可预览步骤）
+
+### assemble.sprite-sheet 说明
+
+配置 `assemble.sprite-sheet` 后，pipeline 完成所有文件处理后，会自动将 `output.dir` 下的所有 `*.png` 合并为一张精灵图（同时生成 `.json` 元数据）：
+
+```yaml
+assemble:
+  sprite-sheet:
+    output: assets/images/sprite_atlas.png
+    columns: 4 # 每行帧数
+    padding: 2 # 帧间距（像素）
+    sort: name # 排序方式：name（默认）/ modified / none
+```
+
+---
+
+## 3. 何时用哪种方式（完整决策树）
+
+```
+需要批量处理？
+│
+├─ 需要 AI 生成（generate-image/generate-3d）？
+│   └─ 用 Node.js 脚本（ta-workspace/scripts/*.mjs）
+│       参考：playcraft-image-generation SKILL 的 reference/gen-batch.template.mjs
+│
+├─ 只需要本地图像变换（resize/tint/trim/convert/去背等）？
+│   │
+│   ├─ 需要最终合并成精灵图？
+│   │   └─ 用 pipeline（YAML/JSON 配置 + assemble）
+│   │
+│   ├─ 需要并发加速？
+│   │   └─ 用 batch（--parallel N）
+│   │
+│   ├─ 需要断点续传？
+│   │   └─ 用 batch（--skip-existing）
+│   │
+│   └─ 配置需要复用/版本管理？
+│       └─ 用 pipeline（YAML 文件）
+│
+└─ 需要 crop 作为批处理步骤？
+    └─ 用 for 循环（batch 不支持 crop）：
+       for f in dir/*.png; do
+         playcraft image crop --input "$f" --output "out/$(basename $f)" \
+           --x 0 --y 0 --width 128 --height 128
+       done
+```
+
+---
+
+## 4. 已知限制汇总
+
+| 限制                                               | 影响                                                       | 绕过方法                                      |
+| -------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------- |
+| `batch` 的 `--steps` 不支持 `crop`                 | 无法在批处理管线中裁切                                     | 改用 for 循环或 Node.js 脚本                  |
+| `batch` 不支持 `overlay`（需要两个输入）           | 无法批量合成                                               | 改用 Node.js 脚本                             |
+| `pipeline` 不支持并发（顺序处理）                  | 大批量时较慢                                               | 改用 `batch --parallel`                       |
+| `batch` 输出统一为 `.png`（忽略 convert 步骤后缀） | 即使 steps 中有 `convert --format webp`，文件名仍是 `.png` | pipeline 中用 convert 步骤 + 修改 output 路径 |
+| `remove-background --method ai` 在 batch 中不支持  | 批量 AI 去背报错                                           | 改用 floodfill，或用 Node.js 脚本             |
+
+---
+
+## 5. 配方参考
+
+完整的 batch/pipeline 实用配方（批量 resize、批量去背、主题色变体、精灵图组装管线等）见 `refs/ta-batch-pipeline-recipes.md`。

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 改为用户交互触发                              |