refactor: rewritten skill

2026-04-10 12:47:00 +08:00 · 2026-04-10 12:47:00 +08:00 · b8e4f73126
parent 9d6e7a75f8
commit b8e4f73126
3 changed files with 1005 additions and 117 deletions
--- a/.qwen/skills/create-game-module/SKILL.md
+++ b/.qwen/skills/create-game-module/SKILL.md
@ -0,0 +1,246 @@
 ---
 name: Create Game Module
 description: Create a runnable logic module for a board game with 'boardgame-core', '@preact/signals' and 'mutative'
 ---
 # 如何编写游戏模组
 ## 要求
 游戏模组需要导出以下接口：
 ```typescript
 import { IGameContext, createGameCommandRegistry } from '@/index';
 // 定义类型
 export type GameState = {
    //...
 };
 export type Game = IGameContext<GameState>;
 // 创建 mutative 游戏初始状态
 export function createInitialState(): GameState {
    //...
 }
 // 创建命令注册表（可选）
 export const registry = createGameCommandRegistry<GameState>();
 // 运行游戏
 export async function start(game: Game) {
    // ...
 }
 ```
 或者导出为 `GameModule` 对象：
 ```typescript
 import { GameModule } from '@/index';
 export const gameModule: GameModule<GameState> = {
    registry,
    createInitialState,
    start,
 };
 ```
 ## 流程
 ### 0. 确认规则
 规则应当存放在 `rule.md`。
 描述一个桌面游戏的以下要素：
 - **主题**：游戏的世界观和背景
 - **配件**：棋子、卡牌、骰子等物理组件
 - **游戏布置形式**：棋盘、版图、卡牌放置区等
 - **游戏流程**：回合结构、阶段划分
 - **玩家行动**：每回合玩家可以做什么
 - **胜利条件与终局结算**：如何判定胜负
 ### 1. 创建类型
 创建 `types.ts` 并导出游戏所用的类型。
 - 为游戏概念创建字符串枚举类型（如 `PlayerType = 'X' | 'O'`）
 - 使用 `Part<TMeta>` 为游戏配件创建对象类型
 - 使用 `Region` 为游戏区域创建容器类型
 - 设计游戏的全局状态类型
 游戏使用 `mutative` 不可变类型驱动。状态类型必须是**可序列化的**（不支持函数、`Map`、`Set` 等）。
 ```typescript
 import { Part, Region } from '@/index';
 export type PlayerType = 'X' | 'O';
 export type PieceMeta = {
    owner: PlayerType;
 };
 export type Piece = Part<PieceMeta>;
 export type GameState = {
    board: Region;
    pieces: Record<string, Piece>;
    currentPlayer: PlayerType;
    turn: number;
    winner: PlayerType | null;
 };
 ```
 ### 2. 创建游戏配件表
 若某种游戏配件数量较大，可使用csv文件进行配置，否则在代码中inline创建。
 csv文件遵循以下要求：
 - 从`#`开头的内容会被当作注释忽略
 - 第二行为数据类型，会用于生成.d.ts文件
 - 可以有空行
 ```csv
 # parts.csv
 type,player,count
 string,string,int
 kitten,white,8
 kitten,black,8
 cat,white,8
 cat,black,8
 - ```
 ```typescript
 import parts from "./parts.csv";
 const pieces = createPartsFromTable(
    parts,
    (item, index) => `${item.player}-${item.type}-${index + 1}`,
    (item) => item.count
 ) as Record<string, BoopPart>;
 ```
 ### 3. 创建 Prompts
 使用 prompt 来描述需要玩家进行的行动命令 schema。
 - prompt 包含一个 schema 和若干参数
 - 每个参数通常指定某个配件 ID、某个枚举字符串、或者某个数字
 - 参数类型必须是原始类型（`string`、`number`）或字符串枚举
 ```typescript
 import { createPromptDef } from '@/index';
 export const prompts = {
    play: createPromptDef<[PlayerType, number, number]>(
        'play <player> <row:number> <col:number>',
        '选择下子位置'
    ),
 };
 ```
 Prompt schema 语法：
 - `<param>` - 必需参数
 - `[param]` - 可选参数
 - `[param:type]` - 带类型验证的参数（如 `[count:number]`）
 ### 3. 创建游戏流程
 游戏主循环负责协调游戏进程、等待玩家输入、更新状态。
 ```typescript
 export async function start(game: Game) {
    while (true) {
        // game.value 可获取当前的全局状态
        const currentPlayer = game.value.currentPlayer;
        const turnNumber = game.value.turn + 1;
        const turnOutput = await turn(game, currentPlayer, turnNumber);
        // 更新状态
        await game.produceAsync((state) => {
            state.winner = turnOutput.winner;
            if (!state.winner) {
                state.currentPlayer = state.currentPlayer === 'X' ? 'O' : 'X';
                state.turn = turnNumber;
            }
        });
        // 检查游戏结束条件
        if (game.value.winner) break;
    }
    return game.value;
 }
 ```
 回合逻辑示例：
 ```typescript
 async function turn(game: Game, turnPlayer: PlayerType, turnNumber: number) {
    // 获取玩家输入
    const { player, row, col } = await game.prompt(
        prompts.play,
        (player, row, col) => {
            if (player !== turnPlayer) {
                throw `无效的玩家: ${player}。应为 ${turnPlayer}。`;
            } else if (!isValidMove(row, col)) {
                throw `无效位置: (${row}, ${col})。必须在 0 到 ${BOARD_SIZE - 1} 之间。`;
            } else if (isCellOccupied(game, row, col)) {
                throw `格子 (${row}, ${col}) 已被占用。`;
            } else {
                return { player, row, col };
            }
        },
        game.value.currentPlayer
    );
    // 执行放置逻辑
    placePiece(game, row, col, turnPlayer);
    // 返回回合结果
    return { winner: checkWinner(game) };
 }
 ```
 **注意事项：**
 - `game.produce(fn)` 用于同步更新状态
 - `game.produceAsync(fn)` 用于异步更新状态（会等待中断 Promise 完成，适用于播放动画）
 - 验证器函数中抛出字符串错误会返回给玩家，玩家可重新输入
 - 循环必须有明确的退出条件，避免无限循环
 - 玩家取消输入时，`game.prompt()` 会抛出异常，需要适当处理
 ### 4. 创建测试
 基于 `createGameContext` 来测试游戏逻辑。
 - 为每种游戏结束条件准备至少一条测试
 - 为每种玩家行动准备至少一条测试
 - 使用 `createTestContext()` 和 `createTestRegion()` 测试辅助函数
 ```typescript
 import { createGameContext } from '@/core/game';
 import { createInitialState, registry, start } from './my-game';
 describe('My Game', () => {
    it('should detect horizontal win for X', async () => {
        const ctx = createGameContext({
            initialState: createInitialState(),
            registry,
        });
        // 执行一系列操作
        await ctx.run('play X 0 0');
        await ctx.run('play O 1 0');
        await ctx.run('play X 0 1');
        await ctx.run('play O 1 1');
        await ctx.run('play X 0 2');
        expect(ctx.value.winner).toBe('X');
    });
 });
 ```
 ## 完整示例
 参考 `src/samples/boop/` 获取完整的`boop`游戏实现。
 ## 相关资源
 - [API 参考](./references/api.md) - 完整的 API 文档
 - [AGENTS.md](../../AGENTS.md) - 项目代码规范和架构说明
