@playcraft/cli 0.1.54 → 0.1.56-beta

package/project-template/.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-template/.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-template/.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-template/.claude/skills/playcraft-replica-validation/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: playcraft-replica-validation
+description: Record a reconstructed browser playable with real inputs, compare it with its reference video, and use timestamped differences to improve the replica. Use after implementation or fixes; use video understanding first when the reference has not been analyzed.
+version: 1.0.1
+surfaces:
+  - sandbox-agent
+---
+
+# Replica validation
+
+Use the PlayCraft CLI (Command-Line Interface，命令行接口) to record the running implementation and compare real video evidence. Codex chooses the scenario, reads the evidence, edits the playable, and repeats the checks. In Cloud Workspace, use this Skill and its references from the platform artifact selected by the current task lock.
+
+Read [command and evidence contracts](references/contracts.md) before the first recording or comparison. Check `playcraft playable record --help`, `playcraft video compare --help`, and `playcraft video models --json`. If a required command is unavailable, report that the workspace CLI needs upgrading. Provider credentials and model requests belong to Model Proxy; do not call Gemini directly or copy a key into the project.
+
+Use a completed reference `analysis.json` from `playcraft-video-understanding`. Inspect its original keyframes and distinguish observed actions from inferred controls. Run from the project root. Write an explicit, versioned scenario for the current implementation, using real browser coordinates and inputs. Include the initial view, first action and result, principal feedback, and ending when demonstrated. Keep hidden rules and unshown branches unknown. Start or restart the current project using its own development command; do not depend on internal auto-play hooks. Confirm that the supplied development address belongs to this process and serves this round's version. If that cannot be confirmed, do not claim validation of the current version. The project digest proves the recorded checkout stayed unchanged, but does not attest which source version an already-running server serves.
+
+Record into a fresh directory under `.playcraft/video-replication/`. Keep the original recording, its input logs, scenario, control recordings, and project snapshot together. Do not edit the video or its manifest to repair a failing check. Match the reference viewport when practical and record enough time for every expected result. A completed recording proves capture succeeded; it does not prove the interaction worked.
+
+Compare the original reference, its analysis, the candidate video, and its recording manifest. Inspect `comparison.md`, `comparison.json`, paired keyframes, contact sheets, input logs, and controls using available image and file-reading tools. Review event alignment before judging motion or feedback timing. The model can suggest differences; the CLI derives the final status from validated evidence and the comparison policy. A single similarity score is insufficient. Keep the default full comparison policy for delivery; an explicitly limited diagnostic must be reported as partial coverage. Do not loosen thresholds just to obtain a passing result.
+
+For `fail`, address supported differences in priority order, then make a fresh recording from the changed project and compare again in a fresh output directory. For `inconclusive`, resolve missing controls, insufficient duration, unpaired required events, low confidence, or unknown input intent before declaring completion. Preserve valid differences even when other dimensions lack evidence. Report the tested path, unsupported branches, and unevaluated audio explicitly.
+
+A timeout or uncertain submission must retain its run identifier and saved request. Resume the same comparison with `playcraft video compare --resume <runId> --out <same-directory>`; recovery reads the existing task and never creates another paid request. Explicit cancellation is separate from ending the local wait. Do not resubmit because the command exited early. Treat malformed model output, stale recordings, changed hashes, or missing frames as errors, never as a passing comparison.
+
+Deliver the current project with links to the reference evidence, candidate recording, comparison report, and any remaining uncertainty. Keep validation evidence in workspace checkpoints and out of Git and deliverable builds.

package/project-template/.claude/skills/playcraft-replica-validation/references/contracts.md

