@playcraft/cli 0.1.39-prod → 0.1.40-beta

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 理解最准确，优先写英文。
 
-透明交付通过 `background: transparent` / `--background transparent` 或目标字段配置表达。用户未明确要求背景且字段没有明确不透明约束时，默认透明，包括卡牌、棋子和面板。下方常规前景模板描述主体、文字、风格、构图与材质；源图背景遵循主文第 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`
-- 需要透明交付时传 `background: transparent` / `--background transparent`。
 
 ### 🃏 卡牌 / 棋子 / 方块（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
 ```
 
-- 需要透明交付 → `background: transparent` / `--background transparent`，按主文第 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,18 +129,17 @@ Each icon centered in its cell, bold outlines, vibrant colors, no shadow.
 
 **背景选择（重要！）**：
 
-| 素材类型                            | 交付要求                                              | 切分后处理                        |
-| ----------------------------------- | ----------------------------------------------------- | --------------------------------- |
-| 独立元素（角色/车/道具/图标）需透明 | `--background transparent`，按主文第 2 节准备源图背景 | 保留透明通道，验证每格前景与边缘  |
-| 卡牌/棋子/UI 面板（矩形本体）       | 默认 `--background transparent`，保留牌面与边框       | 验证本体外透明，按目标尺寸 resize |
-| 用户/字段明确要求保留背景的最终素材 | `--background opaque`，整张图片不透明                 | 保留背景，按目标尺寸 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)
 
 ---
 
@@ -186,7 +183,7 @@ gpt-image-2 是目前质量最高的文生图模型，prompt 套路略有不同
 - **英文 prompt 效果最佳**，中文理解也不错但英文更稳定
 - 对**复杂场景**、**细节描述**处理能力远超其他模型
 - 支持**图生图 edit 模式**（传 `--reference-image`），局部编辑能力强
-- 不支持原生透明 PNG (Portable Network Graphics, 便携式网络图形) 输出（ALPHA = no）；透明交付仍由工具后处理。明确选择独立色幕制作时再按主文第 3 节处理。
+- 不支持透明 PNG 输出（ALPHA = no），需绿幕策略
 
 ### prompt 格式建议
 
@@ -234,7 +231,6 @@ elements centered in each cell, no borders between cells.
 ```bash
 playcraft tools generate-image \
   --prompt "A sword icon, flat 2D..." \
-  --background transparent \
   --output assets/gen/sword \
   --count 4 \
   --image-model iegg-litellm/gpt-image-2
@@ -252,7 +248,6 @@ playcraft tools generate-image \
 # 一次 API 调用生成 4 个候选，选最好的（比 4 次独立调用更高效）
 playcraft tools generate-image \
   --prompt "..." \
-  --background "$BACKGROUND_MODE" \
   --output "test/concept" \
   --count 4 \
   --image-model iegg-litellm/gpt-image-2
@@ -275,8 +270,6 @@ playcraft tools generate-image \
 >
 > 注意：`figer_icon.aiimage`、`win_result_panel.aiimage` 等 atom Skills 提供了带参考图的生成配方，Game Designer `playcraft skills match` 能匹配到时优先使用。本节模板用于无对应 atom Skill 的场景。
 
-下方独立界面前景通过 `background: transparent` / `--background transparent` 要求最终透明；模板描述主体，调用前按主文第 2 节补充适用于所选模型的源图背景。
-
 ### 🟠 CTA 按钮（Call-to-Action Button）
 
 ```
@@ -287,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 比例）
-- 后处理由工具完成，验证最终透明背景、文字与边缘。
+- 后处理：不需要去背景（直接生成透明背景或用绿幕）
 
 ---
 
@@ -306,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
 ```
 
@@ -324,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
 ```
 
 **箭头变体**（更简洁）：
@@ -334,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
 ```
 
 ---
@@ -348,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
 ```
 
@@ -368,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
 ```
 
@@ -379,19 +373,25 @@ Constraints: Centered, isolated subject,
 
 ### 📊 UI 元素背景处理规则速查
 
-CTA 按钮、进度条、引导手势、对话气泡与 EndCard 奖励图标都通过 `background: transparent` / `--background transparent` 要求最终透明；主体内容使用上述模板，源图背景按主文第 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,106 +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),
-        outputFormatFromSchema: delivery.fromSchemaMimeType,
-        fitMode: delivery.fitMode, removeBackground: delivery.removeBackground, paddingColor: delivery.paddingColor,
-        removeBackgroundFromSchema: hasSchemaBackground,
-        imageModelRef: typeof ext?.imageModelRef === 'string' ? ext.imageModelRef : undefined,
-    };
-}