@playcraft/cli 0.1.40-beta → 0.1.42

package/project-template-v2/.claude/skills/playcraft-asset-state-sheet/SKILL.md

@@ -1,205 +0,0 @@
----
-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-template-v2/.claude/skills/playcraft-audio-generation/SKILL.md

@@ -1,280 +0,0 @@
----
-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-template-v2/.claude/skills/playcraft-batch-pipeline/SKILL.md

@@ -1,184 +0,0 @@
----
-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`。