@playcraft/cli 0.0.39 → 0.0.41

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/
+```

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

@@ -0,0 +1,212 @@
+---
+name: playcraft-research
+description: PlayCraft 网络研究协议。当本地 Skill 库不足以覆盖需求时触发——包括遇到陌生玩法机制、不熟悉的美术风格、特定音频类型、算法实现参考、需要图片参考等场景。使用 playcraft tools research / fetch-url / search-image 命令（统一鉴权，无需配置额外 key）直接搜索网络，将研究成果融入活 DAG。
+triggers: 本地skill不够,没有现成skill,找不到参考,不了解这个风格,不熟悉这个玩法,陌生机制,需要调研,搜索参考,互联网搜索,研究,需要图片参考,找参考图,视觉参考
+---
+
+# PlayCraft 网络研究协议
+
+## 可用工具（统一鉴权，无需额外配置）
+
+使用 PlayCraft CLI 提供的三个搜索工具：
+
+```bash
+# 文本研究 — Gemini + Google Search grounding，返回综合答案 + 引用来源
+playcraft tools research --query "<问题>" [--focus <领域>] [--json]
+
+# 读取 URL — Gemini 理解指定页面内容，返回结构化摘要
+playcraft tools fetch-url --url "<URL>" [--query "<具体问题>"] [--json]
+
+# 图片搜索 — Unsplash / Pexels 高质量图库，返回可直接用于 --reference-image 的 URL
+playcraft tools search-image --query "<关键词（建议英文）>" [--source unsplash|pexels|auto] [--count 6] [--orientation landscape|portrait|square] [--json]
+```
+
+`--focus` 参数（research 命令）：`gameplay` | `visual` | `audio` | `code` | `compliance`
+
+---
+
+## 何时使用网络研究
+
+**先本地，再网络**。网络研究是本地 Skill 发现的补充，不是替代。
+
+| 场景 | 应做什么 |
+|---|---|
+| `playcraft skills match` 完整匹配 | 直接用，无需研究 |
+| 部分匹配，缺少细节 | 用本地 Skill，补充网络研究缺失部分 |
+| 完全无匹配 | **触发 `research` 文本研究** |
+| 遇到陌生专业名词 | **触发 `research` 文本研究** |
+| 需要最新数据（2024+ 最佳实践） | **触发 `research` 文本研究** |
+| 需要视觉参考图（Phase 1 概念图 / 风格探索） | **触发 `search-image` 图片搜索** |
+| 生成后不满意，想用参考图引导风格 | **触发 `search-image` → 结果 URL 直接传 `--reference-image`** |
+
+---
+
+## 各角色研究标准流程
+
+### PM — 玩法机制调研
+
+```bash
+# 理解陌生的玩法类型
+playcraft tools research \
+  --query "match-3 mobile game level design best practices difficulty curve" \
+  --focus gameplay --json
+
+# 了解可玩广告设计原则
+playcraft tools research \
+  --query "playable ad game mechanics player retention 15 seconds hook" \
+  --focus gameplay --json
+
+# 读取具体设计文章
+playcraft tools fetch-url \
+  --url "https://www.gamedeveloper.com/design/..." \
+  --query "what are the key level design parameters"
+```
+
+### Designer — 视觉/音频风格调研
+
+```bash
+# 搜索艺术风格生成参数
+playcraft tools research \
+  --query "pixel art 8-bit game sprite limited color palette generation prompt keywords" \
+  --focus visual --json
+
+# 读取调色板数据库
+playcraft tools fetch-url \
+  --url "https://lospec.com/palette-list/..." \
+  --query "what are the exact hex colors and style characteristics"
+
+# 搜索音频风格
+playcraft tools research \
+  --query "chiptune BGM game music BPM range instruments characteristics" \
+  --focus audio --json
+
+# ── 图片搜索（新增）─────────────────────────────────────────────────────────
+
+# 搜索视觉参考图（用于 Phase 1 风格探索）
+playcraft tools search-image \
+  --query "pixel art 8-bit forest game background" \
+  --source pexels --orientation portrait --json
+
+# 搜索元素参考图（用于指导具体 asset 生成）
+playcraft tools search-image \
+  --query "cute cartoon fruit character icon game UI" \
+  --count 4 --json
+
+# 将搜索结果 URL 直接用作参考图（无需先下载）
+playcraft tools generate-image \
+  --prompt "pixel art forest background, 8-bit style, limited color palette" \
+  --reference-image "https://images.unsplash.com/photo-xxxxx" \
+  --output assets/images/bg/background.png \
+  --aspect-ratio 9:16
+```
+
+> **关键提示**：`search-image` 返回的 `downloadUrl` 字段可直接传给 `--reference-image`，CLI 会自动下载，无需手动保存。`--json` 模式返回结构化列表，方便批量选用。
+
+### Developer — 算法/技术实现调研
+
+```bash
+# 搜索具体实现
+playcraft tools research \
+  --query "A* pathfinding javascript tile map Phaser 3 implementation performance" \
+  --focus code --json
+
+# 读取官方文档
+playcraft tools fetch-url \
+  --url "https://phaser.io/docs/3.60.0/Phaser.Physics.html" \
+  --query "how does StaticGroup work with tilemap collision"
+
+# 搜索性能优化
+playcraft tools research \
+  --query "Phaser 3 60fps mobile performance sprite batch rendering optimization" \
+  --focus code --json
+```
+
+### Reviewer — 质量标准调研
+
+```bash
+# 平台合规要求
+playcraft tools research \
+  --query "Google Ads playable ad HTML5 policy requirements file size 2026" \
+  --focus compliance --json
+
+# 读取最新政策文档
+playcraft tools fetch-url \
+  --url "https://support.google.com/google-ads/answer/..." \
+  --query "what are the technical requirements for playable ads"
+
+# 性能基准
+playcraft tools research \
+  --query "web game 60fps performance budget mobile device HTML5 2025" \
+  --focus compliance --json
+```
+
+---
+
+## 研究结果融入活 DAG
+
+研究结果**必须写入 `atom-plan.md`**，否则其他 Agent 无法从中受益。
+
+### 写入格式
+
+```markdown
+<!-- 在对应 atom 的 Asset/Impl Skill Context 下 -->
+
+### {{atom_id}} — {{slot_name}}
+- **本地 Skill**：无匹配（playcraft skills match 返回 0 结果）
+- **文本研究结论**（若执行了 research / fetch-url）：
+  - 命令：`playcraft tools research --query "..." --focus visual --json`
+  - 核心发现：{{1-3 句话，具体且可操作}}
+  - 关键参数：{{数值、关键词、具体配置}}
+  - 引用来源：{{URL}}
+- **图片参考**（若执行了 search-image）：
+  - 命令：`playcraft tools search-image --query "..." --json`
+  - 选用图片：{{description}} — {{downloadUrl}}
+  - 使用方式：作为 `--reference-image` 传入生成命令
+- **实现/生成决策**：{{基于研究的具体方案}}
+- **候选新 Skill**：`{{建议名称}}.{{bundleType}}` — {{为什么值得沉淀}}
+```
+
+### 示例：Designer 研究波普艺术 + 搜图参考
+
+```markdown
+### bg_atom — 背景图层
+- 本地 Skill：无匹配
+- 文本研究结论：
+  - 命令：`playcraft tools research --query "pop art game sprite color palette" --focus visual --json`
+  - 核心发现：波普艺术使用 4-6 色高饱和调色板，粗黑轮廓线，网点图案填充
+  - 关键参数：饱和度 >80%，互补色对比，轮廓线 3-5px
+  - 引用来源：lospec.com/palette-list/pop-art
+- 图片参考：
+  - 命令：`playcraft tools search-image --query "pop art colorful bold graphic background" --source unsplash --json`
+  - 选用图片：Bold geometric pop art composition — https://images.unsplash.com/photo-xxxxx
+  - 使用方式：`--reference-image "https://images.unsplash.com/photo-xxxxx"`
+- 生成决策：
+  - prompt: "pop art style, bold black outlines, halftone dots, vivid colors, {{element}}"
+  - style: "vibrant, graphic, flat colors, 1960s comic style"
+  - reference: 上方 Unsplash URL（CLI 自动下载）
+- 候选新 Skill：`pop_art_sprite.aiimage`
+```
+
+---
+
+## "候选新 Skill" 贡献循环
+
+每次网络研究形成可复用方案，在 `atom-plan.md` 的 **DAG Revisions** 标注：
+
+```markdown
+### Revision N — {{Agent}} (propose-skill)
+- **atomId**: {{atom_id}}
+- **reason**: 本地无 Skill，通过网络研究形成可复用方案
+- **change**: 建议创建：`{{skill_name}}.{{bundleType}}` — {{描述}}，来源：{{URL}}
+```
+
+---
+
+## 研究质量检查
+
+| 检查项 | 要求 |
+|---|---|
+| **来源可信度** | 优先官方文档、行业权威；引用来源来自 `--json` 输出的 `citations` 字段 |
+| **信息时效** | 优先 2024-2026 年内容（在 query 中加年份可提高准确性） |
+| **可操作性** | 结论必须直接用于生成参数或代码，不能泛泛而谈 |
+| **与 StyleDirection 一致** | 视觉研究须与 design-brief 的 StyleDirection 对齐 |