@playcraft/skills 0.0.2

package/skills/solitaire.aigameplay/manifest.json

@@ -0,0 +1,151 @@
+{
+  "schemaVersion": 1,
+  "atomId": "solitaire.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "纸牌接龙玩法",
+    "en": "Klondike Solitaire gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "solitaire",
+    "cards",
+    "puzzle",
+    "klondike",
+    "casual"
+  ],
+  "bindingRoles": [
+    "gameplayRule"
+  ],
+  "imports": [
+    {
+      "slot": "engine",
+      "pinAtomId": "phaser.aicomponent",
+      "edgeKind": "requires",
+      "bindAs": "engine"
+    },
+    {
+      "slot": "bgMusic",
+      "description": "背景循环音乐",
+      "bindAs": "bgm",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "bgMusic"
+      ],
+      "allowedBundleTypes": [
+        "aiaudio"
+      ],
+      "constraints": {
+        "loop": true
+      }
+    },
+    {
+      "slot": "cardSet",
+      "description": "扑克牌面贴图集",
+      "bindAs": "cards",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "tileTextureSet"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "tutorial",
+      "description": "新手引导浮层",
+      "bindAs": "tutorial",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "tutorialOverlay"
+      ],
+      "allowedBundleTypes": [
+        "aicomponent"
+      ]
+    },
+    {
+      "slot": "winPanel",
+      "description": "通关反馈面板视觉",
+      "bindAs": "winPanel",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "successFeedbackPanel"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "losePanel",
+      "description": "失败反馈面板视觉",
+      "bindAs": "losePanel",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "failFeedbackPanel"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "endScreen",
+      "description": "可玩广告结算屏（含 CTA 按钮）",
+      "bindAs": "endScreen",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "playableEndScreenLayout"
+      ],
+      "allowedBundleTypes": [
+        "aicomponent"
+      ]
+    }
+  ],
+  "generation": {
+    "kind": "pgs",
+    "pgsVersion": "1.0",
+    "gameplayType": "solitaire",
+    "rules": {
+      "tableauColumns": 7,
+      "foundationPiles": 4,
+      "drawCount": 1,
+      "stockRecycleLimit": -1
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/solitaire/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(action)",
+        "getState()",
+        "canMoveToTableau(state, card, targetCol)",
+        "canMoveToFoundation(state, card)",
+        "moveCards(state, from, to, count)",
+        "drawFromStock(state)",
+        "getValidMoves(state)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

package/skills/solitaire.aigameplay/ref/pgs-schema.json

@@ -0,0 +1,200 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - Klondike 纸牌接龙。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "solitaire",
+  "entities": {
+    "card": {
+      "type": "card-item",
+      "description": "扑克牌，52张标准牌",
+      "fields": {
+        "suit":    { "type": "enum",    "values": ["S", "H", "D", "C"], "description": "花色：S=黑桃，H=红心，D=方块，C=梅花" },
+        "value":   { "type": "integer", "range": [1, 13], "description": "牌值：1=A，11=J，12=Q，13=K" },
+        "face_up": { "type": "boolean", "default": false, "description": "是否翻面（正面朝上）" },
+        "color":   { "type": "enum",    "values": ["red", "black"], "description": "红色=H/D，黑色=S/C" }
+      }
+    },
+    "tableau": {
+      "type": "card-columns",
+      "description": "7列牌堆（主游戏区）",
+      "columns": 7,
+      "initialSetup": "第 i 列（1-indexed）有 i 张牌，最上面1张 face_up，其余 face_down"
+    },
+    "stock": {
+      "type": "card-pile",
+      "description": "备用牌堆（未翻开的剩余牌），点击翻牌到 waste",
+      "face_up": false
+    },
+    "waste": {
+      "type": "card-pile",
+      "description": "翻开的废牌堆，顶牌可用",
+      "face_up": true
+    },
+    "foundations": {
+      "type": "card-piles",
+      "description": "4个花色目标堆，目标是将所有牌按 A→K 移入",
+      "count": 4,
+      "suits": ["S", "H", "D", "C"],
+      "startValue": 1,
+      "endValue": 13
+    }
+  },
+  "rules": {
+    "move_to_tableau": {
+      "description": "将牌（或牌组）移到另一列牌堆顶部",
+      "conditions": [
+        "目标列顶牌 face_up（或目标列为空）",
+        "移动牌颜色与目标列顶牌颜色不同（红↔黑）",
+        "移动牌的值 = 目标列顶牌值 - 1",
+        "空列只接受 K（value == 13）"
+      ],
+      "group_move": "可以将一组连续的有效叠放牌（由顶部的某张 face_up 牌开始向下）一起移动"
+    },
+    "move_to_foundation": {
+      "description": "将牌移到对应花色的目标堆",
+      "conditions": [
+        "目标堆花色 == 移动牌花色",
+        "目标堆为空时只接受 A（value == 1）",
+        "移动牌值 = 目标堆当前顶牌值 + 1"
+      ],
+      "note": "一次只能移动1张牌到目标堆"
+    },
+    "flip_tableau_top": {
+      "description": "移走某列顶牌后，若新的顶牌 face_down，则自动翻开",
+      "trigger": "after_move_from_tableau",
+      "effect": "new_top_card.face_up = true"
+    },
+    "draw_from_stock": {
+      "description": "从备用牌堆翻 1 张牌到 waste 堆（face_up）",
+      "trigger": "player_click_stock",
+      "drawCount": 1
+    },
+    "recycle_stock": {
+      "description": "备用牌堆为空时，点击将 waste 堆整个翻回作为新的备用堆",
+      "trigger": "player_click_empty_stock",
+      "recycleLimit": -1,
+      "effect": "stock = reverse(waste); waste = []"
+    },
+    "auto_complete": {
+      "description": "所有牌都 face_up 时，可以自动将可移动的牌逐一放入目标堆",
+      "trigger": "all_cards_face_up",
+      "effect": "auto_move_to_foundations_until_win"
+    }
+  },
+  "algorithm": {
+    "description": "主循环：player selects card → validate move → execute move → flip top → check win",
+    "steps": [
+      "1. 玩家选择一张或一组牌（从 tableau/waste）",
+      "2. 玩家选择目标位置（tableau 列 / foundation 堆）",
+      "3. 验证移动合法性（颜色交替降序 / 同花色升序）",
+      "4. 执行移牌：从源位置移除，添加到目标位置",
+      "5. 若源为 tableau 且新顶牌 face_down → 翻开",
+      "6. 若为翻牌操作：stock 顶牌移到 waste（face_up）",
+      "7. 检测胜利：4个 foundation 堆都满（各13张，A→K）",
+      "8. 若所有牌都 face_up → 触发 auto_complete 提示"
+    ]
+  },
+  "winCondition": {
+    "type": "all_in_foundations",
+    "description": "4个花色目标堆各有13张牌（A到K），共52张"
+  },
+  "loseCondition": {
+    "type": "no_valid_moves",
+    "description": "（可选检测）无任何合法移动且 stock 为空且 waste 仅剩无法移动的牌"
+  },
+  "testCases": [
+    {
+      "id": "tc_move_to_tableau",
+      "description": "合法移牌：红色5放到黑色6上",
+      "initialState": {
+        "tableau": {
+          "col_0": [
+            { "suit": "H", "value": 5, "face_up": true, "color": "red" }
+          ],
+          "col_1": [
+            { "suit": "S", "value": 7, "face_up": false },
+            { "suit": "C", "value": 6, "face_up": true, "color": "black" }
+          ]
+        },
+        "foundations": { "S": [], "H": [], "D": [], "C": [] },
+        "stock": [],
+        "waste": []
+      },
+      "actions": [
+        { "type": "move_cards", "from": { "zone": "tableau", "col": 0 }, "to": { "zone": "tableau", "col": 1 }, "count": 1 }
+      ],
+      "expectedState": {
+        "tableau.col_0": [],
+        "tableau.col_1_top": { "suit": "H", "value": 5, "face_up": true }
+      }
+    },
+    {
+      "id": "tc_move_to_foundation",
+      "description": "移牌到目标堆：A先进，再放2",
+      "initialState": {
+        "tableau": {
+          "col_0": [
+            { "suit": "S", "value": 2, "face_up": true, "color": "black" }
+          ]
+        },
+        "foundations": { "S": [{ "suit": "S", "value": 1, "face_up": true }], "H": [], "D": [], "C": [] },
+        "stock": [],
+        "waste": []
+      },
+      "actions": [
+        { "type": "move_cards", "from": { "zone": "tableau", "col": 0 }, "to": { "zone": "foundation", "suit": "S" }, "count": 1 }
+      ],
+      "expectedState": {
+        "foundations.S": [
+          { "suit": "S", "value": 1 },
+          { "suit": "S", "value": 2 }
+        ],
+        "tableau.col_0": []
+      }
+    },
+    {
+      "id": "tc_draw_from_stock",
+      "description": "从备用堆翻牌到 waste",
+      "initialState": {
+        "tableau": { "col_0": [], "col_1": [], "col_2": [], "col_3": [], "col_4": [], "col_5": [], "col_6": [] },
+        "foundations": { "S": [], "H": [], "D": [], "C": [] },
+        "stock": [
+          { "suit": "D", "value": 9, "face_up": false },
+          { "suit": "H", "value": 3, "face_up": false }
+        ],
+        "waste": []
+      },
+      "actions": [
+        { "type": "draw_from_stock" }
+      ],
+      "expectedState": {
+        "stock_count": 1,
+        "waste_top": { "suit": "H", "value": 3, "face_up": true }
+      }
+    },
+    {
+      "id": "tc_flip_after_move",
+      "description": "移走顶牌后，下方 face_down 牌自动翻开",
+      "initialState": {
+        "tableau": {
+          "col_0": [
+            { "suit": "C", "value": 8, "face_up": false },
+            { "suit": "H", "value": 5, "face_up": true, "color": "red" }
+          ],
+          "col_1": [
+            { "suit": "S", "value": 6, "face_up": true, "color": "black" }
+          ]
+        },
+        "foundations": { "S": [], "H": [], "D": [], "C": [] },
+        "stock": [],
+        "waste": []
+      },
+      "actions": [
+        { "type": "move_cards", "from": { "zone": "tableau", "col": 0 }, "to": { "zone": "tableau", "col": 1 }, "count": 1 }
+      ],
+      "expectedState": {
+        "tableau.col_0_top": { "suit": "C", "value": 8, "face_up": true },
+        "lastFlipped": true
+      }
+    }
+  ]
+}

package/skills/solitaire.aigameplay/ref/reducer.template.ts

@@ -0,0 +1,176 @@
+/**
+ * solitaire.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，适用于无头测试。
+ * 渲染层需要在移牌前先验证合法性（canMoveToTableau/canMoveToFoundation），
+ * 再执行 moveCards，然后根据 lastFlipped 决定是否播放翻牌动画。
+ * 不要用 dispatch 然后全量重建所有牌精灵——这会破坏动画连续性。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type SolitaireConfig = {
+  /** 每次翻牌数量，默认 1（Klondike）或 3（Vegas） */
+  drawCount: number;
+  /** 翻牌堆循环限制，-1 = 无限，0 = 不可循环 */
+  stockRecycleLimit: number;
+  /** 是否自动将可用的牌移到目标堆（auto-complete 提示） */
+  autoComplete: boolean;
+};
+
+// ─── 核心类型 ─────────────────────────────────────────────────────────────────
+
+export type Suit = 'S' | 'H' | 'D' | 'C';  // 黑桃、红心、方块、梅花
+export type CardColor = 'red' | 'black';
+export type CardValue = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
+
+export type Card = {
+  suit: Suit;
+  value: CardValue;  // 1=A, 11=J, 12=Q, 13=K
+  faceUp: boolean;
+  color: CardColor;  // H/D=red, S/C=black
+};
+
+/** 移牌来源/目标位置 */
+export type ZoneRef =
+  | { zone: 'tableau'; col: number }      // 7 列牌堆，col 0~6
+  | { zone: 'foundation'; suit: Suit }    // 4 个花色目标堆
+  | { zone: 'waste' };                    // 废牌堆顶
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type SolitaireAction =
+  | { type: 'move_cards'; from: ZoneRef; to: ZoneRef; count: number }
+  | { type: 'draw_from_stock' }
+  | { type: 'recycle_stock' }
+  | { type: 'auto_complete' }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type SolitaireState = {
+  /** 7 列牌堆，tableau[col] = Card[] 从底到顶 */
+  tableau: Card[][];
+  /** 备用牌堆（未翻开），stock[0] 是顶部 */
+  stock: Card[];
+  /** 废牌堆（已翻开），waste[waste.length-1] 是顶部 */
+  waste: Card[];
+  /** 4 个花色目标堆，foundations[suit] = Card[] 从 A 到顶 */
+  foundations: Record<Suit, Card[]>;
+  /** 翻牌堆已循环次数 */
+  stockRecycleCount: number;
+  /** 游戏是否结束 */
+  gameOver: boolean;
+  /** 是否胜利（所有牌进入 foundations） */
+  win: boolean;
+  /** 上一次操作是否触发了自动翻牌 */
+  lastFlipped: boolean;
+  /** 上一次翻开的牌所在列（用于渲染层播放翻牌动画） */
+  lastFlippedCol: number | null;
+  /** 所有牌是否都已翻面（触发 auto-complete 提示） */
+  allFaceUp: boolean;
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** 合法移动描述 */
+export type ValidMove = {
+  from: ZoneRef;
+  to: ZoneRef;
+  count: number;
+  /** 是否为移到 foundation 的操作（通常优先级更高） */
+  toFoundation: boolean;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：初始化 Klondike 纸牌接龙
+ * - 随机洗52张牌
+ * - 第 i 列（1-indexed）发 i 张牌，最顶部翻面
+ * - 剩余牌放入 stock
+ */
+export declare function init(config: SolitaireConfig): SolitaireState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: SolitaireState, action: SolitaireAction): SolitaireState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: SolitaireState): SolitaireState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * canMoveToTableau：验证将指定牌移到目标列是否合法
+ * 规则：颜色交替（红↔黑），数值 = 目标列顶牌值 - 1；空列只接受 K
+ *
+ * 渲染层在玩家拖动牌到列时调用，若返回 false 则播放弹回动画
+ */
+export declare function canMoveToTableau(
+  state: SolitaireState,
+  card: Card,
+  targetCol: number,
+): boolean;
+
+/**
+ * canMoveToFoundation：验证将指定牌移到目标堆是否合法
+ * 规则：同花色，值 = 目标堆顶牌值 + 1；空堆只接受 A（value == 1）
+ *
+ * 渲染层在玩家双击牌时调用，自动移到 foundation
+ */
+export declare function canMoveToFoundation(
+  state: SolitaireState,
+  card: Card,
+): boolean;
+
+/**
+ * moveCards：执行移牌操作
+ * - 支持从 tableau/waste 移到 tableau/foundation
+ * - 移完后自动翻开源列新顶牌（若 faceDown）
+ * - 更新 lastFlipped 和 lastFlippedCol
+ * - 检测胜利条件
+ *
+ * 渲染层在验证合法后调用，根据 lastFlipped 决定是否播放翻牌动画
+ */
+export declare function moveCards(
+  state: SolitaireState,
+  from: ZoneRef,
+  to: ZoneRef,
+  count: number,
+): SolitaireState;
+
+/**
+ * drawFromStock：从备用堆翻 drawCount 张牌到 waste（faceUp）
+ * 若 stock 为空则循环（受 stockRecycleLimit 限制）
+ *
+ * 渲染层在玩家点击备用堆时调用，播放翻牌动画
+ */
+export declare function drawFromStock(state: SolitaireState): SolitaireState;
+
+/**
+ * getValidMoves：获取当前状态下所有合法的移动
+ * 用于：1) AI 自动解牌；2) 检测是否无解（no valid moves）；3) 提示功能
+ *
+ * 性能注意：完整扫描所有组合，不要在每帧调用
+ */
+export declare function getValidMoves(state: SolitaireState): ValidMove[];

