@zhin.js/plugin-idiom-chain 1.0.0

package/src/game-flow.ts

@@ -0,0 +1,270 @@
+import type { Adapter, Message, Plugin } from 'zhin.js';
+import {
+  CHAIN_PREFIX,
+  getGloss,
+  lastChar,
+  modeLabel,
+  normalizeInput,
+  pickBotIdiom,
+  pickHintIdiom,
+  pickStarterIdiom,
+  promptLine,
+  validatePlayerIdiom,
+  type MatchMode,
+} from './engine.js';
+import type { ChainSessionRow } from './models.js';
+import { parseUsed, type SessionService } from './session-service.js';
+import { buildChainView, MAX_WRONG } from './view.js';
+
+function sessionMode(session: ChainSessionRow): MatchMode {
+  return session.match_mode === 'char' ? 'char' : 'pinyin';
+}
+
+export async function sendOrEditView(
+  plugin: Plugin,
+  services: SessionService,
+  message: Message<any>,
+  session: ChainSessionRow,
+  eventLines: string[] = [],
+): Promise<void> {
+  const content = buildChainView(session, eventLines);
+  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.updateSession(session.id, { board_message_id: msgId });
+    }
+    return;
+  }
+
+  const msgId = await message.$reply?.(content);
+  if (msgId) await services.updateSession(session.id, { board_message_id: msgId });
+}
+
+async function botTurn(
+  services: SessionService,
+  session: ChainSessionRow,
+  used: Set<string>,
+): Promise<{ session: ChainSessionRow; lines: string[]; playerWon: boolean }> {
+  const mode = sessionMode(session);
+  const bot = pickBotIdiom(session.last_idiom, mode, used);
+  if (!bot) {
+    await services.updateSession(session.id, {
+      status: 'won',
+      player_score: session.player_score + 1,
+    });
+    const updated = (await services.getById(session.id))!;
+    return { session: updated, lines: ['🎉 机器人接不上，你赢本局！'], playerWon: true };
+  }
+
+  used.add(bot.text);
+  const next = lastChar(bot.text);
+  const gloss = bot.gloss ?? getGloss(bot.text);
+  await services.updateSession(session.id, {
+    last_idiom: bot.text,
+    next_char: next,
+    used_idioms: JSON.stringify([...used]),
+    turn: 'player',
+  });
+  const updated = (await services.getById(session.id))!;
+  const lines = [
+    `🤖 机器人：${bot.text}${gloss ? `（${gloss}）` : ''}`,
+    promptLine(bot.text, mode),
+  ];
+  return { session: updated, lines, playerWon: false };
+}
+
+export async function startGame(
+  plugin: Plugin,
+  services: SessionService,
+  message: Message<any>,
+  matchMode: MatchMode = 'pinyin',
+): Promise<string | undefined> {
+  const ch = `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+  const active = await services.getActiveByChannel(ch);
+  if (active) {
+    if (active.player_id === message.$sender.id) {
+      return '你已有进行中的接龙，发送「接龙 继续」刷新。';
+    }
+    return `本频道 ${active.player_name} 正在成语接龙。`;
+  }
+
+  const used = new Set<string>();
+  const starter = pickStarterIdiom(used);
+  used.add(starter.text);
+  const session = await services.createSession(message, {
+    text: starter.text,
+    nextChar: lastChar(starter.text),
+    used: [...used],
+    matchMode,
+  });
+
+  const gloss = starter.gloss ?? getGloss(starter.text);
+  await sendOrEditView(plugin, services, message, session, [
+    `🎬 ${modeLabel(matchMode)}开局！我先出：**${starter.text}**${gloss ? `（${gloss}）` : ''}`,
+    promptLine(starter.text, matchMode),
+  ]);
+  return undefined;
+}
+
+export async function continueGame(
+  plugin: Plugin,
+  services: SessionService,
+  message: Message<any>,
+): Promise<string> {
+  const session = await services.getActiveForUser(
+    `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`,
+    message.$sender.id,
+  );
+  if (!session) return '你没有进行中的接龙，发送「接龙 开始」。';
+  await sendOrEditView(plugin, services, message, session);
+  return '已刷新接龙界面。';
+}
+
+export async function processIdiomText(
+  plugin: Plugin,
+  services: SessionService,
+  message: Message<any>,
+  raw: string,
+): Promise<string | null> {
+  const ch = `${message.$adapter}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+  const session = await services.getActiveForUser(ch, message.$sender.id);
+  if (!session || session.status !== 'active') return null;
+
+  const mode = sessionMode(session);
+  const used = parseUsed(session.used_idioms);
+  const idiom = normalizeInput(raw);
+  const check = validatePlayerIdiom(idiom, session.last_idiom, mode, used);
+  if (!check.ok) {
+    const wrong = session.wrong_count + 1;
+    if (wrong >= MAX_WRONG) {
+      await services.updateSession(session.id, {
+        wrong_count: wrong,
+        status: 'lost',
+        bot_score: session.bot_score + 1,
+        streak: 0,
+      });
+      const updated = (await services.getById(session.id))!;
+      await sendOrEditView(plugin, services, message, updated, [check.reason!, '失误过多，本局结束。']);
+      return null;
+    }
+    await services.updateSession(session.id, { wrong_count: wrong, streak: 0 });
+    const updated = (await services.getById(session.id))!;
+    await sendOrEditView(plugin, services, message, updated, [check.reason!]);
+    return null;
+  }
+
+  used.add(idiom);
+  const streak = session.streak + 1;
+  const best = Math.max(session.best_streak, streak);
+  const nextChar = lastChar(idiom);
+  const gloss = getGloss(idiom);
+
+  await services.updateSession(session.id, {
+    last_idiom: idiom,
+    next_char: nextChar,
+    used_idioms: JSON.stringify([...used]),
+    streak,
+    best_streak: best,
+    wrong_count: 0,
+  });
+
+  const current = (await services.getById(session.id))!;
+  const userLine = `✅ 你：${idiom}${gloss ? `（${gloss}）` : ''}`;
+
+  const botResult = await botTurn(services, current, used);
+  await sendOrEditView(plugin, services, message, botResult.session, [userLine, ...botResult.lines]);
+  return null;
+}
+
+export async function handleChoice(
+  plugin: Plugin,
+  services: SessionService,
+  message: Message<any>,
+  sessionId: string,
+  choiceId: string,
+): Promise<string | null> {
+  const session = await services.getById(sessionId);
+  if (!session) return '对局不存在。';
+  if (session.player_id !== message.$sender.id) return '这是别人的接龙。';
+
+  const mode = sessionMode(session);
+
+  if (choiceId === 'restart') {
+    const used = new Set<string>();
+    const starter = pickStarterIdiom(used);
+    used.add(starter.text);
+    await services.updateSession(session.id, {
+      last_idiom: starter.text,
+      next_char: lastChar(starter.text),
+      used_idioms: JSON.stringify([...used]),
+      streak: 0,
+      wrong_count: 0,
+      turn: 'player',
+      status: 'active',
+      board_message_id: '',
+    });
+    const updated = (await services.getById(session.id))!;
+    const gloss = starter.gloss ?? getGloss(starter.text);
+    await sendOrEditView(plugin, services, message, updated, [
+      `🎬 新一局！我先出：**${starter.text}**${gloss ? `（${gloss}）` : ''}`,
+      promptLine(starter.text, mode),
+    ]);
+    return null;
+  }
+
+  if (session.status !== 'active') {
+    return '本局已结束，请点击再来一局。';
+  }
+
+  const used = parseUsed(session.used_idioms);
+
+  if (choiceId === 'hint') {
+    const hint = pickHintIdiom(session.last_idiom, mode, used);
+    if (!hint) {
+      await sendOrEditView(plugin, services, message, session, ['💡 词库中暂无可用提示，你赢了！']);
+      await services.updateSession(session.id, { status: 'won', player_score: session.player_score + 1 });
+      const updated = (await services.getById(session.id))!;
+      await sendOrEditView(plugin, services, message, updated);
+      return null;
+    }
+    const gloss = getGloss(hint);
+    await services.updateSession(session.id, { hints_used: session.hints_used + 1, streak: 0 });
+    const updated = (await services.getById(session.id))!;
+    await sendOrEditView(plugin, services, message, updated, [
+      `💡 提示：可试 **${hint}**${gloss ? `（${gloss}）` : ''}`,
+      '（使用提示会清零连击）',
+    ]);
+    return null;
+  }
+
+  if (choiceId === 'skip') {
+    await services.updateSession(session.id, {
+      status: 'lost',
+      bot_score: session.bot_score + 1,
+      streak: 0,
+    });
+    const updated = (await services.getById(session.id))!;
+    await sendOrEditView(plugin, services, message, updated, ['⏭️ 你选择跳过，机器人得一分。']);
+    return null;
+  }
+
+  if (choiceId === 'quit') {
+    await services.updateSession(session.id, { status: 'lost', bot_score: session.bot_score + 1 });
+    const updated = (await services.getById(session.id))!;
+    await sendOrEditView(plugin, services, message, updated, ['🏳️ 你认输了。']);
+    return null;
+  }
+
+  return '未知操作。';
+}
+
+export { CHAIN_PREFIX };

