@zhin.js/game-kit 1.0.1

package/src/game-session.ts

@@ -0,0 +1,97 @@
+/**
+ * 通用游戏会话接口
+ * 定义回合制游戏的基础会话结构
+ */
+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<any>): 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));
+}

package/src/grid-keyboard.ts

@@ -0,0 +1,180 @@
+/**
+ * 通用网格按钮键盘构建器
+ * 支持井字棋（3×3）、五子棋（15×15）、四子棋（7×6）等
+ */
+import { segment, type SendContent } from '@zhin.js/core';
+import { buildChoiceFallbackMap, type ChoiceOption } from './choice-keyboard.js';
+
+import { applyInteractionProfile } from './interaction-profiles.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;
+  /** 终局时在棋盘下方追加的选项（如「再来一局」，不受 terminal 禁用） */
+  postChoices?: ChoiceOption[];
+  /** postChoices 使用的 profile，默认 terminal */
+  postChoicesProfile?: 'terminal';
+  /** terminal 私聊 auto-enter */
+  channelType?: 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,
+    postChoices,
+    postChoicesProfile = 'terminal',
+    channelType,
+  } = 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));
+  }
+
+  if (postChoices?.length) {
+    buttonRows.push(
+      postChoices.map((choice) => {
+        const base = segment.button({
+          id: choice.id,
+          label: choice.label,
+          payload: `${gamePrefix}:${sessionId}:${choice.id}`,
+          disabled: choice.disabled ?? false,
+          style: choice.style ?? 'primary',
+        });
+        return segment.button(
+          applyInteractionProfile(base.data, {
+            profile: postChoicesProfile,
+            channelType,
+          }),
+        );
+      }),
+    );
+    Object.assign(fallback, buildChoiceFallbackMap(gamePrefix, sessionId, postChoices));
+  }
+
+  const parts = [
+    segment.text(textLines.join('\n')),
+    segment.keyboard(buttonRows, {
+      fallback: fallbackHint || Object.keys(fallback).length > 0
+        ? {
+            hint: fallbackHint ?? '回复数字选择',
+            map: fallback,
+          }
+        : undefined,
+    }).toElement(),
+  ];
+
+  return parts;
+}
+
+/**
+ * 解析网格 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;
+}

package/src/help-card.ts

@@ -0,0 +1,188 @@
+import {
+  Card,
+  CardCanvas,
+  CardHeader,
+  DEFAULT_CARD_THEME,
+  h,
+  KvRow,
+  Section,
+  TopicItem,
+} from '@zhin.js/satori';
+import type { RegisteredGame } from './game-hub-feature.js';
+import { slashCommandPrefix } from './game-commands.js';
+import {
+  collectSupplementaryCommandHelp,
+  formatHubOpenCommandLines,
+  type CommandHelpSource,
+} from './command-help.js';
+
+export const HELP_CARD_CANVAS = DEFAULT_CARD_THEME.canvas;
+export const HELP_CARD_WIDTH = 560;
+
+function cardShell(inner: string): string {
+  return h(CardCanvas, {
+    width: HELP_CARD_WIDTH,
+    backgroundColor: HELP_CARD_CANVAS,
+    children: h(Card, { children: inner }),
+  });
+}
+
+function gameTopicSummary(game: RegisteredGame): string {
+  const quick = game.quickStart ?? '开始';
+  const cmd = `${slashCommandPrefix(game.commandPrefix.replace(/^\//, ''))} ${quick}`;
+  const alias = game.aliases?.length ? ` · ${game.aliases.join(' / ')}` : '';
+  return `${cmd}${alias} — ${game.description}`;
+}
+
+function commandTopicSummary(cmd: CommandHelpSource): string {
+  const [label = '', detail = ''] = cmd.helpInfo.desc;
+  return detail || label || cmd.pattern;
+}
+
+export interface BotHelpCardInput {
+  games: readonly RegisteredGame[];
+  commands?: readonly CommandHelpSource[];
+  channelType?: string;
+}
+
+export function buildBotHelpHtml(input: BotHelpCardInput): string {
+  const { games, commands, channelType } = input;
+  const hubLines = formatHubOpenCommandLines(commands);
+  const other = commands?.length
+    ? collectSupplementaryCommandHelp(commands, games)
+    : [];
+
+  const parts: string[] = [];
+
+  parts.push(
+    h(CardHeader, {
+      title: '游戏大厅',
+      subtitle: games.length
+        ? `已注册 ${games.length} 款游戏 · 发送 /游戏 打开按钮大厅`
+        : '暂无已注册游戏',
+      badge: '🎮',
+    }),
+  );
+
+  if (hubLines.length) {
+    parts.push(
+      h(Section, {
+        title: '入口',
+        children: hubLines.map((line) => {
+          const sep = line.indexOf(' — ');
+          const pattern = sep >= 0 ? line.slice(0, sep) : line;
+          const desc = sep >= 0 ? line.slice(sep + 3) : '';
+          return h(KvRow, { label: pattern, value: desc, labelWidth: 72 });
+        }),
+      }),
+    );
+  }
+
+  if (games.length) {
+    parts.push(
+      h(Section, {
+        title: '游戏列表',
+        children: games.map((g, i) =>
+          h(TopicItem, {
+            index: i + 1,
+            title: `${g.icon} ${g.title}`,
+            summary: gameTopicSummary(g),
+          }),
+        ),
+      }),
+    );
+  } else {
+    parts.push(
+      h(Section, {
+        title: '提示',
+        children: h(TopicItem, {
+          index: 1,
+          title: '安装任意游戏插件',
+          summary: 'registerGame 后会自动挂载大厅命令',
+        }),
+      }),
+    );
+  }
+
+  if (other.length) {
+    parts.push(
+      h(Section, {
+        title: '其他命令',
+        children: other.map((cmd, i) =>
+          h(TopicItem, {
+            index: i + 1,
+            title: cmd.pattern,
+            summary: commandTopicSummary(cmd),
+          }),
+        ),
+      }),
+    );
+  }
+
+  if (channelType === 'group') {
+    parts.push(
+      h(Section, {
+        title: 'QQ 群用法',
+        children: [
+          h(TopicItem, {
+            index: 1,
+            title: '公域群需 @ 机器人',
+            summary: '发送命令或直接点击消息按钮',
+          }),
+          h(TopicItem, {
+            index: 2,
+            title: '/游戏 打开大厅',
+            summary: '同群成员均可点击按钮参与',
+          }),
+        ],
+      }),
+    );
+  }
+
+  return cardShell(parts.join(''));
+}
+
+export function buildHubHelpHtml(
+  games: readonly RegisteredGame[],
+  commands?: readonly CommandHelpSource[],
+): string {
+  const hubLines = formatHubOpenCommandLines(commands);
+  const parts: string[] = [
+    h(CardHeader, {
+      title: '游戏大厅帮助',
+      subtitle: games.length ? `${games.length} 款游戏可选` : '暂无游戏',
+      badge: '🎮',
+    }),
+  ];
+
+  if (hubLines.length) {
+    parts.push(
+      h(Section, {
+        title: '入口',
+        children: hubLines.map((line) => {
+          const sep = line.indexOf(' — ');
+          const pattern = sep >= 0 ? line.slice(0, sep) : line;
+          const desc = sep >= 0 ? line.slice(sep + 3) : '';
+          return h(KvRow, { label: pattern, value: desc, labelWidth: 72 });
+        }),
+      }),
+    );
+  }
+
+  if (games.length) {
+    parts.push(
+      h(Section, {
+        title: '游戏',
+        children: games.map((g, i) =>
+          h(TopicItem, {
+            index: i + 1,
+            title: `${g.icon} ${g.title}`,
+            summary: gameTopicSummary(g),
+          }),
+        ),
+      }),
+    );
+  }
+
+  return cardShell(parts.join(''));
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @zhin.js/game-kit - 通用游戏工具包
+ *
+ * 提供网格棋盘、会话管理、消息发送等通用抽象
+ */
+
+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 './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';
+export * from './runtime-hub.js';
+export * from './command-alias.js';
+export * from './random.js';