package/skills/sound-effects/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: sound-effects
+description: 通过 playcraft CLI 生成音效（SFX）；--prompt 仅支持英文。含时长、循环等 CLI 参数与英文提示词写法，与 playcraft-audio-generation 配合。
+license: MIT
+source: https://github.com/elevenlabs/skills/tree/main/sound-effects
+compatibility: agent,opencode
+---
+
+# 音效生成（SFX）— CLI 与提示词
+
+用**英文文字描述**生成短音效（平台后端走 ElevenLabs Sound Effects，**不是**语音 TTS）。你在沙箱里**只使用 `playcraft tools generate-sfx`**；云端认证与厂商侧配置由平台处理，**无需也不应**在技能文档或命令中涉及密钥、环境变量或自行调用厂商 HTTP/SDK。
+
+## 语言（必须遵守）
+
+**`--prompt` 只支持英文。** 不要用中文或其他语言写 SFX 描述：模型对非英文支持差，易出现杂音、语义跑偏或听感像念白。若用户给中文需求，先在心里翻译成简洁英文短语再写入 `--prompt`。
+
+## CLI
+
+```bash
+playcraft tools generate-sfx \
+  --prompt "<English only, see Prompt Tips below>" \
+  [--duration <秒>] \
+  [--loop] \
+  --output <路径>
+```
+
+| CLI 选项 | 说明 |
+|----------|------|
+| `--prompt` | 必填，**仅英文**音效描述 |
+| `--duration` | 可选，约 0.5–30 秒 |
+| `--loop` | 可选，可循环音效 |
+| `--output` | 必填，保存路径（如 `./assets/audio/click.mp3`） |
+
+生成 BGM 用 `playcraft tools generate-bgm`（见 `playcraft-audio-generation`）。
+
+## Prompt Tips（英文 `--prompt`，优先遵守）
+
+- 具体化："Heavy rain on a tin roof" 优于 "Rain"
+- 组合层次："Footsteps on gravel with distant traffic"
+- 标明风格："Cinematic braam, horror" 或 "8-bit retro jump sound"
+- 情绪与场景："Eerie wind howling through an abandoned building"
+- 使用**非对白、偏拟声/材质/场景**的短语；长句口语容易听起来像念稿（虽非 TTS API）
+
+## 失败时
+
+根据 CLI 报错判断：参数问题则改 `--prompt` / `--duration`；若提示权限、额度或上游不可用，向用户说明需**在平台侧**检查配置或配额——**不要**尝试自行配置密钥或直连厂商 API。

