refactor: fix command parsing

src/core/context.ts

@@ -2,7 +2,7 @@ import {createModel, Signal, signal} from '@preact/signals-core';
 import {createEntityCollection} from "../utils/entity";
 import {Part} from "./part";
 import {Region} from "./region";
-import {RuleRegistry, RuleContext, dispatchCommand as dispatchRuleCommand} from "./rule";
+import {RuleDef, RuleRegistry, RuleContext, GameContextLike, dispatchCommand as dispatchRuleCommand} from "./rule";
 
 export type Context = {
     type: string;
@@ -37,11 +37,34 @@ export const GameContext = createModel((root: Context) => {
         return undefined;
     }
 
-    function dispatchCommand(input: string) {
+    function registerRule(name: string, rule: RuleDef<unknown>) {
+        const newRules = new Map(rules.value);
+        newRules.set(name, rule);
+        rules.value = newRules;
+    }
+
+    function unregisterRule(name: string) {
+        const newRules = new Map(rules.value);
+        newRules.delete(name);
+        rules.value = newRules;
+    }
+
+    function addRuleContext(ctx: RuleContext<unknown>) {
+        ruleContexts.value = [...ruleContexts.value, ctx];
+    }
+
+    function removeRuleContext(ctx: RuleContext<unknown>) {
+        ruleContexts.value = ruleContexts.value.filter(c => c !== ctx);
+    }
+
+    function dispatchCommand(this: GameContextLike, input: string) {
         return dispatchRuleCommand({
+            ...this,
             rules: rules.value,
             ruleContexts: ruleContexts.value,
             contexts,
+            addRuleContext,
+            removeRuleContext,
         }, input);
     }
 
@@ -54,11 +77,15 @@ export const GameContext = createModel((root: Context) => {
         pushContext,
         popContext,
         latestContext,
+        registerRule,
+        unregisterRule,
         dispatchCommand,
     }
 })
 
-/** 创建游戏上下文实例 */
+/** 创建游æˆ<EFBFBD>上下文实ä¾?*/
 export function createGameContext(root: Context = { type: 'game' }) {
     return new GameContext(root);
 }
+
+export type GameContextInstance = ReturnType<typeof createGameContext>;

src/core/rule.ts

@@ -1,11 +1,19 @@
-import {Command, CommandSchema, parseCommand, parseCommandSchema} from "../utils/command";
+import {Command, CommandSchema, parseCommand, parseCommandSchema, applyCommandSchema} from "../utils/command";
 
-export type RuleState = 'running' | 'yielded' | 'waiting' | 'done';
+export type RuleState = 'running' | 'yielded' | 'waiting' | 'invoking' | 'done';
+
+export type InvokeYield = {
+    type: 'invoke';
+    rule: string;
+    command: Command;
+};
+
+export type RuleYield = string | CommandSchema | InvokeYield;
 
 export type RuleContext<T = unknown> = {
     type: string;
     schema?: CommandSchema;
-    generator: Generator<string | CommandSchema, T, Command>;
+    generator: Generator<RuleYield, T, Command | RuleContext<unknown>>;
     parent?: RuleContext<unknown>;
     children: RuleContext<unknown>[];
     state: RuleState;
@@ -14,14 +22,14 @@ export type RuleContext<T = unknown> = {
 
 export type RuleDef<T = unknown> = {
     schema: CommandSchema;
-    create: (cmd: Command) => Generator<string | CommandSchema, T, Command>;
+    create: (this: GameContextLike, cmd: Command) => Generator<RuleYield, T, Command | RuleContext<unknown>>;
 };
 
 export type RuleRegistry = Map<string, RuleDef<unknown>>;
 
 export function createRule<T>(
     schemaStr: string,
-    fn: (cmd: Command) => Generator<string | CommandSchema, T, Command>
+    fn: (this: GameContextLike, cmd: Command) => Generator<RuleYield, T, Command | RuleContext<unknown>>
 ): RuleDef<T> {
     return {
         schema: parseCommandSchema(schemaStr, ''),
@@ -29,6 +37,10 @@ export function createRule<T>(
     };
 }
 
+function isInvokeYield(value: RuleYield): value is InvokeYield {
+    return typeof value === 'object' && value !== null && 'type' in value && (value as InvokeYield).type === 'invoke';
+}
+
 function parseYieldedSchema(value: string | CommandSchema): CommandSchema {
     if (typeof value === 'string') {
         return parseCommandSchema(value, '');
@@ -36,15 +48,18 @@ function parseYieldedSchema(value: string | CommandSchema): CommandSchema {
     return value;
 }
 
+function parseCommandWithSchema(command: Command, schema: CommandSchema): Command {
+    return applyCommandSchema(command, schema).command;
+}
+
 function pushContextToGame(game: GameContextLike, ctx: RuleContext<unknown>) {
     game.contexts.value = [...game.contexts.value, { value: ctx } as any];
-    game.ruleContexts.push(ctx);
+    game.addRuleContext(ctx);
 }
 
 function discardChildren(game: GameContextLike, parent: RuleContext<unknown>) {
     for (const child of parent.children) {
-        const idx = game.ruleContexts.indexOf(child);
-        if (idx !== -1) game.ruleContexts.splice(idx, 1);
+        game.removeRuleContext(child);
 
         const ctxIdx = game.contexts.value.findIndex((c: any) => c.value === child);
         if (ctxIdx !== -1) {
@@ -80,6 +95,85 @@ function validateYieldedSchema(command: Command, schema: CommandSchema): boolean
     return true;
 }
 
+function invokeChildRule(
+    game: GameContextLike,
+    ruleName: string,
+    command: Command,
+    parent: RuleContext<unknown>
+): RuleContext<unknown> {
+    const ruleDef = game.rules.get(ruleName)!;
+    const ctx: RuleContext<unknown> = {
+        type: ruleDef.schema.name,
+        schema: undefined,
+        generator: ruleDef.create.call(game, command),
+        parent,
+        children: [],
+        state: 'running',
+        resolution: undefined,
+    };
+
+    parent.children.push(ctx);
+    pushContextToGame(game, ctx);
+
+    return stepGenerator(game, ctx);
+}
+
+function resumeInvokingParent(
+    game: GameContextLike,
+    childCtx: RuleContext<unknown>
+): RuleContext<unknown> | undefined {
+    const parent = childCtx.parent;
+    if (!parent || parent.state !== 'invoking') return undefined;
+
+    parent.children = parent.children.filter(c => c !== childCtx);
+
+    const result = parent.generator.next(childCtx);
+    if (result.done) {
+        (parent as RuleContext<unknown>).resolution = result.value;
+        (parent as RuleContext<unknown>).state = 'done';
+        const resumed = resumeInvokingParent(game, parent);
+        return resumed ?? parent;
+    } else if (isInvokeYield(result.value)) {
+        (parent as RuleContext<unknown>).state = 'invoking';
+        const childCtx2 = invokeChildRule(game, result.value.rule, result.value.command, parent);
+        return childCtx2;
+    } else {
+        (parent as RuleContext<unknown>).schema = parseYieldedSchema(result.value);
+        (parent as RuleContext<unknown>).state = 'yielded';
+    }
+
+    return parent;
+}
+
+function stepGenerator<T>(
+    game: GameContextLike,
+    ctx: RuleContext<T>
+): RuleContext<T> {
+    const result = ctx.generator.next();
+
+    if (result.done) {
+        ctx.resolution = result.value;
+        ctx.state = 'done';
+        const resumed = resumeInvokingParent(game, ctx as RuleContext<unknown>);
+        if (resumed) return resumed as RuleContext<T>;
+    } else if (isInvokeYield(result.value)) {
+        const childRuleDef = game.rules.get(result.value.rule);
+        if (childRuleDef) {
+            ctx.state = 'invoking';
+            const childCtx = invokeChildRule(game, result.value.rule, result.value.command, ctx as RuleContext<unknown>);
+            return childCtx as RuleContext<T>;
+        } else {
+            ctx.schema = parseYieldedSchema('');
+            ctx.state = 'yielded';
+        }
+    } else {
+        ctx.schema = parseYieldedSchema(result.value);
+        ctx.state = 'yielded';
+    }
+
+    return ctx;
+}
+
 function invokeRule<T>(
     game: GameContextLike,
     command: Command,
@@ -89,7 +183,7 @@ function invokeRule<T>(
     const ctx: RuleContext<T> = {
         type: ruleDef.schema.name,
         schema: undefined,
-        generator: ruleDef.create(command),
+        generator: ruleDef.create.call(game, command),
         parent,
         children: [],
         state: 'running',
@@ -104,16 +198,7 @@ function invokeRule<T>(
 
     pushContextToGame(game, ctx as RuleContext<unknown>);
 
-    const result = ctx.generator.next();
-    if (result.done) {
-        ctx.resolution = result.value;
-        ctx.state = 'done';
-    } else {
-        ctx.schema = parseYieldedSchema(result.value);
-        ctx.state = 'yielded';
-    }
-
-    return ctx;
+    return stepGenerator(game, ctx);
 }
 
 export function dispatchCommand(game: GameContextLike, input: string): RuleContext<unknown> | undefined {
@@ -121,20 +206,28 @@ export function dispatchCommand(game: GameContextLike, input: string): RuleConte
 
     if (game.rules.has(command.name)) {
         const ruleDef = game.rules.get(command.name)!;
+        const typedCommand = parseCommandWithSchema(command, ruleDef.schema);
 
         const parent = findYieldedParent(game);
 
-        return invokeRule(game, command, ruleDef, parent);
+        return invokeRule(game, typedCommand, ruleDef, parent);
     }
 
     for (let i = game.ruleContexts.length - 1; i >= 0; i--) {
         const ctx = game.ruleContexts[i];
         if (ctx.state === 'yielded' && ctx.schema) {
             if (validateYieldedSchema(command, ctx.schema)) {
-                const result = ctx.generator.next(command);
+                const typedCommand = parseCommandWithSchema(command, ctx.schema);
+                const result = ctx.generator.next(typedCommand);
                 if (result.done) {
                     ctx.resolution = result.value;
                     ctx.state = 'done';
+                    const resumed = resumeInvokingParent(game, ctx);
+                    return resumed ?? ctx;
+                } else if (isInvokeYield(result.value)) {
+                    ctx.state = 'invoking';
+                    const childCtx = invokeChildRule(game, result.value.rule, result.value.command, ctx);
+                    return childCtx;
                 } else {
                     ctx.schema = parseYieldedSchema(result.value);
                     ctx.state = 'yielded';
@@ -157,8 +250,25 @@ function findYieldedParent(game: GameContextLike): RuleContext<unknown> | undefi
     return undefined;
 }
 
-type GameContextLike = {
+export type GameContextLike = {
     rules: RuleRegistry;
     ruleContexts: RuleContext<unknown>[];
     contexts: { value: any[] };
+    addRuleContext: (ctx: RuleContext<unknown>) => void;
+    removeRuleContext: (ctx: RuleContext<unknown>) => void;
+    parts: {
+        collection: { value: Record<string, any> };
+        add: (...entities: any[]) => void;
+        remove: (...ids: string[]) => void;
+        get: (id: string) => any;
+    };
+    regions: {
+        collection: { value: Record<string, any> };
+        add: (...entities: any[]) => void;
+        remove: (...ids: string[]) => void;
+        get: (id: string) => any;
+    };
+    pushContext: (context: any) => any;
+    popContext: () => void;
+    latestContext: <T>(type: string) => any | undefined;
 };

src/index.ts

@@ -18,7 +18,7 @@ export { createRule, dispatchCommand } from './core/rule';
 
 // Utils
 export type { Command, CommandSchema, CommandParamSchema, CommandOptionSchema, CommandFlagSchema } from './utils/command';
-export { parseCommand, parseCommandSchema, validateCommand } from './utils/command';
+export { parseCommand, parseCommandSchema, validateCommand, parseCommandWithSchema, applyCommandSchema } from './utils/command';
 
 export type { Entity, EntityAccessor } from './utils/entity';
 export { createEntityCollection } from './utils/entity';

src/samples/tic-tac-toe.ts

@@ -0,0 +1,155 @@
+import { GameContextInstance } from '../core/context';
+import type { GameContextLike, RuleContext } from '../core/rule';
+import { createRule, type InvokeYield, type RuleYield } from '../core/rule';
+import type { Command } from '../utils/command';
+import type { Part } from '../core/part';
+import type { Region } from '../core/region';
+import type { Context } from '../core/context';
+
+export type TicTacToeState = Context & {
+    type: 'tic-tac-toe';
+    currentPlayer: 'X' | 'O';
+    winner: 'X' | 'O' | 'draw' | null;
+    moveCount: number;
+};
+
+type TurnResult = {
+    winner: 'X' | 'O' | 'draw' | null;
+};
+
+function getBoardRegion(game: GameContextLike) {
+    return game.regions.get('board');
+}
+
+function isCellOccupied(game: GameContextLike, row: number, col: number): boolean {
+    const board = getBoardRegion(game);
+    return board.value.children.some(
+        (child: { value: { position: number[] } }) => child.value.position[0] === row && child.value.position[1] === col
+    );
+}
+
+function checkWinner(game: GameContextLike): 'X' | 'O' | 'draw' | null {
+    const parts = Object.values(game.parts.collection.value).map((s: { value: Part }) => s.value);
+
+    const xPositions = parts.filter((_: Part, i: number) => i % 2 === 0).map((p: Part) => p.position);
+    const oPositions = parts.filter((_: Part, i: number) => i % 2 === 1).map((p: Part) => p.position);
+
+    if (hasWinningLine(xPositions)) return 'X';
+    if (hasWinningLine(oPositions)) return 'O';
+
+    return null;
+}
+
+function hasWinningLine(positions: number[][]): boolean {
+    const lines = [
+        [[0, 0], [0, 1], [0, 2]],
+        [[1, 0], [1, 1], [1, 2]],
+        [[2, 0], [2, 1], [2, 2]],
+        [[0, 0], [1, 0], [2, 0]],
+        [[0, 1], [1, 1], [2, 1]],
+        [[0, 2], [1, 2], [2, 2]],
+        [[0, 0], [1, 1], [2, 2]],
+        [[0, 2], [1, 1], [2, 0]],
+    ];
+
+    return lines.some(line =>
+        line.every(([r, c]) =>
+            positions.some(([pr, pc]) => pr === r && pc === c)
+        )
+    );
+}
+
+function placePiece(game: GameContextLike, row: number, col: number, moveCount: number) {
+    const board = getBoardRegion(game);
+    const piece: Part = {
+        id: `piece-${moveCount}`,
+        sides: 1,
+        side: 0,
+        region: board,
+        position: [row, col],
+    };
+    game.parts.add(piece);
+    board.value.children.push(game.parts.get(piece.id));
+}
+
+const playSchema = 'play <player> <row:number> <col:number>';
+
+export function createSetupRule() {
+    return createRule('start', function*() {
+        this.pushContext({
+            type: 'tic-tac-toe',
+            currentPlayer: 'X',
+            winner: null,
+            moveCount: 0,
+        } as TicTacToeState);
+
+        this.regions.add({
+            id: 'board',
+            axes: [
+                { name: 'x', min: 0, max: 2 },
+                { name: 'y', min: 0, max: 2 },
+            ],
+            children: [],
+        } as Region);
+
+        let currentPlayer: 'X' | 'O' = 'X';
+        let turnResult: TurnResult | undefined;
+
+        while (true) {
+            const yieldValue: InvokeYield = {
+                type: 'invoke',
+                rule: 'turn',
+                command: { name: 'turn', params: [currentPlayer], flags: {}, options: {} } as Command,
+            };
+            const ctx = yield yieldValue as RuleYield;
+            turnResult = (ctx as RuleContext<TurnResult>).resolution;
+            if (turnResult?.winner) break;
+
+            currentPlayer = currentPlayer === 'X' ? 'O' : 'X';
+            const state = this.latestContext<TicTacToeState>('tic-tac-toe')!;
+            state.value.currentPlayer = currentPlayer;
+        }
+
+        const state = this.latestContext<TicTacToeState>('tic-tac-toe')!;
+        state.value.winner = turnResult?.winner ?? null;
+        return { winner: state.value.winner };
+    });
+}
+
+export function createTurnRule() {
+    return createRule('turn <player>', function*(cmd) {
+        while (true) {
+            const received = yield playSchema;
+            if ('resolution' in received) continue;
+
+            const playCmd = received as Command;
+            if (playCmd.name !== 'play') continue;
+
+            const row = playCmd.params[1] as number;
+            const col = playCmd.params[2] as number;
+
+            if (isNaN(row) || isNaN(col) || row < 0 || row > 2 || col < 0 || col > 2) continue;
+            if (isCellOccupied(this, row, col)) continue;
+
+            const state = this.latestContext<TicTacToeState>('tic-tac-toe')!;
+            if (state.value.winner) continue;
+
+            placePiece(this, row, col, state.value.moveCount);
+            state.value.moveCount++;
+
+            const winner = checkWinner(this);
+            if (winner) return { winner };
+
+            if (state.value.moveCount >= 9) return { winner: 'draw' as const };
+        }
+    });
+}
+
+export function registerTicTacToeRules(game: GameContextInstance) {
+    game.registerRule('start', createSetupRule());
+    game.registerRule('turn', createTurnRule());
+}
+
+export function startTicTacToe(game: GameContextInstance) {
+    game.dispatchCommand('start');
+}

src/utils/command.ts

@@ -1,6 +1,6 @@
 export { parseCommand } from './command/command-parse.js';
 export { parseCommandSchema } from './command/schema-parse.js';
-export { validateCommand, parseCommandWithSchema } from './command/command-validate.js';
+export { validateCommand, parseCommandWithSchema, applyCommandSchema } from './command/command-validate.js';
 export type {
     Command,
     CommandParamSchema,

src/utils/command/command-apply.ts

@@ -0,0 +1,79 @@
+import { type ParseError } from 'inline-schema';
+import type { Command, CommandSchema } from './types.js';
+
+function validateCommandCore(command: Command, schema: CommandSchema): string[] {
+    const errors: string[] = [];
+
+    if (schema.name !== '' && command.name !== schema.name) {
+        errors.push(`命令名称不匹配：期望 "${schema.name}"，实际 "${command.name}"`);
+    }
+
+    const requiredParams = schema.params.filter(p => p.required);
+    const variadicParam = schema.params.find(p => p.variadic);
+
+    if (command.params.length < requiredParams.length) {
+        errors.push(`参数不足：至少需要 ${requiredParams.length} 个参数，实际 ${command.params.length} 个`);
+    }
+
+    if (!variadicParam && command.params.length > schema.params.length) {
+        errors.push(`参数过多：最多 ${schema.params.length} 个参数，实际 ${command.params.length} 个`);
+    }
+
+    const requiredOptions = schema.options.filter(o => o.required);
+    for (const opt of requiredOptions) {
+        const hasOption = opt.name in command.options || (opt.short && opt.short in command.options);
+        if (!hasOption) {
+            errors.push(`缺少必需选项：--${opt.name}${opt.short ? ` 或 -${opt.short}` : ''}`);
+        }
+    }
+
+    return errors;
+}
+
+export function applyCommandSchema(
+    command: Command,
+    schema: CommandSchema
+): { command: Command; valid: true } | { command: Command; valid: false; errors: string[] } {
+    const errors = validateCommandCore(command, schema);
+    if (errors.length > 0) {
+        return { command, valid: false, errors };
+    }
+
+    const parseErrors: string[] = [];
+
+    const parsedParams: unknown[] = [...command.params];
+    for (let i = 0; i < command.params.length; i++) {
+        const paramValue = command.params[i];
+        const paramSchema = schema.params[i]?.schema;
+
+        if (paramSchema && typeof paramValue === 'string') {
+            try {
+                parsedParams[i] = paramSchema.parse(paramValue);
+            } catch (e) {
+                const err = e as ParseError;
+                parseErrors.push(`参数 "${schema.params[i]?.name}" 解析失败：${err.message}`);
+            }
+        }
+    }
+
+    const parsedOptions: Record<string, unknown> = { ...command.options };
+    for (const [key, value] of Object.entries(command.options)) {
+        const optSchema = schema.options.find(o => o.name === key || o.short === key);
+        if (optSchema?.schema && typeof value === 'string') {
+            try {
+                parsedOptions[key] = optSchema.schema.parse(value);
+            } catch (e) {
+                const err = e as ParseError;
+                parseErrors.push(`选项 "--${key}" 解析失败：${err.message}`);
+            }
+        }
+    }
+
+    const result = { ...command, params: parsedParams, options: parsedOptions };
+
+    if (parseErrors.length > 0) {
+        return { command: result, valid: false, errors: parseErrors };
+    }
+
+    return { command: result, valid: true };
+}

src/utils/command/command-parse.ts

@@ -1,6 +1,9 @@
-import type { Command } from './types.js';
+import type { Command, CommandSchema } from './types.js';
+import { applyCommandSchema } from './command-validate.js';
 
-export function parseCommand(input: string): Command {
+export function parseCommand(input: string): Command;
+export function parseCommand(input: string, schema: CommandSchema): Command;
+export function parseCommand(input: string, schema?: CommandSchema): Command {
     const tokens = tokenize(input);
 
     if (tokens.length === 0) {
@@ -44,7 +47,14 @@ export function parseCommand(input: string): Command {
         }
     }
 
-    return { name, flags, options, params };
+    const command = { name, flags, options, params };
+
+    if (schema) {
+        const result = applyCommandSchema(command, schema);
+        return result.command;
+    }
+
+    return command;
 }
 
 function tokenize(input: string): string[] {

src/utils/command/command-validate.ts

@@ -1,48 +1,19 @@
-import { type ParseError } from 'inline-schema';
 import type { Command, CommandSchema } from './types.js';
 import { parseCommand } from './command-parse.js';
 import { parseCommandSchema } from './schema-parse.js';
+import { applyCommandSchema as applyCommandSchemaCore } from './command-apply.js';
+
+export { applyCommandSchemaCore as applyCommandSchema };
 
 export function validateCommand(
     command: Command,
     schema: CommandSchema
 ): { valid: true } | { valid: false; errors: string[] } {
-    const errors = validateCommandCore(command, schema);
-
-    if (errors.length > 0) {
-        return { valid: false, errors };
+    const result = applyCommandSchemaCore(command, schema);
+    if (result.valid) {
+        return { valid: true };
     }
-
-    return { valid: true };
-}
-
-function validateCommandCore(command: Command, schema: CommandSchema): string[] {
-    const errors: string[] = [];
-
-    if (command.name !== schema.name) {
-        errors.push(`命令名称不匹配：期望 "${schema.name}"，实际 "${command.name}"`);
-    }
-
-    const requiredParams = schema.params.filter(p => p.required);
-    const variadicParam = schema.params.find(p => p.variadic);
-
-    if (command.params.length < requiredParams.length) {
-        errors.push(`参数不足：至少需要 ${requiredParams.length} 个参数，实际 ${command.params.length} 个`);
-    }
-
-    if (!variadicParam && command.params.length > schema.params.length) {
-        errors.push(`参数过多：最多 ${schema.params.length} 个参数，实际 ${command.params.length} 个`);
-    }
-
-    const requiredOptions = schema.options.filter(o => o.required);
-    for (const opt of requiredOptions) {
-        const hasOption = opt.name in command.options || (opt.short && opt.short in command.options);
-        if (!hasOption) {
-            errors.push(`缺少必需选项：--${opt.name}${opt.short ? ` 或 -${opt.short}` : ''}`);
-        }
-    }
-
-    return errors;
+    return { valid: false, errors: result.errors };
 }
 
 export function parseCommandWithSchema(
@@ -51,53 +22,5 @@ export function parseCommandWithSchema(
 ): { command: Command; valid: true } | { command: Command; valid: false; errors: string[] } {
     const schema = parseCommandSchema(schemaStr);
     const command = parseCommand(input);
-
-    const errors = validateCommandCore(command, schema);
-    if (errors.length > 0) {
-        return { command, valid: false, errors };
-    }
-
-    const parseErrors: string[] = [];
-
-    const parsedParams: unknown[] = [];
-    for (let i = 0; i < command.params.length; i++) {
-        const paramValue = command.params[i];
-        const paramSchema = schema.params[i]?.schema;
-
-        if (paramSchema) {
-            try {
-                const parsed = typeof paramValue === 'string'
-                    ? paramSchema.parse(paramValue)
-                    : paramValue;
-                parsedParams.push(parsed);
-            } catch (e) {
-                const err = e as ParseError;
-                parseErrors.push(`参数 "${schema.params[i]?.name}" 解析失败：${err.message}`);
-            }
-        } else {
-            parsedParams.push(paramValue);
-        }
-    }
-
-    const parsedOptions: Record<string, unknown> = { ...command.options };
-    for (const [key, value] of Object.entries(command.options)) {
-        const optSchema = schema.options.find(o => o.name === key || o.short === key);
-        if (optSchema?.schema && typeof value === 'string') {
-            try {
-                parsedOptions[key] = optSchema.schema.parse(value);
-            } catch (e) {
-                const err = e as ParseError;
-                parseErrors.push(`选项 "--${key}" 解析失败：${err.message}`);
-            }
-        }
-    }
-
-    if (parseErrors.length > 0) {
-        return { command: { ...command, params: parsedParams, options: parsedOptions }, valid: false, errors: parseErrors };
-    }
-
-    return {
-        command: { ...command, params: parsedParams, options: parsedOptions },
-        valid: true,
-    };
+    return applyCommandSchemaCore(command, schema);
 }

src/utils/entity.ts

@@ -9,6 +9,43 @@ export type EntityAccessor<T extends Entity> = {
   value: T;
 }
 
+function createReactiveProxy<T extends Entity>(entitySignal: Signal<T>): T {
+  return new Proxy({} as T, {
+    get(_target, prop) {
+      const current = entitySignal.value;
+      const value = current[prop as keyof T];
+      if (typeof value === 'function') {
+        return value.bind(current);
+      }
+      return value;
+    },
+    set(_target, prop, value) {
+      const current = entitySignal.value;
+      entitySignal.value = { ...current, [prop]: value };
+      return true;
+    },
+    ownKeys(_target) {
+      return Reflect.ownKeys(entitySignal.value);
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      return Reflect.getOwnPropertyDescriptor(entitySignal.value, prop);
+    },
+  });
+}
+
+function createReactiveAccessor<T extends Entity>(id: string, entitySignal: Signal<T>): EntityAccessor<T> {
+  const proxy = createReactiveProxy(entitySignal);
+  return {
+    id,
+    get value() {
+      return proxy;
+    },
+    set value(value: T) {
+      entitySignal.value = value;
+    }
+  } as EntityAccessor<T>;
+}
+
 export function createEntityCollection<T extends Entity>() {
   const collection = signal({} as Record<string, Signal<T>>);
   const remove = (...ids: string[]) => {
@@ -24,17 +61,18 @@ export function createEntityCollection<T extends Entity>() {
     };
   };
   
-  const get = (id: string) => {
-    return {
-      id,
-      get value(){
-        return collection.value[id]?.value;
-      },
-      set value(value: T){
-        const signal = collection.value[id];
-        if(signal)signal.value = value;
-      }
+  const get = (id: string): EntityAccessor<T> => {
+    const entitySignal = collection.value[id];
+    if (!entitySignal) {
+      return {
+        id,
+        get value() {
+          return undefined as unknown as T;
+        },
+        set value(_value: T) {}
+      } as EntityAccessor<T>;
     }
+    return createReactiveAccessor(id, entitySignal);
   }
   
   return {

tests/core/rule.test.ts

@@ -1,6 +1,11 @@
 import { describe, it, expect } from 'vitest';
-import { createRule, dispatchCommand, type RuleContext, type RuleRegistry } from '../../src/core/rule';
+import { createRule, type RuleContext, type GameContextLike } from '../../src/core/rule';
 import { createGameContext } from '../../src/core/context';
+import type { Command } from '../../src/utils/command';
+
+function isCommand(value: Command | RuleContext<unknown>): value is Command {
+    return 'name' in value;
+}
 
 describe('Rule System', () => {
     function createTestGame() {
@@ -24,11 +29,12 @@ describe('Rule System', () => {
         });
 
         it('should create a generator when called', () => {
+            const game = createTestGame();
             const rule = createRule('<target>', function*(cmd) {
                 return cmd.params[0];
             });
 
-            const gen = rule.create({ name: 'test', params: ['card1'], flags: {}, options: {} });
+            const gen = rule.create.call(game as unknown as GameContextLike, { name: 'test', params: ['card1'], flags: {}, options: {} });
             const result = gen.next();
             expect(result.done).toBe(true);
             expect(result.value).toBe('card1');
@@ -39,7 +45,7 @@ describe('Rule System', () => {
         it('should invoke a registered rule and yield schema', () => {
             const game = createTestGame();
 
-            game.rules.value.set('move', createRule('<from> <to>', function*(cmd) {
+            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
                 yield { name: '', params: [], options: [], flags: [] };
                 return { moved: cmd.params[0] };
             }));
@@ -55,9 +61,10 @@ describe('Rule System', () => {
         it('should complete a rule when final command matches yielded schema', () => {
             const game = createTestGame();
 
-            game.rules.value.set('move', createRule('<from> <to>', function*(cmd) {
+            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
                 const confirm = yield { name: '', params: [], options: [], flags: [] };
-                return { moved: cmd.params[0], confirmed: confirm.name === 'confirm' };
+                const confirmCmd = isCommand(confirm) ? confirm : undefined;
+                return { moved: cmd.params[0], confirmed: confirmCmd?.name === 'confirm' };
             }));
 
             game.dispatchCommand('move card1 hand');
@@ -79,20 +86,20 @@ describe('Rule System', () => {
         it('should pass the initial command to the generator', () => {
             const game = createTestGame();
 
-            game.rules.value.set('attack', createRule('<target> [--power: number]', function*(cmd) {
+            game.registerRule('attack', createRule('<target> [--power: number]', function*(cmd) {
                 return { target: cmd.params[0], power: cmd.options.power || '1' };
             }));
 
             const ctx = game.dispatchCommand('attack goblin --power 5');
 
             expect(ctx!.state).toBe('done');
-            expect(ctx!.resolution).toEqual({ target: 'goblin', power: '5' });
+            expect(ctx!.resolution).toEqual({ target: 'goblin', power: 5 });
         });
 
         it('should complete immediately if generator does not yield', () => {
             const game = createTestGame();
 
-            game.rules.value.set('look', createRule('[--at]', function*() {
+            game.registerRule('look', createRule('[--at]', function*() {
                 return 'looked';
             }));
 
@@ -107,12 +114,12 @@ describe('Rule System', () => {
         it('should prioritize new rule invocation over feeding yielded context', () => {
             const game = createTestGame();
 
-            game.rules.value.set('move', createRule('<from> <to>', function*(cmd) {
+            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
                 yield { name: '', params: [], options: [], flags: [] };
                 return { moved: cmd.params[0] };
             }));
 
-            game.rules.value.set('confirm', createRule('', function*() {
+            game.registerRule('confirm', createRule('', function*() {
                 return 'new confirm rule';
             }));
 
@@ -130,9 +137,10 @@ describe('Rule System', () => {
         it('should feed a yielded context when command does not match any rule', () => {
             const game = createTestGame();
 
-            game.rules.value.set('move', createRule('<from> <to>', function*(cmd) {
+            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
                 const response = yield { name: '', params: [], options: [], flags: [] };
-                return { moved: cmd.params[0], response: response.name };
+                const rcmd = isCommand(response) ? response : undefined;
+                return { moved: cmd.params[0], response: rcmd?.name };
             }));
 
             game.dispatchCommand('move card1 hand');
@@ -145,9 +153,10 @@ describe('Rule System', () => {
         it('should skip non-matching commands for yielded context', () => {
             const game = createTestGame();
 
-            game.rules.value.set('move', createRule('<from> <to>', function*(cmd) {
+            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
                 const response = yield '<item>';
-                return { response: response.params[0] };
+                const rcmd = isCommand(response) ? response : undefined;
+                return { response: rcmd?.params[0] };
             }));
 
             game.dispatchCommand('move card1 hand');
@@ -160,9 +169,10 @@ describe('Rule System', () => {
         it('should validate command against yielded schema', () => {
             const game = createTestGame();
 
-            game.rules.value.set('trade', createRule('<from> <to>', function*(cmd) {
+            game.registerRule('trade', createRule('<from> <to>', function*(cmd) {
                 const response = yield '<item> [amount: number]';
-                return { traded: response.params[0] };
+                const rcmd = isCommand(response) ? response : undefined;
+                return { traded: rcmd?.params[0] };
             }));
 
             game.dispatchCommand('trade player1 player2');
@@ -177,12 +187,12 @@ describe('Rule System', () => {
         it('should feed the deepest yielded context', () => {
             const game = createTestGame();
 
-            game.rules.value.set('parent', createRule('<action>', function*() {
+            game.registerRule('parent', createRule('<action>', function*() {
                 yield { name: '', params: [], options: [], flags: [] };
                 return 'parent done';
             }));
 
-            game.rules.value.set('child', createRule('<target>', function*() {
+            game.registerRule('child', createRule('<target>', function*() {
                 yield { name: '', params: [], options: [], flags: [] };
                 return 'child done';
             }));
@@ -201,12 +211,12 @@ describe('Rule System', () => {
         it('should link child to parent', () => {
             const game = createTestGame();
 
-            game.rules.value.set('parent', createRule('<action>', function*() {
+            game.registerRule('parent', createRule('<action>', function*() {
                 yield 'child_cmd';
                 return 'parent done';
             }));
 
-            game.rules.value.set('child_cmd', createRule('<target>', function*() {
+            game.registerRule('child_cmd', createRule('<target>', function*() {
                 return 'child done';
             }));
 
@@ -225,16 +235,16 @@ describe('Rule System', () => {
         it('should discard previous children when a new child is invoked', () => {
             const game = createTestGame();
 
-            game.rules.value.set('parent', createRule('<action>', function*() {
+            game.registerRule('parent', createRule('<action>', function*() {
                 yield 'child_a | child_b';
                 return 'parent done';
             }));
 
-            game.rules.value.set('child_a', createRule('<target>', function*() {
+            game.registerRule('child_a', createRule('<target>', function*() {
                 return 'child_a done';
             }));
 
-            game.rules.value.set('child_b', createRule('<target>', function*() {
+            game.registerRule('child_b', createRule('<target>', function*() {
                 return 'child_b done';
             }));
 
@@ -259,7 +269,7 @@ describe('Rule System', () => {
         it('should track rule contexts in ruleContexts signal', () => {
             const game = createTestGame();
 
-            game.rules.value.set('test', createRule('<arg>', function*() {
+            game.registerRule('test', createRule('<arg>', function*() {
                 yield { name: '', params: [], options: [], flags: [] };
                 return 'done';
             }));
@@ -275,7 +285,7 @@ describe('Rule System', () => {
         it('should add context to the context stack', () => {
             const game = createTestGame();
 
-            game.rules.value.set('test', createRule('<arg>', function*() {
+            game.registerRule('test', createRule('<arg>', function*() {
                 yield { name: '', params: [], options: [], flags: [] };
                 return 'done';
             }));
@@ -292,7 +302,7 @@ describe('Rule System', () => {
         it('should leave context in place when generator throws', () => {
             const game = createTestGame();
 
-            game.rules.value.set('failing', createRule('<arg>', function*() {
+            game.registerRule('failing', createRule('<arg>', function*() {
                 throw new Error('rule error');
             }));
 
@@ -304,12 +314,12 @@ describe('Rule System', () => {
         it('should leave children in place when child generator throws', () => {
             const game = createTestGame();
 
-            game.rules.value.set('parent', createRule('<action>', function*() {
+            game.registerRule('parent', createRule('<action>', function*() {
                 yield 'child';
                 return 'parent done';
             }));
 
-            game.rules.value.set('child', createRule('<target>', function*() {
+            game.registerRule('child', createRule('<target>', function*() {
                 throw new Error('child error');
             }));
 
@@ -331,9 +341,10 @@ describe('Rule System', () => {
                 flags: [],
             };
 
-            game.rules.value.set('test', createRule('<arg>', function*() {
+            game.registerRule('test', createRule('<arg>', function*() {
                 const cmd = yield customSchema;
-                return { received: cmd.params[0] };
+                const rcmd = isCommand(cmd) ? cmd : undefined;
+                return { received: rcmd?.params[0] };
             }));
 
             game.dispatchCommand('test val1');
@@ -346,10 +357,12 @@ describe('Rule System', () => {
         it('should parse string schema on each yield', () => {
             const game = createTestGame();
 
-            game.rules.value.set('multi', createRule('<start>', function*() {
+            game.registerRule('multi', createRule('<start>', function*() {
                 const a = yield '<value>';
                 const b = yield '<value>';
-                return { a: a.params[0], b: b.params[0] };
+                const acmd = isCommand(a) ? a : undefined;
+                const bcmd = isCommand(b) ? b : undefined;
+                return { a: acmd?.params[0], b: bcmd?.params[0] };
             }));
 
             game.dispatchCommand('multi init');
@@ -365,17 +378,19 @@ describe('Rule System', () => {
         it('should handle a multi-step game flow', () => {
             const game = createTestGame();
 
-            game.rules.value.set('start', createRule('<player>', function*(cmd) {
+            game.registerRule('start', createRule('<player>', function*(cmd) {
                 const player = cmd.params[0];
                 const action = yield { name: '', params: [], options: [], flags: [] };
 
-                if (action.name === 'move') {
-                    yield '<target>';
-                } else if (action.name === 'attack') {
-                    yield '<target> [--power: number]';
+                if (isCommand(action)) {
+                    if (action.name === 'move') {
+                        yield '<target>';
+                    } else if (action.name === 'attack') {
+                        yield '<target> [--power: number]';
+                    }
                 }
 
-                return { player, action: action.name };
+                return { player, action: isCommand(action) ? action.name : '' };
             }));
 
             const ctx1 = game.dispatchCommand('start alice');

tests/samples/tic-tac-toe.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest';
+import { createGameContext } from '../../src/core/context';
+import { registerTicTacToeRules, startTicTacToe, type TicTacToeState } from '../../src/samples/tic-tac-toe';
+
+describe('Tic-Tac-Toe', () => {
+    function createGame() {
+        const game = createGameContext();
+        registerTicTacToeRules(game);
+        return game;
+    }
+
+    function getBoardState(game: ReturnType<typeof createGame>) {
+        return game.latestContext<TicTacToeState>('tic-tac-toe')!.value;
+    }
+
+    it('should initialize the board and start the game', () => {
+        const game = createGame();
+        startTicTacToe(game);
+
+        const state = getBoardState(game);
+        expect(state.currentPlayer).toBe('X');
+        expect(state.winner).toBeNull();
+        expect(state.moveCount).toBe(0);
+
+        const board = game.regions.get('board');
+        expect(board.value.axes).toHaveLength(2);
+        expect(board.value.axes[0].name).toBe('x');
+        expect(board.value.axes[1].name).toBe('y');
+    });
+
+    it('should play moves and determine a winner', () => {
+        const game = createGame();
+        startTicTacToe(game);
+
+        // X wins with column 0
+        game.dispatchCommand('play X 0 0');
+        game.dispatchCommand('play O 0 1');
+        game.dispatchCommand('play X 1 0');
+        game.dispatchCommand('play O 1 1');
+        game.dispatchCommand('play X 2 0');
+
+        const state = getBoardState(game);
+        expect(state.winner).toBe('X');
+        expect(state.moveCount).toBe(5);
+    });
+
+    it('should reject out-of-bounds moves', () => {
+        const game = createGame();
+        startTicTacToe(game);
+
+        const beforeCount = getBoardState(game).moveCount;
+
+        game.dispatchCommand('play X 5 5');
+        game.dispatchCommand('play X -1 0');
+        game.dispatchCommand('play X 3 3');
+
+        expect(getBoardState(game).moveCount).toBe(beforeCount);
+    });
+
+    it('should reject moves on occupied cells', () => {
+        const game = createGame();
+        startTicTacToe(game);
+
+        game.dispatchCommand('play X 1 1');
+        expect(getBoardState(game).moveCount).toBe(1);
+
+        // Try to play on the same cell
+        game.dispatchCommand('play O 1 1');
+        expect(getBoardState(game).moveCount).toBe(1);
+    });
+
+    it('should ignore moves after game is over', () => {
+        const game = createGame();
+        startTicTacToe(game);
+
+        // X wins
+        game.dispatchCommand('play X 0 0');
+        game.dispatchCommand('play O 0 1');
+        game.dispatchCommand('play X 1 0');
+        game.dispatchCommand('play O 1 1');
+        game.dispatchCommand('play X 2 0');
+
+        expect(getBoardState(game).winner).toBe('X');
+        const moveCountAfterWin = getBoardState(game).moveCount;
+
+        // Try to play more
+        game.dispatchCommand('play X 2 1');
+        game.dispatchCommand('play O 2 2');
+
+        expect(getBoardState(game).moveCount).toBe(moveCountAfterWin);
+    });
+
+    it('should detect a draw', () => {
+        const game = createGame();
+        startTicTacToe(game);
+
+        // Fill board with no winner (cat's game)
+        // X: (1,1), (0,2), (2,2), (1,0), (2,1)
+        // O: (0,0), (2,0), (0,1), (1,2)
+        game.dispatchCommand('play X 1 1');  // X
+        game.dispatchCommand('play O 0 0');  // O
+        game.dispatchCommand('play X 0 2');  // X
+        game.dispatchCommand('play O 2 0');  // O
+        game.dispatchCommand('play X 2 2');  // X
+        game.dispatchCommand('play O 0 1');  // O
+        game.dispatchCommand('play X 1 0');  // X
+        game.dispatchCommand('play O 1 2');  // O
+        game.dispatchCommand('play X 2 1');  // X (last move, draw)
+
+        const state = getBoardState(game);
+        expect(state.winner).toBe('draw');
+        expect(state.moveCount).toBe(9);
+    });
+
+    it('should place parts on the board region at correct positions', () => {
+        const game = createGame();
+        startTicTacToe(game);
+
+        game.dispatchCommand('play X 1 2');
+
+        const board = game.regions.get('board');
+        expect(board.value.children).toHaveLength(1);
+
+        const piece = board.value.children[0].value;
+        expect(piece.position).toEqual([1, 2]);
+    });
+});