@playcraft/skills 0.0.2

package/skills/gameplay_balance_check.aivalidator/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: gameplay_balance_check.aivalidator
+description: 玩法平衡性校验器 - 分析关卡配置和玩法参数，检查难度合理性、可完成性、首关保胜、CTA 时机
+triggers: 平衡性,balance check,校验,validate,难度检查,difficulty check,关卡校验,level check,可完成性
+---
+
+# 玩法平衡性校验器（Gameplay Balance Checker）
+
+## 说明
+
+分析关卡配置和玩法参数，检查试玩广告的平衡性问题。输出结构化校验报告，涵盖：
+
+- **可完成性**：是否存在不可能完成的关卡
+- **难度曲线**：曲线是否平滑递进，有无突然跳变
+- **首关保胜**：第一关是否保证玩家成功
+- **CTA 时机**：CTA 触发是否在峰值体验之后
+- **时长预算**：总时长是否在 30-60 秒的试玩广告最佳区间
+
+## Imports
+
+（无外部依赖，独立运行）
+
+## 校验维度
+
+| 维度 | 检查内容 | 严重级别 |
+|------|---------|---------|
+| 首关保胜 | `firstLevelGuaranteeWin` 是否为 `true`，首关 `difficultyScale` 是否 ≤ 0.3 | ERROR |
+| 不可能关卡 | 是否存在 `difficultyScale` = 1.0 的关卡 | ERROR |
+| 曲线平滑性 | 相邻关卡难度差是否 > 0.5 | WARNING |
+| CTA 时机 | `ctaTriggerAfterLevel` 是否 ≥ `peakDifficultyLevel` | WARNING |
+| 时长预算 | 所有关卡预估总时长是否在 30-60 秒内 | WARNING |
+| 峰值位置 | 峰值是否在总关卡数的 50%-75% 位置 | INFO |
+
+## 报告格式
+
+```markdown
+# 玩法平衡性校验报告
+
+## 总体评级：✅ PASS / ⚠️ WARNING / ❌ FAIL
+
+### 详细结果
+| # | 维度 | 状态 | 说明 |
+|---|------|------|------|
+| 1 | 首关保胜 | ✅ | difficultyScale[0] = 0.2, firstLevelGuaranteeWin = true |
+| 2 | ... | ... | ... |
+
+### 建议
+- ...
+```
+
+## Skill Definition
+
+tools:
+  - read
+  - write
+  - bash
+prompt_extension: |
+  You are a gameplay balance validator for playable ads (试玩广告).
+  Read game/config.json and all level data files, then check these dimensions:
+  1. First level guarantee: firstLevelGuaranteeWin must be true AND
+     difficultyScale[0] must be ≤ 0.3 (trivially easy)
+  2. Smooth difficulty curve: adjacent levels' difficulty difference must not exceed 0.5
+  3. No impossible levels: no level should have difficultyScale = 1.0
+  4. CTA timing: ctaTriggerAfterLevel should be ≥ peakDifficultyLevel
+     (CTA fires after peak engagement, not before)
+  5. Duration budget: estimated total playtime across all levels should be 30-60 seconds
+     (the sweet spot for playable ad retention)
+  Output a structured markdown report with pass/warn/fail status for each dimension.
+  Write the report to stdout or a designated output path.

package/skills/gameplay_balance_check.aivalidator/manifest.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "atomId": "gameplay_balance_check.aivalidator",
+  "bundleType": "aivalidator",
+  "category": "validator",
+  "mode": "fixed",
+  "label": {
+    "zh": "玩法平衡性校验器",
+    "en": "Gameplay balance checker"
+  },
+  "tags": ["validator", "balance", "gameplay", "difficulty", "level", "quality", "playable-ads"],
+  "bindingRoles": ["levelValidator"],
+  "imports": [],
+  "validation": {
+    "target": "gameplay",
+    "outputFormat": "report"
+  },
+  "files": {
+    "skill": "SKILL.md"
+  }
+}

