@zhin.js/core 1.1.34 → 1.1.35

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

@@ -0,0 +1,16 @@
+import type { Message } from '../../message.js';
+import type { MessageMiddleware } from '../../types.js';
+import type { InteractiveHandler, RegisteredInteractiveHandler } from './types.js';
+/** 旧轨频道键：与出站降级（Adapter.renderSendMessage）及 game-kit channelKey 一致。 */
+export declare function interactiveChannelKey(message: Message<any>): string;
+/**
+ * 文本回跳解析：中央 fallback map（裸数字）→ payload；
+ * 或 QQ 指令预填等直出 `prefix:session:id` payload。
+ */
+export declare function resolveInboundTextPayload(message: Message<any>): string | undefined;
+export declare function registerInteractiveHandler(prefix: string, handler: InteractiveHandler): () => void;
+export declare function getInteractiveHandlers(): readonly RegisteredInteractiveHandler[];
+export declare function resetInteractiveHandlersForTests(): void;
+/** 在根插件上安装一次性 action 路由中间件（幂等） */
+export declare function ensureInteractiveMiddleware(addMiddleware: (mw: MessageMiddleware) => () => void): void;
+export declare function dispatchInteractiveAction(message: Message<any>): Promise<boolean>;

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

@@ -0,0 +1,74 @@
+import { getActionFromMessage, resolvePayloadFromText } from './action.js';
+import { keyboardFallbackStore } from './fallback-store.js';
+const handlers = [];
+let middlewareInstalled = false;
+function findHandler(payload) {
+    let match;
+    for (const entry of handlers) {
+        if (payload.startsWith(entry.prefix)) {
+            if (!match || entry.prefix.length > match.prefix.length) {
+                match = entry;
+            }
+        }
+    }
+    return match?.handler;
+}
+/** 旧轨频道键：与出站降级（Adapter.renderSendMessage）及 game-kit channelKey 一致。 */
+export function interactiveChannelKey(message) {
+    return `${String(message.$adapter)}-${message.$endpoint}-${message.$channel.type}:${message.$channel.id}`;
+}
+/**
+ * 文本回跳解析：中央 fallback map（裸数字）→ payload；
+ * 或 QQ 指令预填等直出 `prefix:session:id` payload。
+ */
+export function resolveInboundTextPayload(message) {
+    const raw = message.$raw?.trim() ?? '';
+    if (!raw)
+        return undefined;
+    return resolvePayloadFromText(raw, keyboardFallbackStore.mapFor(interactiveChannelKey(message)));
+}
+export function registerInteractiveHandler(prefix, handler) {
+    const entry = { prefix, handler };
+    handlers.push(entry);
+    const dispose = () => {
+        const idx = handlers.indexOf(entry);
+        if (idx >= 0)
+            handlers.splice(idx, 1);
+    };
+    return dispose;
+}
+export function getInteractiveHandlers() {
+    return handlers;
+}
+export function resetInteractiveHandlersForTests() {
+    handlers.length = 0;
+    middlewareInstalled = false;
+}
+/** 在根插件上安装一次性 action 路由中间件（幂等） */
+export function ensureInteractiveMiddleware(addMiddleware) {
+    if (middlewareInstalled)
+        return;
+    middlewareInstalled = true;
+    addMiddleware(async (message, next) => {
+        const payload = getActionFromMessage(message)?.payload
+            ?? resolveInboundTextPayload(message);
+        if (!payload)
+            return next();
+        const handler = findHandler(payload);
+        if (!handler)
+            return next();
+        const handled = await handler(message);
+        if (handled)
+            return;
+        return next();
+    });
+}
+export async function dispatchInteractiveAction(message) {
+    const action = getActionFromMessage(message);
+    if (!action)
+        return false;
+    const handler = findHandler(action.payload);
+    if (!handler)
+        return false;
+    return !!(await handler(message));
+}

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

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './button-spec.js';
+export * from './action.js';
+export * from './resolve.js';
+export * from './handlers.js';
+export * from './fallback-store.js';
+export { KeyboardSegment } from './keyboard-segment.js';
+export * from './onebot-keyboard.js';

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

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './button-spec.js';
+export * from './action.js';
+export * from './resolve.js';
+export * from './handlers.js';
+export * from './fallback-store.js';
+export { KeyboardSegment } from './keyboard-segment.js';
+export * from './onebot-keyboard.js';

