@playcraft/cli 0.1.36-beta1 → 0.1.37-beta

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

@@ -1,7 +1,7 @@
 // ============================================================
-// gen-batch-sprite.template.mjs — 精灵图直出脚本模板
+// gen-batch-sprite.template.mjs — gpt-image-2 精灵图直出脚本模板
 //
-// 核心原则：一次 API (Application Programming Interface, 应用程序编程接口) 调用生成包含多个元素的
+// 核心原则：让 gpt-image-2 一次 API 调用直接生成包含多个元素的
 // 网格精灵图，然后用 sprite-split 切分。比逐个生成效率高 N 倍。
 //
 // 适用场景：
@@ -34,11 +34,11 @@ function playcraft(args, { capture = false, timeout } = {}) {
 // ============ CONFIG — 修改这里 ============
 const CONFIG = {
   /**
-   * 使用 list-image-models 核实本次模型；默认示例为 Image 2.5。
-   * 用户或制作流程锁定其他模型时填写实际 provider/model。
-   * 请求使用命令行默认等待时间，不在脚本中提前杀死仍在运行的请求。
+   * 精灵图直出模型：永远用 gpt-image-2（图像理解 + 布局能力最强）
+   * mulerouter 质量更高（建议作为主模型），iegg 更快（备用）
+   * 注意：精灵图生成比单图慢，通常需要 90-150s，timeout 设 240 以上
    */
-  model: 'iegg-litellm/gpt-image-2.5-sunburst',
+  model: 'mulerouter/gpt-image-2',
 
   /**
    * 每批精灵图的列数
@@ -64,20 +64,21 @@ const CONFIG = {
   /**
    * 通用风格描述（追加到每个批次 prompt 末尾）
    *
-   * 只填写主体风格与构图，源图背景由下方流程选择。
-   * 卡牌白色牌面属于主体，应在 items.desc 中描述并设 removeBg=false。
+   * 元素需要透明背景（独立元素：角色/车/道具/图标）→ 绿幕策略：
+   *   style: 'flat 2D illustration, isolated on solid bright green #00FF00 background, centered, no shadow'
+   *   removeBg: true  （切分后逐帧去背景）
+   *
+   * 元素本身就是矩形（卡牌/棋子/UI 面板）→ 白底策略：
+   *   style: 'flat 2D, white background, no shadow, no drop shadow, clean edges'
+   *   removeBg: false
    */
-  style: 'flat 2D illustration, isolated subjects, centered, no shadow',
+  style: 'flat 2D illustration, isolated on solid bright green #00FF00 background, centered, no shadow',
   /**
-   * 最终是否需要透明：true 为独立元素，false 为不透明牌面/场景。
-   * automatic：整板由工具交付透明，切分后保留，不重复去背。
-   * chroma：保留色幕中间图，切分后逐格去背；仅限主文第 3 节明确选择的流程。
+   * 切分后是否对每帧执行 remove-background（绿幕去背景）
+   * true  → 独立元素（需透明通道）：remove-background --tolerance 25
+   * false → 卡牌/UI 面板等矩形元素：直接 resize，不去背景
    */
   removeBg: true,
-  backgroundMode: 'automatic',
-  /** 独立色幕才使用；按主体颜色选择，金/黄/橙/绿用蓝幕，蓝/紫用绿幕。 */
-  chromaColor: '#00FF00',
-  chromaTolerance: 25,
 
   /**
    * 切分单元尺寸（像素）。留空（null）= 自动按精灵图实际像素尺寸 ÷ 网格推导（推荐）。
@@ -118,7 +119,7 @@ const BATCHES = [
 // ============ 精灵图 Prompt 构建器 ============
 /**
  * 根据 items 列表构建精灵图网格 prompt
- * 描述网格布局，避免重绘边框或格子标签。
+ * 关键词组合让 gpt-image-2 理解"网格布局"意图
  */
 /**
  * 读取精灵图实际像素尺寸（用于自动推导切分单元尺寸）。
@@ -137,7 +138,7 @@ function readSheetDims(sheetPath) {
   return null;
 }
 
-function buildSpriteSheetPrompt(items, columns, config) {
+function buildSpriteSheetPrompt(items, columns, style, removeBg) {
   const actualRows = Math.ceil(items.length / columns);
   const cellDescs = items.map((item, i) => {
     const col = (i % columns) + 1;
@@ -145,13 +146,10 @@ function buildSpriteSheetPrompt(items, columns, config) {
     return `[Row${row},Col${col}]: ${item.desc}`;
   }).join('; ');
 
-  // Image 2.5 由后端组装背景；其他模型首次请求需明确单一干净底色。
-  const modelId = config.model.trim().split('/').at(-1);
-  const nativeBackground = /^gpt-image-2\.5(?:$|-)/.test(modelId);
-  const bgInstruction = !config.removeBg ? '' : config.backgroundMode === 'chroma'
-    ? `Each element isolated on a uniform solid ${config.chromaColor} background, no shadow, no gradient background.`
-    : nativeBackground ? ''
-      : 'Render all foreground elements on a uniform solid pure white background for subsequent background removal. Preserve all elements, text, white details, colors and style.';
+  // 绿幕模式强制在 prompt 里明确背景色，避免模型用白底
+  const bgInstruction = removeBg
+    ? 'Each element isolated on solid bright green #00FF00 background, no shadow, no gradient background.'
+    : 'Each element on clean white background.';
 
   return [
     `Sprite sheet grid layout, ${columns} columns × ${actualRows} rows.`,
@@ -159,19 +157,13 @@ function buildSpriteSheetPrompt(items, columns, config) {
     bgInstruction,
     `Grid layout, uniform cell size, equal spacing, elements perfectly centered in each cell.`,
     `No borders between cells, no labels, no numbers on cells.`,
-    config.style,
-  ].filter(Boolean).join(' ');
+    style,
+  ].join(' ');
 }
 
 // ============ LOGIC — 通常不需要修改 ============
 
 const LOG_FILE = 'ta-workspace/logs/gen-batch-sprite.log';
-if (!['automatic', 'chroma'].includes(CONFIG.backgroundMode)) {
-  throw new Error('backgroundMode must be automatic or chroma.');
-}
-if (CONFIG.backgroundMode === 'chroma' && !/^#[\da-f]{6}$/i.test(CONFIG.chromaColor)) {
-  throw new Error('chromaColor must be one six-digit hex color.');
-}
 mkdirSync(CONFIG.sheetDir, { recursive: true });
 mkdirSync(CONFIG.outputDir, { recursive: true });
 mkdirSync('ta-workspace/logs', { recursive: true });
@@ -198,7 +190,7 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
     log(`[SKIP-SHEET] (${bi + 1}/${BATCHES.length}) ${batch.sheetName} already exists`);
   } else {
     log(`[GEN-SHEET ] (${bi + 1}/${BATCHES.length}) Generating ${batch.sheetName} (${batch.items.length} elements)`);
-    const prompt = buildSpriteSheetPrompt(batch.items, CONFIG.columns, CONFIG);
+    const prompt = buildSpriteSheetPrompt(batch.items, CONFIG.columns, CONFIG.style, CONFIG.removeBg);
 
     try {
       playcraft(
@@ -208,9 +200,9 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
           '--output', sheetPath,
           '--aspect-ratio', CONFIG.aspectRatio,
           '--image-model', CONFIG.model,
-          CONFIG.removeBg && CONFIG.backgroundMode === 'automatic'
-            ? '--remove-background' : '--no-remove-background',
+          '--timeout', '240',
         ],
+        { timeout: 300_000 },
       );
       log(`[OK-SHEET  ] ${batch.sheetName}`);
     } catch (e) {
@@ -277,11 +269,10 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
     continue;
   }
 
-  // ── Step 3: 保留自动透明结果；独立色幕才逐格去背 ────────────────
+  // ── Step 3: 重命名（+可选绿幕去背景）切分结果到最终位置 ─────────
   // 任何缺帧 / 处理失败都视为该批次失败（FAIL，不是 WARN）：一个不完整的
   // 批次绝不能被报成 OK-BATCH，否则下游会拿到缺图的资产集。
-  const removeCellBackground = CONFIG.removeBg && CONFIG.backgroundMode === 'chroma';
-  log(`[RENAME    ] Renaming ${batch.items.length} cells${removeCellBackground ? ' + remove-background' : ''}`);
+  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++) {
@@ -298,13 +289,13 @@ for (let bi = 0; bi < BATCHES.length; bi++) {
       continue;
     }
     try {
-      if (removeCellBackground) {
-        // 只处理独立色幕，保留常规工具已经交付的透明边缘。
+      if (CONFIG.removeBg) {
+        // 绿幕去背景（tolerance 25 适合纯绿色 #00FF00 背景）
         playcraft([
           'image', 'remove-background',
           '--input', srcPath,
           '--output', dstPath,
-          '--tolerance', String(CONFIG.chromaTolerance),
+          '--tolerance', '25',
         ]);
       } else {
         copyFileSync(srcPath, dstPath);

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

@@ -1,5 +1,5 @@
 // ============================================================
-// gen-batch.template.mjs — 批量 AI (Artificial Intelligence, 人工智能) 生图脚本模板
+// gen-batch.template.mjs — 批量 AI 生图脚本模板
 // 用途：从零批量生成一组风格一致的素材（reference-image 模式）
 //
 // 使用方式：
@@ -8,18 +8,22 @@
 //   3. node ta-workspace/scripts/gen-<name>.mjs
 // ============================================================
 
-import { execFileSync } from 'child_process';
+import { execSync } from 'child_process';
 import { existsSync, mkdirSync, appendFileSync } from 'fs';
 
 // ============ CONFIG — 修改这里 ============
 const CONFIG = {
   /**
    * 生图模型。
-   * 先 list-image-models，再填写本次实际模型；普通素材优先 Image 2.5。
-   * 用户或制作流程锁定其他模型时保留其选择。
-   * 参考图要求模型支持 text+image 或 image→image。
+   * - Phase 1 概念图（追求质量）：用 gpt-image-2
+   *   model: 'iegg-litellm/gpt-image-2'
+   * - Phase 2 批量（reference-image 一致性）：用 google/，更稳定
+   *   model: 'google/gemini-3.1-flash-image-preview'
+   *
+   * 后端按优先级自动 fallback 多个 provider，无需手动指定 provider。
+   * text+image CAPABILITY 的模型才支持 --reference-image
    */
-  model: 'iegg-litellm/gpt-image-2.5-sunburst',
+  model: 'google/gemini-3.1-flash-image-preview',
   /** 概念图路径（确认过风格的样本，所有后续图的参考来源） */
   referenceImage: 'assets/images/concept/approved_sample.png',
   /** 输出目录 */
@@ -28,11 +32,9 @@ const CONFIG = {
   aspectRatio: '1:1',
   /**
    * 统一风格描述（从 design-brief.md 复制，粘贴到每个 prompt 末尾）
-   * 示例："flat 2D icon, vibrant colors, clean edges, no shadow"
+   * 示例："flat 2D icon, vibrant colors, clean edges, white background, no shadow"
    */
   style: '<从 design-brief 复制的统一风格描述>',
-  /** 最终透明设 true；完整场景或不透明牌面设 false。独立色幕使用精灵图模板。 */
-  removeBackground: true,
 };
 // ============ DATA — 定义要生成的素材列表 ============
 const ITEMS = [
@@ -70,17 +72,17 @@ for (let i = 0; i < ITEMS.length; i++) {
 
   log(`[GEN ] (${i + 1}/${ITEMS.length}) ${item.name}`);
 
-  const nativeBackground = /^gpt-image-2\.5(?:$|-)/.test(CONFIG.model.trim().split('/').at(-1));
-  const sourceBackground = CONFIG.removeBackground && !nativeBackground
-    ? 'on a uniform solid pure white background for subsequent background removal' : '';
-  const prompt = [item.desc, CONFIG.style, sourceBackground].filter(Boolean).join('. ');
-  const args = ['tools', 'generate-image', '--prompt', prompt, '--output', outPath,
-    '--aspect-ratio', CONFIG.aspectRatio, '--image-model', CONFIG.model,
-    CONFIG.removeBackground ? '--remove-background' : '--no-remove-background'];
-  if (CONFIG.referenceImage) args.push('--reference-image', CONFIG.referenceImage);
+  const promptEscaped = `${item.desc}. ${CONFIG.style}`.replace(/"/g, '\\"');
+  const cmd =
+    `playcraft tools generate-image` +
+    ` --prompt "${promptEscaped}"` +
+    ` --output "${outPath}"` +
+    ` --aspect-ratio ${CONFIG.aspectRatio}` +
+    ` --reference-image "${CONFIG.referenceImage}"` +
+    ` --image-model "${CONFIG.model}"`;
 
   try {
-    execFileSync('playcraft', args, { stdio: 'inherit' });
+    execSync(cmd, { stdio: 'inherit', timeout: 120_000 });
     done++;
     log(`[OK  ] ${item.name}`);
   } catch (e) {

package/project-templates/threejs/.claude/skills/playcraft-image-generation/reference/process-batch.template.mjs

@@ -8,9 +8,10 @@
 //   3. node ta-workspace/scripts/process-<name>.mjs
 //
 // 背景处理决策（修改 CONFIG.skipRemoveBg 前请阅读）：
-//   - 常规工具已验证透明 / 不透明牌面或场景 → skipRemoveBg = true（默认）
-//   - 明确选择的独立色幕中间图 → skipRemoveBg = false，按主文第 3 节选择色幕
-//     生成中间图时用 --no-remove-background，最终去背后验证透明边缘
+//   - 独立元素（角色/道具/图标）需透明背景 → skipRemoveBg = false（默认）
+//     建议生图时 prompt 加 "on solid bright green #00FF00 background, isolated"
+//   - 卡牌/棋子/UI面板（矩形本体不需透明）→ skipRemoveBg = true
+//     生图时 prompt 加 "flat 2D, no shadow, no 3D effect, clean edges"
 // ============================================================
 
 import { execSync } from 'child_process';
@@ -31,10 +32,10 @@ const CONFIG = {
   targetH: 128,
   /**
    * 跳过去背景步骤
-   * - true（默认）：保留已验证透明的结果或不透明牌面/场景，不重复去背
-   * - false：仅对独立色幕中间图执行 remove-background
+   * - false（默认）：执行 remove-background（绿幕素材/独立元素）
+   * - true：跳过，只做 trim + resize（卡牌/棋子等矩形本体素材）
    */
-  skipRemoveBg: true,
+  skipRemoveBg: false,
   /**
    * floodfill 容差（0–255）
    * 绿幕背景建议 25；默认白背景可用 15

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

@@ -1,23 +1,21 @@
 # Image Generation Prompt Cookbook
 
-> 适用于 PlayCraft CLI (Command-Line Interface, 命令行工具) `playcraft tools generate-image` 及沙箱生图工具。
+> 适用于 PlayCraft CLI `playcraft tools generate-image`。
 > 所有模型均适用；gpt-image-2 类模型对英文 prompt 理解最准确，优先写英文。
 
-透明交付通过 `removeBackground: true` / `--remove-background` 或目标字段配置表达。下方常规前景模板描述主体、文字、风格、构图与材质；源图背景遵循主文第 2 节：Image 2.5 由后端组装，不追加背景后缀；明确选用其他模型时，首次请求需追加单一 `on a uniform solid pure white background for subsequent background removal`。不要同时要求透明、白底与色幕。完整场景可以描述背景内容，矩形本体的白色牌面也应保留。独立色幕流程见主文第 3 节，中间图必须关闭自动去背。
-
 ---
 
 ## 一、Prompt 万能公式
 
 ```
-[主体描述] + [风格/介质] + [构图/视角] + [场景内容（如需要）] + [质量修饰词]
+[主体描述] + [风格/介质] + [构图/视角] + [背景] + [质量修饰词]
 ```
 
 **示例**：
 
 ```
 A golden sword icon, flat 2D vector style, centered composition,
-isolated subject, clean crisp edges, game UI asset, high quality
+white background, clean crisp edges, game UI asset, high quality
 ```
 
 ---
@@ -28,13 +26,12 @@ isolated subject, clean crisp edges, game UI asset, high quality
 
 ```
 A [物品名] icon, flat 2D vector illustration, bold outlines,
-vibrant colors, centered composition, isolated subject,
+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`
-- 需要透明交付时传 `removeBackground: true` / `--remove-background`。
 
 ### 🃏 卡牌 / 棋子 / 方块（Rectangular Tiles）
 
@@ -53,11 +50,12 @@ sharp clean edges, centered on white background
 ```
 A [角色描述] character, full body visible, game sprite style,
 [艺术风格: pixel art / cartoon / chibi / realistic],
-isolated subject,
+isolated on solid bright green #00FF00 background,
 centered, facing forward / side view, clean silhouette
 ```
 
-- 需要透明交付 → `removeBackground: true` / `--remove-background`，按主文第 2 节准备源图背景，由后端去背并完成验收。
+- 需要透明背景 → **绿幕策略**，prompt 加 `"on solid bright green #00FF00 background, isolated"`
+- 后处理：`remove-background --tolerance 25`
 
 ### 🌄 场景背景（Backgrounds）
 
@@ -122,7 +120,7 @@ Grid layout, equal cell size, no borders between cells. Bold black ink for spade
 **图标集示例**（一批 9 个图标）：
 
 ```
-Sprite sheet grid, 3 columns × 3 rows. Flat 2D game icon style, isolated subjects.
+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.
@@ -131,17 +129,17 @@ Each icon centered in its cell, bold outlines, vibrant colors, no shadow.
 
 **背景选择（重要！）**：
 
-| 素材类型                            | 交付要求                                         | 切分后处理                       |
-| ----------------------------------- | ------------------------------------------------ | -------------------------------- |
-| 独立元素（角色/车/道具/图标）需透明 | `--remove-background`，按主文第 2 节准备源图背景 | 保留透明通道，验证每格前景与边缘 |
-| 卡牌/棋子/UI 面板（矩形本体）       | `--no-remove-background`，保留白色牌面           | 直接 resize，不去背景            |
+| 素材类型                            | 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)：`backgroundMode='automatic'` 为常规流程，`removeBg` 表示最终是否透明。独立色幕需显式设 `backgroundMode='chroma'`、所选模型和色幕颜色；脚本关闭整板自动去背，切分后逐格去背。
+- 模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)
 
 ---
 
@@ -185,7 +183,7 @@ gpt-image-2 是目前质量最高的文生图模型，prompt 套路略有不同
 - **英文 prompt 效果最佳**，中文理解也不错但英文更稳定
 - 对**复杂场景**、**细节描述**处理能力远超其他模型
 - 支持**图生图 edit 模式**（传 `--reference-image`），局部编辑能力强
-- 不支持原生透明 PNG (Portable Network Graphics, 便携式网络图形) 输出（ALPHA = no）；透明交付仍由工具后处理。明确选择独立色幕制作时再按主文第 3 节处理。
+- 不支持透明 PNG 输出（ALPHA = no），需绿幕策略
 
 ### prompt 格式建议
 
@@ -272,8 +270,6 @@ playcraft tools generate-image \
 >
 > 注意：`figer_icon.aiimage`、`win_result_panel.aiimage` 等 atom Skills 提供了带参考图的生成配方，Game Designer `playcraft skills match` 能匹配到时优先使用。本节模板用于无对应 atom Skill 的场景。
 
-下方独立界面前景通过 `removeBackground: true` / `--remove-background` 要求最终透明；模板描述主体，调用前按主文第 2 节补充适用于所选模型的源图背景。
-
 ### 🟠 CTA 按钮（Call-to-Action Button）
 
 ```
@@ -284,13 +280,13 @@ Important details: [bright orange / gold / green] gradient fill,
   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: No extra elements, centered, clean crisp edges,
+Constraints: Transparent background, no extra elements, centered, clean crisp edges,
   no watermark
 ```
 
 - CTA 颜色必须是游戏画面中**最少使用**的颜色（对比稀缺性原则）
 - 触控目标区域 ≥ 48×48px，生成建议尺寸 360×120px（9:3 比例）
-- 后处理由工具完成，验证最终透明背景、文字与边缘。
+- 后处理：不需要去背景（直接生成透明背景或用绿幕）
 
 ---
 
@@ -303,7 +299,7 @@ Important details: [color] filled portion [80% of total width], unfilled portion
   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: Horizontal orientation, no text labels,
+Constraints: Transparent background, horizontal orientation, no text labels,
   clean edges, no watermark
 ```
 
@@ -321,7 +317,8 @@ 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: No extra limbs or elements, finger pointing at bottom-center
+Constraints: Transparent background, PNG with alpha channel,
+  no extra limbs or elements, finger pointing at bottom-center
 ```
 
 **箭头变体**（更简洁）：
@@ -331,7 +328,7 @@ 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: Single clean arrow shape, no text
+Constraints: Transparent background, single clean arrow shape, no text
 ```
 
 ---
@@ -345,7 +342,7 @@ 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: No text inside, clean edges,
+Constraints: Transparent background, no text inside, clean edges,
   no watermark, no extra decorations
 ```
 
@@ -365,7 +362,7 @@ Important details: [treasure chest]: lid slightly ajar, golden glow escaping fro
   [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: Centered, isolated subject,
+Constraints: Transparent background, centered, isolated subject,
   no CTA text (added separately), warm celebratory lighting
 ```
 
@@ -376,19 +373,25 @@ Constraints: Centered, isolated subject,
 
 ### 📊 UI 元素背景处理规则速查
 
-CTA 按钮、进度条、引导手势、对话气泡与 EndCard 奖励图标都通过 `removeBackground: true` / `--remove-background` 要求最终透明；主体内容使用上述模板，源图背景按主文第 2 节准备。交付后验证文字、完整前景及深浅背景上的边缘。独立色幕制作沿用主文第 3 节的单一背景与独立去背流程。
+| 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`                              |
-| 背景不干净         | 交付要求或处理不匹配 | 核对背景开关、字段配置及模型对应的源图规则；检查最终验收，不混加背景要求 |
-| 多个物体出现       | 主体不够明确         | 加 `a single [物体]`, `only one [物体]`                                  |
-| 文字拼写错误       | 所有模型通病         | 尝试 gpt-image-2（最好），或多生成几张                                   |
-| 风格不一致（批量） | 没用 reference image | Phase 2 必须加 `--reference-image`                                       |
-| 细节过于复杂       | 素材尺寸小但细节太多 | 加 `simple design, minimal details, bold shapes`                         |
-| 生成极慢/超时      | 模型负载高           | 换另一个 provider 或换模型                                               |
+| 问题               | 原因                 | 修正                                             |
+| ------------------ | -------------------- | ------------------------------------------------ |
+| 图标边缘有阴影     | 模型默认加立体效果   | 加 `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/dist/commands/tools-image-context.js

@@ -1,23 +0,0 @@
-import { readImageAssetContext } from '../utils/image-asset-context.js';
-import { collectReferenceImagePaths, handleError } from './tools-utils.js';
-export function registerImageContextCommand(tools) {
-    tools.command('image-context')
-        .description('Read image asset reference and delivery constraints locally; does not generate an image')
-        .requiredOption('--asset-path <path>', 'Existing image asset path relative to the project')
-        .option('--reference-image <path>', 'Explicit local reference; may be repeated', collectReferenceImagePaths, [])
-        .option('--no-target-reference', 'Do not use the target schema or current asset as a reference')
-        .option('--prompt <text>', 'Generation request used to resolve background intent')
-        .option('--remove-background', 'Explicitly request verified transparency')
-        .option('--no-remove-background', 'Explicitly keep an opaque background')
-        .action(async (opts) => {
-        try {
-            console.log(JSON.stringify(await readImageAssetContext(opts.assetPath, process.cwd(), {
-                referenceImagePaths: opts.referenceImage, useTargetReference: opts.targetReference,
-                prompt: opts.prompt, removeBackground: opts.removeBackground,
-            })));
-        }
-        catch (error) {
-            handleError(error);
-        }
-    });
-}

package/dist/utils/image-asset-context.js

@@ -1,105 +0,0 @@
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import path from 'node:path';
-import JSON5 from 'json5';
-import sharp from 'sharp';
-import { extractAssetFields, getByPath, resolveAiImageTargetConstraints, resolveImageBackgroundRequirement, THEME_SCHEMA_PATH, themeDataPath, } from '@playcraft/common/prefab';
-/** Resolve only real files in this project, including legacy /project aliases. */
-function projectFile(root, input) {
-    const mapped = input.startsWith('/project/') ? input.slice('/project/'.length) : input;
-    const file = path.resolve(root, mapped);
-    const prefix = path.resolve(root) + path.sep;
-    if (!file.startsWith(prefix))
-        throw new Error(`Image asset path is outside the project: ${input}`);
-    const real = realpathSync(file);
-    if (!real.startsWith(realpathSync(root) + path.sep))
-        throw new Error(`Image asset symlink is outside the project: ${input}`);
-    return file;
-}
-/** Read the same per-field constraints used by the asset image dialog. */
-export async function readImageAssetContext(assetPath, projectDir = process.cwd(), options = {}) {
-    const root = path.resolve(projectDir);
-    const target = projectFile(root, assetPath);
-    const relativeTarget = path.relative(root, target).replace(/\\/g, '/');
-    const themeMatch = relativeTarget.match(/^src\/theme\/([^/]+)\/assets\//);
-    let field;
-    const schemaFile = path.join(root, THEME_SCHEMA_PATH);
-    if (themeMatch && existsSync(schemaFile)) {
-        const schema = JSON5.parse(readFileSync(projectFile(root, THEME_SCHEMA_PATH), 'utf8'));
-        const dataPath = themeDataPath(themeMatch[1]);
-        const data = existsSync(path.join(root, dataPath))
-            ? JSON5.parse(readFileSync(projectFile(root, dataPath), 'utf8')) : {};
-        const themeRoot = path.dirname(path.join(root, dataPath));
-        const matches = extractAssetFields(schema, data).filter(candidate => {
-            let configured = getByPath(data, candidate.path);
-            if (configured === undefined && ['gameplay', 'gamePlay'].includes(candidate.path[0])) {
-                configured = getByPath(data, [candidate.path[0] === 'gameplay' ? 'gamePlay' : 'gameplay', ...candidate.path.slice(1)]);
-            }
-            const value = typeof configured === 'string' ? configured : candidate.schema.default;
-            if (typeof value !== 'string' || /^https?:\/\//i.test(value))
-                return false;
-            return path.resolve(themeRoot, value) === target;
-        });
-        if (matches.length > 1)
-            throw new Error('Multiple image fields use this asset; specify an unambiguous target asset.');
-        field = matches[0];
-        if (!field)
-            throw new Error(`No image schema field matches ${relativeTarget}; check theme.data.json5 before generating.`);
-    }
-    const xp = field?.schema.xplatform;
-    const ext = xp?.ext;
-    // Schema references follow the dialog's root/theme conventions; explicit tool paths do not change.
-    const schemaReferences = Array.isArray(ext?.reference_image)
-        ? ext.reference_image.filter(ref => typeof ref === 'string' && ref.trim()).map(ref => {
-            const raw = ref.trim().replace(/\\/g, '/');
-            const normalized = raw.replace(/^\.\/+/, '').replace(/^\/+/, '').replace(/\/{2,}/g, '/');
-            if (/^\/?(?:assets|src|public)\//.test(raw) || normalized.startsWith('src/'))
-                return normalized;
-            if (!themeMatch || path.isAbsolute(raw) || /^https?:\/\//i.test(raw))
-                return raw;
-            return path.posix.join('src/theme', themeMatch[1], normalized);
-        }) : [];
-    const referenceImagePaths = options.referenceImagePaths?.length ? options.referenceImagePaths
-        : options.useTargetReference === false ? [] : schemaReferences.length ? schemaReferences : [relativeTarget];
-    if (referenceImagePaths.length > 8)
-        throw new Error('At most 8 reference images are allowed.');
-    for (const ref of referenceImagePaths) {
-        if (/^https?:\/\//i.test(ref))
-            throw new Error('Download the schema reference into the project before generating.');
-        await sharp(projectFile(root, ref)).metadata();
-    }
-    const targetMeta = await sharp(target).metadata();
-    const hasSchemaBackground = typeof ext?.remove_background === 'boolean';
-    const targetStats = !hasSchemaBackground && targetMeta.hasAlpha ? await sharp(target).stats() : undefined;
-    const targetHasTransparency = !!targetStats && targetStats.channels.at(-1).min < 250;
-    const removeBackground = resolveImageBackgroundRequirement({
-        prompt: options.prompt ?? '',
-        schemaRemoveBackground: hasSchemaBackground ? ext.remove_background : undefined,
-        removeBackground: options.removeBackground,
-        fallbackRemoveBackground: targetHasTransparency,
-    });
-    const delivery = resolveAiImageTargetConstraints({
-        schemaResolution: ext?.resolution,
-        schemaMimeType: xp?.mime_type,
-        schemaFitMode: xp?.fit_mode ?? ext?.fit_mode,
-        schemaRemoveBackground: removeBackground,
-        schemaPaddingColor: ext?.padding_color,
-        assetPath: relativeTarget,
-        referenceWidth: targetMeta.width,
-        referenceHeight: targetMeta.height,
-        referenceFormat: targetMeta.format,
-    });
-    if (!['png', 'webp', 'jpeg'].includes(delivery.format))
-        throw new Error('Unsupported image delivery format; use a dedicated animation or vector workflow.');
-    return {
-        targetAssetPath: relativeTarget,
-        fieldPath: field?.path,
-        referenceImagePaths,
-        width: delivery.width, height: delivery.height,
-        aspectRatio: typeof ext?.ratio === 'string' ? ext.ratio : `${delivery.width}:${delivery.height}`,
-        outputFormat: (removeBackground && delivery.format === 'jpeg' && !delivery.fromSchemaMimeType
-            ? 'png' : delivery.format),
-        fitMode: delivery.fitMode, removeBackground: delivery.removeBackground, paddingColor: delivery.paddingColor,
-        removeBackgroundFromSchema: hasSchemaBackground,
-        imageModelRef: typeof ext?.imageModelRef === 'string' ? ext.imageModelRef : undefined,
-    };
-}