package/skills/gameplay_unit_test.aivalidator/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: gameplay_unit_test.aivalidator
+description: 路径消除玩法的纯逻辑单元测试框架。使用 vitest 测试 LevelParser、碰撞检测、消除规则、胜负条件，不依赖 Phaser 或浏览器。
+triggers: 单元测试,unit test,vitest,测试玩法,测试逻辑,验证消除规则,test gameplay
+---
+
+# 玩法逻辑单元测试（Gameplay Unit Tests）
+
+## 说明
+
+为路径消除玩法的核心逻辑提供**纯函数单元测试**：
+
+- 不依赖 Phaser（不需要浏览器或 Canvas）
+- 不依赖 DOM（纯 Node.js 环境运行）
+- 测试覆盖：坐标解析、碰撞检测、消除规则、胜负判定
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|------|
+| `tests/gameplay.test.ts` | `ref/gameplay.test.ts` | 完整测试用例 |
+| `vitest.config.ts` | `ref/vitest.config.ts` | Vitest 配置 |
+
+`package.json` 新增：
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  }
+}
+```
+
+## 使用方式
+
+```bash
+pnpm test          # 运行所有测试
+pnpm test:watch    # 监听模式（修改代码自动重跑）
+```
+
+## 测试覆盖
+
+| 模块 | 测试点 |
+|------|--------|
+| `LevelParser` | Cocos→Phaser 坐标翻转 / 路径离散化 / 方向推导 |
+| 碰撞检测 | `isCellOccupied` 正确性 / `ignorePathIndex` 排除自身 |
+| 消除规则 | 方向无阻挡→成功 / 方向有阻挡→失败 / 已消除不参与碰撞 |
+| 胜负条件 | 全部消除→胜利 / 生命归零→失败 |
+| 数据校验 | 坐标越界检测 / 空路径检测 |
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **与 Phaser 完全解耦** | 玩法规则（坐标解析、碰撞检测、消除判断）是纯函数，不需要 Canvas 或 DOM；在 Node.js 中运行测试速度快 10 倍以上 |
+| **Vitest 而非 Jest** | 项目使用 ESM 模块，Vitest 原生支持 ESM + TypeScript，无需额外 Babel 配置 |
+| **测试纯函数，不测场景生命周期** | Phaser Scene 的 `create/update` 测试成本高且价值低；核心算法的正确性才是单元测试的目标 |
+
+## Adapter
+
+- **Role**: `gameplayTest` — 玩法逻辑纯函数单元测试框架
+- **Provides**: `tests/gameplay.test.ts` 测试套件、`vitest.config.ts` 测试配置、`pnpm test` / `pnpm test:watch` 命令
+- **Requires**: `arrow_path_data_format.aicomponent`（LevelParser、LevelTypes 被测对象）
+- **Consumed by**: Agent 在修改游戏逻辑后执行 `pnpm test` 验证正确性；无上游 skill 依赖
+- **Integration point**: 根目录 `vitest.config.ts` —— `pnpm test` 运行 `tests/` 目录下所有测试文件
+
+## Imports
+
+- `arrow_path_data_format.aicomponent`（硬依赖：LevelParser + LevelTypes）
+- `path_elimination_rules.aigameplay`（参考：PGS 测试用例）
+- `level_data_validator.aivalidator`（可选：集成校验测试）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: ref/gameplay.test.ts
+  - source: ref/vitest.config.ts
+outputs:
+  - testSuite: tests/gameplay.test.ts
+  - testConfig: vitest.config.ts
+  - testScripts: test / test:watch npm scripts
+```

package/skills/gameplay_unit_test.aivalidator/manifest.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "atomId": "gameplay_unit_test.aivalidator",
+  "bundleType": "aivalidator",
+  "category": "validator",
+  "mode": "fixed",
+  "label": {
+    "zh": "玩法逻辑单元测试",
+    "en": "Gameplay logic unit tests"
+  },
+  "tags": ["test", "unit-test", "vitest", "gameplay", "quality", "validation"],
+  "bindingRoles": ["testFramework"],
+  "files": {
+    "skill": "SKILL.md",
+    "ref": ["ref/gameplay.test.ts", "ref/vitest.config.ts"]
+  }
+}

