@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/skills/playcraft-art-style-guide/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: playcraft-art-style-guide
+description: 可玩广告美术风格选择与应用指南。涵盖 9 种主流风格的视觉特征、选型决策树（按游戏类型/受众/品牌调性）、风格对生产流水线的影响、以及各风格的 prompt 核心策略。Designer 在 Phase 1 确定美术方向前必读。
+triggers: 美术风格,art style,像素风,pixel art,写实,realistic,卡通,cartoon,扁平,flat,科技风,tech,科幻,sci-fi,赛博朋克,cyberpunk,奇幻,fantasy,中国风,chinese,水彩,watercolor,手绘,Q版,chibi,风格选择,style direction,视觉风格
+---
+
+# PlayCraft 美术风格选择与应用指南
+
+## 0. 风格选择的设计思考
+
+美术风格不是"好看就行"——它直接影响：
+
+- **CTR 表现**：风格与目标受众的审美期待是否匹配
+- **生产成本**：不同风格对 AI 生图质量要求和后处理复杂度差异极大
+- **文件体积**：像素风天然小，写实风天然大——直接影响 5MB 预算分配
+- **TA 管线**：像素风需要整数倍缩放 + 限色板；写实风需要高分辨率 + 精细抠图
+
+**风格决策时机**：PM 在 `design-brief.md` 的 StyleDirection 中定义方向，Designer 在 Phase 1 具体化并生成样本验证。
+
+---
+
+## 1. 风格选型决策树
+
+```
+游戏类型 + 目标受众？
+│
+├─ 休闲消除/益智 + 全年龄
+│   ├─ 追求高辨识度/IP感 → Q版/Chibi
+│   ├─ 追求简洁现代 → 扁平卡通
+│   └─ 追求怀旧/独特 → 像素风
+│
+├─ 卡牌/棋牌/麻将 + 成年用户
+│   ├─ 中国市场 → 中国传统风
+│   ├─ 全球市场/高端感 → 写实/半写实
+│   └─ 年轻用户/轻量感 → 扁平卡通
+│
+├─ 动作/射击/跑酷 + 年轻男性
+│   ├─ 现代/都市 → 赛博朋克/科技风
+│   ├─ 太空/未来 → 科幻风
+│   └─ 魔法/剑与盾 → 奇幻风
+│
+├─ 模拟经营/养成 + 女性/全年龄
+│   ├─ 追求温暖治愈 → 水彩/手绘
+│   ├─ 追求可爱萌系 → Q版/Chibi
+│   └─ 追求清新文艺 → 扁平卡通
+│
+└─ RPG/冒险 + 核心玩家
+    ├─ 西方奇幻 → 奇幻风
+    ├─ 东方仙侠 → 中国传统风
+    └─ 暗黑/硬核 → 写实/半写实
+```
+
+---
+
+## 2. 九种风格速览
+
+| #   | 风格                | 视觉特征                             | 体积倾向 | AI 生图难度      | 最佳模型             |
+| --- | ------------------- | ------------------------------------ | -------- | ---------------- | -------------------- |
+| 1   | **像素风**          | 方块化、限色板(8-32色)、无抗锯齿     | 极小     | 中（需严格限色） | gpt-image-2          |
+| 2   | **扁平卡通**        | 粗描边、纯色填充、几何化、无渐变阴影 | 小       | 低               | 任意模型             |
+| 3   | **Q版/Chibi**       | 大头身比(2-3头)、圆润形状、夸张表情  | 小-中    | 低               | 任意模型             |
+| 4   | **写实/半写实**     | 真实光影、材质细节、自然比例         | 大       | 高（细节要求高） | gpt-image-2          |
+| 5   | **中国传统风**      | 水墨笔触、留白、金色装饰、书法元素   | 中       | 中（需文化细节） | gpt-image-2          |
+| 6   | **赛博朋克/科技风** | 霓虹光、暗底、几何线条、HUD 叠加     | 中       | 中               | gpt-image-2 / gemini |
+| 7   | **科幻风**          | 金属质感、星空、全息UI、冷色调       | 中       | 中               | gpt-image-2          |
+| 8   | **奇幻/魔法**       | 发光粒子、魔法阵、饱和色彩、神秘光   | 中-大    | 中               | gpt-image-2          |
+| 9   | **水彩/手绘**       | 纸质纹理、渗透感、不规则边缘、柔和   | 中       | 中（边缘控制难） | gpt-image-2          |
+
+---
+
+## 3. 风格对 TA 管线的影响
+
+| 风格        | 缩放策略                              | 抠图难度          | VFX 适配                 | 特殊注意                        |
+| ----------- | ------------------------------------- | ----------------- | ------------------------ | ------------------------------- |
+| 像素风      | 整数倍(`--scale 2/4/8`)，禁止分数缩放 | 低（硬边）        | `pixelate` 后 VFX        | 缩放后禁用抗锯齿                |
+| 扁平卡通    | 任意缩放                              | 低（粗描边清晰）  | 所有 VFX 兼容            | 描边粗细要统一                  |
+| Q版/Chibi   | 任意缩放                              | 低-中             | 所有 VFX 兼容            | 头身比一致性                    |
+| 写实/半写实 | 只降不升(原图需高分辨率)              | 高（毛发/半透明） | 写实 VFX 慎用卡通预设    | 需 AI 去背(--method ai)         |
+| 中国传统风  | 任意缩放                              | 中（水墨渐变边）  | glow/sparkle 适合        | 文字必须楷体/行书               |
+| 赛博朋克    | 任意缩放                              | 中（发光溢出）    | glow/starburst 适合      | 发光边缘保留，不要过度 trim     |
+| 科幻风      | 任意缩放                              | 中                | glow/impact_ring 适合    | 金属质感需 reference-image 锁定 |
+| 奇幻/魔法   | 任意缩放                              | 中（魔法粒子）    | sparkle/glow/starburst   | 粒子效果保留半透明              |
+| 水彩/手绘   | 任意缩放                              | 高（不规则边缘）  | 慎用——VFX 可能破坏手绘感 | trim threshold 要高(30+)        |
+
+---
+
+## 4. Prompt 核心策略（按风格）
+
+每种风格的 prompt 都遵循公式：`[主体] + [风格关键词] + [技术约束] + [负面约束]`
+
+| 风格      | 核心关键词                                                                     | 必加约束                | 必加负面                                              |
+| --------- | ------------------------------------------------------------------------------ | ----------------------- | ----------------------------------------------------- |
+| 像素风    | `pixel art, 8-bit, limited N-color palette, sharp pixels, no anti-aliasing`    | 指定色板数量            | `no smooth gradients, no anti-aliasing, no blur`      |
+| 扁平卡通  | `flat 2D vector, bold outlines, solid color fills, minimal shading`            | 描边粗细(如 3px)        | `no gradient, no 3D effect, no realistic shading`     |
+| Q版/Chibi | `chibi style, cute, 2.5-head proportion, round shapes, big eyes`               | 头身比                  | `no realistic proportion, no thin limbs`              |
+| 写实      | `photorealistic, detailed textures, natural lighting, high resolution`         | 光源方向                | `no cartoon, no flat color, no cel-shading`           |
+| 中国传统  | `Chinese traditional ink painting, brush strokes, elegant, gold accents`       | 留白比例                | `no western fantasy, no neon, no modern UI`           |
+| 赛博朋克  | `cyberpunk, neon glow, dark background, holographic, circuit patterns`         | 发光色(如 cyan/magenta) | `no nature, no warm colors, no daylight`              |
+| 科幻      | `sci-fi, metallic surfaces, space, holographic UI, cold blue lighting`         | 材质(金属/玻璃)         | `no organic textures, no warm wood, no fantasy magic` |
+| 奇幻      | `fantasy art, magical glow, ethereal, mystical atmosphere, rich colors`        | 光源类型(魔法光)        | `no modern technology, no sci-fi, no urban`           |
+| 水彩      | `watercolor painting, soft edges, paper texture, transparent washes, artistic` | 纸张纹理                | `no hard edges, no digital look, no sharp outlines`   |
+
+---
+
+## 5. 风格一致性检查点
+
+生成样本后，对照以下维度确认风格执行是否到位：
+
+| 维度     | 检查方法                     | 不通过时调整             |
+| -------- | ---------------------------- | ------------------------ |
+| **色板** | 肉眼对比概念图主色           | prompt 加具体 hex 值     |
+| **描边** | 放大看边缘处理               | 加/减 `bold outline Npx` |
+| **光影** | 对比光源方向和阴影风格       | 明确光照描述             |
+| **材质** | 对比表面纹理(哑光/光泽/粗糙) | 加材质修饰词             |
+| **比例** | 对比元素间大小关系           | 加尺寸约束描述           |
+
+---
+
+## 6. 详细参考
+
+每种风格的完整 prompt 示例、模型推荐、TA 管线详细配置、常见错误与修正：
+
+> **Read `refs/designer-art-style-catalog.md`**

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

