@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/phaser/.claude/skills/playcraft-asset-state-sheet/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: playcraft-asset-state-sheet
+description: PlayCraft 资产状态参考精灵图板（ASR / Asset State Reference Sheet）生成指南。Artist 在 ring 3 Ring Gate（MC 选定）后输出两张 4K 参考精灵图：UI 组件状态板 + 玩法元素状态板，供 TA crop 量产。
+triggers: ASR,asset state reference,state reference sheet,UI state sheet,element state sheet,组件状态图,状态精灵图,精灵图板,参考精灵图,authoring sprite sheet,design handoff sheet,TA参考图,状态参考板,playcraft-asset-state-sheet
+---
+
+# PlayCraft 资产状态参考精灵图板（ASR）
+
+> **ASR** = **Asset State Reference Sheet**（资产状态参考精灵图板）  
+> **Authoring sprite sheet**（制作期精灵图板）：单张 PNG、规则网格、每格一种状态；与 TA 产出的 **runtime atlas**（`.webp` + `.json`）不同。
+
+## 0. 前置条件（硬门禁）
+
+- **仅在 ring 3 Ring Gate 通过、`selectedMcOption` 已写入 `project-state.md` 之后** 才能生成 ASR
+- **禁止**为未选中的 MC 方案生成 ASR
+- 两张板均使用已确认 MC 作 `--reference-image`，且 `--image-model` 与 MC 一致
+- **生成 ASR 前必读** `playcraft-image-generation` Skill §3（色幕矩阵）— 格内元素须可抠
+
+## 0.1 Sheet 底色 + 格内抠图（必读）
+
+> **整图 opaque 是预期行为** — ASR PNG 本身**不需要**也**不应**交付透明 PNG。TA 负责 `crop → remove-background → WebP atlas`。  
+> Artist 的职责是：让 **每个格内的单元素** 在 crop 后能被 TA 可靠抠图。
+
+| 层级                  | 规则                                                                              |
+| --------------------- | --------------------------------------------------------------------------------- |
+| **Sheet canvas**      | 不透明；默认 **中性灰 `#808080` flat background**（整板统一，禁止渐变/场景/纹理） |
+| **Sheet 备选**        | 若全板元素均非金/橙/绿，可用 **统一绿幕 `#00FF00`** 整板底色                      |
+| **Cell 内容**         | **单元素 isolated、居中**；禁止格内地面/阴影/白盒/场景/context                    |
+| **金/橙/黄/绿元素格** | 该格背景用 **蓝幕 `#0000FF`**（见 `playcraft-image-generation` 色幕矩阵）         |
+| **蓝/紫元素格**       | 该格背景用 **绿幕 `#00FF00`**                                                     |
+| **Artist 禁止**       | 对 ASR 做 `remove-background` 量产；那是 TA 在 `production` 的工作                |
+
+**错误示例（必须重生成）**：格内白底方块、渐变底、整屏 HUD 截屏、两元素叠在同一格、元素带地面阴影。
+
+## 1. 交付物：两张状态参考板
+
+| 交付物                            | 文件                                                  | 内容                                                  |
+| --------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- |
+| **UI State Reference Sheet**      | `assets/images/reference/ui_state_sheet_[X].png`      | 各 **UI/HUD 组件** 在所需交互态下的外观（非玩法棋子） |
+| **Element State Reference Sheet** | `assets/images/reference/element_state_sheet_[X].png` | 各 **玩法视觉元素** 在特殊/事件态下的外观             |
+
+`[X]` = `selectedMcOption`（A/B/C）。
+
+**多板扩展**（`unique element types > 12` 或 Layer1 槽位 > 12）：允许追加 `element_state_sheet_[X]_2.png`；Coverage Matrix 的 `sheet` 列填 `element_2`。详见 `docs/team/atom-tree-format.md` § `asrSlot`.
+
+### UI State Reference Sheet — 放什么
+
+- CTA 按钮、安装条、HUD 条、进度/分数框、手指引导、高亮框、徽章、弹窗底板等
+- 每个组件占 **一个或多个相邻槽位**，每槽 **一种状态**，例如：
+  - `cta_install`: default | pressed | disabled
+  - `finger_guide`: idle | tap-down
+  - `highlight_frame`: off | on
+
+### Element State Reference Sheet — 放什么
+
+- 棋子、牌面、角色、道具、匹配特效关键帧等（MC 概念面板里出现的玩法元素）
+- 每个元素 **type** 至少 **1 个代表态** 占物理槽位；同 type 的 color 变体可标 `CoverageLayer: ta-extends`（见 `artist-deliverable-spec.md`）
+- 每 type **2–3 个代表状态** 优先（完整全集由 TA 在 `production` 扩展），例如：
+  - `tile_gold`: idle | selected | matched
+  - `panda_char`: idle | happy | win
+
+**物理槽位预算**：每张板 **8–12 个状态槽**（宁可少槽、加大间距，也不要重叠）。  
+**Coverage Matrix 100% 行** ≠ 每行都有物理槽位 — 见 §1.1 三层覆盖。
+
+### 1.1 三层覆盖（与 Coverage Matrix 对齐）
+
+| CoverageLayer  | 含义                                        | Matrix 填写                              |
+| -------------- | ------------------------------------------- | ---------------------------------------- |
+| **on-asr**     | 该 contract id 在 ASR PNG 有物理槽位 `R#C#` | `ASR sheet` + `Grid`                     |
+| **mc-crop**    | MC Panel 1 可见、ASR 无槽位                 | `ASR sheet` = `MC-crop` + Panel 区域说明 |
+| **ta-extends** | 颜色变体 / 额外状态，TA 从 ASR 或 MC 扩展   | `TA extends? = yes` + Style Intent 一句  |
+
+**硬规则**：每种 **element type** 至少在 **on-asr** 或 **mc-crop** 有一处代表态；禁止全部 `ta-extends` 且 MC/ASR 均无参考。
+
+## 2. 布局策略 — 规则网格、零重叠
+
+1. **零重叠**：任意两格 bounding box 不得相交
+2. **网格化**：每行 3–4 槽；每槽固定矩形空白区；元素居中；四周 **≥80px** 边距
+3. **行间距 ≥120px**，**列间距 ≥100px**
+4. 禁止层叠、散落堆叠、透视干扰
+
+### UI 板示例布局
+
+```
+Row 1: [CTA default] [CTA pressed] [CTA disabled] [HUD bar]
+Row 2: [finger idle] [finger tap]   [badge]        [highlight on]
+```
+
+### 元素板示例布局
+
+```
+Row 1: [tile A idle] [tile A selected] [tile A matched] [tile B idle]
+Row 2: [char idle]   [char happy]      [char win]       (empty)
+```
+
+## 3. Prompt 模板
+
+**生成前**：按 `playcraft-image-generation` §3 为每格元素选定 cell 背景色（灰/绿/蓝幕）。
+
+**UI 板** — 在 prompt 中显式写 `UI component state reference sprite sheet`：
+
+```
+UI component state reference sprite sheet for [GAME_TYPE] playable ad.
+3840x2160 canvas, solid flat #808080 gray background on entire sheet. NO gradient, NO scene.
+
+STRICT LAYOUT: orthographic grid, fixed non-overlapping cells. Each UI widget state in exactly one cell, 80px margin, 100px column gap, 120px row gap. NO overlapping.
+
+Each cell: ONE isolated UI widget, centered, no drop shadow on floor, no white box behind widget, no scene context.
+
+Row 1 — CTA / HUD:
+- Cell 1: CTA install button, default state, isolated, centered ...
+- Cell 2: CTA install button, pressed state, isolated, centered ...
+...
+
+Art style: [SAME as Master Composite]. Front-facing UI, crisp edges, consistent lighting.
+```
+
+**元素板** — 写 `gameplay element state reference sprite sheet`：
+
+```
+Gameplay element state reference sprite sheet for [GAME_TYPE].
+3840x2160 canvas, solid flat #808080 gray background on entire sheet. NO gradient, NO scene.
+
+STRICT LAYOUT: [same as UI sheet]
+
+Each cell: ONE isolated game element, centered. Gold/orange/yellow elements: cell background solid bright blue #0000FF. Blue/purple elements: cell background solid bright green #00FF00. NO white box, NO ground shadow, NO scene.
+
+Row 1 — Core tiles/items:
+- Cell 1: [Element type A] idle, isolated, centered ...
+- Cell 2: [Element type A] selected, isolated, centered ...
+...
+
+Art style: [SAME as Master Composite].
+```
+
+**元素板额外约束（test11 B10/B12）**：
+
+```
+UNIFORM SILHOUETTE: All gameplay elements of the same category (e.g. all match-3 gems) MUST share the
+identical outer silhouette and occupy the same visual scale in every cell. NO mixing hex/diamond/square/drop shapes.
+
+REGULAR GRID: Equal cell width and height, equal spacing — TA re-measures from pixels after generation;
+do NOT trust API-reported grid metadata without calibration.
+```
+
+**Prompt 必须包含**：`sprite sheet` 或 `state reference sheet`、`STRICT LAYOUT`、`non-overlapping cells`、具体 gap 像素、`isolated`、`NO white box`、`NO scene`、**`UNIFORM SILHOUETTE`**（元素板）。
+
+## 4. 生成命令
+
+```bash
+# UI 组件状态板
+playcraft tools generate-image \
+  --prompt "<UI sheet prompt>" \
+  --output assets/images/reference/ui_state_sheet_[X].png \
+  --reference-image assets/images/storyboard/master_composite_option_[X].png \
+  --image-model <与 MC 相同> \
+  --aspect-ratio 16:9 \
+  --image-size 4K
+
+# 玩法元素状态板
+playcraft tools generate-image \
+  --prompt "<Element sheet prompt>" \
+  --output assets/images/reference/element_state_sheet_[X].png \
+  --reference-image assets/images/storyboard/master_composite_option_[X].png \
+  --image-model <与 MC 相同> \
+  --aspect-ratio 16:9 \
+  --image-size 4K
+
+# 元素板溢出时（可选第二张）
+playcraft tools generate-image \
+  --prompt "<Element sheet part 2 prompt>" \
+  --output assets/images/reference/element_state_sheet_[X]_2.png \
+  --reference-image assets/images/storyboard/master_composite_option_[X].png \
+  --image-model <与 MC 相同> \
+  --aspect-ratio 16:9 \
+  --image-size 4K
+```
+
+## 5. 核查清单
+
+| #   | 核查项       | 标准                                                                         |
+| --- | ------------ | ---------------------------------------------------------------------------- |
+| 1   | 时机         | `selectedMcOption` 已设置                                                    |
+| 2   | 数量         | UI 板 + 元素板各至少一张                                                     |
+| 3   | 视觉         | 两板均无重叠；有重叠则重生成                                                 |
+| 4   | 语义         | UI 板无玩法棋子；元素板无整屏 HUD 截屏                                       |
+| 5   | 格内可抠     | 目视：无白盒/场景底/格内渐变；金橙元素格用蓝幕                               |
+| 6   | 整图 opaque  | 预期行为 — 不要求透明 PNG                                                    |
+| 7   | 清单         | `artist-log` § **ASR Coverage Matrix** 100% contract 行 + `CoverageLayer` 列 |
+| 8   | 网格元数据   | Sheet grid 表：rows × cols + cell W×H + padding（非 `{{placeholder}}`）      |
+| 9   | type 代表态  | 每种 element type 至少在 on-asr 或 mc-crop 有一处                            |
+| 10  | asrSlot 镜像 | on-asr 行已写入 `atom-tree.json` → `meta.selectedAtoms.asrSlot`              |
+
+## 6. 与 TA 的协作协议
+
+Artist：风格与 MC 一致；在 `artist-log.md` § **ASR Coverage Matrix** 标注 **CoverageLayer** 与 **TA 需扩展的状态**。
+
+TA 提取（详见 `playcraft-masking`）：
+
+| 来源图               | 推荐方式                   | 说明                                                                                                                                           |
+| -------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **ASR**（规则网格）  | `playcraft image crop`     | 槽位坐标来自 `artist-log` § **ASR Coverage Matrix**（含 Sheet grid 元数据）或 `atom-tree.json` → `asrSlot`；**禁止**对 ASR 用纯 text `segment` |
+| **Master Composite** | `decompose-layers` 或 crop | `mc-crop` 层从此补提取                                                                                                                         |
+
+**若 TA crop 后仍不可抠**（白边/色幕残留/元素被截断）→ `routeTo: artist` 重生成 ASR 格，**非** TA 自行重画 ASR。

