@playcraft/cli 0.0.43 → 0.0.46

package/project-template/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playcraft-audio-generation
-description: PlayCraft AI 音频生成完整指南。涵盖 SFX 音效生成、BGM 背景音乐生成（prompt 套路、时长、风格参数）、本地音频后处理（compress/fade/loop/normalize/mix），以及完整的音频管线。Designer 和 TA 在生成音频资产前必读。
+description: PlayCraft AI 音频生成完整指南。涵盖 SFX 音效生成、BGM 背景音乐生成（prompt 套路、时长、风格参数）、本地音频后处理（compress/fade/loop/normalize/mix），以及完整的音频管线。Artist 和 TA 在生成音频资产前必读。
 triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
 ---
 
@@ -67,34 +67,34 @@ playcraft tools generate-sfx \
 
 ```javascript
 // ta-workspace/scripts/gen-sfx.mjs
-import { execSync } from "child_process";
-import { existsSync } from "fs";
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
 
-const OUTPUT_DIR = "assets/audio/sfx";
+const OUTPUT_DIR = 'assets/audio/sfx';
 const SFX_LIST = [
   {
-    name: "coin",
-    prompt: "coin collect chime, arcade game, bright metallic, 0.5 seconds",
+    name: 'coin',
+    prompt: 'coin collect chime, arcade game, bright metallic, 0.5 seconds',
     duration: 0.5,
   },
   {
-    name: "click",
-    prompt: "button click, game UI, soft satisfying, short",
+    name: 'click',
+    prompt: 'button click, game UI, soft satisfying, short',
     duration: 0.3,
   },
   {
-    name: "win",
-    prompt: "victory fanfare, casual mobile game, cheerful upbeat jingle",
+    name: 'win',
+    prompt: 'victory fanfare, casual mobile game, cheerful upbeat jingle',
     duration: 2.0,
   },
   {
-    name: "fail",
-    prompt: "fail sound, game over, descending tone, simple",
+    name: 'fail',
+    prompt: 'fail sound, game over, descending tone, simple',
     duration: 1.5,
   },
   {
-    name: "jump",
-    prompt: "jump sound, platform game, light spring bounce",
+    name: 'jump',
+    prompt: 'jump sound, platform game, light spring bounce',
     duration: 0.4,
   },
 ];
@@ -108,7 +108,7 @@ for (const sfx of SFX_LIST) {
   console.log(`[GEN] ${sfx.name}...`);
   execSync(
     `playcraft tools generate-sfx --prompt "${sfx.prompt}" --output "${output}" --duration ${sfx.duration}`,
-    { stdio: "inherit" },
+    { stdio: 'inherit' },
   );
 }
 ```

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

