@zhin.js/plugin-tic-tac-toe 1.0.0

package/src/board-view.ts

@@ -0,0 +1,93 @@
+import type { Message, SendContent } from 'zhin.js';
+import {
+  buildGridKeyboard,
+  buildGridFallbackMap,
+  parseGridPayload,
+  parseCellButtonId as parseButtonId,
+  channelKey,
+  type GridCell,
+} from '@zhin.js/game-shared';
+import {
+  asciiBoard,
+  cellLabel,
+  type Board,
+  type Cell,
+  EMPTY,
+  X,
+  O,
+} from './engine.js';
+
+/** 游戏前缀（用于 payload） */
+export const TTT_PREFIX = 'ttt';
+
+export { channelKey };
+
+/** 将井字棋棋盘转为通用 GridCell 数组 */
+function boardToCells(board: Board, highlight?: number[]): GridCell<Cell>[] {
+  const highlightSet = new Set(highlight ?? []);
+  return board.map((cell, i) => ({
+    state: cell,
+    label: cell === EMPTY ? '·' : cellLabel(cell),
+    disabled: cell !== EMPTY,
+    highlight: highlightSet.has(i),
+  }));
+}
+
+/** 井字棋 ASCII 棋盘渲染器（适配 GridCell） */
+function renderTttAscii(
+  cells: GridCell<Cell>[],
+  rows: number,
+  cols: number,
+  highlight?: number[],
+): string {
+  const board = cells.map((c) => c.state);
+  return asciiBoard(board as Board, highlight);
+}
+
+export function buildBoardInteractive(options: {
+  sessionId: string;
+  board: Board;
+  statusLine: string;
+  turnMark: Cell;
+  terminal?: boolean;
+  omitAsciiBoard?: boolean;
+  highlight?: number[];
+}): SendContent {
+  const { sessionId, board, statusLine, terminal, omitAsciiBoard, highlight } = options;
+
+  return buildGridKeyboard({
+    gamePrefix: TTT_PREFIX,
+    sessionId,
+    rows: 3,
+    cols: 3,
+    cells: boardToCells(board, highlight),
+    statusLine,
+    terminal,
+    omitAsciiBoard,
+    renderAscii: renderTttAscii,
+    highlight,
+    fallbackHint: '落子：回复数字 1-9（仅空格）',
+  });
+}
+
+export function buildFallbackMap(sessionId: string, board: Board): Record<string, string> {
+  return buildGridFallbackMap(TTT_PREFIX, sessionId, boardToCells(board));
+}
+
+export function parseTttPayload(payload: string): { sessionId: string; cell: number } | null {
+  const result = parseGridPayload(payload, TTT_PREFIX);
+  if (!result) return null;
+  if (result.cell > 8) return null;
+  return { sessionId: result.sessionId, cell: result.cell };
+}
+
+/** QQ 等平台回调可能只带 button_id（如 c4），不含 ttt: 前缀 payload */
+export function parseCellButtonId(value: string): number | null {
+  const cell = parseButtonId(value);
+  if (cell === null || cell > 8) return null;
+  return cell;
+}
+
+export function markName(mark: Cell): string {
+  return mark === X ? '✕' : '○';
+}

package/src/commands.ts

