@playcraft/cli 0.1.53-beta → 0.1.54

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

@@ -1,306 +0,0 @@
----
-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 改为用户交互触发                              |