@playcraft/skills 0.0.2

package/skills/level_data_pack.aiconfig/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: level_data_pack.aiconfig
+description: 路径消除玩法关卡数据包。一组符合 RawLevelJson 格式的关卡 JSON 文件，定义棋盘尺寸、路径折线坐标和关卡时限。
+triggers: 需要生成或定义路径消除玩法的关卡数据集时触发。
+---
+
+# 关卡数据包（Level Data Pack）
+
+## 说明
+
+`RawLevelJson` 格式的关卡数据集，由 `arrow_path_data_format.aicomponent` 的 `parseLevelJson()` 解析后供游戏使用。
+
+每个关卡定义：
+- `row × col`：棋盘尺寸（如 8×10）
+- `arrows`：路径折线坐标数组（Cocos 坐标系，y 轴向上，第一个点可含颜色字符串）
+- `levelTime`：关卡时限（秒，0 = 无时限）
+
+## Recipe
+
+```json
+{
+  "kind": "level-data",
+  "format": "RawLevelJson",
+  "params": {
+    "levelCount": 10,
+    "gridSize": "8x10",
+    "difficulty": "easy-to-hard"
+  }
+}
+```
+
+## Result
+
+`levels.json`（`RawLevelJson[]` 数组）
+
+## Binding
+
+挂载到 `src/theme/<variant>/` 下，被 `ThemeVariantConfig.levels` 引用。
+
+## Skill Definition
+
+```yaml
+tools:
+  - write_file
+  - generate_level_data
+inputs:
+  - schema: RawLevelJson from arrow_path_data_format.aicomponent
+outputs:
+  - levelData: RawLevelJson[] JSON file
+```
+
+## RawLevelJson 格式
+
+```typescript
+type RawLevelJson = {
+  name: number | string;          // 关卡序号
+  row: number;                    // 棋盘行数
+  col: number;                    // 棋盘列数
+  arrows: (number | string)[][][]; // 路径点 [[x, y], [x, y], ...]
+  levelTime: number;              // 时限秒数（0=无时限）
+};
+```
+
+**坐标注意**：Cocos 坐标系 y 轴向上（0 在底部），`parseLevelJson()` 会自动翻转为 Phaser 坐标。

package/skills/level_data_pack.aiconfig/manifest.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "atomId": "level_data_pack.aiconfig",
+  "bundleType": "aiconfig",
+  "category": "config",
+  "mode": "generative",
+  "label": { "zh": "关卡数据包", "en": "Level data pack" },
+  "tags": ["config", "level-data", "json", "puzzle", "paths", "grid"],
+  "bindingRoles": ["levelDataPack"],
+  "generation": {
+    "kind": "level-data",
+    "format": "RawLevelJson",
+    "schema": "arrow_path_data_format.aicomponent/LevelTypes.ts#RawLevelJson",
+    "params": {
+      "levelCount": 10,
+      "gridSize": "8x10",
+      "difficulty": "easy-to-hard"
+    }
+  },
+  "result": {
+    "outputFile": "levels.json",
+    "format": "json",
+    "constraints": { "schema": "RawLevelJson[]", "minLevels": 1 }
+  },
+  "binding": {
+    "role": "levelDataPack",
+    "target": "src/theme/<variant>/levels.json",
+    "type": "config-file-reference",
+    "constraints": { "schema": "RawLevelJson[]" }
+  },
+  "imports": [
+    { "slot": "dataFormat", "pinAtomId": "arrow_path_data_format.aicomponent", "edgeKind": "requires", "bindAs": "dataFormat" }
+  ],
+  "files": {
+    "skill": "SKILL.md"
+  }
+}