@@ -0,0 +1,129 @@
+import { Message, MessageCommand, getActionFromMessage, type Plugin } from 'zhin.js';
+import { channelKey, normalizeTttAction, registerGameTextMiddleware } from '@zhin.js/game-shared';
+import { buildFallbackMap } from './board-view.js';
+import { parseBoard } from './engine.js';
+import { handleMove } from './game-flow.js';
+import { runTttCommand } from './ttt-command.js';
+import type { SessionServices } from './session-service.js';
+
+function actionPayload(message: Message<any>): string | undefined {
+  return getActionFromMessage(message)?.payload;
+}
+
+/** @deprecated 使用 game-shared parseChoicePayload；保留 ttt 专用解析 */
+function parseTttPayload(payload: string): { sessionId: string; cell: number } | null {
+  const m = /^ttt:([^:]+):(\d)$/.exec(payload);
+  if (!m) return null;
+  return { sessionId: m[1]!, cell: Number(m[2]) };
+}
+
+function parseCellButtonId(id: string): number | null {
+  const m = /^c(\d)$/.exec(id);
+  if (!m) return null;
+  const cell = Number(m[1]);
+  return cell >= 0 && cell <= 8 ? cell : null;
+}
+
+async function resolveTttMove(
+  message: Message<any>,
+  services: SessionServices,
+): Promise<{ sessionId: string; cell: number } | null> {
+  const action = getActionFromMessage(message);
+  if (!action) return null;
+
+  const fromPayload = parseTttPayload(action.payload);
+  if (fromPayload) return fromPayload;
+
+  const cell =
+    parseCellButtonId(action.payload)
+    ?? parseCellButtonId(action.id ?? '');
+  if (cell == null) return null;
+
+  const ch = channelKey(message);
+  const session =
+    await services.session.getActiveForUser(ch, message.$sender.id)
+    ?? (action.sourceMessageId
+      ? await services.session.getActiveByBoardMessageId(action.sourceMessageId)
+      : null);
+  if (!session || session.channel_key !== ch) return null;
+  return { sessionId: session.id, cell };
+}
+
+function registerTttPattern(
+  plugin: Plugin,
+  pattern: string,
+  desc: string,
+  getServices: () => SessionServices | null,
+): void {
+  plugin.addCommand(
+    new MessageCommand(pattern)
+      .desc(desc)
+      .action(async (message, result) => {
+        const services = getServices();
+        if (!services) return '井字棋需要启用 database 配置。';
+        const raw = (result.params.action as string | undefined) ?? '';
+        const action = normalizeTttAction(raw);
+        return runTttCommand(plugin, services, message, action);
+      }),
+  );
+}
+
+export function registerCommands(
+  plugin: Plugin,
+  getServices: () => SessionServices | null,
+): void {
+  registerTttPattern(plugin, 'ttt [action:word]', '井字棋（ttt）', getServices);
+  registerTttPattern(plugin, '井字棋 [action:word]', '井字棋（中文）', getServices);
+}
+
+async function handleTttAction(
+  plugin: Plugin,
+  getServices: () => SessionServices | null,
+  message: Message<any>,
+): Promise<boolean> {
+  const services = getServices();
+  if (!services) return false;
+  const move = await resolveTttMove(message, services);
+  if (!move) return false;
+  const err = await handleMove(plugin, services, message, move.sessionId, move.cell);
+  if (err) await message.$reply?.(err);
+  return true;
+}
+
+export function registerInteractive(plugin: Plugin, getServices: () => SessionServices | null): void {
+  plugin.registerInteractiveHandler('ttt:', (message) => handleTttAction(plugin, getServices, message));
+  plugin.registerInteractiveHandler('c', (message) => handleTttAction(plugin, getServices, message));
+}
+
+export function registerTextFallback(plugin: Plugin, getServices: () => SessionServices | null): void {
+  registerGameTextMiddleware(plugin, async (message, next) => {
+    const services = getServices();
+    if (!services) return next();
+
+    const inboundAction = actionPayload(message);
+    if (inboundAction?.startsWith('ttt:')) return next();
+
+    const ch = channelKey(message);
+    const session = await services.session.getActiveForUser(ch, message.$sender.id);
+    if (!session) return next();
+
+    const raw = message.$raw?.trim() ?? '';
+    let cell: number | null = null;
+    const direct = parseTttPayload(raw.startsWith('ttt:') ? raw : '');
+    if (direct && direct.sessionId === session.id) {
+      cell = direct.cell;
+    } else {
+      const n = /^(\d)$/.exec(raw);
+      if (n) {
+        const map = buildFallbackMap(session.id, parseBoard(session.board));
+        const payload = map[n[1]!];
+        const p = payload ? parseTttPayload(payload) : null;
+        if (p?.sessionId === session.id) cell = p.cell;
+      }
+    }
+    if (cell == null) return next();
+
+    const err = await handleMove(plugin, services, message, session.id, cell);
+    if (err) await message.$reply?.(err);
+  }, 'ttt:text');
+}

package/src/engine.ts

