tavern-harness 0.1.0

package/src/core/fileDownload.ts

@@ -0,0 +1,67 @@
+// ============================================================
+// 文件下载（支持用户选择保存位置与文件名）
+// 返回：'saved' 已保存到用户选择的位置；'downloaded' 已下载到默认目录；
+//       'canceled' 用户取消（不产生任何文件）
+// ============================================================
+
+export type SaveResult = 'saved' | 'downloaded' | 'canceled';
+
+async function pickSaveFileHandle(suggestedName: string): Promise<FileSystemFileHandle | 'canceled' | null> {
+  // 仅在安全上下文（localhost / https）下可用
+  if (typeof (window as unknown as { showSaveFilePicker?: unknown }).showSaveFilePicker !== 'function') {
+    return null;
+  }
+  try {
+    return await (window as unknown as {
+      showSaveFilePicker: (opts: {
+        suggestedName: string;
+        types: Array<{ description: string; accept: Record<string, string[]> }>;
+      }) => Promise<FileSystemFileHandle>;
+    }).showSaveFilePicker({
+      suggestedName,
+      types: [
+        {
+          description: 'Text Files',
+          accept: { 'text/plain': ['.txt', '.json', '.md', '.csv', '.log'] },
+        },
+      ],
+    });
+  } catch (e) {
+    // 用户主动取消（Esc / 点取消）→ 不产生任何文件
+    if ((e as Error).name === 'AbortError') return 'canceled';
+    // 其余异常（如浏览器不支持）→ 回退默认下载目录
+    return null;
+  }
+}
+
+/** 保存文本内容：优先调用系统「另存为」对话框让用户选择位置与文件名；
+ *  不可用时回退为浏览器默认下载目录。用户取消时不产生任何文件。 */
+export async function saveTextFile(content: string, mime: string, suggestedName: string): Promise<SaveResult> {
+  const handle = await pickSaveFileHandle(suggestedName);
+  if (handle === 'canceled') return 'canceled';
+  if (handle) {
+    try {
+      const writable = await handle.createWritable();
+      await writable.write(content);
+      await writable.close();
+      return 'saved';
+    } catch (e) {
+      // 写入失败（如权限被拒）→ 回退默认下载
+      console.warn('saveTextFile: File System Access API 写入失败，回退下载', e);
+    }
+  }
+  // 回退：浏览器默认下载目录 + 建议文件名
+  const blob = new Blob([content], { type: `${mime};charset=utf-8` });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = suggestedName;
+  a.click();
+  URL.revokeObjectURL(url);
+  return 'downloaded';
+}
+
+/** 保存 JSON 对象为文件（便于各导出入口统一调用） */
+export function saveJsonFile(payload: unknown, suggestedName: string): Promise<SaveResult> {
+  return saveTextFile(JSON.stringify(payload, null, 2), 'application/json', suggestedName);
+}

package/src/core/gameplay.ts