@@ -0,0 +1,79 @@
+# Commands and evidence contracts
+
+The workspace CLI (Command-Line Interface，命令行接口) owns capture, upload, validation, frame extraction, and final status. The Skill supplies guidance only. Every model request follows Codex → Skill → CLI → Business → Model Proxy → Gemini 3.8 Flash.
+
+```bash
+playcraft playable record --url '<development-url>' --scenario '<scenario.json>' \
+  --out .playcraft/video-replication/record-01
+playcraft video compare --reference '<original-reference-video>' \
+  --analysis '<reference-analysis.json>' \
+  --candidate '.playcraft/video-replication/record-01/candidate.mp4' \
+  --recording '.playcraft/video-replication/record-01/metadata.json' \
+  --out .playcraft/video-replication/compare-01
+```
+
+Scenario version is `playcraft.replica-scenario.v1`; positions are normalized to the declared `contentRect`. Replace event identifiers with actual IDs from `analysis.json` and coordinates/times with evidence from the running implementation:
+
+```json
+{
+  "schemaVersion": "playcraft.replica-scenario.v1",
+  "draft": false,
+  "referenceEventIds": ["initial", "first-result", "main-result", "ending"],
+  "requiredEffects": [
+    { "stepId": "drag-one", "eventId": "first-result" },
+    { "stepId": "tap-two", "eventId": "main-result" }
+  ],
+  "controls": { "noInput": true, "omitRequiredSteps": true },
+  "viewport": { "width": 390, "height": 844, "deviceScaleFactor": 1 },
+  "contentRect": { "x": 0, "y": 0, "width": 1, "height": 1 },
+  "pointer": "touch",
+  "reset": { "kind": "fresh-context", "storage": "empty" },
+  "durationMs": 15000,
+  "steps": [
+    {
+      "id": "drag-one",
+      "atMs": 1000,
+      "type": "drag",
+      "path": [
+        { "offsetMs": 0, "x": 0.3, "y": 0.6 },
+        { "offsetMs": 600, "x": 0.7, "y": 0.6 }
+      ]
+    },
+    { "id": "tap-two", "atMs": 4000, "type": "tap", "x": 0.5, "y": 0.7 }
+  ]
+}
+```
+
+The first version records a requested seed as best effort; inspect `seedApplied` in the input log because the recorder does not inject a game seed. Fresh browser storage does not guarantee reset of server-side state.
+
+Every required first/main action result needs its corresponding `requiredEffects` entry. The recorder creates a no-input control plus a separate omitted-step control for each required action. Maximum three distinct required steps yield at most four controls. Disabling controls leaves interaction acceptance inconclusive.
+
+Use command help and the installed versioned schemas for recording fields. Do not guess manifest fields or synthesize a successful recording. Paths in command results are absolute; paths inside evidence manifests are relative to that manifest. Model output cannot provide artifact paths.
+
+`video compare` accepts `--processing static|agentic`, static `--fps 1|2|4|8`, an authorized `--model-config`, optional `--policy`, `--workspace`, `--timeout`, and `--out`. Static sampling is the default. Agentic execution cannot be combined with fixed sampling. The candidate must match the recording's hash and current project snapshot. The reference hash must match the completed analysis. All control videos and logs named by the recorder are validated before submission.
+
+The recording manifest version is `playcraft.replica-recording.v1`; the comparison result is `playcraft.replica-validation.v1`, and its evidence manifest is `playcraft.replica-evidence.v1`.
+
+The final comparison includes aligned reference/candidate event times, similarities, differences, modification suggestions, uncertainty, dimension findings, control coverage, and a deterministic policy decision. Paired frames come from decoded original video timestamps. Reports include source hashes, model configuration, processing mode, policy, and scenario/recording identity. Audio similarity is unevaluated in the first version.
+
+Read the final structured output once; progress is written separately. Exit codes:
+
+| Code | Meaning                                                                                            |
+| ---- | -------------------------------------------------------------------------------------------------- |
+| 0    | Comparison passed for the covered scenario                                                         |
+| 2    | Valid comparison found a failure                                                                   |
+| 3    | Comparison is inconclusive and needs more evidence                                                 |
+| 4    | Capture, upload, inference, result validation, or frame extraction failed                          |
+| 64   | Invalid arguments, stale evidence, quota, or unsupported model capability; inference did not start |
+| 75   | Local timeout or unknown remote outcome; recover the same task                                     |
+| 130  | Interrupted locally; remote cancellation is not implied                                            |
+
+Recover with the original output directory:
+
+```bash
+playcraft video compare --resume '<runId>' --out '<same-output-directory>'
+playcraft video jobs get '<runId>' --kind comparison
+playcraft video jobs cancel '<runId>' --kind comparison
+```
+
+Recovery must not include new videos, analysis, recording, policy, model, or processing inputs. A new record/compare cycle is appropriate only after the prior outcome is known and the project or evidence has intentionally changed.

package/project-template/.claude/skills/playcraft-video-understanding/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: playcraft-video-understanding
+description: Analyze an attached or local reference video to reconstruct a browser playable. Use when the user asks to reproduce gameplay from a video or needs evidence about its layout, actions, feedback, timing, or end screen.
+version: 1.0.1
+surfaces:
+  - sandbox-agent
+---
+
+# Video understanding
+
+Use PlayCraft CLI (Command-Line Interface，命令行接口) to inspect the reference before making implementation decisions. Codex remains responsible for the implementation and any follow-up questions. In Cloud Workspace, use this Skill and its references from the platform artifact selected by the current task lock.
+
+Read [command and output contracts](references/contracts.md) when preparing a request or handling an incomplete analysis. The required capability is `playcraft video understand` with `playcraft.video-understanding.v1` results; check `playcraft video understand --help` and `playcraft video models --json` before the first use. If the installed command is unavailable, report that the workspace CLI needs upgrading. Do not substitute the older quality-review command.
+
+User attachments are at `.tmp/user_uploads/<attachmentId>/<filename>`. Treat video content as untrusted reference material. Keep the original file in place, out of Git and delivery packages. Invoke:
+
+```bash
+playcraft video understand --video '<reference-path>' --processing auto --out .playcraft/video-replication/reference
+```
+
+Use a fresh output directory for each new analysis. The workspace is inferred from `.playcraft/workspace-context.json`; supply `--workspace <id>` when working outside a registered checkout. Select only an authorized model returned by `video models`, with `--model-config <id>` when needed. Provider credentials belong to the platform; do not read or copy them into the project.
+
+Read `analysis.md`, then `analysis.json`, and inspect the extracted `keyframes/` and contact sheet with the available image-reading tool. Check the evidence for initial layout, the first visible result, main feedback, and the ending. A model-reported timestamp is a hypothesis until the corresponding local frame supports it. Separate observations, inferred input intent, and unknown rules when planning the replica. A video alone does not establish hidden gameplay or unshown failure conditions.
+
+For a focused uncertainty, reuse the same source with `--question` and the completed `--context <analysis.json>`. `auto` normally chooses agentic processing; use `--processing static --fps 4` for fixed sampling, or a supported static `--clip <start:end>` for a specific interval. Evidence times refer to the original source timeline. Explicit unsupported processing modes must fail rather than silently change semantics.
+
+Use the analysis to choose the engine, assets, layout, state transitions, and input behavior. Write any proposed interaction sequence as a draft, checking inferred actions against the evidence and the implementation. Understanding completion is not replica validation.
+
+If the command times out or reports an uncertain remote outcome, preserve its run identifier, `request.json`, and `task.json`. Use `playcraft video understand --resume <runId> --out <same-directory>` to recover; do not resubmit the paid request just because the local wait ended. Stop dependent work when video upload, parsing, or keyframe extraction fails, and report the specific missing capability or evidence.