@playcraft/cli 0.0.39 → 0.0.41

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); });

package/project-template/.claude/skills/playcraft-image-ops/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: playcraft-image-ops
+description: TA 图形操作生产上下文指南。按可玩广告流水线阶段（提取/标准化/变换/合成/验证）组织 playcraft image 子命令，说明 WHEN 和 WHY 而非仅 HOW。完整 CLI 参数速查表见 refs/ta-image-ops-reference.md。
+triggers: 裁剪,crop,叠图,合成,overlay,扩画布,pad,去白边,trim,旋转,rotate,翻转,flip,模糊,blur,色调,tint,灰度,grayscale,反色,negate,居中裁,等比裁,图层叠加,画布,像素级操作,图形处理,decompose-layers,图层分层,提取,extract
+---
+
+# PlayCraft 图形操作 — 生产上下文指南
+
+## 0. 在流水线中的位置
+
+所有命令均为 `playcraft image <子命令>` 格式，基于 sharp 本地处理，无需后端。
+
+```
+TA Production Pipeline:
+  Extract (从 Composite/ASR 提取)
+    -> decompose-layers (302 整图语义分层，Master Composite；见 playcraft-masking skill)
+    -> crop (ASR 网格 / 已知 bbox 的像素级裁切)
+    -> segment (SAM3 单对象蒙版，见 playcraft-masking skill)
+
+  Process (标准化处理)
+    -> trim (去除多余透明边)
+    -> resize (统一到 assetSpec 尺寸)
+    -> pad (补齐到等宽画布)
+    -> remove-background -> 见 playcraft-masking skill
+
+  Transform (变体生成)
+    -> flip horizontal (左右镜像，节省生成成本)
+    -> rotate (方向调整)
+    -> tint (色调变体 / 禁用状态)
+    -> grayscale (锁定 / 未解锁状态)
+
+  Compose (合成叠加)
+    -> overlay (多层合成：背景 + 角色 + UI)
+
+  Verify (验证)
+    -> info (检查尺寸 / 格式 / 文件大小)
+    -> convert (最终格式转换 -- 生产阶段保持 PNG)
+```
+
+---
+
+## 1. 按阶段命令速查
+
+| Stage     | Command            | One-liner                                                                         | Key Param                          |
+| --------- | ------------------ | --------------------------------------------------------------------------------- | ---------------------------------- |
+| Extract   | `decompose-layers` | `playcraft image decompose-layers --input X --output-dir ./layers --num-layers 4` | 后端 302；`--input` 宜为 HTTPS URL |
+| Extract   | `crop`             | `playcraft image crop --input X --output Y --x N --y N --width W --height H`      | x,y = 左上角原点                   |
+| Process   | `trim`             | `playcraft image trim --input X --output Y --threshold 10`                        | threshold: 0-255                   |
+| Process   | `resize`           | `playcraft image resize --input X --output Y --width W --height H`                | 或 `--scale 0.5`                   |
+| Process   | `pad`              | `playcraft image pad --input X --output Y --all 16`                               | 或 --top/bottom/left/right         |
+| Transform | `flip`             | `playcraft image flip --input X --output Y --direction horizontal`                | horizontal / vertical              |
+| Transform | `rotate`           | `playcraft image rotate --input X --output Y --angle 90`                          | 角度（顺时针），背景默认透明       |
+| Transform | `tint`             | `playcraft image tint --input X --output Y --color "#FFD700"`                     | hex 颜色值                         |
+| Transform | `grayscale`        | `playcraft image grayscale --input X --output Y`                                  | 无额外参数                         |
+| Compose   | `overlay`          | `playcraft image overlay --base BG --overlay FG --output Y --gravity center`      | 或 --x --y 精确坐标                |
+| Verify    | `info`             | `playcraft image info --input X`                                                  | --json 供脚本解析                  |
+| Verify    | `convert`          | `playcraft image convert --input X --output Y --format webp --quality 85`         | 生产阶段保持 PNG                   |
+
+**overlay gravity 值**：center(默认) / north / south / east / west / northeast / northwest / southeast / southwest。
+指定 --x + --y 时 gravity 被忽略，叠加图左上角放置在底图 (x, y) 坐标处。
+
+---
+
+## 2. 最常用配方
+
+### 配方 A：标准化精灵尺寸 (trim -> info -> pad)
+
+**场景**：AI 生成或分割提取的素材尺寸不一，需要统一到 assetSpec 指定的画布大小。
+
+```bash
+playcraft image trim --input raw_sprite.png --output /tmp/trimmed.png
+playcraft image info --input /tmp/trimmed.png --json
+# 根据 info 输出计算 pad 值：top/bottom = (目标高 - 当前高) / 2，left/right 同理
+playcraft image pad --input /tmp/trimmed.png --output assets/images/tiles/sprite_128x128.png \
+  --top 8 --bottom 8 --left 16 --right 16
+```
+
+**为什么这个顺序**：先 trim 去掉 AI 生成图的冗余透明边，再 pad 到精确尺寸。反过来做会把冗余透明边也算进画布。
+
+### 配方 B：多层合成 (overlay chain: bg -> character -> UI)
+
+**场景**：将背景、角色、UI 元素按层合成为最终画面。Layout Spec 中的 composite 通常需要这个流程。
+
+```bash
+playcraft image overlay --base assets/images/bg/background.png \
+  --overlay assets/images/character.png --output /tmp/step1.png --gravity center
+playcraft image overlay --base /tmp/step1.png \
+  --overlay assets/images/ui/cta_button.png --output assets/images/final.png --gravity south
+```
+
+**为什么逐层叠加**：overlay 每次只接受一个叠加层。从最底层开始，每一步的输出作为下一步的 base，保证 z-order 正确。
+
+### 配方 C：镜像动画帧 (flip horizontal)
+
+**场景**：已有 run_right 动画序列帧，需要 run_left。翻转比重新生成节省时间和 API 调用。
+
+```bash
+for f in assets/images/character/run_right_*.png; do
+  name=$(basename "$f" .png)
+  playcraft image flip --input "$f" \
+    --output "assets/images/character/${name/right/left}.png" \
+    --direction horizontal
+done
+```
+
+**为什么用 flip 而不重新生成**：AI 生成的镜像帧可能出现风格不一致，而 flip 保证像素级对称，且零 API 成本。
+
+---
+
+## 3. 关键注意事项
+
+- **crop 不支持 batch**：`playcraft image batch --steps` 中 crop 会报 `unsupported command`。批量裁切用 for 循环或 Node.js 脚本。
+- **生产阶段保持 PNG**：所有中间产物和最终资产用 PNG。WebP/AVIF 转换交给构建阶段 `playcraft build --convert-webp`。
+- **tint 是混合不是替换**：深色图像 tint 效果弱，需要颜色替换时用 overlay + 纯色图层。
+- **居中裁公式**：`x = (原图宽 - 目标宽) / 2`，`y = (原图高 - 目标高) / 2`（取整）。
+
+---
+
+## 4. 完整参考
+
+完整 CLI 参数速查表、所有 gravity 值、rotation 选项、滤镜命令（blur / negate）及更多组合配方：
+读取 `refs/ta-image-ops-reference.md`。