@@ -0,0 +1,521 @@
+// ============================================================
+// 游戏导出 / 导入（完全重建）
+// ============================================================
+// 把一次「游戏局」完整导出为独立 JSON 文件：
+// - 会话设置（模式 / 标题 / 世界书关联 / 用户人设 / 发言顺序 / 开场白开关 / 队列&循环历史）
+// - 全部参与 NPC（角色卡：人设 / 开场白 / 头像 / 启用的技能）
+// - 全部涉及的工具（生成式技能：OpenAI tool JSON + 声明式实现）
+// - 对话历史（可选）：消息 / 参与者 / 队列与循环索引完全复原
+// 导入时反向重建：先建工具 → 再建角色与回调映射 → 再建世界书（会话引用其新 id）→
+// 再建会话与参与者 → 最后批量写入消息（保留顺序与相对间隔）。
+// 幂等：技能 / 角色 / 世界书 / 用户人设不与现有对象合并——名称冲突时创建「 (2)」副本，
+// 绝不覆盖用户已有数据；会话始终新建。
+// 格式版本号：1
+// ============================================================
+
+import { db } from '../db/database';
+import type {
+  ChatMessage,
+  ChatParticipant,
+  ChatSession,
+  McpTool,
+  NpcCharacter,
+  WorldBook,
+} from '../types/models';
+import { saveJsonFile, type SaveResult } from './fileDownload';
+import { createSessionWorkspaceDir, ensureSessionWorkspaceDir } from './tools/generatedSkillExecutor';
+import { seedOpeningGreeting } from './openingGreeting';
+
+const GAMEPLAY_EXPORT_VERSION = 1;
+const GAMEPLAY_FORMAT = 'tavern-harness-gameplay';
+
+/** 参与会话的角色：角色卡全量快照 + 会话内显示名 */
+interface GameplayNpc {
+  npc: NpcCharacter;
+  /** 会话参与者表中的显示名（可能与会话创建后角色改名不同） */
+  sessionDisplayName: string;
+}
+
+/** 游戏导出文件结构 */
+interface GameplayExportPayload {
+  format: typeof GAMEPLAY_FORMAT;
+  version: number;
+  exportedAt: number;
+  appName: 'Tavern Harness';
+  title: string;
+  includeHistory: boolean;
+  /** 会话设置（无 id 与 lastMessage；队列/循环历史按参与者旧 id 记录） */
+  session: Omit<ChatSession, 'id' | 'lastMessage'>;
+  /** 会话内参与记录（源 participantId → 席位/显示名，玩家恒定 -1） */
+  sessionParticipants: ChatParticipant[];
+  /** 参与会话的角色卡快照（含会话内显示名） */
+  npcs: GameplayNpc[];
+  /** 对话历史消息（仅重建所需字段，id 在导入时重建） */
+  messages: ReturnType<typeof sanitizeMessage>[];
+  /** 会话引用的世界书（worldBookId 关联） */
+  worldBook?: WorldBook;
+  /** 会话引用的用户人设（userPersonaNpcId 关联） */
+  userPersona?: NpcCharacter;
+  /** 会话涉及的生成式技能（NPC 启用列表 ∪ 历史消息工具记录；不含内置技能） */
+  tools: McpTool[];
+}
+
+// ---------------------------------------------------------------------------
+// 内部帮助函数
+// ---------------------------------------------------------------------------
+
+async function loadMessages(sessionId: number): Promise<ChatMessage[]> {
+  return db.messages.where('sessionId').equals(sessionId).sortBy('timestamp');
+}
+
+/** 从会话历史消息中收集实际出现过的工具调用名 */
+function collectToolNamesFromMessages(messages: ChatMessage[]): Set<string> {
+  const names = new Set<string>();
+  for (const m of messages) {
+    if (m.role !== 'assistant') continue;
+    try {
+      const calls = JSON.parse(m.toolCallsJson || '[]') as Array<{ name?: string }>;
+      for (const c of calls) if (c.name) names.add(c.name);
+    } catch {
+      /* ignore */
+    }
+  }
+  return names;
+}
+
+/** 不影响重建对话的字段：性能 / 调试 / 运行时细节，导出时直接移除
+ *  （toolCallsJson 必须保留：工具调用卡片与工具结果关联都依赖它） */
+function sanitizeMessage(m: ChatMessage) {
+  const {
+    sessionId: _sessionId,
+    latencyMs: _latencyMs,
+    promptTokens: _promptTokens,
+    completionTokens: _completionTokens,
+    totalTokens: _totalTokens,
+    tokensPerSec: _tokensPerSec,
+    modelUsed: _modelUsed,
+    attachmentInfos: _attachmentInfos,
+    rawRequestBody: _rawRequestBody,
+    rawResponseBody: _rawResponseBody,
+    ...rest
+  } = m;
+  void _sessionId;
+  void _latencyMs;
+  void _promptTokens;
+  void _completionTokens;
+  void _totalTokens;
+  void _tokensPerSec;
+  void _modelUsed;
+  void _attachmentInfos;
+  void _rawRequestBody;
+  void _rawResponseBody;
+  return rest;
+}
+
+function sanitizeSession(session: ChatSession): Omit<ChatSession, 'id' | 'lastMessage'> {
+  const { id: _id, lastMessage: _last, ...rest } = session;
+  void _id;
+  void _last;
+  return rest;
+}
+
+function safeFileName(title: string): string {
+  return (title.replace(/[\\/:*?"<>|\s]+/g, '_').slice(0, 40) || 'gameplay') + '-gameplay.json';
+}
+
+/** 队列 JSON 里的参与者 id 是字符串（'-1' = 玩家，其余为 NPC 的 participantId）。
+ *  导入后 NPC 的 participantId 变为新 npc id，因此逐 token 替换队列字符串。 */
+function remapQueueJson(value: string, map: Map<number, number>): string {
+  if (!value || map.size === 0) return value;
+  return value.replace(/"(-?\d+)"/g, (match, raw: string) => {
+    const num = Number(raw);
+    if (Number.isInteger(num)) {
+      const mapped = map.get(num);
+      if (mapped != null) return `"${mapped}"`;
+    }
+    return match;
+  });
+}
+
+/** 生成一个不与现有条目重名的名称：重名时追加「 (2)」「 (3)」… */
+async function uniqueName(
+  table: 'npcs' | 'worldBooks' | 'tools',
+  name: string
+): Promise<string> {
+  const count = (n: string) =>
+    db[table].where('name').equals(n).count();
+  if ((await count(name)) === 0) return name;
+  let i = 2;
+  for (;;) {
+    const candidate = `${name} (${i})`;
+    if ((await count(candidate)) === 0) return candidate;
+    i += 1;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 导出
+// ---------------------------------------------------------------------------
+
+interface ExportGameplayOptions {
+  sessionId: number;
+  includeHistory: boolean;
+}
+
+/**
+ * 导出会话游戏为 JSON 文件（弹出保存对话框）。
+ * 返回：'saved' 保存成功 / 'downloaded' 已下载到默认目录 / 'canceled' 用户取消
+ */
+export async function exportGameplay({ sessionId, includeHistory }: ExportGameplayOptions): Promise<SaveResult> {
+  const session = await db.sessions.get(sessionId);
+  if (!session) throw new Error('会话不存在');
+
+  const participants = await db.participants.where('sessionId').equals(sessionId).toArray();
+  const messages = includeHistory ? await loadMessages(sessionId) : [];
+
+  // 参与角色（按座位顺序）
+  const npcIds = participants
+    .filter((p) => p.kind === 'NPC' && p.npcId != null)
+    .sort((a, b) => a.seatOrder - b.seatOrder)
+    .map((p) => p.npcId!);
+  if (session.associatedId != null && !npcIds.includes(session.associatedId)) {
+    npcIds.unshift(session.associatedId);
+  }
+
+  const npcs: GameplayNpc[] = [];
+  for (const npcId of npcIds) {
+    const npc = await db.npcs.get(npcId);
+    if (!npc) continue;
+    const participant = participants.find((p) => p.kind === 'NPC' && p.npcId === npcId);
+    npcs.push({ npc, sessionDisplayName: participant?.displayName ?? npc.name });
+  }
+
+  const worldBook = session.worldBookId != null
+    ? (await db.worldBooks.get(session.worldBookId)) ?? undefined
+    : undefined;
+  const userPersona = session.userPersonaNpcId != null
+    ? (await db.npcs.get(session.userPersonaNpcId)) ?? undefined
+    : undefined;
+
+  // 涉及技能：NPC 启用列表 ∪ 历史消息工具调用
+  const toolNames = new Set<string>();
+  for (const n of npcs) for (const name of n.npc.enabledToolNames) toolNames.add(name);
+  for (const name of collectToolNamesFromMessages(messages)) toolNames.add(name);
+
+  const allTools = await db.tools.toArray();
+  const tools = allTools
+    .filter((t) => !t.isBuiltIn && toolNames.has(t.name))
+    .map((t) => stripToolId(t));
+
+  const payload: GameplayExportPayload = {
+    format: GAMEPLAY_FORMAT,
+    version: GAMEPLAY_EXPORT_VERSION,
+    exportedAt: Date.now(),
+    appName: 'Tavern Harness',
+    title: session.title,
+    includeHistory,
+    session: sanitizeSession(session),
+    sessionParticipants: participants,
+    messages: messages.map(sanitizeMessage),
+    npcs,
+    worldBook,
+    userPersona,
+    tools,
+  };
+
+  return saveJsonFile(payload, safeFileName(session.title));
+}
+
+/** 去除工具表的自增 id（导入时重建） */
+function stripToolId(tool: McpTool): Omit<McpTool, 'id'> {
+  const { id: _id, ...rest } = tool;
+  void _id;
+  return rest;
+}
+
+/** 把消息的 toolCallsJson 中的工具调用名重映射到副本名（工具重名被改为「 (2)」时） */
+function remapToolCallsJson(value: string | undefined, map: Map<string, string>): string {
+  if (!value || map.size === 0) return value || '[]';
+  try {
+    const calls = JSON.parse(value) as Array<{ name?: string }>;
+    if (!Array.isArray(calls)) return value;
+    let changed = false;
+    for (const c of calls) {
+      if (c && typeof c.name === 'string') {
+        const mapped = map.get(c.name);
+        if (mapped && mapped !== c.name) {
+          c.name = mapped;
+          changed = true;
+        }
+      }
+    }
+    return changed ? JSON.stringify(calls) : value;
+  } catch {
+    return value;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 导入
+// ---------------------------------------------------------------------------
+
+interface ImportGameplayResult {
+  sessionId: number;
+  sessionTitle: string;
+  createdNpcs: number;
+  importedWorldBook: boolean;
+  importedPersona: boolean;
+  importedTools: number;
+  importedMessages: number;
+}
+
+/**
+ * 把游戏导出 JSON 完全重建为可游玩的会话。
+ * 返回统计信息；失败抛出带信息的 Error。
+ */
+export async function importGameplay(payload: unknown): Promise<ImportGameplayResult> {
+  const data = parseGameplayPayload(payload);
+
+  // ---- 1. 工具（生成式技能）：重名不覆盖，创建独立副本 ----
+  // toolNameMap：源工具名 → 副本最终名，供 NPC enabledToolNames / 消息记录重映射
+  let importedTools = 0;
+  const toolNameMap = new Map<string, string>();
+  for (const tool of data.tools) {
+    if (!tool.name) continue;
+    const finalName = await uniqueName('tools', tool.name);
+    toolNameMap.set(tool.name, finalName);
+    await db.tools.add({
+      name: finalName,
+      jsonContent: tool.jsonContent,
+      executionJson: tool.executionJson ?? null,
+      isBuiltIn: false,
+      origin: 'imported',
+      createdAt: Date.now(),
+      displayOrder: (await db.tools.count()) + 1,
+    });
+    importedTools += 1;
+  }
+
+  // ---- 2. 角色（NPC）与用户人设：重名不覆盖，创建副本；保留源 id → 新 id 映射 ----
+  const sourceNpcIdToNew = new Map<number, number>();
+  let createdNpcs = 0;
+  const createNpcCopy = async (source: NpcCharacter): Promise<number | null> => {
+    if (!source || !source.name) return null;
+    if (source.id != null && sourceNpcIdToNew.has(source.id)) return sourceNpcIdToNew.get(source.id)!;
+    const finalName = await uniqueName('npcs', source.name);
+    const id = await db.npcs.add({
+      name: finalName,
+      prompt: source.prompt ?? '',
+      greeting: source.greeting ?? '',
+      alternateGreetings: source.alternateGreetings ?? [],
+      avatarColorOrdinal: source.avatarColorOrdinal ?? 0,
+      avatarDataUrl: source.avatarDataUrl ?? null,
+      enabledToolNames: (source.enabledToolNames ?? []).map((n) => toolNameMap.get(n) ?? n),
+      isBuiltIn: false,
+      createdAt: Date.now(),
+    });
+    if (source.id != null) sourceNpcIdToNew.set(source.id, id);
+    createdNpcs += 1;
+    return id;
+  };
+
+  // 参与角色按导出顺序登记
+  for (const entry of data.npcs) {
+    await createNpcCopy(entry.npc);
+  }
+
+  // 用户人设角色
+  let personaNpcId: number | null = null;
+  if (data.userPersona) {
+    personaNpcId = await createNpcCopy(data.userPersona);
+  }
+
+  // ---- 3. 世界书：重名不覆盖，创建副本 ----
+  let importedWorldBook = false;
+  let worldBookId: number | null = null;
+  if (data.worldBook && data.worldBook.name) {
+    const finalName = await uniqueName('worldBooks', data.worldBook.name);
+    worldBookId = await db.worldBooks.add({
+      name: finalName,
+      content: data.worldBook.content ?? '',
+      imageUri: null,
+      createdAt: Date.now(),
+    });
+    importedWorldBook = true;
+  }
+
+  // ---- 4. 会话 ----
+  const src = data.session;
+  const title = data.title?.trim() || src.title || '导入的游戏';
+  const sessionId = await db.sessions.add({
+    title,
+    mode: src.mode === 'NPC' || src.mode === 'GROUP' ? src.mode : 'STANDARD',
+    associatedId: null,
+    worldBookId,
+    userPersonaNpcId: personaNpcId,
+    enableGreeting: src.enableGreeting !== false,
+    mentionOnlyMode: src.mode === 'GROUP' && src.mentionOnlyMode === true,
+    turnOrderMode: src.turnOrderMode === 'RANDOM' ? 'RANDOM' : 'PRESET',
+    workspaceDir: null, // 导入的会话分配全新的独立工作目录，不继承源导出文件
+    turnQueueJson: remapQueueJson(src.turnQueueJson || '[]', sourceNpcIdToNew),
+    turnQueueHistoryJson: remapQueueJson(src.turnQueueHistoryJson || '[]', sourceNpcIdToNew),
+    loopIndex: Number.isFinite(src.loopIndex) ? src.loopIndex : 0,
+    pinned: 0,
+    lastMessage: '',
+    updatedAt: Date.now(),
+    createdAt: Date.now(),
+  });
+  // 会话专属工作目录（当前酒馆实例 + 会话 id，单层目录、不嵌套）
+  const workspaceDir = createSessionWorkspaceDir(sessionId);
+  await db.sessions.update(sessionId, { workspaceDir });
+  // 创建对话的同时预建其专属工作目录
+  await ensureSessionWorkspaceDir(workspaceDir);
+
+  // ---- 5. 参与者（玩家恒定 -1；NPC participantId = 新 npc id，保持座位顺序） ----
+  const participants: ChatParticipant[] = [];
+  participants.push({
+    sessionId,
+    participantId: -1,
+    kind: 'PLAYER',
+    npcId: null,
+    displayName: '用户',
+    seatOrder: 0,
+  });
+  const sortedSrcParticipants = [...data.sessionParticipants].sort((a, b) => a.seatOrder - b.seatOrder);
+  for (const sp of sortedSrcParticipants) {
+    if (sp.kind !== 'NPC' || sp.npcId == null) continue;
+    const newNpcId = sourceNpcIdToNew.get(sp.npcId) ?? null;
+    if (newNpcId == null) continue;
+    participants.push({
+      sessionId,
+      participantId: newNpcId,
+      kind: 'NPC',
+      npcId: newNpcId,
+      displayName: sp.displayName || '',
+      seatOrder: participants.length,
+    });
+  }
+  await db.participants.bulkAdd(participants);
+
+  // 会话关联角色（NPC 模式）
+  const npcParts = participants.filter((p) => p.kind === 'NPC');
+  const sessionMode = npcParts.length === 1 ? 'NPC' : 'GROUP';
+  await db.sessions.update(sessionId, {
+    associatedId: sessionMode === 'NPC' ? npcParts[0].npcId : null,
+    mode: sessionMode,
+  });
+
+  // 导出文件未包含对话时，按新建对话的规则写入角色开场白。
+  let importedMessages = 0;
+  if (data.messages.length === 0 && src.enableGreeting !== false) {
+    const remappedQueue = (() => {
+      try {
+        const queue = JSON.parse(remapQueueJson(src.turnQueueJson || '[]', sourceNpcIdToNew));
+        return Array.isArray(queue) ? queue.map(Number) : [];
+      } catch {
+        return [];
+      }
+    })();
+    const greetingParticipant = sessionMode === 'NPC'
+      ? npcParts[0]
+      : npcParts.find((participant) => participant.participantId === remappedQueue[0]);
+    if (greetingParticipant?.npcId != null) {
+      const greetingNpc = await db.npcs.get(greetingParticipant.npcId);
+      if (greetingNpc) {
+        const preview = await seedOpeningGreeting(sessionId, greetingNpc, greetingParticipant.displayName || greetingNpc.name);
+        if (preview) {
+          await db.sessions.update(sessionId, { lastMessage: preview });
+          importedMessages = 1;
+        }
+      }
+    }
+  }
+
+  // ---- 6. 消息（保留顺序与相对间隔，id 重建） ----
+  // 注意：导出时已剔除性能/调试字段（tokens、latency、model、raw body、attachmentInfos），
+  // 此处为所有非导出字段补齐默认值，兼容旧版导出文件。
+  if (data.messages.length > 0) {
+    const sorted = [...data.messages].sort((a, b) => a.timestamp - b.timestamp);
+    const firstTs = sorted[0]?.timestamp ?? Date.now();
+    const baseTime = Date.now() - (sorted.length - 1) * 30_000;
+    for (const m of sorted) {
+      const speaker = m.speakerParticipantId == null
+        ? null
+        : m.speakerParticipantId === -1
+          ? -1
+          : sourceNpcIdToNew.get(m.speakerParticipantId) ?? null;
+      const row: ChatMessage = {
+        sessionId,
+        role: m.role,
+        speakerParticipantId: speaker,
+        speakerName: m.speakerName ?? null,
+        content: m.content ?? '',
+        toolCallsJson: remapToolCallsJson(m.toolCallsJson || '[]', toolNameMap),
+        toolCallId: m.toolCallId ?? null,
+        thinkingContent: m.thinkingContent ?? null,
+        loopIndex: m.loopIndex ?? null,
+        timestamp: baseTime + Math.max(0, (m.timestamp ?? firstTs) - firstTs),
+        latencyMs: null,
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+        tokensPerSec: null,
+        modelUsed: null,
+        attachments: m.attachments ?? [],
+        attachmentInfos: [],
+        displayRef: m.displayRef ?? null,
+        rawRequestBody: null,
+        rawResponseBody: null,
+      };
+      await db.messages.add(row);
+      importedMessages += 1;
+    }
+    // 会话预览
+    const lastVisible = [...sorted].reverse().find((m) => m.role !== 'tool');
+    if (lastVisible && lastVisible.content) {
+      await db.sessions.update(sessionId, { lastMessage: lastVisible.content.slice(0, 60) });
+    }
+  }
+
+  return {
+    sessionId,
+    sessionTitle: title,
+    createdNpcs,
+    importedWorldBook,
+    importedPersona: Boolean(personaNpcId),
+    importedTools,
+    importedMessages,
+  };
+}
+
+/** 校验并规范化游戏导出结构；失败抛出带信息的 Error */
+function parseGameplayPayload(payload: unknown): GameplayExportPayload {
+  if (!payload || typeof payload !== 'object') throw new Error('无效的游戏文件');
+  const p = payload as Partial<GameplayExportPayload> & { participants?: ChatParticipant[] };
+  if (p.format !== GAMEPLAY_FORMAT) {
+    throw new Error('不是 Tavern Harness 游戏导出文件');
+  }
+  const session = p.session as Partial<ChatSession> | undefined;
+  if (!session || typeof session !== 'object' || !session.mode) {
+    throw new Error('游戏文件缺少会话信息');
+  }
+  return {
+    format: GAMEPLAY_FORMAT,
+    version: typeof p.version === 'number' ? p.version : 0,
+    exportedAt: typeof p.exportedAt === 'number' ? p.exportedAt : 0,
+    appName: 'Tavern Harness',
+    title: typeof p.title === 'string' ? p.title : (session.title ?? ''),
+    includeHistory: p.includeHistory !== false,
+    session: session as Omit<ChatSession, 'id' | 'lastMessage'>,
+    sessionParticipants: Array.isArray(p.sessionParticipants)
+      ? p.sessionParticipants
+      : Array.isArray(p.participants)
+        ? p.participants
+        : [],
+    messages: Array.isArray(p.messages) ? p.messages : [],
+    npcs: Array.isArray(p.npcs) ? p.npcs : [],
+    worldBook: p.worldBook,
+    userPersona: p.userPersona,
+    tools: Array.isArray(p.tools) ? p.tools : [],
+  };
+}

package/src/core/horizontalWheel.ts

@@ -0,0 +1,93 @@
+// ============================================================
+// 横向滚动容器的「垂直滚轮 → 水平滚动」翻译
+//
+// 问题背景：类似 .side-nav（侧边栏上部导航 / 角色工坊 tab 栏）的
+// 容器是 overflow-x: auto。桌面鼠标滚轮默认产生垂直 deltaY，
+// 悬停其上不会触发横向滚动，导致窄布局下按钮被裁掉却滚不动。
+//
+// 方案：在 document 上做事件委托（capture + passive:false），
+// 当滚轮事件落在带 [data-hscroll] 的容器内、且容器存在横向溢出时，
+// 把 deltaY（必要时叠加 deltaX）写入 scrollLeft；滚动到两端边界时
+// 还原默认行为（放行给外层容器/页面），避免“粘住”不可达的滚动条。
+//
+// 用法：给希望滚轮横滚的容器加 data-hscroll 属性即可，无需改组件。
+// 本模块在应用启动时调用一次 enableHorizontalWheel()。
+// ============================================================
+
+function findScrollParent(target: EventTarget | null): HTMLElement | null {
+  let el = target instanceof Element ? (target as HTMLElement) : null;
+  while (el && el !== document.body) {
+    if (el.matches('[data-hscroll]')) return el;
+    el = el.parentElement;
+  }
+  return null;
+}
+
+// 维护横向溢出提示状态（class 由 CSS 的 mask 渐变消费）：
+//   has-overflow — 存在横向溢出（内容确实被遮挡）
+//   hidden-left  — 左侧有内容被遮挡 → 左边缘淡出
+//   hidden-right — 右侧有内容被遮挡 → 右边缘淡出
+function updateOverflowHint(el: HTMLElement): void {
+  const overflowX = el.scrollWidth > el.clientWidth + 1;
+  const atStart = el.scrollLeft <= 1;
+  const atEnd = el.scrollLeft >= el.scrollWidth - el.clientWidth - 1;
+  el.classList.toggle('has-overflow', overflowX);
+  el.classList.toggle('hidden-left', overflowX && !atStart);
+  el.classList.toggle('hidden-right', overflowX && !atEnd);
+}
+
+export function enableHorizontalWheel(): void {
+  // 滚动时刷新溢出提示
+  document.addEventListener(
+    'scroll',
+    (e: Event) => {
+      const target = e.target;
+      if (!(target instanceof Element)) return;
+      const h = target.closest('[data-hscroll]') as HTMLElement | null;
+      if (!h) return;
+      updateOverflowHint(h);
+    },
+    { capture: true, passive: true }
+  );
+
+  // 布局变化（初次渲染 / 窗口尺寸变化 / 字体加载）后重新计算
+  const sweep = () => {
+    document.querySelectorAll<HTMLElement>('[data-hscroll]').forEach(updateOverflowHint);
+  };
+  // 初次渲染可能晚于 enableHorizontalWheel 调用，延后到 React 挂载完成后执行
+  requestAnimationFrame(() => setTimeout(sweep, 0));
+  window.addEventListener('resize', sweep);
+  window.addEventListener('load', sweep);
+  document.fonts?.ready?.then(sweep).catch(() => {});
+  // 动态挂载的 [data-hscroll] 容器（如工坊 tab 切换）出现后立即计算
+  const mo = new MutationObserver(sweep);
+  mo.observe(document.body, { subtree: true, childList: true });
+
+  document.addEventListener(
+    'wheel',
+    (e: WheelEvent) => {
+      const el = findScrollParent(e.target);
+      if (!el) return;
+
+      const canScrollX = el.scrollWidth > el.clientWidth + 1;
+      if (!canScrollX) return;
+
+      // 只有横向溢出才接管；无横向溢出时保持默认（不影响页面内其它滚动）
+      const delta = e.deltaY ?? 0;
+      if (delta === 0 && (e.deltaX ?? 0) === 0) return;
+
+      // 滚轮偏移换算：正常一次“格”约 100px，与常规滚动体感一致
+      let target = el.scrollLeft + delta + (e.deltaX ?? 0);
+      const max = el.scrollWidth - el.clientWidth;
+      const prev = el.scrollLeft;
+      target = Math.max(0, Math.min(target, max));
+      if (target !== prev) {
+        el.scrollLeft = target;
+        // 到此为止：真正发生了横向滚动，阻止默认（避免外层/页面也跟着滚）
+        e.preventDefault();
+      }
+      // 若目标在两端（无剩余空间），不 preventDefault，让事件自然冒泡
+    },
+    { capture: true, passive: false }
+  );
+}