package/skills/level_data_validator.aivalidator/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: level_data_validator.aivalidator
+description: 关卡数据校验器。对 RawLevelJson 格式进行编译期 + 运行期双重校验：坐标越界、路径长度、自交叉、可解性检测。开发模式自动输出警告。
+triggers: 关卡数据校验,validate,level data,坐标越界,路径错误,无解关卡,数据质量
+---
+
+# 关卡数据校验器（Level Data Validator）
+
+## 说明
+
+`validateLevel()` 在开发模式下自动校验关卡数据，发现问题立即报错而非等到运行时崩溃。
+
+**检测规则：**
+1. 基础结构：行列 > 0、arrows 数组非空
+2. 坐标越界：所有点必须在 `[0, col)` × `[0, row)` 范围内
+3. 路径长度：每条路径至少 2 个点
+4. 路径重叠：两条路径不应共享格子（警告）
+5. 可解性：至少存在一条路径可以直接消除（警告）
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|------|
+| `src/game/levels/LevelValidator.ts` | `ref/LevelValidator.ts` | 校验函数 |
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **开发期校验，生产期跳过** | 校验逻辑本身有一定性能开销；通过 `NODE_ENV !== 'production'` 保护，生产版本零开销 |
+| **错误与警告双通道** | 坐标越界是致命错误（游戏必然崩溃），路径重叠是设计警告（游戏能运行但关卡可能有问题）；两者严重程度不同，分通道报告 |
+| **与 solvability_validator 分离** | 基础数据格式校验（坐标、结构）与玩法可解性校验（消除顺序、篮子容量）是不同关注点；分离后各自可独立加载 |
+
+## Adapter
+
+- **Role**: `levelDataValidator` — 关卡数据开发期格式与约束校验器
+- **Provides**: `validateLevel()` 函数、`ValidationResult` 类型（`valid`、`errors[]`、`warnings[]`）
+- **Requires**: `arrow_path_data_format.aicomponent`（RawLevelJson 类型）
+- **Consumed by**: `game_scene.aicomponent`（开发模式下在 `parseLevelJson()` 前校验）、`gameplay_unit_test.aivalidator`（集成数据校验测试）
+- **Integration point**: `src/game/levels/LevelValidator.ts` —— 在 `parseLevelJson(raw)` 调用前插入 `validateLevel(raw)` 检查
+
+## Imports
+
+- `arrow_path_data_format.aicomponent`（硬依赖：RawLevelJson 类型）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: ref/LevelValidator.ts
+outputs:
+  - validator: validateLevel() function + ValidationResult type
+```
+
+## 使用方式
+
+```typescript
+import { validateLevel } from "./levels/LevelValidator";
+
+// 在加载关卡时调用
+const raw = LevelData[index];
+const result = validateLevel(raw);
+if (!result.valid) {
+  console.error("[LevelValidator] Level", index, "has errors:", result.errors);
+}
+if (result.warnings.length > 0) {
+  console.warn("[LevelValidator] Level", index, "warnings:", result.warnings);
+}
+```
+
+## 集成到 Game.ts
+
+```typescript
+// 只在开发模式校验（生产模式跳过）
+if (process.env.NODE_ENV !== 'production') {
+  const validation = validateLevel(raw);
+  if (!validation.valid) {
+    console.error('[Game] Invalid level data:', validation.errors);
+  }
+}
+const level = parseLevelJson(raw);
+```

package/skills/level_data_validator.aivalidator/manifest.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "atomId": "level_data_validator.aivalidator",
+  "bundleType": "aivalidator",
+  "category": "validator",
+  "mode": "fixed",
+  "label": {
+    "zh": "关卡数据校验器",
+    "en": "Level data validator"
+  },
+  "tags": ["validation", "level", "data", "debug", "quality"],
+  "bindingRoles": ["dataValidator"],
+  "files": {
+    "skill": "SKILL.md",
+    "ref": ["ref/LevelValidator.ts"]
+  }
+}

package/skills/level_data_validator.aivalidator/ref/LevelValidator.ts

@@ -0,0 +1,113 @@
+import type { RawLevelJson } from "./LevelTypes";
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * 校验 RawLevelJson 关卡数据完整性和合理性
+ */
+export function validateLevel(raw: unknown): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (typeof raw !== "object" || raw === null) {
+    return { valid: false, errors: ["关卡数据不是有效对象"], warnings };
+  }
+
+  const data = raw as Partial<RawLevelJson>;
+
+  // 1. 基础结构检查
+  if (typeof data.row !== "number" || data.row <= 0) {
+    errors.push(`row 必须为正整数，当前值: ${data.row}`);
+  }
+  if (typeof data.col !== "number" || data.col <= 0) {
+    errors.push(`col 必须为正整数，当前值: ${data.col}`);
+  }
+  if (!Array.isArray(data.arrows) || data.arrows.length === 0) {
+    errors.push("arrows 必须为非空数组");
+    return { valid: false, errors, warnings };
+  }
+
+  const rows = data.row ?? 0;
+  const cols = data.col ?? 0;
+
+  // 2. 逐条路径校验
+  const allOccupiedCells = new Set<number>();
+
+  for (let i = 0; i < data.arrows.length; i++) {
+    const path = data.arrows[i];
+
+    if (!Array.isArray(path)) {
+      errors.push(`arrows[${i}] 不是数组`);
+      continue;
+    }
+
+    if (path.length < 2) {
+      errors.push(`arrows[${i}] 至少需要 2 个点，当前 ${path.length} 个`);
+      continue;
+    }
+
+    // 3. 坐标越界检查
+    for (let j = 0; j < path.length; j++) {
+      const point = path[j];
+      if (!Array.isArray(point) || point.length < 2) {
+        errors.push(`arrows[${i}][${j}] 格式错误，应为 [x, y]`);
+        continue;
+      }
+
+      const [x, y] = point as [number, number];
+      if (typeof x !== "number" || typeof y !== "number") {
+        errors.push(`arrows[${i}][${j}] 坐标必须为数字`);
+        continue;
+      }
+
+      if (x < 0 || x >= cols) {
+        errors.push(`arrows[${i}][${j}] x=${x} 越界 (合法范围: 0~${cols - 1})`);
+      }
+      if (y < 0 || y >= rows) {
+        errors.push(`arrows[${i}][${j}] y=${y} 越界 (合法范围: 0~${rows - 1})`);
+      }
+    }
+
+    // 4. 路径占据的格子（检测重叠）
+    const pathCells = new Set<number>();
+    for (let j = 0; j < path.length; j++) {
+      const [x, y] = path[j] as [number, number];
+      if (typeof x === "number" && typeof y === "number") {
+        const idx = y * cols + x;
+        if (allOccupiedCells.has(idx)) {
+          warnings.push(`arrows[${i}] 点 (${x},${y}) 与其他路径重叠`);
+        }
+        pathCells.add(idx);
+      }
+    }
+    pathCells.forEach(c => allOccupiedCells.add(c));
+  }
+
+  // 5. 可解性检查（简单版：至少一条路径的 head 朝向边界无阻挡）
+  if (errors.length === 0 && data.arrows.length > 1) {
+    // 简化：检查是否有路径的最后一个点在边界
+    let hasEdgePath = false;
+    for (const path of data.arrows) {
+      if (path.length < 2) continue;
+      const last = path[path.length - 1] as [number, number];
+      const [x, y] = last;
+      if (x === 0 || x === cols - 1 || y === 0 || y === rows - 1) {
+        hasEdgePath = true;
+        break;
+      }
+    }
+    if (!hasEdgePath) {
+      warnings.push("没有路径的箭头头部在棋盘边界，可能无法直接消除任何路径");
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}

package/skills/level_lifecycle.aicomponent/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: level_lifecycle.aicomponent
+description: 关卡生命周期控制器。管理生命值扣除、超时处理、胜利/失败判断、GameOverPanel 展示和自动进入下一关逻辑。
+triggers: 需要实现关卡的生命值、胜败判定和关卡流转逻辑时触发。
+---
+
+# 关卡生命周期控制器（Level Lifecycle Controller）
+
+## 说明
+
+`LevelLifecycle` 是关卡生命周期的状态机，管理：
+
+- **生命扣除**（`loseLife`）：减少 `currentLives`，命归零时延迟显示失败面板
+- **危险闪光**（`playDangerFrame`）：命不足时播放全屏 `nomove_hint` 图片闪烁
+- **胜利流程**（`handleLevelSuccess`）：播放胜利动画，延迟后进入下一关或显示胜利面板
+- **超时流程**（`handleTimeOut`）：倒计时归零触发失败
+- **自动进关**（可配置）：胜利后是否自动进入下一关
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|-----|
+| `src/game/scenes/GameUI/LevelLifecycle.ts` | `ref/LevelLifecycle.ts` | 完整生命周期管理类 |
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖：Phaser.Scene API）
+- `level_state.aicomponent`（硬依赖：LevelManager 进关逻辑）
+- `game_over_panel.aicomponent`（软槽位：胜利/失败面板展示）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/LevelLifecycle.ts
+outputs:
+  - levelLifecycle: LevelLifecycle class + LevelLifecycleGameRef interface
+```
+
+## 关键接口
+
+```typescript
+interface LevelLifecycleGameRef extends Phaser.Scene {
+  currentLives: number;
+  maxLives: number;
+  isInputLocked: boolean;
+  removedPaths: Set<number>;
+  // ... 其他场景引用
+}
+
+class LevelLifecycle {
+  loseLife(): void;                // 扣命（由 InputHandler 调用）
+  playDangerFrame(): void;         // 危险闪光（命少时调用）
+  handleLevelSuccess(): void;      // 通关（由 InputHandler 调用）
+  handleTimeOut(): void;           // 超时（由 CountdownDisplay 调用）
+}
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **状态机从 GameScene 中提取** | 关卡生命周期（扣命→危险→胜利→失败）是有限状态机，逻辑复杂；提取为独立类后 Game.ts 不膨胀，状态转换逻辑集中可测试 |
+| **LevelLifecycleGameRef 接口** | 与 InputHandler 相同的接口解耦模式；LevelLifecycle 通过接口读写 Game 状态，不直接引用 Game 类，防止循环依赖 |
+| **软槽位 gameOverDialog** | 胜败面板的视觉风格在不同 Remix 变体中不同；软槽位允许不改 LevelLifecycle 代码的前提下替换面板实现 |
+| **危险闪光帧独立** | `playDangerFrame` 是低血量时的全屏 nomove_hint 闪烁，与"扣命"是两个不同的视觉事件；分离调用让触发时机更精确 |
+
+## Adapter
+
+- **Role**: `levelLifecycle` — 关卡生命周期状态机（扣命/超时/胜利/失败全流程）
+- **Provides**: `LevelLifecycle` 类（`loseLife()`、`handleLevelSuccess()`、`handleTimeOut()`、`playDangerFrame()`），`LevelLifecycleGameRef` 接口
+- **Requires**: `phaser.aicomponent`、`level_state.aicomponent`（LevelManager `nextLevel()`）、`game_over_panel.aicomponent`（软槽位 `gameOverDialog`）
+- **Consumed by**: `game_scene.aicomponent`（持有实例，传给 `path_input_handler` 的 `attemptMovePath` 回调）
+- **Integration point**: `src/game/scenes/GameUI/LevelLifecycle.ts` → `Game.create()` 中实例化并持有
+
+## 软槽位说明
+
+`gameOverDialog` 槽位使用 `matchBindingRoles: ["gameOverDialog"]`，允许替换为不同视觉风格的游戏结束面板。

package/skills/level_lifecycle.aicomponent/manifest.json

@@ -0,0 +1,87 @@
+{
+  "schemaVersion": 1,
+  "atomId": "level_lifecycle.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "component",
+  "mode": "fixed",
+  "label": { "zh": "关卡生命周期控制器", "en": "Level lifecycle controller" },
+  "tags": ["lifecycle", "lives", "timer", "gameover", "win", "lose", "next-level"],
+  "bindingRoles": ["levelLifecycleController"],
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/LevelLifecycle.ts": {
+        "source": "ref/LevelLifecycle.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "imports": [
+    { "slot": "engine",      "pinAtomId": "phaser.aicomponent",        "edgeKind": "requires", "bindAs": "engine" },
+    { "slot": "levelState",  "pinAtomId": "level_state.aicomponent",   "edgeKind": "requires", "bindAs": "levelState" },
+    {
+      "slot": "gameOverDialog",
+      "description": "游戏结束面板组件（胜利/失败结果展示）",
+      "bindAs": "gameOverPanel",
+      "required": true,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["gameOverDialog"],
+      "allowedBundleTypes": ["aicomponent"]
+    },
+    {
+      "slot": "sfxSuccess",
+      "description": "关卡通关成功音效",
+      "bindAs": "sfxSuccess",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["sfxSuccess"],
+      "allowedBundleTypes": ["aiaudio"]
+    },
+    {
+      "slot": "sfxFail",
+      "description": "关卡失败音效",
+      "bindAs": "sfxFail",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["sfxFail"],
+      "allowedBundleTypes": ["aiaudio"]
+    },
+    {
+      "slot": "sfxLose",
+      "description": "生命耗尽/游戏结束音效",
+      "bindAs": "sfxLose",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["sfxLose"],
+      "allowedBundleTypes": ["aiaudio"]
+    },
+    {
+      "slot": "dangerFlashOverlay",
+      "description": "危险提示全屏闪光覆盖层图片",
+      "bindAs": "dangerFlashOverlay",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["dangerFlashOverlay"],
+      "allowedBundleTypes": ["aiimage"]
+    }
+  ],
+  "exports": [
+    { "name": "LevelLifecycle",         "kind": "class",     "location": "src/game/scenes/GameUI/LevelLifecycle.ts" },
+    { "name": "LevelLifecycleGameRef",  "kind": "interface", "location": "src/game/scenes/GameUI/LevelLifecycle.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "level state machine managing lives count, win condition detection, game-over display, and automatic level progression",
+    "layers": ["state-machine", "ui-trigger", "progression"],
+    "replaceable": ["auto-next-level behavior", "game-over panel animation", "life display style"]
+  },
+  "usageHints": [
+    "loseLife() 扣除一条命，命归零时自动触发 handleOutOfLives()",
+    "handleLevelSuccess() 在所有路径消除后由 InputHandler 调用，触发胜利流程",
+    "handleTimeOut() 倒计时归零时由 CountdownDisplay 调用",
+    "playDangerFrame() 生命不足时触发全屏危险闪光（调用 nomove_hint 资源）"
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "levelLifecycle": "ref/LevelLifecycle.ts"
+  }
+}