@@ -0,0 +1,131 @@
+export const EMPTY = 0;
+export const X = 1;
+export const O = 2;
+
+export type Cell = typeof EMPTY | typeof X | typeof O;
+export type Board = Cell[];
+
+export type GameStatus = 'active' | 'won' | 'draw' | 'aborted';
+
+const WIN_LINES = [
+  [0, 1, 2], [3, 4, 5], [6, 7, 8],
+  [0, 3, 6], [1, 4, 7], [2, 5, 8],
+  [0, 4, 8], [2, 4, 6],
+];
+
+export function emptyBoard(): Board {
+  return Array(9).fill(EMPTY);
+}
+
+export function parseBoard(raw: string | number[] | null | undefined): Board {
+  if (Array.isArray(raw)) return raw.map((v) => Number(v) as Cell);
+  if (typeof raw === 'string') {
+    try {
+      const parsed = JSON.parse(raw) as number[];
+      if (Array.isArray(parsed) && parsed.length === 9) {
+        return parsed.map((v) => Number(v) as Cell);
+      }
+    } catch {
+      // fall through
+    }
+  }
+  return emptyBoard();
+}
+
+export function cellLabel(cell: Cell): string {
+  if (cell === X) return '✕';
+  if (cell === O) return '○';
+  return '·';
+}
+
+export function asciiBoard(board: Board, highlight?: number[]): string {
+  const mark = (i: number) => {
+    const base = cellLabel(board[i]!);
+    return highlight?.includes(i) ? `[${base}]` : ` ${base} `;
+  };
+  return [
+    `${mark(0)}|${mark(1)}|${mark(2)}`,
+    '-+-+-',
+    `${mark(3)}|${mark(4)}|${mark(5)}`,
+    '-+-+-',
+    `${mark(6)}|${mark(7)}|${mark(8)}`,
+  ].join('\n');
+}
+
+export function checkWinner(board: Board): { winner: Cell; line: number[] } | null {
+  for (const line of WIN_LINES) {
+    const [a, b, c] = line;
+    const v = board[a!]!;
+    if (v !== EMPTY && v === board[b!] && v === board[c!]) {
+      return { winner: v, line };
+    }
+  }
+  return null;
+}
+
+export function isDraw(board: Board): boolean {
+  return board.every((c) => c !== EMPTY) && !checkWinner(board);
+}
+
+export function validMove(board: Board, cell: number): boolean {
+  return Number.isInteger(cell) && cell >= 0 && cell < 9 && board[cell] === EMPTY;
+}
+
+export function applyMove(board: Board, cell: number, player: Cell): Board {
+  if (!validMove(board, cell)) throw new Error('invalid move');
+  const next = [...board] as Board;
+  next[cell] = player;
+  return next;
+}
+
+export function opponent(player: Cell): Cell {
+  return player === X ? O : X;
+}
+
+/** Minimax for tic-tac-toe (O = AI by default when aiPlays O) */
+export function bestMove(board: Board, ai: Cell = O): number {
+  const human = opponent(ai);
+  let bestScore = -Infinity;
+  let move = -1;
+
+  for (let i = 0; i < 9; i++) {
+    if (board[i] !== EMPTY) continue;
+    const next = applyMove(board, i, ai);
+    const score = minimax(next, 0, false, ai, human);
+    if (score > bestScore) {
+      bestScore = score;
+      move = i;
+    }
+  }
+  return move;
+}
+
+function minimax(
+  board: Board,
+  depth: number,
+  isAi: boolean,
+  ai: Cell,
+  human: Cell,
+): number {
+  const win = checkWinner(board);
+  if (win?.winner === ai) return 10 - depth;
+  if (win?.winner === human) return depth - 10;
+  if (isDraw(board)) return 0;
+
+  const player = isAi ? ai : human;
+  let best = isAi ? -Infinity : Infinity;
+
+  for (let i = 0; i < 9; i++) {
+    if (board[i] !== EMPTY) continue;
+    const next = applyMove(board, i, player);
+    const score = minimax(next, depth + 1, !isAi, ai, human);
+    best = isAi ? Math.max(best, score) : Math.min(best, score);
+  }
+  return best;
+}
+
+export function playerMark(playerId: string, session: { playerX: string; playerO: string }): Cell | null {
+  if (playerId === session.playerX) return X;
+  if (playerId === session.playerO) return O;
+  return null;
+}

package/src/game-flow.ts

