@zhin.js/game-kit 1.0.2 → 2.0.1

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);
 }

package/src/game-hub-feature.ts

@@ -1,10 +1,10 @@
-import { Feature, getPlugin, type FeatureJSON, type Plugin, type PluginLike, type DatabaseFeature } from '@zhin.js/core';
+import { Feature, getPlugin, type FeatureJSON, type Message, type Plugin, type PluginLike, type DatabaseFeature } from '@zhin.js/core';
 import { mountGameHubUi, markGameHubUiMounted } from './game-hub-mount.js';
 import { registerGameRecordModels, initGameRecordDatabase } from './game-records.js';
 
 export interface GameHubContext {
   plugin: Plugin;
-  message: import('zhin.js').Message<any>;
+  message: Message;
 }
 
 export interface GameMenuAction {
@@ -42,6 +42,10 @@ declare module '@zhin.js/core' {
 
 let activeFeature: GameHubFeature | null = null;
 
+function setActiveFeature(feature: GameHubFeature | null): void {
+  activeFeature = feature;
+}
+
 export class GameHubFeature extends Feature<RegisteredGame> {
   readonly name = 'game' as const;
   readonly icon = 'Gamepad2';
@@ -84,13 +88,12 @@ export class GameHubFeature extends Feature<RegisteredGame> {
   }
 
   get extensions() {
-    const feature = this;
     return {
-      registerGame(game: RegisteredGame) {
+      registerGame: (game: RegisteredGame) => {
         const plugin = getPlugin();
         ensureGameHubService(plugin);
-        const dispose = feature.register(game, plugin.name);
-        plugin.recordFeatureContribution(feature.name, game.id);
+        const dispose = this.register(game, plugin.name);
+        plugin.recordFeatureContribution(this.name, game.id);
         plugin.onDispose(dispose);
         return dispose;
       },
@@ -98,7 +101,7 @@ export class GameHubFeature extends Feature<RegisteredGame> {
   }
 
   mounted(plugin: PluginLike): void {
-    activeFeature = this;
+    setActiveFeature(this);
     const root = plugin as Plugin;
     const host = root.root ?? root;
     registerGameRecordModels(host);
@@ -117,7 +120,7 @@ export class GameHubFeature extends Feature<RegisteredGame> {
     for (const d of this.hubDisposers) d();
     this.hubDisposers = [];
     if (activeFeature === this) {
-      activeFeature = null;
+      setActiveFeature(null);
     }
   }
 }
@@ -133,7 +136,7 @@ export function ensureGameHubService(plugin: Plugin): GameHubFeature {
 
   const feature = new GameHubFeature();
   root.provide(feature);
-  activeFeature = feature;
+  setActiveFeature(feature);
 
   if (root.started && feature.mounted) {
     feature.mounted(root);

package/src/game-hub-flow.ts

@@ -42,7 +42,7 @@ function gameMenuChoices(gameId: string, channelType: string): HubMenuChoice[] {
   ];
 }
 
-export function openMainMenu(message: Message<any>): ReturnType<typeof buildMainHubMenu> | string {
+export function openMainMenu(message: Message): ReturnType<typeof buildMainHubMenu> | string {
   const games = getRegisteredGames();
   if (!games.length) {
     return formatHubEmptyMessage();
@@ -55,7 +55,7 @@ export function openMainMenu(message: Message<any>): ReturnType<typeof buildMain
 
 export async function handleHubChoice(
   plugin: Plugin,
-  message: Message<any>,
+  message: Message,
   scopeId: string,
   choiceId: string,
 ): Promise<boolean> {

package/src/game-hub-menu-context.ts

@@ -6,7 +6,7 @@ export interface HubMenuContext {
   channelKey: string;
   /** 打开菜单的用户（仅记录，大厅导航不限制点击者） */
   openerId: string;
-  message: Message<any>;
+  message: Message;
   expiresAt: number;
 }
 
@@ -27,11 +27,11 @@ const contexts = new Map<string, HubMenuContext>();
 const lastMenus = new Map<string, LastHubMenu>();
 
 /** 大厅 fallback 按频道共享，任意成员可回复数字或点按钮 */
-function hubMenuKey(message: Message<any>): string {
+function hubMenuKey(message: Message): string {
   return channelKey(message);
 }
 
-export function createHubScope(message: Message<any>): string {
+export function createHubScope(message: Message): string {
   const scopeId = generateCompactId('h');
   contexts.set(scopeId, {
     channelKey: channelKey(message),
@@ -44,7 +44,7 @@ export function createHubScope(message: Message<any>): string {
 }
 
 export function rememberHubMenu(
-  message: Message<any>,
+  message: Message,
   scopeId: string,
   choices: HubMenuChoice[],
 ): void {
@@ -56,7 +56,7 @@ export function rememberHubMenu(
   pruneExpired();
 }
 
-export function getLastHubMenu(message: Message<any>): LastHubMenu | null {
+export function getLastHubMenu(message: Message): LastHubMenu | null {
   pruneExpired();
   const key = hubMenuKey(message);
   const last = lastMenus.get(key);

package/src/game-hub-mount.ts

@@ -2,17 +2,14 @@ import {
   Message,
   MessageCommand,
   getActionFromMessage,
-  resolvePayloadFromText,
   type Plugin,
 } from '@zhin.js/core';
-import { buildChoiceFallbackMap, parseChoicePayload } from './choice-keyboard.js';
 import {
   formatHubEmptyMessage,
   buildBotHelpReply,
   buildHubHelpReply,
   HUB_PREFIX,
 } from './game-hub-menu.js';
-import { getLastHubMenu } from './game-hub-menu-context.js';
 import { handleHubChoice, openMainMenu, parseHubPayload } from './game-hub-flow.js';
 import { getRegisteredGames } from './game-hub-feature.js';
 import { mountGameRecordCommands } from './game-records.js';
@@ -24,17 +21,21 @@ function resolveRegisteredCommands(root: Plugin): MessageCommand[] {
   return commandService?.items ?? [];
 }
 
-async function resolveHelpCommands(root: Plugin, message: Message<any>): Promise<CommandHelpSource[]> {
+async function resolveHelpCommands(root: Plugin, message: Message): Promise<CommandHelpSource[]> {
   return filterHelpCommands(resolveRegisteredCommands(root), message, root);
 }
 
 /**
  * 在 root 上挂载「游戏 / game」大厅命令，返回 dispose 列表。
+ *
+ * @deprecated 仅 classic `GameHubFeature` / `bootstrapNode` 路径。
+ * Plugin Runtime 请用 `@zhin.js/plugin-game-hub` 的 `commands/games/`（defineCommand）。
+ * 勿在新代码调用；随 classic Feature 退役。
  */
 export function mountGameHubUi(root: Plugin): (() => void)[] {
   const disposers: (() => void)[] = [];
 
-  const openHandler = async (message: Message<any>) => {
+  const openHandler = async (message: Message) => {
     const games = getRegisteredGames();
     if (!games.length) {
       return formatHubEmptyMessage();
@@ -111,43 +112,17 @@ export function mountGameHubUi(root: Plugin): (() => void)[] {
   disposers.push(mountGameRecordCommands(root));
   disposers.push(mountFirstAtHintMiddleware(root));
 
+  // interactive 回跳由框架中央执行（`registerInteractiveHandler` 安装的根
+  // 中间件）：action 段、数字 fallback（中央存储的菜单映射）与 QQ 指令预填
+  // 直出 payload 都路由到下面的 hub handler，不再自行解析文本。
   root.registerInteractiveHandler(`${HUB_PREFIX}:`, (message) =>
     handleHubInteractive(root, message),
   );
 
-  disposers.push(
-    root.addMiddleware(async (message, next) => {
-      const action = getActionFromMessage(message);
-      if (action?.payload.startsWith(`${HUB_PREFIX}:`)) return next();
-
-      const raw = message.$raw?.trim() ?? '';
-
-      // QQ 指令预填等：payload 自包含 hub:scope:choice，不依赖 opener 的菜单缓存
-      const directPayload = resolvePayloadFromText(raw);
-      if (directPayload?.startsWith(`${HUB_PREFIX}:`)) {
-        const direct = parseChoicePayload(directPayload, HUB_PREFIX);
-        if (direct) {
-          await handleHubChoice(root, message, direct.sessionId, direct.choiceId);
-          return;
-        }
-      }
-
-      const last = getLastHubMenu(message);
-      if (!last) return next();
-
-      const map = buildChoiceFallbackMap(HUB_PREFIX, last.scopeId, last.choices);
-      const payload = resolvePayloadFromText(raw, map);
-      const parsed = payload ? parseChoicePayload(payload, HUB_PREFIX) : null;
-      if (!parsed || parsed.sessionId !== last.scopeId) return next();
-
-      await handleHubChoice(root, message, parsed.sessionId, parsed.choiceId);
-    }),
-  );
-
   return disposers;
 }
 
-async function handleHubInteractive(root: Plugin, message: Message<any>): Promise<boolean> {
+async function handleHubInteractive(root: Plugin, message: Message): Promise<boolean> {
   const action = getActionFromMessage(message);
   if (!action) return false;
 

package/src/game-interactive.ts

@@ -28,7 +28,7 @@ export interface GameSessionRef {
 }
 
 export interface ResolveGameChoiceOptions {
-  message: Message<any>;
+  message: Message;
   gamePrefix: string;
   validChoiceIds: readonly string[];
   getById: (sessionId: string) => Promise<GameSessionRef | null>;

package/src/game-onboarding.ts

@@ -1,10 +1,12 @@
 import { getActionFromMessage, type Message, type Plugin } from '@zhin.js/core';
 
+type BotAwareMessage = Message<{ readonly $bot?: { readonly id?: string } }>;
+
 const hintedChannels = new Set<string>();
 const TTL_MS = 24 * 60 * 60 * 1000;
 const channelHintAt = new Map<string, number>();
 
-function channelHintKey(message: Message<any>): string {
+function channelHintKey(message: Message): string {
   return `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
 }
 
@@ -18,7 +20,7 @@ function pruneHintCache(): void {
   }
 }
 
-function messageMentionsBot(message: Message<any>): boolean {
+function messageMentionsBot(message: BotAwareMessage): boolean {
   const raw = message.$raw ?? '';
   if (/@(?:everyone|all)/i.test(raw)) return false;
   const botId = message.$bot?.id;
@@ -56,6 +58,8 @@ export function mountFirstAtHintMiddleware(root: Plugin): () => void {
     hintedChannels.add(key);
     channelHintAt.set(key, Date.now());
 
+    await message.$reply?.('发送「游戏」查看游戏列表，发送「帮助」查看可用命令');
+
     return next();
   });
 }

package/src/game-records.ts

@@ -2,12 +2,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 type { GameMessageLike } from './command-message.js';
 import { getRegisteredGame, getRegisteredGames } from './game-hub-feature.js';
 import { createHostGameDb, type HostGameDbSource } from './memory-db.js';
 import { generateCompactId } from './random.js';
@@ -39,10 +39,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 +116,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 +131,12 @@ function recordId(): string {
 
 /** 对局结束时写入战绩（database 未就绪时静默跳过） */
 export async function recordGameOutcome(
-  message: Message<any>,
+  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 +206,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,
@@ -254,7 +278,9 @@ export function mountGameRecordCommands(root: Plugin): () => void {
           const query = args.join(' ').trim();
           const games = getRegisteredGames();
           if (!games.length) return '暂无已注册游戏。';
-          let gameId = games[0]!.id;
+          const firstGame = games[0];
+          if (!firstGame) return '暂无已注册游戏。';
+          let gameId = firstGame.id;
           if (query) {
             const hit = games.find(
               (g) => g.id === query
@@ -284,4 +310,6 @@ export function resetGameRecordsForTests(): void {
   legacyDb = null;
   hostDatabases = new WeakMap();
   hostRegistrations.splice(0);
+  gameDatabases.clear();
+  latestHostDatabase = null;
 }

package/src/game-session.ts

@@ -83,7 +83,7 @@ export function nextTurn(current: 1 | 2): 1 | 2 {
 }
 
 /** 从 Message 提取发送者显示名 */
-export function senderDisplayName(message: Message<any>): string {
+export function senderDisplayName(message: Message): string {
   const name = message.$sender.name?.trim();
   return name || message.$sender.id;
 }
@@ -93,5 +93,6 @@ 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

@@ -60,7 +60,8 @@ export function buildGridFallbackMap(
   const map: Record<string, string> = {};
   let n = 1;
   for (let i = 0; i < cells.length; i++) {
-    if (!cells[i]!.disabled) {
+    const cell = cells[i];
+    if (cell && !cell.disabled) {
       map[String(n)] = `${gamePrefix}:${sessionId}:${i}`;
       n++;
     }
@@ -95,7 +96,10 @@ export function buildGridKeyboard<T>(options: GridKeyboardOptions<T>): SendConte
     const row: ReturnType<typeof segment.button>[] = [];
     for (let c = 0; c < cols; c++) {
       const i = r * cols + c;
-      const cell = cells[i]!;
+      const cell = cells[i];
+      if (!cell) {
+        throw new RangeError(`Missing grid cell at index ${i}`);
+      }
       row.push(
         segment.button({
           id: `c${i}`,
@@ -134,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 = [
@@ -161,11 +166,12 @@ export function parseGridPayload(
 ): { prefix: string; sessionId: string; cell: number } | null {
   const m = /^([a-z0-9_]+):([^:]+):(\d+)$/i.exec(payload);
   if (!m) return null;
-  const prefix = m[1]!;
+  const [, prefix, sessionId, rawCell] = m;
+  if (!prefix || !sessionId || rawCell === undefined) return null;
   if (expectedPrefix && prefix !== expectedPrefix) return null;
-  const cell = Number(m[3]);
+  const cell = Number(rawCell);
   if (!Number.isInteger(cell) || cell < 0) return null;
-  return { prefix, sessionId: m[2]!, cell };
+  return { prefix, sessionId, cell };
 }
 
 /**
@@ -174,7 +180,9 @@ export function parseGridPayload(
 export function parseCellButtonId(value: string): number | null {
   const m = /^c(\d+)$/.exec(value);
   if (!m) return null;
-  const cell = Number(m[1]);
+  const rawCell = m[1];
+  if (rawCell === undefined) return null;
+  const cell = Number(rawCell);
   if (!Number.isInteger(cell) || cell < 0) return null;
   return cell;
 }

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;
@@ -43,7 +48,8 @@ function createMemoryModel(): InMemoryGameModel {
     deleteWhere: async (where: Record<string, unknown>) => {
       let n = 0;
       for (let i = rows.length - 1; i >= 0; i -= 1) {
-        if (match(rows[i]!, where)) {
+        const row = rows[i];
+        if (row && match(row, where)) {
           rows.splice(i, 1);
           n += 1;
         }
@@ -69,7 +75,8 @@ export function createInMemoryGameDb(tableNames: readonly string[]): InMemoryGam
 /** Minimal DatabaseHost model surface (structural typing; no plugin-runtime dep). */
 export interface HostGameModelSource {
   select(): {
-    where(query: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    // DatabaseHostSelection is a thenable, not an instance of Promise; accept both.
+    where(query: Record<string, unknown>): PromiseLike<Record<string, unknown>[]>;
   };
   insert(row: Record<string, unknown>): Promise<unknown>;
   delete(): { where(query: Record<string, unknown>): Promise<unknown> };

package/src/random.ts

@@ -16,17 +16,25 @@ export function secureRandomIntInclusive(min: number, max: number): number {
 
 export function secureRandomItem<T>(items: readonly T[]): T {
   if (items.length === 0) throw new RangeError('cannot choose from an empty array');
-  return items[secureRandomInt(items.length)]!;
+  return itemAt(items, secureRandomInt(items.length));
 }
 
 export function secureShuffleInPlace<T>(items: T[]): T[] {
   for (let i = items.length - 1; i > 0; i--) {
     const j = secureRandomInt(i + 1);
-    [items[i], items[j]] = [items[j]!, items[i]!];
+    const current = itemAt(items, i);
+    const selected = itemAt(items, j);
+    items[i] = selected;
+    items[j] = current;
   }
   return items;
 }
 
+function itemAt<T>(items: readonly T[], index: number): T {
+  if (!(index in items)) throw new RangeError(`missing array item at index ${index}`);
+  return items[index] as T;
+}
+
 export function generateCompactId(prefix: string): string {
   return `${prefix}${Date.now().toString(36)}${randomUUID().replaceAll('-', '').slice(0, 8)}`;
 }

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);