@zhin.js/game-shared 1.0.0

package/src/game-hub-flow.ts

@@ -0,0 +1,114 @@
+import type { Message, Plugin } from 'zhin.js';
+import { parseChoicePayload } from './choice-keyboard.js';
+import {
+  buildGameHubMenu,
+  buildMainHubMenu,
+  formatHubEmptyMessage,
+  HUB_PREFIX,
+  hubActionChoiceId,
+  hubGameChoiceId,
+  parseHubChoiceId,
+} from './game-hub-menu.js';
+import { getRegisteredGame, getRegisteredGames } from './game-hub-feature.js';
+import {
+  createHubScope,
+  getHubContext,
+  rememberHubMenu,
+  type HubMenuChoice,
+} from './game-hub-menu-context.js';
+
+function mainMenuChoices(): HubMenuChoice[] {
+  return getRegisteredGames().map((g) => ({
+    id: hubGameChoiceId(g.id),
+    label: `${g.icon} ${g.title}`,
+  }));
+}
+
+function gameMenuChoices(gameId: string, channelType: string): HubMenuChoice[] {
+  const game = getRegisteredGame(gameId);
+  if (!game) return [];
+  const isGroup = channelType !== 'private';
+  const menus = game.menus.filter((m) => {
+    if (m.groupOnly && !isGroup) return false;
+    if (m.privateOnly && isGroup) return false;
+    return true;
+  });
+  return [
+    ...menus.map((m) => ({
+      id: hubActionChoiceId(game.id, m.id),
+      label: m.label,
+    })),
+    { id: 'back', label: '↩️ 返回大厅' },
+  ];
+}
+
+export function openMainMenu(message: Message<any>): ReturnType<typeof buildMainHubMenu> | string {
+  const games = getRegisteredGames();
+  if (!games.length) {
+    return formatHubEmptyMessage();
+  }
+  const scopeId = createHubScope(message);
+  const choices = mainMenuChoices();
+  rememberHubMenu(message, scopeId, choices);
+  return buildMainHubMenu(scopeId, games);
+}
+
+export async function handleHubChoice(
+  plugin: Plugin,
+  message: Message<any>,
+  scopeId: string,
+  choiceId: string,
+): Promise<boolean> {
+  const ctx = getHubContext(scopeId);
+  if (!ctx) {
+    await message.$reply?.('菜单已过期，请重新发送「游戏」。');
+    return true;
+  }
+  const ch = `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+  if (ctx.channelKey !== ch) {
+    await message.$reply?.('请在本频道使用游戏大厅。');
+    return true;
+  }
+
+  const parsed = parseHubChoiceId(choiceId);
+  if (!parsed) return false;
+
+  // 大厅导航（选游戏 / 返回）：同频道任何人都可点；具体开局由 runAction 用当前点击者 message
+  if (parsed.kind === 'back') {
+    const games = getRegisteredGames();
+    const choices = mainMenuChoices();
+    rememberHubMenu(message, scopeId, choices);
+    await message.$reply?.(buildMainHubMenu(scopeId, games));
+    return true;
+  }
+
+  if (parsed.kind === 'game') {
+    const game = getRegisteredGame(parsed.gameId);
+    if (!game) {
+      await message.$reply?.('该游戏未安装。');
+      return true;
+    }
+    const choices = gameMenuChoices(parsed.gameId, message.$channel.type);
+    rememberHubMenu(message, scopeId, choices);
+    await message.$reply?.(
+      buildGameHubMenu(scopeId, game, message.$channel.type),
+    );
+    return true;
+  }
+
+  const game = getRegisteredGame(parsed.gameId);
+  if (!game) {
+    await message.$reply?.('该游戏未安装。');
+    return true;
+  }
+
+  const result = await game.runAction(parsed.actionId, { plugin, message });
+  if (typeof result === 'string') await message.$reply?.(result);
+  return true;
+}
+
+export function parseHubPayload(payload: string): { scopeId: string; choiceId: string } | null {
+  const parsed = parseChoicePayload(payload, HUB_PREFIX);
+  if (!parsed) return null;
+  return { scopeId: parsed.sessionId, choiceId: parsed.choiceId };
+}

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

@@ -0,0 +1,91 @@
+import type { Message } from 'zhin.js';
+import { channelKey } from './board-sender.js';
+
+export interface HubMenuContext {
+  channelKey: string;
+  /** 打开菜单的用户（仅记录，大厅导航不限制点击者） */
+  openerId: string;
+  message: Message<any>;
+  expiresAt: number;
+}
+
+export interface HubMenuChoice {
+  id: string;
+  label: string;
+  disabled?: boolean;
+}
+
+export interface LastHubMenu {
+  scopeId: string;
+  choices: HubMenuChoice[];
+  expiresAt: number;
+}
+
+const TTL_MS = 60 * 60 * 1000;
+const contexts = new Map<string, HubMenuContext>();
+const lastMenus = new Map<string, LastHubMenu>();
+
+function userChannelKey(message: Message<any>): string {
+  return `${channelKey(message)}:${message.$sender.id}`;
+}
+
+export function createHubScope(message: Message<any>): string {
+  const scopeId = `h${Date.now().toString(36)}${Math.random().toString(36).slice(2, 5)}`;
+  contexts.set(scopeId, {
+    channelKey: channelKey(message),
+    openerId: message.$sender.id,
+    message,
+    expiresAt: Date.now() + TTL_MS,
+  });
+  pruneExpired();
+  return scopeId;
+}
+
+export function rememberHubMenu(
+  message: Message<any>,
+  scopeId: string,
+  choices: HubMenuChoice[],
+): void {
+  lastMenus.set(userChannelKey(message), {
+    scopeId,
+    choices,
+    expiresAt: Date.now() + TTL_MS,
+  });
+  pruneExpired();
+}
+
+export function getLastHubMenu(message: Message<any>): LastHubMenu | null {
+  pruneExpired();
+  const last = lastMenus.get(userChannelKey(message));
+  if (!last || last.expiresAt < Date.now()) {
+    lastMenus.delete(userChannelKey(message));
+    return null;
+  }
+  return last;
+}
+
+export function getHubContext(scopeId: string): HubMenuContext | null {
+  pruneExpired();
+  const ctx = contexts.get(scopeId);
+  if (!ctx || ctx.expiresAt < Date.now()) {
+    contexts.delete(scopeId);
+    return null;
+  }
+  return ctx;
+}
+
+function pruneExpired(): void {
+  const now = Date.now();
+  for (const [id, ctx] of contexts) {
+    if (ctx.expiresAt < now) contexts.delete(id);
+  }
+  for (const [key, menu] of lastMenus) {
+    if (menu.expiresAt < now) lastMenus.delete(key);
+  }
+}
+
+/** 测试专用：清空菜单上下文 */
+export function resetHubMenuContextForTests(): void {
+  contexts.clear();
+  lastMenus.clear();
+}

package/src/game-hub-menu.ts

@@ -0,0 +1,134 @@
+import type { SendContent } from 'zhin.js';
+import { buildChoiceKeyboard } from './choice-keyboard.js';
+import type { RegisteredGame } from './game-hub-feature.js';
+
+export const HUB_PREFIX = 'hub';
+
+export function hubGameChoiceId(gameId: string): string {
+  return `g_${gameId}`;
+}
+
+export function hubActionChoiceId(gameId: string, actionId: string): string {
+  return `a_${gameId}_${actionId}`;
+}
+
+export function parseHubChoiceId(
+  choiceId: string,
+):
+  | { kind: 'game'; gameId: string }
+  | { kind: 'action'; gameId: string; actionId: string }
+  | { kind: 'back' }
+  | null {
+  if (choiceId === 'back') return { kind: 'back' };
+  if (choiceId.startsWith('g_')) return { kind: 'game', gameId: choiceId.slice(2) };
+  if (choiceId.startsWith('a_')) {
+    const rest = choiceId.slice(2);
+    const sep = rest.indexOf('_');
+    if (sep <= 0) return null;
+    return {
+      kind: 'action',
+      gameId: rest.slice(0, sep),
+      actionId: rest.slice(sep + 1),
+    };
+  }
+  return null;
+}
+
+export function buildMainHubMenu(scopeId: string, games: readonly RegisteredGame[]): SendContent {
+  const cmdHint = formatCommandPrefixHint(games);
+  const lines = [
+    '🎮 **游戏大厅**',
+    '',
+    cmdHint,
+    '',
+    '_同频道均可浏览；开局后仅对局玩家可操作棋盘。_',
+    '',
+  ];
+  for (const g of games) {
+    lines.push(`• ${g.icon} **${g.title}** — ${g.description}`);
+  }
+
+  return buildChoiceKeyboard({
+    gamePrefix: HUB_PREFIX,
+    sessionId: scopeId,
+    narrative: lines.join('\n'),
+    choices: games.map((g) => ({
+      id: hubGameChoiceId(g.id),
+      label: `${g.icon} ${g.title}`,
+      style: 'primary' as const,
+    })),
+    buttonsPerRow: 2,
+    fallbackHint: '回复数字进入对应游戏',
+  });
+}
+
+export function buildGameHubMenu(
+  scopeId: string,
+  game: RegisteredGame,
+  channelType: string,
+): SendContent {
+  const isGroup = channelType !== 'private';
+  const menus = game.menus.filter((m) => {
+    if (m.groupOnly && !isGroup) return false;
+    if (m.privateOnly && isGroup) return false;
+    return true;
+  });
+
+  return buildChoiceKeyboard({
+    gamePrefix: HUB_PREFIX,
+    sessionId: scopeId,
+    narrative: `${game.icon} **${game.title}**\n\n${game.description}\n\n请选择：`,
+    choices: [
+      ...menus.map((m) => ({
+        id: hubActionChoiceId(game.id, m.id),
+        label: m.label,
+        style: m.style,
+      })),
+      { id: 'back', label: '↩️ 返回大厅' },
+    ],
+    buttonsPerRow: 2,
+    fallbackHint: '回复数字选择操作',
+  });
+}
+
+/** 大厅主菜单：命令前缀提示 */
+export function formatCommandPrefixHint(games: readonly RegisteredGame[]): string {
+  if (!games.length) return '暂无可用游戏。';
+  const sample = games.slice(0, 5).map((g) => g.commandPrefix);
+  const tail = games.length > sample.length ? '等' : '';
+  return `选择想玩的游戏（也可直接发送中文命令，如「${sample.join('」「')}」${tail}）：`;
+}
+
+/** 游戏大厅帮助文案（随 registerGame 动态生成） */
+export function formatHubHelp(games: readonly RegisteredGame[]): string {
+  const lines = [
+    '🎮 **游戏大厅**',
+    '',
+    '游戏 — 打开可点击的游戏菜单',
+    'game — 同上（英文）',
+  ];
+
+  if (!games.length) {
+    lines.push('', '当前暂无已注册游戏。', '请安装任意游戏插件（registerGame 会自动挂载大厅）。');
+    return lines.join('\n');
+  }
+
+  lines.push('', `当前已注册 **${games.length}** 款游戏：`, '');
+
+  for (const g of games) {
+    const quick = g.quickStart ?? '开始';
+    const alias = g.aliases?.length ? ` · ${g.aliases.join(' / ')}` : '';
+    lines.push(`• ${g.icon} **${g.title}**${alias}`);
+    lines.push(`  命令：\`${g.commandPrefix} ${quick}\` — ${g.description}`);
+  }
+
+  return lines.join('\n');
+}
+
+/** 无游戏时的提示 */
+export function formatHubEmptyMessage(): string {
+  return [
+    '游戏大厅暂无可用游戏。',
+    '请安装任意游戏插件；首个游戏 registerGame 时会自动挂载大厅命令。',
+  ].join('');
+}

