@zhin.js/game-kit 2.0.0 → 2.0.2

package/lib/versioned-session-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-session-service.js","sourceRoot":"","sources":["../src/versioned-session-service.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/game-kit",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Zhin.js 游戏插件通用工具包",
   "type": "module",
   "main": "./lib/index.js",
@@ -13,8 +13,8 @@
     }
   },
   "peerDependencies": {
-    "zhin.js": "^5.0.0",
-    "@zhin.js/html-renderer": "2.0.0"
+    "zhin.js": "^5.0.2",
+    "@zhin.js/html-renderer": "2.0.2"
   },
   "peerDependenciesMeta": {
     "@zhin.js/html-renderer": {
@@ -22,13 +22,14 @@
     }
   },
   "dependencies": {
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/middleware": "1.0.2",
-    "@zhin.js/satori": "1.0.16"
+    "@zhin.js/core": "1.4.2",
+    "@zhin.js/middleware": "1.0.4",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "@zhin.js/satori": "1.0.17"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "zhin.js": "5.0.0"
+    "zhin.js": "5.0.2"
   },
   "files": [
     "lib",

package/src/base-session-service.ts

@@ -0,0 +1,210 @@
+import {
+  gameEvents,
+  type GameEventSession,
+  type GameOutcome,
+} from './game-events.js';
+import { gameSessionCoordinator, type GameSessionProvider } from './session-coordinator.js';
+
+export interface BaseGameSessionRow extends GameEventSession {
+  id: string;
+  channel_key: string;
+  status: string;
+  updated_at: number;
+  created_at: number;
+  turn?: unknown;
+}
+
+export interface GameSessionModel<TRow extends BaseGameSessionRow> {
+  findAll(query?: Record<string, unknown>): Promise<TRow[]>;
+  findOne(query?: Record<string, unknown>): Promise<TRow | null>;
+  create(row: TRow): Promise<unknown>;
+  updateWhere(
+    where: Record<string, unknown>,
+    patch: Record<string, unknown>,
+  ): Promise<unknown>;
+}
+
+export interface GameSessionDatabase<TRow extends BaseGameSessionRow> {
+  readonly models: {
+    get(name: string): GameSessionModel<TRow> | undefined;
+  };
+}
+
+export interface BaseSessionServiceOptions<TRow extends BaseGameSessionRow> {
+  readonly gameId: string;
+  readonly table: string;
+  readonly userFields: readonly (keyof TRow & string)[];
+  readonly activeStatus?: string;
+  readonly abortedStatus?: string;
+  readonly projectOutcomes?: (
+    session: Readonly<TRow>,
+    previous: Readonly<TRow>,
+  ) => readonly GameOutcome[];
+}
+
+export type SessionTimeoutListener<TRow extends BaseGameSessionRow> = (
+  session: TRow,
+) => void | Promise<void>;
+
+/**
+ * Shared session lifecycle for every game. Subclasses own row construction and
+ * game-specific tables; this module owns persistence invariants and events.
+ */
+export abstract class BaseSessionService<TRow extends BaseGameSessionRow>
+implements GameSessionProvider {
+  readonly gameId: string;
+  readonly #activeStatus: string;
+  readonly #abortedStatus: string;
+  readonly #userFields: readonly (keyof TRow & string)[];
+  readonly #projectOutcomes?: BaseSessionServiceOptions<TRow>['projectOutcomes'];
+  readonly #model: GameSessionModel<TRow>;
+
+  protected constructor(
+    database: GameSessionDatabase<TRow>,
+    options: BaseSessionServiceOptions<TRow>,
+  ) {
+    const model = database.models.get(options.table);
+    if (!model) throw new Error(`${options.table} not registered`);
+    this.#model = model;
+    this.gameId = options.gameId;
+    this.#userFields = options.userFields;
+    this.#projectOutcomes = options.projectOutcomes;
+    this.#activeStatus = options.activeStatus ?? 'active';
+    this.#abortedStatus = options.abortedStatus ?? 'aborted';
+  }
+
+  async getById(id: string): Promise<TRow | null> {
+    return this.#model.findOne({ id });
+  }
+
+  async getActiveByChannel(channelKey: string): Promise<TRow | null> {
+    const rows = await this.#model.findAll({
+      channel_key: channelKey,
+      status: this.#activeStatus,
+    });
+    return rows[0] ?? null;
+  }
+
+  async getActiveForUser(channelKey: string, userId: string): Promise<TRow | null> {
+    const rows = await this.#model.findAll({
+      channel_key: channelKey,
+      status: this.#activeStatus,
+    });
+    return rows.find((row) =>
+      this.#userFields.some((field) => row[field] === userId)) ?? null;
+  }
+
+  async getLatestForUser(channelKey: string, userId: string): Promise<TRow | null> {
+    const rows = await this.#model.findAll({ channel_key: channelKey });
+    const matches = rows.filter((row) =>
+      this.#userFields.some((field) => row[field] === userId));
+    return matches.reduce<TRow | null>(
+      (latest, row) => !latest || row.updated_at >= latest.updated_at ? row : latest,
+      null,
+    );
+  }
+
+  async updateSession(id: string, patch: Partial<TRow>): Promise<void> {
+    const previous = await this.getById(id);
+    if (!previous) return;
+    await this.commitSession(previous, patch, { id });
+  }
+
+  /**
+   * Persist one transition and emit lifecycle events from the row that was
+   * actually stored. Versioned services use `where` for optimistic locking.
+   */
+  protected async commitSession(
+    previous: TRow,
+    patch: Partial<TRow>,
+    where: Record<string, unknown>,
+  ): Promise<TRow | null> {
+    const updatedAt = Date.now();
+    const changed = await this.#model.updateWhere(
+      where,
+      { ...patch, updated_at: updatedAt },
+    );
+    if (typeof changed === 'number' && changed === 0) return null;
+    const session = await this.getById(previous.id);
+    if (!session) return null;
+    if (patch.turn !== undefined && patch.turn !== previous.turn) {
+      await gameEvents.emit('turn:change', {
+        gameId: this.gameId,
+        session,
+        previousTurn: previous.turn,
+        turn: patch.turn,
+      });
+    }
+    if (patch.status !== undefined
+      && previous.status === this.#activeStatus
+      && patch.status !== this.#activeStatus) {
+      await gameEvents.emit('game:end', {
+        gameId: this.gameId,
+        session,
+        previousStatus: previous.status,
+        outcomes: this.#projectOutcomes?.(session, previous) ?? [],
+      });
+    }
+    return session;
+  }
+
+  async abortStale(
+    idleMs: number,
+    onTimeout?: SessionTimeoutListener<TRow>,
+  ): Promise<number> {
+    const cutoff = Date.now() - idleMs;
+    const rows = await this.#model.findAll({ status: this.#activeStatus });
+    let count = 0;
+    for (const row of rows) {
+      if (row.updated_at >= cutoff) continue;
+      // The timestamp condition prevents a cleanup scan from aborting a
+      // session that received a player action after this row was selected.
+      const session = await this.commitSession(
+        row,
+        { status: this.#abortedStatus } as Partial<TRow>,
+        {
+          id: row.id,
+          status: this.#activeStatus,
+          updated_at: row.updated_at,
+        },
+      );
+      if (!session) continue;
+      await gameEvents.emit('session:timeout', {
+        gameId: this.gameId,
+        session,
+        idleMs,
+      });
+      // A broken outbound adapter must not prevent later stale sessions from
+      // being finalized. Persistence and lifecycle events already succeeded.
+      if (onTimeout) {
+        try {
+          await onTimeout(session);
+        } catch {
+          // Notification is best-effort; the next cleanup pass stays healthy.
+        }
+      }
+      count += 1;
+    }
+    return count;
+  }
+
+  registerCoordinator(): () => void {
+    return gameSessionCoordinator.register(this);
+  }
+
+  protected async createRow(row: TRow): Promise<TRow> {
+    const userIds: string[] = [];
+    for (const field of this.#userFields) {
+      const value: unknown = row[field];
+      if (typeof value === 'string') userIds.push(value);
+    }
+    await gameSessionCoordinator.assertAvailable(this.gameId, row.channel_key, userIds);
+    await this.#model.create(row);
+    await gameEvents.emit('game:start', { gameId: this.gameId, session: row });
+    return row;
+  }
+
+  protected get model(): GameSessionModel<TRow> {
+    return this.#model;
+  }
+}