package/skills/gameplay_unit_test.aivalidator/ref/gameplay.test.ts

@@ -0,0 +1,202 @@
+import { describe, test, expect } from "vitest";
+import { parseLevelJson } from "../src/game/levels/LevelParser";
+import { ArrowDirection } from "../src/game/levels/LevelTypes";
+import type { RawLevelJson, ParsedLevel } from "../src/game/levels/LevelTypes";
+
+// ─── 测试数据 ────────────────────────────────────
+
+const simpleLevelRaw: RawLevelJson = {
+  name: 1,
+  row: 4,
+  col: 4,
+  arrows: [
+    [[0, 2], [1, 2], [2, 2]], // 水平路径，箭头朝右
+    [[3, 1], [2, 1], [1, 1]], // 水平路径，箭头朝左
+  ],
+  levelTime: 0,
+};
+
+const blockedLevelRaw: RawLevelJson = {
+  name: 2,
+  row: 5,
+  col: 5,
+  arrows: [
+    [[0, 2], [1, 2], [2, 2]],       // 朝右
+    [[3, 2], [3, 3], [3, 4]],       // 在右边挡住第一条路径
+  ],
+  levelTime: 60,
+};
+
+// ─── LevelParser 测试 ────────────────────────────
+
+describe("LevelParser", () => {
+  test("解析基础关卡结构", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    expect(level.index).toBe(1);
+    expect(level.rows).toBe(4);
+    expect(level.cols).toBe(4);
+    expect(level.paths.length).toBe(2);
+    expect(level.timeSeconds).toBe(0);
+  });
+
+  test("Cocos → Phaser 坐标翻转 (y 轴反转)", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    // Cocos y=2 在 4 行棋盘中 → Phaser y = 4-1-2 = 1
+    const firstPath = level.paths[0];
+    expect(firstPath.points[0].y).toBe(1); // rows-1-cocosY = 4-1-2 = 1
+  });
+
+  test("路径方向由最后两点推导", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    // 第一条路径：[0,2] → [1,2] → [2,2]，最后两点 x 递增 → right
+    expect(level.paths[0].direction).toBe(ArrowDirection.Right);
+    // 第二条路径：[3,1] → [2,1] → [1,1]，最后两点 x 递减 → left
+    expect(level.paths[1].direction).toBe(ArrowDirection.Left);
+  });
+
+  test("head 为路径最后一个点", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    expect(level.paths[0].head).toEqual({ x: 2, y: 1 }); // Phaser 坐标
+  });
+
+  test("indices 包含路径覆盖的所有格子", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    const path0 = level.paths[0];
+    // 水平路径 x: 0→1→2, y: 1 (Phaser), cols=4
+    // indices: 1*4+0=4, 1*4+1=5, 1*4+2=6
+    expect(path0.indices).toContain(4);
+    expect(path0.indices).toContain(5);
+    expect(path0.indices).toContain(6);
+    expect(path0.indices.length).toBe(3);
+  });
+
+  test("带时间限制的关卡", () => {
+    const level = parseLevelJson(blockedLevelRaw);
+    expect(level.timeSeconds).toBe(60);
+  });
+});
+
+// ─── 碰撞检测测试 ──────────────────────────────────
+
+describe("碰撞检测", () => {
+  function isCellOccupied(
+    level: ParsedLevel,
+    col: number,
+    row: number,
+    removedPaths: Set<number>,
+    ignorePathIndex?: number,
+  ): boolean {
+    const idx = row * level.cols + col;
+    return level.paths.some((p, i) => {
+      if (removedPaths.has(i)) return false;
+      if (ignorePathIndex !== undefined && i === ignorePathIndex) return false;
+      return p.indices.includes(idx);
+    });
+  }
+
+  test("路径覆盖的格子返回 occupied", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    const removed = new Set<number>();
+    // 第一条路径覆盖 (0,1), (1,1), (2,1)
+    expect(isCellOccupied(level, 0, 1, removed)).toBe(true);
+    expect(isCellOccupied(level, 1, 1, removed)).toBe(true);
+  });
+
+  test("空格子返回 not occupied", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    const removed = new Set<number>();
+    expect(isCellOccupied(level, 3, 3, removed)).toBe(false);
+  });
+
+  test("已消除路径不参与碰撞", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    const removed = new Set<number>([0]); // 第一条路径已消除
+    expect(isCellOccupied(level, 0, 1, removed)).toBe(false);
+  });
+
+  test("ignorePathIndex 排除自身", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    const removed = new Set<number>();
+    // 格子 (0,1) 被路径0占据，但 ignore 路径0 → 返回 false
+    expect(isCellOccupied(level, 0, 1, removed, 0)).toBe(false);
+  });
+});
+
+// ─── 消除规则测试 ──────────────────────────────────
+
+describe("消除规则", () => {
+  function canEliminate(
+    level: ParsedLevel,
+    pathIndex: number,
+    removedPaths: Set<number>,
+  ): boolean {
+    const path = level.paths[pathIndex];
+    const dx = path.direction === "right" ? 1 : path.direction === "left" ? -1 : 0;
+    const dy = path.direction === "down" ? 1 : path.direction === "up" ? -1 : 0;
+
+    let x = path.head.x;
+    let y = path.head.y;
+    const maxSteps = Math.max(level.cols, level.rows) + 1;
+
+    for (let step = 0; step < maxSteps; step++) {
+      x += dx;
+      y += dy;
+      if (x < 0 || y < 0 || x >= level.cols || y >= level.rows) {
+        return true; // 到达边界，可消除
+      }
+      const idx = y * level.cols + x;
+      const blocked = level.paths.some((p, i) => {
+        if (removedPaths.has(i) || i === pathIndex) return false;
+        return p.indices.includes(idx);
+      });
+      if (blocked) return false;
+    }
+    return false;
+  }
+
+  test("方向无阻挡 → 可消除", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    const removed = new Set<number>();
+    // 第一条路径朝右 head=(2,1)，右边 (3,1) 无路径 → 可消除
+    expect(canEliminate(level, 0, removed)).toBe(true);
+  });
+
+  test("方向有阻挡 → 不可消除", () => {
+    const level = parseLevelJson(blockedLevelRaw);
+    const removed = new Set<number>();
+    // 第一条路径朝右，但 col=3 有第二条路径占据 → 不可消除
+    expect(canEliminate(level, 0, removed)).toBe(false);
+  });
+
+  test("消除阻挡路径后 → 原路径可消除", () => {
+    const level = parseLevelJson(blockedLevelRaw);
+    const removed = new Set<number>([1]); // 移除阻挡的第二条路径
+    expect(canEliminate(level, 0, removed)).toBe(true);
+  });
+});
+
+// ─── 胜负条件测试 ──────────────────────────────────
+
+describe("胜负条件", () => {
+  test("所有路径消除 → 胜利", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    const removed = new Set<number>([0, 1]);
+    const isWin = removed.size >= level.paths.length;
+    expect(isWin).toBe(true);
+  });
+
+  test("部分路径消除 → 未胜利", () => {
+    const level = parseLevelJson(simpleLevelRaw);
+    const removed = new Set<number>([0]);
+    const isWin = removed.size >= level.paths.length;
+    expect(isWin).toBe(false);
+  });
+
+  test("生命归零 → 失败", () => {
+    let lives = 3;
+    lives--; // 第一次扣命
+    lives--; // 第二次扣命
+    lives--; // 第三次扣命
+    expect(lives <= 0).toBe(true);
+  });
+});