package/src/hub-register.ts

@@ -0,0 +1,32 @@
+import { getPlugin } from 'zhin.js';
+import { ensureGameHubService } from '@zhin.js/game-shared';
+import { idiomCount } from './engine.js';
+import { runChainCommand, CHAIN_HELP } from './chain-command.js';
+import type { SessionService } from './session-service.js';
+
+export function registerChainHub(getServices: () => SessionService | null): () => void {
+  const plugin = getPlugin();
+  ensureGameHubService(plugin);
+  return plugin.registerGame({
+    id: 'chain',
+    title: '成语接龙',
+    icon: '📜',
+    description: `四字成语接龙（同音/同字），词库 ${idiomCount()} 条`,
+    commandPrefix: '接龙',
+    quickStart: 'start_pinyin',
+    aliases: ['chain'],
+    menus: [
+      { id: 'start_pinyin', label: '🎮 同音接龙', style: 'primary' },
+      { id: 'start_char', label: '📝 同字接龙' },
+      { id: 'continue', label: '🔄 继续' },
+      { id: 'help', label: '📖 玩法说明' },
+    ],
+    runAction: async (actionId, ctx) => {
+      const services = getServices();
+      if (!services) return '成语接龙需要启用 database 配置。';
+      return runChainCommand(ctx.plugin, services, ctx.message, actionId);
+    },
+  });
+}
+
+export { CHAIN_HELP };

