@playcraft/skills 0.0.2

package/skills/progress_bar.aicomponent/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: progress_bar.aicomponent
+description: 关卡进度条。显示当前关卡已消除路径数/总路径数的比例，直观呈现关卡完成进度。
+triggers: 需要显示关卡进度指示器时触发。
+---
+
+# 关卡进度条（Level Progress Bar）
+
+## Scaffold
+
+`src/game/scenes/GameUI/ProgressDisplay.ts`
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **已消除数/总数比例** | 进度条显示的是"完成了多少"而非剩余多少，正向激励玩家继续；比生命条更直观地传递关卡接近尾声的信息 |
+| **独立于 LevelManager** | ProgressDisplay 只读取已消除路径数，不持有 LevelManager 引用；GameScene 负责同步，DisplayWidget 保持纯视觉 |
+
+## Adapter
+
+- **Role**: `levelProgressBar` — 关卡完成进度条 UI
+- **Provides**: `ProgressDisplay` 类（更新进度百分比 + 渲染进度条）
+- **Requires**: `phaser.aicomponent`（Graphics/Rectangle API）
+- **Consumed by**: `top_ui_bar.aicomponent` 或 `game_scene.aicomponent`（在路径消除时调用 `update(removed, total)`）
+- **Integration point**: `src/game/scenes/GameUI/ProgressDisplay.ts` → 顶部 UI 条或 GameScene 持有实例
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/ProgressDisplay.ts
+outputs:
+  - progressDisplay: ProgressDisplay class
+```

package/skills/progress_bar.aicomponent/manifest.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "atomId": "progress_bar.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "component",
+  "mode": "fixed",
+  "label": { "zh": "关卡进度条", "en": "Level progress bar" },
+  "tags": ["ui", "progress", "bar", "level-progress"],
+  "bindingRoles": ["progressBar"],
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/ProgressDisplay.ts": { "source": "ref/ProgressDisplay.ts", "mode": "full", "weight": 10 }
+    }
+  },
+  "imports": [
+    { "slot": "engine", "pinAtomId": "phaser.aicomponent", "edgeKind": "requires", "bindAs": "engine" }
+  ],
+  "exports": [
+    { "name": "ProgressDisplay", "kind": "class", "location": "src/game/scenes/GameUI/ProgressDisplay.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "horizontal progress bar showing ratio of eliminated paths to total paths in the current level"
+  },
+  "files": { "skill": "SKILL.md", "progressDisplay": "ref/ProgressDisplay.ts" }
+}

package/skills/progress_bar.aicomponent/ref/ProgressDisplay.ts

@@ -0,0 +1,140 @@
+import * as Phaser from "phaser";
+import { DigitRenderer } from "./DigitRenderer";
+
+/**
+ * 进度百分比显示组件（LED / 七段数码管风格）。
+ * 显示一个3位数字后跟百分号（如 "42%"）。
+ */
+export class ProgressDisplay {
+  private scene: Phaser.Scene;
+  private container: Phaser.GameObjects.Container;
+  private digitGraphics: Phaser.GameObjects.Graphics[] = [];
+  private digitWidth: number;
+  private digitHeight: number;
+  private digitSpacing: number;
+  private percentWidth: number;
+  private displayWidth: number;
+  private anchorLeftX: number;
+
+  constructor(
+    scene: Phaser.Scene,
+    parent: Phaser.GameObjects.Container,
+    options: {
+      xLeft: number;
+      y: number;
+      digitWidth: number;
+      digitHeight: number;
+      digitSpacing: number;
+      percentWidth: number;
+    },
+  ) {
+    this.scene = scene;
+    this.digitWidth = options.digitWidth;
+    this.digitHeight = options.digitHeight;
+    this.digitSpacing = options.digitSpacing;
+    this.percentWidth = options.percentWidth;
+    this.anchorLeftX = options.xLeft;
+
+    // 3位数字 + 百分号
+    const totalWidth =
+      this.digitWidth * 3 + this.percentWidth + this.digitSpacing * 3;
+    this.displayWidth = totalWidth;
+
+    this.container = scene.add.container(
+      options.xLeft + totalWidth / 2,
+      options.y,
+    );
+    this.container.setSize(totalWidth, this.digitHeight);
+    parent.add(this.container);
+
+    let offsetX = -totalWidth / 2;
+
+    // 3个数字槽位
+    for (let i = 0; i < 3; i++) {
+      const g = scene.add.graphics();
+      g.setPosition(offsetX + this.digitWidth / 2, 0);
+      offsetX += this.digitWidth;
+      offsetX += this.digitSpacing;
+      this.digitGraphics.push(g);
+      this.container.add(g);
+    }
+
+    // 百分号
+    const percentG = scene.add.graphics();
+    percentG.setPosition(offsetX + this.percentWidth / 2, 0);
+    this.digitGraphics.push(percentG);
+    this.container.add(percentG);
+  }
+
+  /**
+   * 更新容器位置，使第一个可见数字与图标对齐。
+   * 前导空白数字会将容器向左偏移。
+   * @param percent 百分比值
+   */
+  private updatePosition(percent: number): void {
+    let leadingBlanks = 0;
+    if (percent < 100) {
+      leadingBlanks += 1;
+    }
+    if (percent < 10) {
+      leadingBlanks += 1;
+    }
+
+    const blankWidth = leadingBlanks * (this.digitWidth + this.digitSpacing);
+    this.container.x = this.anchorLeftX - blankWidth + this.displayWidth / 2;
+  }
+
+  /**
+   * 根据已消除/总数更新进度显示。
+   * @param removed 已消除的路径数
+   * @param total 总路径数
+   */
+  public updateProgress(removed: number, total: number): void {
+    if (!this.container || this.digitGraphics.length < 4) {
+      return;
+    }
+
+    let percent = 0;
+    if (total > 0) {
+      percent = Math.floor((removed / total) * 100);
+    }
+    percent = Math.max(0, Math.min(100, percent));
+
+    this.updatePosition(percent);
+
+    const color = 0x50536b;
+    const digitWidth = this.digitWidth;
+    const digitHeight = this.digitHeight;
+
+    const hundreds = percent >= 100 ? 1 : -1;
+    const tens = percent >= 10 ? Math.floor((percent % 100) / 10) : -1;
+    const ones = percent % 10;
+
+    // 百位
+    DigitRenderer.drawDigit(
+      this.digitGraphics[0],
+      hundreds,
+      color,
+      digitWidth,
+      digitHeight,
+    );
+    // 十位
+    DigitRenderer.drawDigit(
+      this.digitGraphics[1],
+      tens,
+      color,
+      digitWidth,
+      digitHeight,
+    );
+    // 个位
+    DigitRenderer.drawDigit(
+      this.digitGraphics[2],
+      ones,
+      color,
+      digitWidth,
+      digitHeight,
+    );
+    // 百分号
+    DigitRenderer.drawPercentSign(this.digitGraphics[3], color, digitHeight);
+  }
+}

package/skills/references/xplatform.schema.json5

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "平台私有metadata字段协议",
+  "description": "描述PlayCraft平台渲染各字段表单时的辅助数据结构",
+  "required": [
+  ],
+  "properties": {
+    "value_type": {
+      "type": "string",
+      "const": "path",
+      "description": "可选字段，值类型标识。例如 所描述的目标字段若表示文件路径，例如 value: ./assets/xxx.png，则可以添加 value_type: path 用于平台识别后使用文件解析器处理该目标字段",
+      "examples": [
+        "path"
+      ]
+    },
+    "mime_type": {
+      "type": "string",
+      "description": "可选字段，所描述的目标字段若表示文件/文件路径时可以使用。用于指定文件格式，遵循 MIME 规范",
+      "examples": [
+        "image/png",
+        "image/jpeg",
+        "image/gif",
+        "image/webp",
+        "audio/mpeg",
+        "application/json"
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/skills/responsive_2d_layout.aicomponent/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: responsive_2d_layout.aicomponent
+description: 2D 可玩 UI 布局规范（框架无关）+ 本仓库默认的 Phaser 参考实现。规范定义设计分辨率、uiScale/vScale 与不变量；ref/UiLayout.ts 为 Phaser 绑定，非 Phaser 运行时需按同一公式实现等价逻辑。
+triggers: 需要为试玩或 2D UI 做跨屏适配、从设计稿坐标换算到运行时坐标、或统一 UI 缩放规则时触发。
+---
+
+# 2D 自适应布局（Responsive 2D Layout）
+
+本 skill 分两层：
+
+1. **布局规范（Layout Canon）**：与具体引擎无关；Agent **必须先理解并遵守**，在任何运行时（Phaser、Canvas、DOM、其他）中复用同一套数学与约束。
+2. **Phaser 参考实现**：本仓库提供的默认代码骨架；若项目使用其他引擎，**不得删改规范公式**，只替换「从哪里读取 width/height」的绑定层。
+
+---
+
+## 一、框架无关：布局规范（Layout Canon）
+
+### 1.1 坐标系与设计空间
+
+- **设计稿（Design space）**：固定基准宽 \(W_d\) × 高 \(H_d\)（本系列 skill 约定默认 **750 × 1334**，竖屏可_play 常用；可按项目替换，但须在配置中单点定义）。
+- **原点**：画布左上角为 \((0,0)\)，**x 向右、y 向下**（与常见 2D 画布一致）。
+- **设计像素**：UI 稿上的数值（间距、字号、图标边长）均以设计空间中的 **dp**（design px）理解，记为无单位实数，与 \(W_d, H_d\) 同量纲。
+
+### 1.2 运行时视口
+
+- **运行时布局宽高** \(W_r, H_r\)：Agent 必须从当前「用于摆放 UI 的矩形」读出——在 Phaser 中通常是主摄像机在 **Scale 模式生效后** 的宽高；在 DOM 中可以是根容器 clientWidth/Height；原则一致：**与最终绘制/点击检测使用同一坐标系**。
+- **不规定** 如何实现全屏或 HiDPI（devicePixelRatio、内部渲染倍数由引擎 skill 决定）。规范只要求：用于布局公式的 \(W_r, H_r\) 与 **UI 摆放/命中** 一致。
+
+### 1.3 缩放系数（必须按此定义）
+
+令：
+
+\[
+\text{scaleX} = W_r / W_d,\quad \text{scaleY} = H_r / H_d
+\]
+
+- **uiScale**（整体 UI 可取的最小维缩放，且夹断）：
+
+\[
+\text{rawUiScale} = \min(\text{scaleX}, \text{scaleY}),\quad
+\text{uiScale} = \mathrm{clamp}(\text{rawUiScale}, \text{minScale}, \text{maxScale})
+\]
+
+其中 `minScale`、`maxScale` 为项目配置（默认可沿用 `GameConfig`：0.7～1.4），**须在单点配置中可调，禁止在组件内各自写死缩放**。
+
+- **vScale**（仅随高度变化，用于「贴底 / 贴顶」等垂向比例）：
+
+\[
+\text{vScale} = \text{scaleY} = H_r / H_d
+\]
+
+- **中心点**（运行时像素）：
+
+\[
+\text{centerX} = W_r / 2,\quad \text{centerY} = H_r / 2
+\]
+
+### 1.4 从设计量到运行时的映射（约定）
+
+Agent 布置控件时应**统一**使用下列规则（除非本规范另有说明）：
+
+- **以设计稿为单位的宽高、圆角、描边粗细、图标边长**（各向同性缩放需求）：乘以 **uiScale**。
+- **距屏幕上/下边的垂直距离**（设计稿中从底边向上的距离）：用 **vScale** 换算，例如距底 `80` dp → 运行时 `y = H_r - 80 * vScale`（锚点策略与具体引擎 API 由实现决定，**换算系数必须是 vScale**）。
+- **居中偏移**：相对中心的水平/垂直偏移，优先用 `centerX/centerY` 加 **设计偏移 × uiScale**（与项目现有代码一致）。
+
+### 1.5 布局不变量（跨引擎）
+
+- **单一真理来源**：每个画面/场景一次计算 \(W_r, H_r, \text{uiScale}, \text{vScale}, \text{centerX}, \text{centerY}\)，**全屏 UI 共用**；禁止部分组件自行 `innerWidth/字体模糊估算` 另起一套比例。
+- **棋盘 / 世界内容**：可与 UI 分层；若棋盘 skill 依赖「可用区域高度（扣除顶栏/底栏）」，扣除量须用 **设计稿高度常量 × vScale** 或 **运行时像素** 明确统一，并与本规范中的 \(W_r, H_r\) 一致。
+- **安全区 / 刘海**：若需适配，**先**得到有效 \(W_r', H_r'\)（ inset 后的矩形），再**代入以上公式**替换 \(W_r, H_r\)；公式不变。
+
+---
+
+## 二、Agent 执行要点（与引擎无关）
+
+1. 读取规范第一节，确认项目的 \(W_d, H_d\) 与 `minScale`/`maxScale` 数据源（如 `GameConfig`）。
+2. 在目标运行时实现或调用与 **1.3 节公式等价** 的函数，得到 `uiScale`、`vScale`、`centerX`、`centerY`。
+3. 所有 2D UI 字号、边距、控件尺寸除非特例，均通过 **dp × uiScale** 或 **dp × vScale（垂向边距）** 导出；**禁止** 混用未夹断的 `scaleX` 作为「整体 UI 缩放」以免扁长屏拉伸失调。
+4. 若运行时不是 Phaser：**不要**复制粘贴 Phaser 类型；保留输入为「宽、高 + 配置」、输出为「上述系数与中心点」的纯函数即可。
+
+---
+
+## 三、Phaser 参考实现（本仓库默认）
+
+`ref/UiLayout.ts` 中的 `computeUiLayout(sceneOrCamera, config?)` 即为 **1.3 节** 的 Phaser 绑定：`width/height` 取自主摄像机，`config` 默认 `GameConfig`。
+
+### Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|-----|
+| `src/game/utils/UiLayout.ts` | `ref/UiLayout.ts` | `computeUiLayout()` + 类型定义 |
+
+### Imports
+
+- `phaser.aicomponent`（硬依赖：从 `Phaser.Scene` / `Camera` 取宽高）
+
+### Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/utils/UiLayout.ts
+outputs:
+  - computeUiLayout: function computing responsive UI scale parameters
+  - UiLayoutConfig: interface
+  - UiLayoutResult: interface
+```
+
+### 使用示例（Phaser）
+
+```typescript
+import { computeUiLayout } from '../utils/UiLayout';
+
+// 在 Phaser Scene.create() 中
+const { width, height, uiScale, vScale, centerX, centerY } = computeUiLayout(this);
+
+// UI 元素定位示例（与第一节规范一致）
+const buttonY = height - 80 * vScale;   // 距底 80 dp
+const iconSize = 48 * uiScale;        // 边长 48 dp 的图标
+```
+
+---
+
+## 四、与引擎 skill 的关系
+
+- **`phaser.aicomponent`**：负责画布分辨率、Scale 模式、HiDPR 等 **引擎层** 行为；**UI 逻辑坐标**仍须服从本 skill **第一节** 的 \(W_r, H_r\) 定义（与主摄像机一致）。
+- **`grid_board_layout.aicomponent`**：棋盘几何在已扣除 HUD 的可用区域内计算；所用 **\(W_r, H_r\) 与 uiScale/vScale** 须与本规范一致，避免棋盘与 UI 两套比例。
+
+---
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **规范与实现分离** | Layout Canon（第一节）与引擎无关；若与 `phaser.aicomponent` 合并，则 Three.js 或 DOM 项目无法复用布局数学 |
+| **数学符号表述** | 用 LaTeX 公式明确定义 uiScale/vScale 计算式，消除 Agent 对"缩放"语义的歧义（clamp 边界、最小维优先等） |
+| **vScale 独立于 uiScale** | 垂向间距随高度变化，水平内容随最小维变化，两者不可混用；独立命名强制 Agent 正确选择换算系数 |
+| **单点配置原则** | minScale/maxScale 从 GameConfig 读取，禁止各组件内写死，保证全局一致性 |
+
+## Adapter
+
+- **Role**: `responsiveLayout` — 2D UI 自适应布局规范（Canon）及 Phaser 参考实现
+- **Provides**: 布局数学规范文档（引擎无关）、`computeUiLayout()` Phaser 绑定实现、`UiLayoutResult` 接口类型
+- **Requires**: `phaser.aicomponent`（Phaser 绑定层硬依赖；规范层本身无运行时依赖）
+- **Consumed by**: `grid_board_layout.aicomponent`、`top_ui_bar.aicomponent`、`bottom_ui_bar.aicomponent`、`playable_hud_layout.aicomponent`、`playable_end_screen_layout.aicomponent` 等所有涉及 UI 坐标换算的 skill
+- **Integration point**: `src/game/utils/UiLayout.ts` —— 所有 Phaser Scene 在 `create()` 中调用 `computeUiLayout(this)` 获取布局参数
+
+## 五、屏幕分区与分层（引专用规范 skill）
+
+以下 skill **不重复** 推导 uiScale/vScale，仅在 **本第一节** 之上约定 **顶/底/棋盘/指引/结算** 的合同：
+
+| skill | 内容 |
+|-------|------|
+| `playable_hud_layout.aicomponent` | HUD 顶/底区与中间 playable 区域高度扣减、相对 z-order |
+| `playable_end_screen_layout.aicomponent` | 全屏结算：遮罩、主视觉安全区、主/次 CTA 锚点 |
+| `playable_guidance_layer.aicomponent` | 指引层：遮罩/挖洞/手指缩放、与 HUD 及结算的深度关系 |
+| `bottom_ui_bar.aicomponent` | （Phaser）底栏占位与 `GAME_BOTTOM_UI_BAR_HEIGHT` 与 `GameConfig` 对齐 |
+
+Agent 处理 HUD / 结算 / 指引时 **应加载** 对应规范 skill，再落地到具体 `aicomponent` 代码。

