@playcraft/skills 0.0.2

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

@@ -0,0 +1,166 @@
+/**
+ * car_parking.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部执行完整的移动+胜利检测后只返回最终状态。
+ * 渲染层需要知道具体哪辆车移动了多少格才能播放位移动画，
+ * 因此必须使用下方的「分步函数」逐步驱动。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、快速验证关卡可解性。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type CarParkingConfig = {
+  /** 棋盘列数，默认 6 */
+  cols: number;
+  /** 棋盘行数，默认 6 */
+  rows: number;
+  /** 初始车辆配置 */
+  cars: CarConfig[];
+  /** 出口位置 */
+  exit: { col: number; row: number };
+};
+
+export type CarConfig = {
+  /** 车辆唯一标识 */
+  id: string;
+  /** 朝向：H=水平，V=垂直 */
+  orientation: 'H' | 'V';
+  /** 初始占据格子坐标 */
+  cells: Array<{ col: number; row: number }>;
+  /** 车辆颜色/显示类型 */
+  color: string;
+  /** 是否为目标车（需移至出口） */
+  isTarget: boolean;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type CarParkingAction =
+  | { type: 'move_car'; carId: string; steps: number }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type Car = {
+  id: string;
+  orientation: 'H' | 'V';
+  /** 当前占据格子坐标（按朝向排序，从小到大） */
+  cells: Array<{ col: number; row: number }>;
+  color: string;
+  isTarget: boolean;
+};
+
+export type CarParkingState = {
+  /** 棋盘尺寸 */
+  cols: number;
+  rows: number;
+  /** 所有车辆当前状态 */
+  cars: Car[];
+  /** 出口位置 */
+  exit: { col: number; row: number };
+  /** 游戏是否结束 */
+  gameOver: boolean;
+  /** 是否胜利 */
+  win: boolean;
+  /** 已执行的移动步数（用于评分） */
+  moveCount: number;
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** getCarMoveRange 返回值：该车可移动的范围（负=向左/上，正=向右/下） */
+export type MoveRange = {
+  /** 可向负方向（左/上）移动的最大格数（负数，如 -2 表示最多向左2格） */
+  minSteps: number;
+  /** 可向正方向（右/下）移动的最大格数（正数，如 3 表示最多向右3格） */
+  maxSteps: number;
+};
+
+/** isBlocked 检测方向 */
+export type BlockDirection = 'positive' | 'negative';
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态
+ */
+export declare function init(config: CarParkingConfig): CarParkingState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - move_car：移动指定车辆指定步数，检测胜利条件
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: CarParkingState, action: CarParkingAction): CarParkingState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: CarParkingState): CarParkingState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * getCarMoveRange：查询指定车辆在当前状态下可移动的步数范围。
+ *
+ * 场景层在玩家按下/拖动某辆车时调用，用于限制拖动范围。
+ * minSteps <= 0 <= maxSteps，均值为0时表示该车完全被阻挡（四面无路）。
+ *
+ * @param state   当前游戏状态
+ * @param carId   目标车辆 ID
+ * @returns       可移动范围 { minSteps（负=向左/上）, maxSteps（正=向右/下）}
+ */
+export declare function getCarMoveRange(state: CarParkingState, carId: string): MoveRange;
+
+/**
+ * moveCar：执行车辆移动，返回新状态。
+ *
+ * 场景层在确认移动格数后调用（应先经过 getCarMoveRange 验证 steps 在合法范围内）。
+ * 返回的新状态中 cars 已更新，win 字段已反映胜利检测结果。
+ *
+ * @param state   当前游戏状态（不可变）
+ * @param carId   目标车辆 ID
+ * @param steps   移动步数（正=向右/下，负=向左/上）
+ * @returns       更新后的游戏状态
+ */
+export declare function moveCar(state: CarParkingState, carId: string, steps: number): CarParkingState;
+
+/**
+ * checkWin：检测目标车是否已到达出口。
+ *
+ * 场景层在每次 moveCar 动画播放完毕后调用，判断是否触发胜利演出。
+ *
+ * @param state   当前游戏状态
+ * @returns       true 表示目标车已到达出口
+ */
+export declare function checkWin(state: CarParkingState): boolean;
+
+/**
+ * isBlocked：检测指定车辆在给定方向上是否被阻挡（无法移动）。
+ *
+ * 场景层可用于显示"该车无法移动"的视觉反馈（如抖动动画）。
+ *
+ * @param state      当前游戏状态
+ * @param carId      目标车辆 ID
+ * @param direction  检测方向：'positive'（右/下）或 'negative'（左/上）
+ * @returns          true 表示该方向完全被阻挡
+ */
+export declare function isBlocked(state: CarParkingState, carId: string, direction: BlockDirection): boolean;

