@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/skills/playcraft-image-generation/reference/prompt-cookbook.md

@@ -0,0 +1,397 @@
+# Image Generation Prompt Cookbook
+
+> 适用于 PlayCraft CLI `playcraft tools generate-image`。
+> 所有模型均适用；gpt-image-2 类模型对英文 prompt 理解最准确，优先写英文。
+
+---
+
+## 一、Prompt 万能公式
+
+```
+[主体描述] + [风格/介质] + [构图/视角] + [背景] + [质量修饰词]
+```
+
+**示例**：
+
+```
+A golden sword icon, flat 2D vector style, centered composition,
+white background, clean crisp edges, game UI asset, high quality
+```
+
+---
+
+## 二、各素材类型模板
+
+### 🎮 游戏图标（UI Icons）
+
+```
+A [物品名] icon, flat 2D vector illustration, bold outlines,
+vibrant colors, centered composition, white background,
+no shadow, no gradient, game UI style, sharp crisp edges
+```
+
+- 关键词：`flat 2D` / `bold outlines` / `centered` / `no shadow` / `game UI style`
+- 避免：`3D` / `realistic` / `photographic` / `drop shadow`
+
+### 🃏 卡牌 / 棋子 / 方块（Rectangular Tiles）
+
+```
+A playing card: [花色] [数字], flat 2D, clean white card face,
+[花色符号] symbol clearly visible, bold [颜色] ink,
+no drop shadow, no 3D effect, no perspective distortion,
+sharp clean edges, centered on white background
+```
+
+- 关键词：`flat 2D` / `no drop shadow` / `no 3D effect` / `clean edges`
+- 注意：**不需要绿幕**，直接 resize，不要 remove-background
+
+### 👾 游戏角色 / 精灵（Characters & Sprites）
+
+```
+A [角色描述] character, full body visible, game sprite style,
+[艺术风格: pixel art / cartoon / chibi / realistic],
+isolated on solid bright green #00FF00 background,
+centered, facing forward / side view, clean silhouette
+```
+
+- 需要透明背景 → **绿幕策略**，prompt 加 `"on solid bright green #00FF00 background, isolated"`
+- 后处理：`remove-background --tolerance 25`
+
+### 🌄 场景背景（Backgrounds）
+
+```
+[场景描述], [风格: hand-drawn / watercolor / pixel art / 3D render],
+full scene composition, edge to edge, no UI elements,
+[时间: day / night / sunset], [氛围: peaceful / intense / magical],
+[画面比例暗示: wide panoramic / portrait]
+```
+
+- 不需要背景处理，直接 resize
+- 比例建议：横版游戏 `--aspect-ratio 16:9`，竖版 `9:16`
+
+### 🔤 含文字 / 数字的素材
+
+```
+[描述], with [内容] clearly written in bold [颜色] [字体风格] font,
+legible, centered, high contrast text
+```
+
+- gpt-image-2 对文字处理最好，优先使用
+- Google Gemini 对中文支持较好
+
+### 🌿 纹理 / 材质（Textures）
+
+```
+[材质名: ice / wood / metal / stone] texture, seamless tileable,
+top-down view, diffuse map, [颜色倾向],
+no shadows, flat lighting, high detail
+```
+
+### 🔲 精灵图网格（Sprite Sheet Grid，gpt-image-2 直出）
+
+**一次 API 调用生成完整精灵图，后续 sprite-split 切分**。比逐个生成效率高 N 倍。
+
+```
+Sprite sheet grid layout, [N] columns × [M] rows.
+Each cell contains one [元素类型]. Cell contents:
+[Row1,Col1]: [内容描述]; [Row1,Col2]: [内容描述]; ...
+Grid layout, uniform cell size, equal spacing,
+elements perfectly centered in each cell.
+No borders between cells, no labels, no numbers on cells.
+[风格描述]
+```
+
+**卡牌套（扑克）示例**：
+
+```
+Sprite sheet grid layout, 4 columns × 4 rows.
+Each cell contains one playing card face, flat 2D illustration, white card face.
+Cell contents:
+[Row1,Col1]: Ace of Spades, A symbol top-left, large spade symbol center;
+[Row1,Col2]: 2 of Spades, number 2, two spade symbols;
+[Row1,Col3]: 3 of Spades, number 3, three spade symbols;
+[Row1,Col4]: 4 of Spades, number 4, four spade symbols;
+[Row2,Col1]: 5 of Spades; [Row2,Col2]: 6 of Spades; [Row2,Col3]: 7 of Spades; [Row2,Col4]: 8 of Spades;
+[Row3,Col1]: 9 of Spades; [Row3,Col2]: 10 of Spades; [Row3,Col3]: Jack of Spades with J; [Row3,Col4]: Queen of Spades with Q;
+[Row4,Col1]: King of Spades with K; [Row4,Col2]: Ace of Hearts; [Row4,Col3]: 2 of Hearts; [Row4,Col4]: 3 of Hearts.
+Grid layout, equal cell size, no borders between cells. Bold black ink for spades, bold red ink for hearts.
+```
+
+**图标集示例**（一批 9 个图标）：
+
+```
+Sprite sheet grid, 3 columns × 3 rows. Flat 2D game icon style, white background.
+[Row1,Col1]: sword icon; [Row1,Col2]: shield icon; [Row1,Col3]: bow and arrow icon;
+[Row2,Col1]: magic staff icon; [Row2,Col2]: potion bottle icon; [Row2,Col3]: scroll icon;
+[Row3,Col1]: coin gold icon; [Row3,Col2]: gem diamond icon; [Row3,Col3]: key icon.
+Each icon centered in its cell, bold outlines, vibrant colors, no shadow.
+```
+
+**背景选择（重要！）**：
+
+| 素材类型                            | prompt 背景写法                                     | 切分后处理                         |
+| ----------------------------------- | --------------------------------------------------- | ---------------------------------- |
+| 独立元素（角色/车/道具/图标）需透明 | `isolated on solid bright green #00FF00 background` | `remove-background --tolerance 25` |
+| 卡牌/棋子/UI 面板（矩形本体）       | `white background, no shadow`                       | 直接 resize，不去背景              |
+
+**注意事项**：
+
+- 每批最多 **4×4 = 16 个元素**，超过会出现混乱
+- 每个格的描述要精确，包含特征性视觉元素
+- 切分后用 `sprite-split --rows N --columns M` 按网格切分
+- 模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)
+
+---
+
+## 三、风格关键词速查
+
+### 艺术风格
+
+| 风格      | 关键词                                                           |
+| --------- | ---------------------------------------------------------------- |
+| 像素艺术  | `pixel art, 8-bit style, limited color palette, sharp pixels`    |
+| 扁平插画  | `flat 2D illustration, vector style, bold outlines, minimal`     |
+| 卡通      | `cartoon style, bright colors, cel-shaded, clean lines`          |
+| Q版/Chibi | `chibi style, cute, big head proportion, round shapes`           |
+| 写实      | `realistic, photorealistic, detailed, high resolution`           |
+| 水彩      | `watercolor painting, soft edges, transparent washes, artistic`  |
+| 赛博朋克  | `cyberpunk, neon lights, dark background, glowing effects`       |
+| 奇幻      | `fantasy art, magical, ethereal glow, detailed illustration`     |
+| 中国风    | `Chinese traditional ink painting style, brush strokes, minimal` |
+
+### 质量修饰词（末尾通用）
+
+```
+high quality, clean, sharp details, professional game asset, centered composition
+```
+
+### 负面描述（告诉模型不要什么）
+
+```
+no text, no watermark, no blur, no noise, no artifacts, no extra limbs,
+no distortion, no compression artifacts, isolated subject
+```
+
+---
+
+## 四、gpt-image-2 专项技巧
+
+gpt-image-2 是目前质量最高的文生图模型，prompt 套路略有不同：
+
+### 特点
+
+- **英文 prompt 效果最佳**，中文理解也不错但英文更稳定
+- 对**复杂场景**、**细节描述**处理能力远超其他模型
+- 支持**图生图 edit 模式**（传 `--reference-image`），局部编辑能力强
+- 不支持透明 PNG 输出（ALPHA = no），需绿幕策略
+
+### prompt 格式建议
+
+```
+[简洁主体，1句话] + [风格描述，2-3个关键词] + [技术要求，1-2个]
+```
+
+避免过度堆砌修饰词（10+ 个关键词反而会降低质量）。
+
+### Edit 模式（图生图）的 prompt 格式
+
+```
+[修改指令，动词开头] + [保持不变的元素] + [想要改变的元素]
+```
+
+示例：
+
+```
+# 好的 edit prompt：
+"Change the rank to 2, keep the same card layout and spade suit symbol"
+
+# 差的 edit prompt（会让模型重新生成）：
+"A playing card with 2 of spades, white background, flat 2D..."
+```
+
+### 精灵图直出（最高效用法！）
+
+**gpt-image-2 理解布局描述能力最强**，可以一次生成完整网格图：
+
+```
+# 精灵图直出 prompt 结构
+Sprite sheet grid layout, [N] columns × [M] rows.
+Each cell: [描述元素类型和内容].
+Grid layout, uniform cell size, equal cell spacing,
+elements centered in each cell, no borders between cells.
+[风格描述]
+```
+
+**每批推荐 ≤ 16 个元素（4×4）**。超过时分批，每批生成一张网格图。
+
+### 批量出图（--count N）
+
+同一 prompt 一次出多张候选：
+
+```bash
+playcraft tools generate-image \
+  --prompt "A sword icon, flat 2D..." \
+  --output assets/gen/sword \
+  --count 4 \
+  --image-model iegg-litellm/gpt-image-2
+# → sword_1.png sword_2.png sword_3.png sword_4.png
+# 从 4 张中挑最好的，比重试 4 次高效
+```
+
+---
+
+## 五、多轮迭代策略
+
+### Phase 1：概念确认（1-4 张）
+
+```bash
+# 一次 API 调用生成 4 个候选，选最好的（比 4 次独立调用更高效）
+playcraft tools generate-image \
+  --prompt "..." \
+  --output "test/concept" \
+  --count 4 \
+  --image-model iegg-litellm/gpt-image-2
+# → concept_1.png concept_2.png concept_3.png concept_4.png
+```
+
+### Phase 2：锁定风格，加 reference 批量
+
+确认概念图后，**所有后续生图必须加 `--reference-image`**，用确认的概念图作为参考。
+
+### Phase 3：批量 edit 微调
+
+对已生成的图片用 edit 模型做微调（调颜色、调细节），比重新生成更高效。
+
+---
+
+## 八、UI / HUD 元素模板
+
+> 可玩广告中高频出现的界面元素。这些素材需要**透明背景**（独立叠加在游戏画面上），且必须配合 60-30-10 色彩法则——CTA 按钮颜色必须是画面中唯一出现该颜色的地方。
+>
+> 注意：`figer_icon.aiimage`、`win_result_panel.aiimage` 等 atom Skills 提供了带参考图的生成配方，PM `playcraft skills match` 能匹配到时优先使用。本节模板用于无对应 atom Skill 的场景。
+
+### 🟠 CTA 按钮（Call-to-Action Button）
+
+```
+Subject: Mobile game CTA button, rounded rectangle shape
+Style: [flat 2D vector / semi-glossy / cartoon 3D beveled — match game style]
+Important details: [bright orange / gold / green] gradient fill,
+  white bold sans-serif text reading "PLAY NOW",
+  subtle drop shadow below button, glossy highlight on top edge,
+  3px white inner border, corners rounded radius 24px
+Use case: Game ad install button, isolated asset, HTML5 playable ad
+Constraints: Transparent background, no extra elements, centered, clean crisp edges,
+  no watermark
+```
+
+- CTA 颜色必须是游戏画面中**最少使用**的颜色（对比稀缺性原则）
+- 触控目标区域 ≥ 48×48px，生成建议尺寸 360×120px（9:3 比例）
+- 后处理：不需要去背景（直接生成透明背景或用绿幕）
+
+---
+
+### ⬜ 进度条 / 血条（Progress Bar）
+
+```
+Subject: Horizontal game progress bar, [80%] filled
+Style: [flat 2D / cartoon / metallic frame]
+Important details: [color] filled portion [80% of total width], unfilled portion [gray / dark],
+  rounded end caps, thin outer frame in [darker shade],
+  optional inner glow on filled section
+Use case: Game HUD progress indicator, isolated UI element
+Constraints: Transparent background, horizontal orientation, no text labels,
+  clean edges, no watermark
+```
+
+- 固定填充比例（75–90%）激活进度错觉心理钩子
+- 建议尺寸：480×48px（10:1 宽高比）
+
+---
+
+### 👆 教程引导箭头 / 手势（Tutorial Guidance）
+
+```
+Subject: Cartoon pointing hand with index finger extended downward
+Style: cartoon, slightly stylized proportions, large rounded fingertip
+Important details: warm skin tone, white sleeve cuff visible at wrist,
+  soft drop shadow beneath finger tip, friendly approachable style,
+  [optional: subtle animated glow ring around fingertip]
+Use case: Tutorial overlay tap gesture for playable ad, points toward target element
+Constraints: Transparent background, PNG with alpha channel,
+  no extra limbs or elements, finger pointing at bottom-center
+```
+
+**箭头变体**（更简洁）：
+
+```
+Subject: Bold cartoon arrow pointing [down / right], game tutorial UI
+Style: flat 2D, thick outline 4px, rounded arrowhead
+Important details: [bright yellow / white] fill, [dark outline],
+  slight perspective tilt for depth, attention-grabbing
+Constraints: Transparent background, single clean arrow shape, no text
+```
+
+---
+
+### 💬 对话气泡 / 提示框（Tooltip / Speech Bubble）
+
+```
+Subject: Game UI speech bubble / tooltip, [rectangular with tail / rounded cloud shape]
+Style: flat cartoon, clean vector
+Important details: white or [light color] fill, [2–3px] dark outline,
+  tail pointing [down-left / down-center], interior empty for text overlay,
+  subtle inner shadow or gradient
+Use case: Game tutorial hint tooltip, isolated UI asset
+Constraints: Transparent background, no text inside, clean edges,
+  no watermark, no extra decorations
+```
+
+- 生成空白气泡，文字通过代码 Canvas 叠加（避免 AI 文字渲染错误）
+
+---
+
+### 🏆 EndCard 合成画面元素（Reward Icons）
+
+EndCard 需要展示"可见但未到手"的奖励，驱动 FOMO 安装冲动：
+
+```
+Subject: [treasure chest half-open / pile of gold coins / rare gem crystal]
+Style: [match game art style from concept mockup]
+Important details: [treasure chest]: lid slightly ajar, golden glow escaping from inside,
+  jewels visible inside, exciting but incomplete;
+  [gold coins]: scattered pile, gleaming highlights, not neatly stacked (implies uncollected);
+  [gem crystal]: large, brilliant facets, floating above ground, clearly valuable
+Use case: EndCard reward visual, creates FOMO and drives install
+Constraints: Transparent background, centered, isolated subject,
+  no CTA text (added separately), warm celebratory lighting
+```
+
+- EndCard **不能**展示"已获得"状态——宝箱要半开、金币要散落、关卡要未完成
+- 这些元素和 CTA 按钮分开生成，由 Developer 在代码中合成布局
+
+---
+
+### 📊 UI 元素背景处理规则速查
+
+| UI 元素类型      | prompt 背景写法                                 | 后处理                         |
+| ---------------- | ----------------------------------------------- | ------------------------------ |
+| CTA 按钮         | `transparent background` 或绿幕                 | floodfill 去背                 |
+| 进度条           | `transparent background` 或绿幕                 | floodfill 去背                 |
+| 引导手势         | `transparent background, PNG with alpha`        | floodfill 去背（tolerance 25） |
+| 对话气泡         | `transparent background` 或绿幕                 | floodfill 去背                 |
+| EndCard 奖励图标 | 绿幕（`solid bright green #00FF00 background`） | floodfill 去背（tolerance 25） |
+
+---
+
+## 六、常见问题 & 修正方案
+
+| 问题               | 原因                 | 修正                                             |
+| ------------------ | -------------------- | ------------------------------------------------ |
+| 图标边缘有阴影     | 模型默认加立体效果   | 加 `no shadow, no drop shadow, flat 2D`          |
+| 构图不居中         | 没有明确指定         | 加 `centered composition, subject centered`      |
+| 背景不干净         | 背景描述不够明确     | 加 `solid white background, isolated` 或绿幕策略 |
+| 多个物体出现       | 主体不够明确         | 加 `a single [物体]`, `only one [物体]`          |
+| 文字拼写错误       | 所有模型通病         | 尝试 gpt-image-2（最好），或多生成几张           |
+| 风格不一致（批量） | 没用 reference image | Phase 2 必须加 `--reference-image`               |
+| 细节过于复杂       | 素材尺寸小但细节太多 | 加 `simple design, minimal details, bold shapes` |
+| 生成极慢/超时      | 模型负载高           | 换另一个 provider 或换模型                       |

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

