@zhin.js/plugin-word-riddle 1.0.0

package/src/data/riddles.ts

@@ -0,0 +1,8 @@
+export type { RiddleEntry, RiddleType } from '../riddle-provider.js';
+export {
+  getRiddleById,
+  pickRoundQueue,
+  QUESTIONS_PER_ROUND,
+  riddleCount,
+  riddlesByType,
+} from '../riddle-provider.js';

package/src/engine.ts

@@ -0,0 +1,30 @@
+import {
+  getRiddleById,
+  type RiddleEntry,
+  type RiddleType,
+} from './riddle-provider.js';
+
+export type { RiddleType };
+
+export const RIDDLE_PREFIX = 'riddle';
+
+export function normalizeAnswer(raw: string): string {
+  return raw.trim().replace(/\s/g, '').replace(/[。.!！?？,，]/g, '');
+}
+
+export function answersFor(entry: RiddleEntry): string[] {
+  const all = [entry.answer, ...(entry.aliases ?? [])];
+  return [...new Set(all.map(normalizeAnswer))];
+}
+
+export function checkAnswer(entry: RiddleEntry, raw: string): boolean {
+  const a = normalizeAnswer(raw);
+  if (!a) return false;
+  return answersFor(entry).some((x) => x === a);
+}
+
+export function typeLabel(type: RiddleType): string {
+  return type === 'char' ? '字谜' : '猜成语';
+}
+
+export { getRiddleById };

package/src/game-flow.ts