package/project-templates/phaser/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: playcraft-audio-generation
+description: PlayCraft AI 音频生成完整指南。涵盖 SFX 音效生成、BGM 背景音乐生成（prompt 套路、时长、风格参数）、本地音频后处理（compress/fade/loop/normalize/mix），以及完整的音频管线。Artist 和 TA 在生成音频资产前必读。
+triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
+---
+
+# PlayCraft AI 音频生成指南
+
+## 0. 开始前必读
+
+音频资产分两类，使用不同工具：
+
+| 类型               | 工具                           | 是否需要后端 |
+| ------------------ | ------------------------------ | ------------ |
+| AI 生成音效（SFX） | `playcraft tools generate-sfx` | 是           |
+| AI 生成 BGM        | `playcraft tools generate-bgm` | 是           |
+| 本地音频处理       | `playcraft audio <子命令>`     | 否           |
+
+> ⚠️ **重要**：`generate-sfx` 的 `--prompt` **只支持英文**。BGM 的 prompt 可以用中文描述风格，但英文效果更稳定。
+
+---
+
+## 1. SFX 音效生成
+
+### 基本用法
+
+```bash
+playcraft tools generate-sfx \
+  --prompt "short coin collect chime, game UI, bright and crisp" \
+  --output assets/audio/sfx/coin.mp3 \
+  --duration 1.0
+```
+
+### 常用参数
+
+| 参数         | 说明                        | 建议值                     |
+| ------------ | --------------------------- | -------------------------- |
+| `--prompt`   | 音效描述（**必须英文**）    | 见下方 prompt 套路         |
+| `--output`   | 保存路径（`.mp3` / `.wav`） | —                          |
+| `--duration` | 时长（秒）                  | SFX：0.3–3.0；环境音：3–10 |
+| `--loop`     | 是否循环友好                | 环境音、引擎声用 `--loop`  |
+
+### SFX Prompt 套路
+
+**结构**：`[音效描述], [场景/用途], [音色特征], [可选：情绪/风格]`
+
+| 用途           | Prompt 示例                                                                |
+| -------------- | -------------------------------------------------------------------------- |
+| UI 点击        | `"button click, game UI, soft and satisfying, short"`                      |
+| 金币收集       | `"coin collect chime, arcade game, bright metallic, 0.5 seconds"`          |
+| 爆炸           | `"explosion impact, action game, deep bass rumble with debris scatter"`    |
+| 卡牌翻转       | `"card flip whoosh, card game, crisp paper sound"`                         |
+| 胜利提示       | `"victory fanfare, casual mobile game, cheerful and upbeat, short jingle"` |
+| 失败提示       | `"fail sound, game over, descending tone, simple"`                         |
+| 跳跃           | `"jump sound, platform game, light spring bounce"`                         |
+| 魔法施放       | `"magic spell cast, fantasy game, sparkling shimmer with whoosh"`          |
+| 麻将碰牌       | `"mahjong tile click, ceramic tap sound, sharp and clear"`                 |
+| 环境音（循环） | `"forest ambient, birds chirping, peaceful, seamless loop"`                |
+
+**质量修饰词**（加在末尾）：
+
+- 追求干净：`"clean, no reverb, game-ready"`
+- 追求丰富：`"rich, layered, cinematic"`
+- 追求复古：`"8-bit, chiptune, retro game"`
+
+### 批量 SFX 生成脚本
+
+```javascript
+// ta-workspace/scripts/gen-sfx.mjs
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+
+const OUTPUT_DIR = 'assets/audio/sfx';
+const SFX_LIST = [
+  {
+    name: 'coin',
+    prompt: 'coin collect chime, arcade game, bright metallic, 0.5 seconds',
+    duration: 0.5,
+  },
+  {
+    name: 'click',
+    prompt: 'button click, game UI, soft satisfying, short',
+    duration: 0.3,
+  },
+  {
+    name: 'win',
+    prompt: 'victory fanfare, casual mobile game, cheerful upbeat jingle',
+    duration: 2.0,
+  },
+  {
+    name: 'fail',
+    prompt: 'fail sound, game over, descending tone, simple',
+    duration: 1.5,
+  },
+  {
+    name: 'jump',
+    prompt: 'jump sound, platform game, light spring bounce',
+    duration: 0.4,
+  },
+];
+
+for (const sfx of SFX_LIST) {
+  const output = `${OUTPUT_DIR}/${sfx.name}.mp3`;
+  if (existsSync(output)) {
+    console.log(`[SKIP] ${sfx.name}`);
+    continue;
+  }
+  console.log(`[GEN] ${sfx.name}...`);
+  execSync(
+    `playcraft tools generate-sfx --prompt "${sfx.prompt}" --output "${output}" --duration ${sfx.duration}`,
+    { stdio: 'inherit' },
+  );
+}
+```
+
+---
+
+## 2. BGM 背景音乐生成
+
+### 基本用法
+
+```bash
+playcraft tools generate-bgm \
+  --prompt "upbeat casual mobile game, playful and energetic, suitable for a card matching game" \
+  --output assets/audio/bgm/main_theme.mp3 \
+  --bpm 120
+```
+
+### 常用参数
+
+| 参数       | 说明         | 建议值                                         |
+| ---------- | ------------ | ---------------------------------------------- |
+| `--prompt` | 音乐风格描述 | 见下方 prompt 套路                             |
+| `--output` | 保存路径     | —                                              |
+| `--bpm`    | 节拍速度     | 轻松：90–110；激烈：130–160                    |
+| `--style`  | 附加风格标签 | `"electronic"` / `"orchestral"` / `"chiptune"` |
+
+### BGM Prompt 套路
+
+**结构**：`[游戏类型], [情绪基调], [乐器风格], [可选：特定场景]`
+
+| 场景         | Prompt 示例                                                         | BPM |
+| ------------ | ------------------------------------------------------------------- | --- |
+| 休闲手游主题 | `"casual mobile game, cheerful and bouncy, ukulele and marimba"`    | 110 |
+| 扑克牌游戏   | `"card game background, smooth jazz lounge, elegant and relaxed"`   | 95  |
+| 麻将游戏     | `"mahjong game, traditional Chinese instruments, calm and focused"` | 85  |
+| 动作游戏     | `"action arcade game, intense and driving, electronic synth drums"` | 145 |
+| 像素风冒险   | `"8-bit adventure game, chiptune style, heroic and nostalgic"`      | 130 |
+| 益智解谜     | `"puzzle game, gentle and thoughtful, soft piano and ambient pad"`  | 90  |
+| 胜利画面     | `"victory celebration, triumphant fanfare, short and energetic"`    | 140 |
+| 菜单/大厅    | `"game lobby menu, welcoming and pleasant, light and airy"`         | 100 |
+
+### BGM 循环处理（必做！）
+
+AI 生成的 BGM 首尾通常不能无缝循环，需要后处理：
+
+```bash
+# 生成后检查时长
+playcraft audio info --input assets/audio/bgm/main_theme.mp3
+
+# 无缝循环处理（交叉淡化 1 秒）
+playcraft audio loop \
+  --input assets/audio/bgm/main_theme.mp3 \
+  --output assets/audio/bgm/main_theme_loop.mp3 \
+  --crossfade 1.0
+
+# 验证循环点
+playcraft audio info --input assets/audio/bgm/main_theme_loop.mp3
+```
+
+---
+
+## 3. 本地音频后处理
+
+所有 `playcraft audio` 子命令**完全本地运行**，无需网络。
+
+### 3.1 常用处理命令
+
+```bash
+# 查看音频信息（时长、体积、比特率、采样率）
+playcraft audio info --input audio.mp3
+
+# 压缩（减小文件体积）
+playcraft audio compress \
+  --input audio.mp3 \
+  --output audio_small.mp3 \
+  --target-size 50KB          # 或指定比特率 --bitrate 64k
+
+# 裁剪（取片段）
+playcraft audio trim \
+  --input audio.mp3 \
+  --output trimmed.mp3 \
+  --start 0 --end 5.0         # 取前 5 秒
+
+# 淡入淡出
+playcraft audio fade \
+  --input audio.mp3 \
+  --output audio_fade.mp3 \
+  --fade-in 0.3 \
+  --fade-out 0.5
+
+# 无缝循环
+playcraft audio loop \
+  --input audio.mp3 \
+  --output audio_loop.mp3 \
+  --crossfade 1.0
+
+# 响度标准化（游戏音频建议 -16 LUFS）
+playcraft audio normalize \
+  --input audio.mp3 \
+  --output audio_norm.mp3 \
+  --target-loudness -16
+
+# 格式转换（WAV → MP3，或 MP3 → OGG）
+playcraft audio convert \
+  --input audio.wav \
+  --output audio.mp3
+
+# 多轨混音
+playcraft audio mix \
+  --inputs bgm.mp3,sfx.mp3 \
+  --output mixed.mp3 \
+  --volumes 0.7,1.0           # BGM 70%，SFX 100%
+  --offsets 0,2.5             # SFX 在 2.5 秒处开始
+```
+
+### 3.2 标准音频处理管线
+
+AI 生成后的**必做处理步骤**：
+
+```
+SFX 管线：
+generate-sfx → normalize (-16 LUFS) → compress (目标 <100KB) → convert (.mp3)
+
+BGM 管线：
+generate-bgm → normalize (-16 LUFS) → loop (--crossfade 1.0) → compress (目标 <500KB) → convert (.mp3)
+```
+
+---
+
+## 4. 错误恢复策略
+
+| 错误现象                       | 原因              | 行动                                         |
+| ------------------------------ | ----------------- | -------------------------------------------- |
+| `generate-sfx` prompt 返回错误 | Prompt 包含中文   | **改为英文**                                 |
+| SFX 时长不准                   | AI 生成时长近似值 | 用 `audio trim` 裁剪到精确时长               |
+| BGM 首尾断裂                   | AI 未做循环       | **必须跑 `audio loop --crossfade 1.0`**      |
+| 音量太小/太大                  | 生成音量随机      | `audio normalize --target-loudness -16`      |
+| 文件体积太大（>1MB）           | 无压缩            | `audio compress --target-size 200KB`         |
+| 格式不对                       | 项目要求特定格式  | `audio convert --input x.wav --output x.mp3` |
+
+---
+
+## 5. 常用命令速查
+
+```bash
+# AI 生成 SFX（prompt 必须英文）
+playcraft tools generate-sfx \
+  --prompt "coin collect, bright chime, 0.5 seconds" \
+  --output sfx/coin.mp3 \
+  --duration 0.5
+
+# AI 生成 BGM
+playcraft tools generate-bgm \
+  --prompt "casual card game, upbeat jazz, relaxed" \
+  --output bgm/theme.mp3 \
+  --bpm 110
+
+# 无缝循环处理（BGM 必做）
+playcraft audio loop --input bgm/theme.mp3 --output bgm/theme_loop.mp3 --crossfade 1.0
+
+# 响度标准化（SFX/BGM 推荐）
+playcraft audio normalize --input audio.mp3 --output audio_norm.mp3 --target-loudness -16
+
+# 压缩减体积
+playcraft audio compress --input audio.mp3 --output audio_small.mp3 --target-size 100KB
+
+# 查看音频信息
+playcraft audio info --input audio.mp3
+```

