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

package/src/models.ts

@@ -0,0 +1,104 @@
+import type { Models, Plugin } from 'zhin.js';
+
+export type TttSessionStatus = 'active' | 'won' | 'draw' | 'aborted';
+
+declare module 'zhin.js' {
+  interface Models {
+    ttt_sessions: {
+      id: string;
+      adapter: string;
+      endpoint: string;
+      channel_type: string;
+      channel_id: string;
+      channel_key: string;
+      player_x: string;
+      player_o: string;
+      player_x_name: string;
+      player_o_name: string;
+      board: string;
+      turn: number;
+      status: TttSessionStatus;
+      winner: number;
+      board_message_id: string;
+      move_count: number;
+      updated_at: number;
+      created_at: number;
+    };
+    ttt_queue: {
+      id: number;
+      channel_key: string;
+      user_id: string;
+      user_name: string;
+      joined_at: number;
+    };
+    ttt_moves: {
+      id: number;
+      session_id: string;
+      player_id: string;
+      cell: number;
+      move_index: number;
+      created_at: number;
+    };
+    ttt_spectators: {
+      id: number;
+      session_id: string;
+      user_id: string;
+      joined_at: number;
+    };
+  }
+}
+
+export type TttSessionRow = Models['ttt_sessions'];
+export type TttQueueRow = Models['ttt_queue'];
+export type TttMoveRow = Models['ttt_moves'];
+export type TttSpectatorRow = Models['ttt_spectators'];
+
+/** 井字棋插件注册的表名 */
+export type TttModelName = 'ttt_sessions' | 'ttt_queue' | 'ttt_moves' | 'ttt_spectators';
+
+export function registerModels(plugin: Plugin): void {
+  plugin.defineModel('ttt_sessions', {
+    id: { type: 'text', primary: true },
+    adapter: { type: 'text', nullable: false },
+    endpoint: { type: 'text', nullable: false },
+    channel_type: { type: 'text', nullable: false },
+    channel_id: { type: 'text', nullable: false },
+    channel_key: { type: 'text', nullable: false },
+    player_x: { type: 'text', nullable: false },
+    player_o: { type: 'text', nullable: false },
+    player_x_name: { type: 'text', default: '' },
+    player_o_name: { type: 'text', default: '' },
+    board: { type: 'text', default: '[]' },
+    turn: { type: 'integer', default: 1 },
+    status: { type: 'text', default: 'active' },
+    winner: { type: 'integer', default: 0 },
+    board_message_id: { type: 'text', default: '' },
+    move_count: { type: 'integer', default: 0 },
+    updated_at: { type: 'integer', default: 0 },
+    created_at: { type: 'integer', default: 0 },
+  });
+
+  plugin.defineModel('ttt_queue', {
+    id: { type: 'integer', primary: true },
+    channel_key: { type: 'text', nullable: false },
+    user_id: { type: 'text', nullable: false },
+    user_name: { type: 'text', default: '' },
+    joined_at: { type: 'integer', default: 0 },
+  });
+
+  plugin.defineModel('ttt_moves', {
+    id: { type: 'integer', primary: true },
+    session_id: { type: 'text', nullable: false },
+    player_id: { type: 'text', nullable: false },
+    cell: { type: 'integer', nullable: false },
+    move_index: { type: 'integer', nullable: false },
+    created_at: { type: 'integer', default: 0 },
+  });
+
+  plugin.defineModel('ttt_spectators', {
+    id: { type: 'integer', primary: true },
+    session_id: { type: 'text', nullable: false },
+    user_id: { type: 'text', nullable: false },
+    joined_at: { type: 'integer', default: 0 },
+  });
+}

package/src/player-label.ts