package/skills/castle.aiimage/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: castle.aiimage
+description: 城堡背景图封包 - 奇幻城堡/中世纪场景，适合逃脱益智类游戏的史诗风格背景贴图
+triggers: 城堡,castle,奇幻,fantasy,中世纪,medieval,背景,background,宫殿,palace
+---
+
+# castle.aiimage
+
+奇幻城堡主题背景图封包。适合逃脱益智、停车逃脱等类型游戏，营造史诗奇幻氛围。
+
+## Recipe
+
+- **基础 prompt**：`majestic fantasy castle on a hill, mystical atmosphere, casual mobile game style, flat design, vibrant colors, blue sky`
+- **宽高比**：9:16
+- **风格**：cartoon / flat design
+- **可 fork 变体**：
+  - 黑暗城堡：`dark gothic castle, ominous clouds, bats, dramatic lighting`
+  - 冰雪城堡：`ice crystal palace, frozen landscape, blue and white tones`
+  - 废墟城堡：`ruined castle, overgrown with vines, mysterious fog`
+
+**生成步骤：**
+1. 确认尺寸约束（1080×1920 PNG）
+2. 调用图像生成 API
+3. 验证输出尺寸 ≥ 1080px 宽
+4. 写入 `background.png`，更新 manifest
+
+## Result
+
+- **产物文件**：`background.png`
+- **格式**：PNG，最小 1080×1920
+
+## Binding
+
+- **Binding Role**：`backgroundTexture`
+- **挂载目标**：`scene://entities/Background/element/textureAsset`
+- **引用类型**：`texture-asset-reference`
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "majestic fantasy castle on a hill, mystical atmosphere, casual mobile game style, flat design, vibrant colors, blue sky" \
+     --aspect-ratio 9:16 \
+     --image-model google/imagen-3.0-generate-002 \
+     --output ta-workspace/raw.png
+
+# 2. 后处理（去白底 + 格式转换）
+playcraft image remove-background --input ta-workspace/raw.png --output ta-workspace/trimmed.png
+playcraft image convert --input ta-workspace/trimmed.png --output ta-workspace/background.webp --quality 85
+
+# 3. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are generating a castle background image for a mobile game.
+  Follow the Recipe to call the image generation API. Verify output meets Result constraints, then apply Binding.

package/skills/castle.aiimage/manifest.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "atomId": "castle.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "城堡背景",
+    "en": "Castle background"
+  },
+  "tags": [
+    "background",
+    "visual",
+    "castle",
+    "fantasy",
+    "medieval",
+    "epic"
+  ],
+  "bindingRoles": ["backgroundTexture"],
+  "generation": {
+    "kind": "image",
+    "prompt": "majestic fantasy castle on a hill, mystical atmosphere, casual mobile game style, flat design, vibrant colors, blue sky",
+    "aspectRatio": "9:16",
+    "model": "google/imagen-3.0-generate-002",
+    "style": "cartoon",
+    "platformSkill": "playcraft-image-generation"
+  },
+  "result": {
+    "outputFile": "background.png",
+    "format": "png",
+    "constraints": {
+      "minWidth": 1080,
+      "minHeight": 1920
+    }
+  },
+  "binding": {
+    "role": "backgroundTexture",
+    "target": "scene://entities/Background/element/textureAsset",
+    "type": "texture-asset-reference",
+    "constraints": {
+      "format": "png",
+      "minWidth": 1080
+    }
+  },
+  "files": {
+    "skill": "SKILL.md"
+  }
+}