--- a/.qwen/skills/create-game-module/references/api.md
+++ b/.qwen/skills/create-game-module/references/api.md
@ -0,0 +1,759 @@
 # API 参考
 本文档记录游戏模组开发者需要使用的公共 API。
 ## 核心接口
 ### `IGameContext<TState>`
 游戏运行的核心上下文，提供状态访问、随机数、命令执行和提示系统。
 ```typescript
 interface IGameContext<TState extends Record<string, unknown> = {}> {
    readonly value: TState;                           // 当前游戏状态（只读）
    readonly rng: ReadonlyRNG;                        // 随机数生成器（只读）
    // 状态更新
    produce(fn: (draft: TState) => void): void;       // 同步变更状态（基于 mutative）
    produceAsync(fn: (draft: TState) => void): Promise<void>;  // 异步变更状态（等待中断）
    // 命令执行
    run<T>(input: string): Promise<CommandResult<T>>;           // 执行命令字符串
    runParsed<T>(command: Command): Promise<CommandResult<T>>; // 执行已解析的命令
    // 提示系统
    prompt<TResult, TArgs>(
        def: PromptDef<TArgs>,
        validator: PromptValidator<TResult, TArgs>,
        currentPlayer?: string | null
    ): Promise<TResult>;
 }
 ```
 **使用示例：**
 ```typescript
 // 读取状态
 const currentPlayer = game.value.currentPlayer;
 // 同步更新状态
 game.produce((state) => {
    state.score += 10;
 });
 // 异步更新状态（等待动画完成）
 await game.produceAsync((state) => {
    state.phase = 'next';
 });
 // 等待玩家输入
 const result = await game.prompt(
    prompts.move,
    (from, to) => {
        if (!isValidMove(from, to)) {
            throw '无效移动';
        }
        return { from, to };
    }
 );
 ```
 ---
 ### `GameModule<TState, TResult>`
 游戏模块的类型定义，这是开发者创建游戏时需要导出的核心结构。
 ```typescript
 type GameModule<TState extends Record<string, unknown>, TResult = unknown> = {
    registry?: CommandRegistry<IGameContext<TState>>;  // 可选的命令注册表
    createInitialState: () => TState;                   // 创建初始状态
    start: (ctx: IGameContext<TState>) => Promise<TResult>;  // 游戏主循环
 }
 ```
 ---
 ### `createGameCommandRegistry<TState>()`
 创建游戏命令注册表，游戏模组用它来注册自定义命令。
 ```typescript
 function createGameCommandRegistry<TState extends Record<string, unknown> = {}>(): CommandRegistry<IGameContext<TState>>
 ```
 **使用示例：**
 ```typescript
 import { createGameCommandRegistry, IGameContext } from '@/index';
 export type GameState = { score: number };
 export const registry = createGameCommandRegistry<GameState>();
 // 注册命令
 registry.register('addScore <amount:number>', async function(ctx, amount) {
    ctx.produce((state) => {
        state.score += amount;
    });
    return { success: true, result: undefined };
 });
 ```
 ---
 ## 提示系统
 ### `createPromptDef<TArgs>(schema, hintText?)`
 从字符串模式创建 `PromptDef`。
 ```typescript
 function createPromptDef<TArgs>(
    schema: CommandSchema | string,
    hintText?: string
 ): PromptDef<TArgs>
 ```
 **使用示例：**
 ```typescript
 import { createPromptDef } from '@/index';
 export const prompts = {
    // 必需参数
    play: createPromptDef<[PlayerType, number, number]>(
        'play <player> <row:number> <col:number>',
        '选择下子位置'
    ),
    // 可选参数
    draw: createPromptDef<[number?]>(
        'draw [count:number]',
        '抽牌'
    ),
    // 带选项
    trade: createPromptDef<[string, string]>(
        'trade <give> <receive> [--force]',
        '交易'
    ),
 };
 ```
 ---
 ### `PromptDef<TArgs>`
 提示定义，用于 `context.prompt()` 方法。
 ```typescript
 type PromptDef<TArgs extends any[] = any[]> = {
    schema: CommandSchema;    // 命令模式定义
    hintText?: string;        // 可选的提示文本
 }
 ```
 ---
 ### `PromptValidator<TResult, TArgs>`
 提示验证函数类型。验证器函数接收解析后的参数，应返回结果或抛出字符串错误。
 ```typescript
 type PromptValidator<TResult, TArgs extends any[] = any[]> = (...params: TArgs) => TResult;
 ```
 **验证器规则：**
 - 返回任意值表示验证成功，该值将作为 `prompt()` 的返回值
 - 抛出字符串错误表示验证失败，错误消息会返回给玩家，玩家可重新输入
 - 玩家取消输入时，`prompt()` 会抛出异常
 ---
 ### `PromptEvent`
 提示事件对象，通过 `commandRunnerContext.on('prompt', handler)` 监听。
 ```typescript
 type PromptEvent = {
    schema: CommandSchema;
    hintText?: string;
    currentPlayer: string | null;
    tryCommit: (commandOrInput: Command | string) => string | null;  // null=成功，string=错误消息
    cancel: (reason?: string) => void;
 }
 ```
 ---
 ## 零件系统 (Part)
 ### `Part<TMeta>`
 游戏中的可操作物件（棋子、卡牌、骰子等）。
 ```typescript
 type Part<TMeta = {}> = {
    id: string;                    // 唯一标识
    sides?: number;                // 总面数（用于骰子/多面牌）
    side?: number;                 // 当前面
    alignments?: string[];         // 可用对齐方式
    alignment?: string;            // 当前对齐方式
    regionId: string;              // 所属区域 ID
    position: number[];            // 在区域中的位置坐标
 } & Immutable<TMeta>;             // 自定义元数据（不可变）
 ```
 **使用示例：**
 ```typescript
 import { Part } from '@/index';
 export type PieceMeta = {
    owner: 'X' | 'O';
    type: 'pawn' | 'king';
 };
 export type Piece = Part<PieceMeta>;
 // 访问元数据
 const piece: Piece = ...;
 console.log(piece.owner);  // 'X'
 console.log(piece.type);   // 'pawn'
 ```
 ---
 ### 零件操作函数
 #### `flip<TMeta>(part)`
 翻转到下一面（循环）。
 ```typescript
 function flip<TMeta>(part: Part<TMeta>): void
 ```
 #### `flipTo<TMeta>(part, side)`
 翻转到指定面。
 ```typescript
 function flipTo<TMeta>(part: Part<TMeta>, side: number): void
 ```
 #### `roll<TMeta>(part, rng)`
 用 RNG 随机掷骰子。
 ```typescript
 function roll<TMeta>(part: Part<TMeta>, rng: RNG): void
 ```
 ---
 ## 零件工厂 (Part Factory)
 ### `createParts<T>(item, getId, count?)`
 创建多个相同类型的零件。
 ```typescript
 function createParts<T>(
    item: T,
    getId: (index: number) => string,
    count?: number
 ): Record<string, Part<T>>
 ```
 **使用示例：**
 ```typescript
 import { createParts } from '@/index';
 const pieces = createParts(
    { owner: 'X', type: 'pawn' },
    (i) => `piece-x-${i}`,
    5  // 创建 5 个
 );
 ```
 ---
 ### `createPartsFromTable<T>(items, getId, getCount?)`
 从配置表批量创建零件。
 ```typescript
 function createPartsFromTable<T>(
    items: readonly T[],
    getId: (item: T, index: number) => string,
    getCount?: ((item: T) => number) | number
 ): Record<string, Part<T>>
 ```
 **使用示例：**
 ```typescript
 import { createPartsFromTable } from '@/index';
 const cardTable = [
    { name: 'fireball', damage: 3 },
    { name: 'shield', defense: 2 },
 ];
 const cards = createPartsFromTable(
    cardTable,
    (item) => item.name,
    (item) => item.name === 'fireball' ? 4 : 2  // 每种卡牌的数量
 );
 ```
 ---
 ## 区域系统 (Region)
 ### `Region`
 游戏区域（棋盘、手牌区等）。
 ```typescript
 type Region = {
    id: string;                     // 区域 ID
    axes: RegionAxis[];             // 坐标轴定义
    childIds: string[];             // 包含的零件 ID 列表
    partMap: Record<string, string>; // 位置 -> 零件 ID 映射
 }
 ```
 ---
 ### `RegionAxis`
 区域的一个坐标轴。
 ```typescript
 type RegionAxis = {
    name: string;
    min?: number;
    max?: number;
    align?: 'start' | 'end' | 'center';  // 对齐方式
 }
 ```
 ---
 ### `createRegion(id, axes)`
 创建区域。
 ```typescript
 function createRegion(id: string, axes: RegionAxis[]): Region
 ```
 **使用示例：**
 ```typescript
 import { createRegion, createRegionAxis } from '@/index';
 // 创建 3x3 棋盘
 const board = createRegion('board', [
    createRegionAxis('row', 0, 2),
    createRegionAxis('col', 0, 2),
 ]);
 // 或简写
 const board = createRegion('board', [
    { name: 'row', min: 0, max: 2 },
    { name: 'col', min: 0, max: 2 },
 ]);
 ```
 ---
 ### `createRegionAxis(name, min?, max?, align?)`
 创建坐标轴。
 ```typescript
 function createRegionAxis(
    name: string,
    min?: number,
    max?: number,
    align?: 'start' | 'end' | 'center'
 ): RegionAxis
 ```
 ---
 ### 区域操作函数
 #### `applyAlign<TMeta>(region, parts)`
 根据轴的 `align` 配置重新排列零件位置。
 ```typescript
 function applyAlign<TMeta>(region: Region, parts: Record<string, Part<TMeta>>): void
 ```
 #### `shuffle<TMeta>(region, parts, rng)`
 在区域内随机打乱零件位置。
 ```typescript
 function shuffle<TMeta>(region: Region, parts: Record<string, Part<TMeta>>, rng: RNG): void
 ```
 #### `moveToRegion<TMeta>(part, sourceRegion, targetRegion, position?)`
 将零件从一个区域移动到另一个区域。
 ```typescript
 function moveToRegion<TMeta>(
    part: Part<TMeta>,
    sourceRegion: Region | null,
    targetRegion: Region | null,
    position?: number[]
 ): void
 ```
 ---
 ## 命令系统 (Command System)
 ### `Command`
 解析后的命令对象。
 ```typescript
 type Command = {
    name: string;                                    // 命令名
    flags: Record<string, true>;                     // 标志（如 --verbose）
    options: Record<string, unknown>;                // 选项（如 --player X）
    params: unknown[];                               // 位置参数
 }
 ```
 ---
 ### `CommandSchema`
 命令模式定义，用于验证和解析。
 ```typescript
 type CommandSchema = {
    name: string;
    params: CommandParamSchema[];
    options: Record<string, CommandOptionSchema>;
    flags: Record<string, CommandFlagSchema>;
 }
 ```
 ---
 ### `CommandResult<T>`
 命令执行结果（判别联合类型）。
 ```typescript
 type CommandResult<T = unknown> =
    | { success: true; result: T }
    | { success: false; error: string }
 ```
 **使用示例：**
 ```typescript
 const result = await game.run('move piece1 piece2');
 if (result.success) {
    console.log('命令执行成功', result.result);
 } else {
    console.error('命令执行失败', result.error);
 }
 ```
 ---
 ### `CommandDef<TContext, TFunc>`
 命令定义对象，用于 `registry.register()`。
 ```typescript
 type CommandDef<TContext, TFunc extends CommandFunction<TContext>> = {
    schema: string | CommandSchema;
    run: TFunc;
 }
 type CommandFunction<TContext> = (ctx: TContext, ...args: any[]) => Promise<unknown>;
 ```
 ---
 ### `CommandRegistry<TContext>`
 命令注册表。
 ```typescript
 class CommandRegistry<TContext> extends Map<string, CommandRunner<TContext>> {
    register<TFunc>(
        ...args: [schema: CommandSchema | string, run: TFunc] | [CommandDef<TContext, TFunc>]
    ): (ctx, ...args) => Promise<TResult>
 }
 ```
 **注册命令的两种方式：**
 ```typescript
 // 方式 1：直接传入 schema 和函数
 registry.register('move <from> <to>', async function(ctx, from, to) {
    ctx.produce((state) => { /* 修改状态 */ });
    return { success: true, result: undefined };
 });
 // 方式 2：使用 CommandDef 对象
 registry.register({
    schema: 'move <from> <to>',
    run: async function(ctx, from, to) {
        ctx.produce((state) => { /* 修改状态 */ });
        return { success: true, result: undefined };
    }
 });
 ```
 ---
 ### `parseCommand(input, schema?)`
 解析命令字符串为 `Command` 对象。
 ```typescript
 function parseCommand(input: string, schema?: CommandSchema): Command
 ```
 ---
 ### `parseCommandSchema(schemaStr, name?)`
 从字符串模式解析命令模式。
 ```typescript
 function parseCommandSchema(schemaStr: string, name?: string): CommandSchema
 ```
 **Schema 语法：**
 - `<param>` - 必需参数
 - `[param]` - 可选参数
 - `[param:type]` - 带类型验证的参数（如 `[count:number]`）
 - `--option:value` - 必需选项
 - `[-o value]` - 可选选项
 - `[--flag]` - 可选标志
 ---
 ## 随机数生成器 (RNG)
 ### `ReadonlyRNG`
 只读 RNG 接口（`IGameContext.rng` 返回此类型）。
 ```typescript
 interface ReadonlyRNG {
    next(max?: number): number;     // [0,1) 随机数，或 [0,max)
    nextInt(max: number): number;   // [0,max) 随机整数
 }
 ```
 ---
 ### `RNG`
 可设置种子的 RNG 接口。
 ```typescript
 interface RNG extends ReadonlyRNG {
    setSeed(seed: number): void;
    getSeed(): number;
 }
 ```
 **使用示例：**
 ```typescript
 // 在 IGameContext 中使用
 const roll = game.rng.nextInt(6) + 1;  // 1-6 的随机数
 // 在区域操作中使用时
 shuffle(region, parts, rng);  // 需要传入 RNG
 ```
 ---
 ## 可变信号 (MutableSignal)
 ### `MutableSignal<T>`
 扩展自 Preact Signal 的可变信号类，支持 mutative-style 的 `produce` 方法。
 ```typescript
 class MutableSignal<T> extends Signal<T> {
    produce(fn: (draft: T) => void): void;
    addInterruption(promise: Promise<void>): void;    // 添加中断 Promise（用于动画等待）
    clearInterruptions(): void;                        // 清除所有中断
    produceAsync(fn: (draft: T) => void): Promise<void>;  // 等待中断后更新状态
 }
 ```
 ---
 ### `mutableSignal<T>(initial?, options?)`
 创建可变信号。
 ```typescript
 function mutableSignal<T>(initial?: T, options?: SignalOptions<T>): MutableSignal<T>
 ```
 ---
 ## 游戏主机 (GameHost)
 ### `GameHost<TState, TResult>`
 游戏会话的生命周期管理器。
 ```typescript
 class GameHost<TState, TResult> {
    readonly state: ReadonlySignal<TState>;                    // 游戏状态（响应式）
    readonly status: ReadonlySignal<GameHostStatus>;           // 运行状态
    readonly activePromptSchema: ReadonlySignal<CommandSchema | null>;   // 当前活动提示的模式
    readonly activePromptPlayer: ReadonlySignal<string | null>;          // 当前等待输入的玩家
    readonly activePromptHint: ReadonlySignal<string | null>;            // 当前提示文本
    tryInput(input: string): string | null;                    // 尝试提交输入，返回错误信息或 null
    tryAnswerPrompt<TArgs>(def: PromptDef<TArgs>, ...args: TArgs): void;  // 尝试回答提示
    addInterruption(promise: Promise<void>): void;             // 注册中断 Promise（用于动画）
    clearInterruptions(): void;                                // 清除所有中断
    start(seed?: number): Promise<TResult>;                    // 启动游戏
    dispose(): void;                                           // 销毁游戏
    on(event: 'start' | 'dispose', listener: () => void): () => void;  // 注册事件监听
 }
 ```
 ---
 ### `GameHostStatus`
 ```typescript
 type GameHostStatus = 'created' | 'running' | 'disposed';
 ```
 ---
 ### `createGameHost<TState>(gameModule)`
 从游戏模块创建 `GameHost` 实例。
 ```typescript
 function createGameHost<TState extends Record<string, unknown>>(
    gameModule: GameModule<TState>
 ): GameHost<TState>
 ```
 **使用示例：**
 ```typescript
 import { createGameHost } from '@/index';
 import { gameModule } from './my-game';
 const host = createGameHost(gameModule);
 // 启动游戏
 const result = await host.start(42);  // 传入种子
 // 提交玩家输入
 const error = host.tryInput('play X 0 0');
 if (error) {
    console.error('输入错误:', error);
 }
 // 监听事件
 host.on('start', () => console.log('游戏开始'));
 host.on('dispose', () => console.log('游戏结束'));
 // 销毁游戏
 host.dispose();
 ```
 ---
 ## Preact Signals 重新导出
 ```typescript
 export * from '@preact/signals-core';
 ```
 开发者可直接使用 `@preact/signals-core` 的所有导出，包括：
 - `Signal<T>` - 基础信号类
 - `ReadonlySignal<T>` - 只读信号类型
 - `signal<T>(value)` - 创建信号
 - `computed<T>(fn)` - 创建计算信号
 - `effect(fn)` - 创建副作用
 - `batch(fn)` - 批量更新
 - `untracked(fn)` - 非追踪读取
 ---
 ## 测试辅助函数
 以下函数主要用于测试代码：
 ### `createGameContext(options)`
 创建游戏上下文实例。
 ```typescript
 function createGameContext<TState>(options: {
    initialState: TState;
    registry?: CommandRegistry<IGameContext<TState>>;
    rng?: RNG;
 }): IGameContext<TState>
 ```
 **使用示例：**
 ```typescript
 import { createGameContext } from '@/core/game';
 import { createInitialState, registry } from './my-game';
 const ctx = createGameContext({
    initialState: createInitialState(),
    registry,
 });
 // 执行命令
 await ctx.run('move piece1 piece2');
 // 断言状态
 expect(ctx.value.score).toBe(10);
 ```
 ---
 ### `createTestContext()`
 创建用于测试的游戏上下文（简化版）。
 ```typescript
 function createTestContext<TState>(initialState: TState): IGameContext<TState>
 ```
 ---
 ### `createTestRegion()`
 创建用于测试的区域。
 ```typescript
 function createTestRegion(): Region
 ```