package/src/game-hub-mount.ts

@@ -0,0 +1,108 @@
+import {
+  Message,
+  MessageCommand,
+  getActionFromMessage,
+  type Plugin,
+} from 'zhin.js';
+import { buildChoiceFallbackMap, parseChoicePayload } from './choice-keyboard.js';
+import {
+  formatHubEmptyMessage,
+  formatHubHelp,
+  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';
+
+/**
+ * 在 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),
+    ),
+  );
+
+  disposers.push(
+    root.addCommand(
+      new MessageCommand('game')
+        .desc('Game lobby (English alias)')
+        .action(openHandler),
+    ),
+  );
+
+  disposers.push(
+    root.addCommand(
+      new MessageCommand('游戏 帮助')
+        .desc('游戏大厅帮助')
+        .action(async () => formatHubHelp(getRegisteredGames())),
+    ),
+  );
+
+  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() ?? '';
+      const n = /^(\d+)$/.exec(raw);
+      if (!n) return next();
+
+      const last = getLastHubMenu(message);
+      if (!last) return next();
+
+      const map = buildChoiceFallbackMap(HUB_PREFIX, last.scopeId, last.choices);
+      const payload = map[n[1]!];
+      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-middleware.ts

@@ -0,0 +1,14 @@
+import type { MessageMiddleware, Plugin, RegisteredAdapter } from 'zhin.js';
+
+/**
+ * 在 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-session.ts

@@ -0,0 +1,88 @@
+/**
+ * 通用游戏会话接口
+ * 定义回合制游戏的基础会话结构
+ */
+import type { Message } from 'zhin.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 `s${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+}
+
+/** 获取当前回合玩家 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<any>): string {
+  const name = message.$sender.name?.trim();
+  return name || message.$sender.id;
+}

package/src/grid-keyboard.ts

@@ -0,0 +1,142 @@
+/**
+ * 通用网格按钮键盘构建器
+ * 支持井字棋（3×3）、五子棋（15×15）、四子棋（7×6）等
+ */
+import { segment, type SendContent } from 'zhin.js';
+
+export interface GridCell<T = unknown> {
+  /** 单元格状态（游戏自定义，如 0=空, 1=X, 2=O） */
+  state: T;
+  /** 按钮显示文本 */
+  label: string;
+  /** 是否禁用（已落子或终局） */
+  disabled: boolean;
+  /** 高亮（胜利连线等） */
+  highlight?: boolean;
+}
+
+export interface GridKeyboardOptions<T = unknown> {
+  /** 游戏前缀（如 'ttt', 'gomoku', 'c4'） */
+  gamePrefix: string;
+  /** 会话 ID */
+  sessionId: string;
+  /** 行数 */
+  rows: number;
+  /** 列数 */
+  cols: number;
+  /** 单元格数据，按行优先 [row * cols + col] */
+  cells: GridCell<T>[];
+  /** 状态行文本 */
+  statusLine: string;
+  /** 是否终局（全部按钮禁用） */
+  terminal?: boolean;
+  /** 省略 ASCII 文本棋盘（QQ 等平台） */
+  omitAsciiBoard?: boolean;
+  /** ASCII 棋盘渲染器（可选，省略则不渲染 ASCII） */
+  renderAscii?: (cells: GridCell<T>[], rows: number, cols: number, highlight?: number[]) => string;
+  /** 高亮的单元格索引（胜利连线等） */
+  highlight?: number[];
+  /** fallback 提示文本 */
+  fallbackHint?: string;
+}
+
+/**
+ * 构建 fallback 数字映射（仅可落子的格子）
+ */
+export function buildGridFallbackMap(
+  gamePrefix: string,
+  sessionId: string,
+  cells: GridCell[],
+): Record<string, string> {
+  const map: Record<string, string> = {};
+  let n = 1;
+  for (let i = 0; i < cells.length; i++) {
+    if (!cells[i]!.disabled) {
+      map[String(n)] = `${gamePrefix}:${sessionId}:${i}`;
+      n++;
+    }
+  }
+  return map;
+}
+
+/**
+ * 构建网格按钮键盘消息内容
+ */
+export function buildGridKeyboard<T>(options: GridKeyboardOptions<T>): SendContent {
+  const {
+    gamePrefix,
+    sessionId,
+    rows,
+    cols,
+    cells,
+    statusLine,
+    terminal,
+    omitAsciiBoard,
+    renderAscii,
+    highlight,
+    fallbackHint,
+  } = options;
+
+  const buttonRows: ReturnType<typeof segment.button>[][] = [];
+
+  for (let r = 0; r < rows; r++) {
+    const row: ReturnType<typeof segment.button>[] = [];
+    for (let c = 0; c < cols; c++) {
+      const i = r * cols + c;
+      const cell = cells[i]!;
+      row.push(
+        segment.button({
+          id: `c${i}`,
+          label: cell.label,
+          payload: `${gamePrefix}:${sessionId}:${i}`,
+          disabled: terminal || cell.disabled,
+          style: cell.highlight ? 'primary' : 'secondary',
+        }),
+      );
+    }
+    buttonRows.push(row);
+  }
+
+  const fallback = buildGridFallbackMap(gamePrefix, sessionId, cells);
+
+  const textLines = [statusLine];
+  if (!omitAsciiBoard && renderAscii) {
+    textLines.push('', renderAscii(cells, rows, cols, highlight));
+  }
+
+  return [
+    segment.text(textLines.join('\n')),
+    segment.keyboard(buttonRows, {
+      fallback: fallbackHint
+        ? { hint: fallbackHint, map: fallback }
+        : undefined,
+    }).toElement(),
+  ];
+}
+
+/**
+ * 解析网格 payload：`{prefix}:{sessionId}:{cellIndex}`
+ */
+export function parseGridPayload(
+  payload: string,
+  expectedPrefix?: string,
+): { prefix: string; sessionId: string; cell: number } | null {
+  const m = /^([a-z0-9_]+):([^:]+):(\d+)$/i.exec(payload);
+  if (!m) return null;
+  const prefix = m[1]!;
+  if (expectedPrefix && prefix !== expectedPrefix) return null;
+  const cell = Number(m[3]);
+  if (!Number.isInteger(cell) || cell < 0) return null;
+  return { prefix, sessionId: m[2]!, cell };
+}
+
+/**
+ * 解析按钮 ID 格式：`c{cellIndex}`（QQ 等平台 action 可能只回传 button_id）
+ */
+export function parseCellButtonId(value: string): number | null {
+  const m = /^c(\d+)$/.exec(value);
+  if (!m) return null;
+  const cell = Number(m[1]);
+  if (!Number.isInteger(cell) || cell < 0) return null;
+  return cell;
+}