@playcraft/cli 0.1.54 → 0.1.56-beta

package/project-templates/threejs/.claude/skills/playcraft-image-generation/reference/ta-image-generation-detail.md

@@ -0,0 +1,300 @@
+# TA (Technical Artist, 技术美术师) 图片生成进阶参考
+
+> 本文件供 TA/Designer 在需要精灵图直出、Edit 模型变体、错误恢复等进阶场景时按需查阅。核心决策逻辑见 `playcraft-image-generation` skill。复制模板前，将 `SKILL_DIR` 设为本次实际加载的 `SKILL.md` 所在目录（以技能加载回执为准）。
+
+---
+
+## 1. 精灵图直出 + 批量出图策略
+
+### 策略一：直接生成整张精灵图（最高效）
+
+**一次 API (Application Programming Interface, 应用程序编程接口) 调用生成包含多个元素的网格图**，后续用 `sprite-split` 切分。使用主文选定的模型，不因批量生成自动改用旧模型。
+
+> 保留命令行默认等待时间。等待本身不表示请求失败；本地超时也不表示后端已停止，确认原请求状态后再决定下一步，避免重复计费。
+
+#### 先判断：元素需要透明背景吗？
+
+```
+需要透明背景（独立元素：角色、车、道具、图标）？
+├─ 常规透明交付 → --remove-background；按主文第 2 节准备源图背景
+│                切分后保留透明通道，不重复去背
+├─ 不透明牌面/场景 → --no-remove-background；白色牌面属于主体
+└─ 明确选择独立色幕 → 仅限主文第 3 节；关闭整板自动去背，切分后逐格去背
+```
+
+#### 白底示例（卡牌，不需要去背景）
+
+```bash
+playcraft tools generate-image \
+  --prompt "Sprite sheet grid, 4 columns × 2 rows. Each cell: one playing card face, flat 2D, white card face, uniform size. Row 1: Ace of Spades, 2 of Spades, 3 of Spades, 4 of Spades. Row 2: 5 of Spades, 6 of Spades, 7 of Spades, 8 of Spades. Grid layout, equal cell size, no border between cells." \
+  --output assets/gen/cards_sheet.png \
+  --aspect-ratio 3:2 \
+  --image-model iegg-litellm/gpt-image-2.5-sunburst \
+  --no-remove-background
+
+# 查尺寸再切分（frame-width=总宽/列数, frame-height=总高/行数）
+playcraft image info --input assets/gen/cards_sheet.png
+playcraft image sprite-split \
+  --input assets/gen/cards_sheet.png \
+  --output-dir assets/images/cards/ \
+  --rows 2 --columns 4 \
+  --frame-width <总宽/4> --frame-height <总高/2>
+```
+
+#### 自动透明示例（独立元素）
+
+```bash
+# Step 1：Image 2.5 由后端组装源图背景并验收透明交付
+playcraft tools generate-image \
+  --prompt "Sprite sheet grid, 3 columns × 1 row. Each cell: one car, flat 2D vector, bold outline, centered, isolated subject. [Row1,Col1]: red sports car front view; [Row1,Col2]: blue SUV front view; [Row1,Col3]: yellow taxi front view. Grid layout, equal cell size, no border between cells." \
+  --output assets/gen/cars_sheet.png \
+  --aspect-ratio 3:2 \
+  --image-model iegg-litellm/gpt-image-2.5-sunburst \
+  --remove-background
+
+# Step 2：切分
+playcraft image info --input assets/gen/cars_sheet.png
+playcraft image sprite-split \
+  --input assets/gen/cars_sheet.png \
+  --output-dir assets/images/cars/ \
+  --rows 1 --columns 3 \
+  --frame-width <总宽/3> --frame-height <总高>
+
+# Step 3：验证每格主体完整及深浅背景上的透明边缘，不重复去背
+```
+
+明确选用其他模型时，同样传 `--remove-background`，但首次 prompt 需追加单一 `on a uniform solid pure white background for subsequent background removal`；后端不会像 Image 2.5 那样自动补源图背景。
+
+#### 独立色幕示例（仅限明确选择的制作流程）
+
+先按主文第 3 节选与主体不冲突的色幕。参考图和交付规格来自目标字段时先读取，再显式传给中间图请求，省略 `--target-asset`，避免字段透明要求覆盖保留色幕的开关。
+
+```bash
+# 已明确锁定不支持原生透明的模型与品红色幕；常规流程不使用此分支
+playcraft tools generate-image \
+  --prompt "Sprite sheet grid, 3 columns × 1 row. [Row1,Col1]: red sports car; [Row1,Col2]: blue SUV; [Row1,Col3]: yellow taxi. Each car isolated, centered on a uniform solid #FF00FF background, equal cell size, no borders, no shadows." \
+  --output assets/gen/cars_chroma.png \
+  --aspect-ratio 3:2 \
+  --image-model mulerouter/gpt-image-2 \
+  --no-remove-background
+
+# 读取实际尺寸并 sprite-split 后，逐格去背；品红使用 tolerance 20
+playcraft image remove-background \
+  --input assets/gen/cars-split/frame_r0_c0.png \
+  --output assets/images/cars/red_car.png \
+  --tolerance 20
+```
+
+其他格同样处理，并分别验收。自动透明图使用 `backgroundMode='automatic'`；独立色幕脚本设 `backgroundMode='chroma'`、`chromaColor` 和 `chromaTolerance`，不要把两种流程混用。
+
+**Prompt 关键词**：`sprite sheet grid, N columns × M rows, grid layout, equal cell size, uniform size`
+
+**每批推荐最多 16 个元素（4x4）**，元素太多时会出现混乱。
+
+### 策略二：批量出图（n>1，一次 API 调用返回多张候选）
+
+`--count N` 让同一个 prompt 一次返回 N 张候选图，适合 Phase 1 挑图。**谨慎使用，容易触发 provider 并发限制。**
+
+```bash
+# 一次 API 调用生成 4 张候选，选最好的
+playcraft tools generate-image \
+  --prompt "A single playing card, Ace of Hearts, flat 2D..." \
+  --output assets/gen/card \
+  --count 4 \
+  --image-model iegg-litellm/gpt-image-2
+# → 保存为 card_1.png card_2.png card_3.png card_4.png
+```
+
+> `--count N` 是"同一 prompt 出 N 张变体"，而不是"N 个不同元素"。生成 N 个不同元素请用策略一（精灵图直出）。
+
+**两种策略对比**：
+
+| 场景                       | 推荐策略                    | 说明                              |
+| -------------------------- | --------------------------- | --------------------------------- |
+| <=16 个同类元素            | 精灵图直出（策略一）        | 一张网格图 + sprite-split，最高效 |
+| 17-52 个元素               | 精灵图直出分批（每批 <=16） | 生成多张精灵图再切分              |
+| 风格变体（同构造不同内容） | 批量出图 `--count 4-6`      | 同 prompt 出多张挑最好的          |
+| 禁止                       | 逐个生成每个元素            | 效率极低，应全面避免              |
+
+### 策略三：分批生成精灵图（元素数量 > 16）
+
+```javascript
+// ta-workspace/scripts/gen-cards-batch-sheets.mjs
+// 52 张牌 → 4 批 × 13 = 4 张精灵图，再统一切分
+const BATCHES = [
+  {
+    name: 'sheet_spades',
+    cards: ['A♠', '2♠', '3♠', '4♠', '5♠', '6♠', '7♠', '8♠', '9♠', '10♠', 'J♠', 'Q♠', 'K♠'],
+  },
+  {
+    name: 'sheet_hearts',
+    cards: ['A♥', '2♥', '3♥', '4♥', '5♥', '6♥', '7♥', '8♥', '9♥', '10♥', 'J♥', 'Q♥', 'K♥'],
+  },
+  {
+    name: 'sheet_diamonds',
+    cards: ['A♦', '2♦', '3♦', '4♦', '5♦', '6♦', '7♦', '8♦', '9♦', '10♦', 'J♦', 'Q♦', 'K♦'],
+  },
+  {
+    name: 'sheet_clubs',
+    cards: ['A♣', '2♣', '3♣', '4♣', '5♣', '6♣', '7♣', '8♣', '9♣', '10♣', 'J♣', 'Q♣', 'K♣'],
+  },
+];
+// 每批生成一张 13×1 精灵图，再用 sprite-split 切分
+```
+
+参考脚本模板：[gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)
+
+---
+
+## 2. Edit 模型工作流（基图 → 编辑变体）
+
+### 适用场景
+
+结构相同、只改局部的变体集合：扑克牌（换花色/换数字）、棋子（换颜色）、图标集（换内容符号）。
+
+### 工作流
+
+```
+Phase 1：高质量模型生成 1 张完美基图
+  → gpt-image-2 / gemini-flash（最佳质量）
+  → 反复生成直到满意，存为 base_xxx.png
+
+Phase 2：用参考图 + prompt 批量生成变体
+  → 任何 text+image 或 image→image 模型均可
+  → 将基图作为 --reference-image，prompt 中描述变体差异
+  → 纯 edit 场景可用 mulerouter/qwen-image-edit-max
+```
+
+### Edit Prompt 写法
+
+```
+好的写法（修改指令）：
+   "Change the rank symbol from A to 2, show two spade symbols in the center"
+
+差的写法（完整重描述）：
+   "A playing card with two spade symbols, white background..."
+   （这会让模型重新生图，而不是编辑）
+```
+
+### 使用脚本模板
+
+```bash
+cp "$SKILL_DIR/reference/gen-edit-variants.template.mjs" \
+   ta-workspace/scripts/gen-<name>-variants.mjs
+# 修改 CONFIG.baseImage / CONFIG.editModel / VARIANTS[] 后运行
+node ta-workspace/scripts/gen-<name>-variants.mjs
+```
+
+---
+
+## 3. 错误恢复策略
+
+后端统一限制模型、供应商与重生成的总尝试次数；命令行默认不额外重试。普通素材默认模型选择、原生透明优先与剩余一次干净底图重生成均以主文第 2 节为准，脚本不再叠加模型回退链。
+
+| 错误现象               | 立即行动                                                                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| 仍在等待 / 本地超时    | 确认原请求状态，等待或核实后端已结束；不要并发重发，也不要仅因等待改模型。                                               |
+| 上游错误 / 网络失败    | 记录请求编号、实际 provider/model 与尝试次数，报告后端诊断；用户或流程锁定的模型不静默更换。                             |
+| 透明源图或最终验收失败 | 报告失败阶段并停止；不把棋盘格、补边或未完成的去背当成功，不自行改用色幕。                                               |
+| 去背处理失败           | 报告处理错误并停止，不重复生图或降低最终透明要求。                                                                       |
+| 参考图 / 交付参数错误  | 修正路径或参数后再发送；保留用户及字段约束，不丢弃参考图继续生成。                                                       |
+| 风格或内容偏差         | 参考 [prompt-cookbook.md](prompt-cookbook.md) 的主体模板，检查实际模型、参考图与交付规格；新一轮生成仍保留最终背景要求。 |
+
+---
+
+## 4. 批量生成最佳实践
+
+### 首选策略：精灵图直出（见第 1 节）
+
+**优先用本次选定的模型生成包含多个元素的网格图**，然后用 `sprite-split` 切分，避免逐个 API 调用。只有在以下情况才退化为逐个调用：
+
+- 需要 reference-image 一致性（网格 prompt 不稳定）
+- 每个元素差异太大，一张图放不下
+
+### 单张验证后再批量
+
+先生成 1 张验证效果，满意后再运行批量脚本。
+
+### 使用 Node.js 脚本（推荐）
+
+参见 [gen-batch.template.mjs](gen-batch.template.mjs)，复制到 `ta-workspace/scripts/` 后修改 CONFIG 区域。
+
+```bash
+cp "$SKILL_DIR/reference/gen-batch.template.mjs" \
+   ta-workspace/scripts/gen-<name>.mjs
+# 修改 CONFIG / ITEMS[] 后运行
+node ta-workspace/scripts/gen-<name>.mjs
+```
+
+### 批量处理
+
+参见 [process-batch.template.mjs](process-batch.template.mjs)。
+
+```bash
+cp "$SKILL_DIR/reference/process-batch.template.mjs" \
+   ta-workspace/scripts/process-<name>.mjs
+# 修改 CONFIG（特别是 skipRemoveBg）后运行
+node ta-workspace/scripts/process-<name>.mjs
+```
+
+已由生成工具验证透明的图使用 `skipRemoveBg=true`，保留透明边缘；不透明牌面/场景同样跳过去背。只有独立色幕中间图才设为 `false`，按所选色幕设置容差。
+
+### 合并精灵图
+
+参见 [build-sprite-sheet.template.mjs](build-sprite-sheet.template.mjs)。
+
+```bash
+cp "$SKILL_DIR/reference/build-sprite-sheet.template.mjs" \
+   ta-workspace/scripts/build-<name>-atlas.mjs
+# 修改 CONFIG / ORDERED_NAMES[] 后运行
+node ta-workspace/scripts/build-<name>-atlas.mjs
+```
+
+---
+
+## 5. TA Workspace：Node.js 脚本驱动
+
+### 为什么用 Node.js 而不是 bash？
+
+| 维度     | bash              | Node.js                    |
+| -------- | ----------------- | -------------------------- |
+| 语法错误 | 引号/转义陷阱多   | 标准 ES 语法，错误立即可读 |
+| 条件逻辑 | 繁琐              | if/else/switch 简洁        |
+| 错误处理 | `set -e` 容易遗漏 | try/catch 完整覆盖         |
+| 数据驱动 | 字符串拼接        | 对象数组，结构清晰         |
+| 调试     | `bash -x` 噪声大  | `console.log` 精确定位     |
+
+**结论**：超过 5 步或超过 10 个文件，始终写 Node.js 脚本。
+
+### ta-workspace 目录约定
+
+```
+ta-workspace/
+├── scripts/    ← Node.js 脚本（.mjs）
+├── logs/       ← 脚本运行日志（自动追加）
+└── tmp/        ← 临时文件（脚本完成后自动清理）
+```
+
+### 脚本模板目录
+
+| 模板                                                               | 用途                                          | 关键 CONFIG                                                   |
+| ------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------- |
+| [gen-batch-sprite.template.mjs](gen-batch-sprite.template.mjs)     | 精灵图直出，自动透明或独立色幕 → sprite-split | `model`, `removeBg`, `backgroundMode`, `columns`, `BATCHES[]` |
+| [gen-batch.template.mjs](gen-batch.template.mjs)                   | 批量从零 AI 生图（reference-image 模式）      | `model`, `referenceImage`, `style`, `ITEMS[]`                 |
+| [gen-edit-variants.template.mjs](gen-edit-variants.template.mjs)   | 基图 + edit 模型生成变体                      | `baseImage`, `editModel`, `VARIANTS[]`                        |
+| [process-batch.template.mjs](process-batch.template.mjs)           | 批量去背景 / trim + resize                    | `inputDir`, `outputDir`, `skipRemoveBg`                       |
+| [build-sprite-sheet.template.mjs](build-sprite-sheet.template.mjs) | 精灵图合并 + JSON 验证                        | `processedDir`, `columns`, `ORDERED_NAMES[]`                  |
+
+每个模板均包含：CONFIG/DATA/LOGIC 三段式结构、`existsSync` 幂等跳过、`appendFileSync` 日志、try/catch 错误统计。
+
+### 什么时候用命令行，什么时候写脚本？
+
+| 场景                             | 命令行 | 脚本 |
+| -------------------------------- | ------ | ---- |
+| 单张图片处理 / 查看信息          | 是     | —    |
+| 3-5 个文件，步骤简单             | 是     | —    |
+| 10+ 个文件，相同步骤             | —      | 是   |
+| 需要条件逻辑（不同素材不同参数） | —      | 是   |
+| 需要验证中间结果                 | —      | 是   |
+| 需要幂等重跑（跳过已存在）       | —      | 是   |
+| 完整管线（生成 → 处理 → 打包）   | —      | 是   |

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

