@zhin.js/game-kit 1.0.1

package/src/game-hub-mount.ts

@@ -0,0 +1,172 @@
+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';
+import { mountFirstAtHintMiddleware } from './game-onboarding.js';
+import { filterHelpCommands, type CommandHelpSource } from './command-help.js';
+
+function resolveRegisteredCommands(root: Plugin): MessageCommand[] {
+  const commandService = root.inject('command') as { items?: MessageCommand[] } | undefined;
+  return commandService?.items ?? [];
+}
+
+async function resolveHelpCommands(root: Plugin, message: Message<any>): Promise<CommandHelpSource[]> {
+  return filterHelpCommands(resolveRegisteredCommands(root), message, root);
+}
+
+/**
+ * 在 root 上挂载「游戏 / game」大厅命令，返回 dispose 列表。
+ */
+export function mountGameHubUi(root: Plugin): (() => void)[] {
+  const disposers: (() => void)[] = [];
+
+  const openHandler = async (message: Message<any>) => {
+    const games = getRegisteredGames();
+    if (!games.length) {
+      return formatHubEmptyMessage();
+    }
+    const menu = openMainMenu(message);
+    if (typeof menu === 'string') return menu;
+    await message.$reply?.(menu);
+    return undefined;
+  };
+
+  disposers.push(
+    root.addCommand(
+      new MessageCommand('/游戏')
+        .desc('游戏大厅：选择游戏并开始')
+        .action(openHandler),
+    ),
+    root.addCommand(
+      new MessageCommand('/game')
+        .desc('Game lobby (English alias)')
+        .action(openHandler),
+    ),
+    root.addCommand(
+      new MessageCommand('游戏')
+        .desc('游戏大厅（无斜杠兼容）')
+        .action(openHandler),
+    ),
+    root.addCommand(
+      new MessageCommand('game')
+        .desc('Game lobby (legacy alias)')
+        .action(openHandler),
+    ),
+  );
+
+  disposers.push(
+    root.addCommand(
+      new MessageCommand('/游戏 帮助')
+        .desc('游戏大厅帮助')
+        .action(async (message) =>
+          buildHubHelpReply(getRegisteredGames(), await resolveHelpCommands(root, message)),
+        ),
+    ),
+    root.addCommand(
+      new MessageCommand('/帮助')
+        .desc('机器人帮助：游戏列表与 QQ 群用法')
+        .action(async (message) =>
+          buildBotHelpReply(getRegisteredGames(), {
+            channelType: message.$channel.type,
+            commands: await resolveHelpCommands(root, message),
+          }),
+        ),
+    ),
+    root.addCommand(
+      new MessageCommand('/help')
+        .desc('Bot help (English alias)')
+        .action(async (message) =>
+          buildBotHelpReply(getRegisteredGames(), {
+            channelType: message.$channel.type,
+            commands: await resolveHelpCommands(root, message),
+          }),
+        ),
+    ),
+    root.addCommand(
+      new MessageCommand('帮助')
+        .desc('帮助（无斜杠兼容）')
+        .action(async (message) =>
+          buildBotHelpReply(getRegisteredGames(), {
+            channelType: message.$channel.type,
+            commands: await resolveHelpCommands(root, message),
+          }),
+        ),
+    ),
+  );
+
+  disposers.push(mountGameRecordCommands(root));
+  disposers.push(mountFirstAtHintMiddleware(root));
+
+  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> {
+  const action = getActionFromMessage(message);
+  if (!action) return false;
+
+  const fromPayload = parseHubPayload(action.payload);
+  if (!fromPayload) return false;
+
+  return handleHubChoice(root, message, fromPayload.scopeId, fromPayload.choiceId);
+}
+
+let hubUiMounted = false;
+
+export function isGameHubMounted(): boolean {
+  return hubUiMounted;
+}
+
+export function markGameHubUiMounted(): void {
+  hubUiMounted = true;
+}
+
+export function resetGameHubMountForTests(): void {
+  hubUiMounted = false;
+}

package/src/game-interactive.ts

@@ -0,0 +1,88 @@
+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_');
+}
+
+/** 从 QQ 指令预填 / 数字 fallback 解析游戏 payload */
+export function resolveGameTextPayload(
+  raw: string,
+  map?: Record<string, string>,
+): string | undefined {
+  return resolvePayloadFromText(raw, map);
+}
+
+export interface GameSessionRef {
+  id: string;
+  channel_key: string;
+}
+
+export interface ResolveGameChoiceOptions {
+  message: Message<any>;
+  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-middleware.ts

@@ -0,0 +1,14 @@
+import type { MessageMiddleware, Plugin, RegisteredAdapter } from '@zhin.js/core';
+
+/**
+ * 在 root 插件上注册游戏文本中间件（入站管线只走 root.middleware）。
+ */
+export function registerGameTextMiddleware(
+  plugin: Plugin,
+  middleware: MessageMiddleware<RegisteredAdapter>,
+  name?: string,
+): () => void {
+  const dispose = plugin.root.addMiddleware(middleware, name);
+  plugin.onDispose(dispose);
+  return dispose;
+}

package/src/game-onboarding.ts

@@ -0,0 +1,67 @@
+import { getActionFromMessage, type Message, type Plugin } from '@zhin.js/core';
+
+const hintedChannels = new Set<string>();
+const TTL_MS = 24 * 60 * 60 * 1000;
+const channelHintAt = new Map<string, number>();
+
+function channelHintKey(message: Message<any>): string {
+  return `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+}
+
+function pruneHintCache(): void {
+  const now = Date.now();
+  for (const [key, at] of channelHintAt) {
+    if (now - at > TTL_MS) {
+      channelHintAt.delete(key);
+      hintedChannels.delete(key);
+    }
+  }
+}
+
+function messageMentionsBot(message: Message<any>): boolean {
+  const raw = message.$raw ?? '';
+  if (/@(?:everyone|all)/i.test(raw)) return false;
+  const botId = message.$bot?.id;
+  if (botId && raw.includes(String(botId))) return true;
+  for (const item of message.$content ?? []) {
+    if (typeof item === 'string') continue;
+    if (item.type === 'at' && (!item.data.user_id || item.data.user_id === botId || item.data.user_id === 'all')) {
+      if (item.data.user_id !== 'all') return true;
+    }
+  }
+  return false;
+}
+
+function looksLikeCommand(raw: string): boolean {
+  const t = raw.trim();
+  return t.startsWith('/') || /^(游戏|game|帮助|help|签到|stats)\b/i.test(t);
+}
+
+/**
+ * 群聊首次 @ 且非命令时提示 /游戏 /帮助（每频道 24h 最多一次）
+ */
+export function mountFirstAtHintMiddleware(root: Plugin): () => void {
+  return root.addMiddleware(async (message, next) => {
+    if (message.$channel.type !== 'group') return next();
+    if (getActionFromMessage(message)) return next();
+    if (!messageMentionsBot(message)) return next();
+
+    const raw = message.$raw?.trim() ?? '';
+    if (looksLikeCommand(raw)) return next();
+
+    pruneHintCache();
+    const key = channelHintKey(message);
+    if (hintedChannels.has(key)) return next();
+
+    hintedChannels.add(key);
+    channelHintAt.set(key, Date.now());
+
+    return next();
+  });
+}
+
+/** 测试专用 */
+export function resetOnboardingForTests(): void {
+  hintedChannels.clear();
+  channelHintAt.clear();
+}

package/src/game-records.ts

@@ -0,0 +1,287 @@
+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 { createHostGameDb, type HostGameDbSource } from './memory-db.js';
+import { generateCompactId } from './random.js';
+
+export type GameRecordResult = 'won' | 'lost' | 'draw' | 'aborted';
+
+declare module '@zhin.js/core' {
+  interface Models {
+    game_records: {
+      id: string;
+      user_id: string;
+      user_name: string;
+      channel_key: string;
+      game_id: string;
+      result: GameRecordResult;
+      score: number;
+      created_at: number;
+    };
+  }
+}
+
+export type GameRecordRow = Models['game_records'];
+type GameRecordDb = Database<unknown, Models, string>;
+
+let legacyDb: GameRecordDb | null = null;
+let hostDatabases = new WeakMap<GameRecordDatabaseHost, GameRecordDb>();
+const hostRegistrations: Array<{
+  readonly host: GameRecordDatabaseHost;
+  readonly database: GameRecordDb;
+}> = [];
+
+function activeDatabase(): GameRecordDb | null {
+  return hostRegistrations[hostRegistrations.length - 1]?.database ?? legacyDb;
+}
+
+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');
+  return model as RelatedModel<unknown, Models, 'game_records'>;
+}
+
+export function registerGameRecordModels(plugin: Plugin): void {
+  plugin.defineModel('game_records', {
+    id: { type: 'text', primary: true },
+    user_id: { type: 'text', nullable: false },
+    user_name: { type: 'text', default: '' },
+    channel_key: { type: 'text', nullable: false },
+    game_id: { type: 'text', nullable: false },
+    result: { type: 'text', nullable: false },
+    score: { type: 'integer', default: 0 },
+    created_at: { type: 'integer', default: 0 },
+  });
+}
+
+export function initGameRecordDatabase(dbFeature: DatabaseFeature): void {
+  legacyDb = dbFeature.db as GameRecordDb;
+}
+
+const GAME_RECORDS_DEFINITION: Record<string, unknown> = {
+  id: { type: 'text', primary: true },
+  user_id: { type: 'text', nullable: false },
+  user_name: { type: 'text', default: '' },
+  channel_key: { type: 'text', nullable: false },
+  game_id: { type: 'text', nullable: false },
+  result: { type: 'text', nullable: false },
+  score: { type: 'integer', default: 0 },
+  created_at: { type: 'integer', default: 0 },
+};
+
+/** Plugin Runtime DatabaseHost 的最小结构（与 @zhin.js/plugin-runtime 的 DatabaseHost 结构对齐） */
+export interface GameRecordDatabaseHost extends HostGameDbSource {
+  define(name: string, definition: Record<string, unknown>): void;
+}
+
+/**
+ * Plugin Runtime 下用 databaseHostToken 初始化战绩库。
+ * 幂等：多个游戏插件 setup 都会调用，只建一次；无 token 时保持跳过（内存/静默）。
+ */
+export function initGameRecordHost(host: GameRecordDatabaseHost): () => void {
+  let database = hostDatabases.get(host);
+  if (!database) {
+    host.define('game_records', GAME_RECORDS_DEFINITION);
+    database = createHostGameDb(host, ['game_records']) as unknown as GameRecordDb;
+    hostDatabases.set(host, database);
+  }
+  const registration = Object.freeze({ host, database });
+  hostRegistrations.push(registration);
+  return () => {
+    const index = hostRegistrations.lastIndexOf(registration);
+    if (index >= 0) hostRegistrations.splice(index, 1);
+  };
+}
+
+function recordId(): string {
+  return generateCompactId('gr');
+}
+
+/** 对局结束时写入战绩（database 未就绪时静默跳过） */
+export async function recordGameOutcome(
+  message: Message<any>,
+  gameId: string,
+  result: GameRecordResult,
+  score = 0,
+): Promise<void> {
+  const db = activeDatabase();
+  if (!db) return;
+  const row: GameRecordRow = {
+    id: recordId(),
+    user_id: message.$sender.id,
+    user_name: String(message.$sender.name ?? message.$sender.id),
+    channel_key: channelKey(message),
+    game_id: gameId,
+    result,
+    score,
+    created_at: Date.now(),
+  };
+  await getRecordModel(db).create(row);
+}
+
+export interface UserGameStats {
+  gameId: string;
+  wins: number;
+  losses: number;
+  draws: number;
+  totalScore: number;
+  games: number;
+}
+
+export async function getUserGameStats(
+  userId: string,
+  channelKeyFilter?: string,
+): Promise<UserGameStats[]> {
+  const db = activeDatabase();
+  if (!db) return [];
+  const where = channelKeyFilter
+    ? { user_id: userId, channel_key: channelKeyFilter }
+    : { user_id: userId };
+  const rows = await getRecordModel(db).findAll(where);
+  const byGame = new Map<string, UserGameStats>();
+  for (const row of rows) {
+    let stat = byGame.get(row.game_id);
+    if (!stat) {
+      stat = {
+        gameId: row.game_id,
+        wins: 0,
+        losses: 0,
+        draws: 0,
+        totalScore: 0,
+        games: 0,
+      };
+      byGame.set(row.game_id, stat);
+    }
+    stat.games++;
+    stat.totalScore += row.score;
+    if (row.result === 'won') stat.wins++;
+    else if (row.result === 'lost') stat.losses++;
+    else if (row.result === 'draw') stat.draws++;
+  }
+  return [...byGame.values()].sort((a, b) => b.wins - a.wins);
+}
+
+export interface LeaderboardEntry {
+  userId: string;
+  userName: string;
+  wins: number;
+  totalScore: number;
+  games: number;
+}
+
+export async function getGameLeaderboard(
+  gameId: string,
+  channelKeyFilter: string,
+  limit = 10,
+): Promise<LeaderboardEntry[]> {
+  const db = activeDatabase();
+  if (!db) return [];
+  const rows = await getRecordModel(db).findAll({
+    game_id: gameId,
+    channel_key: channelKeyFilter,
+  });
+  const byUser = new Map<string, LeaderboardEntry>();
+  for (const row of rows) {
+    let entry = byUser.get(row.user_id);
+    if (!entry) {
+      entry = {
+        userId: row.user_id,
+        userName: row.user_name,
+        wins: 0,
+        totalScore: 0,
+        games: 0,
+      };
+      byUser.set(row.user_id, entry);
+    }
+    entry.games++;
+    entry.totalScore += row.score;
+    if (row.result === 'won') entry.wins++;
+  }
+  return [...byUser.values()]
+    .sort((a, b) => b.wins - a.wins || b.totalScore - a.totalScore)
+    .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 '暂无已注册游戏。';
+          let gameId = games[0]!.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);
+}