package/skills/gameplay_unit_test.aivalidator/ref/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "vitest/config";
+import path from "path";
+
+export default defineConfig({
+  test: {
+    globals: true,
+  },
+  resolve: {
+    alias: {
+      assets: path.resolve(__dirname, "assets"),
+    },
+  },
+});

package/skills/grid_board_layout.aicomponent/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: grid_board_layout.aicomponent
+description: 格子棋盘布局计算器。根据关卡的行列数和屏幕尺寸计算最优格子大小、棋盘位置和缩放/拖拽边界约束。
+triggers: 需要在屏幕上布局可变尺寸的格子棋盘、计算格子坐标或实现棋盘缩放/拖拽时触发。
+---
+
+# 格子棋盘布局（Grid Board Layout）
+
+## 说明
+
+**布局系数**：棋盘可用区域、cell 尺寸与边距须与 **`responsive_2d_layout.aicomponent` 第一节（Layout Canon）** 一致——使用同一套 \(W_r, H_r\)、**uiScale / vScale**，不得在棋盘模块内单独发明一套缩放比。
+
+**纵向扣减**：顶栏 / 底栏预留高度与 **`playable_hud_layout.aicomponent`** 合同一致（`H_mid = H_r - H_top - H_bottom`）。
+
+**职责边界**：本 skill 只做「在已给定可用矩形内的格子几何」；顶栏/底栏预留高度若来自设计稿 dp，通过 **vScale**（或 Canon 规定的等价方式）换算，与全局 UI 对齐。
+
+`BoardLayout` 负责将 `rows × cols` 的棋盘正确布局在屏幕内：
+
+- 根据屏幕可用高度（减去 UI 条）和 `rows × cols` 计算最优 `cellSize`
+- 应用 `CELL_SPACING_MULTIPLIER`（默认 1.15）放大格子间距，提升点击体验
+- 计算 `boardOffsetX / boardOffsetY`（棋盘左上角坐标）
+- 计算缩放/拖拽的边界约束（`minZoom / maxZoom / panBounds`）
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|-----|
+| `src/game/scenes/GameUI/BoardLayout.ts` | `ref/BoardLayout.ts` | 棋盘布局计算 |
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖）
+- `responsive_2d_layout.aicomponent`（硬依赖：屏幕尺寸参数）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/BoardLayout.ts
+outputs:
+  - boardLayout: computeBoardLayout() + BoardLayout module
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **纯计算，无渲染** | `computeBoardLayout()` 是纯函数，输入为行列数+屏幕尺寸，输出为几何参数；渲染器（PathRenderer/InputHandler）依赖此数据，反向依赖会造成循环 |
+| **遵从 Layout Canon** | cellSize 和偏移量必须使用 `uiScale/vScale` 换算，不得另起一套缩放；保证棋盘与 UI 坐标系一致 |
+| **CELL_SPACING_MULTIPLIER 放大格子间距** | 实际格子稍小于 cellSize，留出视觉间距和点击余量；1.15 是试玩广告实践中手感较好的值 |
+
+## Adapter
+
+- **Role**: `gridBoardLayout` — 可变尺寸格子棋盘的几何布局计算器
+- **Provides**: `computeBoardLayout()` 函数、`BoardLayout` 类型（cellSize、boardOffsetX/Y、minZoom、maxZoom、panBounds）
+- **Requires**: `phaser.aicomponent`、`responsive_2d_layout.aicomponent`（屏幕尺寸参数，确保坐标系一致）
+- **Consumed by**: `game_scene.aicomponent`（初始化棋盘几何）、`path_renderer.aicomponent`（格子像素坐标）、`path_input_handler.aicomponent`（命中检测）、`debug_overlay.aicomponent`（格子坐标可视化）
+- **Integration point**: `src/game/scenes/GameUI/BoardLayout.ts` → `Game.ts` 在 `create()` 中调用 `computeBoardLayout()` 并缓存结果
+
+## 使用示例
+
+```typescript
+const layout = computeBoardLayout({
+  rows: level.rows,
+  cols: level.cols,
+  screenWidth: width,
+  screenHeight: height,
+  topUIHeight: GAME_TOP_UI_BAR_HEIGHT,
+});
+
+this.cellSize    = layout.cellSize;
+this.boardOffsetX = layout.boardOffsetX;
+this.boardOffsetY = layout.boardOffsetY;
+
+// 格子中心坐标
+cellCenter(col: number, row: number) {
+  return {
+    x: this.boardOffsetX + col * this.cellWidth + this.cellWidth / 2,
+    y: this.boardOffsetY + row * this.cellHeight + this.cellHeight / 2,
+  };
+}
+```