@@ -5,7 +5,7 @@
  * TA 在 Compliance Gate 前运行，确认精灵图尺寸、帧数、通道数均符合要求。
  *
  * 使用方法：
- *   cp .claude/skills/playcraft-image-generation/reference/validate-sprite-sheet.template.mjs \
+ *   cp "$SKILL_DIR/reference/validate-sprite-sheet.template.mjs" \
  *      ta-workspace/scripts/validate-sprite-sheet.mjs
  *   # 修改下方 SHEETS 数组后运行：
  *   node ta-workspace/scripts/validate-sprite-sheet.mjs

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

@@ -1,7 +1,10 @@
 ---
 name: playcraft-image-processing
-description: 可玩广告流程步骤 6。对生成的图片进行后处理：缩放、裁剪、旋转、翻转、填充、格式转换、滤镜、合成等。所有操作通过 `playcraft image` CLI 命令在沙箱本地执行，无需 backend，速度快。
+description: Use when processing playable images with local transforms, platform layer separation, object segmentation, nine-patch analysis, or sprite slicing through playcraft image.
 compatibility: agent,opencode
+version: 1.1.1
+surfaces:
+  - sandbox-agent
 ---
 
 ## Skill Definition
@@ -11,13 +14,14 @@ tools:
 - bash
 - read
   prompt_extension: |