package/lib/built/interactive-segments/keyboard-segment.d.ts

@@ -0,0 +1,11 @@
+import { type KeyboardSegmentData } from './types.js';
+export declare class KeyboardSegment {
+    readonly data: KeyboardSegmentData;
+    readonly segmentType: "keyboard";
+    constructor(data: KeyboardSegmentData);
+    toElement(): {
+        type: "keyboard";
+        data: KeyboardSegmentData;
+    };
+}
+/** @deprecated 使用 {@link KeyboardSegment} */

package/lib/built/interactive-segments/keyboard-segment.js

@@ -0,0 +1,12 @@
+import { KEYBOARD_SEGMENT_TYPE } from './types.js';
+export class KeyboardSegment {
+    data;
+    segmentType = KEYBOARD_SEGMENT_TYPE;
+    constructor(data) {
+        this.data = data;
+    }
+    toElement() {
+        return { type: this.segmentType, data: this.data };
+    }
+}
+/** @deprecated 使用 {@link KeyboardSegment} */

package/lib/built/interactive-segments/onebot-keyboard.d.ts

@@ -0,0 +1,7 @@
+import type { MessageSegment, SendContent } from '../../types.js';
+import { type KeyboardSegmentData } from './types.js';
+/** OneBot / QQ 系 keyboard 段（各 adapter 在 $sendMessage 中识别） */
+export declare function keyboardToOneBotSegment(data: KeyboardSegmentData): MessageSegment;
+/** 出站前将 core keyboard 段展开为 OneBot keyboard（保留前置 text 等段） */
+export declare function expandKeyboardSegmentsInContent(content: SendContent): SendContent;
+/** @deprecated 使用 {@link expandKeyboardSegmentsInContent} */

package/lib/built/interactive-segments/onebot-keyboard.js

@@ -0,0 +1,51 @@
+import { isKeyboardSegment } from './types.js';
+import { KeyboardSegment } from './keyboard-segment.js';
+/** OneBot / QQ 系 keyboard 段（各 adapter 在 $sendMessage 中识别） */
+export function keyboardToOneBotSegment(data) {
+    return {
+        type: 'keyboard',
+        data: {
+            rows: data.rows.map((row) => row.map((btn) => ({
+                label: btn.label,
+                data: btn.payload,
+                enter: false,
+                action_type: 'callback',
+                disable: !!btn.disabled,
+            }))),
+        },
+    };
+}
+/** @deprecated 使用 {@link keyboardToOneBotSegment} */
+function asKeyboardData(item) {
+    if (item instanceof KeyboardSegment)
+        return item.data;
+    if (isKeyboardSegment(item))
+        return item.data;
+    return null;
+}
+/** 出站前将 core keyboard 段展开为 OneBot keyboard（保留前置 text 等段） */
+export function expandKeyboardSegmentsInContent(content) {
+    const items = Array.isArray(content) ? content : [content];
+    const out = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            out.push(item);
+            continue;
+        }
+        if (typeof item.type !== 'string') {
+            continue;
+        }
+        const data = asKeyboardData(item);
+        if (data) {
+            out.push(keyboardToOneBotSegment(data));
+            continue;
+        }
+        out.push(item);
+    }
+    if (out.length === 0)
+        return { type: 'text', data: { text: '' } };
+    if (out.length === 1)
+        return out[0];
+    return out;
+}
+/** @deprecated 使用 {@link expandKeyboardSegmentsInContent} */

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

@@ -0,0 +1,15 @@
+import type { SendContent } from '../../types.js';
+import { type InteractivePolicy, type KeyboardSegmentData } from './types.js';
+/**
+ * keyboard 的有效 fallback 映射：显式 `fallback.map` 优先；否则按按钮顺序
+ * 自动编号（与 {@link renderKeyboardAsText} 的自动编号一致，含 disabled 按钮）。
+ */
+export declare function effectiveKeyboardFallbackMap(data: KeyboardSegmentData): Record<string, string>;
+/** 收集 content 中所有 keyboard 段的有效 fallback 映射（文本降级前调用）。 */
+export declare function collectKeyboardFallbackMaps(content: SendContent | undefined): Record<string, string>[];
+/** keyboard 段 → 编号文本（'text' 策略端点的中央降级渲染）。 */
+export declare function renderKeyboardAsText(data: KeyboardSegmentData): string;
+export declare function hasKeyboardSegment(content: SendContent | undefined): boolean;
+/** @deprecated 使用 {@link hasKeyboardSegment} */
+/** 按 Adapter interactivePolicy 将 keyboard 段转为 native 保留或文本降级 */
+export declare function resolveKeyboardSegments(content: SendContent, policy: InteractivePolicy): SendContent;

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

