@playcraft/cli 0.0.39 → 0.0.41

package/project-template/.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），以及完整的音频管线。Designer 和 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/.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`。