@zhin.js/game-kit 1.0.1

package/lib/game-hub-menu.js

@@ -0,0 +1,162 @@
+import { segment } from '@zhin.js/core';
+import { buildChoiceKeyboard } from './choice-keyboard.js';
+import { slashCommandPrefix } from './game-commands.js';
+import { formatHubOpenCommandLines, formatSupplementaryCommandsHelp, } from './command-help.js';
+import { buildBotHelpHtml, buildHubHelpHtml, HELP_CARD_CANVAS, HELP_CARD_WIDTH, } from './help-card.js';
+export const HUB_PREFIX = 'hub';
+export function hubGameChoiceId(gameId) {
+    return `g_${gameId}`;
+}
+export function hubActionChoiceId(gameId, actionId) {
+    return `a_${gameId}_${actionId}`;
+}
+export function parseHubChoiceId(choiceId) {
+    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, games, channelType) {
+    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',
+        })),
+        buttonsPerRow: 2,
+        fallbackHint: '回复数字进入对应游戏',
+        interactionProfile: 'menu',
+        channelType,
+    });
+}
+export function buildGameHubMenu(scopeId, game, channelType) {
+    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: '回复数字选择操作',
+        interactionProfile: 'menu',
+        channelType,
+    });
+}
+/** 大厅主菜单：命令前缀提示 */
+export function formatCommandPrefixHint(games) {
+    if (!games.length)
+        return '暂无可用游戏。';
+    const sample = games.slice(0, 5).map((g) => slashCommandPrefix(g.commandPrefix.replace(/^\//, '')));
+    const tail = games.length > sample.length ? '等' : '';
+    return `选择想玩的游戏（也可直接发送斜杠命令，如「${sample.join('」「')}」${tail}）：`;
+}
+/** 游戏大厅帮助文案（随 registerGame 动态生成） */
+export function formatHubHelp(games, commands) {
+    const lines = [
+        '🎮 **游戏大厅**',
+        '',
+        ...formatHubOpenCommandLines(commands),
+    ];
+    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(`  命令：\`${slashCommandPrefix(g.commandPrefix.replace(/^\//, ''))} ${quick}\` — ${g.description}`);
+    }
+    return lines.join('\n');
+}
+/** 顶层 /帮助：游戏大厅 + 已注册命令自动汇总 */
+export function formatBotHelp(games, options) {
+    const commands = options?.commands;
+    const sections = [formatHubHelp(games, commands)];
+    const other = commands?.length
+        ? formatSupplementaryCommandsHelp(commands, games)
+        : '';
+    if (other) {
+        sections.push('', '---', '', other);
+    }
+    if (options?.channelType === 'group') {
+        sections.push('', '**QQ 群用法**', '• 公域群需 **@ 机器人** 后发送命令，或直接 **点击消息按钮**', '• 发送 `/游戏` 打开大厅，同群成员均可点击按钮');
+    }
+    return sections.join('\n');
+}
+/** 顶层 /帮助：HTML 卡片（QQ 等出站 policy 为 image 时渲染为 PNG；无 renderer 时回退文本） */
+export function buildBotHelpReply(games, options) {
+    const text = formatBotHelp(games, options);
+    return segment.html({
+        html: buildBotHelpHtml({
+            games,
+            commands: options?.commands,
+            channelType: options?.channelType,
+        }),
+        text,
+        width: HELP_CARD_WIDTH,
+        backgroundColor: HELP_CARD_CANVAS,
+        fileName: 'bot-help.png',
+    });
+}
+/** /游戏 帮助：大厅专用卡片 */
+export function buildHubHelpReply(games, commands) {
+    const text = formatHubHelp(games, commands);
+    return segment.html({
+        html: buildHubHelpHtml(games, commands),
+        text,
+        width: HELP_CARD_WIDTH,
+        backgroundColor: HELP_CARD_CANVAS,
+        fileName: 'game-hub-help.png',
+    });
+}
+/** 无游戏时的提示 */
+export function formatHubEmptyMessage() {
+    return [
+        '游戏大厅暂无可用游戏。',
+        '请安装任意游戏插件；首个游戏 registerGame 时会自动挂载大厅命令。',
+    ].join('');
+}
+//# sourceMappingURL=game-hub-menu.js.map

package/lib/game-hub-menu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-hub-menu.js","sourceRoot":"","sources":["../src/game-hub-menu.ts"],"names":[],"mappings":"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"}

package/lib/game-hub-mount.d.ts

@@ -0,0 +1,9 @@
+import { type Plugin } from '@zhin.js/core';
+/**
+ * 在 root 上挂载「游戏 / game」大厅命令，返回 dispose 列表。
+ */
+export declare function mountGameHubUi(root: Plugin): (() => void)[];
+export declare function isGameHubMounted(): boolean;
+export declare function markGameHubUiMounted(): void;
+export declare function resetGameHubMountForTests(): void;
+//# sourceMappingURL=game-hub-mount.d.ts.map

package/lib/game-hub-mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-hub-mount.d.ts","sourceRoot":"","sources":["../src/game-hub-mount.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,MAAM,EACZ,MAAM,eAAe,CAAC;AAwBvB;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAkH3D;AAcD,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/lib/game-hub-mount.js

@@ -0,0 +1,108 @@
+import { MessageCommand, getActionFromMessage, resolvePayloadFromText, } 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 } from './command-help.js';
+function resolveRegisteredCommands(root) {
+    const commandService = root.inject('command');
+    return commandService?.items ?? [];
+}
+async function resolveHelpCommands(root, message) {
+    return filterHelpCommands(resolveRegisteredCommands(root), message, root);
+}
+/**
+ * 在 root 上挂载「游戏 / game」大厅命令，返回 dispose 列表。
+ */
+export function mountGameHubUi(root) {
+    const disposers = [];
+    const openHandler = async (message) => {
+        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, message) {
+    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() {
+    return hubUiMounted;
+}
+export function markGameHubUiMounted() {
+    hubUiMounted = true;
+}
+export function resetGameHubMountForTests() {
+    hubUiMounted = false;
+}
+//# sourceMappingURL=game-hub-mount.js.map

package/lib/game-hub-mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-hub-mount.js","sourceRoot":"","sources":["../src/game-hub-mount.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACd,oBAAoB,EACpB,sBAAsB,GAEvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,GACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAA0B,MAAM,mBAAmB,CAAC;AAE/E,SAAS,yBAAyB,CAAC,IAAY;IAC7C,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAA6C,CAAC;IAC1F,OAAO,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC;AACrC,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAC,IAAY,EAAE,OAAqB;IACpE,OAAO,kBAAkB,CAAC,yBAAyB,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,SAAS,GAAmB,EAAE,CAAC;IAErC,MAAM,WAAW,GAAG,KAAK,EAAE,OAAqB,EAAE,EAAE;QAClD,MAAM,KAAK,GAAG,kBAAkB,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAClB,OAAO,qBAAqB,EAAE,CAAC;QACjC,CAAC;QACD,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1C,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QAC7B,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAEF,SAAS,CAAC,IAAI,CACZ,IAAI,CAAC,UAAU,CACb,IAAI,cAAc,CAAC,KAAK,CAAC;SACtB,IAAI,CAAC,cAAc,CAAC;SACpB,MAAM,CAAC,WAAW,CAAC,CACvB,EACD,IAAI,CAAC,UAAU,CACb,IAAI,cAAc,CAAC,OAAO,CAAC;SACxB,IAAI,CAAC,4BAA4B,CAAC;SAClC,MAAM,CAAC,WAAW,CAAC,CACvB,EACD,IAAI,CAAC,UAAU,CACb,IAAI,cAAc,CAAC,IAAI,CAAC;SACrB,IAAI,CAAC,aAAa,CAAC;SACnB,MAAM,CAAC,WAAW,CAAC,CACvB,EACD,IAAI,CAAC,UAAU,CACb,IAAI,cAAc,CAAC,MAAM,CAAC;SACvB,IAAI,CAAC,2BAA2B,CAAC;SACjC,MAAM,CAAC,WAAW,CAAC,CACvB,CACF,CAAC;IAEF,SAAS,CAAC,IAAI,CACZ,IAAI,CAAC,UAAU,CACb,IAAI,cAAc,CAAC,QAAQ,CAAC;SACzB,IAAI,CAAC,QAAQ,CAAC;SACd,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CACxB,iBAAiB,CAAC,kBAAkB,EAAE,EAAE,MAAM,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAClF,CACJ,EACD,IAAI,CAAC,UAAU,CACb,IAAI,cAAc,CAAC,KAAK,CAAC;SACtB,IAAI,CAAC,oBAAoB,CAAC;SAC1B,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CACxB,iBAAiB,CAAC,kBAAkB,EAAE,EAAE;QACtC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;QAClC,QAAQ,EAAE,MAAM,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC;KACnD,CAAC,CACH,CACJ,EACD,IAAI,CAAC,UAAU,CACb,IAAI,cAAc,CAAC,OAAO,CAAC;SACxB,IAAI,CAAC,0BAA0B,CAAC;SAChC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CACxB,iBAAiB,CAAC,kBAAkB,EAAE,EAAE;QACtC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;QAClC,QAAQ,EAAE,MAAM,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC;KACnD,CAAC,CACH,CACJ,EACD,IAAI,CAAC,UAAU,CACb,IAAI,cAAc,CAAC,IAAI,CAAC;SACrB,IAAI,CAAC,WAAW,CAAC;SACjB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CACxB,iBAAiB,CAAC,kBAAkB,EAAE,EAAE;QACtC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;QAClC,QAAQ,EAAE,MAAM,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC;KACnD,CAAC,CACH,CACJ,CACF,CAAC;IAEF,SAAS,CAAC,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9C,SAAS,CAAC,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC;IAEjD,IAAI,CAAC,0BAA0B,CAAC,GAAG,UAAU,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAC5D,oBAAoB,CAAC,IAAI,EAAE,OAAO,CAAC,CACpC,CAAC;IAEF,SAAS,CAAC,IAAI,CACZ,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QACzC,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,GAAG,CAAC;YAAE,OAAO,IAAI,EAAE,CAAC;QAEhE,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAEvC,yDAAyD;QACzD,MAAM,aAAa,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAClD,IAAI,aAAa,EAAE,UAAU,CAAC,GAAG,UAAU,GAAG,CAAC,EAAE,CAAC;YAChD,MAAM,MAAM,GAAG,kBAAkB,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;YAC7D,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACxE,OAAO;YACT,CAAC;QACH,CAAC;QAED,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,EAAE,CAAC;QAEzB,MAAM,GAAG,GAAG,sBAAsB,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3E,MAAM,OAAO,GAAG,sBAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,SAAS,KAAK,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,EAAE,CAAC;QAEhE,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1E,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,oBAAoB,CAAC,IAAY,EAAE,OAAqB;IACrE,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAE1B,MAAM,WAAW,GAAG,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpD,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAE/B,OAAO,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;AACnF,CAAC;AAED,IAAI,YAAY,GAAG,KAAK,CAAC;AAEzB,MAAM,UAAU,gBAAgB;IAC9B,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,YAAY,GAAG,KAAK,CAAC;AACvB,CAAC"}

package/lib/game-interactive.d.ts

@@ -0,0 +1,25 @@
+import { type Message } from '@zhin.js/core';
+export declare const GAME_RESTART_CHOICE_IDS: Set<string>;
+export declare function isRestartChoice(choiceId: string): boolean;
+/** 从 QQ 指令预填 / 数字 fallback 解析游戏 payload */
+export declare function resolveGameTextPayload(raw: string, map?: Record<string, string>): string | undefined;
+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 declare function resolveGameChoice(opts: ResolveGameChoiceOptions): Promise<{
+    sessionId: string;
+    choiceId: string;
+} | null>;
+//# sourceMappingURL=game-interactive.d.ts.map

package/lib/game-interactive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-interactive.d.ts","sourceRoot":"","sources":["../src/game-interactive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgD,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAK3F,eAAO,MAAM,uBAAuB,aAKlC,CAAC;AAEH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,2CAA2C;AAC3C,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3B,MAAM,GAAG,SAAS,CAEpB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC/D,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACtF,mBAAmB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAC7E;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA4CzD"}

package/lib/game-interactive.js

@@ -0,0 +1,62 @@
+import { getActionFromMessage, resolvePayloadFromText } 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) {
+    return GAME_RESTART_CHOICE_IDS.has(choiceId) || choiceId.startsWith('restart_');
+}
+/** 从 QQ 指令预填 / 数字 fallback 解析游戏 payload */
+export function resolveGameTextPayload(raw, map) {
+    return resolvePayloadFromText(raw, map);
+}
+/**
+ * 解析按钮/选项回调：优先 payload；终局「再来一局」允许已结束 session。
+ */
+export async function resolveGameChoice(opts) {
+    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 };
+}
+//# sourceMappingURL=game-interactive.js.map

package/lib/game-interactive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-interactive.js","sourceRoot":"","sources":["../src/game-interactive.ts"],"names":[],"mappings":"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"}

package/lib/game-middleware.d.ts

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

package/lib/game-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-middleware.d.ts","sourceRoot":"","sources":["../src/game-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElF;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,EAChD,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,IAAI,CAIZ"}

package/lib/game-middleware.js

@@ -0,0 +1,9 @@
+/**
+ * 在 root 插件上注册游戏文本中间件（入站管线只走 root.middleware）。
+ */
+export function registerGameTextMiddleware(plugin, middleware, name) {
+    const dispose = plugin.root.addMiddleware(middleware, name);
+    plugin.onDispose(dispose);
+    return dispose;
+}
+//# sourceMappingURL=game-middleware.js.map

package/lib/game-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-middleware.js","sourceRoot":"","sources":["../src/game-middleware.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAc,EACd,UAAgD,EAChD,IAAa;IAEb,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAC5D,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/lib/game-onboarding.d.ts

@@ -0,0 +1,8 @@
+import { type Plugin } from '@zhin.js/core';
+/**
+ * 群聊首次 @ 且非命令时提示 /游戏 /帮助（每频道 24h 最多一次）
+ */
+export declare function mountFirstAtHintMiddleware(root: Plugin): () => void;
+/** 测试专用 */
+export declare function resetOnboardingForTests(): void;
+//# sourceMappingURL=game-onboarding.d.ts.map

package/lib/game-onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-onboarding.d.ts","sourceRoot":"","sources":["../src/game-onboarding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAuChF;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI,CAkBnE;AAED,WAAW;AACX,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C"}

package/lib/game-onboarding.js

@@ -0,0 +1,66 @@
+import { getActionFromMessage } from '@zhin.js/core';
+const hintedChannels = new Set();
+const TTL_MS = 24 * 60 * 60 * 1000;
+const channelHintAt = new Map();
+function channelHintKey(message) {
+    return `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+}
+function pruneHintCache() {
+    const now = Date.now();
+    for (const [key, at] of channelHintAt) {
+        if (now - at > TTL_MS) {
+            channelHintAt.delete(key);
+            hintedChannels.delete(key);
+        }
+    }
+}
+function messageMentionsBot(message) {
+    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) {
+    const t = raw.trim();
+    return t.startsWith('/') || /^(游戏|game|帮助|help|签到|stats)\b/i.test(t);
+}
+/**
+ * 群聊首次 @ 且非命令时提示 /游戏 /帮助（每频道 24h 最多一次）
+ */
+export function mountFirstAtHintMiddleware(root) {
+    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() {
+    hintedChannels.clear();
+    channelHintAt.clear();
+}
+//# sourceMappingURL=game-onboarding.js.map

package/lib/game-onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-onboarding.js","sourceRoot":"","sources":["../src/game-onboarding.ts"],"names":[],"mappings":"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"}

package/lib/game-records.d.ts

@@ -0,0 +1,52 @@
+import { type DatabaseFeature, type Message, type Models, type Plugin } from '@zhin.js/core';
+import { type HostGameDbSource } from './memory-db.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'];
+export declare function registerGameRecordModels(plugin: Plugin): void;
+export declare function initGameRecordDatabase(dbFeature: DatabaseFeature): void;
+/** 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 declare function initGameRecordHost(host: GameRecordDatabaseHost): () => void;
+/** 对局结束时写入战绩（database 未就绪时静默跳过） */
+export declare function recordGameOutcome(message: Message<any>, gameId: string, result: GameRecordResult, score?: number): Promise<void>;
+export interface UserGameStats {
+    gameId: string;
+    wins: number;
+    losses: number;
+    draws: number;
+    totalScore: number;
+    games: number;
+}
+export declare function getUserGameStats(userId: string, channelKeyFilter?: string): Promise<UserGameStats[]>;
+export interface LeaderboardEntry {
+    userId: string;
+    userName: string;
+    wins: number;
+    totalScore: number;
+    games: number;
+}
+export declare function getGameLeaderboard(gameId: string, channelKeyFilter: string, limit?: number): Promise<LeaderboardEntry[]>;
+export declare function mountGameRecordCommands(root: Plugin): () => void;
+/** 测试专用 */
+export declare function resetGameRecordsForTests(): void;
+//# sourceMappingURL=game-records.d.ts.map

package/lib/game-records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-records.d.ts","sourceRoot":"","sources":["../src/game-records.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,MAAM,EACX,KAAK,MAAM,EAEZ,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGzE,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAEnE,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,MAAM;QACd,YAAY,EAAE;YACZ,EAAE,EAAE,MAAM,CAAC;YACX,OAAO,EAAE,MAAM,CAAC;YAChB,SAAS,EAAE,MAAM,CAAC;YAClB,WAAW,EAAE,MAAM,CAAC;YACpB,OAAO,EAAE,MAAM,CAAC;YAChB,MAAM,EAAE,gBAAgB,CAAC;YACzB,KAAK,EAAE,MAAM,CAAC;YACd,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC;KACH;CACF;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AAoBnD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAW7D;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI,CAEvE;AAaD,uFAAuF;AACvF,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACjE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,IAAI,CAa3E;AAMD,mCAAmC;AACnC,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EACrB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,gBAAgB,EACxB,KAAK,SAAI,GACR,OAAO,CAAC,IAAI,CAAC,CAcf;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,aAAa,EAAE,CAAC,CA4B1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,KAAK,SAAK,GACT,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA2B7B;AA2BD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI,CA0ChE;AAED,WAAW;AACX,wBAAgB,wBAAwB,IAAI,IAAI,CAI/C"}