@@ -80,22 +80,22 @@ grep -r "ExitApi.exit" game/ --include="*.js" --include="*.ts"
 // 多平台兼容 CTA 处理
 function handleCTAClick() {
   // Meta / Facebook
-  if (typeof FbPlayableAd !== "undefined") {
+  if (typeof FbPlayableAd !== 'undefined') {
     FbPlayableAd.onCTAClick();
     return;
   }
   // Google Ads / AdMob
-  if (typeof ExitApi !== "undefined") {
+  if (typeof ExitApi !== 'undefined') {
     ExitApi.exit();
     return;
   }
   // AppLovin / IronSource / 其他
-  if (typeof mraid !== "undefined") {
+  if (typeof mraid !== 'undefined') {
     mraid.open(STORE_URL);
     return;
   }
   // Fallback
-  window.open(STORE_URL, "_blank");
+  window.open(STORE_URL, '_blank');
 }
 ```
 
@@ -216,7 +216,7 @@ playcraft build-all . \
 
 - 不要先用 `playcraft image convert --format webp` 手动转换，再用 `--convert-webp` 构建（双重转换）
 - 不要对同一图片多次运行 `--compress-images`（每次都会损失质量）
-- 生产阶段（Designer/TA）产出应保持 PNG 格式，优化阶段统一转换
+- 生产阶段（Artist/TA）产出应保持 PNG 格式，优化阶段统一转换
 
 ---
 

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

@@ -137,7 +137,7 @@ playcraft tools generate-image \
 
 ### Master Composite（MC）模型白名单
 
-Designer 生成 MC 时**不得**套用上方通用决策树里的 gemini / flux / hy-image 等——MC 只允许：
+Artist 生成 MC 时**不得**套用上方通用决策树里的 gemini / flux / hy-image 等——MC 只允许：
 
 | 允许                       | 禁止（MC）                                          |
 | -------------------------- | --------------------------------------------------- |
@@ -258,17 +258,17 @@ playcraft image overlay \
 
 ---
 
-## 3.1 ASR 专用分支（Designer · Gate #2b）
+## 3.1 ASR 专用分支（Artist · ring 3 build）
 
 > **Read `playcraft-asset-state-sheet` Skill first.** ASR 是制作期参考板，不是 runtime 透明资产。
 
-| 阶段              | Designer                              | TA                            |
+| 阶段              | Artist                                | TA                            |
 | ----------------- | ------------------------------------- | ----------------------------- |
 | ASR 整图          | **opaque**（灰底或统一色幕）— 正常    | —                             |
 | ASR 格内元素      | **isolated** + 按色幕矩阵选 cell 背景 | `crop` 后 `remove-background` |
-| remove-background | **禁止** — Designer 不做              | production Wave 2             |
+| remove-background | **禁止** — Artist 不做                | production Wave 2             |
 
-**Designer ASR prompt 要点**：
+**Artist ASR prompt 要点**：
 
 1. Sheet canvas：`solid flat #808080` 或整板统一绿幕（非渐变）
 2. 每格：`ONE isolated element, centered, NO white box, NO scene, NO ground shadow`

package/project-template/.claude/skills/playcraft-image-generation/reference/compare-style.template.mjs

@@ -2,7 +2,7 @@
  * compare-style.template.mjs
  *
  * 色彩风格一致性定量检查脚本。
- * 用途：TA Micro-Batch Validation 辅助工具，对 AI 补全素材与 Designer 样本做客观色彩比较。
+ * 用途：TA Micro-Batch Validation 辅助工具，对 AI 补全素材与 Artist 样本做客观色彩比较。
  *
  * 使用方法：
  *   cp .claude/skills/playcraft-image-generation/reference/compare-style.template.mjs \
@@ -28,7 +28,7 @@ import path from 'path';
 // ─── CONFIG ───────────────────────────────────────────────────────────────────
 
 const CONFIG = {
-  /** Designer 样本图（风格基准） */
+  /** Artist 样本图（风格基准） */
   referenceImage: 'assets/images/tiles/tile_sample_1.png',
 
   /** 要检查的 TA 补全素材目录或文件列表 */
@@ -37,7 +37,7 @@ const CONFIG = {
   /** 只检查该目录下的哪些文件（glob 后缀匹配） */
   targetGlob: '.png',
 
-  /** 排除文件名包含这些关键词的文件（Designer 样本自身） */
+  /** 排除文件名包含这些关键词的文件（Artist 样本自身） */
   excludeKeywords: ['sample', 'concept', 'selected', 'storyboard'],
 
   /** 日志输出路径 */
@@ -129,7 +129,7 @@ function weightedChannelDiff(colorsA, colorsB, channel) {
  *   色相距离 < 20°  且 明度/饱和度差 < 0.15  → 4 分
  *   色相距离 < 30°  且 明度/饱和度差 < 0.20  → 3 分（勉强可接受）
  *   色相距离 < 45°  且 明度/饱和度差 < 0.30  → 2 分（需调整）
- *   其他                                       → 1 分（停止，提问 Designer）
+ *   其他                                       → 1 分（停止，提问 Artist）
  */
 function calcScore(hueDist, lightDiff, satDiff) {
   const channelOk = Math.max(lightDiff, satDiff);
@@ -235,7 +235,7 @@ async function main() {
     `  平均评分:   ${avgScore.toFixed(1)} / 5`,
     `  低于阈值数: ${failCount}（阈值 ${CONFIG.warnThreshold}）`,
     failCount > 0
-      ? `  ⚠️  建议：停止低分文件类型的批量生产，调整生成参数或向 Designer 提问 ICP`
+      ? `  ⚠️  建议：停止低分文件类型的批量生产，调整生成参数或向 Artist 提问 ICP`
       : `  ✅  全部通过，可继续批量生产`,
     '',
   ].join('\n');

package/project-template/.claude/skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs

@@ -15,8 +15,21 @@
 //   3. node ta-workspace/scripts/gen-<name>-sprite.mjs
 // ============================================================
 
-import { execSync } from 'child_process';
-import { existsSync, mkdirSync, appendFileSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { existsSync, mkdirSync, appendFileSync, copyFileSync } from 'fs';
+
+/**
+ * Run the `playcraft` CLI with an argv ARRAY (never a shell string), so prompts
+ * and paths containing $(), backticks, quotes, spaces, backslashes, etc. are
+ * passed verbatim and cannot be reinterpreted by a shell.
+ *   - capture:true → returns stdout (utf8); otherwise inherits stdio.
+ */
+function playcraft(args, { capture = false, timeout } = {}) {
+  return execFileSync('playcraft', args, {
+    ...(capture ? { encoding: 'utf8' } : { stdio: 'inherit' }),
+    ...(timeout ? { timeout } : {}),
+  });
+}
 
 // ============ CONFIG — 修改这里 ============
 const CONFIG = {
@@ -66,6 +79,16 @@ const CONFIG = {
    * false → 卡牌/UI 面板等矩形元素：直接 resize，不去背景
    */
   removeBg: true,
+
+  /**
+   * 切分单元尺寸（像素）。留空（null）= 自动按精灵图实际像素尺寸 ÷ 网格推导（推荐）。
+   * 仅当模型输出的格子并非均匀均分、需要手动指定时才填写。
+   * ⚠️ 不要写死 256：4K 精灵图按 256 切分会严重错位。
+   */
+  cellWidth: null,
+  cellHeight: null,
+  /** 帧间距（像素），默认 0 */
+  padding: 0,
 };
 
 // ============ DATA — 分批定义元素 ============
@@ -98,6 +121,23 @@ const BATCHES = [
  * 根据 items 列表构建精灵图网格 prompt
  * 关键词组合让 gpt-image-2 理解"网格布局"意图
  */
+/**
+ * 读取精灵图实际像素尺寸（用于自动推导切分单元尺寸）。
+ * 失败返回 null，由调用方决定是否中止该批次。
+ */
+function readSheetDims(sheetPath) {
+  try {
+    const out = playcraft(['image', 'info', '--input', sheetPath, '--json'], { capture: true });
+    const meta = JSON.parse(out.slice(out.indexOf('{')));
+    if (typeof meta.width === 'number' && typeof meta.height === 'number') {
+      return { width: meta.width, height: meta.height };
+    }
+  } catch {
+    // fall through → null
+  }
+  return null;
+}
+
 function buildSpriteSheetPrompt(items, columns, style, removeBg) {
   const actualRows = Math.ceil(items.length / columns);
   const cellDescs = items.map((item, i) => {
@@ -151,18 +191,19 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
   } else {
     log(`[GEN-SHEET ] (${bi + 1}/${BATCHES.length}) Generating ${batch.sheetName} (${batch.items.length} elements)`);
     const prompt = buildSpriteSheetPrompt(batch.items, CONFIG.columns, CONFIG.style, CONFIG.removeBg);
-    const promptEscaped = prompt.replace(/"/g, '\\"');
-
-    const cmd =
-      `playcraft tools generate-image` +
-      ` --prompt "${promptEscaped}"` +
-      ` --output "${sheetPath}"` +
-      ` --aspect-ratio ${CONFIG.aspectRatio}` +
-      ` --image-model "${CONFIG.model}"` +
-      ` --timeout 240`;
 
     try {
-      execSync(cmd, { stdio: 'inherit', timeout: 300_000 });
+      playcraft(
+        [
+          'tools', 'generate-image',
+          '--prompt', prompt,
+          '--output', sheetPath,
+          '--aspect-ratio', CONFIG.aspectRatio,
+          '--image-model', CONFIG.model,
+          '--timeout', '240',
+        ],
+        { timeout: 300_000 },
+      );
       log(`[OK-SHEET  ] ${batch.sheetName}`);
     } catch (e) {
       log(`[FAIL-SHEET] ${batch.sheetName}: ${e.message?.slice(0, 200)}`);
@@ -181,16 +222,47 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
     continue;
   }
 
-  log(`[SPLIT     ] Splitting ${batch.sheetName} (${CONFIG.columns}×${actualRows})`);
-  const splitCmd =
-    `playcraft image sprite-split` +
-    ` --input "${sheetPath}"` +
-    ` --output-dir "ta-workspace/tmp/${batch.sheetName}"` +
-    ` --rows ${actualRows}` +
-    ` --columns ${CONFIG.columns}`;
+  // 切分单元尺寸：优先用 CONFIG 显式值；否则按精灵图实际像素尺寸 ÷ 网格自动推导。
+  // ⚠️ 绝不写死 256——4K 精灵图按 256 切分会严重错位（test11 类事故）。
+  const padding = CONFIG.padding ?? 0;
+  let cellWidth = CONFIG.cellWidth;
+  let cellHeight = CONFIG.cellHeight;
+  if (cellWidth == null || cellHeight == null) {
+    const dims = readSheetDims(sheetPath);
+    if (!dims) {
+      log(
+        `[FAIL-SPLIT] ${batch.sheetName}: 无法读取精灵图尺寸，请在 CONFIG 显式设置 cellWidth/cellHeight`,
+      );
+      failedBatches++;
+      continue;
+    }
+    // 去掉帧间距后按网格均分
+    cellWidth ??= Math.floor((dims.width - padding * (CONFIG.columns - 1)) / CONFIG.columns);
+    cellHeight ??= Math.floor((dims.height - padding * (actualRows - 1)) / actualRows);
+    log(
+      `[CELL-SIZE ] ${batch.sheetName}: sheet ${dims.width}×${dims.height} → cell ${cellWidth}×${cellHeight} (grid ${CONFIG.columns}×${actualRows}, padding ${padding})`,
+    );
+  }
+  if (!(cellWidth > 0 && cellHeight > 0)) {
+    log(`[FAIL-SPLIT] ${batch.sheetName}: 推导出的 cell 尺寸非法 (${cellWidth}×${cellHeight})`);
+    failedBatches++;
+    continue;
+  }
+
+  log(`[SPLIT     ] Splitting ${batch.sheetName} (${CONFIG.columns}×${actualRows}, cell ${cellWidth}×${cellHeight})`);
+  const splitDir = `ta-workspace/tmp/${batch.sheetName}`;
 
   try {
-    execSync(splitCmd, { stdio: 'inherit' });
+    playcraft([
+      'image', 'sprite-split',
+      '--input', sheetPath,
+      '--output-dir', splitDir,
+      '--rows', String(actualRows),
+      '--columns', String(CONFIG.columns),
+      '--frame-width', String(cellWidth),
+      '--frame-height', String(cellHeight),
+      '--padding', String(padding),
+    ]);
   } catch (e) {
     log(`[FAIL-SPLIT] ${batch.sheetName}: ${e.message?.slice(0, 200)}`);
     failedBatches++;
@@ -198,33 +270,50 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
   }
 
   // ── Step 3: 重命名（+可选绿幕去背景）切分结果到最终位置 ─────────
+  // 任何缺帧 / 处理失败都视为该批次失败（FAIL，不是 WARN）：一个不完整的
+  // 批次绝不能被报成 OK-BATCH，否则下游会拿到缺图的资产集。
   log(`[RENAME    ] Renaming ${batch.items.length} cells${CONFIG.removeBg ? ' + remove-background' : ''}`);
+  let processedOk = 0;
+  let batchFailed = false;
   for (let j = 0; j < batch.items.length; j++) {
     const item = batch.items[j];
     const row = Math.floor(j / CONFIG.columns);
     const col = j % CONFIG.columns;
     // sprite-split 默认命名：frame_r{row}_c{col}.png（0-indexed）
-    const srcPath = `ta-workspace/tmp/${batch.sheetName}/frame_r${row}_c${col}.png`;
+    const srcPath = `${splitDir}/frame_r${row}_c${col}.png`;
     const dstPath = `${CONFIG.outputDir}/${item.name}.png`;
 
     if (!existsSync(srcPath)) {
-      log(`[WARN] Expected cell not found: ${srcPath} (index ${j} out of ${batch.items.length})`);
+      log(`[FAIL-CELL ] Expected cell not found: ${srcPath} (item ${item.name}, index ${j}/${batch.items.length})`);
+      batchFailed = true;
       continue;
     }
     try {
       if (CONFIG.removeBg) {
         // 绿幕去背景（tolerance 25 适合纯绿色 #00FF00 背景）
-        execSync(`playcraft image remove-background --input "${srcPath}" --output "${dstPath}" --tolerance 25`);
+        playcraft([
+          'image', 'remove-background',
+          '--input', srcPath,
+          '--output', dstPath,
+          '--tolerance', '25',
+        ]);
       } else {
-        execSync(`cp "${srcPath}" "${dstPath}"`);
+        copyFileSync(srcPath, dstPath);
       }
+      processedOk++;
     } catch (e) {
-      log(`[WARN] Failed to process ${srcPath} → ${dstPath}: ${e.message?.slice(0, 80)}`);
+      log(`[FAIL-CELL ] Failed to process ${srcPath} → ${dstPath}: ${e.message?.slice(0, 120)}`);
+      batchFailed = true;
     }
   }
 
-  log(`[OK-BATCH  ] (${bi + 1}/${BATCHES.length}) ${batch.sheetName} → ${batch.items.length} files`);
-  doneBatches++;
+  if (batchFailed) {
+    log(`[FAIL-BATCH] (${bi + 1}/${BATCHES.length}) ${batch.sheetName} → only ${processedOk}/${batch.items.length} cells OK (see FAIL-CELL above)`);
+    failedBatches++;
+  } else {
+    log(`[OK-BATCH  ] (${bi + 1}/${BATCHES.length}) ${batch.sheetName} → ${batch.items.length} files`);
+    doneBatches++;
+  }
 }
 
 log(`\n=== Complete: Done=${doneBatches} Failed=${failedBatches}/${BATCHES.length} batches ===`);

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

@@ -268,7 +268,7 @@ playcraft tools generate-image \
 
 > 可玩广告中高频出现的界面元素。这些素材需要**透明背景**（独立叠加在游戏画面上），且必须配合 60-30-10 色彩法则——CTA 按钮颜色必须是画面中唯一出现该颜色的地方。
 >
-> 注意：`figer_icon.aiimage`、`win_result_panel.aiimage` 等 atom Skills 提供了带参考图的生成配方，PM `playcraft skills match` 能匹配到时优先使用。本节模板用于无对应 atom Skill 的场景。
+> 注意：`figer_icon.aiimage`、`win_result_panel.aiimage` 等 atom Skills 提供了带参考图的生成配方，Game Designer `playcraft skills match` 能匹配到时优先使用。本节模板用于无对应 atom Skill 的场景。
 
 ### 🟠 CTA 按钮（Call-to-Action Button）
 

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

@@ -0,0 +1,219 @@
+---
+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"
+```