@@ -0,0 +1,196 @@
+import type { Adapter, Message, Plugin } from 'zhin.js';
+import {
+  checkAnswer,
+  getRiddleById,
+  RIDDLE_PREFIX,
+  typeLabel,
+} from './engine.js';
+import type { RiddleSessionRow } from './models.js';
+import type { RiddleType } from './data/riddles.js';
+import {
+  currentRiddleId,
+  parseQueue,
+  type SessionService,
+} from './session-service.js';
+import { buildRiddleView, MAX_WRONG } from './view.js';
+
+export async function sendOrEditView(
+  plugin: Plugin,
+  services: SessionService,
+  message: Message<any>,
+  session: RiddleSessionRow,
+  eventLines: string[] = [],
+): Promise<void> {
+  const content = buildRiddleView(session, eventLines);
+  if (typeof content === 'string') {
+    await message.$reply?.(content);
+    return;
+  }
+
+  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 advanceQuestion(
+  services: SessionService,
+  session: RiddleSessionRow,
+): Promise<RiddleSessionRow> {
+  const queue = parseQueue(session.queue);
+  const nextIndex = session.index + 1;
+  if (nextIndex >= queue.length) {
+    await services.updateSession(session.id, { index: nextIndex, status: 'completed', wrong_count: 0 });
+  } else {
+    await services.updateSession(session.id, { index: nextIndex, wrong_count: 0 });
+  }
+  return (await services.getById(session.id))!;
+}
+
+export async function startGame(
+  plugin: Plugin,
+  services: SessionService,
+  message: Message<any>,
+  mode: RiddleType,
+): 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 `你已有进行中的猜谜（${typeLabel(active.mode as RiddleType)}），发送「猜谜 继续」刷新。`;
+    }
+    return `本频道 ${active.player_name} 正在猜谜。`;
+  }
+
+  const session = await services.createSession(message, mode);
+  await sendOrEditView(plugin, services, message, session);
+  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 processAnswerText(
+  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 riddleId = currentRiddleId(session);
+  const entry = riddleId ? getRiddleById(riddleId) : undefined;
+  if (!entry) return null;
+
+  if (checkAnswer(entry, raw)) {
+    const streak = session.streak + 1;
+    const best = Math.max(session.best_streak, streak);
+    await services.updateSession(session.id, {
+      score: session.score + 10 + Math.min(streak, 5),
+      streak,
+      best_streak: best,
+      wrong_count: 0,
+    });
+    const after = await advanceQuestion(services, (await services.getById(session.id))!);
+    const explain = entry.explanation ? `\n📖 ${entry.explanation}` : '';
+    await sendOrEditView(plugin, services, message, after, [
+      `✅ 正确！答案：**${entry.answer}**${explain}`,
+      `+${10 + Math.min(streak, 5)} 分`,
+    ]);
+    return null;
+  }
+
+  const wrong = session.wrong_count + 1;
+  if (wrong >= MAX_WRONG) {
+    await services.updateSession(session.id, { wrong_count: wrong, streak: 0 });
+    const after = await advanceQuestion(services, (await services.getById(session.id))!);
+    await sendOrEditView(plugin, services, message, after, [
+      `❌ 本题答案：**${entry.answer}**`,
+      '失误过多，自动下一题。',
+    ]);
+    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, ['❌ 不对，再想想！']);
+  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 '这是别人的猜谜。';
+
+  if (choiceId === 'restart_char') {
+    await services.updateSession(session.id, { status: 'aborted' });
+    return startGame(plugin, services, message, 'char') as unknown as string;
+  }
+  if (choiceId === 'restart_idiom') {
+    await services.updateSession(session.id, { status: 'aborted' });
+    return startGame(plugin, services, message, 'idiom') as unknown as string;
+  }
+
+  if (session.status !== 'active') return '本轮已结束。';
+
+  const riddleId = currentRiddleId(session);
+  const entry = riddleId ? getRiddleById(riddleId) : undefined;
+  if (!entry) return '题目丢失。';
+
+  if (choiceId === 'hint') {
+    const hint = entry.hint ?? `答案共 ${entry.answer.length} 个字`;
+    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}`, '（连击清零）']);
+    return null;
+  }
+
+  if (choiceId === 'skip') {
+    await services.updateSession(session.id, { streak: 0 });
+    const after = await advanceQuestion(services, session);
+    await sendOrEditView(plugin, services, message, after, [`⏭️ 跳过，答案：**${entry.answer}**`]);
+    return null;
+  }
+
+  if (choiceId === 'quit') {
+    await services.updateSession(session.id, { status: 'aborted' });
+    return '已结束猜谜。';
+  }
+
+  return '未知操作。';
+}
+
+export { RIDDLE_PREFIX };

package/src/hub-register.ts

@@ -0,0 +1,34 @@
+import { getPlugin } from 'zhin.js';
+import { ensureGameHubService } from '@zhin.js/game-shared';
+import { riddleCount } from './data/riddles.js';
+import { runRiddleCommand, RIDDLE_HELP } from './riddle-command.js';
+import type { SessionService } from './session-service.js';
+
+const counts = riddleCount();
+
+export function registerRiddleHub(getServices: () => SessionService | null): () => void {
+  const plugin = getPlugin();
+  ensureGameHubService(plugin);
+  return plugin.registerGame({
+    id: 'riddle',
+    title: '猜谜',
+    icon: '🧩',
+    description: `字谜 ${counts.char.toLocaleString('zh-CN')} 题 + 成语 ${counts.idiom.toLocaleString('zh-CN')} 题`,
+    commandPrefix: '猜谜',
+    quickStart: '开始',
+    aliases: ['riddle'],
+    menus: [
+      { id: 'char', label: '🔤 字谜模式', style: 'primary' },
+      { id: 'idiom', label: '📜 成语模式' },
+      { id: 'continue', label: '🔄 继续' },
+      { id: 'help', label: '📖 玩法说明' },
+    ],
+    runAction: async (actionId, ctx) => {
+      const services = getServices();
+      if (!services) return '猜谜需要启用 database 配置。';
+      return runRiddleCommand(ctx.plugin, services, ctx.message, actionId === 'start' ? 'char' : actionId);
+    },
+  });
+}
+
+export { RIDDLE_HELP };

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 { registerRiddleHub } 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({ 模块: '猜谜', 数据模型: '已就绪' }));
+});
+
+registerRiddleHub(() => 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,57 @@
+import type { Models, Plugin } from 'zhin.js';
+
+export type RiddleSessionStatus = 'active' | 'completed' | 'aborted';
+
+declare module 'zhin.js' {
+  interface Models {
+    word_riddle_sessions: {
+      id: string;
+      adapter: string;
+      endpoint: string;
+      channel_type: string;
+      channel_id: string;
+      channel_key: string;
+      player_id: string;
+      player_name: string;
+      mode: string;
+      queue: string;
+      index: number;
+      score: number;
+      streak: number;
+      best_streak: number;
+      hints_used: number;
+      wrong_count: number;
+      status: RiddleSessionStatus;
+      board_message_id: string;
+      updated_at: number;
+      created_at: number;
+    };
+  }
+}
+
+export type RiddleSessionRow = Models['word_riddle_sessions'];
+
+export function registerModels(plugin: Plugin): void {
+  plugin.defineModel('word_riddle_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: '' },
+    mode: { type: 'text', default: 'char' },
+    queue: { type: 'text', default: '[]' },
+    index: { type: 'integer', default: 0 },
+    score: { type: 'integer', default: 0 },
+    streak: { type: 'integer', default: 0 },
+    best_streak: { type: 'integer', default: 0 },
+    hints_used: { type: 'integer', default: 0 },
+    wrong_count: { type: 'integer', default: 0 },
+    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/riddle-command.ts

@@ -0,0 +1,66 @@
+import type { Message, Plugin } from 'zhin.js';
+import { channelKey } from '@zhin.js/game-shared';
+import { continueGame, startGame } from './game-flow.js';
+import { riddleCount } from './data/riddles.js';
+import type { RiddleType } from './data/riddles.js';
+import { typeLabel } from './engine.js';
+import type { SessionService } from './session-service.js';
+
+const counts = riddleCount();
+
+export const RIDDLE_HELP = [
+  '🧩 猜谜（字谜 + 猜成语）',
+  `字谜 ${counts.char.toLocaleString('zh-CN')} 题 · 成语 ${counts.idiom.toLocaleString('zh-CN')} 题`,
+  '猜谜 / riddle — 帮助',
+  '猜谜 开始 — 字谜模式',
+  '猜谜 字谜 — 字谜模式',
+  '猜谜 成语 — 猜成语模式',
+  '猜谜 继续 — 刷新界面',
+  '猜谜 放弃 — 结束',
+  '',
+  '进行中直接回复答案；连击加分，提示/失误会清零连击。',
+].join('\n');
+
+function parseMode(action: string): RiddleType | null {
+  if (action === 'char' || action === '字谜') return 'char';
+  if (action === 'idiom' || action === '成语') return 'idiom';
+  if (action === 'start' || action === '开始') return 'char';
+  return null;
+}
+
+export async function runRiddleCommand(
+  plugin: Plugin,
+  services: SessionService,
+  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.getActiveByChannel(ch);
+    const lines = [RIDDLE_HELP, ''];
+    if (active) {
+      lines.push(`进行中：${typeLabel(active.mode as RiddleType)} · 得分 ${active.score} · 连击 ${active.streak}`);
+    } else {
+      lines.push('暂无对局，发送「猜谜 开始」。');
+    }
+    return lines.join('\n');
+  }
+
+  const mode = parseMode(action);
+  if (mode) return startGame(plugin, services, message, mode);
+
+  if (action === 'continue' || action === '继续') {
+    return continueGame(plugin, services, message);
+  }
+
+  if (action === 'quit' || action === '放弃') {
+    const row = await services.getActiveForUser(ch, userId);
+    if (!row) return '你没有进行中的猜谜。';
+    await services.updateSession(row.id, { status: 'aborted' });
+    return '已放弃猜谜。';
+  }
+
+  return `未知子命令：${action}\n\n${RIDDLE_HELP}`;
+}

package/src/riddle-provider.ts

@@ -0,0 +1,105 @@
+/**
+ * 猜谜词库
+ * - 字谜：riddle_demo CSV（构建为 char-riddles.json）
+ * - 成语：npm `chinese-idiom-chengyu`（MIT）
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+export type RiddleType = 'char' | 'idiom';
+
+export interface RiddleEntry {
+  id: string;
+  type: RiddleType;
+  question: string;
+  answer: string;
+  aliases?: string[];
+  hint?: string;
+  explanation?: string;
+}
+
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const charRiddles = JSON.parse(
+  readFileSync(join(__dirname, 'data/char-riddles.json'), 'utf8'),
+) as RiddleEntry[];
+
+interface ChengyuLib {
+  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 FOUR_CHAR = /^[\u4e00-\u9fff]{4}$/;
+
+const charPool: RiddleEntry[] = charRiddles as RiddleEntry[];
+const charById = new Map(charPool.map((r) => [r.id, r]));
+
+let idiomPool: RiddleEntry[] | null = null;
+
+function buildIdiomEntry(word: string): RiddleEntry | null {
+  let gloss: string;
+  try {
+    gloss = chengyu.getDefinition(word).trim();
+  } catch {
+    return null;
+  }
+  if (!gloss || gloss.length < 4 || gloss === word) return null;
+  return {
+    id: `i:${word}`,
+    type: 'idiom',
+    question: `${gloss}。（猜成语）`,
+    answer: word,
+    hint: '共 4 个字',
+    explanation: gloss,
+  };
+}
+
+function buildIdiomPool(): RiddleEntry[] {
+  if (idiomPool) return idiomPool;
+  const pool: RiddleEntry[] = [];
+  for (const word of WORD_PINYIN_MAP.keys()) {
+    if (!FOUR_CHAR.test(word)) continue;
+    const entry = buildIdiomEntry(word);
+    if (entry) pool.push(entry);
+  }
+  idiomPool = pool;
+  return pool;
+}
+
+export function riddlesByType(type: RiddleType): RiddleEntry[] {
+  return type === 'char' ? charPool : buildIdiomPool();
+}
+
+export function getRiddleById(id: string): RiddleEntry | undefined {
+  if (id.startsWith('c:')) return charById.get(id);
+  if (id.startsWith('i:')) return buildIdiomEntry(id.slice(2)) ?? undefined;
+  return undefined;
+}
+
+export function riddleCount(): { char: number; idiom: number; total: number } {
+  const char = charPool.length;
+  const idiom = buildIdiomPool().length;
+  return { char, idiom, total: char + idiom };
+}
+
+/** 每局随机抽题数量（避免把整库写入 session queue） */
+export const QUESTIONS_PER_ROUND = 10;
+
+export function pickRoundQueue(type: RiddleType, count = QUESTIONS_PER_ROUND): RiddleEntry[] {
+  const pool = riddlesByType(type);
+  const n = pool.length;
+  const k = Math.min(count, n);
+  const indices = Array.from({ length: n }, (_, i) => i);
+  for (let i = 0; i < k; i++) {
+    const j = i + Math.floor(Math.random() * (n - i));
+    [indices[i], indices[j]] = [indices[j]!, indices[i]!];
+  }
+  return indices.slice(0, k).map((i) => pool[i]!);
+}

package/src/session-service.ts

@@ -0,0 +1,113 @@
+import type { Database, DatabaseFeature, Message, Models, RelatedModel } from 'zhin.js';
+import { channelKey, generateSessionId } from '@zhin.js/game-shared';
+import { pickRoundQueue, type RiddleType } from './data/riddles.js';
+import type { RiddleSessionRow } from './models.js';
+
+export type RiddleDatabase = Database<unknown, Models, string>;
+
+function getModel(db: RiddleDatabase) {
+  const model = db.models.get('word_riddle_sessions');
+  if (!model) throw new Error('word_riddle_sessions not registered');
+  return model as RelatedModel<unknown, Models, 'word_riddle_sessions'>;
+}
+
+export function parseQueue(value: string | string[] | unknown): string[] {
+  if (Array.isArray(value)) return value.filter((x): x is string => typeof x === 'string');
+  if (typeof value !== 'string' || !value) return [];
+  try {
+    const v = JSON.parse(value);
+    return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+export class SessionService {
+  constructor(private readonly db: RiddleDatabase) {}
+
+  async getActiveByChannel(channel: string): Promise<RiddleSessionRow | null> {
+    const rows = await getModel(this.db).findAll({ channel_key: channel, status: 'active' });
+    return rows[0] ?? null;
+  }
+
+  async getActiveForUser(channel: string, userId: string): Promise<RiddleSessionRow | null> {
+    const row = await this.getActiveByChannel(channel);
+    if (!row || row.player_id !== userId) return null;
+    return row;
+  }
+
+  async getById(id: string): Promise<RiddleSessionRow | null> {
+    return getModel(this.db).findOne({ id });
+  }
+
+  async getActiveByBoardMessageId(messageId: string): Promise<RiddleSessionRow | 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>, mode: RiddleType): Promise<RiddleSessionRow> {
+    const now = Date.now();
+    const queue = pickRoundQueue(mode).map((r) => r.id);
+    const row: RiddleSessionRow = {
+      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,
+      mode,
+      queue: JSON.stringify(queue),
+      index: 0,
+      score: 0,
+      streak: 0,
+      best_streak: 0,
+      hints_used: 0,
+      wrong_count: 0,
+      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<RiddleSessionRow>): 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: RiddleDatabase): SessionService {
+  return new SessionService(db);
+}
+
+export function resolveGameDatabase(feature: DatabaseFeature): RiddleDatabase {
+  return feature.db;
+}
+
+export function currentRiddleId(session: RiddleSessionRow): string | null {
+  const queue = parseQueue(session.queue);
+  return queue[session.index] ?? null;
+}