package/project-templates/phaser/.claude/skills/playcraft-batch-pipeline/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: playcraft-batch-pipeline
+description: PlayCraft 批处理管线选型与语法指南。涵盖三种批处理方式的选型决策树（Node.js 脚本 / CLI batch / CLI pipeline）、playcraft image batch 的 steps 语法与已知限制、playcraft image pipeline 的 YAML 配置结构与 assemble 精灵图组装。实用配方见 refs 文件。
+triggers: 批处理,batch,pipeline,批量操作,多文件处理,声明式管线,YAML配置,批量resize,批量转换,批量去背,assemble,精灵图组装,image batch,image pipeline,批量处理,parallel,skip-existing,断点续传
+---
+
+# PlayCraft 批处理管线指南
+
+## 0. 三种批处理方式选型
+
+```
+需要批量处理多张图片？
+│
+├─ 涉及 AI 生成（generate-image）或复杂分支逻辑？
+│   └─ → Node.js .mjs 脚本（ta-workspace/scripts/）
+│         参考：playcraft-image-generation Skill 的 reference/ 模板
+│
+├─ 纯本地图像处理（resize/convert/tint 等），需要并发加速？
+│   └─ → playcraft image batch（本节 §1）
+│
+└─ 需要最终自动打包成精灵图，或用配置文件管理管线？
+    └─ → playcraft image pipeline（本节 §2）
+```
+
+**三种方式对比**：
+
+| 特性           | Node.js 脚本 | image batch       | image pipeline          |
+| -------------- | ------------ | ----------------- | ----------------------- |
+| AI 生成        | 支持         | 不支持            | 不支持                  |
+| 并发控制       | 自定义       | `--parallel N`    | 顺序                    |
+| 断点续传       | 自实现       | `--skip-existing` | 不支持                  |
+| 配置复用       | JS 文件      | 命令行            | YAML/JSON 文件          |
+| 自动组装精灵图 | 自实现       | 不支持            | `assemble.sprite-sheet` |
+| 学习成本       | 中           | 低                | 低                      |
+
+---
+
+## 1. playcraft image batch — 声明式多步批处理
+
+对一个目录（或多个文件）中的所有图片，按顺序执行多个处理步骤。
+
+### 基础用法
+
+```bash
+playcraft image batch \
+  --input-dir assets/images/raw/ \
+  --output-dir assets/images/processed/ \
+  --steps "resize --width 256 --height 256, tint --color #FFD700" \
+  --parallel 4 --skip-existing
+```
+
+| 参数                 | 类型   | 说明                                           |
+| -------------------- | ------ | ---------------------------------------------- |
+| `--input-dir <dir>`  | string | 输入目录（与 `--inputs` 二选一）               |
+| `--inputs <paths>`   | string | 逗号分隔的文件列表（与 `--input-dir` 二选一）  |
+| `--glob <pattern>`   | string | 文件匹配模式，默认 `*.png,*.jpg,*.jpeg,*.webp` |
+| `--output-dir <dir>` | string | 输出目录（必填）**输出统一为 .png**            |
+| `--steps <pipeline>` | string | 处理步骤（必填，见下方语法）                   |
+| `--parallel <N>`     | number | 并发数，默认 4                                 |
+| `--skip-existing`    | flag   | 跳过输出目录中已存在的文件（断点续传）         |
+
+### Steps 语法
+
+`--steps` 接受逗号分隔的步骤列表，每步格式为 `子命令名 [参数...]`：
+
+```bash
+--steps "resize --width 128 --height 128, grayscale, tint --color #4488FF"
+```
+
+### 支持的步骤命令
+
+| 可用命令            | 示例                                                      |
+| ------------------- | --------------------------------------------------------- |
+| `resize`            | `resize --width 128 --height 128` 或 `resize --scale 0.5` |
+| `convert`           | `convert --format webp --quality 85`                      |
+| `grayscale`         | `grayscale`                                               |
+| `blur`              | `blur --sigma 5`                                          |
+| `tint`              | `tint --color #FFD700`                                    |
+| `trim`              | `trim --threshold 20`                                     |
+| `negate`            | `negate`                                                  |
+| `rotate`            | `rotate --angle 90`                                       |
+| `flip`              | `flip --direction horizontal`                             |
+| `pad`               | `pad --all 8`                                             |
+| `pixelate`          | `pixelate --pixel-size 8`                                 |
+| `remove-background` | `remove-background --method floodfill --tolerance 40`     |
+
+> **已知限制**：`crop`、`overlay`、`sprite-split`、`sprite-sheet`、`animate`、`use-vfx`、`segment`、`decompose-layers` 不能在 `--steps` 中使用（`segment` / `decompose-layers` 走后端 API）。需要 `crop` 或分层的批量操作请用 for 循环或 Node.js 脚本。
+
+---
+
+## 2. playcraft image pipeline — YAML/JSON 声明式管线
+
+比 `batch` 更强大：支持配置文件复用、可选自动组装精灵图。
+
+### YAML 配置结构
+
+```yaml
+# ta-workspace/pipeline_config.yaml
+input:
+  dir: assets/images/raw_tiles/
+  glob: '*.png'
+
+steps:
+  - command: resize
+    width: 128
+    height: 128
+  - command: trim
+    threshold: 15
+
+output:
+  dir: assets/images/tiles/
+
+assemble: # 可选：处理完后自动组装精灵图
+  sprite-sheet:
+    output: assets/images/tiles_sprite.png
+    columns: 4
+    padding: 2
+```
+
+执行：`playcraft image pipeline --config ta-workspace/pipeline_config.yaml`（加 `--dry-run` 可预览步骤）
+
+### assemble.sprite-sheet 说明
+
+配置 `assemble.sprite-sheet` 后，pipeline 完成所有文件处理后，会自动将 `output.dir` 下的所有 `*.png` 合并为一张精灵图（同时生成 `.json` 元数据）：
+
+```yaml
+assemble:
+  sprite-sheet:
+    output: assets/images/sprite_atlas.png
+    columns: 4 # 每行帧数
+    padding: 2 # 帧间距（像素）
+    sort: name # 排序方式：name（默认）/ modified / none
+```
+
+---
+
+## 3. 何时用哪种方式（完整决策树）
+
+```
+需要批量处理？
+│
+├─ 需要 AI 生成（generate-image/generate-3d）？
+│   └─ 用 Node.js 脚本（ta-workspace/scripts/*.mjs）
+│       参考：playcraft-image-generation SKILL 的 reference/gen-batch.template.mjs
+│
+├─ 只需要本地图像变换（resize/tint/trim/convert/去背等）？
+│   │
+│   ├─ 需要最终合并成精灵图？
+│   │   └─ 用 pipeline（YAML/JSON 配置 + assemble）
+│   │
+│   ├─ 需要并发加速？
+│   │   └─ 用 batch（--parallel N）
+│   │
+│   ├─ 需要断点续传？
+│   │   └─ 用 batch（--skip-existing）
+│   │
+│   └─ 配置需要复用/版本管理？
+│       └─ 用 pipeline（YAML 文件）
+│
+└─ 需要 crop 作为批处理步骤？
+    └─ 用 for 循环（batch 不支持 crop）：
+       for f in dir/*.png; do
+         playcraft image crop --input "$f" --output "out/$(basename $f)" \
+           --x 0 --y 0 --width 128 --height 128
+       done
+```
+
+---
+
+## 4. 已知限制汇总
+
+| 限制                                               | 影响                                                       | 绕过方法                                      |
+| -------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------- |
+| `batch` 的 `--steps` 不支持 `crop`                 | 无法在批处理管线中裁切                                     | 改用 for 循环或 Node.js 脚本                  |
+| `batch` 不支持 `overlay`（需要两个输入）           | 无法批量合成                                               | 改用 Node.js 脚本                             |
+| `pipeline` 不支持并发（顺序处理）                  | 大批量时较慢                                               | 改用 `batch --parallel`                       |
+| `batch` 输出统一为 `.png`（忽略 convert 步骤后缀） | 即使 steps 中有 `convert --format webp`，文件名仍是 `.png` | pipeline 中用 convert 步骤 + 修改 output 路径 |
+| `remove-background --method ai` 在 batch 中不支持  | 批量 AI 去背报错                                           | 改用 floodfill，或用 Node.js 脚本             |
+
+---
+
+## 5. 配方参考
+
+完整的 batch/pipeline 实用配方（批量 resize、批量去背、主题色变体、精灵图组装管线等）见 `refs/ta-batch-pipeline-recipes.md`。