@zhin.js/core 1.1.34 → 1.1.35

package/lib/built/generic-segment-mapper.js

@@ -0,0 +1,190 @@
+import { isMediaRef, readMentionTarget, } from './segment-contract/index.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readPlatform(seg) {
+    const platform = seg.platform;
+    return platform && typeof platform === 'object' ? platform : undefined;
+}
+function normalizeMention(seg) {
+    const data = seg.data;
+    const target = readMentionTarget(data);
+    const name = typeof data.name === 'string' && data.name ? data.name : undefined;
+    const platform = readPlatform(seg);
+    return {
+        type: 'mention',
+        data: name ? { target, name } : { target },
+        ...(platform ? { platform } : {}),
+    };
+}
+const MEDIA_SEGMENT_TYPES = new Set(['image', 'audio', 'video', 'file']);
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+function legacyMediaRef(data) {
+    if (isMediaRef(data.media))
+        return data.media;
+    const url = nonEmptyString(data.url) ?? nonEmptyString(data.href) ?? nonEmptyString(data.src);
+    const path = nonEmptyString(data.path) ?? nonEmptyString(data.file_path);
+    const base64 = nonEmptyString(data.base64);
+    const file = nonEmptyString(data.file) ?? nonEmptyString(data.file_id);
+    const value = url ?? path ?? base64 ?? file;
+    if (!value)
+        return undefined;
+    const kind = url ? 'url'
+        : path ? 'path'
+            : base64 ? 'base64'
+                : /^(?:[a-z][a-z0-9+.-]*:)?\/\//iu.test(value) ? 'url'
+                    : /^(?:\.{1,2}\/|\/|~\/)/u.test(value) ? 'path'
+                        : 'file';
+    const mimeType = nonEmptyString(data.mime_type) ?? nonEmptyString(data.mimeType);
+    // Legacy top-level fileName names the rendered file segment. Keep source
+    // metadata reserved for an explicit media object instead of duplicating it.
+    const fileName = nonEmptyString(data.media_file_name);
+    const size = typeof data.size === 'number' && Number.isFinite(data.size) ? data.size : undefined;
+    return {
+        kind,
+        value,
+        ...(mimeType ? { mime_type: mimeType } : {}),
+        ...(fileName ? { file_name: fileName } : {}),
+        ...(size === undefined ? {} : { size }),
+    };
+}
+/**
+ * The sole ingress compatibility boundary for media. Adapters may emit their
+ * native `url`/`path`/`file` fields, but every consumer receives `data.media`.
+ */
+function normalizeMedia(seg) {
+    const data = seg.data;
+    const platform = readPlatform(seg);
+    const media = legacyMediaRef(data);
+    if (!media)
+        return seg;
+    const attributes = seg.type === 'image'
+        ? { ...(typeof data.alt === 'string' ? { alt: data.alt } : {}) }
+        : seg.type === 'audio'
+            ? { ...(typeof data.duration === 'number' ? { duration: data.duration } : {}) }
+            : seg.type === 'video'
+                ? {
+                    ...(typeof data.duration === 'number' ? { duration: data.duration } : {}),
+                    ...(typeof data.alt === 'string' ? { alt: data.alt } : {}),
+                }
+                : {
+                    ...(nonEmptyString(data.name) ?? nonEmptyString(data.file_name) ?? nonEmptyString(data.fileName)
+                        ? { name: nonEmptyString(data.name) ?? nonEmptyString(data.file_name) ?? nonEmptyString(data.fileName) }
+                        : {}),
+                };
+    return {
+        type: seg.type,
+        data: { media, ...attributes },
+        ...(platform ? { platform } : {}),
+    };
+}
+function normalizeReply(seg) {
+    const data = seg.data;
+    const messageId = String(data.message_id ?? data.id ?? '').trim();
+    if (!messageId)
+        return seg;
+    return { type: 'reply', data: { message_id: messageId } };
+}
+function normalizeLink(seg) {
+    const data = seg.data;
+    const url = String(data.url ?? data.href ?? '').trim();
+    if (!url)
+        return seg;
+    const text = typeof data.text === 'string' && data.text ? data.text : undefined;
+    const platform = readPlatform(seg);
+    return {
+        type: 'link',
+        data: text ? { url, text } : { url },
+        ...(platform ? { platform } : {}),
+    };
+}
+function normalizeForward(seg) {
+    const data = seg.data;
+    const forwardId = String(data.forward_id ?? data.id ?? data.resid ?? '').trim();
+    if (!forwardId)
+        return seg;
+    const title = typeof data.title === 'string' ? data.title : undefined;
+    const messages = Array.isArray(data.messages) ? data.messages : undefined;
+    const platform = { ...(readPlatform(seg) ?? {}) };
+    if (data.resid != null)
+        platform.resid = String(data.resid);
+    return {
+        type: 'forward',
+        data: {
+            forward_id: forwardId,
+            ...(title ? { title } : {}),
+            ...(messages ? { messages: messages } : {}),
+        },
+        ...(Object.keys(platform).length ? { platform } : {}),
+    };
+}
+function isPlatformSticker(seg) {
+    if (seg.type !== 'sticker')
+        return false;
+    const data = seg.data;
+    return data.package_id != null
+        || data.sticker_id != null
+        || data.packageId != null
+        || data.stickerId != null;
+}
+function normalizeFace(seg) {
+    if (isPlatformSticker(seg))
+        return seg;
+    const data = seg.data;
+    const rawId = data.id ?? data.face_id;
+    const name = typeof data.name === 'string'
+        ? data.name
+        : typeof data.text === 'string'
+            ? data.text
+            : undefined;
+    const platform = readPlatform(seg);
+    return {
+        type: 'face',
+        data: {
+            ...(rawId != null ? { id: rawId } : {}),
+            ...(name ? { name } : {}),
+        },
+        ...(platform ? { platform } : {}),
+    };
+}
+function normalizeMarkdown(seg) {
+    const data = seg.data;
+    const content = typeof data.content === 'string'
+        ? data.content
+        : typeof data.text === 'string'
+            ? data.text
+            : '';
+    return { type: 'markdown', data: { content } };
+}
+function normalizeSegment(seg) {
+    if (seg.type === 'at' || seg.type === 'mention')
+        return normalizeMention(seg);
+    if (MEDIA_SEGMENT_TYPES.has(seg.type))
+        return normalizeMedia(seg);
+    if (seg.type === 'reply')
+        return normalizeReply(seg);
+    if (seg.type === 'forward')
+        return normalizeForward(seg);
+    if (seg.type === 'sticker' && isPlatformSticker(seg))
+        return seg;
+    if (seg.type === 'face' || seg.type === 'sticker' || seg.type === 'emoji')
+        return normalizeFace(seg);
+    if (seg.type === 'link')
+        return normalizeLink(seg);
+    if (seg.type === 'markdown')
+        return normalizeMarkdown(seg);
+    return seg;
+}
+function asMessageSegments(content) {
+    return content.map((item) => {
+        if (typeof item === 'string')
+            return { type: 'text', data: { text: item } };
+        return item;
+    });
+}
+/** wire 段数组 → canonical Segment[]（包括所有媒体的 `data.media` 归一）。 */
+export function toCanonicalSegments(content) {
+    return asMessageSegments(content).map((seg) => normalizeSegment(seg));
+}

