@zhin.js/core 1.1.34 → 1.1.35

package/lib/plugin-runtime/im/index.d.ts

@@ -0,0 +1,9 @@
+export * from './contracts.js';
+export * from './im-runtime.js';
+export * from './interactive.js';
+export * from './login-assist-host.js';
+export * from './message-bus.js';
+export * from './message-dispatcher.js';
+export * from './outbound-renderer.js';
+export * from './outbound-segments.js';
+export * from './service-tokens.js';

package/lib/plugin-runtime/im/index.js

@@ -0,0 +1,9 @@
+export * from './contracts.js';
+export * from './im-runtime.js';
+export * from './interactive.js';
+export * from './login-assist-host.js';
+export * from './message-bus.js';
+export * from './message-dispatcher.js';
+export * from './outbound-renderer.js';
+export * from './outbound-segments.js';
+export * from './service-tokens.js';

package/lib/plugin-runtime/im/interactive.d.ts

@@ -0,0 +1,26 @@
+import type { ConversationRef } from '@zhin.js/im-contract';
+import type { Message } from './contracts.js';
+/**
+ * Plugin Runtime IM 管线的 interactive action 回跳（旧轨
+ * `built/interactive-segments/handlers.ts` 的等价物）：
+ * - 平台 callback 以 canonical action 段入站（telegram / discord，Wave 1 C 约定
+ *   `{type:'action', data:{id, payload, sourceMessageId?}}`）；
+ * - 'text' 端点的数字回跳：出站降级写入中央 fallback 存储的映射在此解析回 payload；
+ * - QQ 指令预填等直出 `prefix:session:id` 文本同样识别。
+ * payload 按 prefix 最长匹配路由给 `ImRuntime.registerInteractiveHandler`
+ * 注册的 handler。
+ */
+export type RuntimeInteractiveHandler = (message: Message) => Promise<boolean> | boolean;
+export interface RegisteredRuntimeInteractiveHandler {
+    readonly prefix: string;
+    readonly handler: RuntimeInteractiveHandler;
+}
+/** 频道键：出站降级写入与入站回跳读取共用（由 ConversationRef 派生，稳定即可）。 */
+export declare function runtimeInteractiveConversationKey(conversation: ConversationRef): string;
+/** prefix 最长匹配（与旧轨 findHandler 一致）。 */
+export declare function findRuntimeInteractiveHandler(handlers: readonly RegisteredRuntimeInteractiveHandler[], payload: string): RuntimeInteractiveHandler | undefined;
+/**
+ * 从入站消息解析 interactive payload：
+ * action 段 → 中央 fallback map（裸数字）→ 指令预填直出 payload。
+ */
+export declare function resolveRuntimeInteractivePayload(message: Message): string | undefined;

package/lib/plugin-runtime/im/interactive.js

@@ -0,0 +1,46 @@
+import { resolvePayloadFromText } from '../../built/interactive-segments/action.js';
+import { keyboardFallbackStore } from '../../built/interactive-segments/fallback-store.js';
+/** 频道键：出站降级写入与入站回跳读取共用（由 ConversationRef 派生，稳定即可）。 */
+export function runtimeInteractiveConversationKey(conversation) {
+    const base = `${String(conversation.endpoint.id)}~${conversation.kind}:${conversation.id}`;
+    const parent = conversation.parent
+        ? `@${conversation.parent.kind}:${conversation.parent.id}`
+        : '';
+    const thread = conversation.threadId ? `#${conversation.threadId}` : '';
+    return `${base}${parent}${thread}`;
+}
+/** prefix 最长匹配（与旧轨 findHandler 一致）。 */
+export function findRuntimeInteractiveHandler(handlers, 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;
+}
+/**
+ * 从入站消息解析 interactive payload：
+ * action 段 → 中央 fallback map（裸数字）→ 指令预填直出 payload。
+ */
+export function resolveRuntimeInteractivePayload(message) {
+    const fromSegments = actionPayloadFromSegments(message.segments);
+    if (fromSegments)
+        return fromSegments;
+    const raw = message.content.trim();
+    if (!raw)
+        return undefined;
+    return resolvePayloadFromText(raw, keyboardFallbackStore.mapFor(runtimeInteractiveConversationKey(message.conversation)));
+}
+function actionPayloadFromSegments(segments) {
+    for (const seg of segments ?? []) {
+        if (seg.type !== 'action')
+            continue;
+        const payload = seg.data?.payload;
+        if (typeof payload === 'string' && payload)
+            return payload;
+    }
+    return undefined;
+}