-  你是图像处理工程师。不得向 /project/ 写入；所有输出路径必须在 ta-workspace（技术美术角色）。
-  通过 bash 工具运行 `playcraft image <command>` CLI 命令进行图片处理，所有操作在沙箱本地执行，无需往返 backend。
+  你是图像处理工程师。工作素材写入当前工程的 assets/ 或当前主题素材目录；最终交付导出到工程根目录 dist/。
+  通过 bash 工具运行 `playcraft image <command>` CLI (Command Line Interface, 命令行界面) 命令处理图片。几何、格式、滤镜和合成在本地执行；图层分离、目标分割、九宫格和自动精灵分析使用平台能力。
 
 ## 我做什么
 
 - 对生成的图片进行后处理，使其符合游戏引擎和可玩广告的规格
 - 支持：缩放、裁剪、旋转、翻转、填充边距、格式转换、灰度化、模糊、色调叠加、反色、图片合成、像素化、自动裁边
+- 支持：图层分离、目标分割、九宫格拉伸边距分析、精灵图自动检测与切片
 
 ## 何时用我
 
@@ -32,7 +36,28 @@ tools:
 
 ## 命令速查
 
-所有命令格式：`playcraft image <command> --input <路径> --output <路径> [选项]`
+先查看目标子命令的 `--help`。单文件处理通常使用 `--input` / `--output`；分层、分割和切片使用 `--output-dir`，合成使用 `--base` / `--overlay`。
+
+### 图层分离与九宫格分析
+
+```bash
+# 当前云工作区分层管线：底图、可编辑图层和重建元数据
+playcraft image decompose-layers --input assets/composite.png --output-dir assets/layers
+playcraft image decompose-layers --input assets/composite.png --prompt "背景、角色和文字分别成层" --size 1.5K --output-dir assets/layers-v2
+
+# 明确需要旧管线时才选 Qwen
+playcraft image decompose-layers --input assets/composite.png --engine qwen --num-layers 4 --output-dir assets/layers-qwen
+
+# 分析面板四边的拉伸边距
+playcraft image analyze-nine-patch --input assets/panel.png --output assets/panel-analysis.json
+
+# 自动分析精灵图的行列及帧边界后切片
+playcraft image sprite-split --input assets/sheet.png --auto-detect --output-dir assets/frames
+```
+
+`decompose-layers` 默认使用 `seedream` 工作区管线，保存底图、全部图层和 `decompose-layers-meta.json`。重建时保留元数据中的相对路径、层叠顺序和边界框，不能只取预览图。`--num-layers`、`--no-safety-checker` 和 `--output-format` 是旧 Qwen 参数，不与显式 `--engine seedream` 混用。平台处理使用当前沙箱或登录用户的授权。
+
+如果原图需要从共享素材库获取，先运行 `playcraft library search`、`get`、`files`、`download`。素材包下载到新目录并保留相对路径；素材库与生成任务的完整工作流见当前可用的 `playcraft-workspace-assets` 技能。
 
 ### 几何变换
 