package/lib/built/html-renderer-loader.d.ts

@@ -0,0 +1,13 @@
+import type { HtmlRendererForRichSegment } from './rich-segments/types.js';
+/** 动态 import 时使用的包名（与 @zhin.js/html-renderer package.json 一致） */
+export declare const HTML_RENDERER_PACKAGE = "@zhin.js/html-renderer";
+export interface LoadHtmlRendererOptions {
+    getConfig?: () => Record<string, unknown> | undefined;
+    warn?: (message: string) => void;
+}
+/** zhin 启动时已创建 renderer 时注入，避免 core 目录下 peer 解析失败 */
+export declare function seedHtmlRenderer(renderer: HtmlRendererForRichSegment): void;
+/** 动态加载 @zhin.js/html-renderer；未安装时 warn 一次并返回 undefined */
+export declare function loadHtmlRenderer(opts?: LoadHtmlRendererOptions): Promise<HtmlRendererForRichSegment | undefined>;
+/** 测试用：重置加载缓存 */
+export declare function resetHtmlRendererLoaderForTests(): void;

package/lib/built/html-renderer-loader.js

@@ -0,0 +1,33 @@
+import { importOptionalPeerPackage } from './optional-peer-import.js';
+/** 动态 import 时使用的包名（与 @zhin.js/html-renderer package.json 一致） */
+export const HTML_RENDERER_PACKAGE = '@zhin.js/html-renderer';
+let cached;
+let warned = false;
+/** zhin 启动时已创建 renderer 时注入，避免 core 目录下 peer 解析失败 */
+export function seedHtmlRenderer(renderer) {
+    cached = renderer;
+}
+/** 动态加载 @zhin.js/html-renderer；未安装时 warn 一次并返回 undefined */
+export async function loadHtmlRenderer(opts) {
+    if (cached !== undefined) {
+        return cached ?? undefined;
+    }
+    try {
+        const mod = await importOptionalPeerPackage(HTML_RENDERER_PACKAGE);
+        cached = mod.createHtmlRenderer(opts?.getConfig?.() ?? {});
+        return cached;
+    }
+    catch {
+        if (!warned) {
+            warned = true;
+            opts?.warn?.(`未安装 ${HTML_RENDERER_PACKAGE}，html/markdown=>image 已降级为 text。安装: pnpm add ${HTML_RENDERER_PACKAGE}`);
+        }
+        cached = null;
+        return undefined;
+    }
+}
+/** 测试用：重置加载缓存 */
+export function resetHtmlRendererLoaderForTests() {
+    cached = undefined;
+    warned = false;
+}