package/lib/plugin-runtime/im/login-assist-host.d.ts

@@ -0,0 +1,6 @@
+import { LoginAssist } from '../../built/login-assist.js';
+/**
+ * Plugin Runtime login-assist port（与出站消息服务并列）。
+ * 适配器 waitForInput；Console / stdin 经 listPending + submit 消费。
+ */
+export declare const loginAssistToken: import("@zhin.js/plugin-runtime").Token<LoginAssist>;

package/lib/plugin-runtime/im/login-assist-host.js

@@ -0,0 +1,6 @@
+import { createToken } from '@zhin.js/plugin-runtime';
+/**
+ * Plugin Runtime login-assist port（与出站消息服务并列）。
+ * 适配器 waitForInput；Console / stdin 经 listPending + submit 消费。
+ */
+export const loginAssistToken = createToken('zhin.im.login-assist');

package/lib/plugin-runtime/im/message-bus.d.ts

@@ -0,0 +1,38 @@
+/**
+ * MessageBus — 独立于 Plugin 的 IM 生命周期事件总线。
+ *
+ * 覆盖 Plugin.Lifecycle 中关键 IM 事件，供 Scope+Token 路径消费。
+ * 遗留 Plugin.emit 通过短暂双写桥接（迁移窗口）。
+ */
+import type { DeliveryReceipt } from '@zhin.js/im-contract';
+import type { Message, OutboundEnvelope, SendContent } from './contracts.js';
+export interface EndpointEvent {
+    readonly adapter: string;
+    readonly endpointKey: string;
+    readonly error?: Error;
+}
+export interface MessageBusEventMap {
+    'message.receive': [message: Message];
+    'before.sendMessage': [envelope: OutboundEnvelope];
+    'message.send': [payload: {
+        adapter: string;
+        endpointKey: string;
+        content: SendContent;
+        receipt: DeliveryReceipt;
+    }];
+    'endpoint.connect': [event: EndpointEvent];
+    'endpoint.disconnect': [event: EndpointEvent];
+    'endpoint.error': [event: EndpointEvent];
+}
+export type MessageBusEventName = keyof MessageBusEventMap;
+export declare class MessageBus {
+    private readonly emitter;
+    constructor();
+    on<E extends MessageBusEventName>(event: E, listener: (...args: MessageBusEventMap[E]) => void): () => void;
+    once<E extends MessageBusEventName>(event: E, listener: (...args: MessageBusEventMap[E]) => void): () => void;
+    emit<E extends MessageBusEventName>(event: E, ...args: MessageBusEventMap[E]): void;
+    off<E extends MessageBusEventName>(event: E, listener: (...args: MessageBusEventMap[E]) => void): void;
+    listenerCount(event: MessageBusEventName): number;
+    removeAllListeners(event?: MessageBusEventName): void;
+}
+export declare const messageBusToken: import("@zhin.js/plugin-runtime").Token<MessageBus>;

package/lib/plugin-runtime/im/message-bus.js

@@ -0,0 +1,40 @@
+/**
+ * MessageBus — 独立于 Plugin 的 IM 生命周期事件总线。
+ *
+ * 覆盖 Plugin.Lifecycle 中关键 IM 事件，供 Scope+Token 路径消费。
+ * 遗留 Plugin.emit 通过短暂双写桥接（迁移窗口）。
+ */
+import { EventEmitter } from 'node:events';
+import { createToken } from '@zhin.js/plugin-runtime';
+export class MessageBus {
+    emitter = new EventEmitter();
+    constructor() {
+        this.emitter.setMaxListeners(50);
+    }
+    on(event, listener) {
+        this.emitter.on(event, listener);
+        return () => this.emitter.off(event, listener);
+    }
+    once(event, listener) {
+        this.emitter.once(event, listener);
+        return () => this.emitter.off(event, listener);
+    }
+    emit(event, ...args) {
+        this.emitter.emit(event, ...args);
+    }
+    off(event, listener) {
+        this.emitter.off(event, listener);
+    }
+    listenerCount(event) {
+        return this.emitter.listenerCount(event);
+    }
+    removeAllListeners(event) {
+        if (event) {
+            this.emitter.removeAllListeners(event);
+        }
+        else {
+            this.emitter.removeAllListeners();
+        }
+    }
+}
+export const messageBusToken = createToken('zhin.im.message-bus');

package/lib/plugin-runtime/im/message-dispatcher.d.ts