@@ -99,43 +124,43 @@ playcraft image overlay --base bg.png --overlay icon.png --output out.png --x 10
 
 ### 语义分割（SAM3）
 
-通过 SAM3（Segment Anything Model 3）对图片进行**开放词汇语义分割**：用文字或框 prompt 精确抠出任意对象，返回 mask 和 RGBA 透明图。
+通过 SAM3 (Segment Anything Model 3, 第三代通用分割模型) 对图片进行**开放词汇语义分割**：用文字或框 prompt 精确抠出任意对象，返回 mask 和 RGBA (Red Green Blue Alpha, 红绿蓝透明通道) 透明图。
 需要经由 backend 代理，首次冷启动约 15s，热启动约 5-10s。
 
 ```bash
 # ── 单 prompt — 文本 ──
 # 找到图中所有"logo"区域，输出 mask + RGBA
 playcraft image segment \
-  --input ta-workspace/banner.png \
+  --input assets/banner.png \
   --text "logo" \
-  --output-dir ta-workspace/segment-out
+  --output-dir assets/segment-out
 
 # ── 单 prompt — 框选区域 ──
 # 用 [x1,y1,x2,y2] 绝对像素坐标指定目标区域
 playcraft image segment \
-  --input ta-workspace/banner.png \
+  --input assets/banner.png \
   --boxes "[[50,100,300,400]]" \
-  --output-dir ta-workspace/segment-out
+  --output-dir assets/segment-out
 
 # ── 多 prompt 批量（一次调用，多个目标）──
 playcraft image segment \
-  --input ta-workspace/banner.png \
+  --input assets/banner.png \
   --prompts '[{"text":"icon"},{"text":"button"},{"text":"logo"}]' \
-  --output-dir ta-workspace/segment-out
+  --output-dir assets/segment-out
 
 # ── 调节得分阈值（默认 0.3，越低召回越多）──
 playcraft image segment \
-  --input ta-workspace/hero.png \
+  --input assets/hero.png \
   --text "character" \
   --threshold 0.2 \
-  --output-dir ta-workspace/segment-out
+  --output-dir assets/segment-out
 
 # ── 不需要 RGBA 抠图，只要 mask ──
 playcraft image segment \
-  --input ta-workspace/hero.png \
+  --input assets/hero.png \
   --text "character" \
   --no-rgba \
-  --output-dir ta-workspace/segment-out
+  --output-dir assets/segment-out
 ```
 
 **输出目录结构**：
