---
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）。