@zhin.js/core 1.4.0 → 1.4.2

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

@@ -1,4 +1,6 @@
-import type { CapabilityId, PluginId } from '@zhin.js/plugin-runtime';
+import type { CapabilityId, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { MediaRef, Segment } from '../../built/segment-contract/types.js';
+export type { MediaRef, Segment };
 declare const componentCallBrand: "zhin.component-call/1";
 declare const rawContentBrand: "zhin.raw-content/1";
 export interface ComponentCall<TProps = unknown> {
@@ -18,7 +20,18 @@ export declare function isRawContent(value: SendContent): value is RawContent;
 export interface IncomingMessage {
     readonly adapter: CapabilityId;
     readonly target: string;
+    /**
+     * 纯文本视图：与 `segments` 同源（adapter 从同一份入站载荷派生二者）。
+     * 触发判定与 Console 预览读取此字段；命令匹配在有 segments 时优先使用结构化视图。
+     */
     readonly content: string;
+    /**
+     * 结构化段视图（canonical Segment SSOT，见 built/segment-contract）。
+     * 与 `content` 同源：segments 承载纯文本无法表达的媒体（image/audio/video/file
+     * 的 MediaRef）、mention、reply 等信息。旧 adapter 未迁移时可缺省，
+     * 读取方必须容忍 undefined。
+     */
+    readonly segments?: readonly Segment[];
     readonly id?: string;
     readonly sender?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
@@ -48,6 +61,18 @@ export interface OutboundEnvelope {
 export interface MessageGateway {
     receive(input: IncomingMessage): Promise<MessageDispatchResult>;
     send(request: SendRequest): Promise<unknown>;
+    /**
+     * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
+     * 平台 callback 的 action 段、'text' 端点的数字回跳与指令预填直出
+     * payload 都会路由到这里。
+     */
+    registerInteractiveHandler(prefix: string, handler: (message: Message) => Promise<boolean> | boolean): () => void;
+    /**
+     * Command miss（或非前缀文本）后的回退处理：Host AI 对话、单文件 bot 用。
+     * 返回 true 表示已处理（回复已发送）；后注册者覆盖前者。
+     * `requester` 是消息所属 Adapter Endpoint 的 owner（用于 CapabilityIngress 继承）。
+     */
+    setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
 }
 export interface MessageDispatchResult {
     readonly matched: boolean;
@@ -63,9 +88,18 @@ export declare class Message {
     readonly id?: string | undefined;
     readonly sender?: string | undefined;
     readonly metadata: Readonly<Record<string, unknown>>;
-    constructor(adapter: CapabilityId, target: string, content: string, generation: number, reply: (content: SendContent, requester?: PluginId) => Promise<unknown>, id?: string | undefined, sender?: string | undefined, metadata?: Readonly<Record<string, unknown>>);
+    /**
+     * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
+     * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
+     */
+    readonly segments?: readonly Segment[] | undefined;
+    constructor(adapter: CapabilityId, target: string, content: string, generation: number, reply: (content: SendContent, requester?: PluginId) => Promise<unknown>, id?: string | undefined, sender?: string | undefined, metadata?: Readonly<Record<string, unknown>>, 
+    /**
+     * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
+     * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
+     */
+    segments?: readonly Segment[] | undefined);
     readonly $reply: (content: SendContent) => Promise<unknown>;
     readonly $replyFrom: (requester: PluginId, content: SendContent) => Promise<unknown>;
 }
 export declare function createOutboundEnvelope(request: Omit<OutboundEnvelope, 'payload' | 'replace'>, initialPayload: unknown): OutboundEnvelope;
-export {};

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

@@ -30,7 +30,13 @@ export class Message {
     id;
     sender;
     metadata;
-    constructor(adapter, target, content, generation, reply, id, sender, metadata = Object.freeze({})) {
+    segments;
+    constructor(adapter, target, content, generation, reply, id, sender, metadata = Object.freeze({}), 
+    /**
+     * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
+     * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
+     */
+    segments) {
         this.adapter = adapter;
         this.target = target;
         this.content = content;
@@ -38,6 +44,7 @@ export class Message {
         this.id = id;
         this.sender = sender;
         this.metadata = metadata;
+        this.segments = segments;
         this.$reply = (content) => reply(content);
         this.$replyFrom = (requester, content) => reply(content, requester);
         Object.freeze(this);

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

@@ -2,6 +2,7 @@ import { Scope, type CapabilityId, type PluginId, type RuntimeSnapshot, type Sna
 import { type EndpointManagement, type EndpointManagementCapability } from '@zhin.js/adapter';
 import { Message, type ChannelParent, type IncomingMessage, type MessageDispatchResult, type MessageGateway, type SendRequest } from './contracts.js';
 import { OutboundRenderer } from './outbound-renderer.js';
+import { type RuntimeInteractiveHandler } from './interactive.js';
 export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<MessageGateway>;
 /** Console 实时消息事件（SSE 推送源；content 仅为截断预览，不含完整原始段）。 */
 export interface RuntimeMessageEvent {
@@ -39,6 +40,11 @@ export declare class ImRuntime implements MessageGateway {
      */
     setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
     install(resources: Scope): void;
+    /**
+     * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
+     * 在 Command dispatch 之前路由：action 段 / 数字回跳 / 指令预填 payload。
+     */
+    registerInteractiveHandler(prefix: string, handler: RuntimeInteractiveHandler): () => void;
     /**
      * 订阅消息事件（入站 dispatch 完成后 / 出站发送成功后回调）。
      * 返回注销函数。listener 抛错不会阻断消息链路。

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

@@ -1,16 +1,21 @@
 import { createToken, htmlRendererToken, } from '@zhin.js/plugin-runtime';
 import { adapterFeatureId, isAdapterIndex, resolveEndpointManagement, } from '@zhin.js/adapter';
 import { isMiddlewareIndex, middlewareFeatureId } from '@zhin.js/middleware';
+import { formatCompact, getLogger, truncatePreview } from '@zhin.js/logger';
 import { Message, createOutboundEnvelope, } from './contracts.js';
 import { defaultCommandPrefixResolver, MessageDispatcher } from './message-dispatcher.js';
 import { OutboundRenderer } from './outbound-renderer.js';
-import { normalizeOutboundPayload } from './outbound-segments.js';
+import { applyOutboundInteractivePolicy, normalizeOutboundPayload, resolveOutboundInteractivePolicy, resolveOutboundMediaPolicy, } from './outbound-segments.js';
+import { keyboardFallbackStore } from '../../built/interactive-segments/fallback-store.js';
+import { findRuntimeInteractiveHandler, resolveRuntimeInteractivePayload, runtimeInteractiveChannelKey, } from './interactive.js';
+const logger = getLogger('im');
 export const messageGatewayToken = createToken('zhin.im.message-gateway');
 export const messagePreviewLimit = 200;
 export class ImRuntime {
     #dispatcher;
     #renderer;
     #messageListeners = new Set();
+    #interactiveHandlers = [];
     #snapshots;
     #unmatchedHandler;
     constructor(options = {}) {
@@ -36,6 +41,19 @@ export class ImRuntime {
     install(resources) {
         resources.provide(messageGatewayToken, this);
     }
+    /**
+     * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
+     * 在 Command dispatch 之前路由：action 段 / 数字回跳 / 指令预填 payload。
+     */
+    registerInteractiveHandler(prefix, handler) {
+        const entry = Object.freeze({ prefix, handler });
+        this.#interactiveHandlers.push(entry);
+        return () => {
+            const index = this.#interactiveHandlers.indexOf(entry);
+            if (index >= 0)
+                this.#interactiveHandlers.splice(index, 1);
+        };
+    }
     /**
      * 订阅消息事件（入站 dispatch 完成后 / 出站发送成功后回调）。
      * 返回注销函数。listener 抛错不会阻断消息链路。
@@ -59,6 +77,16 @@ export class ImRuntime {
         let active = true;
         try {
             const requester = requireAdapters(lease.value).owner(input.adapter);
+            logger.debug(formatCompact({
+                op: 'im_inbound_receive',
+                adapter: String(input.adapter).split('\0').pop() ?? String(input.adapter),
+                target: input.target,
+                sender: input.sender,
+                id: input.id,
+                preview: truncatePreview(input.content),
+                segments: input.segments?.length,
+                generation: lease.value.generation,
+            }));
             const message = new Message(input.adapter, input.target, input.content, lease.value.generation, (content, replyRequester = requester) => {
                 if (!active)
                     throw new Error('Message reply scope has ended');
@@ -68,17 +96,31 @@ export class ImRuntime {
                     requester: replyRequester,
                     content,
                 }, lease.value);
-            }, input.id, input.sender, Object.freeze({ ...input.metadata }));
+            }, input.id, input.sender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined);
             let result = Object.freeze({ matched: false });
             await runMiddleware(lease.value, message, async () => {
-                result = await this.#dispatcher.dispatch(message, lease.value);
+                result = await this.#dispatchInteractive(message, requester)
+                    ?? await this.#dispatcher.dispatch(message, lease.value);
                 if (!result.matched && this.#unmatchedHandler) {
+                    logger.debug(formatCompact({
+                        op: 'im_inbound_unmatched_handler',
+                        target: input.target,
+                        id: input.id,
+                    }));
                     const handled = await this.#unmatchedHandler(message, lease.value, requester);
                     if (handled) {
                         result = Object.freeze({ matched: true, command: 'ai', owner: requester });
                     }
                 }
             }, 'inbound');
+            logger.debug(formatCompact({
+                op: 'im_inbound_done',
+                target: input.target,
+                id: input.id,
+                matched: result.matched,
+                command: result.command,
+                owner: result.owner,
+            }));
             this.#emitMessage({
                 direction: 'inbound',
                 adapter: input.adapter,
@@ -262,11 +304,16 @@ export class ImRuntime {
     }
     async #sendWithSnapshot(request, snapshot) {
         const rendered = await this.#renderer.render(request.content, request.requester, snapshot);
-        // 单段对象 / html 段在此归一为适配器可消费的 wire 段数组；
+        // 单段对象 / html 段在此归一为适配器可消费的 canonical 段数组（含媒体能力协商）；
         // sandbox 适配器（控制台 UI）直接消费 html 段，跳过规范化。
-        const payload = isDirectHtmlConsumer(snapshot, request.adapter)
+        let payload = isDirectHtmlConsumer(snapshot, request.adapter)
             ? rendered
-            : await normalizeOutboundPayload(rendered, resolveHtmlRenderer(snapshot));
+            : await normalizeOutboundPayload(rendered, resolveHtmlRenderer(snapshot), {
+                mediaPolicy: resolveOutboundMediaPolicy(request.adapter, snapshot),
+            });
+        // interactive 中央执行：'text' 端点 keyboard → 编号文本，fallback 映射写
+        // 中央存储（入站数字回跳解析用）；'native' 端点透传 keyboard。
+        payload = applyOutboundInteractivePolicy(payload, resolveOutboundInteractivePolicy(request.adapter, snapshot), (map) => keyboardFallbackStore.remember(runtimeInteractiveChannelKey(String(request.adapter), request.target), map));
         const envelope = createOutboundEnvelope({
             adapter: request.adapter,
             target: request.target,
@@ -297,6 +344,24 @@ export class ImRuntime {
             throw new Error('ImRuntime is not attached to a Root');
         return this.#snapshots.acquire();
     }
+    /**
+     * interactive 回跳分发（Command dispatch 之前）：action 段 / 中央 fallback
+     * 数字回跳 / 指令预填 payload → prefix 最长匹配 handler。
+     */
+    async #dispatchInteractive(message, requester) {
+        if (this.#interactiveHandlers.length === 0)
+            return undefined;
+        const payload = resolveRuntimeInteractivePayload(message);
+        if (!payload)
+            return undefined;
+        const handler = findRuntimeInteractiveHandler(this.#interactiveHandlers, payload);
+        if (!handler)
+            return undefined;
+        const handled = await handler(message);
+        return handled
+            ? Object.freeze({ matched: true, command: 'interactive', owner: requester })
+            : undefined;
+    }
 }
 function requireAdapters(snapshot) {
     const projection = snapshot.projections.get(adapterFeatureId);

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

@@ -1,5 +1,6 @@
 export * from './contracts.js';
 export * from './im-runtime.js';
+export * from './interactive.js';
 export * from './message-dispatcher.js';
 export * from './outbound-renderer.js';
 export * from './outbound-segments.js';

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

@@ -1,5 +1,6 @@
 export * from './contracts.js';
 export * from './im-runtime.js';
+export * from './interactive.js';
 export * from './message-dispatcher.js';
 export * from './outbound-renderer.js';
 export * from './outbound-segments.js';

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

@@ -0,0 +1,25 @@
+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;
+}
+/** 频道键：出站降级写入与入站回跳读取共用（`adapter~target`）。 */
+export declare function runtimeInteractiveChannelKey(adapter: string, target: string): 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,41 @@
+import { resolvePayloadFromText } from '../../built/interactive-segments/action.js';
+import { keyboardFallbackStore } from '../../built/interactive-segments/fallback-store.js';
+/** 频道键：出站降级写入与入站回跳读取共用（`adapter~target`）。 */
+export function runtimeInteractiveChannelKey(adapter, target) {
+    return `${adapter}~${target}`;
+}
+/** 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(runtimeInteractiveChannelKey(String(message.adapter), message.target)));
+}
+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/message-dispatcher.js

@@ -1,4 +1,6 @@
-import { commandFeatureId, isCommandIndex } from '@zhin.js/command';
+import { commandFeatureId, isCommandIndex, } from '@zhin.js/command';
+import { formatCompact, getLogger, truncatePreview } from '@zhin.js/logger';
+const logger = getLogger('command');
 function ownerOfMessage(message) {
     return String(message.adapter).split('\0')[0];
 }
@@ -29,22 +31,137 @@ export class MessageDispatcher {
     async dispatch(message, snapshot) {
         const prefix = this.resolvePrefix(message, snapshot);
         let input = message.content.trim();
+        logger.debug(formatCompact({
+            op: 'command_dispatch_start',
+            adapter: ownerOfMessage(message),
+            endpoint: typeof message.metadata?.endpoint === 'string'
+                ? message.metadata.endpoint
+                : undefined,
+            prefix: prefix || '(none)',
+            preview: truncatePreview(input),
+            segments: summarizeSegmentTypes(message.segments),
+        }));
         if (prefix) {
-            if (!input.startsWith(prefix))
+            if (!input.startsWith(prefix)) {
+                logger.debug(formatCompact({
+                    op: 'command_dispatch_miss',
+                    reason: 'prefix_miss',
+                    prefix,
+                    preview: truncatePreview(input),
+                }));
                 return Object.freeze({ matched: false });
+            }
             input = input.slice(prefix.length).trim();
         }
-        if (!input)
+        if (!input) {
+            logger.debug(formatCompact({
+                op: 'command_dispatch_miss',
+                reason: 'empty_after_prefix',
+                prefix: prefix || '(none)',
+            }));
             return Object.freeze({ matched: false });
+        }
         const commands = snapshot.projections.get(commandFeatureId);
-        if (!isCommandIndex(commands))
+        if (!isCommandIndex(commands)) {
+            logger.debug(formatCompact({
+                op: 'command_dispatch_miss',
+                reason: 'no_command_index',
+            }));
             return Object.freeze({ matched: false });
-        const result = await commands.dispatch(input, message);
+        }
+        const structuredInput = message.segments
+            ? stripCommandPrefix(message.segments, prefix)
+            : undefined;
+        if (message.segments && structuredInput === undefined) {
+            logger.debug(formatCompact({
+                op: 'command_dispatch_fallback_text',
+                reason: 'strip_prefix_failed',
+                prefix: prefix || '(none)',
+                segments: summarizeSegmentTypes(message.segments),
+            }));
+        }
+        const matchInput = structuredInput ?? input;
+        logger.debug(formatCompact({
+            op: 'command_dispatch_match_input',
+            mode: typeof matchInput === 'string' ? 'text' : 'segments',
+            preview: typeof matchInput === 'string'
+                ? truncatePreview(matchInput)
+                : summarizeSegmentTypes(matchInput),
+        }));
+        const result = await commands.dispatch(matchInput, message);
         if (result.matched && result.value !== undefined) {
             if (!result.owner)
                 throw new Error('Matched Command is missing its owner');
+            logger.debug(formatCompact({
+                op: 'command_dispatch_hit',
+                command: result.command,
+                owner: result.owner,
+            }));
             await message.$replyFrom(result.owner, result.value);
         }
+        else {
+            logger.debug(formatCompact({
+                op: 'command_dispatch_miss',
+                reason: result.matched ? 'empty_value' : 'no_match',
+                command: result.command,
+            }));
+        }
         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;
+}
+function summarizeSegmentTypes(segments) {
+    if (!segments?.length)
+        return undefined;
+    return segments
+        .map((segment) => {
+        if (typeof segment.type === 'string')
+            return segment.type;
+        if (segment.type && typeof segment.type === 'object' && 'name' in segment.type) {
+            return String(segment.type.name);
+        }
+        return '?';
+    })
+        .join(',');
+}

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

@@ -1,22 +1,69 @@
-import type { HtmlRendererHost } from '@zhin.js/plugin-runtime';
+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]'.
- * `html` segments additionally need a Host renderer: image when
- * `@zhin.js/html-renderer` is installed, plain-text fallback otherwise.
+ *
+ * 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 直发（qq / icqq / slack / weixin-ilink）；
+ * - `url-or-text`：平台仅接受 URL 媒体；本层无上传通道，base64/path → 文本降级；
+ * - `passthrough`：adapter 自行物化媒体（napcat / onebot11 / onebot12），本层不动。
+ */
+export type OutboundMediaPolicy = 'base64' | 'url-or-text' | 'passthrough';
+/**
+ * 任务 C `defineAdapter` segments policy 挂载形状（duck-typed 读取）。
+ * 契约形状为 `outboundMedia: readonly ('url'|'path'|'base64'|'upload')[]`
+ * （端点可消费的媒体来源形式，见 `@zhin.js/adapter` 的 AdapterSegmentPolicy）；
+ * 兼容过渡期的单值策略字符串。Adapter 在 definition 上声明
+ * `segments: { outboundMedia }` 即覆盖内置表。
+ */
+export interface OutboundSegmentsPolicy {
+    readonly outboundMedia?: OutboundMediaPolicy | readonly ('url' | 'path' | 'base64' | 'upload')[];
+    readonly interactive?: InteractivePolicy;
+}
+export interface NormalizeOutboundOptions {
+    /** 缺省 `base64`（保持历史行为：html→image base64 直发）。 */
+    readonly mediaPolicy?: OutboundMediaPolicy;
+}
 export declare function isOutboundSegment(value: unknown): value is OutboundSegment;
 /**
- * Normalize a rendered outbound payload to wire segments:
- * - segment arrays stay arrays (html segments converted per element);
+ * 解析端点的出站媒体策略：优先读 adapter definition 上声明的
+ * `segments.outboundMedia`（任务 C 挂载点；多 endpoint 展开的 `slot~entry`
+ * id 回退到 slot id 查声明），否则按平台名查内置表，
+ * 未知平台回退 `base64`（历史行为）。
+ */
+export declare function resolveOutboundMediaPolicy(adapter: CapabilityId, snapshot: RuntimeSnapshot): OutboundMediaPolicy;
+/**
+ * 解析端点的出站 interactive 策略：优先读 adapter definition 上声明的
+ * `segments.interactive`，否则按平台名查内置表，未知平台回退 'text'。
+ */
+export declare function resolveOutboundInteractivePolicy(adapter: CapabilityId, snapshot: RuntimeSnapshot): InteractivePolicy;
+/**
+ * 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): Promise<unknown>;
+export declare function normalizeOutboundPayload(payload: unknown, renderer?: HtmlRendererHost, options?: NormalizeOutboundOptions): Promise<unknown>;