@playcraft/skills 0.0.2

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

@@ -0,0 +1,189 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 画线解谜玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "draw_line_puzzle",
+  "entities": {
+    "scene": {
+      "type": "spatial",
+      "description": "关卡场景空间",
+      "fields": {
+        "width": { "type": "number", "default": 800 },
+        "height": { "type": "number", "default": 600 },
+        "startPoint": { "type": "vec2", "description": "角色初始位置" },
+        "endPoint": { "type": "vec2", "description": "目标位置（宝箱/出口）" },
+        "obstacles": {
+          "type": "rect[]",
+          "description": "障碍物列表，每个为 {x, y, width, height}，线段不能穿过障碍"
+        }
+      }
+    },
+    "drawnLines": {
+      "type": "entity-list",
+      "description": "玩家已绘制的所有线段集合",
+      "item": {
+        "id": { "type": "string" },
+        "points": { "type": "vec2[]", "description": "折线路径点数组，首尾相连" },
+        "length": { "type": "number", "description": "该段折线的总长度（px）" }
+      }
+    },
+    "character": {
+      "type": "agent",
+      "description": "被引导的角色",
+      "fields": {
+        "position": { "type": "vec2" },
+        "state": { "type": "enum", "values": ["idle", "moving", "arrived", "blocked"], "default": "idle" },
+        "pathProgress": { "type": "number", "description": "沿当前路径的移动进度（0~1）" }
+      }
+    },
+    "target": {
+      "type": "point",
+      "description": "目标位置（角色需要到达的地点）",
+      "fields": {
+        "position": { "type": "vec2" },
+        "radius": { "type": "number", "default": 30, "description": "到达判定半径" }
+      }
+    },
+    "inkUsed": {
+      "type": "counter",
+      "initial": 0,
+      "description": "已使用的墨水长度（所有线段总长度之和）"
+    },
+    "timeLeft": {
+      "type": "counter",
+      "description": "剩余时间（ms，仅 timeLimitEnabled 时有效）"
+    }
+  },
+  "rules": {
+    "draw_line": {
+      "description": "玩家在空白区域绘制线段",
+      "steps": [
+        "1. startLine(point)：记录起始点，创建新线段",
+        "2. extendLine(point)：追加新折点，检测是否与障碍物相交",
+        "   - 若新线段与任何 obstacle 矩形相交：拒绝追加，标记 inkExceeded=false, blocked=true",
+        "   - 若 inkUsed + newSegmentLength > maxInkLength：拒绝追加，标记 inkExceeded=true",
+        "   - 否则：追加折点，更新 inkUsed",
+        "3. finishLine()：封存当前线段"
+      ]
+    },
+    "validate_path": {
+      "description": "检查绘制的路径是否能引导角色从 startPoint 到 endPoint",
+      "conditions": [
+        "路径起点距离 scene.startPoint ≤ snapRadius（30px）",
+        "路径终点距离 scene.endPoint ≤ snapRadius（30px）",
+        "路径所有线段不与任何 obstacle 相交"
+      ]
+    },
+    "execute": {
+      "description": "路径验证通过后，角色沿路径移动",
+      "speed": "characterSpeed（px/s，由 config 覆盖）",
+      "interpolation": "线性插值沿折线路径逐段移动"
+    },
+    "win_check": {
+      "description": "角色到达 target 判定圆内时触发胜利"
+    },
+    "line_limit": {
+      "description": "墨水限制：inkUsed 超过 maxInkLength 时无法继续绘制"
+    }
+  },
+  "algorithm": {
+    "description": "主流程：draw → validate → execute → win",
+    "steps": [
+      "1. 玩家触摸开始：startLine(touchPoint)",
+      "2. 玩家拖动：extendLine(touchPoint)，实时检测障碍碰撞和墨水限制",
+      "3. 玩家抬起手指：finishLine()",
+      "4. validatePath()：检查路径是否有效",
+      "5. 若有效：character.state = moving，开始 executeCharacterMove(deltaMs) 循环",
+      "6. 每帧：executeCharacterMove(deltaMs) 更新 character.position 和 pathProgress",
+      "7. checkWin()：若 character.position 进入 target 半径 → win=true"
+    ]
+  },
+  "winCondition": {
+    "type": "character_reaches_target",
+    "description": "角色到达目标点判定圆内"
+  },
+  "loseCondition": {
+    "type": "time_limit_or_ink_exhausted",
+    "description": "（时限模式）时间耗尽前角色未到达目标；或墨水耗尽无法画出有效路径（软失败，需玩家重试）"
+  },
+  "testCases": [
+    {
+      "id": "tc_draw_path_and_win",
+      "description": "正常通关：画出有效路径，角色到达目标",
+      "initialState": {
+        "scene": {
+          "width": 800, "height": 600,
+          "startPoint": { "x": 100, "y": 300 },
+          "endPoint": { "x": 700, "y": 300 },
+          "obstacles": []
+        },
+        "drawnLines": [],
+        "character": { "position": { "x": 100, "y": 300 }, "state": "idle", "pathProgress": 0 },
+        "target": { "position": { "x": 700, "y": 300 }, "radius": 30 },
+        "inkUsed": 0
+      },
+      "actions": [
+        { "type": "startLine", "point": { "x": 100, "y": 300 } },
+        { "type": "extendLine", "point": { "x": 400, "y": 300 } },
+        { "type": "extendLine", "point": { "x": 700, "y": 300 } },
+        { "type": "finishLine" },
+        { "type": "tick", "deltaMs": 7000 }
+      ],
+      "expectedState": {
+        "character.state": "arrived",
+        "win": true
+      }
+    },
+    {
+      "id": "tc_obstacle_blocks_line",
+      "description": "障碍阻挡：线段与障碍物相交时被拒绝，不能继续绘制",
+      "initialState": {
+        "scene": {
+          "width": 800, "height": 600,
+          "startPoint": { "x": 100, "y": 300 },
+          "endPoint": { "x": 700, "y": 300 },
+          "obstacles": [
+            { "x": 300, "y": 200, "width": 100, "height": 200 }
+          ]
+        },
+        "drawnLines": [],
+        "character": { "position": { "x": 100, "y": 300 }, "state": "idle", "pathProgress": 0 },
+        "target": { "position": { "x": 700, "y": 300 }, "radius": 30 },
+        "inkUsed": 0
+      },
+      "actions": [
+        { "type": "startLine", "point": { "x": 100, "y": 300 } },
+        { "type": "extendLine", "point": { "x": 500, "y": 300 } }
+      ],
+      "expectedState": {
+        "lastExtendResult.blocked": true,
+        "drawnLines[0].points.length": { "max": 2 },
+        "win": false
+      }
+    },
+    {
+      "id": "tc_ink_too_long",
+      "description": "墨水耗尽：绘制超过最大墨水长度时被拒绝",
+      "initialState": {
+        "scene": {
+          "width": 800, "height": 600,
+          "startPoint": { "x": 100, "y": 300 },
+          "endPoint": { "x": 700, "y": 300 },
+          "obstacles": []
+        },
+        "drawnLines": [],
+        "character": { "position": { "x": 100, "y": 300 }, "state": "idle", "pathProgress": 0 },
+        "target": { "position": { "x": 700, "y": 300 }, "radius": 30 },
+        "inkUsed": 480,
+        "config": { "maxInkLength": 500 }
+      },
+      "actions": [
+        { "type": "startLine", "point": { "x": 100, "y": 300 } },
+        { "type": "extendLine", "point": { "x": 700, "y": 300 } }
+      ],
+      "expectedState": {
+        "lastExtendResult.inkExceeded": true,
+        "win": false
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,194 @@
+/**
+ * draw_line_puzzle.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部完成整个画线 → 验证 → 角色移动流程，
+ * 中间过程（实时墨水消耗、线段碰撞点、角色逐帧位置）全部丢失。
+ *
+ * 渲染层需要实时绘制线段、显示墨水条、逐帧更新角色位置，
+ * 因此必须使用下方的「分步函数」逐步驱动，每步之间同步渲染状态。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、跳过动画等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type Vec2 = { x: number; y: number };
+
+export type Rect = { x: number; y: number; width: number; height: number };
+
+export type DrawLinePuzzleConfig = {
+  /** 场景宽度（px） */
+  sceneWidth: number;
+  /** 场景高度（px） */
+  sceneHeight: number;
+  /** 最大墨水总长度（px） */
+  maxInkLength: number;
+  /** 角色移动速度（px/s） */
+  characterSpeed: number;
+  /** 折点最小间距（小于此值则合并，px） */
+  lineSegmentSnap: number;
+  /** 是否启用时间限制 */
+  timeLimitEnabled: boolean;
+  /** 时间限制（ms，仅 timeLimitEnabled=true 时有效） */
+  timeLimitMs?: number;
+  /** 起点吸附半径（角色在此范围内则路径起点有效，px） */
+  snapRadius: number;
+  /** 场景障碍物列表 */
+  obstacles: Rect[];
+  /** 起始点 */
+  startPoint: Vec2;
+  /** 目标点 */
+  endPoint: Vec2;
+  /** 目标到达判定半径（px） */
+  targetRadius: number;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type DrawLinePuzzleAction =
+  | { type: 'startLine'; point: Vec2 }
+  | { type: 'extendLine'; point: Vec2 }
+  | { type: 'finishLine' }
+  | { type: 'tick'; deltaMs: number }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type CharacterState = 'idle' | 'moving' | 'arrived' | 'blocked';
+
+export type DrawnLine = {
+  id: string;
+  points: Vec2[];
+  length: number;
+};
+
+export type DrawLinePuzzleState = {
+  lines: DrawnLine[];
+  activeLine: DrawnLine | null;
+  character: {
+    position: Vec2;
+    state: CharacterState;
+    pathProgress: number;
+    currentPathPoints: Vec2[];
+  };
+  target: {
+    position: Vec2;
+    radius: number;
+  };
+  inkUsed: number;
+  timeLeft: number;
+  gameOver: boolean;
+  win: boolean;
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+export type ExtendLineResult = {
+  newSegment: { from: Vec2; to: Vec2 } | null;
+  inkUsed: number;
+  inkExceeded: boolean;
+  blocked: boolean;
+};
+
+export type ValidatePathResult = {
+  valid: boolean;
+  reason: 'ok' | 'no_path' | 'obstacle_blocked' | 'no_start_connection' | 'no_end_connection';
+};
+
+export type CharacterMoveResult = {
+  position: Vec2;
+  progress: number;
+  arrived: boolean;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态
+ */
+export declare function init(config: DrawLinePuzzleConfig): DrawLinePuzzleState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: DrawLinePuzzleState, action: DrawLinePuzzleAction): DrawLinePuzzleState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: DrawLinePuzzleState): DrawLinePuzzleState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * startLine：开始绘制新线段
+ * 场景层创建新的 Phaser.Graphics 对象，移动到起始点
+ */
+export declare function startLine(
+  state: DrawLinePuzzleState,
+  point: Vec2,
+): { lineId: string; inkUsed: number };
+
+/**
+ * extendLine：延伸当前线段到新点
+ * 场景层在 Graphics 上实时追加 lineTo，更新墨水进度条 HUD
+ *
+ * - blocked=true：新线段与障碍物相交，拒绝追加
+ * - inkExceeded=true：墨水不足，拒绝追加
+ * - newSegment=null：小于 lineSegmentSnap，忽略（合并到上一点）
+ */
+export declare function extendLine(
+  state: DrawLinePuzzleState,
+  point: Vec2,
+): ExtendLineResult;
+
+/**
+ * finishLine：封存当前绘制的线段
+ * 场景层调用后，Graphics 对象变为静态，不再追加
+ */
+export declare function finishLine(
+  state: DrawLinePuzzleState,
+): { lines: DrawnLine[]; totalInkUsed: number };
+
+/**
+ * validatePath：检查所有已绘制线段是否能构成从 startPoint 到 endPoint 的有效路径
+ * 场景层根据 valid 高亮路径（绿色=有效，红色=无效）
+ */
+export declare function validatePath(
+  state: DrawLinePuzzleState,
+): ValidatePathResult;
+
+/**
+ * executeCharacterMove：逐帧推进角色沿路径移动
+ * 场景层每帧调用，根据返回 position 更新角色精灵位置
+ *
+ * - arrived=true：角色到达目标，场景层调用 checkWin()
+ */
+export declare function executeCharacterMove(
+  state: DrawLinePuzzleState,
+  deltaMs: number,
+): CharacterMoveResult;
+
+/**
+ * checkWin：检查是否胜利（角色是否已到达目标）
+ */
+export declare function checkWin(
+  state: DrawLinePuzzleState,
+): { win: boolean };

package/skills/easy_to_hard.aiconfig/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: easy_to_hard.aiconfig
+description: 先易后难难度曲线配置封包 - 关卡难度线性递增的参数配置，适合引导新玩家的休闲游戏
+triggers: 难度曲线,difficulty,先易后难,easy_to_hard,关卡,level,配置,config,递增,progressive
+---
+
+# easy_to_hard.aiconfig
+
+先易后难难度曲线配置封包。配置关卡从简单到困难线性递增，适合给新玩家良好的上手体验。
+
+## Recipe
+
+- **配置方式**：参数化（parametric）
+- **核心参数**：
+  - `difficultyMode`: `"easy_to_hard"`
+  - `initialMoves`: 30（第一关步数）
+  - `finalMoves`: 15（最后一关步数）
+  - `progressionSteps`: 10（关卡总数）
+- **可 fork 变体**：
+  - 更快递增：`progressionSteps: 5`，更快进入高难度
+  - 超宽松入门：`initialMoves: 50`，给更多初始步数
+  - 逆序（先难后易）：将 `initialMoves` 和 `finalMoves` 互换
+
+**配置步骤：**
+1. 读取 Prefab 容器的 `game/config.json`
+2. 将 `difficulty.curve` 键写入 `"easy_to_hard"`
+3. 写入对应步数参数（`difficulty.initialMoves`、`difficulty.finalMoves`）
+4. 更新 manifest
+
+## Result
+
+- **产物**：修改 `game/config.json` 的参数键值
+- **格式**：JSON patch
+- **目标键**：`difficulty.curve`
+
+## Binding
+
+- **Binding Role**：`gameConfig`
+- **挂载目标**：`game/config.json`
+- **引用类型**：`config-key-value`
+- **约束**：key=`difficulty.curve`
+
+## Skill Definition
+
+tools:
+  - read
+  - write
+prompt_extension: |
+  You are configuring a difficulty progression curve for a casual match-3 game.
+  Follow the Recipe to write the difficulty parameters to game/config.json.
+  Use easy_to_hard mode: start with generous moves and gradually decrease over levels.
+  Apply the Binding to ensure the config key is correctly set.

package/skills/easy_to_hard.aiconfig/manifest.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "atomId": "easy_to_hard.aiconfig",
+  "bundleType": "aiconfig",
+  "category": "config",
+  "mode": "parametric",
+  "label": { "zh": "先易后难难度曲线", "en": "Easy-to-hard difficulty curve" },
+  "tags": ["config", "difficulty", "curve", "level", "progression", "casual"],
+  "bindingRoles": ["gameConfig"],
+  "generation": {
+    "kind": "config-patch",
+    "params": {
+      "difficultyMode": "easy_to_hard",
+      "initialMoves": 30,
+      "finalMoves": 15,
+      "progressionSteps": 10
+    }
+  },
+  "result": {
+    "configKey": "difficulty.curve",
+    "configValue": "easy_to_hard",
+    "format": "json-patch"
+  },
+  "binding": {
+    "role": "gameConfig",
+    "target": "game/config.json",
+    "type": "config-key-value",
+    "constraints": { "key": "difficulty.curve" }
+  },
+  "files": {
+    "skill": "SKILL.md"
+  }
+}

package/skills/eight_ball_pool.aigameplay/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: eight_ball_pool.aigameplay
+description: 8球台球核心玩法封包 - 标准8球台球简化版 PGS 实现，支持瞄准、击球、进袋判定和胜负逻辑
+triggers: 台球,billiards,pool,8ball,eight ball,撞球,球桌,球杆,瞄准,进袋,physics,物理,sports,体育
+---
+
+# eight_ball_pool.aigameplay
+
+8球台球核心玩法封包。实现标准8球台球简化版的 PGS (PlayCraft Gameplay Schema, 玩法定义规范) JSON 和 reducer。单人模式：先将自己的7个球（实心球1-7或条纹球9-15）全部打入球袋，再打黑色8号球入袋获胜。
+
+## Recipe
+
+- **玩法类型**：eight_ball_pool（台球）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema, 玩法定义规范) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `ballCount`: 16（1个白球 + 7个实心球 + 7个条纹球 + 1个8号黑球）
+  - `pocketCount`: 6（台球桌四角+两侧中点共6个球袋）
+  - `singlePlayer`: true（简化为单人模式）
+  - `physicsStepsPerFrame`: 10（物理模拟精度）
+- **PGS Agent 操作流程**：
+  1. 读取 `ref/pgs-schema.json` 作为规则骨架起点
+  2. 读取 `ref/reducer.template.ts` 了解接口约束
+  3. 实现 `reducer.ts`，导出 `init(config)`、`dispatch(state, action)`、`getState(state)` 以及**全部分步函数**
+  4. 物理模拟抽象为简化模型：直线运动 + 弹性碰撞 + 球袋检测（不需要真实弹性系数）
+  5. 运行 `ref/pgs-schema.json` 中的所有 `testCases`，全部通过后才算完成
+- **物理简化策略**：
+  - 球运动：每帧速度衰减（friction），直到速度 < 阈值停止
+  - 球碰撞：球心距 < 直径时，交换速度分量（弹性碰撞近似）
+  - 球袋检测：球心进入球袋区域半径内则进袋
+- **可 fork 变体**：
+  - 双人对战：移除 `singlePlayer`，添加 `currentPlayer` 轮换逻辑
+  - 9球玩法：修改 `gameplayType` 为 `nine_ball`，调整胜负条件
+  - 障碍模式：在台球桌上增加固定障碍物实体
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(action)`、`getState()` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：物理循环与渲染分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，返回中间过程数据 |
+
+### ⚠️ 渲染层必须使用分步函数驱动动画
+
+```ts
+// ✅ 正确做法：分步驱动
+// Step 1: 设置瞄准
+const aimed = aimCueBall(state, angle, power);
+
+// Step 2: 击球 - 渲染层播放击球动画
+const shotState = shootCueBall(aimed);
+
+// Step 3: 物理帧循环（每帧调用直到所有球停止）
+while (ballsMoving(shotState)) {
+  const nextState = applyPhysicsStep(shotState, dt);
+  await renderBallPositions(nextState.balls);  // 更新精灵位置
+
+  // Step 4: 检测进袋
+  const pocketResult = checkPockets(nextState);
+  if (pocketResult.pocketed.length > 0) {
+    await playPocketAnimation(pocketResult.pocketed);
+  }
+  shotState = nextState;
+}
+
+// Step 5: 判断回合
+const turnState = determineTurn(shotState);
+updateUIForTurn(turnState);
+```
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/eight_ball_pool/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(action)` / `getState()` / `aimCueBall()` / `shootCueBall()` / `applyPhysicsStep()` / `checkPockets()` / `determineTurn()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing an 8-ball pool gameplay module following the PGS specification.
+  Write the PGS JSON with entities, rules, algorithm, and testCases.
+  Implement the reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - aimCueBall/shootCueBall/applyPhysicsStep/checkPockets/determineTurn (分步函数，用于渲染层动画驱动)
+  Physics is abstracted: use simple linear motion with friction damping, elastic ball-ball collision (velocity exchange),
+  and pocket detection by proximity. No need for real physics engine.
+  Run the testCases to verify the logic before finalizing.
+  Apply the Binding to wire the reducer into the game's gameplay module path.