package/lib/built/html-segment-fallback.d.ts

@@ -1,9 +1,9 @@
 /**
- * 出站 `html` 消息段兜底：未装 html-renderer 或转图失败时，自动剥离为 text 段。
+ * 出站 `html` 消息段兜底：等价于 Adapter policy `html:'text'`。
+ * 出站渲染首选 `resolveRichSegments`（renderSendMessage 首步）。
  */
 import type { Plugin } from '../plugin.js';
 import type { SendContent } from '../types.js';
 export declare function coerceHtmlSegmentsToText(content: SendContent): SendContent;
 /** 注册链尾 before.sendMessage：将未转换的 html 段降级为 text */
 export declare function registerHtmlSegmentFallback(plugin: Plugin): () => void;
-//# sourceMappingURL=html-segment-fallback.d.ts.map

package/lib/built/html-segment-fallback.js

@@ -47,4 +47,3 @@ export function registerHtmlSegmentFallback(plugin) {
     plugin.root.on('before.sendMessage', handler);
     return () => plugin.root.off('before.sendMessage', handler);
 }
-//# sourceMappingURL=html-segment-fallback.js.map

package/lib/built/html-to-text.d.ts

@@ -14,4 +14,3 @@ export declare function htmlToPlainTextWithBlockBreaks(html: string, options?: H
  * HTML 卡片出站回退：块级换行 + 语义标题轻量 markdown 前缀。
  */
 export declare function htmlToFallbackText(html: string, options?: HtmlToPlainTextOptions): string;
-//# sourceMappingURL=html-to-text.d.ts.map

package/lib/built/html-to-text.js

@@ -79,20 +79,21 @@ function stripRemainingTags(html) {
     return out;
 }
 function decodeCommonEntities(text) {
-    return text
-        .replace(/ /gi, ' ')
-        .replace(/&/g, '&')
-        .replace(/&lt;/g, '<')
-        .replace(/&gt;/g, '>')
-        .replace(/&quot;/g, '"')
-        .replace(/&#39;/g, "'")
-        .replace(/&apos;/g, "'")
-        .replace(/&#(\d+);/g, (_, code) => {
-        const n = Number(code);
-        return Number.isFinite(n) && n >= 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
-    })
-        .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => {
-        const n = parseInt(hex, 16);
+    return text.replace(/&(#x[0-9a-fA-F]+|#\d+|nbsp|amp|lt|gt|quot|apos);/gi, (entity) => {
+        const key = entity.slice(1, -1).toLowerCase();
+        if (key === 'nbsp')
+            return ' ';
+        if (key === 'amp')
+            return '&';
+        if (key === 'lt')
+            return '<';
+        if (key === 'gt')
+            return '>';
+        if (key === 'quot')
+            return '"';
+        if (key === 'apos')
+            return "'";
+        const n = key.startsWith('#x') ? parseInt(key.slice(2), 16) : Number(key.slice(1));
         return Number.isFinite(n) && n >= 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
     });
 }
@@ -163,4 +164,3 @@ export function htmlToFallbackText(html, options) {
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }
-//# sourceMappingURL=html-to-text.js.map

package/lib/built/inbound-pipeline.d.ts

@@ -0,0 +1,37 @@
+/**
+ * InboundMessagePipeline — ordered IM inbound pipeline for adapter message.receive.
+ *
+ * Extracted from Adapter.emit() override to improve testability and decoupling.
+ * Handles: event routing, logging, backpressure, pipeline execution, observer emission.
+ */
+import { type Logger } from '@zhin.js/logger';
+import { type Message as MessageType } from '../message.js';
+import type { Plugin } from '../plugin.js';
+export interface InboundPipelineOptions {
+    getPlugin: () => Plugin | null;
+    logger: Logger;
+    getMaxConcurrentMessages: () => number;
+    getPendingMessages: () => number;
+    decrementPending: () => void;
+}
+export declare class InboundMessagePipeline {
+    private readonly options;
+    constructor(options: InboundPipelineOptions);
+    /**
+     * Check if message should be dropped due to backpressure (sync check).
+     * Call this BEFORE receive() to match original emit() backpressure contract.
+     */
+    shouldDropDueToBackpressure(): boolean;
+    /**
+     * Process a message.receive event through the full inbound pipeline:
+     * 1. Logging (caller should have already logged via emit)
+     * 2. runInboundMessage (middleware → dispatcher → lifecycle)
+     * 3. Adapter observer emission
+     *
+     * Note: backpressure check is done by the caller via shouldDropDueToBackpressure()
+     */
+    receive(message: MessageType<any>, emitAdapterObservers: () => void): Promise<void>;
+    /** Bridge notice/request events to plugin dispatch */
+    bridgeNoticeOrRequest(event: string, args: unknown[], directEmit: () => boolean): boolean;
+    private logIncoming;
+}

package/lib/built/inbound-pipeline.js

@@ -0,0 +1,63 @@
+/**
+ * InboundMessagePipeline — ordered IM inbound pipeline for adapter message.receive.
+ *
+ * Extracted from Adapter.emit() override to improve testability and decoupling.
+ * Handles: event routing, logging, backpressure, pipeline execution, observer emission.
+ */
+import { formatCompact, truncatePreview } from '@zhin.js/logger';
+import { segment } from '../utils.js';
+import { runInboundMessage } from './inbound-runner.js';
+export class InboundMessagePipeline {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Check if message should be dropped due to backpressure (sync check).
+     * Call this BEFORE receive() to match original emit() backpressure contract.
+     */
+    shouldDropDueToBackpressure() {
+        const limit = this.options.getMaxConcurrentMessages();
+        return limit > 0 && this.options.getPendingMessages() >= limit;
+    }
+    /**
+     * Process a message.receive event through the full inbound pipeline:
+     * 1. Logging (caller should have already logged via emit)
+     * 2. runInboundMessage (middleware → dispatcher → lifecycle)
+     * 3. Adapter observer emission
+     *
+     * Note: backpressure check is done by the caller via shouldDropDueToBackpressure()
+     */
+    async receive(message, emitAdapterObservers) {
+        this.logIncoming(message);
+        try {
+            await runInboundMessage({
+                plugin: this.options.getPlugin(),
+                message,
+                emitAdapterObservers,
+            });
+        }
+        catch (e) {
+            this.options.logger.warn(`message.receive handling error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        finally {
+            this.options.decrementPending();
+        }
+    }
+    /** Bridge notice/request events to plugin dispatch */
+    bridgeNoticeOrRequest(event, args, directEmit) {
+        const result = directEmit();
+        const plugin = this.options.getPlugin();
+        if (plugin) {
+            void plugin.dispatch(event, args[0]);
+        }
+        return result;
+    }
+    logIncoming(message) {
+        this.options.logger.debug(formatCompact({
+            recv: `${message.$channel.type}(${message.$channel.id})`,
+            endpoint: message.$endpoint,
+            preview: truncatePreview(segment.raw(message.$content)),
+        }));
+    }
+}

package/lib/built/inbound-runner.d.ts

@@ -20,4 +20,3 @@ export interface InboundRunResult {
  * Agent / 业务逻辑一致。
  */
 export declare function runInboundMessage(options: RunInboundMessageOptions): Promise<InboundRunResult>;
-//# sourceMappingURL=inbound-runner.d.ts.map

package/lib/built/inbound-runner.js

@@ -1,7 +1,6 @@
 /**
  * Inbound runner — one ordered entry for IM message.receive processing.
  */
-import { Message } from '../message.js';
 function getDispatcher(plugin) {
     const dispatcher = plugin?.inject('dispatcher');
     if (dispatcher && typeof dispatcher.dispatch === 'function') {
@@ -19,7 +18,6 @@ function getDispatcher(plugin) {
  */
 export async function runInboundMessage(options) {
     const { plugin, message, emitAdapterObservers } = options;
-    Message.syncQuoteId(message);
     const dispatcher = getDispatcher(plugin);
     const root = plugin?.root;
     if (dispatcher && root) {
@@ -34,4 +32,3 @@ export async function runInboundMessage(options) {
     emitAdapterObservers();
     return { dispatched: !!dispatcher };
 }
-//# sourceMappingURL=inbound-runner.js.map

package/lib/built/interactive-segment-contract.d.ts

@@ -0,0 +1,6 @@
+import type { InteractivePolicy } from './interactive-segments/types.js';
+/** 契约测试：adapter 须声明 interactivePolicy */
+export declare function assertAdapterDeclaresInteractivePolicy(adapterClass: {
+    interactivePolicy?: InteractivePolicy;
+}): void;
+export type { InteractivePolicy };

package/lib/built/interactive-segment-contract.js

@@ -0,0 +1,9 @@
+/** 契约测试：adapter 须声明 interactivePolicy */
+export function assertAdapterDeclaresInteractivePolicy(adapterClass) {
+    if (!adapterClass.interactivePolicy) {
+        throw new Error('Adapter must declare static interactivePolicy');
+    }
+    if (adapterClass.interactivePolicy !== 'native' && adapterClass.interactivePolicy !== 'text') {
+        throw new Error('interactivePolicy must be "native" or "text"');
+    }
+}

package/lib/built/interactive-segments/action.d.ts

@@ -0,0 +1,17 @@
+import type { Message } from '../../message.js';
+import type { MessageElement } from '../../types.js';
+import { type ActionSegmentData } from './types.js';
+export declare function actionSegment(data: ActionSegmentData): MessageElement;
+export declare function getActionFromMessage(message: Message<any>): ActionSegmentData | undefined;
+/** 入站互动 action（按钮点击等），不应计入用户发言/消息统计 */
+export declare function isActionMessage(message: Message<any>): boolean;
+/** 去掉 @bot、XML at 段、首尾空白（QQ 指令预填文本归一化） */
+export declare function stripInteractiveCommandText(raw: string): string;
+/** 从文本降级输入解析 payload（需在 active session 的 fallback.map 中查找） */
+export declare function resolveTextFallbackPayload(raw: string, map: Record<string, string>): string | undefined;
+/**
+ * 从用户文本入站解析 interactive payload：
+ * 归一化 → 直接匹配 prefix:session:id → fallback 数字映射
+ */
+export declare function resolvePayloadFromText(raw: string, map?: Record<string, string>): string | undefined;
+export declare function formatActionAsRaw(data: ActionSegmentData): string;

package/lib/built/interactive-segments/action.js

@@ -0,0 +1,69 @@
+import { ACTION_SEGMENT_TYPE, isActionSegment, } from './types.js';
+export function actionSegment(data) {
+    return { type: ACTION_SEGMENT_TYPE, data };
+}
+export function getActionFromMessage(message) {
+    for (const item of message.$content ?? []) {
+        if (typeof item === 'string')
+            continue;
+        if (isActionSegment(item))
+            return item.data;
+    }
+    return undefined;
+}
+/** 入站互动 action（按钮点击等），不应计入用户发言/消息统计 */
+export function isActionMessage(message) {
+    return getActionFromMessage(message) != null;
+}
+const PAYLOAD_PATTERN = /^[a-z0-9_]+:[^:\s]+:[a-z0-9_-]+$/i;
+/** 去掉 @bot、XML at 段、首尾空白（QQ 指令预填文本归一化） */
+export function stripInteractiveCommandText(raw) {
+    let text = raw.trim();
+    text = stripXmlAtSegments(text);
+    text = text.replace(/^@\S+\s+/u, '');
+    text = text.replace(/\s+/g, ' ').trim();
+    return text;
+}
+function stripXmlAtSegments(text) {
+    let out = '';
+    let cursor = 0;
+    while (cursor < text.length) {
+        const start = text.toLowerCase().indexOf('<at ', cursor);
+        if (start < 0)
+            break;
+        const end = text.indexOf('/>', start + 4);
+        if (end < 0)
+            break;
+        out += text.slice(cursor, start) + ' ';
+        cursor = end + 2;
+    }
+    return out + text.slice(cursor);
+}
+/** 从文本降级输入解析 payload（需在 active session 的 fallback.map 中查找） */
+export function resolveTextFallbackPayload(raw, map) {
+    const trimmed = raw.trim();
+    if (map[trimmed])
+        return map[trimmed];
+    const match = trimmed.match(/^(?:ttt\s+)?(\d)$/i);
+    if (match && map[match[1]])
+        return map[match[1]];
+    return undefined;
+}
+/**
+ * 从用户文本入站解析 interactive payload：
+ * 归一化 → 直接匹配 prefix:session:id → fallback 数字映射
+ */
+export function resolvePayloadFromText(raw, map) {
+    const normalized = stripInteractiveCommandText(raw);
+    if (!normalized)
+        return undefined;
+    if (PAYLOAD_PATTERN.test(normalized))
+        return normalized;
+    if (map && Object.keys(map).length > 0) {
+        return resolveTextFallbackPayload(normalized, map);
+    }
+    return undefined;
+}
+export function formatActionAsRaw(data) {
+    return data.payload;
+}

package/lib/built/interactive-segments/button-spec.d.ts

@@ -0,0 +1,10 @@
+import type { ButtonData } from './types.js';
+/** 键盘布局单元：`segment.button()` 产物，仅用于组装 `segment.keyboard()` */
+export declare class ButtonSpec {
+    readonly data: ButtonData;
+    constructor(data: ButtonData);
+}
+export type KeyboardRowInput = Array<ButtonSpec | ButtonData>;
+export declare function isButtonLike(value: unknown): value is ButtonSpec | ButtonData;
+export declare function normalizeButton(btn: ButtonSpec | ButtonData): ButtonData;
+export declare function normalizeKeyboardRows(rows: KeyboardRowInput[]): ButtonData[][];

package/lib/built/interactive-segments/button-spec.js

@@ -0,0 +1,21 @@
+/** 键盘布局单元：`segment.button()` 产物，仅用于组装 `segment.keyboard()` */
+export class ButtonSpec {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+}
+export function isButtonLike(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    if (value instanceof ButtonSpec)
+        return true;
+    const v = value;
+    return typeof v.id === 'string' && typeof v.label === 'string' && typeof v.payload === 'string';
+}
+export function normalizeButton(btn) {
+    return btn instanceof ButtonSpec ? btn.data : btn;
+}
+export function normalizeKeyboardRows(rows) {
+    return rows.map((row) => row.map(normalizeButton));
+}

package/lib/built/interactive-segments/fallback-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * keyboard 文本降级 fallback map 的中央存储。
+ *
+ * 出站：端点 interactive 策略为 'text' 时，框架把 keyboard 段降级为编号文本，
+ * 同时把「数字 → payload」映射按频道写入本存储（后写覆盖先写，等价
+ * game-kit lastMenus 的“最近一张键盘”语义）。
+ * 入站：框架中间件 / dispatcher 钩子用本存储把用户回复的裸数字解析回
+ * payload，再按 prefix 最长匹配路由给注册的 interactive handler。
+ *
+ * 模块级共享实例与 handlers.ts 的 handler 注册表同例：状态按频道键控、
+ * TTL 有界（对齐 game-hub 菜单上下文的 1h），无裸悬挂业务对象。
+ */
+export declare const KEYBOARD_FALLBACK_TTL_MS: number;
+export declare class KeyboardFallbackStore {
+    #private;
+    private readonly defaultTtlMs;
+    constructor(defaultTtlMs?: number);
+    /** 记录频道最近一次 keyboard 降级的数字→payload 映射（空 map 忽略）。 */
+    remember(channelKey: string, map: Record<string, string>, ttlMs?: number): void;
+    /** 频道当前有效的 fallback map（过期即删并返回 undefined）。 */
+    mapFor(channelKey: string): Record<string, string> | undefined;
+    /** 裸数字 / fallback 键 → payload（无映射或过期返回 undefined）。 */
+    resolve(channelKey: string, raw: string): string | undefined;
+    clear(): void;
+}
+/** 中央共享实例：出站降级写入、入站回跳读取。 */
+export declare const keyboardFallbackStore: KeyboardFallbackStore;
+/** 测试专用：清空中央 fallback 存储。 */
+export declare function resetKeyboardFallbackStoreForTests(): void;

package/lib/built/interactive-segments/fallback-store.js

@@ -0,0 +1,63 @@
+import { resolveTextFallbackPayload } from './action.js';
+/**
+ * keyboard 文本降级 fallback map 的中央存储。
+ *
+ * 出站：端点 interactive 策略为 'text' 时，框架把 keyboard 段降级为编号文本，
+ * 同时把「数字 → payload」映射按频道写入本存储（后写覆盖先写，等价
+ * game-kit lastMenus 的“最近一张键盘”语义）。
+ * 入站：框架中间件 / dispatcher 钩子用本存储把用户回复的裸数字解析回
+ * payload，再按 prefix 最长匹配路由给注册的 interactive handler。
+ *
+ * 模块级共享实例与 handlers.ts 的 handler 注册表同例：状态按频道键控、
+ * TTL 有界（对齐 game-hub 菜单上下文的 1h），无裸悬挂业务对象。
+ */
+export const KEYBOARD_FALLBACK_TTL_MS = 60 * 60 * 1000;
+export class KeyboardFallbackStore {
+    defaultTtlMs;
+    #entries = new Map();
+    constructor(defaultTtlMs = KEYBOARD_FALLBACK_TTL_MS) {
+        this.defaultTtlMs = defaultTtlMs;
+    }
+    /** 记录频道最近一次 keyboard 降级的数字→payload 映射（空 map 忽略）。 */
+    remember(channelKey, map, ttlMs = this.defaultTtlMs) {
+        if (Object.keys(map).length === 0)
+            return;
+        this.#prune();
+        this.#entries.set(channelKey, {
+            map: Object.freeze({ ...map }),
+            expiresAt: Date.now() + ttlMs,
+        });
+    }
+    /** 频道当前有效的 fallback map（过期即删并返回 undefined）。 */
+    mapFor(channelKey) {
+        const entry = this.#entries.get(channelKey);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt < Date.now()) {
+            this.#entries.delete(channelKey);
+            return undefined;
+        }
+        return entry.map;
+    }
+    /** 裸数字 / fallback 键 → payload（无映射或过期返回 undefined）。 */
+    resolve(channelKey, raw) {
+        const map = this.mapFor(channelKey);
+        return map ? resolveTextFallbackPayload(raw, map) : undefined;
+    }
+    clear() {
+        this.#entries.clear();
+    }
+    #prune() {
+        const now = Date.now();
+        for (const [key, entry] of this.#entries) {
+            if (entry.expiresAt < now)
+                this.#entries.delete(key);
+        }
+    }
+}
+/** 中央共享实例：出站降级写入、入站回跳读取。 */
+export const keyboardFallbackStore = new KeyboardFallbackStore();
+/** 测试专用：清空中央 fallback 存储。 */
+export function resetKeyboardFallbackStoreForTests() {
+    keyboardFallbackStore.clear();
+}