package/skills/grid_board_layout.aicomponent/manifest.json

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": 1,
+  "atomId": "grid_board_layout.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "layout",
+  "mode": "fixed",
+  "label": { "zh": "格子棋盘布局", "en": "Grid board layout" },
+  "tags": ["layout", "grid", "board", "cell-size", "zoom", "pan", "drag-bounds", "threejs", "3d", "xz-plane"],
+  "bindingRoles": ["gridBoardLayout"],
+  "renderBackend": ["phaser", "threejs"],
+  "engineVariants": {
+    "phaser": {
+      "imports": ["phaser.aicomponent", "responsive_2d_layout.aicomponent"],
+      "scaffoldFiles": {
+        "src/game/scenes/GameUI/BoardLayout.ts": { "source": "ref/BoardLayout.ts", "mode": "full", "weight": 10 }
+      }
+    },
+    "threejs": {
+      "imports": ["threejs.aicomponent"],
+      "scaffoldFiles": {
+        "src/game/utils/BoardLayout3D.ts": { "source": "ref/BoardLayout3D.ts", "mode": "full", "weight": 10 },
+        "src/game/rendering/BoardRenderer3D.ts": { "source": "ref/BoardRenderer3D.ts", "mode": "full", "weight": 10 }
+      }
+    }
+  },
+  "sharedFiles": {
+    "src/game/utils/BoardLayoutMath.ts": { "source": "ref/BoardLayoutMath.ts", "mode": "full", "weight": 10 }
+  },
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/BoardLayout.ts": {
+        "source": "ref/BoardLayout.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "imports": [
+    { "slot": "engine",          "pinAtomId": "phaser.aicomponent",                "edgeKind": "requires", "bindAs": "engine" },
+    { "slot": "responsiveLayout","pinAtomId": "responsive_2d_layout.aicomponent",  "edgeKind": "requires", "bindAs": "layout" }
+  ],
+  "exports": [
+    { "name": "BoardLayout",        "kind": "module",    "location": "src/game/scenes/GameUI/BoardLayout.ts" },
+    { "name": "computeBoardLayout", "kind": "function",  "location": "src/game/scenes/GameUI/BoardLayout.ts" },
+    { "name": "BoardLayout3D",      "kind": "class",     "location": "src/game/utils/BoardLayout3D.ts" },
+    { "name": "BoardRenderer3D",    "kind": "class",     "location": "src/game/rendering/BoardRenderer3D.ts" },
+    { "name": "BoardLayoutMath",    "kind": "module",    "location": "src/game/utils/BoardLayoutMath.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "dynamic cell-size calculator for a variable-size grid that fits within screen bounds or 3D camera frustum, with configurable margins and spacing",
+    "layers": ["grid-math", "zoom-constraint", "pan-constraint", "3d-xz-layout"],
+    "replaceable": ["margin ratio", "scale factor", "cell spacing multiplier", "zoom range", "coordinate system"]
+  },
+  "usageHints": [
+    "computeBoardLayout() 根据 rows×cols 和可用空间计算最优格子大小和棋盘偏移（纯数学，引擎无关）",
+    "BoardLayout3D 在 Three.js XZ 平面布局棋盘，getCellWorldPos(col, row) 返回世界坐标",
+    "3D 模式以原点为棋盘中心，cellSize 默认 1.0 世界单位",
+    "BOARD_MARGIN_RATIO 控制棋盘与屏幕边缘的留白比例（默认 0.07）",
+    "CELL_SPACING_MULTIPLIER 放大格子尺寸但保持路径线宽不变，提升点击体验",
+    "返回 cellSize / cellWidth / cellHeight / boardOffsetX / boardOffsetY"
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "boardLayout": "ref/BoardLayout.ts",
+    "boardLayout3D": "ref/BoardLayout3D.ts",
+    "boardRenderer3D": "ref/BoardRenderer3D.ts",
+    "boardLayoutMath": "ref/BoardLayoutMath.ts"
+  }
+}