@playcraft/cli 0.1.49-beta → 0.1.51

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

@@ -1,373 +0,0 @@
----
-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/
-```

package/project-template-v2/.claude/skills/playcraft-playable-optimization/SKILL.md

@@ -1,161 +0,0 @@
----
-name: playcraft-playable-optimization
-description: >-
-  Loop 3 optimization toolkit for PlayCraft playable ads: video validate loop,
-  image validator, headed MP4 recording, FX/animation polish, and L→G focus
-  playground. Use during development ready-state, ui_review/ui_rework, and the
-  optional ring 4 deep optimization after final Ring Gate.
-allowed-tools:
-  - Bash(npm run state:get:*)
-  - Bash(npm run ensure:project:*)
-  - Bash(npm run verify:ui:*)
-  - Bash(npm run record:mp4:*)
-  - Bash(npm run playground:*)
-  - Bash(npm run sweep:L1:*)
-  - Bash(npm run sweep:G1:*)
-  - Bash(npm run repack:frames:*)
-  - Read
-  - Write
-  - Edit
----
-
-# PlayCraft Playable Optimization Toolkit
-
-Abbreviations used here: UI (User Interface, 用户界面), MP4 (MPEG-4 Part 14, 视频容器格式), FX (Effects, 特效), ASR (Asset State Reference, 资产状态参考).
-
-> **定位**：PlayCraft 三 loop 中 **Loop 3（优化模板）** 的执行引擎。不改 PlayCraft 的 Agent 编排，只提供工具 + 调用协议。
->
-> **给谁用**：Developer（build 收尾）、Reviewer（ring 4 verify / optional optimization）、Developer / TA / Artist（ui_diff 修复）。
-
----
-
-## 起手式（每次调用前必做）
-
-```bash
-npm run state:get -- --json
-npm run ensure:project
-```
-
-先读 `state:get`，只运行 `nextCommands` / `currentRingVerifiers` 中已经披露的工具。`ensure:project` 只做目录、脚本和依赖准备，不代表当前 Ring 必须跑 UI / MP4 验证。
-
-`ensure:project` 会：
-
-- 检查/创建 `recordings/`、`validate/`、`focus-lab/`、`playground/`。
-- 若无 `playable.ui.profile.yaml` 则从 template 复制一份。
-- 合并 `package.json` scripts。
-- 自动 `npm install` + `npx playwright install chromium`（首次）。
-
-PlayCraft 是 **Vite** 项目，`ensure-project` 会检测到 `vite.config.ts` + 根目录 `index.html`，不会要求 `game/index.html`。
-
----
-
-## 与 PlayCraft growth-rings 的接点
-
-| iteration / loop              | 谁调用                  | 调用什么                                                        | 产出                           |
-| ----------------------------- | ----------------------- | --------------------------------------------------------------- | ------------------------------ |
-| ring 1 `loop: build`（收尾）  | Developer               | `state:get` 披露的 contract/lifecycle/firstwin                  | 轻量 HOOK 生命周期 + 首关可胜  |
-| ring 2+ `loop: build`（收尾） | Developer               | 仅运行 `state:get.nextCommands` 中的 `verify:ui` / `record:mp4` | 当前 Ring 证据                 |
-| ring 4 `loop: verify`         | Reviewer                | `verify:ui` → `playwright-cli` 截图                             | asset/layout 先行拦截          |
-| ring 4 verify ui_diff fail    | Developer / TA / Artist | 读 `playable-validate` 子 skill 做最小 fix                      | 修复后重跑 verify + record     |
-| ring 4 optional optimization  | Reviewer / Orchestrator | `playable-validate` loop                                        | `validate/PLAYABLE-*.md` + MP4 |
-
----
-
-## 一句话指令表
-
-| 用户/Agent 意图          | 命令/入口                                                                     |
-| ------------------------ | ----------------------------------------------------------------------------- |
-| 查看当前可运行命令       | `npm run state:get -- --json`                                                 |
-| 整片优化到可交付         | 读 `skills/playable-validate/SKILL.md` § Agent 入口                           |
-| 检查 UI / atlas / layout | 仅当 `state:get.nextCommands` 披露：`npm run verify:ui`                       |
-| 录完整局 headed MP4      | 仅当 `state:get.nextCommands` 披露：`npm run record:mp4 -- --headed --fps=60` |
-| 只录某个 focus zone      | `npm run record:focus -- --scope=PHASE --fixture=endcard-win --headed`        |
-| 优化 match 碎裂 FX       | 读 `skills/playable-fx-decompose/SKILL.md`                                    |
-| 优化帧光效 / burst       | 读 `skills/playable-fx-peak/SKILL.md`                                         |
-| 优化动效手感             | 读 `skills/playable-animate/SKILL.md`                                         |
-| 局部 L→G 穷举            | `npm run sweep:L1` / `npm run sweep:G1`                                       |
-
----
-
-## Vite 项目注意事项
-
-PlayCraft 项目用 Vite，`record:mp4` 默认脚本已经带了 `--use-dev --url=http://localhost:3000/`。只在当前 Ring 已披露 `record:mp4` 时运行：
-
-```bash
-npm run record:mp4 -- --headed --fps=60
-```
-
-这会：
-
-1. 在当前目录启动 `npm run dev`。
-2. 等待 `http://localhost:3000/` 可访问。
-3. 用 Playwright 打开该 URL 并录制。
-
-如果 Vite 端口不是 3000，改 `package.json` 里的 `record:mp4` 脚本，或手动：
-
-```bash
-# 终端 1
-npm run dev
-
-# 终端 2 / Agent
-npm run record:mp4 -- --url=http://localhost:5173/ --headed --fps=60
-```
-
----
-
-## 录制前提：游戏需暴露 harness 契约
-
-Recorder / `verify:contract` 以 **`window.__playable`** 为 pass 标准（见 `game/contract/` + `publishPlayableRuntime()`）：
-
-```js
-window.__playable.autoPlay(); // 一键推进到 ENDCARD
-window.__playable.getState(); // { currentPhase, isGameOver }
-window.__playable.getCanvas?.(); // 可选，供录屏取 canvas
-window.__playable.hideDebugUi?.(); // 可选，录屏前隐藏 debug UI
-```
-
-`window.__game` 可保留为引擎句柄（如 Phaser.Game），但**不得**在其上挂载 `start` / `autoPlay` 等 harness 方法。
-
-**Legacy 路径（仅 warn，2026-Q3 移除）**：旧项目若仍只暴露 `MainScene._onDebugAutoPlay()` + `sceneManager`，verify 仍可通过但会提示迁移到 `window.__playable`。
-
----
-
-## 标准工作流（按 gate 披露执行）
-
-```
-npm run state:get -- --json
-npm run ensure:project
-# Run only commands disclosed by state:get.nextCommands.
-# Then review MP4 evidence, make the smallest fix, and rerun disclosed gates.
-```
-
----
-
-## 输出规范
-
-- MP4 证据：`recordings/playable-YYYYMMDD-HHmmss.mp4`
-- 报告：`validate/PLAYABLE-YYYYMMDD-HHmmss.md`
-- Focus 录屏：`recordings/focus/...`
-- 给用户/ orchestrator：结论 + 证据路径 + 1–3 条 vs 基线
-
----
-
-## 依赖
-
-- Node.js 18+
-- Python 3 + `pip install pyyaml jsonschema pillow`
-- ffmpeg（`brew install ffmpeg`）
-- Playwright Chromium（由 `ensure-project` 自动安装）
-
----
-
-## 相关文件
-
-- `skills/playable-validate/SKILL.md` — 整片优化主入口
-- `skills/playable-verify-ui/SKILL.md` — Image Validator
-- `skills/playable-record/SKILL.md` — 录屏
-- `skills/playable-debug/SKILL.md` — 一键通关
-- `skills/playable-fx-peak/SKILL.md` — 帧光效
-- `skills/playable-fx-decompose/SKILL.md` — 碎裂
-- `skills/playable-animate/SKILL.md` — 动效手感
-- `skills/playable-focus/SKILL.md` — L→G playground