@playcraft/cli 0.0.40 → 0.0.42

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

@@ -0,0 +1,122 @@
+---
+name: playcraft-image-ops
+description: TA 图形操作生产上下文指南。按可玩广告流水线阶段（提取/标准化/变换/合成/验证）组织 playcraft image 子命令，说明 WHEN 和 WHY 而非仅 HOW。完整 CLI 参数速查表见 refs/ta-image-ops-reference.md。
+triggers: 裁剪,crop,叠图,合成,overlay,扩画布,pad,去白边,trim,旋转,rotate,翻转,flip,模糊,blur,色调,tint,灰度,grayscale,反色,negate,居中裁,等比裁,图层叠加,画布,像素级操作,图形处理,decompose-layers,图层分层,提取,extract
+---
+
+# PlayCraft 图形操作 — 生产上下文指南
+
+## 0. 在流水线中的位置
+
+所有命令均为 `playcraft image <子命令>` 格式，基于 sharp 本地处理，无需后端。
+
+```
+TA Production Pipeline:
+  Extract (从 Composite/ASR 提取)
+    -> decompose-layers (302 整图语义分层，Master Composite；见 playcraft-masking skill)
+    -> crop (ASR 网格 / 已知 bbox 的像素级裁切)
+    -> segment (SAM3 单对象蒙版，见 playcraft-masking skill)
+
+  Process (标准化处理)
+    -> trim (去除多余透明边)
+    -> resize (统一到 assetSpec 尺寸)
+    -> pad (补齐到等宽画布)
+    -> remove-background -> 见 playcraft-masking skill
+
+  Transform (变体生成)
+    -> flip horizontal (左右镜像，节省生成成本)
+    -> rotate (方向调整)
+    -> tint (色调变体 / 禁用状态)
+    -> grayscale (锁定 / 未解锁状态)
+
+  Compose (合成叠加)
+    -> overlay (多层合成：背景 + 角色 + UI)
+
+  Verify (验证)
+    -> info (检查尺寸 / 格式 / 文件大小)
+    -> convert (最终格式转换 -- 生产阶段保持 PNG)
+```
+
+---
+
+## 1. 按阶段命令速查
+
+| Stage     | Command            | One-liner                                                                         | Key Param                          |
+| --------- | ------------------ | --------------------------------------------------------------------------------- | ---------------------------------- |
+| Extract   | `decompose-layers` | `playcraft image decompose-layers --input X --output-dir ./layers --num-layers 4` | 后端 302；`--input` 宜为 HTTPS URL |
+| Extract   | `crop`             | `playcraft image crop --input X --output Y --x N --y N --width W --height H`      | x,y = 左上角原点                   |
+| Process   | `trim`             | `playcraft image trim --input X --output Y --threshold 10`                        | threshold: 0-255                   |
+| Process   | `resize`           | `playcraft image resize --input X --output Y --width W --height H`                | 或 `--scale 0.5`                   |
+| Process   | `pad`              | `playcraft image pad --input X --output Y --all 16`                               | 或 --top/bottom/left/right         |
+| Transform | `flip`             | `playcraft image flip --input X --output Y --direction horizontal`                | horizontal / vertical              |
+| Transform | `rotate`           | `playcraft image rotate --input X --output Y --angle 90`                          | 角度（顺时针），背景默认透明       |
+| Transform | `tint`             | `playcraft image tint --input X --output Y --color "#FFD700"`                     | hex 颜色值                         |
+| Transform | `grayscale`        | `playcraft image grayscale --input X --output Y`                                  | 无额外参数                         |
+| Compose   | `overlay`          | `playcraft image overlay --base BG --overlay FG --output Y --gravity center`      | 或 --x --y 精确坐标                |
+| Verify    | `info`             | `playcraft image info --input X`                                                  | --json 供脚本解析                  |
+| Verify    | `convert`          | `playcraft image convert --input X --output Y --format webp --quality 85`         | 生产阶段保持 PNG                   |
+
+**overlay gravity 值**：center(默认) / north / south / east / west / northeast / northwest / southeast / southwest。
+指定 --x + --y 时 gravity 被忽略，叠加图左上角放置在底图 (x, y) 坐标处。
+
+---
+
+## 2. 最常用配方
+
+### 配方 A：标准化精灵尺寸 (trim -> info -> pad)
+
+**场景**：AI 生成或分割提取的素材尺寸不一，需要统一到 assetSpec 指定的画布大小。
+
+```bash
+playcraft image trim --input raw_sprite.png --output /tmp/trimmed.png
+playcraft image info --input /tmp/trimmed.png --json
+# 根据 info 输出计算 pad 值：top/bottom = (目标高 - 当前高) / 2，left/right 同理
+playcraft image pad --input /tmp/trimmed.png --output assets/images/tiles/sprite_128x128.png \
+  --top 8 --bottom 8 --left 16 --right 16
+```
+
+**为什么这个顺序**：先 trim 去掉 AI 生成图的冗余透明边，再 pad 到精确尺寸。反过来做会把冗余透明边也算进画布。
+
+### 配方 B：多层合成 (overlay chain: bg -> character -> UI)
+
+**场景**：将背景、角色、UI 元素按层合成为最终画面。Layout Spec 中的 composite 通常需要这个流程。
+
+```bash
+playcraft image overlay --base assets/images/bg/background.png \
+  --overlay assets/images/character.png --output /tmp/step1.png --gravity center
+playcraft image overlay --base /tmp/step1.png \
+  --overlay assets/images/ui/cta_button.png --output assets/images/final.png --gravity south
+```
+
+**为什么逐层叠加**：overlay 每次只接受一个叠加层。从最底层开始，每一步的输出作为下一步的 base，保证 z-order 正确。
+
+### 配方 C：镜像动画帧 (flip horizontal)
+
+**场景**：已有 run_right 动画序列帧，需要 run_left。翻转比重新生成节省时间和 API 调用。
+
+```bash
+for f in assets/images/character/run_right_*.png; do
+  name=$(basename "$f" .png)
+  playcraft image flip --input "$f" \
+    --output "assets/images/character/${name/right/left}.png" \
+    --direction horizontal
+done
+```
+
+**为什么用 flip 而不重新生成**：AI 生成的镜像帧可能出现风格不一致，而 flip 保证像素级对称，且零 API 成本。
+
+---
+
+## 3. 关键注意事项
+
+- **crop 不支持 batch**：`playcraft image batch --steps` 中 crop 会报 `unsupported command`。批量裁切用 for 循环或 Node.js 脚本。
+- **生产阶段保持 PNG**：所有中间产物和最终资产用 PNG。WebP/AVIF 转换交给构建阶段 `playcraft build --convert-webp`。
+- **tint 是混合不是替换**：深色图像 tint 效果弱，需要颜色替换时用 overlay + 纯色图层。
+- **居中裁公式**：`x = (原图宽 - 目标宽) / 2`，`y = (原图高 - 目标高) / 2`（取整）。
+
+---
+
+## 4. 完整参考
+
+完整 CLI 参数速查表、所有 gravity 值、rotation 选项、滤镜命令（blur / negate）及更多组合配方：
+读取 `refs/ta-image-ops-reference.md`。

