@zhin.js/game-kit 1.0.1

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@zhin.js/game-kit",
+  "version": "1.0.1",
+  "description": "Zhin.js 游戏插件通用工具包",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "zhin.js": "^4.1.2",
+    "@zhin.js/html-renderer": "1.0.3"
+  },
+  "peerDependenciesMeta": {
+    "@zhin.js/html-renderer": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@zhin.js/core": "1.3.4",
+    "@zhin.js/satori": "1.0.16",
+    "@zhin.js/middleware": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "zhin.js": "4.1.2"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/game-kit"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/board-sender.ts

@@ -0,0 +1,16 @@
+/**
+ * 游戏棋盘消息辅助工具
+ * 提供会话键生成和消息 ID 更新回调封装
+ *
+ * 注意：实际的发送/编辑逻辑由 Adapter.editMessage 统一处理
+ * - 支持编辑的平台：调用平台 API 编辑
+ * - 不支持编辑的平台：自动 fallback 到发送新消息
+ */
+import type { Message } from '@zhin.js/core';
+
+/**
+ * 构建频道唯一键（用于会话查找）
+ */
+export function channelKey(message: Message<any>): string {
+  return `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+}

package/src/choice-keyboard.ts

@@ -0,0 +1,117 @@
+/**
+ * 选项式交互键盘（文字冒险、问答、剧情分支等）
+ */
+import { segment, type SendContent } from '@zhin.js/core';
+import { applyInteractionProfile, type InteractionProfile } from './interaction-profiles.js';
+
+export interface ChoiceOption {
+  /** 选项 ID，写入 payload */
+  id: string;
+  label: string;
+  disabled?: boolean;
+  style?: 'primary' | 'danger' | 'secondary';
+  /** 终局菜单（如「再来一局」）保持可点 */
+  keepEnabledWhenTerminal?: boolean;
+}
+
+export interface ChoiceKeyboardOptions {
+  gamePrefix: string;
+  sessionId: string;
+  /** 剧情/题干正文 */
+  narrative: string;
+  choices: ChoiceOption[];
+  terminal?: boolean;
+  /** 文本 fallback 提示 */
+  fallbackHint?: string;
+  /** 每行最多几个按钮（默认全部一行） */
+  buttonsPerRow?: number;
+  /** 交互 profile：menu→command，gameplay→callback，terminal→command */
+  interactionProfile?: InteractionProfile;
+  /** terminal profile 私聊 auto-enter 用 */
+  channelType?: string;
+}
+
+export function buildChoiceFallbackMap(
+  gamePrefix: string,
+  sessionId: string,
+  choices: ChoiceOption[],
+): Record<string, string> {
+  const map: Record<string, string> = {};
+  let n = 1;
+  for (const choice of choices) {
+    if (!choice.disabled) {
+      map[String(n)] = `${gamePrefix}:${sessionId}:${choice.id}`;
+      n++;
+    }
+  }
+  return map;
+}
+
+function chunkChoices<T>(items: T[], size: number): T[][] {
+  if (size <= 0 || items.length <= size) return [items];
+  const rows: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    rows.push(items.slice(i, i + size));
+  }
+  return rows;
+}
+
+/**
+ * 构建选项键盘消息：正文 + 一行或多行按钮
+ */
+export function buildChoiceKeyboard(options: ChoiceKeyboardOptions): SendContent {
+  const {
+    gamePrefix,
+    sessionId,
+    narrative,
+    choices,
+    terminal,
+    fallbackHint,
+    buttonsPerRow,
+    interactionProfile,
+    channelType,
+  } = options;
+
+  const enabled = choices.filter((c) => !c.disabled);
+  const buttonRows = chunkChoices(enabled, buttonsPerRow ?? enabled.length).map((row) =>
+    row.map((choice) => {
+      const base = segment.button({
+        id: choice.id,
+        label: choice.label,
+        payload: `${gamePrefix}:${sessionId}:${choice.id}`,
+        disabled: choice.disabled || (terminal && !choice.keepEnabledWhenTerminal),
+        style: choice.style ?? 'secondary',
+      });
+      const data = base.data;
+      if (!interactionProfile) return base;
+      return segment.button(
+        applyInteractionProfile(data, { profile: interactionProfile, channelType }),
+      );
+    }),
+  );
+
+  const fallback = buildChoiceFallbackMap(gamePrefix, sessionId, choices);
+
+  return [
+    segment.text(narrative),
+    segment.keyboard(buttonRows, {
+      fallback: fallbackHint && Object.keys(fallback).length > 0
+        ? { hint: fallbackHint, map: fallback }
+        : undefined,
+    }).toElement(),
+  ];
+}
+
+/**
+ * 解析选项 payload：`{prefix}:{sessionId}:{choiceId}`
+ */
+export function parseChoicePayload(
+  payload: string,
+  expectedPrefix?: string,
+): { prefix: string; sessionId: string; choiceId: string } | null {
+  const m = /^([a-z0-9_]+):([^:]+):([a-z0-9_-]+)$/i.exec(payload);
+  if (!m) return null;
+  const prefix = m[1]!;
+  if (expectedPrefix && prefix !== expectedPrefix) return null;
+  return { prefix, sessionId: m[2]!, choiceId: m[3]! };
+}

package/src/command-alias.ts

@@ -0,0 +1,45 @@
+import { defineMiddleware, type MiddlewareContext } from '@zhin.js/middleware';
+import type { Message } from '@zhin.js/core/runtime';
+
+/**
+ * 游戏 legacy 命令别名路由。
+ *
+ * 插件运行时迁移后，约定式命令以 `<instanceKey> <localName>` 限定名注册（ADR 0043），
+ * 旧的短命令（如 `/21点 开始`、`/猜数 开始`）在 runtime 中不存在。
+ * 各游戏插件用本 helper 在 `middlewares/` 下注册一个入站中间件，
+ * 把命中别名的首词消息转发到与限定名命令完全相同的处理逻辑。
+ */
+export interface GameCommandAliasRoute {
+  /** 首词命中即接管（不含前导 `/`），如 `['21点', 'bj']`。 */
+  readonly aliases: readonly string[];
+  /**
+   * 与 `commands/<cmd>/[action:string=].ts` 的 execute 逻辑保持一致：
+   * action 为别名后剩余文本（无参数时为 ''）；返回回复文本，null/undefined 表示放行。
+   */
+  run(
+    action: string,
+    input: unknown,
+    context: MiddlewareContext<Message>,
+  ): Promise<string | null | undefined>;
+}
+
+export function defineGameCommandAliasMiddleware(route: GameCommandAliasRoute) {
+  return defineMiddleware<Message>({
+    target: 'inbound',
+    async handle(context, next) {
+      const raw = context.input.content?.trim() ?? '';
+      const text = raw.startsWith('/') ? raw.slice(1) : raw;
+      const [head, ...rest] = text.split(/\s+/).filter(Boolean);
+      if (!head || !route.aliases.includes(head)) {
+        await next();
+        return;
+      }
+      const reply = await route.run(rest.join(' '), context.input, context);
+      if (reply) {
+        await context.input.$reply(reply);
+        return;
+      }
+      await next();
+    },
+  });
+}

package/src/command-help.ts

@@ -0,0 +1,117 @@
+import type { Message, MessageCommand, Plugin } from '@zhin.js/core';
+import type { RegisteredGame } from './game-hub-feature.js';
+
+export interface CommandHelpSource {
+  pattern: string;
+  helpInfo: {
+    desc: string[];
+    usage?: string[];
+    examples?: string[];
+  };
+}
+
+export function commandToHelpSource(cmd: Pick<MessageCommand, 'pattern' | 'helpInfo'>): CommandHelpSource {
+  return { pattern: cmd.pattern, helpInfo: cmd.helpInfo };
+}
+
+/** 按 MessageCommand.permit 与当前消息上下文过滤（与 handle 一致） */
+export async function filterHelpCommands(
+  commands: readonly MessageCommand[],
+  message: Message<any>,
+  plugin: Plugin,
+): Promise<CommandHelpSource[]> {
+  const out: CommandHelpSource[] = [];
+  for (const cmd of commands) {
+    if (await cmd.checkPermits(message, plugin)) {
+      out.push(commandToHelpSource(cmd));
+    }
+  }
+  return out;
+}
+
+function commandLeadingToken(pattern: string): string {
+  return pattern.split(/\s/)[0] ?? '';
+}
+
+function normalizeToken(token: string): string {
+  return token.replace(/^\//, '').toLowerCase();
+}
+
+/** 不在「其他命令」中重复展示的 pattern（大厅入口 / 帮助自身） */
+const HELP_EXCLUDE_EXACT = new Set([
+  '/帮助',
+  '/help',
+  '帮助',
+  '/游戏 帮助',
+  '/游戏',
+  '/game',
+  '游戏',
+  'game',
+]);
+
+function isHubListedGameCommand(pattern: string, games: readonly RegisteredGame[]): boolean {
+  const lead = normalizeToken(commandLeadingToken(pattern));
+  return games.some((g) => normalizeToken(g.commandPrefix) === lead);
+}
+
+function comparePatterns(a: string, b: string): number {
+  const leadDiff = commandLeadingToken(b).length - commandLeadingToken(a).length;
+  if (leadDiff !== 0) return leadDiff;
+  return b.length - a.length;
+}
+
+function formatPatternDisplay(pattern: string): string {
+  return `\`${pattern}\``;
+}
+
+function formatCommandHelpLine(cmd: CommandHelpSource): string {
+  const [label = '', detail = ''] = cmd.helpInfo.desc;
+  const display = formatPatternDisplay(cmd.pattern);
+  const summary = detail || label || cmd.pattern;
+  if (label && label !== commandLeadingToken(cmd.pattern) && !cmd.pattern.startsWith(label)) {
+    return `• ${display}（${label}）— ${summary}`;
+  }
+  return `• ${display} — ${summary}`;
+}
+
+/** 从 command 服务收集应在 /帮助 中展示的命令（去重、排除已在游戏大厅列出的项） */
+export function collectSupplementaryCommandHelp(
+  commands: readonly CommandHelpSource[],
+  games: readonly RegisteredGame[],
+): CommandHelpSource[] {
+  const seen = new Set<string>();
+  const out: CommandHelpSource[] = [];
+  for (const cmd of [...commands].sort((a, b) => comparePatterns(a.pattern, b.pattern))) {
+    if (HELP_EXCLUDE_EXACT.has(cmd.pattern)) continue;
+    if (isHubListedGameCommand(cmd.pattern, games)) continue;
+    if (seen.has(cmd.pattern)) continue;
+    seen.add(cmd.pattern);
+    out.push(cmd);
+  }
+  return out;
+}
+
+export function formatSupplementaryCommandsHelp(
+  commands: readonly CommandHelpSource[],
+  games: readonly RegisteredGame[],
+): string {
+  const items = collectSupplementaryCommandHelp(commands, games);
+  if (!items.length) return '';
+  const lines = items.map(formatCommandHelpLine);
+  return ['**其他命令**', '', ...lines].join('\n');
+}
+
+/** 大厅入口行：从已注册命令的 .desc() 生成 */
+export function formatHubOpenCommandLines(
+  commands: readonly CommandHelpSource[] | undefined,
+): string[] {
+  if (!commands?.length) return [];
+  const lines: string[] = [];
+  for (const pattern of ['/游戏', '/game'] as const) {
+    const cmd = commands.find((c) => c.pattern === pattern);
+    if (!cmd) continue;
+    const desc = cmd.helpInfo.desc[0] ?? cmd.helpInfo.desc[1] ?? '';
+    if (desc) lines.push(`${pattern} — ${desc}`);
+  }
+  return lines;
+}

package/src/command-message.ts

@@ -0,0 +1,76 @@
+/**
+ * Map Plugin Runtime CommandContext.input → classic Message-like shape used by game SessionService.
+ *
+ * Runtime Message: { adapter, target, sender?, metadata? }
+ * Classic Message: { $adapter, $endpoint, $channel, $sender }
+ */
+
+export interface GameMessageLike {
+  $adapter: string;
+  $endpoint: string;
+  $channel: { type: string; id: string };
+  $sender: { id: string; name: string };
+}
+
+function isClassicMessage(input: unknown): input is GameMessageLike {
+  if (!input || typeof input !== 'object') return false;
+  const m = input as Record<string, unknown>;
+  return (
+    typeof m.$adapter === 'string' &&
+    m.$channel != null &&
+    typeof m.$channel === 'object' &&
+    m.$sender != null &&
+    typeof m.$sender === 'object'
+  );
+}
+
+function isRuntimeMessage(input: unknown): input is {
+  adapter?: string;
+  target?: string;
+  sender?: string;
+  metadata?: Readonly<Record<string, unknown>>;
+} {
+  if (!input || typeof input !== 'object') return false;
+  const m = input as Record<string, unknown>;
+  return (
+    'adapter' in m ||
+    'target' in m ||
+    'sender' in m ||
+    (m.metadata != null && typeof m.metadata === 'object')
+  );
+}
+
+/** Smoke message when CommandContext has no usable input (unit tests / CLI). */
+export function smokeGameMessage(): GameMessageLike {
+  return {
+    $adapter: 'runtime',
+    $endpoint: 'default',
+    $channel: { type: 'private', id: 'smoke' },
+    $sender: { id: 'smoke', name: 'smoke' },
+  };
+}
+
+/**
+ * Convert CommandContext.input to a Message-like object for game-flow / *-command.
+ */
+export function messageFromCommandInput(input: unknown): GameMessageLike {
+  if (isClassicMessage(input)) return input;
+
+  if (isRuntimeMessage(input)) {
+    const meta = input.metadata ?? {};
+    const adapter = String(input.adapter ?? meta.adapter ?? 'runtime');
+    const endpoint = String(meta.endpoint ?? meta.endpointId ?? 'default');
+    const channelType = String(meta.type ?? meta.channelType ?? 'private');
+    const channelId = String(input.target ?? meta.channelId ?? 'smoke');
+    const senderId = String(input.sender ?? meta.senderId ?? 'smoke');
+    const senderName = String(meta.senderName ?? meta.name ?? senderId);
+    return {
+      $adapter: adapter,
+      $endpoint: endpoint,
+      $channel: { type: channelType, id: channelId },
+      $sender: { id: senderId, name: senderName },
+    };
+  }
+
+  return smokeGameMessage();
+}

package/src/game-action-alias.ts

@@ -0,0 +1,129 @@
+const TTT_ACTIONS: Record<string, string> = {
+  bot: 'bot',
+  join: 'join',
+  leave: 'leave',
+  quit: 'quit',
+  spectate: 'spectate',
+  help: 'help',
+  人机: 'bot',
+  排队: 'join',
+  加入: 'join',
+  离开: 'leave',
+  认输: 'quit',
+  观战: 'spectate',
+  帮助: 'help',
+};
+
+const ADV_ACTIONS: Record<string, string> = {
+  start: 'start',
+  continue: 'continue',
+  map: 'map',
+  achievements: 'achievements',
+  achievement: 'achievements',
+  quit: 'quit',
+  help: 'help',
+  开始: 'start',
+  继续: 'continue',
+  地图: 'map',
+  成就: 'achievements',
+  放弃: 'quit',
+  退出: 'quit',
+  帮助: 'help',
+};
+
+const RPS_ACTIONS: Record<string, string> = {
+  start: 'start',
+  continue: 'continue',
+  quit: 'quit',
+  help: 'help',
+  开始: 'start',
+  继续: 'continue',
+  放弃: 'quit',
+  帮助: 'help',
+};
+
+const GUESS_ACTIONS: Record<string, string> = {
+  start: 'start',
+  quit: 'quit',
+  help: 'help',
+  开始: 'start',
+  放弃: 'quit',
+  帮助: 'help',
+};
+
+const DICE_ACTIONS: Record<string, string> = {
+  start: 'start',
+  continue: 'continue',
+  quit: 'quit',
+  help: 'help',
+  开始: 'start',
+  继续: 'continue',
+  放弃: 'quit',
+  帮助: 'help',
+};
+
+function lookup(map: Record<string, string>, raw: string): string {
+  const t = raw.trim();
+  if (!t) return 'help';
+  return map[t] ?? map[t.toLowerCase()] ?? t.toLowerCase();
+}
+
+export function normalizeTttAction(raw: string): string {
+  return lookup(TTT_ACTIONS, raw);
+}
+
+export function normalizeAdvAction(raw: string): string {
+  return lookup(ADV_ACTIONS, raw);
+}
+
+export function normalizeRpsAction(raw: string): string {
+  return lookup(RPS_ACTIONS, raw);
+}
+
+export function normalizeGuessAction(raw: string): string {
+  return lookup(GUESS_ACTIONS, raw);
+}
+
+export function normalizeDiceAction(raw: string): string {
+  return lookup(DICE_ACTIONS, raw);
+}
+
+const CHAIN_ACTIONS: Record<string, string> = {
+  start: 'start_pinyin',
+  start_pinyin: 'start_pinyin',
+  start_char: 'start_char',
+  continue: 'continue',
+  quit: 'quit',
+  help: 'help',
+  pinyin: 'start_pinyin',
+  char: 'start_char',
+  开始: 'start_pinyin',
+  同音: 'start_pinyin',
+  同字: 'start_char',
+  继续: 'continue',
+  放弃: 'quit',
+  帮助: 'help',
+};
+
+const RIDDLE_ACTIONS: Record<string, string> = {
+  start: 'start',
+  continue: 'continue',
+  quit: 'quit',
+  help: 'help',
+  char: 'char',
+  idiom: 'idiom',
+  开始: 'start',
+  继续: 'continue',
+  放弃: 'quit',
+  帮助: 'help',
+  字谜: 'char',
+  成语: 'idiom',
+};
+
+export function normalizeChainAction(raw: string): string {
+  return lookup(CHAIN_ACTIONS, raw);
+}
+
+export function normalizeRiddleAction(raw: string): string {
+  return lookup(RIDDLE_ACTIONS, raw);
+}

package/src/game-commands.ts

@@ -0,0 +1,4 @@
+/** 展示用：`/猜拳` */
+export function slashCommandPrefix(name: string): string {
+  return name.startsWith('/') ? name : `/${name}`;
+}