@playcraft/cli 0.0.56 → 0.0.58

package/project-template-v2/.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-v2/.claude/skills/playcraft-image-processing/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: playcraft-image-processing
+description: 可玩广告流程步骤 6。对生成的图片进行后处理：缩放、裁剪、旋转、翻转、填充、格式转换、滤镜、合成等。所有操作通过 `playcraft image` CLI 命令在沙箱本地执行，无需 backend，速度快。
+compatibility: agent,opencode
+---
+
+## Skill Definition
+
+tools:
+
+- bash
+- read
+  prompt_extension: |
+  你是图像处理工程师。不得向 /project/ 写入；所有输出路径必须在 ta-workspace（技术美术角色）。
+  通过 bash 工具运行 `playcraft image <command>` CLI 命令进行图片处理，所有操作在沙箱本地执行，无需往返 backend。
+
+## 我做什么
+
+- 对生成的图片进行后处理，使其符合游戏引擎和可玩广告的规格
+- 支持：缩放、裁剪、旋转、翻转、填充边距、格式转换、灰度化、模糊、色调叠加、反色、图片合成、像素化、自动裁边
+
+## 何时用我
+
+当 `playcraft tools generate-image` 生成的图片需要进一步处理时：
+
+- 尺寸不符合纹理要求（如需 2 的幂次、特定分辨率）
+- 需要像素风效果
+- 需要旋转/镜像翻转（如左右角色复用同一张图）
+- 需要统一多帧尺寸后合并精灵图
+- 需要格式转换（png → webp 优化体积）
+- 需要裁掉透明边界、叠加合成等
+
+## 命令速查
+
+所有命令格式：`playcraft image <command> --input <路径> --output <路径> [选项]`
+
+### 几何变换
+
+```bash
+# 缩放（支持比例或指定宽高）
+playcraft image resize --input src.png --output out.png --scale 0.5
+playcraft image resize --input src.png --output out.png --width 512 --height 512 --fit contain
+
+# 裁剪（指定区域）
+playcraft image crop --input src.png --output out.png --x 0 --y 0 --width 256 --height 256
+
+# 旋转（任意角度，默认背景透明）
+playcraft image rotate --input src.png --output out.png --angle 90
+playcraft image rotate --input src.png --output out.png --angle 45 --background "#ffffff"
+
+# 镜像翻转
+playcraft image flip --input src.png --output out.png --direction horizontal
+playcraft image flip --input src.png --output out.png --direction vertical
+
+# 扩展画布/加边距（统一精灵尺寸常用）
+playcraft image pad --input src.png --output out.png --all 16
+playcraft image pad --input src.png --output out.png --top 8 --bottom 8 --left 0 --right 0
+
+# 自动裁掉透明/纯色边界
+playcraft image trim --input src.png --output out.png --threshold 10
+```
+
+### 格式与质量
+
+```bash
+# 格式转换 + 压缩质量（png/jpg/webp/avif）
+playcraft image convert --input src.png --output out.webp --quality 85
+playcraft image convert --input src.jpg --output out.png
+```
+
+### 滤镜与色彩
+
+```bash
+# 灰度化
+playcraft image grayscale --input src.png --output out.png
+
+# 高斯模糊（背景虚化等）
+playcraft image blur --input src.png --output out.png --sigma 5
+
+# 色调叠加（做角色不同颜色变体）
+playcraft image tint --input src.png --output out.png --color "#ff4400"
+
+# 反色
+playcraft image negate --input src.png --output out.png
+
+# 像素化（像素风格）
+playcraft image pixelate --input src.png --output out.png --pixel-size 8
+```
+
+### 合成
+
+```bash
+# 将一张图叠在另一张图上（居中对齐）
+playcraft image overlay --base bg.png --overlay icon.png --output out.png
+
+# 指定坐标叠加
+playcraft image overlay --base bg.png --overlay icon.png --output out.png --x 100 --y 200
+```
+
+### 语义分割（SAM3）
+
+通过 SAM3（Segment Anything Model 3）对图片进行**开放词汇语义分割**：用文字或框 prompt 精确抠出任意对象，返回 mask 和 RGBA 透明图。
+需要经由 backend 代理，首次冷启动约 15s，热启动约 5-10s。
+
+```bash
+# ── 单 prompt — 文本 ──
+# 找到图中所有"logo"区域，输出 mask + RGBA
+playcraft image segment \
+  --input ta-workspace/banner.png \
+  --text "logo" \
+  --output-dir ta-workspace/segment-out
+
+# ── 单 prompt — 框选区域 ──
+# 用 [x1,y1,x2,y2] 绝对像素坐标指定目标区域
+playcraft image segment \
+  --input ta-workspace/banner.png \
+  --boxes "[[50,100,300,400]]" \
+  --output-dir ta-workspace/segment-out
+
+# ── 多 prompt 批量（一次调用，多个目标）──
+playcraft image segment \
+  --input ta-workspace/banner.png \
+  --prompts '[{"text":"icon"},{"text":"button"},{"text":"logo"}]' \
+  --output-dir ta-workspace/segment-out
+
+# ── 调节得分阈值（默认 0.3，越低召回越多）──
+playcraft image segment \
+  --input ta-workspace/hero.png \
+  --text "character" \
+  --threshold 0.2 \
+  --output-dir ta-workspace/segment-out
+
+# ── 不需要 RGBA 抠图，只要 mask ──
+playcraft image segment \
+  --input ta-workspace/hero.png \
+  --text "character" \
+  --no-rgba \
+  --output-dir ta-workspace/segment-out
+```
+
+**输出目录结构**：
+
+```
+segment-out/
+  prompt_0_logo/
+    00_mask.png       ← 二值 mask（白色为前景）
+    00_rgba.png       ← RGBA 透明抠图
+    01_mask.png       ← 同一 prompt 的第二个实例（若有多个）
+    01_rgba.png
+  prompt_1_button/
+    00_mask.png
+    00_rgba.png
+  segment-meta.json   ← 汇总：image_size、prompts、instances count、scores、bbox
+```
+
+**使用要点**：
+
+- **冷启动**：SAM3 缩容后首次调用约 15s，命令会自动等待，无需手动 ping
+- **热启动**：模型就绪后约 5-10s 完成分割
+- **抠图直接可用**：`rgba.png` 已是透明背景，可直接用于游戏资产，无需再跑 `remove-background`
+- **多实例**：同一 prompt 可能检测到多个对象（如图中有 3 个 logo），每个实例单独输出 `00_`、`01_`…
+- **bbox 信息**：`segment-meta.json` 包含每个实例的 bbox 坐标，可用于后续裁切定位
+
+**与 remove-background 的对比**：
+
+| 场景                                               | 推荐方案                               |
+| -------------------------------------------------- | -------------------------------------- |
+| 去除纯色/渐变/棋盘格背景（AI 生成图）              | `remove-background --method floodfill` |
+| 去除复杂真实照片背景                               | `remove-background --method ai`        |
+| **精确分割特定对象**（如从 UI 截图中提取某个按钮） | `segment --text "button"`              |
+| **批量提取多个不同对象**                           | `segment --prompts '[...]'`            |
+| **需要 mask 做遮罩特效**                           | `segment`（直接输出 mask.png）         |
+
+### 背景移除
+
+支持两种方法，根据图片类型选择：
+
+```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 ta-workspace/tile.png --output ta-workspace/tile.png --tolerance 40
+
+# 关闭边缘平滑（需要硬边像素风时）
+playcraft image remove-background --input ta-workspace/pixel_art.png --output ta-workspace/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
+```
+
+**方法选择指南**：
+| 方法 | 适用场景 | 速度 | 纹理保真度 |
+|------|---------|------|-----------|
+| `floodfill`（默认） | AI 生成的素材（纯色/灰色/棋盘格背景） | <0.5s | 零损失 |
+| `ai` | 真实照片、复杂背景 | ~1-3s | 可能褪色 |
+
+> **注意**：`--method ai` 会调用 backend API（需要沙箱 token）；`floodfill` 完全本地执行。
+
+## 可玩广告常见规格
+
+- 纹理尺寸：建议 2 的幂次（256×256、512×512、1024×1024）
+- 像素风：`--pixel-size 8` 到 `16` 常见
+- WebP 转换：通常比 PNG 小 30–50%，可玩广告体积敏感时优先用 webp
+- 统一精灵帧尺寸：先 `resize` → 再 `sprite-sheet` 合并
+
+## 典型流程
+
+```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 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"
+```