@@ -0,0 +1,110 @@
+import { segment } from '../../utils.js';
+import { KeyboardSegment } from './keyboard-segment.js';
+import { KEYBOARD_SEGMENT_TYPE, isKeyboardSegment, } from './types.js';
+function asKeyboardData(item) {
+    if (item instanceof KeyboardSegment)
+        return item.data;
+    if (isKeyboardSegment(item))
+        return item.data;
+    return null;
+}
+function toKeyboardElement(data) {
+    return { type: KEYBOARD_SEGMENT_TYPE, data };
+}
+function asArray(content) {
+    return Array.isArray(content) ? content : [content];
+}
+function packSegments(out) {
+    if (out.length === 0)
+        return { type: 'text', data: { text: '' } };
+    if (out.length === 1)
+        return out[0];
+    return out;
+}
+/**
+ * keyboard 的有效 fallback 映射：显式 `fallback.map` 优先；否则按按钮顺序
+ * 自动编号（与 {@link renderKeyboardAsText} 的自动编号一致，含 disabled 按钮）。
+ */
+export function effectiveKeyboardFallbackMap(data) {
+    const map = data.fallback?.map ?? {};
+    if (Object.keys(map).length > 0)
+        return { ...map };
+    const out = {};
+    data.rows.flat().forEach((btn, idx) => {
+        out[String(idx + 1)] = btn.payload;
+    });
+    return out;
+}
+/** 收集 content 中所有 keyboard 段的有效 fallback 映射（文本降级前调用）。 */
+export function collectKeyboardFallbackMaps(content) {
+    if (content == null)
+        return [];
+    const maps = [];
+    for (const item of asArray(content)) {
+        if (typeof item === 'string')
+            continue;
+        const data = asKeyboardData(item);
+        if (data)
+            maps.push(effectiveKeyboardFallbackMap(data));
+    }
+    return maps;
+}
+/** keyboard 段 → 编号文本（'text' 策略端点的中央降级渲染）。 */
+export function renderKeyboardAsText(data) {
+    const lines = [];
+    const flat = data.rows.flat();
+    if (data.fallback?.hint) {
+        lines.push(data.fallback.hint);
+    }
+    else {
+        lines.push('请选择（回复数字）：');
+    }
+    const map = data.fallback?.map ?? {};
+    const entries = Object.keys(map).length > 0
+        ? Object.entries(map).sort(([a], [b]) => Number(a) - Number(b))
+        : flat.map((btn, idx) => [String(idx + 1), btn.payload]);
+    for (const [key, payload] of entries) {
+        const btn = flat.find((b) => b.payload === payload);
+        const label = btn?.label ?? '·';
+        lines.push(`${key}. ${label}${btn?.disabled ? ' (不可用)' : ''}`);
+    }
+    return lines.join('\n');
+}
+export function hasKeyboardSegment(content) {
+    if (content == null)
+        return false;
+    return asArray(content).some((item) => {
+        if (typeof item === 'string')
+            return false;
+        return item instanceof KeyboardSegment || isKeyboardSegment(item);
+    });
+}
+/** @deprecated 使用 {@link hasKeyboardSegment} */
+/** 按 Adapter interactivePolicy 将 keyboard 段转为 native 保留或文本降级 */
+export function resolveKeyboardSegments(content, policy) {
+    if (!hasKeyboardSegment(content))
+        return content;
+    const items = asArray(content);
+    const out = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            out.push(item);
+            continue;
+        }
+        const data = item instanceof KeyboardSegment
+            ? item.data
+            : isKeyboardSegment(item)
+                ? item.data
+                : null;
+        if (!data) {
+            out.push(item);
+            continue;
+        }
+        if (policy === 'native') {
+            out.push(toKeyboardElement(data));
+            continue;
+        }
+        out.push(segment.text(renderKeyboardAsText(data)));
+    }
+    return packSegments(out);
+}

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