package/skills/sound_utils.aicomponent/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sound_utils.aicomponent
+description: 音频工具函数。提供 safePlaySound() 封装，自动处理音效键不存在时的静默失败，并根据用户设置的静音状态决定是否播放。
+triggers: 需要在游戏中安全播放音效（避免缺失音效导致异常）时触发。
+---
+
+# 音频工具函数（Sound Utilities）
+
+## Scaffold
+
+`src/game/utils/SoundUtils.ts`
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖：Phaser SoundManager API）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/utils/SoundUtils.ts
+outputs:
+  - safePlaySound: function(scene, key, config?) - safe audio playback wrapper
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **静默失败而非抛错** | 资产键缺失（如音效文件未加载）不应中断游戏进程；在试玩广告中，音效缺失是可接受的降级，崩溃不可接受 |
+| **尊重静音设置** | SFX 播放必须检查 `settings.soundOn`，否则用户关闭音效后仍会发声，体验问题在发布时暴露 |
+| **从 phaser.aicomponent 中抽出** | `phaser.aicomponent` 已内置基础版 `SoundUtils.ts`；本 skill 在需要更复杂音频管理（如 BGM 队列）时作为增强版单独加载 |
+
+## Adapter
+
+- **Role**: `soundUtils` — Phaser 安全音效播放封装
+- **Provides**: `safePlaySound(scene, key, config?)` 函数
+- **Requires**: `phaser.aicomponent`（硬依赖：Phaser SoundManager API）
+- **Consumed by**: `game_scene.aicomponent`、`level_lifecycle.aicomponent`、`path_input_handler.aicomponent` 等所有需要播放 SFX 的 skill
+- **Integration point**: `src/game/utils/SoundUtils.ts` —— 在任意 Phaser Scene 中 `import { safePlaySound }` 后使用
+
+## 使用示例
+
+```typescript
+import { safePlaySound } from '../utils/SoundUtils';
+
+safePlaySound(this, 'click', { volume: 1.0 });
+safePlaySound(this, 'bg', { loop: true, volume: 0.8 });
+```