@@ -0,0 +1,18 @@
+import type { UserInteractionFactory } from '@zhin.js/interaction';
+import type { RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { Message, MessageDispatchResult } from './contracts.js';
+/**
+ * 命令前缀解析器：返回该消息要求的命令前缀。
+ * `''` 表示无前缀（任意文本都尝试按命令匹配）。
+ */
+export type CommandPrefixResolver = (message: Message, snapshot: RuntimeSnapshot) => string;
+/**
+ * 默认解析：读消息所属适配器实例 config 的 `commandPrefix`（默认 `''`）；
+ * 实例声明 `endpoints` 数组时，按消息 endpoint 名找 entry，`entry.commandPrefix` 覆盖顶层。
+ */
+export declare const defaultCommandPrefixResolver: CommandPrefixResolver;
+export declare class MessageDispatcher {
+    private readonly resolvePrefix;
+    constructor(resolvePrefix?: CommandPrefixResolver);
+    dispatch(message: Message, snapshot: RuntimeSnapshot, interactionFactory?: UserInteractionFactory): Promise<MessageDispatchResult>;
+}

package/lib/plugin-runtime/im/message-dispatcher.js

@@ -0,0 +1,107 @@
+import { commandFeatureId, isCommandIndex, } from '@zhin.js/command';
+import { formatCompact, getLogger, truncatePreview } from '@zhin.js/logger';
+const logger = getLogger('command');
+function ownerOfMessage(message) {
+    return message.conversation.endpoint.adapter;
+}
+/**
+ * 默认解析：读消息所属适配器实例 config 的 `commandPrefix`（默认 `''`）；
+ * 实例声明 `endpoints` 数组时，按消息 endpoint 名找 entry，`entry.commandPrefix` 覆盖顶层。
+ */
+export const defaultCommandPrefixResolver = (message, snapshot) => {
+    const config = snapshot.config.get(ownerOfMessage(message));
+    if (!config)
+        return '';
+    const endpointId = message.endpointId;
+    if (endpointId && Array.isArray(config.endpoints)) {
+        const entry = config.endpoints.find((item) => !!item && typeof item === 'object'
+            && item.id === endpointId);
+        if (typeof entry?.commandPrefix === 'string')
+            return entry.commandPrefix;
+    }
+    return typeof config.commandPrefix === 'string' ? config.commandPrefix : '';
+};
+export class MessageDispatcher {
+    resolvePrefix;
+    constructor(resolvePrefix = defaultCommandPrefixResolver) {
+        this.resolvePrefix = resolvePrefix;
+    }
+    async dispatch(message, snapshot, interactionFactory) {
+        const prefix = this.resolvePrefix(message, snapshot);
+        let input = message.content.trim();
+        if (prefix && !input.startsWith(prefix)) {
+            return Object.freeze({ matched: false });
+        }
+        if (prefix)
+            input = input.slice(prefix.length).trim();
+        if (!input)
+            return Object.freeze({ matched: false });
+        const commands = snapshot.projections.get(commandFeatureId);
+        if (!isCommandIndex(commands))
+            return Object.freeze({ matched: false });
+        const structuredInput = message.segments
+            ? stripCommandPrefix(message.segments, prefix)
+            : undefined;
+        const matchInput = structuredInput ?? input;
+        const result = await commands.dispatch(matchInput, message, interactionFactory, prefix);
+        if (result.matched && result.value !== undefined) {
+            if (!result.owner)
+                throw new Error('Matched Command is missing its owner');
+            logger.debug(formatCompact({
+                op: 'dispatch_hit',
+                command: result.command,
+                owner: result.owner,
+            }));
+            await message.$replyFrom(result.owner, result.value);
+        }
+        else if (!result.matched) {
+            logger.debug(formatCompact({
+                op: 'dispatch_miss',
+                preview: truncatePreview(input),
+            }));
+        }
+        return result;
+    }
+}
+/**
+ * Keep the text and structured views aligned. Falling back to `content` is
+ * intentional when an adapter supplies inconsistent segment data.
+ */
+function stripCommandPrefix(segments, prefix) {
+    let pendingPrefix = prefix;
+    let atStart = true;
+    const result = [];
+    for (const segment of segments) {
+        if (!atStart) {
+            result.push(segment);
+            continue;
+        }
+        if (segment.type !== 'text' || typeof segment.data.text !== 'string') {
+            if (pendingPrefix)
+                return undefined;
+            atStart = false;
+            result.push(segment);
+            continue;
+        }
+        let text = segment.data.text;
+        if (pendingPrefix) {
+            if (text.startsWith(pendingPrefix)) {
+                text = text.slice(pendingPrefix.length);
+                pendingPrefix = '';
+            }
+            else if (pendingPrefix.startsWith(text)) {
+                pendingPrefix = pendingPrefix.slice(text.length);
+                continue;
+            }
+            else {
+                return undefined;
+            }
+        }
+        text = text.trimStart();
+        if (!text)
+            continue;
+        atStart = false;
+        result.push({ ...segment, data: { ...segment.data, text } });
+    }
+    return pendingPrefix ? undefined : result;
+}

package/lib/plugin-runtime/im/outbound-renderer.d.ts

@@ -0,0 +1,7 @@
+import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { ConversationRef } from '@zhin.js/im-contract';
+import { type IncomingContext, type SendContent } from './contracts.js';
+export declare class OutboundRenderer {
+    #private;
+    render(content: SendContent, requester: PluginId, snapshot: RuntimeSnapshot, conversation?: ConversationRef, incoming?: IncomingContext): Promise<unknown>;
+}

package/lib/plugin-runtime/im/outbound-renderer.js

@@ -0,0 +1,70 @@
+import { componentHostToken } from '@zhin.js/plugin-runtime';
+import { componentFeatureId, isComponentIndex, } from '@zhin.js/component';
+import { isComponentCall, isRawContent, isSegmentContent, } from './contracts.js';
+const maxComponentDepth = 32;
+const TEMPLATE_MARKER = '${';
+export class OutboundRenderer {
+    async render(content, requester, snapshot, conversation, incoming) {
+        const host = resolveComponentHost(snapshot);
+        const ctx = conversation ? buildTemplateContext(conversation, incoming) : undefined;
+        return this.#render(content, requester, snapshot, host, ctx, 0);
+    }
+    async #render(content, requester, snapshot, host, ctx, depth) {
+        if (depth > maxComponentDepth)
+            throw new Error('Component render depth exceeded 32');
+        if (typeof content === 'string')
+            return compileText(content, host, ctx);
+        if (Array.isArray(content)) {
+            return Promise.all(content.map((item) => this.#render(item, requester, snapshot, host, ctx, depth)));
+        }
+        if (isRawContent(content))
+            return content.payload;
+        if (isSegmentContent(content)) {
+            if (content.type === 'text') {
+                const text = content.data?.text;
+                if (typeof text === 'string' && text.includes(TEMPLATE_MARKER) && host && ctx) {
+                    return { ...content, data: { ...content.data, text: host.compileTemplate(text, ctx) } };
+                }
+            }
+            return content;
+        }
+        if (isComponentCall(content)) {
+            const rendered = await requireComponents(snapshot).render(requester, content.name, content.props);
+            return this.#render(rendered, requester, snapshot, host, ctx, depth + 1);
+        }
+        throw new TypeError('Unsupported SendContent');
+    }
+}
+function compileText(text, host, ctx) {
+    if (!host || !ctx || !text.includes(TEMPLATE_MARKER))
+        return text;
+    return host.compileTemplate(text, ctx);
+}
+function buildTemplateContext(conversation, incoming) {
+    return {
+        adapter: conversation.endpoint.adapter,
+        endpoint: conversation.endpoint.id,
+        kind: conversation.kind,
+        conversationId: conversation.id,
+        sender: incoming?.sender,
+        content: incoming?.content,
+        segments: incoming?.segments,
+        messageId: incoming?.messageId,
+        timestamp: incoming?.timestamp,
+        endpointId: incoming?.endpointId,
+        mentioned: incoming?.mentioned,
+    };
+}
+function resolveComponentHost(snapshot) {
+    const host = snapshot.resources.get(snapshot.root)?.get(componentHostToken.id);
+    return host && typeof host.compileTemplate === 'function'
+        ? host
+        : undefined;
+}
+function requireComponents(snapshot) {
+    const projection = snapshot.projections.get(componentFeatureId);
+    if (!isComponentIndex(projection)) {
+        throw new Error('Component Feature projection is not installed');
+    }
+    return projection;
+}

package/lib/plugin-runtime/im/outbound-segments.d.ts

@@ -0,0 +1,72 @@
+import type { CapabilityId, HtmlRendererHost, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type InteractivePolicy } from '../../built/interactive-segments/types.js';
+/**
+ * Outbound payload normalization for the Plugin Runtime IM pipeline.
+ *
+ * `raw()` payloads reach adapters as-is; adapters only understand wire
+ * segments (`{ type, data }` arrays). A single segment object (non-array)
+ * would otherwise fall through to `String(payload)` → '[object Object]'.
+ *
+ * Segment payloads are normalized to the canonical Segment SSOT
+ * (`built/segment-contract`，复用 `toCanonicalSegments`：at→mention、
+ * 旧 wire 字段 `{url,file,base64}`→MediaRef)。`html` segments additionally
+ * need a Host renderer: image when `@zhin.js/html-renderer` is installed,
+ * plain-text fallback otherwise. 渲染产出的 base64 图片按端点声明的媒体
+ * 能力（`resolveOutboundMediaPolicy`）协商降级。
+ */
+export interface OutboundSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+/**
+ * 出站媒体能力策略（html→image 渲染产物与 base64/path 媒体段的投递方式）：
+ * - `base64`：平台接受 base64 直发；
+ * - `url-or-text`：平台仅接受 URL 媒体；本层无上传通道，base64/path → 文本降级；
+ * - `passthrough`：adapter 自行物化媒体，本层不动。
+ */
+export type OutboundMediaPolicy = 'base64' | 'url-or-text' | 'passthrough';
+/**
+ * adapter definition 的 segments policy 声明（必选能力面）。
+ * `outboundMedia` 为端点可消费的媒体来源形式数组
+ * （'url' | 'path' | 'base64' | 'upload'），映射到投递策略：
+ * base64 可直发；无 base64 但端点可自行物化（upload/path）→ passthrough；
+ * 仅 url → 非 URL 媒体文本降级。未声明的 adapter 按 ['url'] 兜底。
+ */
+export interface OutboundSegmentsPolicy {
+    readonly outboundMedia: readonly ('url' | 'path' | 'base64' | 'upload')[];
+    readonly interactive?: InteractivePolicy;
+    readonly markdown?: 'native' | 'text';
+}
+export interface NormalizeOutboundOptions {
+    /** 缺省 `url-or-text`（未声明 adapter 的保守兜底：仅 URL 媒体可达）。 */
+    readonly mediaPolicy?: OutboundMediaPolicy;
+}
+/**
+ * 解析端点的出站媒体策略：读 adapter definition 声明的 `segments.outboundMedia`
+ * （多 endpoint 展开的 `slot~entry` id 回退到 slot id 查声明）；
+ * 未声明回退 `url-or-text`（仅 URL 媒体可达，其余文本降级）。
+ */
+export declare function resolveOutboundMediaPolicy(adapter: CapabilityId, snapshot: RuntimeSnapshot): OutboundMediaPolicy;
+export declare function isOutboundSegment(value: unknown): value is OutboundSegment;
+/**
+ * 解析端点的出站 interactive 策略：优先读 adapter definition 上声明的
+ * `segments.interactive`，否则按平台名查内置表，未知平台回退 'text'。
+ */
+export declare function resolveOutboundInteractivePolicy(adapter: CapabilityId, snapshot: RuntimeSnapshot): InteractivePolicy;
+/** Preserve semantic Markdown only when the endpoint explicitly declares native consumption. */
+export declare function resolveOutboundMarkdownPolicy(adapter: CapabilityId, snapshot: RuntimeSnapshot): 'native' | 'text';
+export declare function applyOutboundMarkdownPolicy(payload: unknown, policy: 'native' | 'text'): unknown;
+/**
+ * keyboard 段中央降级：'text' 端点把 keyboard 渲染为编号文本（复用旧轨
+ * `renderKeyboardAsText`），并把有效 fallback 映射经 `remember` 回调写入
+ * 中央存储（供入站数字回跳解析）；'native' 端点透传 keyboard。
+ */
+export declare function applyOutboundInteractivePolicy(payload: unknown, policy: InteractivePolicy, remember?: (map: Record<string, string>) => void): unknown;
+/**
+ * Normalize a rendered outbound payload toward canonical wire segments:
+ * - segment arrays stay arrays (html segments converted per element,
+ *   其余段经 `toCanonicalSegments` 归一为 canonical Segment)；
+ * - a single segment object is wrapped into a one-element array;
+ * - anything else (plain strings, legacy `{ text }` shorthands) passes through.
+ */
+export declare function normalizeOutboundPayload(payload: unknown, renderer?: HtmlRendererHost, options?: NormalizeOutboundOptions): Promise<unknown>;