package/skills/cheerful_ukulele.aiaudio/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: cheerful_ukulele.aiaudio
+description: 轻快尤克里里 BGM 封包 - 热带轻松氛围的循环背景音乐，适合休闲消除类游戏
+triggers: 背景音乐,bgm,轻快,cheerful,尤克里里,ukulele,休闲,casual,循环,loop,热带
+---
+
+# cheerful_ukulele.aiaudio
+
+轻快尤克里里主题 BGM (Background Music, 背景音乐) 封包。营造轻松愉快的休闲游戏氛围，适合三消、分类排序等节奏平缓的玩法。
+
+## Recipe
+
+- **基础 prompt**：`cheerful upbeat ukulele loop, casual mobile game background music, tropical feel, light percussion, 120 BPM`
+- **时长**：30 秒（循环）
+- **BPM**：约 120
+- **风格**：轻快、热带、节奏感轻柔
+- **可 fork 变体**：
+  - 更欢快：提高 BPM 到 140，加入更多打击乐
+  - 更轻柔：降低 BPM 到 90，以钢琴为主
+  - 节日版：加入铃声和节庆元素
+
+**生成步骤：**
+1. 确认目标时长和循环点（默认 30s）
+2. 调用音频生成 API，传入 prompt 和时长参数
+3. 验证输出时长在 15-60s 范围内
+4. 写入 `audio.mp3`，更新 manifest 中的 `generation.seed`
+
+## Result
+
+- **产物文件**：`audio.mp3`
+- **格式**：MP3
+- **时长**：15-60 秒（循环无缝）
+- **引用方式**：通过 `manifest.json.result.outputFile` 引用
+
+## Binding
+
+- **Binding Role**：`backgroundMusic`
+- **挂载目标**：`scene://entities/AudioManager/bgm/asset`
+- **引用类型**：`audio-asset-reference`
+- **播放模式**：loop（无缝循环）
+
+## 生成方式
+
+Platform Skill: `playcraft-audio-generation`
+
+```bash
+# 1. 生成 BGM（Google Lyria 3，固定 30s）
+playcraft tools generate-bgm \
+     --prompt "cheerful upbeat ukulele loop, casual mobile game background music, tropical feel, light percussion, 120 BPM" \
+     --style casual \
+     --bpm 120 \
+     --output ta-workspace/raw_bgm.mp3
+
+# 2. 处理无缝循环 + 归一化
+playcraft audio loop --input ta-workspace/raw_bgm.mp3 --output ta-workspace/bgm_loop.mp3 --crossfade 0.5
+playcraft audio normalize --input ta-workspace/bgm_loop.mp3 --output ta-workspace/bgm_loop.mp3 --target-loudness -16
+
+# 3. 压缩至体积预算（Facebook 可玩广告 BGM 目标 ≤60KB）
+playcraft audio compress --input ta-workspace/bgm_loop.mp3 --output ta-workspace/asset --target-size 60KB
+
+# 4. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are generating a cheerful ukulele BGM for a casual mobile game.
+  Follow the Recipe to call the audio generation API with the specified prompt and duration.
+  Ensure the output is a proper loop-ready MP3 file. Apply the Binding to wire it into the AudioManager.

package/skills/cheerful_ukulele.aiaudio/manifest.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": 1,
+  "atomId": "cheerful_ukulele.aiaudio",
+  "bundleType": "aiaudio",
+  "category": "audio",
+  "mode": "generative",
+  "label": {
+    "zh": "轻快尤克里里 BGM",
+    "en": "Cheerful ukulele BGM"
+  },
+  "tags": [
+    "audio",
+    "bgm",
+    "music",
+    "cheerful",
+    "ukulele",
+    "casual",
+    "loop",
+    "upbeat"
+  ],
+  "bindingRoles": ["bgMusic"],
+  "generation": {
+    "kind": "bgm",
+    "prompt": "cheerful upbeat ukulele loop, casual mobile game background music, tropical feel, light percussion, 120 BPM",
+    "duration": 30,
+    "loop": true,
+    "platformSkill": "playcraft-audio-generation",
+    "bgmStyle": "casual",
+    "bpm": 120
+  },
+  "result": {
+    "outputFile": "audio.mp3",
+    "format": "mp3",
+    "constraints": {
+      "minDuration": 15,
+      "maxDuration": 60
+    }
+  },
+  "binding": {
+    "role": "backgroundMusic",
+    "target": "scene://entities/AudioManager/bgm/asset",
+    "type": "audio-asset-reference",
+    "constraints": {
+      "playMode": "loop"
+    }
+  },
+  "files": {
+    "skill": "SKILL.md"
+  }
+}

package/skills/click_sfx.aiaudio/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: click_sfx.aiaudio
+description: 玩家成功点击消除路径时的反馈音效。
+triggers: 需要生成路径成功消除的点击音效时触发。
+---
+
+# 路径消除音效
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: Google Lyria 3（平台默认，见 manifest.json generation.platformSkill）
+- format: mp3
+- loop: false
+
+## Result
+
+- 产物文件：`click.mp3`
+- 在 Preloader.ts 中作为 `sfxClick` key 加载
+
+## Binding
+
+```json
+{
+  "role": "sfxClick",
+  "target": "assets/sounds/click.mp3",
+  "type": "audio-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-audio-generation`
+
+```bash
+# 1. 生成 SFX（--prompt 必须英文）
+playcraft tools generate-sfx \
+     --prompt "satisfying click sound for successful path removal in a puzzle game" \
+     --duration 1 \
+     --output ta-workspace/raw_sfx.mp3
+
+# 2. 归一化音量
+playcraft audio normalize --input ta-workspace/raw_sfx.mp3 --output ta-workspace/raw_sfx.mp3 --target-loudness -16
+
+# 3. 压缩（SFX 目标 ≤15KB）
+playcraft audio compress --input ta-workspace/raw_sfx.mp3 --output ta-workspace/click.mp3 --target-size 15KB
+
+# 4. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_audio
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - audio: click.mp3
+```

package/skills/click_sfx.aiaudio/manifest.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": 1,
+  "atomId": "click_sfx.aiaudio",
+  "bundleType": "aiaudio",
+  "category": "audio",
+  "mode": "generative",
+  "label": {
+    "zh": "路径点击消除音效",
+    "en": "Path click elimination SFX"
+  },
+  "tags": [
+    "audio",
+    "sfx",
+    "click",
+    "success",
+    "path"
+  ],
+  "bindingRoles": [
+    "sfxClick"
+  ],
+  "generation": {
+    "kind": "sfx",
+    "prompt": "satisfying click sound for successful path removal in a puzzle game",
+    "duration": 1,
+    "loop": false,
+    "referenceAudio": "ref/click.mp3",
+    "platformSkill": "playcraft-audio-generation"
+  },
+  "result": {
+    "outputFile": "ref/click.mp3",
+    "format": "mp3",
+    "constraints": {
+      "maxDuration": 1
+    }
+  },
+  "binding": {
+    "role": "sfxClick",
+    "target": "assets/sounds/click.mp3",
+    "type": "audio-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/click.mp3"
+  }
+}

