@playcraft/skills 0.0.2

package/skills/wave_difficulty.aiconfig/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: wave_difficulty.aiconfig
+description: 波浪难度曲线配置封包 - 难度周期性起伏的参数配置，保持玩家长期参与感
+triggers: 难度,difficulty,波浪,wave,曲线,curve,配置,config,周期,cycle,动态,dynamic
+---
+
+# wave_difficulty.aiconfig
+
+波浪难度曲线配置封包。难度周期性起伏（难→易→难），避免单调线性递增导致的玩家流失。
+
+## Recipe
+
+- **配置方式**：参数化（parametric）
+- **核心参数**：
+  - `difficultyMode`: `"wave"`
+  - `wavePeriod`: 3（每 3 关一个波峰）
+  - `minMoves`: 15（波谷步数）
+  - `maxMoves`: 35（波峰步数）
+- **可 fork 变体**：
+  - 短周期：`wavePeriod: 2`，更频繁的难度变化
+  - 大振幅：`minMoves: 10, maxMoves: 40`
+
+**配置步骤：**
+1. 读取 `game/config.json`
+2. 写入 `difficulty.curve = "wave"` 和周期参数
+3. 更新 manifest
+
+## Result
+
+- **产物**：修改 `game/config.json` 键值
+- **目标键**：`difficulty.curve = "wave"`
+
+## Binding
+
+- **Binding Role**：`gameConfig`
+- **挂载目标**：`game/config.json`
+- **引用类型**：`config-key-value`
+
+## Skill Definition
+
+tools:
+  - read
+  - write
+prompt_extension: |
+  You are configuring a wave difficulty curve for a casual game.
+  Write the wave pattern parameters to game/config.json per the Recipe. Apply the Binding.

package/skills/wave_difficulty.aiconfig/manifest.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "atomId": "wave_difficulty.aiconfig",
+  "bundleType": "aiconfig",
+  "category": "config",
+  "mode": "parametric",
+  "label": { "zh": "波浪难度曲线", "en": "Wave difficulty curve" },
+  "tags": ["config", "difficulty", "wave", "curve", "level", "dynamic"],
+  "bindingRoles": ["gameConfig"],
+  "generation": {
+    "kind": "config-patch",
+    "params": {
+      "difficultyMode": "wave",
+      "wavePeriod": 3,
+      "minMoves": 15,
+      "maxMoves": 35
+    }
+  },
+  "result": {
+    "configKey": "difficulty.curve",
+    "configValue": "wave",
+    "format": "json-patch"
+  },
+  "binding": {
+    "role": "gameConfig",
+    "target": "game/config.json",
+    "type": "config-key-value",
+    "constraints": { "key": "difficulty.curve" }
+  },
+  "files": {
+    "skill": "SKILL.md"
+  }
+}