@@ -178,16 +203,16 @@ segment-out/
 ```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 assets/hero_raw.png --output assets/hero.png
 
 # 调节容差（背景与前景颜色接近时增大）
-playcraft image remove-background --input ta-workspace/tile.png --output ta-workspace/tile.png --tolerance 40
+playcraft image remove-background --input assets/tile.png --output assets/tile.png --tolerance 40
 
 # 关闭边缘平滑（需要硬边像素风时）
-playcraft image remove-background --input ta-workspace/pixel_art.png --output ta-workspace/pixel_art.png --edge-smooth 0
+playcraft image remove-background --input assets/pixel_art.png --output assets/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
+playcraft image remove-background --input assets/photo.jpg --output assets/photo.png --method ai
 ```
 
 **方法选择指南**：
@@ -196,7 +221,7 @@ playcraft image remove-background --input ta-workspace/photo.jpg --output ta-wor
 | `floodfill`（默认） | AI 生成的素材（纯色/灰色/棋盘格背景） | <0.5s | 零损失 |
 | `ai` | 真实照片、复杂背景 | ~1-3s | 可能褪色 |
 
-> **注意**：`--method ai` 会调用 backend API（需要沙箱 token）；`floodfill` 完全本地执行。
+> **注意**：`--method ai` 会调用后端 API (Application Programming Interface, 应用程序编程接口)，需要有效的沙箱或用户凭据；`floodfill` 完全本地执行。
 
 ## 可玩广告常见规格
 