@@ -0,0 +1,50 @@
+import type { MessageElement } from '../../types.js';
+export declare const KEYBOARD_SEGMENT_TYPE: "keyboard";
+export declare const ACTION_SEGMENT_TYPE: "action";
+export type ButtonStyle = 'primary' | 'danger' | 'secondary';
+/** callback：平台回调 action 入站；command：QQ 指令预填后文本入站 */
+export type ButtonInteractionMode = 'callback' | 'command';
+export interface ButtonCommandOptions {
+    /** QQ action.enter — 仅单聊；预填后自动发送 */
+    enter?: boolean;
+    /** QQ action.reply — 预填时引用原消息 */
+    reply?: boolean;
+}
+export type ButtonData = {
+    id: string;
+    label: string;
+    payload: string;
+    disabled?: boolean;
+    style?: ButtonStyle;
+    /** 默认 callback */
+    mode?: ButtonInteractionMode;
+    command?: ButtonCommandOptions;
+};
+export type KeyboardFallback = {
+    hint: string;
+    map: Record<string, string>;
+};
+export type KeyboardSegmentData = {
+    rows: ButtonData[][];
+    fallback?: KeyboardFallback;
+};
+export type ActionSegmentData = {
+    id: string;
+    payload: string;
+    sourceMessageId?: string;
+};
+export type InteractivePolicy = 'native' | 'text';
+export declare const DEFAULT_INTERACTIVE_POLICY: InteractivePolicy;
+export type InteractiveHandler = (message: import('../../message.js').Message<any>) => Promise<boolean> | boolean;
+export interface RegisteredInteractiveHandler {
+    prefix: string;
+    handler: InteractiveHandler;
+}
+export declare function isKeyboardSegment(item: MessageElement): item is MessageElement & {
+    type: typeof KEYBOARD_SEGMENT_TYPE;
+    data: KeyboardSegmentData;
+};
+export declare function isActionSegment(item: MessageElement): item is MessageElement & {
+    type: typeof ACTION_SEGMENT_TYPE;
+    data: ActionSegmentData;
+};

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

@@ -0,0 +1,9 @@
+export const KEYBOARD_SEGMENT_TYPE = 'keyboard';
+export const ACTION_SEGMENT_TYPE = 'action';
+export const DEFAULT_INTERACTIVE_POLICY = 'text';
+export function isKeyboardSegment(item) {
+    return item != null && typeof item === 'object' && 'type' in item && item.type === KEYBOARD_SEGMENT_TYPE;
+}
+export function isActionSegment(item) {
+    return item != null && typeof item === 'object' && 'type' in item && item.type === ACTION_SEGMENT_TYPE;
+}

package/lib/built/introspection-format.d.ts

@@ -0,0 +1,10 @@
+/**
+ * IM 内省指令格式化（/cmd、/endpoints 等）
+ */
+export interface EndpointRow {
+    adapter: string;
+    name: string;
+    online: boolean;
+}
+export declare function formatEndpointsList(endpoints: EndpointRow[]): string;
+export declare function endpointHelpText(): string;

package/lib/built/introspection-format.js

@@ -0,0 +1,28 @@
+/**
+ * IM 内省指令格式化（/cmd、/endpoints 等）
+ */
+export function formatEndpointsList(endpoints) {
+    if (endpoints.length === 0)
+        return '🤖 暂无 Endpoint 实例';
+    const lines = ['🤖 Endpoint 列表 (' + endpoints.length + ')', ''];
+    for (const b of [...endpoints].sort((a, c) => a.adapter.localeCompare(c.adapter) || a.name.localeCompare(c.name))) {
+        const mark = b.online ? '● online' : '○ offline';
+        lines.push(`  ${mark}  ${b.adapter}/${b.name}`);
+    }
+    return lines.join('\n');
+}
+export function endpointHelpText() {
+    return [
+        'Endpoint 运行时管理：',
+        '',
+        '  /endpoint add [adapter]   — 添加 endpoint（adapter 交互或 schema 向导）',
+        '  /endpoint remove <adapter> <name>',
+        '  /endpoint edit <adapter> <name>',
+        '  /endpoint start <adapter> <name>',
+        '  /endpoint stop <adapter> <name>',
+        '  /endpoint cancel          — 取消进行中的添加/绑定',
+        '  /endpoint sync            — 将内存 endpoint 写回 zhin.config',
+        '  /endpoint help',
+        '  /endpoints                — 查看运行时在线状态',
+    ].join('\n');
+}

package/lib/built/login-assist.d.ts

@@ -6,10 +6,12 @@
  * 待办未消费前会一直保留，刷新页面后仍可继续消费。
  *
  * 事件：
