@playcraft/cli 0.1.53-beta → 0.1.54

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

@@ -1,296 +0,0 @@
-/**
- * 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-v2/.claude/skills/playcraft-image-ops/SKILL.md

@@ -1,122 +0,0 @@
----
-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`。

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

@@ -1,219 +0,0 @@
----
-name: playcraft-image-processing
-description: 可玩广告流程步骤 6。对生成的图片进行后处理：缩放、裁剪、旋转、翻转、填充、格式转换、滤镜、合成等。所有操作通过 `playcraft image` CLI 命令在沙箱本地执行，无需 backend，速度快。
-compatibility: agent,opencode
----
-
-## Skill Definition
-
-tools:
-
-- bash
-- read
-  prompt_extension: |
-  你是图像处理工程师。不得向 /project/ 写入；所有输出路径必须在 ta-workspace（技术美术角色）。
-  通过 bash 工具运行 `playcraft image <command>` CLI 命令进行图片处理，所有操作在沙箱本地执行，无需往返 backend。
-
-## 我做什么
-
-- 对生成的图片进行后处理，使其符合游戏引擎和可玩广告的规格
-- 支持：缩放、裁剪、旋转、翻转、填充边距、格式转换、灰度化、模糊、色调叠加、反色、图片合成、像素化、自动裁边
-
-## 何时用我
-
-当 `playcraft tools generate-image` 生成的图片需要进一步处理时：
-
-- 尺寸不符合纹理要求（如需 2 的幂次、特定分辨率）
-- 需要像素风效果
-- 需要旋转/镜像翻转（如左右角色复用同一张图）
-- 需要统一多帧尺寸后合并精灵图
-- 需要格式转换（png → webp 优化体积）
-- 需要裁掉透明边界、叠加合成等
-
-## 命令速查
-
-所有命令格式：`playcraft image <command> --input <路径> --output <路径> [选项]`
-
-### 几何变换
-
-```bash
-# 缩放（支持比例或指定宽高）
-playcraft image resize --input src.png --output out.png --scale 0.5
-playcraft image resize --input src.png --output out.png --width 512 --height 512 --fit contain
-
-# 裁剪（指定区域）
-playcraft image crop --input src.png --output out.png --x 0 --y 0 --width 256 --height 256
-
-# 旋转（任意角度，默认背景透明）
-playcraft image rotate --input src.png --output out.png --angle 90
-playcraft image rotate --input src.png --output out.png --angle 45 --background "#ffffff"
-
-# 镜像翻转
-playcraft image flip --input src.png --output out.png --direction horizontal
-playcraft image flip --input src.png --output out.png --direction vertical
-
-# 扩展画布/加边距（统一精灵尺寸常用）
-playcraft image pad --input src.png --output out.png --all 16
-playcraft image pad --input src.png --output out.png --top 8 --bottom 8 --left 0 --right 0
-
-# 自动裁掉透明/纯色边界
-playcraft image trim --input src.png --output out.png --threshold 10
-```
-
-### 格式与质量
-
-```bash
-# 格式转换 + 压缩质量（png/jpg/webp/avif）
-playcraft image convert --input src.png --output out.webp --quality 85
-playcraft image convert --input src.jpg --output out.png
-```
-
-### 滤镜与色彩
-
-```bash
-# 灰度化
-playcraft image grayscale --input src.png --output out.png
-
-# 高斯模糊（背景虚化等）
-playcraft image blur --input src.png --output out.png --sigma 5
-
-# 色调叠加（做角色不同颜色变体）
-playcraft image tint --input src.png --output out.png --color "#ff4400"
-
-# 反色
-playcraft image negate --input src.png --output out.png
-
-# 像素化（像素风格）
-playcraft image pixelate --input src.png --output out.png --pixel-size 8
-```
-
-### 合成
-
-```bash
-# 将一张图叠在另一张图上（居中对齐）
-playcraft image overlay --base bg.png --overlay icon.png --output out.png
-
-# 指定坐标叠加
-playcraft image overlay --base bg.png --overlay icon.png --output out.png --x 100 --y 200
-```
-
-### 语义分割（SAM3）
-
-通过 SAM3（Segment Anything Model 3）对图片进行**开放词汇语义分割**：用文字或框 prompt 精确抠出任意对象，返回 mask 和 RGBA 透明图。
-需要经由 backend 代理，首次冷启动约 15s，热启动约 5-10s。
-
-```bash
-# ── 单 prompt — 文本 ──
-# 找到图中所有"logo"区域，输出 mask + RGBA
-playcraft image segment \
-  --input ta-workspace/banner.png \
-  --text "logo" \
-  --output-dir ta-workspace/segment-out
-
-# ── 单 prompt — 框选区域 ──
-# 用 [x1,y1,x2,y2] 绝对像素坐标指定目标区域
-playcraft image segment \
-  --input ta-workspace/banner.png \
-  --boxes "[[50,100,300,400]]" \
-  --output-dir ta-workspace/segment-out
-
-# ── 多 prompt 批量（一次调用，多个目标）──
-playcraft image segment \
-  --input ta-workspace/banner.png \
-  --prompts '[{"text":"icon"},{"text":"button"},{"text":"logo"}]' \
-  --output-dir ta-workspace/segment-out
-
-# ── 调节得分阈值（默认 0.3，越低召回越多）──
-playcraft image segment \
-  --input ta-workspace/hero.png \
-  --text "character" \
-  --threshold 0.2 \
-  --output-dir ta-workspace/segment-out
-
-# ── 不需要 RGBA 抠图，只要 mask ──
-playcraft image segment \
-  --input ta-workspace/hero.png \
-  --text "character" \
-  --no-rgba \
-  --output-dir ta-workspace/segment-out
-```
-
-**输出目录结构**：
-
-```
-segment-out/
-  prompt_0_logo/
-    00_mask.png       ← 二值 mask（白色为前景）
-    00_rgba.png       ← RGBA 透明抠图
-    01_mask.png       ← 同一 prompt 的第二个实例（若有多个）
-    01_rgba.png
-  prompt_1_button/
-    00_mask.png
-    00_rgba.png
-  segment-meta.json   ← 汇总：image_size、prompts、instances count、scores、bbox
-```
-
-**使用要点**：
-
-- **冷启动**：SAM3 缩容后首次调用约 15s，命令会自动等待，无需手动 ping
-- **热启动**：模型就绪后约 5-10s 完成分割
-- **抠图直接可用**：`rgba.png` 已是透明背景，可直接用于游戏资产，无需再跑 `remove-background`
-- **多实例**：同一 prompt 可能检测到多个对象（如图中有 3 个 logo），每个实例单独输出 `00_`、`01_`…
-- **bbox 信息**：`segment-meta.json` 包含每个实例的 bbox 坐标，可用于后续裁切定位
-
-**与 remove-background 的对比**：
-
-| 场景                                               | 推荐方案                               |
-| -------------------------------------------------- | -------------------------------------- |
-| 去除纯色/渐变/棋盘格背景（AI 生成图）              | `remove-background --method floodfill` |
-| 去除复杂真实照片背景                               | `remove-background --method ai`        |
-| **精确分割特定对象**（如从 UI 截图中提取某个按钮） | `segment --text "button"`              |
-| **批量提取多个不同对象**                           | `segment --prompts '[...]'`            |
-| **需要 mask 做遮罩特效**                           | `segment`（直接输出 mask.png）         |
-
-### 背景移除
-
-支持两种方法，根据图片类型选择：
-
-```bash
-# ── floodfill（默认）— 本地执行，AI 生成素材首选 ──
-# 从边缘 flood-fill 移除纯色/渐变/棋盘格背景，前景纹理零损失
-playcraft image remove-background --input ta-workspace/hero_raw.png --output ta-workspace/hero.png
-
-# 调节容差（背景与前景颜色接近时增大）
-playcraft image remove-background --input ta-workspace/tile.png --output ta-workspace/tile.png --tolerance 40
-
-# 关闭边缘平滑（需要硬边像素风时）
-playcraft image remove-background --input ta-workspace/pixel_art.png --output ta-workspace/pixel_art.png --edge-smooth 0
-
-# ── ai — 调用 backend AI 模型，复杂背景照片用 ──
-playcraft image remove-background --input ta-workspace/photo.jpg --output ta-workspace/photo.png --method ai
-```
-
-**方法选择指南**：
-| 方法 | 适用场景 | 速度 | 纹理保真度 |
-|------|---------|------|-----------|
-| `floodfill`（默认） | AI 生成的素材（纯色/灰色/棋盘格背景） | <0.5s | 零损失 |
-| `ai` | 真实照片、复杂背景 | ~1-3s | 可能褪色 |
-
-> **注意**：`--method ai` 会调用 backend API（需要沙箱 token）；`floodfill` 完全本地执行。
-
-## 可玩广告常见规格
-
-- 纹理尺寸：建议 2 的幂次（256×256、512×512、1024×1024）
-- 像素风：`--pixel-size 8` 到 `16` 常见
-- WebP 转换：通常比 PNG 小 30–50%，可玩广告体积敏感时优先用 webp
-- 统一精灵帧尺寸：先 `resize` → 再 `sprite-sheet` 合并
-
-## 典型流程
-
-```bash
-# 生成图片 → 缩放到规格 → 转 webp 压缩
-playcraft tools generate-image --prompt "cute hero character, transparent background" --output ta-workspace/hero_raw.png
-playcraft image resize --input ta-workspace/hero_raw.png --output ta-workspace/hero_512.png --width 512 --height 512 --fit contain
-playcraft image convert --input ta-workspace/hero_512.png --output ta-workspace/hero_512.webp --quality 85
-
-# 制作角色颜色变体
-playcraft image tint --input ta-workspace/hero_512.png --output ta-workspace/hero_blue.png --color "#0055ff"
-playcraft image tint --input ta-workspace/hero_512.png --output ta-workspace/hero_red.png --color "#ff2200"
-```