@@ -209,11 +234,11 @@ playcraft image remove-background --input ta-workspace/photo.jpg --output ta-wor
 
 ```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 tools generate-image --prompt "cute hero character" --background transparent --output assets/hero_raw.png
+playcraft image resize --input assets/hero_raw.png --output assets/hero_512.png --width 512 --height 512 --fit contain
+playcraft image convert --input assets/hero_512.png --output assets/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"
+playcraft image tint --input assets/hero_512.png --output assets/hero_blue.png --color "#0055ff"
+playcraft image tint --input assets/hero_512.png --output assets/hero_red.png --color "#ff2200"
 ```

package/project-templates/threejs/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: playcraft-workspace-assets
+description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+compatibility: agent,opencode
+version: 1.0.0
+surfaces:
+  - sandbox-agent
+---
+
+# 工作区素材工作流
+
+使用 PlayCraft CLI (Command Line Interface, 命令行界面) 的 `library` 和 `assets` 命令。运行对应子命令的 `--help` 核对参数；当前命令行缺少这些入口时，先报告需要匹配的命令行与服务版本。凭据由工作区提供。
+
+## 查找并复用素材
+
+```bash
+playcraft library search "角色" --type texture --tags character --limit 20 --json
+playcraft library facets --json
+playcraft library get <assetId> --json
+playcraft library files <assetId> --json
+playcraft library download <assetId> --output ./assets/character
+```
+
+检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+
+`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+
+## 创建持久化生成任务
+
+从 `references/requests.json` 选取所需类型的示例，将**单个请求对象**写入工程内的请求文件，并改成完整的用户需求。六种类型分别为 `image`、`audio`、`sprite`、`animation`、`model`、`video`。请求使用 JSON (JavaScript Object Notation, 数据交换格式)；参考图需同时提供 `referenceImageBase64` 和对应 `referenceImageMimeType`。模型参数以可用配置和共享契约为准。
+
+```bash
+playcraft assets estimate --request .tmp/asset-request.json
+playcraft assets generate --request .tmp/asset-request.json --client-request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId> --timeout 1800
+playcraft assets download <taskId> --output ./assets/generated-result
+```
+
+同一次生成保持 `--client-request-id` 和请求内容不变。提交结果不确定时重用原请求；拿到 `taskId` 后用 `get` 或 `wait` 恢复，不能新建任务来代替查状态。新候选使用新请求编号。`--wait --output <path>` 可合并等待和下载。
+
+命令在当前工程推断工作区和工程目录；工程外须传 `--workspace <workspaceId> --directory <directoryName>`，范围应对应目标工程。`tasks` 列出该范围任务；`cancel <taskId>` 请求取消，上游已提交请求可能继续结算。等待超时返回退出状态 75，远端任务仍可查询。
+
+下载前任务应为 `awaiting_adoption` 或 `saved`。精灵图与动画输出为完整包目录，下载会校验各文件大小与内容摘要。`queued` 和 `running` 只表示任务尚未完成；`failed`、`cancelled`、`interrupted` 应根据真实状态汇报。
+
+## 结果保存和动画版本
+
+- 生成结果保存到共享素材库：先 `assets library-targets` 获取允许的目的地，再通过 `assets library-save <taskId> --request <save-request.json>` 保存。用 `library-saves <taskId>` 查看状态，失败时 `library-retry <taskId> --save-id <saveId>` 沿用原保存任务。请求字段以命令帮助和 `asset-library-save` 共享契约为准。
+- 动画编辑：`assets animation get <taskId>` 读取草稿及修订号，`draft`、`upload-frame`、`version` 使用请求文件更新草稿、替换帧和导出版本。草稿写入结果不确定时先重新读取草稿修订号。
+- 指定动画版本下载：`assets download <taskId> --version <versionId> --output <new-directory>`。
+- `assets saved` 和 `assets animation saved` 需要已有的平台写入回执，不能用普通本地下载路径声明已经采纳。
+
+工作素材写入工程的 `assets/`，请求与回执放在 `dist/` 外。最终交付使用工程根目录 `dist/`，包内依赖一起交付。单张图片的直接生成仍可用 `tools generate-image`；裁剪、分割、分层及九宫格分析使用 `image` 子命令，先查看各自帮助。

package/project-templates/threejs/.claude/skills/playcraft-workspace-assets/references/requests.json

@@ -0,0 +1,32 @@
+{
+  "image": { "kind": "image", "prompt": "A transparent game character", "removeBackground": true },
+  "audio": { "kind": "audio", "category": "sfx", "description": "A short bright reward chime" },
+  "sprite": {
+    "kind": "sprite",
+    "prompt": "A character walking sequence",
+    "frameCount": 8,
+    "frameWidth": 256,
+    "frameHeight": 256,
+    "columns": 4,
+    "fps": 12
+  },
+  "animation": {
+    "kind": "animation",
+    "prompt": "A character waving in a loop",
+    "frameCount": 8,
+    "frameWidth": 256,
+    "frameHeight": 256,
+    "columns": 4,
+    "fps": 12
+  },
+  "model": { "kind": "model", "mode": "text", "prompt": "A low polygon treasure chest" },
+  "video": {
+    "kind": "video",
+    "mode": "text",
+    "prompt": "A treasure chest opening",
+    "duration": 5,
+    "aspectRatio": "16:9",
+    "resolution": "720P",
+    "audio": false
+  }
+}

package/templates/preview-runtime/v1/README.md

@@ -0,0 +1,79 @@
+# Cloud Workspace development runtime
+
+This SDK (Software Development Kit, 软件开发工具包) is distributed with the CLI (Command Line Interface, 命令行接口). It is only for development previews. Initialization copies versioned files; it does not modify your game, declare fields live, migrate a build system, or edit the production entry.
+
+Run `playcraft preview-runtime init --dir .` in the authorized engineering directory. Commit the copied files so the project remains reproducible without an installed CLI or a monorepo checkout. Repeating initialization is safe when all managed files match. Modified files cause a refusal; review and explicitly remove an old managed directory before changing its version. No force overwrite is provided.
+
+## Explicit game adapter
+
+Create your own `src/preview/runtime.ts`. Import `connectPreviewRuntime` and `readWorkspacePreviewContext` from `../../.playcraft/preview-runtime/runtime.mjs` (adjust the relative path). Type declarations are included. Call `readWorkspacePreviewContext('game-config-v1')` with your real configuration contract version, then `connectPreviewRuntime({...context, fields, source, resolve, createGame})`.
+
+- `source.get/install` must use the real game's configuration store. Share a neutral resolver with the independent production entry.
+- `fields` must explicitly register actual `documentId:'themeData'`, raw `path`, resolved `effectivePath`, `groupId` and `mode:'live'|'restart-scene'|'reload'`. Do not register an unconsumed schema field as live.
+- `resolve(documents)` resolves schema defaults and sparse `documents.themeData` overrides exactly as production does.
+- `createGame(context)` returns actual `apply(context)`, `restartScene(context)`, `afterRender(context)` and `dispose()` callbacks. Check `context.assertCurrent()` and honor `context.signal` before late effects. `afterRender` must wait for real rendering, not a successful placeholder.
+- Dispose the endpoint on page exit. Advertising SDK configuration remains the production concern; do not route development updates through advertising caches.
+
+## Runtime image parameters
+
+Register an image consumer with `resource: 'image'` and `mode: 'live'`. Keep its logical asset path in a preview-only resolved property used by `effectivePath`; do not compare an embedded image address with the raw parameter path. `context.loadImage(field, logicalPath)` requests the current declared image through the host and returns a decoded image element. Empty paths clear the consumer without reading a file. The host validates the field against the current schema and configuration; the game receives image bytes, never platform file addresses or credentials.
+
+Prepare all required images before changing visible objects, call `assertCurrent()` after asynchronous work and immediately before installing textures, then wait for the real engine frame. Keep old objects intact until preparation succeeds. Release old preview-owned textures and overlay references after a successful replacement and on disposal. Never remove an engine texture still used by another object.
+
+`ResourceLoadError` is exported from `runtime.mjs`. Live adapters let this error reach the runtime, which retains the last known installation and reports a recoverable, field-level resource failure. Do not catch an arbitrary update exception and claim successful fallback. During initial `createGame`, catch only this load error to start with an embedded default image or empty background; the runtime still reports the saved image as unapplied. A later patch of that field retries it; unrelated parameter updates can continue. `resourceErrors` and file-save receipts are independent. Save logical paths and let the original production asset registry include the file when building delivery output.
+
+## Preview build
+
+The engineering project must install a compatible Vite as a development dependency. Set a separate package script:
+
+```json
+{
+  "scripts": {
+    "build:cloud-preview": "node .playcraft/preview-runtime/build-preview.mjs --entry src/preview/runtime.ts --config vite.preview.config.ts"
+  }
+}
+```
+
+`--config` is optional. Omit it for a simple Vite entry; it never implicitly loads production Vite configuration. A legacy webpack/playable-scripts project needs its own explicit preview configuration/plugins for JSON5 (JavaScript Object Notation 5, 扩展对象配置), aliases, constants and asset handling. Initialization does not translate webpack configuration. `--mount-id game` selects the preview container id.
+
+Preserve unrelated manifest fields and declare in `.playcraft/workspace.json`:
+
+```json
+{
+  "parameters": {
+    "schemaPath": "src/game/schema.json",
+    "dataPath": "src/game/theme-data.json",
+    "themeId": "default"
+  },
+  "previewRuntime": {
+    "version": 1,
+    "buildScript": "build:cloud-preview",
+    "outputPath": ".playcraft-editor-preview/index.html",
+    "reportPath": ".playcraft-editor-preview/report.json",
+    "configContractVersion": "game-config-v1",
+    "entryPath": "src/preview/runtime.ts",
+    "viteConfigPath": "vite.preview.config.ts",
+    "mountId": "game",
+    "gameFilePaths": [
+      "src/preview/runtime.ts",
+      "src/game/configuration.ts",
+      "src/game/game.ts",
+      "vite.preview.config.ts",
+      ".playcraft/preview-runtime/runtime.mjs",
+      ".playcraft/preview-runtime/build-preview.mjs"
+    ]
+  }
+}
+```
+
+List the real preview entry, resolver, consumer and build configuration dependencies in `gameFilePaths`; these paths are examples. For a formally initialized project, entryPath is required; viteConfigPath and mountId are optional. The platform invokes its own trusted packaged helper with those fixed arguments and PLAYCRAFT_RUNTIME_PREVIEW_CONTEXT; it does not execute the project buildScript or trust report-selected commands. The package script is a convenience for local use. Existing package-based integrations without the copied runtime retain their original buildScript route. A manual build without this context fails by design. The helper produces one inline HTML (HyperText Markup Language, 超文本标记语言) document and a module report bound to the build id, schema, data, source fingerprint and SDK bytes. External modules/resources or split scripts are rejected. Engineering-specific assets/plugins may need adaptation; unsupported projects must report the concrete gap.
+
+The report also records raw hashes of actual workspace module inputs and known configuration dependencies. Dependency files under node_modules rely on the project's package/lock state; arbitrary plugins that read extra files without declaring dependencies still require an explicit gameFilePaths declaration or adapter-specific audit. This is not a proof of every possible plugin input.
+
+The platform embeds its immutable build profile after checking the report. The runtime reads the exact host origin and binding from platform context, validates the build profile, and then completes a real versioned handshake. A build report never declares live capability.
+
+## Independent production build
+
+Keep the original production entry and output under `dist/`. Never import the preview entry or runtime from production.
+
+For production builds using Vite, add `previewRuntimeReleaseGuard({root,previewEntries:['src/preview/runtime.ts']})` from this directory's `release-guard.mjs` to the production build plugins. It rejects the development module graph and runtime markers and writes an independent module/artifact report outside `dist/`. It does not migrate the production entry or replace game tests. Other build systems require their own equivalent module boundary; without it, do not claim production isolation has been proved. Passing parameter tests/build does not establish a live preview connection.