package/skills/combo_display.aicomponent/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: combo_display.aicomponent
+description: 连击计数 UI。追踪时间窗口内的连续成功消除次数，显示连击数字和倒计时进度环，超时后重置连击。
+triggers: 需要实现连击系统 UI 时触发。
+---
+
+# 连击计数 UI（Combo Display UI）
+
+## Scaffold
+
+- `src/game/scenes/GameUI/ComboManager.ts`（连击逻辑）
+- `src/game/scenes/GameUI/ComboSmallUI.ts`（小连击 UI 进度环）
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **逻辑与 UI 同 skill** | ComboManager（连击计数+时间窗口）和 ComboSmallUI（进度环动画）高度耦合；拆分没有复用价值，合并为一个 skill 降低管理成本 |
+| **时间窗口重置** | 玩家在时间窗口内连续消除才累积连击，超时后连击归零；给玩家明确的视觉反馈（进度环倒计时）提升参与感 |
+
+## Adapter
+
+- **Role**: `comboDisplay` — 连击计数追踪 + 进度环 UI
+- **Provides**: `ComboManager` 类（连击计数、时间窗口、触发 `maybeShowComboPraiseText`）、`ComboSmallUI` 类（圆形进度环动画）
+- **Requires**: `phaser.aicomponent`（硬依赖）
+- **Consumed by**: `game_scene.aicomponent`（持有 ComboManager）、`path_input_handler.aicomponent`（成功消除时调用 `addCombo()`）
+- **Integration point**: `src/game/scenes/GameUI/ComboManager.ts` + `ComboSmallUI.ts`
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/ComboManager.ts
+  - source: src/game/scenes/GameUI/ComboSmallUI.ts
+outputs:
+  - comboManager: ComboManager class (combo logic + praise text trigger)
+  - comboSmallUI: ComboSmallUI class (circular countdown ring)
+```

package/skills/combo_display.aicomponent/manifest.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": 1,
+  "atomId": "combo_display.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "component",
+  "mode": "fixed",
+  "label": { "zh": "连击计数 UI", "en": "Combo display UI" },
+  "tags": ["ui", "combo", "streak", "chain", "multiplier"],
+  "bindingRoles": ["comboDisplay"],
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/ComboManager.ts": { "source": "ref/ComboManager.ts", "mode": "full", "weight": 10 },
+      "src/game/scenes/GameUI/ComboSmallUI.ts":  { "source": "ref/ComboSmallUI.ts",  "mode": "full", "weight": 10 }
+    }
+  },
+  "imports": [
+    { "slot": "engine", "pinAtomId": "phaser.aicomponent", "edgeKind": "requires", "bindAs": "engine" }
+  ],
+  "exports": [
+    { "name": "ComboManager",  "kind": "class", "location": "src/game/scenes/GameUI/ComboManager.ts" },
+    { "name": "ComboSmallUI",  "kind": "class", "location": "src/game/scenes/GameUI/ComboSmallUI.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "combo streak UI showing consecutive success count with a circular countdown progress ring"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "comboManager": "ref/ComboManager.ts",
+    "comboSmallUI": "ref/ComboSmallUI.ts"
+  }
+}