@@ -0,0 +1,217 @@
+import type { Adapter, Message, Plugin } from 'zhin.js';
+import type { TttSessionRow } from './models.js';
+import { buildBoardInteractive } from './board-view.js';
+import {
+  applyMove,
+  bestMove,
+  checkWinner,
+  isDraw,
+  parseBoard,
+  playerMark,
+  validMove,
+  X,
+  O,
+  type Cell,
+  cellLabel,
+} from './engine.js';
+import {
+  BOT_ID,
+  formatPlayerWithMark,
+  formatRosterLine,
+  formatTurnStatus,
+  formatWinHeadline,
+  playerRefForMark,
+  senderDisplayName,
+} from './player-label.js';
+import type { SessionServices, TttPlayerRef } from './session-service.js';
+
+export { BOT_ID };
+
+export function isBotSession(session: TttSessionRow): boolean {
+  return session.player_o === BOT_ID || session.player_x === BOT_ID;
+}
+
+export async function sendOrEditBoard(
+  plugin: Plugin,
+  services: SessionServices,
+  message: Message<any>,
+  session: TttSessionRow,
+  statusLine: string,
+  terminal = false,
+  highlight?: number[],
+): Promise<string> {
+  const board = parseBoard(session.board);
+  const content = buildBoardInteractive({
+    sessionId: session.id,
+    board,
+    statusLine,
+    turnMark: session.turn as Cell,
+    terminal,
+    omitAsciiBoard: message.$adapter === 'qq',
+    highlight,
+  });
+
+  const adapter = plugin.root.inject(message.$adapter) as Adapter;
+
+  if (session.board_message_id) {
+    const msgId = await adapter.editMessage({
+      messageId: session.board_message_id,
+      context: String(message.$adapter),
+      endpoint: message.$endpoint,
+      id: message.$channel.id,
+      type: message.$channel.type,
+      content,
+    });
+    if (msgId !== session.board_message_id) {
+      await services.session.updateSession(session.id, { board_message_id: msgId });
+    }
+    return msgId;
+  }
+
+  const msgId = await message.$reply?.(content);
+  if (msgId) {
+    await services.session.updateSession(session.id, { board_message_id: msgId });
+  }
+  return msgId ?? '';
+}
+
+function turnCell(session: TttSessionRow): Cell {
+  return session.turn === 1 ? X : O;
+}
+
+function playerIdForTurn(session: TttSessionRow): string {
+  return session.turn === 1 ? session.player_x : session.player_o;
+}
+
+export async function handleMove(
+  plugin: Plugin,
+  services: SessionServices,
+  message: Message<any>,
+  sessionId: string,
+  cell: number,
+): Promise<string | null> {
+  const session = await services.session.getById(sessionId);
+  if (!session || session.status !== 'active') {
+    return '对局不存在或已结束。';
+  }
+  if (session.channel_key !== `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`) {
+    return '请在开局频道落子。';
+  }
+
+  const mark = playerMark(message.$sender.id, {
+    playerX: session.player_x,
+    playerO: session.player_o,
+  });
+  if (!mark) {
+    return '你不是本局玩家。';
+  }
+  if (mark !== turnCell(session)) {
+    const turn = turnCell(session);
+    const { id, name } = playerRefForMark(session, turn);
+    return `还没轮到你（当前轮到 ${formatPlayerWithMark(id, name, cellLabel(turn) as '✕' | '○')}）。`;
+  }
+
+  const board = parseBoard(session.board);
+  if (!validMove(board, cell)) {
+    return '该位置不可落子。';
+  }
+
+  const nextBoard = applyMove(board, cell, mark);
+  const win = checkWinner(nextBoard);
+  const draw = !win && isDraw(nextBoard);
+  const moveCount = session.move_count + 1;
+
+  await services.session.recordMove(session.id, message.$sender.id, cell, moveCount);
+  await services.session.updateSession(session.id, {
+    board: JSON.stringify(nextBoard),
+    move_count: moveCount,
+    turn: session.turn === 1 ? 2 : 1,
+    status: win ? 'won' : draw ? 'draw' : 'active',
+    winner: win ? win.winner : 0,
+  });
+
+  const updated = (await services.session.getById(session.id))!;
+
+  if (win) {
+    const status = formatWinHeadline(updated, win.winner);
+    await sendOrEditBoard(plugin, services, message, updated, status, true, win.line);
+    return null;
+  }
+  if (draw) {
+    await sendOrEditBoard(plugin, services, message, updated, '平局。', true);
+    return null;
+  }
+
+  // 人机：玩家落子后立刻由服务端代下，避免先发「轮到机器人」再发终盘（QQ 被动消息多耗一次）
+  if (isBotSession(updated) && playerIdForTurn(updated) === BOT_ID) {
+    await runBotMove(plugin, services, message, updated);
+    return null;
+  }
+
+  const status = formatTurnStatus(updated, moveCount);
+  await sendOrEditBoard(plugin, services, message, updated, status, false);
+
+  return null;
+}
+
+async function runBotMove(
+  plugin: Plugin,
+  services: SessionServices,
+  message: Message<any>,
+  session: TttSessionRow,
+): Promise<void> {
+  const board = parseBoard(session.board);
+  const aiMark = session.player_o === BOT_ID ? O : X;
+  const cell = bestMove(board, aiMark);
+  if (cell < 0) return;
+
+  const fakeMessage = {
+    ...message,
+    $sender: { ...message.$sender, id: BOT_ID, name: '机器人' },
+  } as Message<any>;
+
+  await handleMove(plugin, services, fakeMessage, session.id, cell);
+}
+
+export async function startBotGame(
+  plugin: Plugin,
+  services: SessionServices,
+  message: Message<any>,
+): Promise<string> {
+  const ch = `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+  const active = await services.session.getActiveByChannel(ch);
+  if (active) return '当前频道已有进行中的对局。';
+
+  const session = await services.session.createSession({
+    message,
+    playerX: message.$sender.id,
+    playerO: BOT_ID,
+    playerXName: senderDisplayName(message.$sender),
+    playerOName: '机器人',
+    boardJson: JSON.stringify([0, 0, 0, 0, 0, 0, 0, 0, 0]),
+  });
+
+  const status = `${formatRosterLine(session)} · 你先手 (✕)`;
+  await sendOrEditBoard(plugin, services, message, session, status, false);
+  return '开局成功！点击棋盘或回复数字落子。';
+}
+
+export async function startPvpGame(
+  plugin: Plugin,
+  services: SessionServices,
+  message: Message<any>,
+  playerX: TttPlayerRef,
+  playerO: TttPlayerRef,
+): Promise<void> {
+  const session = await services.session.createSession({
+    message,
+    playerX: playerX.id,
+    playerO: playerO.id,
+    playerXName: playerX.displayName,
+    playerOName: playerO.displayName,
+    boardJson: JSON.stringify([0, 0, 0, 0, 0, 0, 0, 0, 0]),
+  });
+  const opener = formatPlayerWithMark(session.player_x, session.player_x_name, '✕');
+  const status = `${formatRosterLine(session)} · 先手：${opener}`;
+  await sendOrEditBoard(plugin, services, message, session, status, false);
+}

package/src/hub-register.ts

@@ -0,0 +1,31 @@
+import { getPlugin } from 'zhin.js';
+import { ensureGameHubService } from '@zhin.js/game-shared';
+import { runTttCommand, TTT_HELP } from './ttt-command.js';
+import type { SessionServices } from './session-service.js';
+
+export function registerTttHub(getServices: () => SessionServices | null): () => void {
+  const plugin = getPlugin();
+  ensureGameHubService(plugin);
+  return plugin.registerGame({
+    id: 'ttt',
+    title: '井字棋',
+    icon: '♟️',
+    description: '三子连珠，群聊排队或人机对战',
+    commandPrefix: '井字棋',
+    quickStart: '人机',
+    aliases: ['ttt'],
+    menus: [
+      { id: 'bot', label: '🤖 人机对战', style: 'primary' },
+      { id: 'join', label: '👥 加入排队', groupOnly: true },
+      { id: 'spectate', label: '👀 观战', groupOnly: true },
+      { id: 'help', label: '📖 玩法说明' },
+    ],
+    runAction: async (actionId, ctx) => {
+      const services = getServices();
+      if (!services) return '井字棋需要启用 database 配置。';
+      return runTttCommand(ctx.plugin, services, ctx.message, actionId);
+    },
+  });
+}
+
+export { TTT_HELP };

package/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @zhin.js/plugin-tic-tac-toe — 跨平台井字棋
+ *
+ * ```yaml
+ * plugins:
+ *   - "@zhin.js/plugin-tic-tac-toe"
+ * database:
+ *   dialect: sqlite
+ *   storage: ./data/zhin.db
+ * ```
+ */
+import { Cron, formatCompact, usePlugin, type DatabaseFeature } from 'zhin.js';
+import { registerModels } from './models.js';
+import { createServices, resolveGameDatabase, type SessionServices } from './session-service.js';
+import { registerCommands, registerInteractive, registerTextFallback } from './commands.js';
+import { registerTttHub } from './hub-register.js';
+
+const plugin = usePlugin();
+const { logger, useContext, addCron } = plugin;
+
+registerModels(plugin);
+
+let services: SessionServices | null = null;
+
+useContext('database', (dbFeature: DatabaseFeature) => {
+  services = createServices(resolveGameDatabase(dbFeature));
+  logger.info(formatCompact({ 模块: '井字棋', 数据模型: '已就绪' }));
+});
+
+registerTttHub(() => services);
+registerCommands(plugin, () => services);
+registerInteractive(plugin, () => services);
+registerTextFallback(plugin, () => services);
+
+addCron(
+  new Cron('0 */10 * * * *', async () => {
+    if (!services) return;
+    const n = await services.session.abortStale(30 * 60 * 1000);
+    if (n > 0) logger.debug(formatCompact({ 井字棋: '清理超时局', count: n }));
+  }),
+);
+
+logger.info(formatCompact({ 模块: '井字棋', 状态: '已加载' }));