@zhin.js/game-kit 2.0.0 → 2.0.2

package/src/game-events.ts

@@ -0,0 +1,75 @@
+export interface GameEventSession {
+  readonly id: string;
+  readonly channel_key: string;
+  readonly status: string;
+  readonly updated_at: number;
+  readonly adapter?: string;
+  readonly endpoint?: string;
+  readonly channel_type?: string;
+  readonly channel_id?: string;
+}
+
+export interface GameOutcome {
+  readonly userId: string;
+  readonly userName?: string;
+  readonly result: 'won' | 'lost' | 'draw' | 'aborted';
+  readonly score?: number;
+}
+
+export interface GameEventMap {
+  'game:start': {
+    readonly gameId: string;
+    readonly session: GameEventSession;
+  };
+  'game:end': {
+    readonly gameId: string;
+    readonly session: GameEventSession;
+    readonly previousStatus: string;
+    readonly outcomes: readonly GameOutcome[];
+  };
+  'turn:change': {
+    readonly gameId: string;
+    readonly session: GameEventSession;
+    readonly previousTurn: unknown;
+    readonly turn: unknown;
+  };
+  'session:timeout': {
+    readonly gameId: string;
+    readonly session: GameEventSession;
+    readonly idleMs: number;
+  };
+}
+
+export type GameEventName = keyof GameEventMap;
+export type GameEventListener<K extends GameEventName> = (
+  event: GameEventMap[K],
+) => void | Promise<void>;
+
+/**
+ * Small async pub/sub used by game modules. Listener failures are isolated so a
+ * notification adapter cannot roll back an already committed session update.
+ */
+export class GameEventBus {
+  readonly #listeners = new Map<GameEventName, Set<GameEventListener<GameEventName>>>();
+
+  on<K extends GameEventName>(name: K, listener: GameEventListener<K>): () => void {
+    const listeners = this.#listeners.get(name) ?? new Set();
+    listeners.add(listener as GameEventListener<GameEventName>);
+    this.#listeners.set(name, listeners);
+    return () => {
+      listeners.delete(listener as GameEventListener<GameEventName>);
+      if (listeners.size === 0) this.#listeners.delete(name);
+    };
+  }
+
+  async emit<K extends GameEventName>(name: K, event: GameEventMap[K]): Promise<void> {
+    const listeners = [...(this.#listeners.get(name) ?? [])];
+    await Promise.allSettled(listeners.map((listener) => listener(event)));
+  }
+
+  clear(): void {
+    this.#listeners.clear();
+  }
+}
+
+export const gameEvents = new GameEventBus();

package/src/game-interactive.ts

@@ -1,18 +1,4 @@
-import { getActionFromMessage, resolvePayloadFromText, type Message } from '@zhin.js/core';
-
-import { channelKey } from './board-sender.js';
-import { parseChoicePayload } from './choice-keyboard.js';
-
-export const GAME_RESTART_CHOICE_IDS = new Set([
-  'restart',
-  'restart_char',
-  'restart_idiom',
-  'restart_bot',
-]);
-
-export function isRestartChoice(choiceId: string): boolean {
-  return GAME_RESTART_CHOICE_IDS.has(choiceId) || choiceId.startsWith('restart_');
-}
+import { resolvePayloadFromText } from '@zhin.js/core';
 
 /** 从 QQ 指令预填 / 数字 fallback 解析游戏 payload */
 export function resolveGameTextPayload(
@@ -21,68 +7,3 @@ export function resolveGameTextPayload(
 ): string | undefined {
   return resolvePayloadFromText(raw, map);
 }
-
-export interface GameSessionRef {
-  id: string;
-  channel_key: string;
-}
-
-export interface ResolveGameChoiceOptions {
-  message: Message;
-  gamePrefix: string;
-  validChoiceIds: readonly string[];
-  getById: (sessionId: string) => Promise<GameSessionRef | null>;
-  getActiveForUser: (channel: string, userId: string) => Promise<GameSessionRef | null>;
-  getByBoardMessageId?: (messageId: string) => Promise<GameSessionRef | null>;
-}
-
-/**
- * 解析按钮/选项回调：优先 payload；终局「再来一局」允许已结束 session。
- */
-export async function resolveGameChoice(
-  opts: ResolveGameChoiceOptions,
-): Promise<{ sessionId: string; choiceId: string } | null> {
-  const action = getActionFromMessage(opts.message);
-  if (!action) return null;
-
-  const ch = channelKey(opts.message);
-  const userId = opts.message.$sender.id;
-
-  const fromPayload = parseChoicePayload(action.payload, opts.gamePrefix);
-  if (fromPayload && opts.validChoiceIds.includes(fromPayload.choiceId)) {
-    const session = await opts.getById(fromPayload.sessionId);
-    if (session?.channel_key === ch) {
-      return { sessionId: fromPayload.sessionId, choiceId: fromPayload.choiceId };
-    }
-  }
-
-  const choiceId = action.id || action.payload;
-  if (!choiceId || !opts.validChoiceIds.includes(choiceId)) return null;
-
-  if (isRestartChoice(choiceId)) {
-    if (fromPayload) {
-      const session = await opts.getById(fromPayload.sessionId);
-      if (session?.channel_key === ch) {
-        return { sessionId: fromPayload.sessionId, choiceId };
-      }
-    }
-    if (action.sourceMessageId && opts.getByBoardMessageId) {
-      const byBoard = await opts.getByBoardMessageId(action.sourceMessageId);
-      if (byBoard && byBoard.channel_key === ch) {
-        return { sessionId: byBoard.id, choiceId };
-      }
-    }
-    const active = await opts.getActiveForUser(ch, userId);
-    if (active) return { sessionId: active.id, choiceId };
-    return null;
-  }
-
-  const session =
-    (await opts.getActiveForUser(ch, userId))
-    ?? (action.sourceMessageId && opts.getByBoardMessageId
-      ? await opts.getByBoardMessageId(action.sourceMessageId)
-      : null);
-  if (!session || session.channel_key !== ch) return null;
-
-  return { sessionId: session.id, choiceId };
-}

package/src/game-records.ts

@@ -1,14 +1,12 @@
 import {
-  MessageCommand,
   type Database,
   type DatabaseFeature,
-  type Message,
   type Models,
   type Plugin,
   type RelatedModel,
 } from '@zhin.js/core';
 import { channelKey } from './board-sender.js';
-import { getRegisteredGame, getRegisteredGames } from './game-hub-feature.js';
+import type { GameMessageLike } from './command-message.js';
 import { createHostGameDb, type HostGameDbSource } from './memory-db.js';
 import { generateCompactId } from './random.js';
 
@@ -39,10 +37,33 @@ const hostRegistrations: Array<{
   readonly database: GameRecordDb;
 }> = [];
 
+/** gameId → 该游戏插件 setup 时注册的战绩库（按插件作用域取库，避免多 Host 时全局最后注册者胜） */
+const gameDatabases = new Map<string, GameRecordDb>();
+/** 最近一次 initGameRecordHost 注册的库；registerRuntimeGame 借此把游戏绑定到所属 Host 的库 */
+let latestHostDatabase: GameRecordDb | null = null;
+
 function activeDatabase(): GameRecordDb | null {
   return hostRegistrations[hostRegistrations.length - 1]?.database ?? legacyDb;
 }
 
+/** 按游戏作用域取库：优先该游戏插件注册时绑定的 Host 库，回退到全局活跃库 */
+function databaseForGame(gameId: string): GameRecordDb | null {
+  return gameDatabases.get(gameId) ?? activeDatabase();
+}
+
+/**
+ * 由 registerRuntimeGame 在游戏注册时调用：把游戏绑定到当前插件刚通过 initGameRecordHost 注册的战绩库。
+ * 返回解绑函数（随游戏注销一并解绑）。
+ */
+export function bindGameRecordDatabase(gameId: string): () => void {
+  const db = latestHostDatabase;
+  if (!db) return () => {};
+  gameDatabases.set(gameId, db);
+  return () => {
+    if (gameDatabases.get(gameId) === db) gameDatabases.delete(gameId);
+  };
+}
+
 function getRecordModel(database: GameRecordDb): RelatedModel<unknown, Models, 'game_records'> {
   const model = database.models.get('game_records');
   if (!model) throw new Error('game_records not registered');
@@ -93,6 +114,7 @@ export function initGameRecordHost(host: GameRecordDatabaseHost): () => void {
     database = createHostGameDb(host, ['game_records']) as unknown as GameRecordDb;
     hostDatabases.set(host, database);
   }
+  latestHostDatabase = database;
   const registration = Object.freeze({ host, database });
   hostRegistrations.push(registration);
   return () => {
@@ -107,12 +129,12 @@ function recordId(): string {
 
 /** 对局结束时写入战绩（database 未就绪时静默跳过） */
 export async function recordGameOutcome(
-  message: Message,
+  message: GameMessageLike,
   gameId: string,
   result: GameRecordResult,
   score = 0,
 ): Promise<void> {
-  const db = activeDatabase();
+  const db = databaseForGame(gameId);
   if (!db) return;
   const row: GameRecordRow = {
     id: recordId(),
@@ -182,7 +204,7 @@ export async function getGameLeaderboard(
   channelKeyFilter: string,
   limit = 10,
 ): Promise<LeaderboardEntry[]> {
-  const db = activeDatabase();
+  const db = databaseForGame(gameId);
   if (!db) return [];
   const rows = await getRecordModel(db).findAll({
     game_id: gameId,
@@ -210,80 +232,11 @@ export async function getGameLeaderboard(
     .slice(0, limit);
 }
 
-function gameTitle(gameId: string): string {
-  const g = getRegisteredGame(gameId);
-  return g ? `${g.icon} ${g.title}` : gameId;
-}
-
-function formatUserStats(stats: UserGameStats[]): string {
-  if (!stats.length) return '暂无战绩记录，快去 `/游戏` 开一局吧！';
-  const lines = stats.map((s) => {
-    const title = gameTitle(s.gameId);
-    return `• ${title}：${s.wins} 胜 ${s.losses} 负${s.draws ? ` ${s.draws} 平` : ''}（${s.games} 局，得分 ${s.totalScore}）`;
-  });
-  return ['📊 **你的战绩**', '', ...lines].join('\n');
-}
-
-function formatLeaderboard(gameId: string, entries: LeaderboardEntry[]): string {
-  const title = gameTitle(gameId);
-  if (!entries.length) {
-    return `${title} 在本群暂无排行，发送 \`/游戏\` 开始第一局！`;
-  }
-  const lines = entries.map((e, i) =>
-    `${i + 1}. ${e.userName} — ${e.wins} 胜 / ${e.games} 局（得分 ${e.totalScore}）`,
-  );
-  return [`🏆 **${title} 本群排行**`, '', ...lines].join('\n');
-}
-
-export function mountGameRecordCommands(root: Plugin): () => void {
-  const disposers: (() => void)[] = [];
-
-  disposers.push(
-    root.addCommand(
-      new MessageCommand('/战绩')
-        .desc('查看本人在本群的游戏战绩')
-        .action(async (message) => {
-          const stats = await getUserGameStats(message.$sender.id, channelKey(message));
-          return formatUserStats(stats);
-        }),
-    ),
-    root.addCommand(
-      new MessageCommand('/排行')
-        .desc('查看本群某游戏排行榜')
-        .action(async (message, ...args) => {
-          const query = args.join(' ').trim();
-          const games = getRegisteredGames();
-          if (!games.length) return '暂无已注册游戏。';
-          const firstGame = games[0];
-          if (!firstGame) return '暂无已注册游戏。';
-          let gameId = firstGame.id;
-          if (query) {
-            const hit = games.find(
-              (g) => g.id === query
-                || g.title.includes(query)
-                || g.commandPrefix.includes(query)
-                || g.aliases?.some((a) => a.includes(query)),
-            );
-            if (!hit) {
-              const names = games.map((g) => g.title).join('、');
-              return `未找到游戏「${query}」。可选：${names}`;
-            }
-            gameId = hit.id;
-          }
-          const board = await getGameLeaderboard(gameId, channelKey(message));
-          return formatLeaderboard(gameId, board);
-        }),
-    ),
-  );
-
-  return () => {
-    for (const d of disposers) d();
-  };
-}
-
 /** 测试专用 */
 export function resetGameRecordsForTests(): void {
   legacyDb = null;
   hostDatabases = new WeakMap();
   hostRegistrations.splice(0);
+  gameDatabases.clear();
+  latestHostDatabase = null;
 }

package/src/game-session.ts

@@ -1,97 +1,15 @@
-/**
- * 通用游戏会话接口
- * 定义回合制游戏的基础会话结构
- */
-import type { Message } from '@zhin.js/core';
 import { generateCompactId } from './random.js';
 
-/** 会话状态 */
-export type GameStatus = 'active' | 'won' | 'draw' | 'aborted';
-
-/** 通用游戏会话接口 */
-export interface GameSession {
-  /** 会话 ID */
-  id: string;
-  /** 适配器名称 */
-  adapter: string;
-  /** Endpoint 名称 */
-  endpoint: string;
-  /** 频道类型 */
-  channel_type: 'private' | 'group' | 'channel';
-  /** 频道 ID */
-  channel_id: string;
-  /** 频道唯一键 */
-  channel_key: string;
-  /** 棋盘消息 ID（用于编辑） */
-  board_message_id: string;
-  /** 当前状态 */
-  status: GameStatus;
-  /** 更新时间戳 */
-  updated_at: number;
-  /** 创建时间戳 */
-  created_at: number;
-}
-
-/** 回合制游戏会话（2 人对战） */
-export interface TurnBasedSession extends GameSession {
-  /** 玩家 1 ID */
-  player_1: string;
-  /** 玩家 2 ID */
-  player_2: string;
-  /** 玩家 1 显示名 */
-  player_1_name: string;
-  /** 玩家 2 显示名 */
-  player_2_name: string;
-  /** 当前回合（1 或 2） */
-  turn: 1 | 2;
-  /** 胜者（0=无，1=玩家1，2=玩家2） */
-  winner: 0 | 1 | 2;
-  /** 步数 */
-  move_count: number;
-}
-
 /** 生成会话 ID */
 export function generateSessionId(): string {
   return generateCompactId('s');
 }
 
-/** 获取当前回合玩家 ID */
-export function currentPlayerId(session: TurnBasedSession): string {
-  return session.turn === 1 ? session.player_1 : session.player_2;
-}
-
-/** 判断用户是否为本局玩家 */
-export function isPlayer(session: TurnBasedSession, userId: string): boolean {
-  return session.player_1 === userId || session.player_2 === userId;
-}
-
-/** 判断是否轮到该用户 */
-export function isPlayerTurn(session: TurnBasedSession, userId: string): boolean {
-  return currentPlayerId(session) === userId;
-}
-
-/** 获取玩家编号（1 或 2），非玩家返回 null */
-export function playerNumber(session: TurnBasedSession, userId: string): 1 | 2 | null {
-  if (session.player_1 === userId) return 1;
-  if (session.player_2 === userId) return 2;
-  return null;
-}
-
-/** 切换回合 */
-export function nextTurn(current: 1 | 2): 1 | 2 {
-  return current === 1 ? 2 : 1;
-}
-
-/** 从 Message 提取发送者显示名 */
-export function senderDisplayName(message: Message): string {
-  const name = message.$sender.name?.trim();
-  return name || message.$sender.id;
-}
-
 /** 比对出站 board_message_id 与平台回调 messageId（含 composite id） */
 export function boardMessageMatches(stored: string, messageId: string): boolean {
   if (!stored || !messageId) return false;
   if (stored === messageId || stored.endsWith(`:${messageId}`)) return true;
   const tail = stored.split(':').pop();
-  return !!(tail && messageId.endsWith(tail));
+  // 尾段匹配要求全等或以 `:tail` 结尾（段边界），避免 x99912345 误中 12345
+  return !!tail && (messageId === tail || messageId.endsWith(`:${tail}`));
 }

package/src/grid-keyboard.ts

@@ -138,7 +138,8 @@ export function buildGridKeyboard<T>(options: GridKeyboardOptions<T>): SendConte
         );
       }),
     );
-    Object.assign(fallback, buildChoiceFallbackMap(gamePrefix, sessionId, postChoices));
+    // postChoices 编号从可落子格子数后续起，避免覆盖格子数字映射
+    Object.assign(fallback, buildChoiceFallbackMap(gamePrefix, sessionId, postChoices, Object.keys(fallback).length + 1));
   }
 
   const parts = [

package/src/index.ts

@@ -8,19 +8,16 @@ export * from './grid-keyboard.js';
 export * from './choice-keyboard.js';
 export * from './board-sender.js';
 export * from './game-session.js';
-export * from './game-hub-feature.js';
-export * from './game-hub-menu.js';
-export * from './game-hub-menu-context.js';
-export * from './game-hub-flow.js';
-export * from './game-hub-mount.js';
-export * from './game-middleware.js';
+export * from './base-session-service.js';
+export * from './versioned-session-service.js';
+export * from './deterministic-random.js';
+export * from './game-events.js';
+export * from './session-coordinator.js';
+export * from './define-game-plugin.js';
 export * from './game-action-alias.js';
-export * from './game-commands.js';
 export * from './game-interactive.js';
 export * from './interaction-profiles.js';
 export * from './game-records.js';
-export * from './game-onboarding.js';
-export * from './command-help.js';
 export * from './command-message.js';
 export * from './memory-db.js';
 export * from './send-content-text.js';

package/src/memory-db.ts

@@ -24,8 +24,13 @@ function createMemoryModel(): InMemoryGameModel {
     Object.entries(q).every(([k, v]) => row[k] === v);
 
   return {
-    findAll: async (q: Record<string, unknown> = {}) => rows.filter((row) => match(row, q)),
-    findOne: async (q: Record<string, unknown> = {}) => rows.find((row) => match(row, q)) ?? null,
+    // 返回行拷贝，避免调用方直接改字段绕过 updateWhere
+    findAll: async (q: Record<string, unknown> = {}) =>
+      rows.filter((row) => match(row, q)).map((row) => ({ ...row })),
+    findOne: async (q: Record<string, unknown> = {}) => {
+      const found = rows.find((row) => match(row, q));
+      return found ? { ...found } : null;
+    },
     create: async (row: Row) => {
       rows.push({ ...row });
       return row;
@@ -67,6 +72,18 @@ export function createInMemoryGameDb(tableNames: readonly string[]): InMemoryGam
   };
 }
 
+/**
+ * Typed boundary used by game tests and standalone embedders. The database
+ * implementation is deliberately structural so game packages keep their
+ * precise model types without each package recreating the same adapter.
+ */
+export function createMemoryGameServices<TDatabase, TServices>(
+  tableNames: readonly string[],
+  factory: (database: TDatabase) => TServices,
+): TServices {
+  return factory(createInMemoryGameDb(tableNames) as unknown as TDatabase);
+}
+
 /** Minimal DatabaseHost model surface (structural typing; no plugin-runtime dep). */
 export interface HostGameModelSource {
   select(): {

package/src/runtime-hub.ts

@@ -2,6 +2,8 @@
  * Plugin Runtime game hub — module-level registry (no legacy Feature / getPlugin).
  * Games call `registerRuntimeGame` from `setup()`; hub plugin lists them.
  */
+import { bindGameRecordDatabase } from './game-records.js';
+
 export interface RuntimeGameMenuAction {
   readonly id: string;
   readonly label: string;
@@ -25,7 +27,10 @@ export function registerRuntimeGame(game: RuntimeRegisteredGame): () => void {
   const registrations = games.get(game.id) ?? [];
   registrations.push(registered);
   games.set(game.id, registrations);
+  // 把游戏绑定到其插件刚注册的战绩库（按 Host/插件作用域取库）
+  const unbindRecords = bindGameRecordDatabase(game.id);
   return () => {
+    unbindRecords();
     const current = games.get(game.id);
     if (!current) return;
     const index = current.lastIndexOf(registered);

package/src/session-coordinator.ts

@@ -0,0 +1,74 @@
+export interface ActiveGameSession {
+  readonly id: string;
+  readonly channel_key: string;
+}
+
+export interface GameSessionProvider {
+  readonly gameId: string;
+  getActiveForUser(channelKey: string, userId: string): Promise<ActiveGameSession | null>;
+}
+
+export class GameSessionConflictError extends Error {
+  constructor(
+    readonly requestedGameId: string,
+    readonly activeGameId: string,
+    readonly sessionId: string,
+    readonly userId: string,
+  ) {
+    super(
+      `你在当前频道已有进行中的「${activeGameId}」对局，`
+      + `请先结束它，再开始「${requestedGameId}」。`,
+    );
+    this.name = 'GameSessionConflictError';
+  }
+}
+
+/**
+ * Cross-game active-session index. Registrations form per-game stacks so HMR
+ * can install a new generation before disposing the old one without a gap.
+ */
+export class GameSessionCoordinator {
+  readonly #providers = new Map<string, GameSessionProvider[]>();
+
+  register(provider: GameSessionProvider): () => void {
+    const providers = this.#providers.get(provider.gameId) ?? [];
+    providers.push(provider);
+    this.#providers.set(provider.gameId, providers);
+    return () => {
+      const current = this.#providers.get(provider.gameId);
+      if (!current) return;
+      const index = current.lastIndexOf(provider);
+      if (index >= 0) current.splice(index, 1);
+      if (current.length === 0) this.#providers.delete(provider.gameId);
+    };
+  }
+
+  async assertAvailable(
+    requestedGameId: string,
+    channelKey: string,
+    userIds: readonly string[],
+  ): Promise<void> {
+    for (const [gameId, registrations] of this.#providers) {
+      if (gameId === requestedGameId) continue;
+      const provider = registrations[registrations.length - 1];
+      if (!provider) continue;
+      for (const userId of new Set(userIds.filter(Boolean))) {
+        const active = await provider.getActiveForUser(channelKey, userId);
+        if (active) {
+          throw new GameSessionConflictError(
+            requestedGameId,
+            gameId,
+            active.id,
+            userId,
+          );
+        }
+      }
+    }
+  }
+
+  clear(): void {
+    this.#providers.clear();
+  }
+}
+
+export const gameSessionCoordinator = new GameSessionCoordinator();