--- a/skills/game-module.md
+++ b/skills/game-module.md
@ -1,117 +0,0 @@
 # 如何编写游戏模组
 ## 要求
 游戏模组需要以下接口导出：
 ```
 import {createGameCommandRegistry, IGameContext} from "boardgame-core";
 // 定义类型
 export type GameState = {
    //...
 }
 export type Game = IGameContext<GameState>;
 // 创建mutative游戏初始状态
 export function createInitialState(): GameState {
    //...
 }
 // 运行游戏
 export async function start(game: Game) {
    // ...
 }
 ```
 ## 流程
 0. 确认规则。
 规则应当存放在`rule.md`。
 描述一个桌面游戏的以下要素：
 - 主题
 - 配件
 - 游戏布置形式
 - 游戏流程
 - 玩家行动
 - 胜利条件与终局结算
 1. 创建类型：创建`types.ts`并导出游戏所用的类型。
 - 为游戏概念创建字符串枚举类型。
 - 使用`@/core/part.ts`为游戏配件创建对象类型。
 - 使用`@/core/region.ts`为游戏区域创建容器类型。
 - 设计游戏的全局状态类型。
 游戏使用`mutative`不可变类型驱动。
 2. 创建prompts：
 使用prompt来描述需要玩家进行的行动命令schema。
 - prompt包含一个id和若干params。
 - 每个param通常指定某个配件id、某个枚举字符串、或者某个数字。
 ```typescript
 export const prompts = {
    play: createPromptDef<[PlayerType, number, number]>(
        'play <player> <row:number> <col:number>',
        '选择下子位置')
 }
 ```
 3. 创建游戏流程：
 ```typescript
 export async function start(game: TicTacToeGame) {
    while (true) {
        // game.value可获取当前的全局状态
        const currentPlayer = game.value.currentPlayer;
        const turnNumber = game.value.turn + 1;
        const turnOutput = await turn(game, currentPlayer, turnNumber);
        // 更新状态
        await game.produceAsync(state => {
            state.winner = turnOutput.winner;
            if (!state.winner) {
                state.currentPlayer = state.currentPlayer === 'X' ? 'O' : 'X';
                state.turn = turnNumber;
            }
        });
        if (game.value.winner) break;
    }
    return game.value;
 }
 ```
 ```typescript
 async function run(game: TicTacToeGame, turnPlayer: PlayerType, turnNumber: number) {
    // 获取玩家输入
    const {player, row, col} = await game.prompt(
        prompts.play,
        (player, row, col) => {
            if (player !== turnPlayer) {
                throw `Invalid player: ${player}. Expected ${turnPlayer}.`;
            } else if (!isValidMove(row, col)) {
                throw `Invalid position: (${row}, ${col}). Must be between 0 and ${BOARD_SIZE - 1}.`;
            } else if (isCellOccupied(game, row, col)) {
                throw `Cell (${row}, ${col}) is already occupied.`;
            } else {
                return {player, row, col};
            }
        },
        game.value.currentPlayer
    );
    placePiece(game, row, col, turnPlayer);
 }
 ```
 4. 创建测试
 基于`@/core/game.ts`的createGameContext来测试。
 为每种游戏结束条件准备至少一条测试。
 为每种玩家行动至少准备一条测试。