package/skills/webpack_build.aicomponent/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: webpack_build.aicomponent
+description: 通用 Webpack 5 构建配置。提供 TypeScript + Phaser 项目的标准 webpack 打包方案，支持开发模式热更新和生产模式单文件构建。不依赖任何特定投放平台。
+triggers: 需要初始化项目构建配置、配置 webpack、设置开发服务器、打包生产产物时触发。
+---
+
+# 通用 Webpack 构建配置（Generic Webpack Build）
+
+## 说明
+
+为 Phaser + TypeScript 试玩广告项目提供**不依赖任何平台**的标准构建方案：
+
+- **开发模式**（`pnpm dev`）：webpack-dev-server + 热更新 + source map
+- **生产模式**（`pnpm build`）：压缩打包，输出到 `dist/`
+
+本 skill 替代 `playable_scripts_build.aicomponent`（后者绑死 `@tencent/playable-scripts`）。
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|------|
+| `webpack.config.js` | `ref/webpack.config.js` | Webpack 5 完整配置 |
+| `package.json` (merge) | `ref/package.json` | scripts + devDependencies |
+
+## 文件详解
+
+### webpack.config.js
+
+```javascript
+const path = require('path');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+
+module.exports = {
+  entry: './src/index.ts',
+  output: {
+    filename: 'bundle.js',
+    path: path.resolve(__dirname, 'dist'),
+    clean: true,
+  },
+  resolve: {
+    extensions: ['.ts', '.js', '.json'],
+    alias: {
+      assets: path.resolve(__dirname, 'assets'),
+    },
+  },
+  module: {
+    rules: [
+      {
+        test: /\.ts$/,
+        use: 'ts-loader',
+        exclude: /node_modules/,
+      },
+      {
+        test: /\.css$/,
+        use: ['style-loader', 'css-loader'],
+      },
+      {
+        test: /\.(png|jpg|jpeg|webp|svg|gif)$/,
+        type: 'asset/resource',
+      },
+      {
+        test: /\.(mp3|ogg|wav|m4a)$/,
+        type: 'asset/resource',
+      },
+      {
+        test: /\.json$/,
+        type: 'json',
+      },
+    ],
+  },
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: './src/index.html',
+    }),
+  ],
+  devServer: {
+    static: './dist',
+    hot: true,
+    open: true,
+    port: 3000,
+  },
+};
+```
+
+### package.json（需合并的字段）
+
+```json
+{
+  "scripts": {
+    "dev": "webpack serve --mode development",
+    "build": "webpack --mode production"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "webpack": "^5.90.0",
+    "webpack-cli": "^5.1.0",
+    "webpack-dev-server": "^5.0.0",
+    "ts-loader": "^9.5.0",
+    "html-webpack-plugin": "^5.6.0",
+    "css-loader": "^6.10.0",
+    "style-loader": "^3.3.0"
+  }
+}
+```
+
+## 使用方式
+
+```bash
+pnpm install     # 安装依赖
+pnpm dev         # 启动开发服务器（localhost:3000，自动打开浏览器）
+pnpm build       # 生产构建（输出到 dist/）
+```
+
+## 资源处理规则
+
+| 文件类型 | Webpack 处理方式 | 代码中引用方式 |
+|---------|-----------------|--------------|
+| `.ts` | ts-loader 编译 | `import { Foo } from "./foo"` |
+| `.css` | style-loader + css-loader | `import "./index.css"` |
+| `.png/.webp/.jpg` | asset/resource（输出文件，返回 URL） | `import img from "assets/images/foo.webp"` |
+| `.mp3/.ogg/.wav` | asset/resource | `import sfx from "assets/sounds/foo.mp3"` |
+| `.json` | 内置 JSON 模块 | `import data from "./levels.json"` |
+
+## alias 配置
+
+`assets` alias 指向项目根目录的 `assets/` 文件夹：
+
+```typescript
+// 以下两种写法等价：
+import car from "assets/images/car.webp";      // ✅ 使用 alias
+import car from "../../assets/images/car.webp"; // ✅ 相对路径（不推荐）
+```
+
+**注意**：使用 alias 时 `tsconfig.json` 中也需要对应的 `paths` 配置：
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "assets/*": ["./assets/*"]
+    }
+  }
+}
+```
+
+## 常见问题
+
+### Q: 开发模式修改代码后浏览器没有更新？
+A: 确保 `devServer.hot: true`，且没有缓存问题。尝试强制刷新（Ctrl+Shift+R）。
+
+### Q: 生产构建体积太大？
+A: webpack production 模式默认开启 terser 压缩。如需进一步优化：
+- 确认 Phaser 没有被重复打包（使用 `externals` 或 CDN）
+- 检查是否有大图片被 inline（asset/resource 不 inline，已正确配置）
+
+### Q: 如何同时支持多渠道构建？
+A: 如需批量构建，参考 `builds.config.js` 模式（见 `playable_scripts_build.aicomponent`），或自行扩展 webpack 配置为多 entry/多 output。
+
+## Imports
+
+- `phaser.aicomponent`（配合使用：提供项目骨架文件）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: ref/webpack.config.js
+  - source: ref/package.json
+outputs:
+  - webpackConfig: webpack.config.js
+  - buildScripts: dev / build npm scripts
+  - buildDeps: webpack + ts-loader + plugins devDependencies
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **与引擎 skill 分离** | 构建工具链与游戏运行时无关；分离允许在不改动 phaser/threejs skill 的情况下替换构建方案 |
+| **替代私有包** | 原 `@tencent/playable-scripts` 是黑盒私有包，无法在非腾讯环境使用；标准 webpack 5 可控、可调试、社区生态完整 |
+| **`asset/resource` 类型** | 图片、音频文件输出为独立文件（非 inline base64），保持产物体积可控，且 URL 字符串类型与 Phaser `load.image()` API 直接兼容 |
+| **单 entry 单 output** | 试玩广告以单 HTML+JS 为目标，多 entry 需求由上层管线（builds.config.js）扩展，不写入本 skill |
+
+## Adapter
+
+- **Role**: `buildToolchain` — Webpack 5 开发与生产构建管线
+- **Provides**: `webpack.config.js` 配置、`pnpm dev`（dev server）、`pnpm build`（生产构建）、资源 alias 映射 `assets/*`
+- **Requires**: 与 `phaser.aicomponent` 或 `threejs.aicomponent` 配套（提供项目骨架入口文件）
+- **Consumed by**: 所有需要本地开发和构建的 Remix 项目（作为工程基座，无上游 skill 依赖）
+- **Integration point**: 根目录 `webpack.config.js` + `package.json` scripts，`phaser.aicomponent` 的 `src/index.ts` 作为 webpack entry
+
+## 替代说明
+
+本 skill 替代 `playable_scripts_build.aicomponent`：
+
+| 维度 | playable_scripts_build | webpack_build（本 skill） |
+|------|----------------------|--------------------------|
+| 构建工具 | @tencent/playable-scripts（私有包） | webpack 5（公开、标准） |
+| 环境要求 | 腾讯内部 npm registry | 标准 npm/pnpm |
+| 多渠道构建 | 内置 | 需自行扩展（或不需要） |
+| 灵活性 | 黑盒 | 完全可控的 webpack.config.js |
+| 社区支持 | 无 | webpack 社区生态 |

package/skills/webpack_build.aicomponent/manifest.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "atomId": "webpack_build.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "build",
+  "mode": "fixed",
+  "label": {
+    "zh": "通用 Webpack 构建配置",
+    "en": "Generic Webpack build configuration"
+  },
+  "tags": [
+    "build",
+    "webpack",
+    "dev-server",
+    "typescript",
+    "bundler",
+    "infrastructure"
+  ],
+  "bindingRoles": [
+    "buildSystem"
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "ref": [
+      "ref/webpack.config.js",
+      "ref/package.json"
+    ]
+  }
+}

package/skills/webpack_build.aicomponent/ref/package.json

@@ -0,0 +1,16 @@
+{
+  "scripts": {
+    "dev": "webpack serve --mode development",
+    "build": "webpack --mode production"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "webpack": "^5.90.0",
+    "webpack-cli": "^5.1.0",
+    "webpack-dev-server": "^5.0.0",
+    "ts-loader": "^9.5.0",
+    "html-webpack-plugin": "^5.6.0",
+    "css-loader": "^6.10.0",
+    "style-loader": "^3.3.0"
+  }
+}

package/skills/webpack_build.aicomponent/ref/webpack.config.js

@@ -0,0 +1,53 @@
+const path = require('path');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+
+module.exports = {
+  entry: './src/index.ts',
+  output: {
+    filename: 'bundle.js',
+    path: path.resolve(__dirname, 'dist'),
+    clean: true,
+  },
+  resolve: {
+    extensions: ['.ts', '.js', '.json'],
+    alias: {
+      assets: path.resolve(__dirname, 'assets'),
+    },
+  },
+  module: {
+    rules: [
+      {
+        test: /\.ts$/,
+        use: 'ts-loader',
+        exclude: /node_modules/,
+      },
+      {
+        test: /\.css$/,
+        use: ['style-loader', 'css-loader'],
+      },
+      {
+        test: /\.(png|jpg|jpeg|webp|svg|gif)$/,
+        type: 'asset/resource',
+      },
+      {
+        test: /\.(mp3|ogg|wav|m4a)$/,
+        type: 'asset/resource',
+      },
+      {
+        test: /\.json$/,
+        type: 'json',
+      },
+    ],
+  },
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: './src/index.html',
+    }),
+  ],
+  devServer: {
+    static: './dist',
+    hot: true,
+    open: true,
+    port: 3000,
+  },
+};

package/skills/win_anim_sfx.aiaudio/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: win_anim_sfx.aiaudio
+description: 通关后钻石粒子爆炸动画伴随的胜利音效。
+triggers: 需要生成胜利粒子动画音效时触发。
+---
+
+# 胜利动画音效
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: Google Lyria 3（平台默认，见 manifest.json generation.platformSkill）
+- format: mp3
+- loop: false
+
+## Result
+
+- 产物文件：`win_anim.mp3`
+- 在 Preloader.ts 中作为 `sfxWinAnim` key 加载
+
+## Binding
+
+```json
+{
+  "role": "sfxWinAnim",
+  "target": "assets/sounds/win_anim.mp3",
+  "type": "audio-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-audio-generation`
+
+```bash
+# 1. 生成 SFX（--prompt 必须英文）
+playcraft tools generate-sfx \
+     --prompt "sparkling victory animation sound, magical glitter effect" \
+     --duration 2 \
+     --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/win_anim.mp3 --target-size 15KB
+
+# 4. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_audio
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - audio: win_anim.mp3
+```

package/skills/win_anim_sfx.aiaudio/manifest.json

@@ -0,0 +1,46 @@
+{
+  "schemaVersion": 1,
+  "atomId": "win_anim_sfx.aiaudio",
+  "bundleType": "aiaudio",
+  "category": "audio",
+  "mode": "generative",
+  "label": {
+    "zh": "胜利动画音效",
+    "en": "Win animation SFX"
+  },
+  "tags": [
+    "audio",
+    "sfx",
+    "win",
+    "animation",
+    "sparkle",
+    "victory"
+  ],
+  "bindingRoles": [
+    "sfxWinAnim"
+  ],
+  "generation": {
+    "kind": "sfx",
+    "prompt": "sparkling victory animation sound, magical glitter effect",
+    "duration": 2,
+    "loop": false,
+    "referenceAudio": "ref/win_anim.mp3",
+    "platformSkill": "playcraft-audio-generation"
+  },
+  "result": {
+    "outputFile": "ref/win_anim.mp3",
+    "format": "mp3",
+    "constraints": {
+      "maxDuration": 2
+    }
+  },
+  "binding": {
+    "role": "sfxWinAnim",
+    "target": "assets/sounds/win_anim.mp3",
+    "type": "audio-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/win_anim.mp3"
+  }
+}

package/skills/win_dot.aiimage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: win_dot.aiimage
+description: 通关胜利钻石动画中使用的闪光粒子图片。
+triggers: 需要生成胜利动画粒子图片时触发。
+---
+
+# 胜利粒子
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: google/imagen-3.0-generate-002（默认，见 manifest.json generation.platformSkill）
+- format: webp, 透明背景
+
+## Result
+
+- 产物文件：`win_dot.webp`
+- 在 Preloader.ts 中作为 `winParticleAsset` key 加载
+
+## Binding
+
+```json
+{
+  "role": "winParticleAsset",
+  "target": "assets/win_dot.webp",
+  "type": "image-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "small glowing dot particle for victory animation, bright colorful sparkle" \
+     --aspect-ratio 1:1 \
+     --reference-image ${SKILL_DIR}/ref/win_dot.png \
+     --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/win_dot.webp --quality 85
+
+# 3. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_image
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - image: win_dot.webp
+```

package/skills/win_dot.aiimage/manifest.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": 1,
+  "atomId": "win_dot.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "胜利粒子",
+    "en": "Win particle dot"
+  },
+  "tags": [
+    "visual",
+    "particle",
+    "win",
+    "sparkle",
+    "dot"
+  ],
+  "bindingRoles": [
+    "winParticleAsset"
+  ],
+  "generation": {
+    "kind": "image",
+    "prompt": "small glowing dot particle for victory animation, bright colorful sparkle",
+    "aspectRatio": "1:1",
+    "model": "google/imagen-3.0-generate-002",
+    "referenceImage": "ref/win_dot.png",
+    "platformSkill": "playcraft-image-generation"
+  },
+  "result": {
+    "outputFile": "ref/win_dot.webp",
+    "format": "webp",
+    "constraints": {
+      "minWidth": 32,
+      "minHeight": 32
+    }
+  },
+  "binding": {
+    "role": "winParticleAsset",
+    "target": "assets/win_dot.webp",
+    "type": "image-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/win_dot.webp",
+    "assetPng": "ref/win_dot.png"
+  }
+}

package/skills/win_result_panel.aiimage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: win_result_panel.aiimage
+description: 关卡通关后显示的胜利面板图片，是试玩广告转化的关键视觉资产。
+triggers: 需要生成或替换胜利结果面板图片时触发。
+---
+
+# 胜利结果面板
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: google/imagen-3.0-generate-002（默认，见 manifest.json generation.platformSkill）
+- format: webp, 透明背景
+
+## Result
+
+- 产物文件：`win.webp`
+- 在 Preloader.ts 中作为 `successFeedbackPanel` key 加载
+
+## Binding
+
+```json
+{
+  "role": "successFeedbackPanel",
+  "target": "assets/win.webp",
+  "type": "image-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "winning celebration panel for a mobile game, bright and exciting, trophy or star icons, positive energy" \
+     --aspect-ratio 1:1 \
+     --reference-image ${SKILL_DIR}/ref/win.png \
+     --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/win.webp --quality 85
+
+# 3. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_image
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - image: win.webp
+```