package/src/interaction-profiles.ts

@@ -0,0 +1,56 @@
+import type { ButtonCommandOptions, ButtonData, ButtonInteractionMode } from '@zhin.js/core';
+
+/** 交互模式预设：见 ADR 0022 / docs/essentials/interactive-segments.md */
+export type InteractionProfile = 'menu' | 'gameplay' | 'terminal';
+
+export interface ApplyInteractionProfileOptions {
+  profile: InteractionProfile;
+  /** 用于 terminal profile：私聊可 auto-enter */
+  channelType?: string;
+}
+
+function defaultModeForProfile(
+  profile: InteractionProfile,
+  channelType?: string,
+): ButtonInteractionMode {
+  if (profile === 'gameplay') return 'callback';
+  // 群/频道大厅为共享 UI，须 callback，否则仅 opener 有文本 fallback 上下文
+  if (profile === 'menu' && channelType && channelType !== 'private') return 'callback';
+  return 'command';
+}
+
+function defaultCommandForProfile(
+  profile: InteractionProfile,
+  channelType?: string,
+): ButtonCommandOptions | undefined {
+  if (profile !== 'terminal') return undefined;
+  return { enter: channelType === 'private' };
+}
+
+/**
+ * 按 profile 注入 button.mode（显式 mode 优先）。
+ * - menu / terminal → command
+ * - gameplay → callback
+ */
+export function applyInteractionProfile(
+  btn: ButtonData,
+  options: ApplyInteractionProfileOptions,
+): ButtonData {
+  if (btn.mode != null) return btn;
+  const mode = defaultModeForProfile(options.profile, options.channelType);
+  const commandDefaults = defaultCommandForProfile(options.profile, options.channelType);
+  return {
+    ...btn,
+    mode,
+    command: commandDefaults
+      ? { ...commandDefaults, ...btn.command }
+      : btn.command,
+  };
+}
+
+export function applyInteractionProfileToButtons(
+  buttons: ButtonData[],
+  options: ApplyInteractionProfileOptions,
+): ButtonData[] {
+  return buttons.map((btn) => applyInteractionProfile(btn, options));
+}

