refactor: break up command.ts

README.md

@@ -1,8 +1,186 @@
 # boardgame-core
 
-基于 Preact Signals 的桌游状态管理库。
+A state management library for board games using [Preact Signals](https://preactjs.com/guide/v10/signals/).
 
-## 特性
+## Features
 
-- **响应式状态管理**: 使用 [@preact/signals-core](https://preactjs.com/guide/v10/signals/) 实现细粒度响应式
-- **类型安全**: 完整的 TypeScript 支持
+- **Reactive State Management**: Fine-grained reactivity powered by [@preact/signals-core](https://preactjs.com/guide/v10/signals/)
+- **Type Safe**: Full TypeScript support with strict mode
+- **Entity Collections**: Signal-backed collections for managing game pieces (cards, dice, tokens, meeples, etc.)
+- **Region System**: Spatial management with multi-axis positioning, alignment, and shuffling
+- **Command Parsing**: CLI-style command parsing with schema validation and type coercion
+- **Rule Engine**: Generator-based rule system with reactive context management
+- **Deterministic RNG**: Seeded pseudo-random number generator (Mulberry32) for reproducible game states
+
+## Installation
+
+```bash
+npm install boardgame-core
+```
+
+## Usage
+
+### Game Context
+
+```ts
+import { createGameContext } from 'boardgame-core';
+
+const game = createGameContext({ type: 'game' });
+
+// Access entity collections
+game.parts.add({ id: 'card1', sides: 2, side: 0, region: /* ... */, position: [0] });
+game.regions.add({ id: 'hand', axes: [{ name: 'slot', min: 0, max: 7, align: 'start' }], children: [] });
+
+// Context stack for nested rule scopes
+game.pushContext({ type: 'combat' });
+const combatCtx = game.latestContext('combat');
+game.popContext();
+```
+
+### Parts (Cards, Dice, Tokens)
+
+```ts
+import { flip, flipTo, roll, createRNG } from 'boardgame-core';
+
+const rng = createRNG(42);
+
+flip(card);           // cycle to next side
+flipTo(card, 0);      // set to specific side
+roll(dice, rng);      // random side using seeded RNG
+```
+
+### Regions & Alignment
+
+```ts
+import { applyAlign, shuffle } from 'boardgame-core';
+
+// Compact cards in a hand towards the start
+applyAlign(handRegion);
+
+// Shuffle positions of all parts in a region
+shuffle(handRegion, rng);
+```
+
+### Command Parsing
+
+```ts
+import { parseCommand, parseCommandSchema, validateCommand } from 'boardgame-core';
+
+// Parse a command string
+const cmd = parseCommand('move card1 hand --force -x 10');
+// { name: 'move', params: ['card1', 'hand'], flags: { force: true }, options: { x: '10' } }
+
+// Define and validate against a schema
+const schema = parseCommandSchema('move <from> <to> [--force] [-x: number]');
+const result = validateCommand(cmd, schema);
+// { valid: true }
+```
+
+### Entity Collections
+
+```ts
+import { createEntityCollection } from 'boardgame-core';
+
+const collection = createEntityCollection();
+collection.add({ id: 'a', name: 'Item A' }, { id: 'b', name: 'Item B' });
+
+const accessor = collection.get('a');
+console.log(accessor.value); // reactive access
+
+collection.remove('a');
+```
+
+### Rule Engine
+
+```ts
+import { createRule, invokeRuleContext } from 'boardgame-core';
+
+const myRule = createRule('drawCard', (ctx) => {
+  // yield action types to pause and wait for external handling
+  const action = yield 'draw';
+  ctx.resolution = action;
+});
+
+const result = invokeRuleContext(
+  game.pushContext.bind(game),
+  'drawCard',
+  myRule({ type: 'drawCard', actions: [], handledActions: 0, invocations: [] })
+);
+```
+
+### Random Number Generation
+
+```ts
+import { createRNG } from 'boardgame-core';
+
+const rng = createRNG(12345);
+rng.nextInt(6);       // 0-5
+rng.next();           // [0, 1)
+rng.next(100);        // [0, 100)
+rng.setSeed(999);     // reseed
+```
+
+## API Reference
+
+### Core
+
+| Export | Description |
+|---|---|
+| `createGameContext(root?)` | Create a new game context instance |
+| `GameContext` | The game context model class |
+| `Context` | Base context type |
+
+### Parts
+
+| Export | Description |
+|---|---|
+| `Part` | Entity type representing a game piece (card, die, token, etc.) |
+| `flip(part)` | Cycle to the next side |
+| `flipTo(part, side)` | Set to a specific side |
+| `roll(part, rng)` | Randomize side using RNG |
+
+### Regions
+
+| Export | Description |
+|---|---|
+| `Region` | Entity type for spatial grouping of parts |
+| `RegionAxis` | Axis definition with min/max/align |
+| `applyAlign(region)` | Compact parts according to axis alignment |
+| `shuffle(region, rng)` | Randomize part positions |
+
+### Rules
+
+| Export | Description |
+|---|---|
+| `RuleContext<T>` | Rule execution context type |
+| `createRule(type, fn)` | Create a rule generator factory |
+| `invokeRuleContext(pushContext, type, rule)` | Execute a rule with context management |
+
+### Commands
+
+| Export | Description |
+|---|---|
+| `parseCommand(input)` | Parse a command string into a `Command` object |
+| `parseCommandSchema(schema)` | Parse a schema string into a `CommandSchema` |
+| `validateCommand(cmd, schema)` | Validate a command against a schema |
+
+### Utilities
+
+| Export | Description |
+|---|---|
+| `createEntityCollection<T>()` | Create a reactive entity collection |
+| `createRNG(seed?)` | Create a seeded RNG instance |
+| `Mulberry32RNG` | Mulberry32 PRNG class |
+
+## Scripts
+
+```bash
+npm run build       # Build with tsup
+npm run test        # Run tests in watch mode
+npm run test:run    # Run tests once
+npm run typecheck   # Type check with TypeScript
+```
+
+## License
+
+MIT

package.json

@@ -14,11 +14,11 @@
   "scripts": {
     "build": "tsup",
     "test": "vitest",
-    "test:run": "vitest run"
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@preact/signals-core": "^1.5.1",
-    "boardgame-core": "file:",
     "inline-schema": "git+https://gitea.ayi-games.online/hypercross/inline-schema"
   },
   "devDependencies": {

src/core/context.ts

@@ -2,6 +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";
 
 export type Context = {
     type: string;
@@ -10,34 +11,54 @@ export type Context = {
 export const GameContext = createModel((root: Context) => {
     const parts = createEntityCollection<Part>();
     const regions = createEntityCollection<Region>();
-    const contexts = signal([signal(root)]);
+    const rules = signal<RuleRegistry>(new Map());
+    const ruleContexts = signal<RuleContext<unknown>[]>([]);
+    const contexts = signal<Signal<Context>[]>([]);
+    contexts.value = [signal(root)];
+
     function pushContext(context: Context) {
         const ctxSignal = signal(context);
         contexts.value = [...contexts.value, ctxSignal];
         return context;
     }
+
     function popContext() {
-        contexts.value = contexts.value.slice(0, -1);
+        if (contexts.value.length > 1) {
+            contexts.value = contexts.value.slice(0, -1);
+        }
     }
-    function latestContext<T extends Context>(type: T['type']){
+
+    function latestContext<T extends Context>(type: T['type']): Signal<T> | undefined {
         for(let i = contexts.value.length - 1; i >= 0; i--){
             if(contexts.value[i].value.type === type){
                 return contexts.value[i] as Signal<T>;
             }
         }
+        return undefined;
+    }
+
+    function dispatchCommand(input: string) {
+        return dispatchRuleCommand({
+            rules: rules.value,
+            ruleContexts: ruleContexts.value,
+            contexts,
+        }, input);
     }
 
     return {
         parts,
         regions,
+        rules,
+        ruleContexts,
         contexts,
         pushContext,
         popContext,
         latestContext,
+        dispatchCommand,
     }
 })
 
 /** 创建游戏上下文实例 */
 export function createGameContext(root: Context = { type: 'game' }) {
     return new GameContext(root);
-}
+}

src/core/region.ts

@@ -28,36 +28,36 @@ export type RegionAxis = {
 export function applyAlign(region: Region){
   if (region.children.length === 0) return;
 
-  // 对每个 axis 分别处理，但保持空间关系
+  // Process each axis independently while preserving spatial relationships
   for (let axisIndex = 0; axisIndex < region.axes.length; axisIndex++) {
     const axis = region.axes[axisIndex];
     if (!axis.align) continue;
 
-    // 收集当前轴上的所有唯一位置值，保持原有顺序
+    // Collect all unique position values on this axis, preserving original order
     const positionValues = new Set<number>();
     for (const accessor of region.children) {
       positionValues.add(accessor.value.position[axisIndex] ?? 0);
     }
 
-    // 排序位置值
+    // Sort position values
     const sortedPositions = Array.from(positionValues).sort((a, b) => a - b);
 
-    // 创建位置映射：原位置 -> 新位置
+    // Create position mapping: old position -> new position
     const positionMap = new Map<number, number>();
 
     if (axis.align === 'start' && axis.min !== undefined) {
-      // 从 min 开始紧凑排列，保持相对顺序
+      // Compact from min, preserving relative order
       sortedPositions.forEach((pos, index) => {
         positionMap.set(pos, axis.min! + index);
       });
     } else if (axis.align === 'end' && axis.max !== undefined) {
-      // 从 max 开始向前紧凑排列
+      // Compact towards max
       const count = sortedPositions.length;
       sortedPositions.forEach((pos, index) => {
         positionMap.set(pos, axis.max! - (count - 1 - index));
       });
     } else if (axis.align === 'center') {
-      // 居中排列
+      // Center alignment
       const count = sortedPositions.length;
       const min = axis.min ?? 0;
       const max = axis.max ?? count - 1;
@@ -70,14 +70,14 @@ export function applyAlign(region: Region){
       });
     }
 
-    // 应用位置映射到所有 part
+    // Apply position mapping to all parts
     for (const accessor of region.children) {
       const currentPos = accessor.value.position[axisIndex] ?? 0;
       accessor.value.position[axisIndex] = positionMap.get(currentPos) ?? currentPos;
     }
   }
 
-  // 最后按所有轴排序 children
+  // Sort children by all axes at the end
   region.children.sort((a, b) => {
     for (let i = 0; i < region.axes.length; i++) {
       const diff = (a.value.position[i] ?? 0) - (b.value.position[i] ?? 0);

src/core/rule.ts

@@ -1,88 +1,164 @@
-import {Context} from "./context";
-import {Command} from "../utils/command";
-import {effect} from "@preact/signals-core";
+import {Command, CommandSchema, parseCommand, parseCommandSchema} from "../utils/command";
 
-export type RuleContext<T> = Context & {
-    actions: Command[];
-    handledActions: number;
-    invocations: RuleContext<unknown>[];
+export type RuleState = 'running' | 'yielded' | 'waiting' | 'done';
+
+export type RuleContext<T = unknown> = {
+    type: string;
+    schema?: CommandSchema;
+    generator: Generator<string | CommandSchema, T, Command>;
+    parent?: RuleContext<unknown>;
+    children: RuleContext<unknown>[];
+    state: RuleState;
     resolution?: T;
 }
 
-/**
- * 调用规则生成器并管理其上下文
- * @param pushContext - 用于推送上下文到上下文栈的函数
- * @param type - 规则类型
- * @param rule - 规则生成器函数
- * @returns 规则执行结果
- */
-export function invokeRuleContext<T>(
-    pushContext: (context: Context) => void, 
-    type: string, 
-    rule: Generator<string, T, Command>
+export type RuleDef<T = unknown> = {
+    schema: CommandSchema;
+    create: (cmd: Command) => Generator<string | CommandSchema, T, Command>;
+};
+
+export type RuleRegistry = Map<string, RuleDef<unknown>>;
+
+export function createRule<T>(
+    schemaStr: string,
+    fn: (cmd: Command) => Generator<string | CommandSchema, T, Command>
+): RuleDef<T> {
+    return {
+        schema: parseCommandSchema(schemaStr, ''),
+        create: fn as RuleDef<T>['create'],
+    };
+}
+
+function parseYieldedSchema(value: string | CommandSchema): CommandSchema {
+    if (typeof value === 'string') {
+        return parseCommandSchema(value, '');
+    }
+    return value;
+}
+
+function pushContextToGame(game: GameContextLike, ctx: RuleContext<unknown>) {
+    game.contexts.value = [...game.contexts.value, { value: ctx } as any];
+    game.ruleContexts.push(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);
+
+        const ctxIdx = game.contexts.value.findIndex((c: any) => c.value === child);
+        if (ctxIdx !== -1) {
+            const arr = [...game.contexts.value];
+            arr.splice(ctxIdx, 1);
+            game.contexts.value = arr;
+        }
+    }
+    parent.children = [];
+    parent.state = 'yielded';
+}
+
+function validateYieldedSchema(command: Command, schema: CommandSchema): boolean {
+    const requiredParams = schema.params.filter(p => p.required);
+    const variadicParam = schema.params.find(p => p.variadic);
+
+    if (command.params.length < requiredParams.length) {
+        return false;
+    }
+
+    if (!variadicParam && command.params.length > schema.params.length) {
+        return false;
+    }
+
+    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) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+function invokeRule<T>(
+    game: GameContextLike,
+    command: Command,
+    ruleDef: RuleDef<T>,
+    parent?: RuleContext<unknown>
 ): RuleContext<T> {
     const ctx: RuleContext<T> = {
-        type,
-        actions: [],
-        handledActions: 0,
-        invocations: [],
+        type: ruleDef.schema.name,
+        schema: undefined,
+        generator: ruleDef.create(command),
+        parent,
+        children: [],
+        state: 'running',
         resolution: undefined,
     };
 
-    // 执行生成器直到完成或需要等待动作
-    const executeRule = () => {
-        try {
-            const result = rule.next();
-            
-            if (result.done) {
-                // 规则执行完成，设置结果
-                ctx.resolution = result.value;
-                return;
-            }
+    if (parent) {
+        discardChildren(game, parent);
+        parent.children.push(ctx as RuleContext<unknown>);
+        parent.state = 'waiting';
+    }
 
-            // 如果生成器 yield 了一个动作类型，等待处理
-            // 这里可以扩展为实际的动作处理逻辑
-            const actionType = result.value;
-            
-            // 继续执行直到有动作需要处理或规则完成
-            if (!result.done) {
-                executeRule();
-            }
-        } catch (error) {
-            // 规则执行出错，抛出错误
-            throw error;
-        }
-    };
+    pushContextToGame(game, ctx as RuleContext<unknown>);
 
-    // 使用 effect 来跟踪响应式依赖
-    const dispose = effect(() => {
-        if (ctx.resolution !== undefined) {
-            dispose();
-            return;
-        }
-        executeRule();
-    });
-
-    // 将规则上下文推入栈中
-    pushContext(ctx);
+    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;
 }
 
-/**
- * 创建一个规则生成器辅助函数
- * @param type - 规则类型
- * @param fn - 规则逻辑函数
- */
-export function createRule<T>(
-    type: string,
-    fn: (ctx: RuleContext<T>) => Generator<string, T, Command>
-): Generator<string, T, Command> {
-    return fn({
-        type,
-        actions: [],
-        handledActions: 0,
-        invocations: [],
-        resolution: undefined,
-    });
+export function dispatchCommand(game: GameContextLike, input: string): RuleContext<unknown> | undefined {
+    const command = parseCommand(input);
+
+    if (game.rules.has(command.name)) {
+        const ruleDef = game.rules.get(command.name)!;
+
+        const parent = findYieldedParent(game);
+
+        return invokeRule(game, command, 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);
+                if (result.done) {
+                    ctx.resolution = result.value;
+                    ctx.state = 'done';
+                } else {
+                    ctx.schema = parseYieldedSchema(result.value);
+                    ctx.state = 'yielded';
+                }
+                return ctx;
+            }
+        }
+    }
+
+    return undefined;
 }
+
+function findYieldedParent(game: GameContextLike): RuleContext<unknown> | undefined {
+    for (let i = game.ruleContexts.length - 1; i >= 0; i--) {
+        const ctx = game.ruleContexts[i];
+        if (ctx.state === 'yielded') {
+            return ctx;
+        }
+    }
+    return undefined;
+}
+
+type GameContextLike = {
+    rules: RuleRegistry;
+    ruleContexts: RuleContext<unknown>[];
+    contexts: { value: any[] };
+};

src/index.ts

@@ -13,8 +13,8 @@ export { flip, flipTo, roll } from './core/part';
 export type { Region, RegionAxis } from './core/region';
 export { applyAlign, shuffle } from './core/region';
 
-export type { RuleContext } from './core/rule';
-export { invokeRuleContext, createRule } from './core/rule';
+export type { RuleContext, RuleState, RuleDef, RuleRegistry } from './core/rule';
+export { createRule, dispatchCommand } from './core/rule';
 
 // Utils
 export type { Command, CommandSchema, CommandParamSchema, CommandOptionSchema, CommandFlagSchema } from './utils/command';

src/utils/command.ts

@@ -1,690 +1,10 @@
-import { defineSchema, type ParsedSchema, ParseError } from 'inline-schema';
-
-export type Command = {
-    name: string;
-    flags: Record<string, true>;
-    options: Record<string, unknown>;
-    params: unknown[];
-}
-
-/**
- * 命令参数 schema 定义
- */
-export type CommandParamSchema = {
-    /** 参数名称 */
-    name: string;
-    /** 是否必需 */
-    required: boolean;
-    /** 是否可变参数（可以接收多个值） */
-    variadic: boolean;
-    /** 参数类型 schema（用于解析和验证） */
-    schema?: ParsedSchema;
-}
-
-/**
- * 命令选项 schema 定义
- */
-export type CommandOptionSchema = {
-    /** 选项名称（长格式，不含 --） */
-    name: string;
-    /** 短格式名称（不含 -） */
-    short?: string;
-    /** 是否必需 */
-    required: boolean;
-    /** 默认值 */
-    defaultValue?: unknown;
-    /** 选项类型 schema（用于解析和验证） */
-    schema?: ParsedSchema;
-}
-
-/**
- * 命令标志 schema 定义
- */
-export type CommandFlagSchema = {
-    /** 标志名称（长格式，不含 --） */
-    name: string;
-    /** 短格式名称（不含 -） */
-    short?: string;
-}
-
-/**
- * 命令完整 schema 定义
- */
-export type CommandSchema = {
-    /** 命令名称 */
-    name: string;
-    /** 参数定义列表 */
-    params: CommandParamSchema[];
-    /** 选项定义列表 */
-    options: CommandOptionSchema[];
-    /** 标志定义列表 */
-    flags: CommandFlagSchema[];
-}
-
-/**
- * 解析命令行输入字符串为 Command 对象
- * 支持格式：commandName [params...] [--flags...] [-o value...]
- * 支持引号：单引号 (') 和双引号 (") 可以包裹包含空格的参数
- * 支持转义：使用反斜杠 (\) 转义引号或反斜杠本身
- *
- * @example
- * parseCommand("move meeple1 region1 --force -x 10")
- * // returns { name: "move", params: ["meeple1", "region1"], flags: { force: true }, options: { x: "10" } }
- * parseCommand('place tile "large castle" --x 5')
- * // returns { name: "place", params: ["tile", "large castle"], flags: {}, options: { x: "5" } }
- */
-export function parseCommand(input: string): Command {
-    const tokens = tokenize(input);
-
-    if (tokens.length === 0) {
-        return { name: '', flags: {}, options: {}, params: [] };
-    }
-
-    const name = tokens[0];
-    const params: unknown[] = [];
-    const flags: Record<string, true> = {};
-    const options: Record<string, unknown> = {};
-
-    let i = 1;
-    while (i < tokens.length) {
-        const token = tokens[i];
-
-        if (token.startsWith('--') && !/^-?\d+$/.test(token)) {
-            // 长格式标志或选项：--flag 或 --option value
-            const key = token.slice(2);
-            const nextToken = tokens[i + 1];
-
-            // 如果下一个 token 存在且不以 - 开头（或者是负数），则是选项值
-            if (nextToken && (!nextToken.startsWith('-') || /^-\d+$/.test(nextToken))) {
-                options[key] = nextToken;
-                i += 2;
-            } else {
-                // 否则是布尔标志
-                flags[key] = true;
-                i++;
-            }
-        } else if (token.startsWith('-') && token.length > 1 && !/^-?\d+$/.test(token)) {
-            // 短格式标志或选项：-f 或 -o value（但不匹配负数）
-            const key = token.slice(1);
-            const nextToken = tokens[i + 1];
-
-            // 如果下一个 token 存在且不以 - 开头（或者是负数），则是选项值
-            if (nextToken && (!nextToken.startsWith('-') || /^-\d+$/.test(nextToken))) {
-                options[key] = nextToken;
-                i += 2;
-            } else {
-                // 否则是布尔标志
-                flags[key] = true;
-                i++;
-            }
-        } else {
-            // 普通参数（包括负数）
-            params.push(token);
-            i++;
-        }
-    }
-
-    return { name, flags, options, params };
-}
-
-/**
- * 将输入字符串分解为 tokens，支持引号和转义
- */
-function tokenize(input: string): string[] {
-    const tokens: string[] = [];
-    let current = '';
-    let inQuote: string | null = null;
-    let inBracket = false;
-    let bracketDepth = 0;
-    let escaped = false;
-    let i = 0;
-
-    while (i < input.length) {
-        const char = input[i];
-
-        if (escaped) {
-            current += char;
-            escaped = false;
-        } else if (char === '\\') {
-            escaped = true;
-        } else if (inQuote) {
-            if (char === inQuote) {
-                inQuote = null;
-            } else {
-                current += char;
-            }
-        } else if (char === '"' || char === "'") {
-            inQuote = char;
-        } else if (char === '[') {
-            if (inBracket) {
-                bracketDepth++;
-                current += char;
-            } else {
-                if (current.length > 0) {
-                    tokens.push(current);
-                    current = '';
-                }
-                inBracket = true;
-                bracketDepth = 1;
-                current = '[';
-            }
-        } else if (char === ']') {
-            if (inBracket) {
-                bracketDepth--;
-                current += char;
-                if (bracketDepth === 0) {
-                    tokens.push(current);
-                    current = '';
-                    inBracket = false;
-                }
-            } else {
-                current += char;
-            }
-        } else if (/\s/.test(char)) {
-            if (inBracket) {
-                current += char;
-            } else if (current.length > 0) {
-                tokens.push(current);
-                current = '';
-            }
-        } else {
-            current += char;
-        }
-
-        i++;
-    }
-
-    if (current.length > 0) {
-        tokens.push(current);
-    }
-
-    return tokens;
-}
-
-/**
- * 解析命令 schema 字符串为 CommandSchema 对象
- * 支持语法：
- * - <param> 必需参数
- * - [param] 可选参数
- * - <param...> 必需可变参数
- * - [param...] 可选可变参数
- * - <param: type> 带类型定义的必需参数
- * - [param: type] 带类型定义的可选参数
- * - --flag 长格式标志（布尔类型）
- * - --flag: boolean 长格式标志（布尔类型，与上面等价）
- * - -f 短格式标志
- * - --option: type 带类型的长格式选项
- * - --option: type = default 带默认值的选项
- * - --option: type -o 带短别名的选项
- * - --option: type -o = default 带短别名和默认值的选项
- * - -o: type 带类型的短格式选项
- * 
- * 类型语法使用 inline-schema 格式（使用 ; 而非 ,）：
- * - string, number, boolean
- * - [string; number] 元组
- * - string[] 数组
- * - [string; number][] 元组数组
- *
- * @example
- * parseCommandSchema('move <from> [to...] [--force] [-f] [--speed: number]')
- * parseCommandSchema('move <from: [x: string; y: string]> <to: string> [--all]')
- * parseCommandSchema('move <from> <to> [--speed: number = 10 -s]')
- */
-export function parseCommandSchema(schemaStr: string): CommandSchema {
-    const schema: CommandSchema = {
-        name: '',
-        params: [],
-        options: [],
-        flags: [],
-    };
-
-    const tokens = tokenizeSchema(schemaStr);
-    if (tokens.length === 0) {
-        return schema;
-    }
-
-    schema.name = tokens[0];
-
-    let i = 1;
-    while (i < tokens.length) {
-        const token = tokens[i];
-
-        if (token.startsWith('[') && token.endsWith(']')) {
-            const inner = token.slice(1, -1).trim();
-
-            if (inner.startsWith('--')) {
-                const result = parseOptionToken(inner.slice(2), false);
-                if (result.isFlag) {
-                    schema.flags.push({ name: result.name, short: result.short });
-                } else {
-                    schema.options.push({
-                        name: result.name,
-                        short: result.short,
-                        required: false,
-                        defaultValue: result.defaultValue,
-                        schema: result.schema,
-                    });
-                }
-            } else if (inner.startsWith('-') && inner.length > 1 && !inner.includes('--')) {
-                const result = parseOptionToken(inner.slice(1), false);
-                if (result.isFlag) {
-                    schema.flags.push({ name: result.name, short: result.short || result.name });
-                } else {
-                    schema.options.push({
-                        name: result.name,
-                        short: result.short || result.name,
-                        required: false,
-                        defaultValue: result.defaultValue,
-                        schema: result.schema,
-                    });
-                }
-            } else {
-                const isVariadic = inner.endsWith('...');
-                let paramContent = isVariadic ? inner.slice(0, -3) : inner;
-                let parsedSchema: ParsedSchema | undefined;
-                
-                if (paramContent.includes(':')) {
-                    const [name, typeStr] = paramContent.split(':').map(s => s.trim());
-                    try {
-                        parsedSchema = defineSchema(typeStr);
-                    } catch {
-                        // 不是有效的 schema
-                    }
-                    paramContent = name;
-                }
-
-                schema.params.push({
-                    name: paramContent,
-                    required: false,
-                    variadic: isVariadic,
-                    schema: parsedSchema,
-                });
-            }
-            i++;
-        } else if (token.startsWith('--')) {
-            const result = parseOptionToken(token.slice(2), true);
-            if (result.isFlag) {
-                schema.flags.push({ name: result.name, short: result.short });
-            } else {
-                schema.options.push({
-                    name: result.name,
-                    short: result.short,
-                    required: true,
-                    defaultValue: result.defaultValue,
-                    schema: result.schema,
-                });
-            }
-            i++;
-        } else if (token.startsWith('-') && token.length > 1 && !/^-?\d+$/.test(token)) {
-            const result = parseOptionToken(token.slice(1), true);
-            if (result.isFlag) {
-                schema.flags.push({ name: result.name, short: result.short || result.name });
-            } else {
-                schema.options.push({
-                    name: result.name,
-                    short: result.short || result.name,
-                    required: true,
-                    defaultValue: result.defaultValue,
-                    schema: result.schema,
-                });
-            }
-            i++;
-        } else if (token.startsWith('<') && token.endsWith('>')) {
-            const isVariadic = token.endsWith('...>');
-            let paramContent = token.replace(/^[<]+|[>.>]+$/g, '');
-            let parsedSchema: ParsedSchema | undefined;
-            
-            if (paramContent.includes(':')) {
-                const colonIndex = paramContent.indexOf(':');
-                const name = paramContent.slice(0, colonIndex).trim();
-                const typeStr = paramContent.slice(colonIndex + 1).trim();
-                try {
-                    parsedSchema = defineSchema(typeStr);
-                } catch (e) {
-                    // 不是有效的 schema
-                }
-                paramContent = name;
-            }
-
-            schema.params.push({
-                name: paramContent,
-                required: true,
-                variadic: isVariadic,
-                schema: parsedSchema,
-            });
-            i++;
-        } else {
-            i++;
-        }
-    }
-
-    return schema;
-}
-
-/**
- * 解析选项/标志 token 的结果
- */
-interface ParsedOptionResult {
-    name: string;
-    short?: string;
-    isFlag: boolean;
-    schema?: ParsedSchema;
-    defaultValue?: unknown;
-}
-
-/**
- * 解析单个选项/标志 token
- * 支持格式：
- * - flag                     → 标志
- * - flag: boolean            → 标志（统一处理）
- * - option: type             → 选项
- * - option: type -s          → 选项带短别名
- * - option: type = default   → 选项带默认值
- * - option: type -s = default → 选项带短别名和默认值
- */
-function parseOptionToken(token: string, required: boolean): ParsedOptionResult {
-    const parts = token.split(/\s+/);
-    const mainPart = parts[0];
-    
-    let name: string;
-    let typeStr: string | undefined;
-    let isFlag = false;
-    
-    if (mainPart.endsWith(':')) {
-        name = mainPart.slice(0, -1).trim();
-        typeStr = parts[1] || 'string';
-    } else if (mainPart.includes(':')) {
-        const [optName, optType] = mainPart.split(':').map(s => s.trim());
-        name = optName;
-        typeStr = optType;
-    } else {
-        name = mainPart;
-        isFlag = true;
-    }
-    
-    if (typeStr === 'boolean') {
-        isFlag = true;
-        typeStr = undefined;
-    }
-    
-    let short: string | undefined;
-    let defaultValue: unknown;
-    let schema: ParsedSchema | undefined;
-    
-    for (let i = 1; i < parts.length; i++) {
-        const part = parts[i];
-        
-        if (part.startsWith('-') && part.length === 2) {
-            short = part.slice(1);
-        } else if (part === '=') {
-            const valuePart = parts[i + 1];
-            if (valuePart) {
-                try {
-                    defaultValue = JSON.parse(valuePart);
-                } catch {
-                    defaultValue = valuePart;
-                }
-                i++;
-            }
-        } else if (part.startsWith('=')) {
-            const valuePart = part.slice(1);
-            try {
-                defaultValue = JSON.parse(valuePart);
-            } catch {
-                defaultValue = valuePart;
-            }
-        }
-    }
-    
-    if (typeStr && !isFlag) {
-        try {
-            schema = defineSchema(typeStr);
-        } catch {
-            // 不是有效的 schema
-        }
-    }
-    
-    return { name, short, isFlag, schema, defaultValue };
-}
-
-/**
- * 检查 token 是否是值占位符（如 <value> 或 [value]）
- */
-function isValuePlaceholder(token: string): boolean {
-    return (token.startsWith('<') && token.endsWith('>')) ||
-        (token.startsWith('[') && token.endsWith(']'));
-}
-
-/**
- * 检查 token 是否是参数占位符
- */
-function isParamPlaceholder(token: string): boolean {
-    // 参数占位符必须以 < 或 [ 开头
-    if (!token.startsWith('<') && !token.startsWith('[')) {
-        return false;
-    }
-    // 检查是否是选项的值占位符（如 <--opt <val> 中的 <val>）
-    // 这种情况应该由选项处理逻辑处理，不作为独立参数
-    return true;
-}
-
-/**
- * 将 schema 字符串分解为 tokens
- * 支持方括号分组：[...args] [--flag] 等
- * 支持尖括号分组：<param> <param: type> 等
- */
-function tokenizeSchema(input: string): string[] {
-    const tokens: string[] = [];
-    let current = '';
-    let inBracket = false;
-    let bracketContent = '';
-    let i = 0;
-
-    while (i < input.length) {
-        const char = input[i];
-
-        if (inBracket) {
-            if (char === ']') {
-                tokens.push(`[${bracketContent}]`);
-                inBracket = false;
-                bracketContent = '';
-                current = '';
-            } else if (char === '[') {
-                bracketContent += char;
-            } else {
-                bracketContent += char;
-            }
-        } else if (/\s/.test(char)) {
-            if (current.length > 0) {
-                tokens.push(current);
-                current = '';
-            }
-        } else if (char === '[') {
-            if (current.length > 0) {
-                tokens.push(current);
-                current = '';
-            }
-            inBracket = true;
-            bracketContent = '';
-        } else if (char === '<') {
-            let angleContent = '<';
-            i++;
-            while (i < input.length && input[i] !== '>') {
-                angleContent += input[i];
-                i++;
-            }
-            angleContent += '>';
-            tokens.push(angleContent);
-        } else {
-            current += char;
-        }
-
-        i++;
-    }
-
-    if (current.length > 0) {
-        tokens.push(current);
-    }
-
-    if (bracketContent.length > 0) {
-        tokens.push(`[${bracketContent}`);
-    }
-
-    return tokens;
-}
-
-/**
- * 根据 schema 验证命令
- * @returns 验证结果，valid 为 true 表示通过，否则包含错误信息
- */
-export function validateCommand(
-    command: Command,
-    schema: CommandSchema
-): { valid: true } | { valid: false; errors: 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}` : ''}`);
-        }
-    }
-
-    // 验证标志（标志都是可选的，除非未来扩展支持必需标志）
-    // 目前只检查是否有未定义的标志（可选的严格模式）
-
-    if (errors.length > 0) {
-        return { valid: false, errors };
-    }
-
-    return { valid: true };
-}
-
-/**
- * 根据 schema 解析并验证命令，返回类型化的命令对象
- * 如果 schema 中定义了类型，会自动解析参数和选项的值
- * 
- * @param input 命令行输入字符串
- * @param schemaStr 命令 schema 字符串
- * @returns 解析后的命令对象和验证结果
- * 
- * @example
- * const result = parseCommandWithSchema(
- *   'move [1; 2] region1 --all true',
- *   'move <from: [x: string; y: string]> <to: string> [--all: boolean]'
- * );
- * // result.command.params[0] = ['1', '2'] (已解析为元组)
- * // result.command.options.all = true (已解析为布尔值)
- */
-export function parseCommandWithSchema(
-    input: string,
-    schemaStr: string
-): { command: Command; valid: true } | { command: Command; valid: false; errors: string[] } {
-    const schema = parseCommandSchema(schemaStr);
-    const command = parseCommand(input);
-
-    // 验证命令名称
-    if (command.name !== schema.name) {
-        return {
-            command,
-            valid: false,
-            errors: [`命令名称不匹配：期望 "${schema.name}"，实际 "${command.name}"`],
-        };
-    }
-
-    const errors: string[] = [];
-
-    // 验证参数数量
-    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} 个`);
-        return { command, valid: false, errors };
-    }
-
-    if (!variadicParam && command.params.length > schema.params.length) {
-        errors.push(`参数过多：最多 ${schema.params.length} 个参数，实际 ${command.params.length} 个`);
-        return { command, valid: false, errors };
-    }
-
-    // 验证必需的选项
-    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}` : ''}`);
-        }
-    }
-
-    if (errors.length > 0) {
-        return { command, valid: false, errors };
-    }
-
-    // 使用 schema 解析参数值
-    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 {
-                // 如果是字符串值，使用 schema 解析
-                const parsed = typeof paramValue === 'string'
-                    ? paramSchema.parse(paramValue)
-                    : paramValue;
-                parsedParams.push(parsed);
-            } catch (e) {
-                const err = e as ParseError;
-                errors.push(`参数 "${schema.params[i]?.name}" 解析失败：${err.message}`);
-            }
-        } else {
-            parsedParams.push(paramValue);
-        }
-    }
-
-    // 使用 schema 解析选项值
-    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;
-                errors.push(`选项 "--${key}" 解析失败：${err.message}`);
-            }
-        }
-    }
-
-    if (errors.length > 0) {
-        return { command: { ...command, params: parsedParams, options: parsedOptions }, valid: false, errors };
-    }
-
-    return {
-        command: { ...command, params: parsedParams, options: parsedOptions },
-        valid: true,
-    };
-}
+export { parseCommand } from './command/command-parse.js';
+export { parseCommandSchema } from './command/schema-parse.js';
+export { validateCommand, parseCommandWithSchema } from './command/command-validate.js';
+export type {
+    Command,
+    CommandParamSchema,
+    CommandOptionSchema,
+    CommandFlagSchema,
+    CommandSchema,
+} from './command/types.js';

src/utils/command/command-parse.ts

@@ -0,0 +1,119 @@
+import type { Command } from './types.js';
+
+export function parseCommand(input: string): Command {
+    const tokens = tokenize(input);
+
+    if (tokens.length === 0) {
+        return { name: '', flags: {}, options: {}, params: [] };
+    }
+
+    const name = tokens[0];
+    const params: unknown[] = [];
+    const flags: Record<string, true> = {};
+    const options: Record<string, unknown> = {};
+
+    let i = 1;
+    while (i < tokens.length) {
+        const token = tokens[i];
+
+        if (token.startsWith('--') && !/^-?\d+$/.test(token)) {
+            const key = token.slice(2);
+            const nextToken = tokens[i + 1];
+
+            if (nextToken && (!nextToken.startsWith('-') || /^-\d+$/.test(nextToken))) {
+                options[key] = nextToken;
+                i += 2;
+            } else {
+                flags[key] = true;
+                i++;
+            }
+        } else if (token.startsWith('-') && token.length > 1 && !/^-?\d+$/.test(token)) {
+            const key = token.slice(1);
+            const nextToken = tokens[i + 1];
+
+            if (nextToken && (!nextToken.startsWith('-') || /^-\d+$/.test(nextToken))) {
+                options[key] = nextToken;
+                i += 2;
+            } else {
+                flags[key] = true;
+                i++;
+            }
+        } else {
+            params.push(token);
+            i++;
+        }
+    }
+
+    return { name, flags, options, params };
+}
+
+function tokenize(input: string): string[] {
+    const tokens: string[] = [];
+    let current = '';
+    let inQuote: string | null = null;
+    let inBracket = false;
+    let bracketDepth = 0;
+    let escaped = false;
+    let i = 0;
+
+    while (i < input.length) {
+        const char = input[i];
+
+        if (escaped) {
+            current += char;
+            escaped = false;
+        } else if (char === '\\') {
+            escaped = true;
+        } else if (inQuote) {
+            if (char === inQuote) {
+                inQuote = null;
+            } else {
+                current += char;
+            }
+        } else if (char === '"' || char === "'") {
+            inQuote = char;
+        } else if (char === '[') {
+            if (inBracket) {
+                bracketDepth++;
+                current += char;
+            } else {
+                if (current.length > 0) {
+                    tokens.push(current);
+                    current = '';
+                }
+                inBracket = true;
+                bracketDepth = 1;
+                current = '[';
+            }
+        } else if (char === ']') {
+            if (inBracket) {
+                bracketDepth--;
+                current += char;
+                if (bracketDepth === 0) {
+                    tokens.push(current);
+                    current = '';
+                    inBracket = false;
+                }
+            } else {
+                current += char;
+            }
+        } else if (/\s/.test(char)) {
+            if (inBracket) {
+                current += char;
+            } else if (current.length > 0) {
+                tokens.push(current);
+                current = '';
+            }
+        } else {
+            current += char;
+        }
+
+        i++;
+    }
+
+    if (current.length > 0) {
+        tokens.push(current);
+    }
+
+    return tokens;
+}

src/utils/command/command-validate.ts

@@ -0,0 +1,103 @@
+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';
+
+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 };
+    }
+
+    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;
+}
+
+export function parseCommandWithSchema(
+    input: string,
+    schemaStr: string
+): { 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,
+    };
+}

src/utils/command/schema-parse.ts

@@ -0,0 +1,264 @@
+import { defineSchema, type ParsedSchema } from 'inline-schema';
+import type { CommandSchema, CommandParamSchema, CommandOptionSchema, CommandFlagSchema, ParsedOptionResult } from './types.js';
+
+export function parseCommandSchema(schemaStr: string, name?: string): CommandSchema {
+    const schema: CommandSchema = {
+        name: name ?? '',
+        params: [],
+        options: [],
+        flags: [],
+    };
+
+    const tokens = tokenizeSchema(schemaStr);
+    if (tokens.length === 0) {
+        return schema;
+    }
+
+    const startIdx = name !== undefined ? 0 : 1;
+    schema.name = name ?? tokens[0];
+
+    let i = startIdx;
+    while (i < tokens.length) {
+        const token = tokens[i];
+
+        if (token.startsWith('[') && token.endsWith(']')) {
+            const inner = token.slice(1, -1).trim();
+
+            if (inner.startsWith('--')) {
+                const result = parseOptionToken(inner.slice(2), false);
+                if (result.isFlag) {
+                    schema.flags.push({ name: result.name, short: result.short });
+                } else {
+                    schema.options.push({
+                        name: result.name,
+                        short: result.short,
+                        required: false,
+                        defaultValue: result.defaultValue,
+                        schema: result.schema,
+                    });
+                }
+            } else if (inner.startsWith('-') && inner.length > 1 && !inner.includes('--')) {
+                const result = parseOptionToken(inner.slice(1), false);
+                if (result.isFlag) {
+                    schema.flags.push({ name: result.name, short: result.short || result.name });
+                } else {
+                    schema.options.push({
+                        name: result.name,
+                        short: result.short || result.name,
+                        required: false,
+                        defaultValue: result.defaultValue,
+                        schema: result.schema,
+                    });
+                }
+            } else {
+                const isVariadic = inner.endsWith('...');
+                let paramContent = isVariadic ? inner.slice(0, -3) : inner;
+                let parsedSchema: ParsedSchema | undefined;
+                
+                if (paramContent.includes(':')) {
+                    const colonIdx = paramContent.indexOf(':');
+                    const name = paramContent.slice(0, colonIdx).trim();
+                    const typeStr = paramContent.slice(colonIdx + 1).trim();
+                    try {
+                        parsedSchema = defineSchema(typeStr);
+                    } catch (e) {
+                        // 不是有效的 schema
+                    }
+                    paramContent = name;
+                }
+
+                schema.params.push({
+                    name: paramContent,
+                    required: false,
+                    variadic: isVariadic,
+                    schema: parsedSchema,
+                });
+            }
+            i++;
+        } else if (token.startsWith('--')) {
+            const result = parseOptionToken(token.slice(2), true);
+            if (result.isFlag) {
+                schema.flags.push({ name: result.name, short: result.short });
+            } else {
+                schema.options.push({
+                    name: result.name,
+                    short: result.short,
+                    required: true,
+                    defaultValue: result.defaultValue,
+                    schema: result.schema,
+                });
+            }
+            i++;
+        } else if (token.startsWith('-') && token.length > 1 && !/^-?\d+$/.test(token)) {
+            const result = parseOptionToken(token.slice(1), true);
+            if (result.isFlag) {
+                schema.flags.push({ name: result.name, short: result.short || result.name });
+            } else {
+                schema.options.push({
+                    name: result.name,
+                    short: result.short || result.name,
+                    required: true,
+                    defaultValue: result.defaultValue,
+                    schema: result.schema,
+                });
+            }
+            i++;
+        } else if (token.startsWith('<') && token.endsWith('>')) {
+            const isVariadic = token.endsWith('...>');
+            let paramContent = token.replace(/^<+|>+$/g, '');
+            if (isVariadic) {
+                paramContent = paramContent.replace(/\.\.\.$/, '');
+            }
+            let parsedSchema: ParsedSchema | undefined;
+            
+            if (paramContent.includes(':')) {
+                const colonIdx = paramContent.indexOf(':');
+                const name = paramContent.slice(0, colonIdx).trim();
+                const typeStr = paramContent.slice(colonIdx + 1).trim();
+                try {
+                    parsedSchema = defineSchema(typeStr);
+                } catch (e) {
+                    // 不是有效的 schema
+                }
+                paramContent = name;
+            }
+
+            schema.params.push({
+                name: paramContent,
+                required: true,
+                variadic: isVariadic,
+                schema: parsedSchema,
+            });
+            i++;
+        } else {
+            i++;
+        }
+    }
+
+    return schema;
+}
+
+function parseOptionToken(token: string, required: boolean): ParsedOptionResult {
+    const parts = token.split(/\s+/);
+    const mainPart = parts[0];
+    
+    let name: string;
+    let typeStr: string | undefined;
+    let isFlag = false;
+    
+    if (mainPart.endsWith(':')) {
+        name = mainPart.slice(0, -1).trim();
+        typeStr = parts[1] || 'string';
+    } else if (mainPart.includes(':')) {
+        const [optName, optType] = mainPart.split(':').map(s => s.trim());
+        name = optName;
+        typeStr = optType;
+    } else {
+        name = mainPart;
+        isFlag = true;
+    }
+    
+    if (typeStr === 'boolean') {
+        isFlag = true;
+        typeStr = undefined;
+    }
+    
+    let short: string | undefined;
+    let defaultValue: unknown;
+    let schema: ParsedSchema | undefined;
+    
+    for (let i = 1; i < parts.length; i++) {
+        const part = parts[i];
+        
+        if (part.startsWith('-') && part.length === 2) {
+            short = part.slice(1);
+        } else if (part === '=') {
+            const valuePart = parts[i + 1];
+            if (valuePart) {
+                try {
+                    defaultValue = JSON.parse(valuePart);
+                } catch {
+                    defaultValue = valuePart;
+                }
+                i++;
+            }
+        } else if (part.startsWith('=')) {
+            const valuePart = part.slice(1);
+            try {
+                defaultValue = JSON.parse(valuePart);
+            } catch {
+                defaultValue = valuePart;
+            }
+        }
+    }
+    
+    if (typeStr && !isFlag) {
+        try {
+            schema = defineSchema(typeStr);
+        } catch {
+            // 不是有效的 schema
+        }
+    }
+    
+    return { name, short, isFlag, schema, defaultValue };
+}
+
+function tokenizeSchema(input: string): string[] {
+    const tokens: string[] = [];
+    let current = '';
+    let inBracket = false;
+    let bracketContent = '';
+    let i = 0;
+
+    while (i < input.length) {
+        const char = input[i];
+
+        if (inBracket) {
+            if (char === ']') {
+                tokens.push(`[${bracketContent}]`);
+                inBracket = false;
+                bracketContent = '';
+                current = '';
+            } else if (char === '[') {
+                bracketContent += char;
+            } else {
+                bracketContent += char;
+            }
+        } else if (/\s/.test(char)) {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = '';
+            }
+        } else if (char === '[') {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = '';
+            }
+            inBracket = true;
+            bracketContent = '';
+        } else if (char === '<') {
+            let angleContent = '<';
+            i++;
+            while (i < input.length && input[i] !== '>') {
+                angleContent += input[i];
+                i++;
+            }
+            angleContent += '>';
+            tokens.push(angleContent);
+        } else {
+            current += char;
+        }
+
+        i++;
+    }
+
+    if (current.length > 0) {
+        tokens.push(current);
+    }
+
+    if (bracketContent.length > 0) {
+        tokens.push(`[${bracketContent}`);
+    }
+
+    return tokens;
+}

src/utils/command/types.ts

@@ -0,0 +1,43 @@
+import { type ParsedSchema } from 'inline-schema';
+
+export type Command = {
+    name: string;
+    flags: Record<string, true>;
+    options: Record<string, unknown>;
+    params: unknown[];
+}
+
+export type CommandParamSchema = {
+    name: string;
+    required: boolean;
+    variadic: boolean;
+    schema?: ParsedSchema;
+}
+
+export type CommandOptionSchema = {
+    name: string;
+    short?: string;
+    required: boolean;
+    defaultValue?: unknown;
+    schema?: ParsedSchema;
+}
+
+export type CommandFlagSchema = {
+    name: string;
+    short?: string;
+}
+
+export type CommandSchema = {
+    name: string;
+    params: CommandParamSchema[];
+    options: CommandOptionSchema[];
+    flags: CommandFlagSchema[];
+}
+
+export interface ParsedOptionResult {
+    name: string;
+    short?: string;
+    isFlag: boolean;
+    schema?: ParsedSchema;
+    defaultValue?: unknown;
+}

src/utils/rng.ts

@@ -1,4 +1,4 @@
-export interface RNG {
+export interface RNG {
     /** 设置随机数种子 */
     setSeed(seed: number): void;
 
@@ -20,7 +20,7 @@ export function createRNG(seed?: number): RNG {
 }
 
 /** Mulberry32RNG 类实现（用于类型兼容） */
-export class Mulberry32RNG {
+export class Mulberry32RNG implements RNG {
     private seed: number = 1;
 
     constructor(seed?: number) {
@@ -30,7 +30,7 @@ export class Mulberry32RNG {
     }
 
     /** 设置随机数种子 */
-    call(seed: number): void {
+    setSeed(seed: number): void {
         this.seed = seed;
     }
 
@@ -48,11 +48,6 @@ export class Mulberry32RNG {
         return Math.floor(this.next(max));
     }
 
-    /** 重新设置种子 */
-    setSeed(seed: number): void {
-        this.seed = seed;
-    }
-
     /** 获取当前种子 */
     getSeed(): number {
         return this.seed;

tests/core/rule.test.ts

@@ -0,0 +1,392 @@
+import { describe, it, expect } from 'vitest';
+import { createRule, dispatchCommand, type RuleContext, type RuleRegistry } from '../../src/core/rule';
+import { createGameContext } from '../../src/core/context';
+
+describe('Rule System', () => {
+    function createTestGame() {
+        const game = createGameContext();
+        return game;
+    }
+
+    describe('createRule', () => {
+        it('should create a rule definition with parsed schema', () => {
+            const rule = createRule('<from> <to> [--force]', function*(cmd) {
+                return { from: cmd.params[0], to: cmd.params[1] };
+            });
+
+            expect(rule.schema.params).toHaveLength(2);
+            expect(rule.schema.params[0].name).toBe('from');
+            expect(rule.schema.params[0].required).toBe(true);
+            expect(rule.schema.params[1].name).toBe('to');
+            expect(rule.schema.params[1].required).toBe(true);
+            expect(rule.schema.flags).toHaveLength(1);
+            expect(rule.schema.flags[0].name).toBe('force');
+        });
+
+        it('should create a generator when called', () => {
+            const rule = createRule('<target>', function*(cmd) {
+                return cmd.params[0];
+            });
+
+            const gen = rule.create({ name: 'test', params: ['card1'], flags: {}, options: {} });
+            const result = gen.next();
+            expect(result.done).toBe(true);
+            expect(result.value).toBe('card1');
+        });
+    });
+
+    describe('dispatchCommand - rule invocation', () => {
+        it('should invoke a registered rule and yield schema', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('move', createRule('<from> <to>', function*(cmd) {
+                yield { name: '', params: [], options: [], flags: [] };
+                return { moved: cmd.params[0] };
+            }));
+
+            const ctx = game.dispatchCommand('move card1 hand');
+
+            expect(ctx).toBeDefined();
+            expect(ctx!.state).toBe('yielded');
+            expect(ctx!.schema).toBeDefined();
+            expect(ctx!.resolution).toBeUndefined();
+        });
+
+        it('should complete a rule when final command matches yielded schema', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('move', createRule('<from> <to>', function*(cmd) {
+                const confirm = yield { name: '', params: [], options: [], flags: [] };
+                return { moved: cmd.params[0], confirmed: confirm.name === 'confirm' };
+            }));
+
+            game.dispatchCommand('move card1 hand');
+            const ctx = game.dispatchCommand('confirm');
+
+            expect(ctx).toBeDefined();
+            expect(ctx!.state).toBe('done');
+            expect(ctx!.resolution).toEqual({ moved: 'card1', confirmed: true });
+        });
+
+        it('should return undefined when command matches no rule and no yielded context', () => {
+            const game = createTestGame();
+
+            const result = game.dispatchCommand('unknown command');
+
+            expect(result).toBeUndefined();
+        });
+
+        it('should pass the initial command to the generator', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('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' });
+        });
+
+        it('should complete immediately if generator does not yield', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('look', createRule('[--at]', function*() {
+                return 'looked';
+            }));
+
+            const ctx = game.dispatchCommand('look');
+
+            expect(ctx!.state).toBe('done');
+            expect(ctx!.resolution).toBe('looked');
+        });
+    });
+
+    describe('dispatchCommand - rule priority', () => {
+        it('should prioritize new rule invocation over feeding yielded context', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('move', createRule('<from> <to>', function*(cmd) {
+                yield { name: '', params: [], options: [], flags: [] };
+                return { moved: cmd.params[0] };
+            }));
+
+            game.rules.value.set('confirm', createRule('', function*() {
+                return 'new confirm rule';
+            }));
+
+            game.dispatchCommand('move card1 hand');
+
+            const ctx = game.dispatchCommand('confirm');
+
+            expect(ctx!.state).toBe('done');
+            expect(ctx!.resolution).toBe('new confirm rule');
+            expect(ctx!.type).toBe('');
+        });
+    });
+
+    describe('dispatchCommand - fallback to yielded context', () => {
+        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) {
+                const response = yield { name: '', params: [], options: [], flags: [] };
+                return { moved: cmd.params[0], response: response.name };
+            }));
+
+            game.dispatchCommand('move card1 hand');
+            const ctx = game.dispatchCommand('yes');
+
+            expect(ctx!.state).toBe('done');
+            expect(ctx!.resolution).toEqual({ moved: 'card1', response: 'yes' });
+        });
+
+        it('should skip non-matching commands for yielded context', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('move', createRule('<from> <to>', function*(cmd) {
+                const response = yield '<item>';
+                return { response: response.params[0] };
+            }));
+
+            game.dispatchCommand('move card1 hand');
+
+            const ctx = game.dispatchCommand('goblin');
+
+            expect(ctx).toBeUndefined();
+        });
+
+        it('should validate command against yielded schema', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('trade', createRule('<from> <to>', function*(cmd) {
+                const response = yield '<item> [amount: number]';
+                return { traded: response.params[0] };
+            }));
+
+            game.dispatchCommand('trade player1 player2');
+            const ctx = game.dispatchCommand('offer gold 5');
+
+            expect(ctx!.state).toBe('done');
+            expect(ctx!.resolution).toEqual({ traded: 'gold' });
+        });
+    });
+
+    describe('dispatchCommand - deepest context first', () => {
+        it('should feed the deepest yielded context', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('parent', createRule('<action>', function*() {
+                yield { name: '', params: [], options: [], flags: [] };
+                return 'parent done';
+            }));
+
+            game.rules.value.set('child', createRule('<target>', function*() {
+                yield { name: '', params: [], options: [], flags: [] };
+                return 'child done';
+            }));
+
+            game.dispatchCommand('parent start');
+            game.dispatchCommand('child target1');
+
+            const ctx = game.dispatchCommand('grandchild_cmd');
+
+            expect(ctx!.state).toBe('done');
+            expect(ctx!.resolution).toBe('child done');
+        });
+    });
+
+    describe('nested rule invocations', () => {
+        it('should link child to parent', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('parent', createRule('<action>', function*() {
+                yield 'child_cmd';
+                return 'parent done';
+            }));
+
+            game.rules.value.set('child_cmd', createRule('<target>', function*() {
+                return 'child done';
+            }));
+
+            game.dispatchCommand('parent start');
+            const parentCtx = game.ruleContexts.value[0];
+
+            game.dispatchCommand('child_cmd target1');
+
+            expect(parentCtx.state).toBe('waiting');
+
+            const childCtx = game.ruleContexts.value[1];
+            expect(childCtx.parent).toBe(parentCtx);
+            expect(parentCtx.children).toContain(childCtx);
+        });
+
+        it('should discard previous children when a new child is invoked', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('parent', createRule('<action>', function*() {
+                yield 'child_a | child_b';
+                return 'parent done';
+            }));
+
+            game.rules.value.set('child_a', createRule('<target>', function*() {
+                return 'child_a done';
+            }));
+
+            game.rules.value.set('child_b', createRule('<target>', function*() {
+                return 'child_b done';
+            }));
+
+            game.dispatchCommand('parent start');
+            game.dispatchCommand('child_a target1');
+
+            expect(game.ruleContexts.value.length).toBe(2);
+
+            const oldParent = game.ruleContexts.value[0];
+            expect(oldParent.children).toHaveLength(1);
+
+            game.dispatchCommand('parent start');
+            game.dispatchCommand('child_b target2');
+
+            const newParent = game.ruleContexts.value[2];
+            expect(newParent.children).toHaveLength(1);
+            expect(newParent.children[0].resolution).toBe('child_b done');
+        });
+    });
+
+    describe('context tracking', () => {
+        it('should track rule contexts in ruleContexts signal', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('test', createRule('<arg>', function*() {
+                yield { name: '', params: [], options: [], flags: [] };
+                return 'done';
+            }));
+
+            expect(game.ruleContexts.value.length).toBe(0);
+
+            game.dispatchCommand('test arg1');
+
+            expect(game.ruleContexts.value.length).toBe(1);
+            expect(game.ruleContexts.value[0].state).toBe('yielded');
+        });
+
+        it('should add context to the context stack', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('test', createRule('<arg>', function*() {
+                yield { name: '', params: [], options: [], flags: [] };
+                return 'done';
+            }));
+
+            const initialStackLength = game.contexts.value.length;
+
+            game.dispatchCommand('test arg1');
+
+            expect(game.contexts.value.length).toBe(initialStackLength + 1);
+        });
+    });
+
+    describe('error handling', () => {
+        it('should leave context in place when generator throws', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('failing', createRule('<arg>', function*() {
+                throw new Error('rule error');
+            }));
+
+            expect(() => game.dispatchCommand('failing arg1')).toThrow('rule error');
+
+            expect(game.ruleContexts.value.length).toBe(1);
+        });
+
+        it('should leave children in place when child generator throws', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('parent', createRule('<action>', function*() {
+                yield 'child';
+                return 'parent done';
+            }));
+
+            game.rules.value.set('child', createRule('<target>', function*() {
+                throw new Error('child error');
+            }));
+
+            game.dispatchCommand('parent start');
+            expect(() => game.dispatchCommand('child target1')).toThrow('child error');
+
+            expect(game.ruleContexts.value.length).toBe(2);
+        });
+    });
+
+    describe('schema yielding', () => {
+        it('should accept a CommandSchema object as yield value', () => {
+            const game = createTestGame();
+
+            const customSchema = {
+                name: 'custom',
+                params: [{ name: 'x', required: true, variadic: false }],
+                options: [],
+                flags: [],
+            };
+
+            game.rules.value.set('test', createRule('<arg>', function*() {
+                const cmd = yield customSchema;
+                return { received: cmd.params[0] };
+            }));
+
+            game.dispatchCommand('test val1');
+            const ctx = game.dispatchCommand('custom hello');
+
+            expect(ctx!.state).toBe('done');
+            expect(ctx!.resolution).toEqual({ received: 'hello' });
+        });
+
+        it('should parse string schema on each yield', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('multi', createRule('<start>', function*() {
+                const a = yield '<value>';
+                const b = yield '<value>';
+                return { a: a.params[0], b: b.params[0] };
+            }));
+
+            game.dispatchCommand('multi init');
+            game.dispatchCommand('cmd first');
+            const ctx = game.dispatchCommand('cmd second');
+
+            expect(ctx!.state).toBe('done');
+            expect(ctx!.resolution).toEqual({ a: 'first', b: 'second' });
+        });
+    });
+
+    describe('complex flow', () => {
+        it('should handle a multi-step game flow', () => {
+            const game = createTestGame();
+
+            game.rules.value.set('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]';
+                }
+
+                return { player, action: action.name };
+            }));
+
+            const ctx1 = game.dispatchCommand('start alice');
+            expect(ctx1!.state).toBe('yielded');
+
+            const ctx2 = game.dispatchCommand('attack');
+            expect(ctx2!.state).toBe('yielded');
+
+            const ctx3 = game.dispatchCommand('attack goblin --power 3');
+            expect(ctx3!.state).toBe('done');
+            expect(ctx3!.resolution).toEqual({ player: 'alice', action: 'attack' });
+        });
+    });
+});