@@ -0,0 +1,141 @@
+---
+name: playcraft-asset-state-sheet
+description: PlayCraft 资产状态参考精灵图板（ASR / Asset State Reference Sheet）生成指南。Designer 在 Gate #2a 后输出两张 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. 前置条件（硬门禁）
+
+- **仅在 Gate #2a 通过、`selectedMcOption` 已写入 `project-state.md` 之后** 才能生成 ASR
+- **禁止**为未选中的 MC 方案生成 ASR
+- 两张板均使用已确认 MC 作 `--reference-image`，且 `--image-model` 与 MC 一致
+
+## 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）。
+
+### 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 概念面板里出现的玩法元素）
+- 每个元素类型 **2–3 个代表状态**（完整全集由 TA 在 `production` 扩展），例如：
+  - `tile_gold`: idle | selected | matched
+  - `panda_char`: idle | happy | win
+
+**元素总数**：每张板独立统计，每板 **8–12 个状态槽**（宁可少槽、加大间距，也不要重叠）。
+
+## 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 模板
+
+**UI 板** — 在 prompt 中显式写 `UI component state reference sprite sheet`：
+
+```
+UI component state reference sprite sheet for [GAME_TYPE] playable ad.
+3840x1152 canvas, [BG_COLOR] flat background.
+
+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.
+
+Row 1 — CTA / HUD:
+- CTA install button, default state: ...
+- CTA install button, pressed state: ...
+...
+
+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].
+[same STRICT LAYOUT block]
+
+Row 1 — Core tiles/items:
+- [Element] idle: ...
+- [Element] selected: ...
+- [Element] matched: ...
+...
+
+Art style: [SAME as Master Composite].
+```
+
+**Prompt 必须包含**：`sprite sheet` 或 `state reference sheet`、`STRICT LAYOUT`、`non-overlapping cells`、具体 gap 像素。
+
+## 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
+```
+
+## 5. 核查清单
+
+| #   | 核查项 | 标准                                     |
+| --- | ------ | ---------------------------------------- |
+| 1   | 时机   | `selectedMcOption` 已设置                |
+| 2   | 数量   | UI 板 + 元素板各一张                     |
+| 3   | 视觉   | 两板均无重叠；有重叠则重生成             |
+| 4   | 语义   | UI 板无玩法棋子；元素板无整屏 HUD 截屏   |
+| 5   | 清单   | `designer-log` 含每张板的状态→槽位映射表 |
+
+## 6. 与 TA 的协作协议
+
+Designer：风格与 MC 一致；在 `designer-log.md` 标注每张 ASR **已覆盖的状态** vs **TA 需扩展的状态**。
+
+TA 提取（详见 `playcraft-masking`）：
+
+| 来源图               | 推荐方式                   | 说明                                                                                |
+| -------------------- | -------------------------- | ----------------------------------------------------------------------------------- |
+| **ASR**（规则网格）  | `playcraft image crop`     | 槽位坐标来自 `designer-log` ASR State Inventory；**禁止**对 ASR 用纯 text `segment` |
+| **Master Composite** | `decompose-layers` 或 crop | ASR 未覆盖的类型从此补提取                                                          |

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