package/skills/sound_utils.aicomponent/manifest.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 1,
+  "atomId": "sound_utils.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "util",
+  "mode": "fixed",
+  "label": { "zh": "音频工具函数", "en": "Sound utility functions" },
+  "tags": ["util", "audio", "sound", "safe-play", "phaser"],
+  "bindingRoles": ["audioPlayHelper"],
+  "scaffold": {
+    "files": {
+      "src/game/utils/SoundUtils.ts": { "source": "ref/SoundUtils.ts", "mode": "full", "weight": 10 }
+    }
+  },
+  "imports": [
+    { "slot": "engine", "pinAtomId": "phaser.aicomponent", "edgeKind": "requires", "bindAs": "engine" }
+  ],
+  "exports": [
+    { "name": "safePlaySound", "kind": "function", "location": "src/game/utils/SoundUtils.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "utility wrapper for Phaser audio playback that safely handles missing sound keys and settings-based muting"
+  },
+  "usageHints": [
+    "safePlaySound(scene, key, config?) 在音效不存在时静默失败（不抛异常）",
+    "自动检查 settings.soundOn，静音状态下跳过播放",
+    "在 InputHandler / LevelLifecycle / AnimationManager 中广泛使用"
+  ],
+  "files": { "skill": "SKILL.md", "soundUtils": "ref/SoundUtils.ts" }
+}