@playcraft/cli 0.1.54 → 0.1.55-beta

package/project-template-v2/.claude/skills/playcraft-image-generation/reference/ta-image-generation-detail.md

@@ -0,0 +1,300 @@
+# TA (Technical Artist, 技术美术师) 图片生成进阶参考
+
+> 本文件供 TA/Designer 在需要精灵图直出、Edit 模型变体、错误恢复等进阶场景时按需查阅。核心决策逻辑见 `playcraft-image-generation` skill。复制模板前，将 `SKILL_DIR` 设为本次实际加载的 `SKILL.md` 所在目录（以技能加载回执为准）。
+
+---
+
+## 1. 精灵图直出 + 批量出图策略
+
+### 策略一：直接生成整张精灵图（最高效）
+
+**一次 API (Application Programming Interface, 应用程序编程接口) 调用生成包含多个元素的网格图**，后续用 `sprite-split` 切分。使用主文选定的模型，不因批量生成自动改用旧模型。
+
+> 保留命令行默认等待时间。等待本身不表示请求失败；本地超时也不表示后端已停止，确认原请求状态后再决定下一步，避免重复计费。
+
+#### 先判断：元素需要透明背景吗？
+
+```
+需要透明背景（独立元素：角色、车、道具、图标）？
+├─ 常规透明交付 → --remove-background；按主文第 2 节准备源图背景
+│                切分后保留透明通道，不重复去背
+├─ 不透明牌面/场景 → --no-remove-background；白色牌面属于主体
+└─ 明确选择独立色幕 → 仅限主文第 3 节；关闭整板自动去背，切分后逐格去背
+```
+
+#### 白底示例（卡牌，不需要去背景）
+
+```bash
+playcraft tools generate-image \
+  --prompt "Sprite sheet grid, 4 columns × 2 rows. Each cell: one playing card face, flat 2D, white card face, uniform size. Row 1: Ace of Spades, 2 of Spades, 3 of Spades, 4 of Spades. Row 2: 5 of Spades, 6 of Spades, 7 of Spades, 8 of Spades. Grid layout, equal cell size, no border between cells." \
+  --output assets/gen/cards_sheet.png \
+  --aspect-ratio 3:2 \
+  --image-model iegg-litellm/gpt-image-2.5-sunburst \
+  --no-remove-background
+
+# 查尺寸再切分（frame-width=总宽/列数, frame-height=总高/行数）
+playcraft image info --input assets/gen/cards_sheet.png
+playcraft image sprite-split \
+  --input assets/gen/cards_sheet.png \
+  --output-dir assets/images/cards/ \
+  --rows 2 --columns 4 \
+  --frame-width <总宽/4> --frame-height <总高/2>
+```
+
+#### 自动透明示例（独立元素）
+
+```bash
+# Step 1：Image 2.5 由后端组装源图背景并验收透明交付
+playcraft tools generate-image \
+  --prompt "Sprite sheet grid, 3 columns × 1 row. Each cell: one car, flat 2D vector, bold outline, centered, isolated subject. [Row1,Col1]: red sports car front view; [Row1,Col2]: blue SUV front view; [Row1,Col3]: yellow taxi front view. Grid layout, equal cell size, no border between cells." \
+  --output assets/gen/cars_sheet.png \
+  --aspect-ratio 3:2 \
+  --image-model iegg-litellm/gpt-image-2.5-sunburst \
+  --remove-background
+
+# Step 2：切分
+playcraft image info --input assets/gen/cars_sheet.png
+playcraft image sprite-split \
+  --input assets/gen/cars_sheet.png \
+  --output-dir assets/images/cars/ \
+  --rows 1 --columns 3 \
+  --frame-width <总宽/3> --frame-height <总高>
+
+# Step 3：验证每格主体完整及深浅背景上的透明边缘，不重复去背
+```
+
+明确选用其他模型时，同样传 `--remove-background`，但首次 prompt 需追加单一 `on a uniform solid pure white background for subsequent background removal`；后端不会像 Image 2.5 那样自动补源图背景。
+
+#### 独立色幕示例（仅限明确选择的制作流程）
+
+先按主文第 3 节选与主体不冲突的色幕。参考图和交付规格来自目标字段时先读取，再显式传给中间图请求，省略 `--target-asset`，避免字段透明要求覆盖保留色幕的开关。
+
+```bash
+# 已明确锁定不支持原生透明的模型与品红色幕；常规流程不使用此分支
+playcraft tools generate-image \
+  --prompt "Sprite sheet grid, 3 columns × 1 row. [Row1,Col1]: red sports car; [Row1,Col2]: blue SUV; [Row1,Col3]: yellow taxi. Each car isolated, centered on a uniform solid #FF00FF background, equal cell size, no borders, no shadows." \
+  --output assets/gen/cars_chroma.png \
+  --aspect-ratio 3:2 \
+  --image-model mulerouter/gpt-image-2 \
+  --no-remove-background
+
+# 读取实际尺寸并 sprite-split 后，逐格去背；品红使用 tolerance 20
+playcraft image remove-background \
+  --input assets/gen/cars-split/frame_r0_c0.png \
+  --output assets/images/cars/red_car.png \
+  --tolerance 20
+```
+
+其他格同样处理，并分别验收。自动透明图使用 `backgroundMode='automatic'`；独立色幕脚本设 `backgroundMode='chroma'`、`chromaColor` 和 `chromaTolerance`，不要把两种流程混用。
+
+**Prompt 关键词**：`sprite sheet grid, N columns × M rows, grid layout, equal cell size, uniform size`
+
+**每批推荐最多 16 个元素（4x4）**，元素太多时会出现混乱。
+
+### 策略二：批量出图（n>1，一次 API 调用返回多张候选）
+
+`--count N` 让同一个 prompt 一次返回 N 张候选图，适合 Phase 1 挑图。**谨慎使用，容易触发 provider 并发限制。**
+
+```bash
+# 一次 API 调用生成 4 张候选，选最好的
+playcraft tools generate-image \
+  --prompt "A single playing card, Ace of Hearts, flat 2D..." \
+  --output assets/gen/card \
+  --count 4 \
+  --image-model iegg-litellm/gpt-image-2
+# → 保存为 card_1.png card_2.png card_3.png card_4.png
+```
+
+> `--count N` 是"同一 prompt 出 N 张变体"，而不是"N 个不同元素"。生成 N 个不同元素请用策略一（精灵图直出）。
+
+**两种策略对比**：
+
+| 场景                       | 推荐策略                    | 说明                              |
+| -------------------------- | --------------------------- | --------------------------------- |
+| <=16 个同类元素            | 精灵图直出（策略一）        | 一张网格图 + sprite-split，最高效 |
+| 17-52 个元素               | 精灵图直出分批（每批 <=16） | 生成多张精灵图再切分              |
+| 风格变体（同构造不同内容） | 批量出图 `--count 4-6`      | 同 prompt 出多张挑最好的          |
+| 禁止                       | 逐个生成每个元素            | 效率极低，应全面避免              |
+
+### 策略三：分批生成精灵图（元素数量 > 16）
+
+```javascript
+// ta-workspace/scripts/gen-cards-batch-sheets.mjs
+// 52 张牌 → 4 批 × 13 = 4 张精灵图，再统一切分
+const BATCHES = [
+  {
+    name: 'sheet_spades',
+    cards: ['A♠', '2♠', '3♠', '4♠', '5♠', '6♠', '7♠', '8♠', '9♠', '10♠', 'J♠', 'Q♠', 'K♠'],
+  },
+  {
+    name: 'sheet_hearts',
+    cards: ['A♥', '2♥', '3♥', '4♥', '5♥', '6♥', '7♥', '8♥', '9♥', '10♥', 'J♥', 'Q♥', 'K♥'],
+  },
+  {
+    name: 'sheet_diamonds',
+    cards: ['A♦', '2♦', '3♦', '4♦', '5♦', '6♦', '7♦', '8♦', '9♦', '10♦', 'J♦', 'Q♦', 'K♦'],
+  },
+  {
+    name: 'sheet_clubs',
+    cards: ['A♣', '2♣', '3♣', '4♣', '5♣', '6♣', '7♣', '8♣', '9♣', '10♣', 'J♣', 'Q♣', 'K♣'],
+  },
+];
+// 每批生成一张 13×1 精灵图，再用 sprite-split 切分
+```
+
+参考脚本模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)
+
+---
+
+## 2. Edit 模型工作流（基图 → 编辑变体）
+
+### 适用场景
+
+结构相同、只改局部的变体集合：扑克牌（换花色/换数字）、棋子（换颜色）、图标集（换内容符号）。
+
+### 工作流
+
+```
+Phase 1：高质量模型生成 1 张完美基图
+  → gpt-image-2 / gemini-flash（最佳质量）
+  → 反复生成直到满意，存为 base_xxx.png
+
+Phase 2：用参考图 + prompt 批量生成变体
+  → 任何 text+image 或 image→image 模型均可
+  → 将基图作为 --reference-image，prompt 中描述变体差异
+  → 纯 edit 场景可用 mulerouter/qwen-image-edit-max
+```
+
+### Edit Prompt 写法
+
+```
+好的写法（修改指令）：
+   "Change the rank symbol from A to 2, show two spade symbols in the center"
+
+差的写法（完整重描述）：
+   "A playing card with two spade symbols, white background..."
+   （这会让模型重新生图，而不是编辑）
+```
+
+### 使用脚本模板
+
+```bash
+cp "$SKILL_DIR/reference/gen-edit-variants.template.mjs" \
+   ta-workspace/scripts/gen-<name>-variants.mjs
+# 修改 CONFIG.baseImage / CONFIG.editModel / VARIANTS[] 后运行
+node ta-workspace/scripts/gen-<name>-variants.mjs
+```
+
+---
+
+## 3. 错误恢复策略
+
+后端统一限制模型、供应商与重生成的总尝试次数；命令行默认不额外重试。普通素材默认模型选择、原生透明优先与剩余一次干净底图重生成均以主文第 2 节为准，脚本不再叠加模型回退链。
+
+| 错误现象               | 立即行动                                                                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| 仍在等待 / 本地超时    | 确认原请求状态，等待或核实后端已结束；不要并发重发，也不要仅因等待改模型。                                               |
+| 上游错误 / 网络失败    | 记录请求编号、实际 provider/model 与尝试次数，报告后端诊断；用户或流程锁定的模型不静默更换。                             |
+| 透明源图或最终验收失败 | 报告失败阶段并停止；不把棋盘格、补边或未完成的去背当成功，不自行改用色幕。                                               |
+| 去背处理失败           | 报告处理错误并停止，不重复生图或降低最终透明要求。                                                                       |
+| 参考图 / 交付参数错误  | 修正路径或参数后再发送；保留用户及字段约束，不丢弃参考图继续生成。                                                       |
+| 风格或内容偏差         | 参考 [prompt-cookbook.md](prompt-cookbook.md) 的主体模板，检查实际模型、参考图与交付规格；新一轮生成仍保留最终背景要求。 |
+
+---
+
+## 4. 批量生成最佳实践
+
+### 首选策略：精灵图直出（见第 1 节）
+
+**优先用本次选定的模型生成包含多个元素的网格图**，然后用 `sprite-split` 切分，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
+
+- 需要 reference-image 一致性（网格 prompt 不稳定）
+- 每个元素差异太大，一张图放不下
+
+### 单张验证后再批量
+
+先生成 1 张验证效果，满意后再运行批量脚本。
+
+### 使用 Node.js 脚本（推荐）
+
+参见 [gen-batch.template.mjs](gen-batch.template.mjs)，复制到 `ta-workspace/scripts/` 后修改 CONFIG 区域。
+
+```bash
+cp "$SKILL_DIR/reference/gen-batch.template.mjs" \
+   ta-workspace/scripts/gen-<name>.mjs
+# 修改 CONFIG / ITEMS[] 后运行
+node ta-workspace/scripts/gen-<name>.mjs
+```
+
+### 批量处理
+
+参见 [process-batch.template.mjs](process-batch.template.mjs)。
+
+```bash
+cp "$SKILL_DIR/reference/process-batch.template.mjs" \
+   ta-workspace/scripts/process-<name>.mjs
+# 修改 CONFIG（特别是 skipRemoveBg）后运行
+node ta-workspace/scripts/process-<name>.mjs
+```
+
+已由生成工具验证透明的图使用 `skipRemoveBg=true`，保留透明边缘；不透明牌面/场景同样跳过去背。只有独立色幕中间图才设为 `false`，按所选色幕设置容差。
+
+### 合并精灵图
+
+参见 [build-sprite-sheet.template.mjs](build-sprite-sheet.template.mjs)。
+
+```bash
+cp "$SKILL_DIR/reference/build-sprite-sheet.template.mjs" \
+   ta-workspace/scripts/build-<name>-atlas.mjs
+# 修改 CONFIG / ORDERED_NAMES[] 后运行
+node ta-workspace/scripts/build-<name>-atlas.mjs
+```
+
+---
+
+## 5. TA Workspace：Node.js 脚本驱动
+
+### 为什么用 Node.js 而不是 bash？
+
+| 维度     | bash              | Node.js                    |
+| -------- | ----------------- | -------------------------- |
+| 语法错误 | 引号/转义陷阱多   | 标准 ES 语法，错误立即可读 |
+| 条件逻辑 | 繁琐              | if/else/switch 简洁        |
+| 错误处理 | `set -e` 容易遗漏 | try/catch 完整覆盖         |
+| 数据驱动 | 字符串拼接        | 对象数组，结构清晰         |
+| 调试     | `bash -x` 噪声大  | `console.log` 精确定位     |
+
+**结论**：超过 5 步或超过 10 个文件，始终写 Node.js 脚本。
+
+### ta-workspace 目录约定
+
+```
+ta-workspace/
+├── scripts/    ← Node.js 脚本（.mjs）
+├── logs/       ← 脚本运行日志（自动追加）
+└── tmp/        ← 临时文件（脚本完成后自动清理）
+```
+
+### 脚本模板目录
+
+| 模板                                                               | 用途                                          | 关键 CONFIG                                                   |
+| ------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------- |
+| [gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)     | 精灵图直出，自动透明或独立色幕 → sprite-split | `model`, `removeBg`, `backgroundMode`, `columns`, `BATCHES[]` |
+| [gen-batch.template.mjs](gen-batch.template.mjs)                   | 批量从零 AI 生图（reference-image 模式）      | `model`, `referenceImage`, `style`, `ITEMS[]`                 |
+| [gen-edit-variants.template.mjs](gen-edit-variants.template.mjs)   | 基图 + edit 模型生成变体                      | `baseImage`, `editModel`, `VARIANTS[]`                        |
+| [process-batch.template.mjs](process-batch.template.mjs)           | 批量去背景 / trim + resize                    | `inputDir`, `outputDir`, `skipRemoveBg`                       |
+| [build-sprite-sheet.template.mjs](build-sprite-sheet.template.mjs) | 精灵图合并 + JSON 验证                        | `processedDir`, `columns`, `ORDERED_NAMES[]`                  |
+
+每个模板均包含：CONFIG/DATA/LOGIC 三段式结构、`existsSync` 幂等跳过、`appendFileSync` 日志、try/catch 错误统计。
+
+### 什么时候用命令行，什么时候写脚本？
+
+| 场景                             | 命令行 | 脚本 |
+| -------------------------------- | ------ | ---- |
+| 单张图片处理 / 查看信息          | 是     | —    |
+| 3-5 个文件，步骤简单             | 是     | —    |
+| 10+ 个文件，相同步骤             | —      | 是   |
+| 需要条件逻辑（不同素材不同参数） | —      | 是   |
+| 需要验证中间结果                 | —      | 是   |
+| 需要幂等重跑（跳过已存在）       | —      | 是   |
+| 完整管线（生成 → 处理 → 打包）   | —      | 是   |

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

@@ -0,0 +1,296 @@
+/**
+ * validate-sprite-sheet.template.mjs
+ *
+ * 精灵图技术正确性验证脚本。
+ * TA 在 Compliance Gate 前运行，确认精灵图尺寸、帧数、通道数均符合要求。
+ *
+ * 使用方法：
+ *   cp "$SKILL_DIR/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); });