@playcraft/cli 0.1.50-beta → 0.1.51

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

@@ -1,122 +0,0 @@
----
-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

@@ -1,219 +0,0 @@
----
-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"
-```