package/skills/responsive_2d_layout.aicomponent/manifest.json

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": 1,
+  "atomId": "responsive_2d_layout.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "layout",
+  "mode": "fixed",
+  "label": { "zh": "2D 自适应布局", "en": "Responsive 2D layout" },
+  "tags": ["layout", "responsive", "scale", "design-size", "ui-scale", "phaser", "layout-canon", "framework-agnostic"],
+  "bindingRoles": ["responsiveLayout"],
+  "scaffold": {
+    "files": {
+      "src/game/utils/UiLayout.ts": {
+        "source": "ref/UiLayout.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "imports": [
+    { "slot": "engine", "pinAtomId": "phaser.aicomponent", "edgeKind": "requires", "bindAs": "engine" }
+  ],
+  "exports": [
+    { "name": "computeUiLayout", "kind": "function",  "location": "src/game/utils/UiLayout.ts" },
+    { "name": "UiLayoutConfig",  "kind": "interface", "location": "src/game/utils/UiLayout.ts" },
+    { "name": "UiLayoutResult",  "kind": "interface", "location": "src/game/utils/UiLayout.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "framework-agnostic layout canon: design WxH, viewport Wr/Hr, uiScale = clamp(min(scaleX,scaleY), minScale, maxScale), vScale = scaleY; Phaser ref in ref/UiLayout.ts",
+    "layers": ["coordinate-system", "scaling", "layout-math", "design-tokens"],
+    "replaceable": ["base design resolution", "min/max scale bounds", "engine adapter"]
+  },
+  "usageHints": [
+    "先读 SKILL.md 第一节 Layout Canon：公式与引擎无关，任何运行时都应复用同一套 uiScale/vScale 定义",
+    "默认设计稿 750×1334；uiScale = clamp(min(Wr/Wd, Hr/Hd), minScale, maxScale)；vScale = Hr/Hd",
+    "同一画面只算一次布局系数，全 UI 共用；安全区先缩小 Wr/Hr 再代入公式",
+    "Phaser 项目用 computeUiLayout(scene)；非 Phaser 实现等价纯函数，禁止仅复制 Phaser 类型",
+    "GameConfig.baseWidth/Height/minScale/maxScale 可覆盖默认值"
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "uiLayout": "ref/UiLayout.ts"
+  }
+}

package/skills/responsive_2d_layout.aicomponent/ref/UiLayout.ts

@@ -0,0 +1,56 @@
+import * as Phaser from 'phaser';
+import { GameConfig } from '../GameConfig';
+
+export interface UiLayoutConfig {
+  baseWidth?: number;
+  baseHeight?: number;
+  minScale?: number;
+  maxScale?: number;
+}
+
+export interface UiLayoutResult {
+  camera: Phaser.Cameras.Scene2D.Camera;
+  width: number;
+  height: number;
+  uiScale: number;
+  vScale: number;
+  centerX: number;
+  centerY: number;
+}
+
+/**
+ * 实现 `responsive_2d_layout.aicomponent` SKILL.md 第一节 Layout Canon（Phaser 绑定）。
+ * 统一计算基于 750x1334 设计稿的 UI 适配参数。
+ *
+ * - uiScale: 以宽高比例中较小值为基准，并限制在 [minScale, maxScale]
+ * - vScale: 仅基于高度的缩放系数，用于纵向坐标（设计稿 Y * vScale）
+ */
+export function computeUiLayout(
+  sceneOrCamera: Phaser.Scene | Phaser.Cameras.Scene2D.Camera,
+  config: UiLayoutConfig = GameConfig,
+): UiLayoutResult {
+  const camera =
+    sceneOrCamera instanceof Phaser.Scene
+      ? sceneOrCamera.cameras.main
+      : sceneOrCamera;
+
+  const { width, height } = camera;
+
+  const baseWidth = config.baseWidth ?? 750;
+  const baseHeight = config.baseHeight ?? 1334;
+
+  const scaleX = width / baseWidth;
+  const scaleY = height / baseHeight;
+
+  const minScale = config.minScale ?? 0.7;
+  const maxScale = config.maxScale ?? 1.4;
+
+  const rawUiScale = Math.min(scaleX, scaleY);
+  const uiScale = Phaser.Math.Clamp(rawUiScale, minScale, maxScale);
+  const vScale = scaleY;
+
+  const centerX = width * 0.5;
+  const centerY = height * 0.5;
+
+  return { camera, width, height, uiScale, vScale, centerX, centerY };
+}

package/skills/run_context_state.aicomponent/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: run_context_state.aicomponent
+description: 运行上下文状态（全局单例）。区分当前运行模式（normal 正常闯关 vs test 测试预览），测试模式下提供自定义关卡数据，影响是否更新关卡进度。
+triggers: 需要区分正式运行和测试/预览模式、注入自定义测试关卡时触发。
+---
+
+# 运行上下文状态（Run Context State）
+
+## 说明
+
+`RunContextRuntime` 是一个模块级全局单例，存储当前运行上下文：
+
+- `null`：正常游戏模式
+- `{ mode: "test", raw, displayName }`：测试/预览模式，使用自定义关卡数据
+
+`RunFlags.affectsProgression` 控制本次运行是否更新关卡进度。
+
+## Scaffold
+
+| 目标路径 | 来源 |
+|---------|-----|
+| `src/game/run/RunContextRuntime.ts` | `ref/RunContextRuntime.ts` |
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/run/RunContextRuntime.ts
+outputs:
+  - runContext: setActiveRunContext / getActiveRunContext / clearActiveRunContext functions
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **模块级单例而非类实例** | 运行上下文是全局唯一的；模块级变量比单例类更简洁，且在 ESM 中天然保证唯一性 |
+| **null 表示正常模式** | 默认值 null 意味着"不需要特殊处理"，减少正常游戏路径中的条件判断 |
+| **`affectsProgression` 独立标志** | 测试模式下不应更新关卡进度，但并非所有非正常模式都不更新；独立标志使语义更精确 |
+
+## Adapter
+
+- **Role**: `runContextState` — 运行上下文全局单例（正常游戏 vs 测试预览模式）
+- **Provides**: `setActiveRunContext()`、`getActiveRunContext()`、`clearActiveRunContext()` 函数，`RunFlags.affectsProgression` 标志
+- **Requires**: 无（纯模块级单例，无运行时依赖）
+- **Consumed by**: `level_state.aicomponent`（读取 `affectsProgression` 决定是否更新关卡进度）、调试/预览工具（注入 `{mode:"test", raw, displayName}`）
+- **Integration point**: `src/game/run/RunContextRuntime.ts` —— 游戏启动时由外部工具或 URL 参数注入测试关卡
+
+## Imports
+
+无（纯模块级单例，不依赖其他 skill）。

package/skills/run_context_state.aicomponent/manifest.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": 1,
+  "atomId": "run_context_state.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "state",
+  "mode": "fixed",
+  "label": { "zh": "运行上下文状态", "en": "Run context state" },
+  "tags": ["state", "run-context", "test-mode", "preview", "debug"],
+  "bindingRoles": ["runContext"],
+  "scaffold": {
+    "files": {
+      "src/game/run/RunContextRuntime.ts": {
+        "source": "ref/RunContextRuntime.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "imports": [],
+  "exports": [
+    { "name": "setActiveRunContext",   "kind": "function", "location": "src/game/run/RunContextRuntime.ts" },
+    { "name": "getActiveRunContext",   "kind": "function", "location": "src/game/run/RunContextRuntime.ts" },
+    { "name": "clearActiveRunContext", "kind": "function", "location": "src/game/run/RunContextRuntime.ts" },
+    { "name": "ActiveRunContext",      "kind": "type",     "location": "src/game/run/RunContextRuntime.ts" },
+    { "name": "RunFlags",              "kind": "type",     "location": "src/game/run/RunContextRuntime.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "global singleton storing the current run mode (normal vs test) and optional test level data, affecting game progression behavior",
+    "layers": ["debug-runtime", "test-mode-gate"]
+  },
+  "usageHints": [
+    "test 模式下游戏使用 RunContext 中提供的自定义关卡数据，不影响正式关卡进度",
+    "affectsProgression: false 的 run 不会更新 LevelManager 的进度",
+    "仅在编辑器/预览场景中写入；游戏场景只读"
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "runContextRuntime": "ref/RunContextRuntime.ts"
+  }
+}

package/skills/run_context_state.aicomponent/ref/RunContextRuntime.ts

@@ -0,0 +1,30 @@
+import type { RawLevelJson } from "../levels/LevelTypes";
+
+export type ActiveRunContext = {
+  mode: "test";
+  raw: RawLevelJson;
+  displayName: string;
+} | null;
+
+export type RunKind = "normal" | "test";
+
+export type RunFlags = {
+  kind: RunKind;
+  affectsProgression: boolean;
+};
+
+let activeRunContext: ActiveRunContext = null;
+
+export function setActiveRunContext(
+  payload: Exclude<ActiveRunContext, null>,
+): void {
+  activeRunContext = payload;
+}
+
+export function getActiveRunContext(): ActiveRunContext {
+  return activeRunContext;
+}
+
+export function clearActiveRunContext(): void {
+  activeRunContext = null;
+}

package/skills/score-fly.aicomponent/SKILL.md

@@ -0,0 +1,31 @@
+# score-fly — Score Fly-Up Animation
+
+Displays a floating score popup that rises and fades out. Provides instant feedback for score gains, combos, or bonuses.
+
+## Animation Sequence
+
+```
+0ms:     Create score text at match position, scale 0
+0→120ms: Scale in 0→1.2 (elastic punch)
+120ms:   Scale settle 1.2→1.0
+120→800ms: Float up + fade out
+800ms:   Destroy text object
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `text` | required | Score string: "+100", "COMBO!", "×3" |
+| `flyHeight` | 60px | Distance to float upward |
+| `duration` | 800ms | Total animation time |
+| `color` | "#FFD700" | Text color (gold by default) |
+| `fontSize` | 32px | Text size |
+| `x`, `y` | required | Screen position to spawn at |
+
+## Common Patterns
+
+- Score gain: `"+100"` in gold
+- Combo multiplier: `"×3 COMBO!"` in orange
+- Perfect: `"PERFECT!"` in rainbow gradient
+- Time bonus: `"+5s"` in blue