- *   bot.login.pending — 有新待办时触发，payload: PendingLoginTask
+ *   endpoint.login.pending — 有新待办时触发，payload: PendingLoginTask
+ *   endpoint.login.expired — 超时自动取消时触发，payload: PendingLoginTask
  */
-import type { Plugin } from '../plugin.js';
-export type LoginAssistType = 'qrcode' | 'sms' | 'slider' | 'device' | 'other';
+export type LoginAssistType = 'qrcode' | 'sms' | 'slider' | 'device' | 'auth' | 'other';
+/** 默认 5 分钟；扫码/滑块长期挂起会泄漏 Promise 与 Map 条目 */
+export declare const DEFAULT_LOGIN_ASSIST_TIMEOUT_MS: number;
 export interface PendingLoginTaskPayload {
     /** 说明文案（如「请扫码登录」） */
     message?: string;
@@ -23,20 +25,48 @@ export interface PendingLoginTaskPayload {
 export interface PendingLoginTask {
     id: string;
     adapter: string;
-    botId: string;
+    endpointKey: string;
     type: LoginAssistType;
     payload: PendingLoginTaskPayload;
     createdAt: number;
+    /** 到期时间戳（ms）；无超时则为 undefined */
+    expiresAt?: number;
+}
+export interface WaitForInputOptions {
+    /** Endpoint-instance owner. Only this owner may cancel the task during rollback/retirement. */
+    owner: object;
+    /**
+     * 超时毫秒。默认 {@link DEFAULT_LOGIN_ASSIST_TIMEOUT_MS}。
+     * 传 `0` / `Infinity` / 负数表示不超时（仅测试或显式长驻场景）。
+     */
+    timeoutMs?: number;
+}
+export type LoginAssistEventName = 'endpoint.login.pending' | 'endpoint.login.resolved' | 'endpoint.login.expired';
+/** Minimal bus — Plugin Runtime / classic Plugin / test EventEmitter all qualify. */
+export interface LoginAssistBus {
+    emit(name: LoginAssistEventName, task: PendingLoginTask): void;
 }
 export declare class LoginAssist {
-    private readonly plugin;
+    #private;
+    private readonly bus;
     private readonly pending;
+    private readonly local;
     private idSeq;
-    constructor(plugin: Plugin);
+    /** 构造时默认超时；可被 waitForInput options 覆盖 */
+    private readonly defaultTimeoutMs;
+    constructor(bus?: LoginAssistBus | null, options?: {
+        defaultTimeoutMs?: number;
+    });
     /**
-     * 生产者：等待用户输入后 resolve。会发出 bot.login.pending 事件，未消费前可被 listPending 拉取（刷新后可继续消费）。
+     * Subscribe without requiring a Plugin EventEmitter.
+     * Returns unsubscribe.
      */
-    waitForInput(adapter: string, botId: string, type: LoginAssistType, payload?: PendingLoginTaskPayload): Promise<string | Record<string, unknown>>;
+    subscribe(name: LoginAssistEventName, listener: (task: PendingLoginTask) => void): () => void;
+    /**
+     * 生产者：等待用户输入后 resolve。会发出 endpoint.login.pending 事件，未消费前可被 listPending 拉取（刷新后可继续消费）。
+     * 超时后 reject 并 emit `endpoint.login.expired`。
+     */
+    waitForInput(adapter: string, endpointKey: string, type: LoginAssistType, payload: PendingLoginTaskPayload, options: WaitForInputOptions): Promise<string | Record<string, unknown>>;
     /**
      * 消费者：提交结果，对应 waitForInput 的 Promise 会 resolve。
      */
@@ -45,10 +75,15 @@ export declare class LoginAssist {
      * 消费者：取消某条待办，对应 Promise 会 reject。
      */
     cancel(id: string, reason?: string): boolean;
+    /**
+     * Cancel pending tasks created by one exact Endpoint instance.
+     */
+    cancelOwned(owner: object, reason?: string): number;
     /**
      * 列出未消费的待办（供 Web/CLI 展示，刷新后仍可拉取同一列表）。
      */
     listPending(): PendingLoginTask[];
+    hasPending(adapter?: string, endpointKey?: string): boolean;
     dispose(): void;
 }
 declare module '../plugin.js' {
@@ -58,4 +93,3 @@ declare module '../plugin.js' {
         }
     }
 }
-//# sourceMappingURL=login-assist.d.ts.map