package/src/idiom-provider.ts

@@ -0,0 +1,165 @@
+/**
+ * 成语词库适配层 — 基于 npm `chinese-idiom-chengyu`（MIT，~3 万成语）
+ * @see https://www.npmjs.com/package/chinese-idiom-chengyu
+ */
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export type MatchMode = 'char' | 'pinyin';
+
+export interface IdiomEntry {
+  text: string;
+  gloss?: string;
+}
+
+interface ChengyuLib {
+  nextIdiomsWithMatchingCharacter: (word: string, opts: { word: boolean; pinyin: boolean }) => string[];
+  nextIdiomsWithMatchingNoTonePinyin: (word: string, opts: { word: boolean; pinyin: boolean }) => string[];
+  getDefinition: (word: string) => string;
+}
+
+const chengyu = require('chinese-idiom-chengyu') as ChengyuLib;
+const { WORD_PINYIN_MAP } = require('chinese-idiom-chengyu/src/tools/parse.js') as {
+  WORD_PINYIN_MAP: Map<string, string>;
+};
+const Util = require('chinese-idiom-chengyu/src/tools/util.js') as {
+  pinyinToLetters: (pinyin: string) => string;
+};
+
+const FOUR_CHAR = /^[\u4e00-\u9fff]{4}$/;
+const SEARCH_OPTS = { word: true, pinyin: false } as const;
+
+let fourCharPool: string[] | null = null;
+
+function buildFourCharPool(): string[] {
+  if (fourCharPool) return fourCharPool;
+  const pool: string[] = [];
+  for (const word of WORD_PINYIN_MAP.keys()) {
+    if (FOUR_CHAR.test(word)) pool.push(word);
+  }
+  fourCharPool = pool;
+  return pool;
+}
+
+export function idiomCount(): number {
+  return buildFourCharPool().length;
+}
+
+export function normalizeInput(raw: string): string {
+  return raw.trim().replace(/\s/g, '');
+}
+
+export function isKnownIdiom(text: string): boolean {
+  return WORD_PINYIN_MAP.has(text);
+}
+
+export function getGloss(text: string): string | undefined {
+  try {
+    return chengyu.getDefinition(text);
+  } catch {
+    return undefined;
+  }
+}
+
+export function lastChar(idiom: string): string {
+  return idiom[idiom.length - 1]!;
+}
+
+export function lastSyllableNoTone(idiom: string): string {
+  const py = WORD_PINYIN_MAP.get(idiom);
+  if (!py) return '';
+  const tail = py.split(' ').pop() ?? '';
+  return Util.pinyinToLetters(tail);
+}
+
+export function modeLabel(mode: MatchMode): string {
+  return mode === 'char' ? '同字接龙' : '同音接龙';
+}
+
+export function getValidNext(
+  prevIdiom: string,
+  mode: MatchMode,
+  used: Set<string>,
+): IdiomEntry[] {
+  if (!WORD_PINYIN_MAP.has(prevIdiom)) return [];
+
+  const raw =
+    mode === 'char'
+      ? chengyu.nextIdiomsWithMatchingCharacter(prevIdiom, SEARCH_OPTS)
+      : chengyu.nextIdiomsWithMatchingNoTonePinyin(prevIdiom, SEARCH_OPTS);
+
+  return raw
+    .filter((w) => FOUR_CHAR.test(w) && !used.has(w))
+    .map((text) => ({ text, gloss: getGloss(text) }));
+}
+
+export function pickBotIdiom(
+  prevIdiom: string,
+  mode: MatchMode,
+  used: Set<string>,
+): IdiomEntry | null {
+  const candidates = getValidNext(prevIdiom, mode, used);
+  if (!candidates.length) return null;
+  return candidates[Math.floor(Math.random() * candidates.length)]!;
+}
+
+export function pickStarterIdiom(used: Set<string>): IdiomEntry {
+  const pool = buildFourCharPool().filter((w) => !used.has(w));
+  const text = pool[Math.floor(Math.random() * pool.length)] ?? '一心一意';
+  return { text, gloss: getGloss(text) };
+}
+
+export function pickHintIdiom(
+  prevIdiom: string,
+  mode: MatchMode,
+  used: Set<string>,
+): string | null {
+  return pickBotIdiom(prevIdiom, mode, used)?.text ?? null;
+}
+
+export interface ValidateResult {
+  ok: boolean;
+  reason?: string;
+}
+
+export function validatePlayerIdiom(
+  text: string,
+  prevIdiom: string,
+  mode: MatchMode,
+  used: Set<string>,
+): ValidateResult {
+  const idiom = normalizeInput(text);
+  if (!FOUR_CHAR.test(idiom)) {
+    return { ok: false, reason: '请输入**四字成语**（不要空格或标点）。' };
+  }
+  if (!isKnownIdiom(idiom)) {
+    return { ok: false, reason: '开源词库中未收录该成语，请换一个常见四字成语。' };
+  }
+  if (used.has(idiom)) {
+    return { ok: false, reason: '这个成语本局已经用过了。' };
+  }
+
+  const valid = getValidNext(prevIdiom, mode, used);
+  if (valid.some((v) => v.text === idiom)) return { ok: true };
+
+  const tail = lastChar(prevIdiom);
+  if (mode === 'char') {
+    return { ok: false, reason: `必须以「**${tail}**」开头（上一句尾字）。` };
+  }
+
+  const py = lastSyllableNoTone(prevIdiom);
+  return {
+    ok: false,
+    reason: `首字需**同音**（${py}），如「${tail}」音；也可同字「${tail}」开头。`,
+  };
+}
+
+export function promptLine(prevIdiom: string, mode: MatchMode): string {
+  const tail = lastChar(prevIdiom);
+  if (mode === 'char') {
+    return `请接「**${tail}**」字开头的四字成语`;
+  }
+  const py = lastSyllableNoTone(prevIdiom);
+  return `请接**同音**「${py}」（尾字「${tail}」）开头的四字成语`;
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+import { Cron, formatCompact, usePlugin, type DatabaseFeature } from 'zhin.js';
+import { registerModels } from './models.js';
+import { createServices, resolveGameDatabase, type SessionService } from './session-service.js';
+import { registerCommands, registerInteractive, registerTextMiddleware } from './commands.js';
+import { registerChainHub } from './hub-register.js';
+
+const plugin = usePlugin();
+const { logger, useContext, addCron } = plugin;
+
+registerModels(plugin);
+
+let services: SessionService | null = null;
+
+useContext('database', (dbFeature: DatabaseFeature) => {
+  services = createServices(resolveGameDatabase(dbFeature));
+  logger.info(formatCompact({ 模块: '成语接龙', 数据模型: '已就绪' }));
+});
+
+registerChainHub(() => services);
+registerCommands(plugin, () => services);
+registerInteractive(plugin, () => services);
+registerTextMiddleware(plugin, () => services);
+
+addCron(
+  new Cron('0 */15 * * * *', async () => {
+    if (!services) return;
+    const n = await services.abortStale(45 * 60 * 1000);
+    if (n > 0) logger.debug(formatCompact({ 成语接龙: '清理超时局', count: n }));
+  }),
+);
+
+logger.info(formatCompact({ 模块: '成语接龙', 状态: '已加载' }));

package/src/models.ts

@@ -0,0 +1,64 @@
+import type { Models, Plugin } from 'zhin.js';
+import type { MatchMode } from './engine.js';
+
+export type ChainSessionStatus = 'active' | 'won' | 'lost' | 'aborted';
+
+declare module 'zhin.js' {
+  interface Models {
+    idiom_chain_sessions: {
+      id: string;
+      adapter: string;
+      endpoint: string;
+      channel_type: string;
+      channel_id: string;
+      channel_key: string;
+      player_id: string;
+      player_name: string;
+      last_idiom: string;
+      next_char: string;
+      match_mode: MatchMode;
+      used_idioms: string;
+      player_score: number;
+      bot_score: number;
+      streak: number;
+      best_streak: number;
+      wrong_count: number;
+      hints_used: number;
+      turn: string;
+      status: ChainSessionStatus;
+      board_message_id: string;
+      updated_at: number;
+      created_at: number;
+    };
+  }
+}
+
+export type ChainSessionRow = Models['idiom_chain_sessions'];
+
+export function registerModels(plugin: Plugin): void {
+  plugin.defineModel('idiom_chain_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_id: { type: 'text', nullable: false },
+    player_name: { type: 'text', default: '' },
+    last_idiom: { type: 'text', default: '' },
+    next_char: { type: 'text', default: '' },
+    match_mode: { type: 'text', default: 'pinyin' },
+    used_idioms: { type: 'text', default: '[]' },
+    player_score: { type: 'integer', default: 0 },
+    bot_score: { type: 'integer', default: 0 },
+    streak: { type: 'integer', default: 0 },
+    best_streak: { type: 'integer', default: 0 },
+    wrong_count: { type: 'integer', default: 0 },
+    hints_used: { type: 'integer', default: 0 },
+    turn: { type: 'text', default: 'player' },
+    status: { type: 'text', default: 'active' },
+    board_message_id: { type: 'text', default: '' },
+    updated_at: { type: 'integer', default: 0 },
+    created_at: { type: 'integer', default: 0 },
+  });
+}