@@ -0,0 +1,48 @@
+import type { MessageSender } from 'zhin.js';
+import type { TttSessionRow } from './models.js';
+import { X, O, type Cell, cellLabel } from './engine.js';
+
+export const BOT_ID = '__ttt_bot__';
+
+export function senderDisplayName(sender: Pick<MessageSender, 'id' | 'name'>): string {
+  const name = sender.name?.trim();
+  return name || sender.id;
+}
+
+export function playerDisplayName(playerId: string, storedName?: string): string {
+  if (playerId === BOT_ID) return '机器人';
+  const name = storedName?.trim();
+  return name || playerId;
+}
+
+export function formatPlayerWithMark(
+  playerId: string,
+  storedName: string | undefined,
+  mark: '✕' | '○',
+): string {
+  return `${playerDisplayName(playerId, storedName)} (${mark})`;
+}
+
+export function formatRosterLine(session: TttSessionRow): string {
+  return `${formatPlayerWithMark(session.player_x, session.player_x_name, '✕')} vs ${formatPlayerWithMark(session.player_o, session.player_o_name, '○')}`;
+}
+
+export function playerRefForMark(session: TttSessionRow, mark: Cell): { id: string; name?: string } {
+  if (mark === X) return { id: session.player_x, name: session.player_x_name };
+  return { id: session.player_o, name: session.player_o_name };
+}
+
+export function formatTurnStatus(session: TttSessionRow, moveCount: number): string {
+  const mark = session.turn === 1 ? X : O;
+  const { id, name } = playerRefForMark(session, mark);
+  return `第 ${moveCount} 手 · 轮到 ${formatPlayerWithMark(id, name, cellLabel(mark) as '✕' | '○')}`;
+}
+
+export function formatWinHeadline(session: TttSessionRow, winner: Cell): string {
+  const { id, name } = playerRefForMark(session, winner);
+  return `🎉 ${formatPlayerWithMark(id, name, cellLabel(winner) as '✕' | '○')} 获胜！`;
+}
+
+export function formatWinStatus(session: TttSessionRow, winner: Cell, boardAscii: string): string {
+  return `${formatWinHeadline(session, winner)}\n${boardAscii}`;
+}

package/src/session-service.ts