package/src/memory-db.ts

@@ -0,0 +1,128 @@
+/**
+ * Minimal in-memory models for game SessionService (findAll/findOne/create/updateWhere/deleteWhere).
+ * Slice-2 fallback while Plugin Runtime has no DatabaseFeature Resource path.
+ */
+
+type Row = Record<string, unknown>;
+
+export interface InMemoryGameModel {
+  findAll: (q?: Record<string, unknown>) => Promise<Row[]>;
+  findOne: (q?: Record<string, unknown>) => Promise<Row | null>;
+  create: (row: Row) => Promise<Row>;
+  updateWhere: (where: Record<string, unknown>, patch: Row) => Promise<number>;
+  deleteWhere: (where: Record<string, unknown>) => Promise<number>;
+}
+
+export interface InMemoryGameDb {
+  models: { get: (name: string) => InMemoryGameModel | undefined };
+}
+
+function createMemoryModel(): InMemoryGameModel {
+  const rows: Row[] = [];
+
+  const match = (row: Row, q: Record<string, unknown>) =>
+    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,
+    create: async (row: Row) => {
+      rows.push({ ...row });
+      return row;
+    },
+    updateWhere: async (where: Record<string, unknown>, patch: Row) => {
+      let n = 0;
+      for (const row of rows) {
+        if (match(row, where)) {
+          Object.assign(row, patch);
+          n += 1;
+        }
+      }
+      return n;
+    },
+    deleteWhere: async (where: Record<string, unknown>) => {
+      let n = 0;
+      for (let i = rows.length - 1; i >= 0; i -= 1) {
+        if (match(rows[i]!, where)) {
+          rows.splice(i, 1);
+          n += 1;
+        }
+      }
+      return n;
+    },
+  };
+}
+
+/** Create an in-memory db with the given model table names. */
+export function createInMemoryGameDb(tableNames: readonly string[]): InMemoryGameDb {
+  const models = new Map<string, InMemoryGameModel>();
+  for (const name of tableNames) {
+    models.set(name, createMemoryModel());
+  }
+  return {
+    models: {
+      get: (name: string) => models.get(name),
+    },
+  };
+}
+
+/** Minimal DatabaseHost model surface (structural typing; no plugin-runtime dep). */
+export interface HostGameModelSource {
+  select(): {
+    where(query: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+  };
+  insert(row: Record<string, unknown>): Promise<unknown>;
+  delete(): { where(query: Record<string, unknown>): Promise<unknown> };
+  update(patch: Record<string, unknown>): {
+    where(query: Record<string, unknown>): Promise<unknown>;
+  };
+}
+
+export interface HostGameDbSource {
+  models: { get(name: string): HostGameModelSource | undefined };
+}
+
+function wrapHostModel(model: HostGameModelSource): InMemoryGameModel {
+  return {
+    findAll: async (q: Record<string, unknown> = {}) => {
+      const rows = await model.select().where(q);
+      return rows as Row[];
+    },
+    findOne: async (q: Record<string, unknown> = {}) => {
+      const rows = await model.select().where(q);
+      return (rows[0] as Row | undefined) ?? null;
+    },
+    create: async (row: Row) => {
+      await model.insert(row);
+      return row;
+    },
+    updateWhere: async (where: Record<string, unknown>, patch: Row) => {
+      const matching = await model.select().where(where);
+      if (matching.length === 0) return 0;
+      await model.update(patch).where(where);
+      return matching.length;
+    },
+    deleteWhere: async (where: Record<string, unknown>) => {
+      const matching = await model.select().where(where);
+      if (matching.length === 0) return 0;
+      await model.delete().where(where);
+      return matching.length;
+    },
+  };
+}
+
+/** Adapt DatabaseHost models to SessionService RelatedModel-style API. */
+export function createHostGameDb(
+  host: HostGameDbSource,
+  tableNames: readonly string[],
+): InMemoryGameDb {
+  return {
+    models: {
+      get: (name: string) => {
+        if (!tableNames.includes(name)) return undefined;
+        const raw = host.models.get(name);
+        return raw ? wrapHostModel(raw) : undefined;
+      },
+    },
+  };
+}