package/project-template/.claude/skills/playcraft-masking/SKILL.md

@@ -0,0 +1,373 @@
+---
+name: playcraft-masking
+description: PlayCraft 蒙版与智能抠图完整指南。涵盖 decompose-layers（302 Qwen 整图分层）、segment（SAM3 语义分割）的文本/框选模式、mask+rgba 输出、remove-background 选型、蒙版合成与轮廓描边。TA 在处理抠图、蒙版或背景替换任务前必读。
+triggers: 蒙版,mask,抠图,去背景,remove-background,语义分割,segment,SAM,SAM3,decompose-layers,图层分层,layered,背景替换,透明背景,RGBA,floodfill,ai抠图,轮廓描边,背景分离,foreground,主体提取
+---
+
+# PlayCraft 蒙版与智能抠图完整指南
+
+## 0. 工具速查
+
+| 工具                                   | 适用场景                                          | 速度                   | 质量                 |
+| -------------------------------------- | ------------------------------------------------- | ---------------------- | -------------------- |
+| `remove-background --method floodfill` | 纯色背景（绿幕、白底、渐变色）                    | 快（本地）             | 中等，边缘较硬       |
+| `remove-background --method ai`        | 任意复杂背景                                      | 慢（调后端）           | 高，支持半透明/毛发  |
+| `decompose-layers`                     | **整图**拆成 N 个语义 RGBA 层（Master Composite） | 慢（302，约 1–2 分钟） | 高，全尺寸分层 PNG   |
+| `segment`                              | 按 prompt **指定对象**抠图/蒙版                   | 慢（SAM3）             | 最高，产出 mask+rgba |
+
+**决策逻辑**：
+
+```
+要从整张合成稿一次性拆出背景/角色/UI 等多层？
+├─ 是 → decompose-layers（需 Admin 配置 302 API Key；本地图需公网 URL 或 --input HTTPS）
+└─ 否 → 背景是纯色/绿幕？
+         ├─ 是 → remove-background --method floodfill
+         └─ 否 → 需要 mask 文件供后续合成？
+                  ├─ 是 → segment（或已知位置用 crop）
+                  └─ 否 → remove-background --method ai
+```
+
+**decompose-layers vs segment**：
+
+- **decompose-layers**：无 per-object prompt，自动分层；适合 Master Composite 拆解；**不能**指定「只要第 3 格 tile」。ASR 优先用 `crop`。
+- **segment**：开放词汇或框选单个对象；适合精确蒙版；密集网格上**禁止**纯 text prompt（见下文 §2）。
+
+---
+
+## 1. decompose-layers — 302 Qwen 整图语义分层
+
+将整张图拆成 `num_layers` 张带透明通道的 PNG（默认 4 层），用于 Master Composite 元素提取（ASR 优先 crop，不用本命令）。
+
+```bash
+playcraft image decompose-layers \
+  --input assets/images/storyboard/master_composite.png \
+  --output-dir ta-workspace/tmp/layers \
+  --num-layers 4 \
+  --prompt ""
+
+# 输入已是公网 URL 时（推荐本地 dev）
+playcraft image decompose-layers \
+  --input "https://example.com/composite.png" \
+  --output-dir ./layers-out
+```
+
+**配置**：Admin → 系统 → AI → `provider=302`、`modelKind=image` + API Key（与 302 生图共用，**不必**单独添加 qwen-image-layered 模型项）。
+
+**输出**：`layer_00.png` … `layer_{N-1}.png` + `decompose-layers-meta.json`。
+
+---
+
+## 2. remove-background — 去背景
+
+### Floodfill 模式（纯色背景）
+
+```bash
+# 基础用法（默认 floodfill，去除纯色背景）
+playcraft image remove-background \
+  --input assets/images/tiles/tile_greenscreen.png \
+  --output assets/images/tiles/tile_transparent.png
+
+# 调整容差（--tolerance，默认 30）
+# 值越高，容错越大（适合渐变背景或有噪点的纯色背景）
+playcraft image remove-background \
+  --input assets/images/character/character_white_bg.png \
+  --output assets/images/character/character_transparent.png \
+  --method floodfill \
+  --tolerance 50
+
+# 边缘平滑度（--edge-smooth，默认 2，最大有效 4）
+# 值越高，边缘越柔和（减少锯齿）
+playcraft image remove-background \
+  --input assets/images/tiles/tile_white.png \
+  --output assets/images/tiles/tile_clean.png \
+  --tolerance 30 \
+  --edge-smooth 3
+```
+
+**Floodfill 参数说明**：
+
+| 参数            | 默认值 | 说明                                               |
+| --------------- | ------ | -------------------------------------------------- |
+| `--tolerance`   | 30     | 颜色容差（0-255）：背景色在此范围内的像素都被去掉  |
+| `--edge-smooth` | 2      | 边缘平滑（0-4）：对边缘 alpha 做高斯平滑，减少锯齿 |
+
+**什么时候调大 tolerance**：
+
+- 白色背景但图中有浅色元素 → tolerance 太大会误删内容，建议 20-30
+- 绿幕背景有轻微渐变 → 可试 40-60
+- 背景有明显噪点 → 50+
+
+### AI 模式（复杂背景）
+
+```bash
+playcraft image remove-background \
+  --input assets/images/character/character_scene.png \
+  --output assets/images/character/character_cutout.png \
+  --method ai \
+  --model small    # small（快）或 medium（精细）
+
+# 跳过 alpha 精化（更快，边缘稍粗）
+playcraft image remove-background \
+  --input source.png \
+  --output output.png \
+  --method ai \
+  --no-refine
+```
+
+**AI 模式 vs Floodfill 选型表**：
+
+| 特征                             | 选 floodfill | 选 ai |
+| -------------------------------- | ------------ | ----- |
+| 背景是纯色（绿、白、蓝）         | 是           | —     |
+| 背景有复杂纹理/渐变/场景         | —            | 是    |
+| 角色有半透明部分（衣物、头发丝） | —            | 是    |
+| 需要快速批量处理                 | 是           | —     |
+| 追求最高精度                     | —            | 是    |
+
+---
+
+## 3. segment — SAM3 语义分割
+
+`segment` 调用后端 SAM3 模型，对图片中的对象进行精确语义分割，产出**蒙版文件**（mask）和**透明抠图**（rgba）。
+
+**适用场景**：
+
+- 需要精确 mask 文件供后续合成操作使用
+- 从游戏截图中精确分离多个游戏元素
+- 需要不规则形状的蒙版（圆形徽章、异形 UI 元素）
+
+### ⚠️ 模式选择决策（必读）
+
+> **对网格/已知布局图（如 ASR state sheets、authoring sprite sheets），严禁使用纯 text prompt！**
+>
+> text prompt 在多元素密集图上歧义极大——SAM3 无法准确区分"整个 tile 方块"和"方块内的水果 icon"。
+
+```
+提取目标的位置已知或可计算？
+├─ 是（网格布局、规则排列）
+│   → 优先 playcraft image crop（最可靠，零 AI 歧义）
+│   → 次选 segment --boxes（需要精确蒙版时）
+│
+├─ 位置大致可估、需要精确蒙版
+│   → segment --boxes（用近似 bbox 框选）
+│
+└─ 位置完全未知、元素形状不规则
+    → segment --text（最后手段）
+    → prompt 必须极其具体，包含位置/颜色/上下文描述
+```
+
+**常见错误示例**：
+
+- ❌ `--text "apple tile icon"` → 可能只切出苹果水果，丢失 tile 方块底板
+- ❌ `--text "panda character"` → 图上有 panda face tile + panda 角色，返回多个 instance
+- ✅ `--boxes '[[50,50,450,450]]'` → 框选已知位置的完整元素
+- ✅ `playcraft image crop --x 50 --y 50 --width 400 --height 400` → 零歧义直切
+
+### 文本提示模式（仅用于位置未知、元素分布不规则场景）
+
+```bash
+# 用文字描述要提取的对象（仅适用于元素位置无法提前计算的场景）
+playcraft image segment \
+  --input assets/images/screenshot.png \
+  --text "the main character" \
+  --output-dir assets/images/segment_output/
+
+# 提取特定游戏元素
+playcraft image segment \
+  --input assets/images/game_scene.png \
+  --text "the treasure chest" \
+  --output-dir /tmp/segment/
+```
+
+**text prompt 最佳实践**：
+
+- 描述要尽可能具体：加颜色、位置、完整性描述
+- ✅ `"the complete rounded square tile with green apple in top-left area"`
+- ❌ `"apple tile icon"`（歧义：是苹果本身？还是整个 tile 方块？）
+- 返回多个 instance 时，不要盲目取 score 最高的——检查 bbox 尺寸是否合理
+
+### 框选模式（多对象精确分割）
+
+```bash
+# --boxes 接受 JSON 数组，每个元素为 [x1, y1, x2, y2]（左上角和右下角坐标）
+playcraft image segment \
+  --input assets/images/game_scene.png \
+  --boxes '[[50, 100, 200, 300], [350, 150, 500, 400]]' \
+  --box-labels '["player", "enemy"]' \
+  --output-dir /tmp/segment/
+
+# 单个框（无需 box-labels 时）
+playcraft image segment \
+  --input assets/images/tile_sheet.png \
+  --boxes '[[0, 0, 128, 128]]' \
+  --output-dir /tmp/segment/
+```
+
+### 输出结构
+
+`segment` 在 `--output-dir` 下生成：
+
+```
+segment_output/
+  ├── 00_mask.png        # 二值蒙版（白=前景，黑=背景）
+  ├── 00_rgba.png        # 透明背景抠图（直接可用）
+  ├── 01_mask.png        # 第二个对象的蒙版（若多框）
+  ├── 01_rgba.png        # 第二个对象的透明抠图
+  └── segment-meta.json  # 分割元数据（坐标、置信度等）
+```
+
+### 阈值调节（边缘精细度）
+
+```bash
+# --threshold（默认 0.3）：越低保留越多细节，但可能包含噪点
+# 越高边缘越干净，但可能丢失细节（毛发、透明边缘）
+playcraft image segment \
+  --input game_scene.png \
+  --text "the hero character" \
+  --threshold 0.2 \           # 较低：保留更多边缘细节
+  --output-dir /tmp/segment/
+
+# --mask-threshold：后端蒙版生成阈值（高级参数）
+playcraft image segment \
+  --input source.png \
+  --text "the dragon" \
+  --threshold 0.3 \
+  --mask-threshold 0.5 \
+  --output-dir /tmp/segment/
+```
+
+### 仅生成蒙版（不要 rgba）
+
+```bash
+# --no-rgba：跳过 rgba 生成，只输出 mask（更快）
+playcraft image segment \
+  --input source.png \
+  --text "the background elements" \
+  --no-rgba \
+  --output-dir /tmp/masks/
+```
+
+---
+
+## 4. 蒙版合成工作流
+
+### 工作流 A：换背景（最常用）
+
+```bash
+# 1. 用 segment 提取角色（带透明背景）
+playcraft image segment \
+  --input assets/images/character_with_bg.png \
+  --text "the game character" \
+  --output-dir /tmp/char_segment/
+# → 产出 /tmp/char_segment/00_rgba.png
+
+# 2. 用 overlay 把角色合成到新背景上
+playcraft image overlay \
+  --base assets/images/bg/new_background.png \
+  --overlay /tmp/char_segment/00_rgba.png \
+  --output assets/images/character_on_new_bg.png \
+  --gravity center
+```
+
+### 工作流 B：多层合成（背景 + 角色 + UI）
+
+```bash
+# 层1：基础背景
+cp assets/images/bg/background.png /tmp/composite.png
+
+# 层2：叠加角色（居中偏下）
+playcraft image overlay \
+  --base /tmp/composite.png \
+  --overlay assets/images/character/character_transparent.png \
+  --output /tmp/composite.png \
+  --gravity south
+
+# 层3：叠加 UI 层（顶部）
+playcraft image overlay \
+  --base /tmp/composite.png \
+  --overlay assets/images/ui/hud_overlay.png \
+  --output assets/images/final_scene.png \
+  --gravity north
+```
+
+### 工作流 C：轮廓描边效果
+
+用蒙版制作发光轮廓描边：
+
+```bash
+# 1. 提取蒙版
+playcraft image segment \
+  --input assets/images/character.png \
+  --text "character" \
+  --output-dir /tmp/seg/
+
+# 2. 把蒙版 tint 为描边颜色（金色）
+playcraft image tint \
+  --input /tmp/seg/00_mask.png \
+  --output /tmp/outline_colored.png \
+  --color "#FFD700"
+
+# 3. 扩大描边层（pad 向外扩 4px）
+playcraft image pad \
+  --input /tmp/outline_colored.png \
+  --output /tmp/outline_padded.png \
+  --all 4
+
+# 4. 叠回：描边层在底，原图在上
+playcraft image overlay \
+  --base /tmp/outline_padded.png \
+  --overlay /tmp/seg/00_rgba.png \
+  --output assets/images/character_outlined.png \
+  --gravity center
+```
+
+### 工作流 D：批量替换素材背景
+
+```bash
+# 对多张带绿幕背景的素材批量去背
+for f in assets/images/raw/tile_*_greenscreen.png; do
+  name=$(basename "$f" _greenscreen.png)
+  playcraft image remove-background \
+    --input "$f" \
+    --output "assets/images/tiles/${name}.png" \
+    --method floodfill \
+    --tolerance 40
+done
+```
+
+---
+
+## 5. 常见问题排查
+
+### 边缘有绿色/白色残留（floodfill）
+
+```bash
+# 原因：tolerance 太低，部分背景像素未被删除
+# 修复：适当提高 tolerance（每次 +10 尝试）
+playcraft image remove-background \
+  --input source.png --output output.png \
+  --tolerance 50    # 从 30 提升到 50
+```
+
+### segment 分割到了错误的对象
+
+```bash
+# 原因：文本提示不够精确
+# 修复方案 1：更具体的描述
+--text "the blue warrior character in the center"  # 加颜色/位置描述
+
+# 修复方案 2：改用框选模式，精确框出目标区域
+--boxes '[[x1, y1, x2, y2]]'  # 先用 playcraft image info 确认图片尺寸
+```
+
+### rgba 输出有半透明噪点
+
+```bash
+# 原因：threshold 太低
+# 修复：提高 threshold（从 0.3 到 0.5）
+playcraft image segment \
+  --input source.png \
+  --text "target object" \
+  --threshold 0.5 \
+  --output-dir /tmp/seg/
+```