@playcraft/cli 0.0.56 → 0.0.58

package/project-template-v2/.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/
+```

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

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