@@ -0,0 +1,296 @@
+/**
+ * validate-sprite-sheet.template.mjs
+ *
+ * 精灵图技术正确性验证脚本。
+ * TA 在 Compliance Gate 前运行，确认精灵图尺寸、帧数、通道数均符合要求。
+ *
+ * 使用方法：
+ *   cp .claude/skills/playcraft-image-generation/reference/validate-sprite-sheet.template.mjs \
+ *      ta-workspace/scripts/validate-sprite-sheet.mjs
+ *   # 修改下方 SHEETS 数组后运行：
+ *   node ta-workspace/scripts/validate-sprite-sheet.mjs
+ *
+ * 输出示例：
+ *   [VALIDATE] tile_bounce_anim.png
+ *     尺寸验算: 512×256 = 4cols × 128px × 2rows × 128px ✅
+ *     通道数: 4 (RGBA) ✅
+ *     帧数: 8 帧（JSON 验证: N/A — animate 命令无 JSON）
+ *     帧内容抽查 (帧 0, 4, 7): 全部非空 ✅
+ *   [VALIDATE] explosion_small.png
+ *     尺寸验算: 预设 4cols × 8frames → 期望 W=cols×frameW ✅
+ *     通道数: 4 (RGBA) ✅
+ *
+ * 注意：脚本使用 `playcraft image info --json` 获取图片信息。
+ *       JSON 验证仅适用于 `sprite-sheet` 命令输出（有配套 .json 文件）。
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, appendFileSync, mkdirSync } from 'fs';
+import path from 'path';
+
+// ─── CONFIG ───────────────────────────────────────────────────────────────────
+
+/**
+ * 每个条目描述一张精灵图的期望参数。
+ * source: 'sprite-sheet' | 'animate' | 'use-vfx'
+ *   - sprite-sheet: 有配套 JSON，可做完整验证
+ *   - animate:      无 JSON，从 stdout 记录的参数验证
+ *   - use-vfx:      无 JSON，从 list-vfx --json 记录的参数验证
+ */
+const SHEETS = [
+  {
+    file: 'assets/images/tiles/tile_bounce_anim.png',
+    source: 'animate',          // 'sprite-sheet' | 'animate' | 'use-vfx'
+    columns: 4,
+    frameWidth: 128,
+    frameHeight: 128,
+    frameCount: 8,
+    padding: 0,
+    jsonFile: null,             // animate 无 JSON，填 null
+  },
+  {
+    file: 'assets/images/vfx/explosion.png',
+    source: 'use-vfx',
+    columns: 4,
+    frameWidth: 128,            // use-vfx 预设宽高需用 playcraft image info 确认
+    frameHeight: 128,
+    frameCount: 8,
+    padding: 0,
+    jsonFile: null,
+  },
+  // sprite-sheet 示例（有 JSON）：
+  // {
+  //   file: 'assets/images/tiles/tile_atlas.png',
+  //   source: 'sprite-sheet',
+  //   columns: 6,
+  //   frameWidth: 128,
+  //   frameHeight: 128,
+  //   frameCount: 34,
+  //   padding: 2,
+  //   jsonFile: 'assets/images/tiles/tile_atlas.json',
+  // },
+];
+
+const LOG_FILE = 'ta-workspace/logs/sprite-validate.log';
+
+// ─── HELPERS ──────────────────────────────────────────────────────────────────
+
+function imageInfo(filePath) {
+  try {
+    const raw = execSync(
+      `playcraft image info --input "${filePath}" --json`,
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
+    );
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function pass(msg) { return `✅ ${msg}`; }
+function fail(msg) { return `❌ ${msg}`; }
+
+// ─── VALIDATION ───────────────────────────────────────────────────────────────
+
+async function validateSheet(sheet) {
+  const lines = [`\n[VALIDATE] ${sheet.file} (source: ${sheet.source})`];
+  let allPassed = true;
+
+  if (!existsSync(sheet.file)) {
+    lines.push(`  ${fail('文件不存在 — 请先完成资产生产')}`);
+    return { passed: false, lines };
+  }
+
+  // ── 1. 获取实际图片信息 ────────────────────────────────────────────────
+  const info = imageInfo(sheet.file);
+  if (!info) {
+    lines.push(`  ${fail('无法读取图片信息（playcraft image info 失败）')}`);
+    return { passed: false, lines };
+  }
+
+  const actualW = info.width;
+  const actualH = info.height;
+  const actualChannels = info.channels ?? 4;
+
+  // ── 2. 尺寸数学验算 ────────────────────────────────────────────────────
+  const rows = Math.ceil(sheet.frameCount / sheet.columns);
+  const expectedW = sheet.columns * sheet.frameWidth + (sheet.columns - 1) * sheet.padding;
+  const expectedH = rows * sheet.frameHeight + (rows - 1) * sheet.padding;
+
+  const dimOk = actualW === expectedW && actualH === expectedH;
+  if (dimOk) {
+    lines.push(
+      `  ${pass(`尺寸验算: ${actualW}×${actualH} = ${sheet.columns}cols×${sheet.frameWidth}px + ${rows}rows×${sheet.frameHeight}px (padding=${sheet.padding}px)`)}`
+    );
+  } else {
+    allPassed = false;
+    lines.push(
+      `  ${fail(`尺寸不匹配: 实际 ${actualW}×${actualH}，期望 ${expectedW}×${expectedH}`)}`
+    );
+    lines.push(`    → 检查 columns/frameWidth/frameHeight/padding 参数是否与生成命令一致`);
+    lines.push(`    → animate 命令 padding 固定为 0；sprite-sheet 命令默认 padding 为 0`);
+  }
+
+  // ── 3. 通道数验证 ──────────────────────────────────────────────────────
+  if (actualChannels === 4) {
+    lines.push(`  ${pass(`通道数: 4 (RGBA，支持透明背景)`)}`);
+  } else {
+    allPassed = false;
+    lines.push(
+      `  ${fail(`通道数: ${actualChannels}（不是 4/RGBA）— 透明区域将渲染为黑色`)}`
+    );
+    lines.push(`    → 如果原图有透明背景，确认去背景步骤正确（remove-background 或生成时使用绿幕策略）`);
+  }
+
+  // ── 4. JSON 验证（仅 sprite-sheet 命令）────────────────────────────────
+  if (sheet.source === 'sprite-sheet') {
+    const jsonPath = sheet.jsonFile || sheet.file.replace(/\.png$/i, '.json');
+    if (!existsSync(jsonPath)) {
+      allPassed = false;
+      lines.push(`  ${fail(`JSON 文件不存在: ${jsonPath}`)}`);
+      lines.push(`    → sprite-sheet 命令应自动生成 .json，确认命令执行成功`);
+    } else {
+      try {
+        const json = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+        const frameKeys = Object.keys(json.frames ?? {});
+        const jsonFrameCount = frameKeys.length;
+
+        if (jsonFrameCount === sheet.frameCount) {
+          lines.push(`  ${pass(`JSON 帧数: ${jsonFrameCount} 帧`)}`);
+        } else {
+          allPassed = false;
+          lines.push(
+            `  ${fail(`JSON 帧数不匹配: JSON 中 ${jsonFrameCount} 帧，期望 ${sheet.frameCount} 帧`)}`
+          );
+        }
+
+        // 验证 meta.size
+        const metaW = json.meta?.size?.w;
+        const metaH = json.meta?.size?.h;
+        if (metaW === actualW && metaH === actualH) {
+          lines.push(`  ${pass(`JSON meta.size: ${metaW}×${metaH} 与实际图片一致`)}`);
+        } else {
+          allPassed = false;
+          lines.push(
+            `  ${fail(`JSON meta.size 不匹配: JSON 中 ${metaW}×${metaH}，实际 ${actualW}×${actualH}`)}`
+          );
+        }
+
+        // 帧名字典序警告（数字后缀需补零）
+        const hasUnpaddedNumbers = frameKeys.some(k => /[^0]_\d\.png$/.test(k));
+        if (hasUnpaddedNumbers) {
+          lines.push(
+            `  ⚠️  帧名警告: 检测到未补零的数字后缀（如 _1.png vs _10.png）`
+          );
+          lines.push(
+            `    → 字典序下 f_10.png 排在 f_2.png 之前，导致动画帧乱序`
+          );
+          lines.push(`    → 输入帧文件名应补零对齐（f_01.png, f_02.png...）`);
+        }
+      } catch {
+        allPassed = false;
+        lines.push(`  ${fail(`JSON 文件解析失败: ${jsonPath}`)}`);
+      }
+    }
+  } else {
+    lines.push(
+      `  ℹ️  JSON 验证: 跳过（${sheet.source} 命令不输出 JSON）— 网格参数已记录在 ta-log.md`
+    );
+  }
+
+  // ── 5. 帧内容抽查（随机 3 帧，验证非透明像素 > 1%）─────────────────────
+  if (dimOk && sheet.frameWidth > 0 && sheet.frameHeight > 0) {
+    const sampleFrameIndices = [
+      0,
+      Math.floor(sheet.frameCount / 2),
+      sheet.frameCount - 1,
+    ].filter((v, i, a) => a.indexOf(v) === i);
+
+    const emptyFrames = [];
+    for (const frameIdx of sampleFrameIndices) {
+      const col = frameIdx % sheet.columns;
+      const row = Math.floor(frameIdx / sheet.columns);
+      const x = col * (sheet.frameWidth + sheet.padding);
+      const y = row * (sheet.frameHeight + sheet.padding);
+
+      try {
+        // 裁剪单帧并检查非透明像素比例
+        const cropResult = execSync(
+          `playcraft image crop \
+--input "${sheet.file}" \
+--output ta-workspace/tmp/_frame_check_${frameIdx}.png \
+--x ${x} --y ${y} \
+--width ${sheet.frameWidth} --height ${sheet.frameHeight}`,
+          { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
+        );
+
+        const frameInfo = imageInfo(`ta-workspace/tmp/_frame_check_${frameIdx}.png`);
+        // playcraft image info 返回的 dominantColors 可以间接判断非空
+        // 简单启发式：如果 dominant colors 存在且有非透明颜色，认为帧非空
+        const nonEmpty = frameInfo && (frameInfo.dominantColors?.length > 0 || frameInfo.hasAlpha === false);
+        if (!nonEmpty) emptyFrames.push(frameIdx);
+      } catch {
+        // 裁剪失败跳过
+      }
+    }
+
+    if (emptyFrames.length === 0) {
+      lines.push(
+        `  ${pass(`帧内容抽查 (帧 ${sampleFrameIndices.join(', ')}): 全部非空`)}`
+      );
+    } else {
+      allPassed = false;
+      lines.push(
+        `  ${fail(`帧内容抽查: 帧 ${emptyFrames.join(', ')} 疑似全透明/空帧`)}`
+      );
+      lines.push(`    → 检查对应帧位置坐标是否正确，或去背景是否过激（tolerance 过高）`);
+    }
+
+    // 清理临时文件
+    try {
+      execSync(`rm -f ta-workspace/tmp/_frame_check_*.png`, { stdio: 'ignore' });
+    } catch { /* ignore */ }
+  }
+
+  return { passed: allPassed, lines };
+}
+
+// ─── MAIN ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  mkdirSync('ta-workspace/logs', { recursive: true });
+  mkdirSync('ta-workspace/tmp', { recursive: true });
+
+  console.log('\n🔍 精灵图技术验证');
+  console.log(`   检查 ${SHEETS.length} 张精灵图\n`);
+
+  let passCount = 0;
+  let failCount = 0;
+  const allLines = [];
+
+  for (const sheet of SHEETS) {
+    const { passed, lines } = await validateSheet(sheet);
+    lines.forEach(l => console.log(l));
+    allLines.push(...lines);
+    if (passed) passCount++;
+    else failCount++;
+  }
+
+  const summary = [
+    `\n=== 验证汇总 ===`,
+    `  总计: ${SHEETS.length} 张  通过: ${passCount}  失败: ${failCount}`,
+    failCount > 0
+      ? `  ❌ 存在问题的精灵图需在 Compliance Gate 前修复`
+      : `  ✅ 全部通过，可继续 Compliance Gate`,
+    '',
+  ].join('\n');
+
+  console.log(summary);
+
+  const timestamp = new Date().toISOString();
+  appendFileSync(LOG_FILE, `\n[${timestamp}]\n${allLines.join('\n')}\n${summary}`);
+
+  if (failCount > 0) process.exit(1);
+}
+
+main().catch(e => { console.error(e); process.exit(1); });