@@ -0,0 +1,205 @@
+import type { Database, DatabaseFeature, Message, Models, RelatedModel } from 'zhin.js';
+import { channelKey } from '@zhin.js/game-shared';
+import type { TttModelName, TttSessionRow } from './models.js';
+
+/** 井字棋服务使用的数据库实例（Models 经 models.ts 模块增强） */
+export type TttDatabase = Database<unknown, Models, string>;
+
+type TttModel<K extends TttModelName> = RelatedModel<unknown, Models, K>;
+
+export type TttPlayerRef = { id: string; displayName: string };
+
+function getModel<K extends TttModelName>(db: TttDatabase, name: K): TttModel<K> {
+  const model = db.models.get(name);
+  if (!model) {
+    throw new Error(`Model ${name} is not registered`);
+  }
+  return model as TttModel<K>;
+}
+
+export class QueueService {
+  constructor(private readonly db: TttDatabase) {}
+
+  async join(
+    channel: string,
+    userId: string,
+    displayName?: string,
+  ): Promise<{ queued: boolean; position: number }> {
+    const q = getModel(this.db, 'ttt_queue');
+    const existing = await q.findAll({ channel_key: channel, user_id: userId });
+    const all = await q.findAll({ channel_key: channel });
+    all.sort((a, b) => a.joined_at - b.joined_at);
+    if (existing.length > 0) {
+      return { queued: true, position: all.findIndex((r) => r.user_id === userId) + 1 };
+    }
+    const name = displayName?.trim() || '';
+    await q.create({ channel_key: channel, user_id: userId, user_name: name, joined_at: Date.now() });
+    const after = await q.findAll({ channel_key: channel });
+    after.sort((a, b) => a.joined_at - b.joined_at);
+    return { queued: true, position: after.length };
+  }
+
+  async leave(channel: string, userId: string): Promise<boolean> {
+    const q = getModel(this.db, 'ttt_queue');
+    const rows = await q.findAll({ channel_key: channel, user_id: userId });
+    if (rows.length === 0) return false;
+    await q.deleteWhere({ channel_key: channel, user_id: userId });
+    return true;
+  }
+
+  async list(channel: string): Promise<string[]> {
+    const rows = await getModel(this.db, 'ttt_queue').findAll({ channel_key: channel });
+    return rows.map((r) => r.user_id);
+  }
+
+  async tryMatch(channel: string): Promise<[TttPlayerRef, TttPlayerRef] | null> {
+    const q = getModel(this.db, 'ttt_queue');
+    const rows = await q.findAll({ channel_key: channel });
+    rows.sort((a, b) => a.joined_at - b.joined_at);
+    if (rows.length < 2) return null;
+    await q.deleteWhere({ channel_key: channel });
+    const toRef = (userId: string, userName: string) => ({
+      id: userId,
+      displayName: userName.trim() || userId,
+    });
+    return [
+      toRef(rows[0]!.user_id, rows[0]!.user_name),
+      toRef(rows[1]!.user_id, rows[1]!.user_name),
+    ];
+  }
+
+  async count(channel: string): Promise<number> {
+    const rows = await getModel(this.db, 'ttt_queue').findAll({ channel_key: channel });
+    return rows.length;
+  }
+}
+
+export function sessionId(): string {
+  return `s${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+}
+
+export class SessionService {
+  constructor(private readonly db: TttDatabase) {}
+
+  async getActiveByChannel(channel: string): Promise<TttSessionRow | null> {
+    const rows = await getModel(this.db, 'ttt_sessions').findAll({
+      channel_key: channel,
+      status: 'active',
+    });
+    return rows[0] ?? null;
+  }
+
+  async getById(id: string): Promise<TttSessionRow | null> {
+    return getModel(this.db, 'ttt_sessions').findOne({ id });
+  }
+
+  async getActiveForUser(channel: string, userId: string): Promise<TttSessionRow | null> {
+    const row = await this.getActiveByChannel(channel);
+    if (!row) return null;
+    if (row.player_x === userId || row.player_o === userId) return row;
+    return null;
+  }
+
+  /** 根据棋盘消息 ID 查找进行中的局（QQ 等 action 带 sourceMessageId） */
+  async getActiveByBoardMessageId(messageId: string): Promise<TttSessionRow | null> {
+    if (!messageId) return null;
+    const rows = await getModel(this.db, 'ttt_sessions').findAll({ status: 'active' });
+    for (const row of rows) {
+      const stored = row.board_message_id;
+      if (!stored) continue;
+      if (stored === messageId) return row;
+      if (stored.endsWith(`:${messageId}`)) return row;
+      const tail = stored.split(':').pop();
+      if (tail && messageId.endsWith(tail)) return row;
+    }
+    return null;
+  }
+
+  async createSession(input: {
+    message: Message<any>;
+    playerX: string;
+    playerO: string;
+    playerXName?: string;
+    playerOName?: string;
+    boardJson: string;
+  }): Promise<TttSessionRow> {
+    const now = Date.now();
+    const id = sessionId();
+    const ch = channelKey(input.message);
+    const row: TttSessionRow = {
+      id,
+      adapter: String(input.message.$adapter),
+      endpoint: input.message.$endpoint,
+      channel_type: input.message.$channel.type,
+      channel_id: input.message.$channel.id,
+      channel_key: ch,
+      player_x: input.playerX,
+      player_o: input.playerO,
+      player_x_name: input.playerXName?.trim() || input.playerX,
+      player_o_name: input.playerOName?.trim() || input.playerO,
+      board: input.boardJson,
+      turn: 1,
+      status: 'active',
+      winner: 0,
+      board_message_id: '',
+      move_count: 0,
+      updated_at: now,
+      created_at: now,
+    };
+    await getModel(this.db, 'ttt_sessions').create(row);
+    return row;
+  }
+
+  async updateSession(id: string, patch: Partial<TttSessionRow>): Promise<void> {
+    await getModel(this.db, 'ttt_sessions').updateWhere(
+      { id },
+      { ...patch, updated_at: Date.now() },
+    );
+  }
+
+  async recordMove(sessionId: string, playerId: string, cell: number, moveIndex: number): Promise<void> {
+    await getModel(this.db, 'ttt_moves').create({
+      session_id: sessionId,
+      player_id: playerId,
+      cell,
+      move_index: moveIndex,
+      created_at: Date.now(),
+    });
+  }
+
+  async addSpectator(sessionId: string, userId: string): Promise<void> {
+    const sp = getModel(this.db, 'ttt_spectators');
+    const existing = await sp.findOne({ session_id: sessionId, user_id: userId });
+    if (existing) return;
+    await sp.create({ session_id: sessionId, user_id: userId, joined_at: Date.now() });
+  }
+
+  async listSpectators(sessionId: string): Promise<string[]> {
+    const rows = await getModel(this.db, 'ttt_spectators').findAll({ session_id: sessionId });
+    return rows.map((r) => r.user_id);
+  }
+
+  async abortStale(idleMs: number): Promise<number> {
+    const cutoff = Date.now() - idleMs;
+    const sessions = getModel(this.db, 'ttt_sessions');
+    const rows = await sessions.findAll({ status: 'active' });
+    let n = 0;
+    for (const row of rows) {
+      if (row.updated_at < cutoff) {
+        await sessions.updateWhere({ id: row.id }, { status: 'aborted', updated_at: Date.now() });
+        n++;
+      }
+    }
+    return n;
+  }
+}
+
+export type SessionServices = { queue: QueueService; session: SessionService };
+
+export function createServices(db: TttDatabase): SessionServices {
+  return { queue: new QueueService(db), session: new SessionService(db) };
+}
+
+export function resolveGameDatabase(feature: DatabaseFeature): TttDatabase {
+  return feature.db;
+}

package/src/ttt-command.ts

@@ -0,0 +1,76 @@
+import type { Message, Plugin } from 'zhin.js';
+import { channelKey } from '@zhin.js/game-shared';
+import { formatPlayerWithMark, formatRosterLine } from './player-label.js';
+import { startBotGame, startPvpGame } from './game-flow.js';
+import type { SessionServices } from './session-service.js';
+
+export const TTT_HELP = [
+  '井字棋',
+  '井字棋 / ttt — 本帮助与频道状态',
+  '井字棋 人机 — 人机对战（私聊或单人）',
+  '井字棋 排队 — 群聊排队（满 2 人自动开局）',
+  '井字棋 离开 — 离开排队',
+  '井字棋 认输 — 结束当前局',
+  '井字棋 观战 — 订阅观战推送',
+].join('\n');
+
+export async function runTttCommand(
+  plugin: Plugin,
+  services: SessionServices,
+  message: Message<any>,
+  action: string,
+): Promise<string | undefined> {
+  const ch = channelKey(message);
+  const userId = message.$sender.id;
+
+  if (!action || action === 'help') {
+    const active = await services.session.getActiveByChannel(ch);
+    const q = await services.queue.count(ch);
+    const lines = [TTT_HELP, ''];
+    if (active) lines.push(`进行中：${formatRosterLine(active)}`);
+    if (q > 0) lines.push(`排队：${q} 人`);
+    if (!active && q === 0) lines.push('暂无对局，发送「井字棋 人机」或从游戏大厅进入。');
+    return lines.join('\n');
+  }
+
+  if (action === 'join') {
+    if (message.$channel.type === 'private') {
+      return '私聊请使用「井字棋 人机」。';
+    }
+    const inGame = await services.session.getActiveForUser(ch, userId);
+    if (inGame) return '你已在进行中的对局里。';
+    const { position } = await services.queue.join(ch, userId, message.$sender.name);
+    const pair = await services.queue.tryMatch(ch);
+    if (pair) {
+      const [px, po] = pair;
+      await startPvpGame(plugin, services, message, px, po);
+      return `匹配成功！${formatPlayerWithMark(px.id, px.displayName, '✕')} vs ${formatPlayerWithMark(po.id, po.displayName, '○')}`;
+    }
+    return `已加入排队（第 ${position} 位），凑满 2 人自动开局。`;
+  }
+
+  if (action === 'leave') {
+    const ok = await services.queue.leave(ch, userId);
+    return ok ? '已离开排队。' : '你不在排队中。';
+  }
+
+  if (action === 'bot') {
+    return startBotGame(plugin, services, message);
+  }
+
+  if (action === 'quit') {
+    const row = await services.session.getActiveForUser(ch, userId);
+    if (!row) return '你没有进行中的对局。';
+    await services.session.updateSession(row.id, { status: 'aborted', winner: 0 });
+    return '你已认输，对局结束。';
+  }
+
+  if (action === 'spectate') {
+    const active = await services.session.getActiveByChannel(ch);
+    if (!active) return '当前频道没有进行中的对局。';
+    await services.session.addSpectator(active.id, userId);
+    return `已订阅观战（局 ${active.id}）。每步会在频道更新棋盘。`;
+  }
+
+  return `未知子命令：${action}\n\n${TTT_HELP}`;
+}