package/src/board-sender.ts

@@ -1,16 +1,15 @@
 /**
- * 游戏棋盘消息辅助工具
- * 提供会话键生成和消息 ID 更新回调封装
+ * 游戏棋盘会话键工具。
  *
- * 注意：实际的发送/编辑逻辑由 Adapter.editMessage 统一处理
- * - 支持编辑的平台：调用平台 API 编辑
- * - 不支持编辑的平台：自动 fallback 到发送新消息
+ * Plugin Runtime 下游戏逻辑操作的是 game-kit 自有的 `GameMessageLike`
+ * （由 `messageFromCommandInput` 从 CommandContext.input 桥接而来），
+ * 不再依赖 `@zhin.js/core` 的 Message 类型或 Adapter.editMessage 交互路径。
  */
-import type { Message } from '@zhin.js/core';
+import type { GameMessageLike } from './command-message.js';
 
 /**
  * 构建频道唯一键（用于会话查找）
  */
-export function channelKey(message: Message): string {
+export function channelKey(message: GameMessageLike): string {
   return `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
 }

package/src/choice-keyboard.ts

@@ -35,9 +35,11 @@ export function buildChoiceFallbackMap(
   gamePrefix: string,
   sessionId: string,
   choices: ChoiceOption[],
+  /** 起始编号（默认 1）；拼在网格 fallback 之后时传空格数 +1，避免覆盖格子映射 */
+  startIndex = 1,
 ): Record<string, string> {
   const map: Record<string, string> = {};
-  let n = 1;
+  let n = startIndex;
   for (const choice of choices) {
     if (!choice.disabled) {
       map[String(n)] = `${gamePrefix}:${sessionId}:${choice.id}`;

package/src/command-alias.ts

@@ -1,6 +1,8 @@
 import { defineMiddleware, type MiddlewareContext } from '@zhin.js/middleware';
 import type { Message } from '@zhin.js/core/runtime';
 
+type AliasReply = Parameters<Message['$reply']>[0];
+
 /**
  * 游戏 legacy 命令别名路由。
  *
@@ -20,7 +22,7 @@ export interface GameCommandAliasRoute {
     action: string,
     input: unknown,
     context: MiddlewareContext<Message>,
-  ): Promise<string | null | undefined>;
+  ): Promise<AliasReply | null | undefined>;
 }
 
 export function defineGameCommandAliasMiddleware(route: GameCommandAliasRoute) {

package/src/command-message.ts

@@ -4,12 +4,20 @@
  * Runtime Message: { adapter, target, sender?, metadata? }
  * Classic Message: { $adapter, $endpoint, $channel, $sender }
  */
+import type { SendContent } from '@zhin.js/core';
+
+/** A game returns semantic content; Runtime owns native rendering and text fallback. */
+export type GameReply = SendContent;
 
 export interface GameMessageLike {
   $adapter: string;
   $endpoint: string;
   $channel: { type: string; id: string };
-  $sender: { id: string; name: string };
+  // `name` is optional so this stays a structural supertype of the core
+  // Message shape (whose $sender.name is string | undefined). That lets the
+  // shared game-kit helpers accept both the runtime-bridged GameMessageLike
+  // and, during incremental migration, a legacy core Message.
+  $sender: { id: string; name?: string };
 }
 
 function isClassicMessage(input: unknown): input is GameMessageLike {

package/src/define-game-plugin.ts

@@ -0,0 +1,162 @@
+import {
+  databaseHostToken,
+  definePlugin,
+  outboundHostToken,
+  scheduleHostToken,
+  type DatabaseHost,
+  type PluginMetadata,
+  type PluginSetupContext,
+  type Token,
+} from '@zhin.js/plugin-runtime';
+import {
+  createHostGameDb,
+  createInMemoryGameDb,
+  type InMemoryGameDb,
+} from './memory-db.js';
+import {
+  initGameRecordHost,
+  recordGameOutcome,
+  type GameRecordDatabaseHost,
+} from './game-records.js';
+import { gameEvents } from './game-events.js';
+import {
+  DEFAULT_GAME_STALE_CRON,
+  DEFAULT_GAME_STALE_IDLE_MS,
+  registerRuntimeGame,
+  type RuntimeRegisteredGame,
+} from './runtime-hub.js';
+import type {
+  BaseGameSessionRow,
+  BaseSessionService,
+} from './base-session-service.js';
+
+export interface GamePluginSession<
+  TRow extends BaseGameSessionRow = BaseGameSessionRow,
+> {
+  abortStale(
+    idleMs: number,
+    onTimeout?: (session: TRow) => void | Promise<void>,
+  ): Promise<number>;
+  registerCoordinator?(): () => void;
+}
+
+export interface DefineGamePluginOptions<
+  TServices,
+  TRow extends BaseGameSessionRow = BaseGameSessionRow,
+  TConfig = unknown,
+> {
+  readonly name: string;
+  readonly metadata?: PluginMetadata;
+  readonly game: RuntimeRegisteredGame;
+  readonly tables: readonly string[];
+  readonly servicesToken: Token<TServices>;
+  readonly defineHostTables: (host: DatabaseHost) => void;
+  readonly createServices: (database: InMemoryGameDb) => TServices;
+  readonly session: (
+    services: TServices,
+  ) => GamePluginSession<TRow> | BaseSessionService<TRow>;
+  readonly stale?: {
+    readonly cron?: string;
+    readonly idleMs?: number;
+    readonly description?: string;
+    readonly message?: string | ((session: TRow) => string);
+    readonly onTimeout?: (
+      session: TRow,
+      context: PluginSetupContext<TConfig>,
+    ) => void | Promise<void>;
+  } | false;
+  readonly setup?: (
+    context: PluginSetupContext<TConfig>,
+    services: TServices,
+  ) => void | (() => void) | Promise<void | (() => void)>;
+}
+
+/**
+ * Declarative Plugin Runtime assembly for games. Database selection, service
+ * publication, Hub registration, stale cleanup and HMR disposal live here.
+ */
+export function defineGamePlugin<
+  TServices,
+  TRow extends BaseGameSessionRow = BaseGameSessionRow,
+  TConfig = unknown,
+>(
+  options: DefineGamePluginOptions<TServices, TRow, TConfig>,
+) {
+  return definePlugin<TConfig>({
+    name: options.name,
+    metadata: options.metadata,
+    async setup(context) {
+      let database: InMemoryGameDb;
+      if (context.resources.has(databaseHostToken)) {
+        const host = context.resources.use(databaseHostToken);
+        options.defineHostTables(host);
+        database = createHostGameDb(host, options.tables);
+        context.lifecycle.add(
+          initGameRecordHost(host as unknown as GameRecordDatabaseHost),
+        );
+      } else {
+        database = createInMemoryGameDb(options.tables);
+      }
+
+      const services = options.createServices(database);
+      context.resources.provide(options.servicesToken, services);
+
+      const session = options.session(services);
+      const disposeCoordinator = session.registerCoordinator?.();
+      if (disposeCoordinator) context.lifecycle.add(disposeCoordinator);
+      context.lifecycle.add(registerRuntimeGame(options.game));
+      context.lifecycle.add(gameEvents.on('game:end', async (event) => {
+        if (event.gameId !== options.game.id || event.outcomes.length === 0) return;
+        const row = event.session;
+        if (!row.adapter || !row.endpoint || !row.channel_type || !row.channel_id) return;
+        for (const outcome of event.outcomes) {
+          await recordGameOutcome({
+            $adapter: row.adapter,
+            $endpoint: row.endpoint,
+            $channel: { type: row.channel_type, id: row.channel_id },
+            $sender: {
+              id: outcome.userId,
+              name: outcome.userName ?? outcome.userId,
+            },
+          }, event.gameId, outcome.result, outcome.score);
+        }
+      }));
+
+      if (options.stale !== false && context.resources.has(scheduleHostToken)) {
+        const stale = options.stale ?? {};
+        const schedule = context.resources.use(scheduleHostToken);
+        context.lifecycle.add(schedule.register({
+          id: `${options.game.id}/abort-stale`,
+          cron: stale.cron ?? DEFAULT_GAME_STALE_CRON,
+          description: stale.description
+            ?? `Abort stale ${options.name} sessions`,
+          async execute() {
+            await session.abortStale(
+              stale.idleMs ?? DEFAULT_GAME_STALE_IDLE_MS,
+              async (row) => {
+                await stale.onTimeout?.(row, context);
+                if (!context.resources.has(outboundHostToken)) return;
+                if (!row.adapter || !row.endpoint
+                  || !row.channel_type || !row.channel_id) return;
+                const outbound = context.resources.use(outboundHostToken);
+                await outbound.send({
+                  adapter: row.adapter,
+                  endpointId: row.endpoint,
+                  channelType: row.channel_type,
+                  channelId: row.channel_id,
+                  content: typeof stale.message === 'function'
+                    ? stale.message(row)
+                    : stale.message
+                      ?? `${options.game.icon} ${options.game.title}对局因长时间无操作已结束。`,
+                });
+              },
+            );
+          },
+        }));
+      }
+
+      const dispose = await options.setup?.(context, services);
+      if (dispose) context.lifecycle.add(dispose);
+    },
+  });
+}

package/src/deterministic-random.ts

@@ -0,0 +1,81 @@
+const UINT32_RANGE = 0x1_0000_0000;
+const ZERO_STATE_FALLBACK = 0x6d2b79f5;
+
+/**
+ * Serializable xorshift32 generator for replayable game simulations.
+ * Security-sensitive randomness must continue using secureRandomInt.
+ */
+export class DeterministicRandom {
+  #state: number;
+
+  private constructor(state: number) {
+    this.#state = normalizeState(state);
+  }
+
+  static fromSeed(seed: string | number): DeterministicRandom {
+    return new DeterministicRandom(
+      typeof seed === 'number' ? seed : hashSeed(seed),
+    );
+  }
+
+  static fromState(state: number): DeterministicRandom {
+    return new DeterministicRandom(state);
+  }
+
+  get state(): number {
+    return this.#state;
+  }
+
+  nextUint32(): number {
+    let value = this.#state;
+    value ^= value << 13;
+    value ^= value >>> 17;
+    value ^= value << 5;
+    this.#state = value >>> 0;
+    return this.#state;
+  }
+
+  int(maxExclusive: number): number {
+    if (!Number.isSafeInteger(maxExclusive)
+      || maxExclusive <= 0
+      || maxExclusive > UINT32_RANGE) {
+      throw new RangeError(
+        'maxExclusive must be an integer between 1 and 2^32',
+      );
+    }
+    const limit = Math.floor(UINT32_RANGE / maxExclusive) * maxExclusive;
+    let value: number;
+    do {
+      value = this.nextUint32();
+    } while (value >= limit);
+    return value % maxExclusive;
+  }
+
+  intInclusive(min: number, max: number): number {
+    if (!Number.isSafeInteger(min) || !Number.isSafeInteger(max) || max < min) {
+      throw new RangeError('invalid inclusive random range');
+    }
+    return min + this.int(max - min + 1);
+  }
+
+  item<T>(items: readonly T[]): T {
+    if (items.length === 0) {
+      throw new RangeError('cannot choose from an empty array');
+    }
+    return items[this.int(items.length)] as T;
+  }
+}
+
+function normalizeState(state: number): number {
+  if (!Number.isFinite(state)) throw new RangeError('state must be finite');
+  return (state >>> 0) || ZERO_STATE_FALLBACK;
+}
+
+function hashSeed(seed: string): number {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < seed.length; index += 1) {
+    hash ^= seed.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}

package/src/game-action-alias.ts

@@ -72,22 +72,47 @@ export function normalizeTttAction(raw: string): string {
   return lookup(TTT_ACTIONS, raw);
 }
 
+/** 判断 normalize*Action 的结果是否为已知 action（未知名应放行，避免劫持普通聊天） */
+function isKnownAction(map: Record<string, string>, action: string): boolean {
+  return Object.values(map).includes(action);
+}
+
+export function isTttAction(action: string): boolean {
+  return isKnownAction(TTT_ACTIONS, action);
+}
+
 export function normalizeAdvAction(raw: string): string {
   return lookup(ADV_ACTIONS, raw);
 }
 
+export function isAdvAction(action: string): boolean {
+  return isKnownAction(ADV_ACTIONS, action);
+}
+
 export function normalizeRpsAction(raw: string): string {
   return lookup(RPS_ACTIONS, raw);
 }
 
+export function isRpsAction(action: string): boolean {
+  return isKnownAction(RPS_ACTIONS, action);
+}
+
 export function normalizeGuessAction(raw: string): string {
   return lookup(GUESS_ACTIONS, raw);
 }
 
+export function isGuessAction(action: string): boolean {
+  return isKnownAction(GUESS_ACTIONS, action);
+}
+
 export function normalizeDiceAction(raw: string): string {
   return lookup(DICE_ACTIONS, raw);
 }
 
+export function isDiceAction(action: string): boolean {
+  return isKnownAction(DICE_ACTIONS, action);
+}
+
 const CHAIN_ACTIONS: Record<string, string> = {
   start: 'start_pinyin',
   start_pinyin: 'start_pinyin',
@@ -124,6 +149,14 @@ export function normalizeChainAction(raw: string): string {
   return lookup(CHAIN_ACTIONS, raw);
 }
 
+export function isChainAction(action: string): boolean {
+  return isKnownAction(CHAIN_ACTIONS, action);
+}
+
+export function isRiddleAction(action: string): boolean {
+  return isKnownAction(RIDDLE_ACTIONS, action);
+}
+
 export function normalizeRiddleAction(raw: string): string {
   return lookup(RIDDLE_ACTIONS, raw);
 }