package/src/session-service.ts

@@ -0,0 +1,117 @@
+import type { Database, DatabaseFeature, Message, Models, RelatedModel } from 'zhin.js';
+import { channelKey, generateSessionId } from '@zhin.js/game-shared';
+import type { MatchMode } from './engine.js';
+import type { ChainSessionRow } from './models.js';
+
+export type ChainDatabase = Database<unknown, Models, string>;
+
+function getModel(db: ChainDatabase) {
+  const model = db.models.get('idiom_chain_sessions');
+  if (!model) throw new Error('idiom_chain_sessions not registered');
+  return model as RelatedModel<unknown, Models, 'idiom_chain_sessions'>;
+}
+
+export function parseUsed(value: string | string[] | unknown): Set<string> {
+  if (Array.isArray(value)) return new Set(value.filter((x): x is string => typeof x === 'string'));
+  if (typeof value !== 'string' || !value) return new Set();
+  try {
+    const v = JSON.parse(value);
+    return Array.isArray(v) ? new Set(v.filter((x): x is string => typeof x === 'string')) : new Set();
+  } catch {
+    return new Set();
+  }
+}
+
+export function serializeUsed(set: Set<string>): string {
+  return JSON.stringify([...set]);
+}
+
+export class SessionService {
+  constructor(private readonly db: ChainDatabase) {}
+
+  async getActiveByChannel(channel: string): Promise<ChainSessionRow | null> {
+    const rows = await getModel(this.db).findAll({ channel_key: channel, status: 'active' });
+    return rows[0] ?? null;
+  }
+
+  async getActiveForUser(channel: string, userId: string): Promise<ChainSessionRow | null> {
+    const row = await this.getActiveByChannel(channel);
+    if (!row || row.player_id !== userId) return null;
+    return row;
+  }
+
+  async getById(id: string): Promise<ChainSessionRow | null> {
+    return getModel(this.db).findOne({ id });
+  }
+
+  async getActiveByBoardMessageId(messageId: string): Promise<ChainSessionRow | null> {
+    if (!messageId) return null;
+    const rows = await getModel(this.db).findAll({ status: 'active' });
+    for (const row of rows) {
+      const stored = row.board_message_id;
+      if (!stored) continue;
+      if (stored === messageId || stored.endsWith(`:${messageId}`)) return row;
+    }
+    return null;
+  }
+
+  async createSession(
+    message: Message<any>,
+    starter: { text: string; nextChar: string; used: string[]; matchMode: MatchMode },
+  ): Promise<ChainSessionRow> {
+    const now = Date.now();
+    const row: ChainSessionRow = {
+      id: generateSessionId(),
+      adapter: String(message.$adapter),
+      endpoint: message.$endpoint,
+      channel_type: message.$channel.type,
+      channel_id: message.$channel.id,
+      channel_key: channelKey(message),
+      player_id: message.$sender.id,
+      player_name: message.$sender.name?.trim() || message.$sender.id,
+      last_idiom: starter.text,
+      next_char: starter.nextChar,
+      match_mode: starter.matchMode,
+      used_idioms: serializeUsed(new Set(starter.used)),
+      player_score: 0,
+      bot_score: 0,
+      streak: 0,
+      best_streak: 0,
+      wrong_count: 0,
+      hints_used: 0,
+      turn: 'player',
+      status: 'active',
+      board_message_id: '',
+      updated_at: now,
+      created_at: now,
+    };
+    await getModel(this.db).create(row);
+    return row;
+  }
+
+  async updateSession(id: string, patch: Partial<ChainSessionRow>): Promise<void> {
+    await getModel(this.db).updateWhere({ id }, { ...patch, updated_at: Date.now() });
+  }
+
+  async abortStale(idleMs: number): Promise<number> {
+    const cutoff = Date.now() - idleMs;
+    const model = getModel(this.db);
+    const rows = await model.findAll({ status: 'active' });
+    let n = 0;
+    for (const row of rows) {
+      if (row.updated_at < cutoff) {
+        await model.updateWhere({ id: row.id }, { status: 'aborted', updated_at: Date.now() });
+        n++;
+      }
+    }
+    return n;
+  }
+}
+
+export function createServices(db: ChainDatabase): SessionService {
+  return new SessionService(db);
+}
+
+export function resolveGameDatabase(feature: DatabaseFeature): ChainDatabase {
+  return feature.db;
+}