@zhin.js/core 1.3.5 → 1.4.1

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

@@ -1,18 +1,27 @@
 import { createToken, htmlRendererToken, } from '@zhin.js/plugin-runtime';
-import { adapterFeatureId, isAdapterIndex } from '@zhin.js/adapter';
+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 { MessageDispatcher } from './message-dispatcher.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 = {}) {
-        this.#dispatcher = new MessageDispatcher(options.commandPrefix);
+        this.#dispatcher = new MessageDispatcher(options.commandPrefix === undefined
+            ? defaultCommandPrefixResolver
+            : () => options.commandPrefix ?? '');
         this.#renderer = options.renderer ?? new OutboundRenderer();
     }
     attach(snapshots) {
@@ -32,11 +41,52 @@ 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 抛错不会阻断消息链路。
+     */
+    onMessage(listener) {
+        this.#messageListeners.add(listener);
+        return () => { this.#messageListeners.delete(listener); };
+    }
+    #emitMessage(event) {
+        for (const listener of this.#messageListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // listener 异常不得影响消息收发
+            }
+        }
+    }
     async receive(input) {
         const lease = this.#acquire();
         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');
@@ -46,17 +96,43 @@ 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,
+                target: input.target,
+                ...(input.sender !== undefined ? { sender: input.sender } : {}),
+                ...(channelTypeOf(input.target)
+                    ? { channelType: channelTypeOf(input.target) }
+                    : {}),
+                contentPreview: previewText(input.content),
+                ...(input.id !== undefined ? { messageId: input.id } : {}),
+                timestamp: Date.now(),
+            });
             return result;
         }
         finally {
@@ -82,9 +158,11 @@ export class ImRuntime {
                     name: row.name,
                     // adapter 列显示平台类型（owner 包名去 scope/adapter- 前缀），不是 slot localName
                     adapter: adapterTypeName(lease.value.tree.get(row.owner)?.packageName) ?? row.name,
+                    owner: row.owner,
                     connected: row.connected,
                     status: row.status,
                     phase: row.phase,
+                    managementCapabilities: row.managementCapabilities,
                 }));
             }
             finally {
@@ -106,12 +184,15 @@ export class ImRuntime {
                 const row = index.describe().find((item) => item.id === id);
                 if (!row)
                     return null;
+                // adapter 与 listEndpoints 对齐：平台类型（owner 包名去 scope/adapter- 前缀），
+                // 不是 live name（如 ICQQ uin）。此前误写 row.name 导致 endpoint.info 与 list 不一致。
                 return Object.freeze({
                     name: row.name,
-                    adapter: row.name,
+                    adapter: adapterTypeName(lease.value.tree.get(row.owner)?.packageName) ?? row.name,
                     connected: row.connected,
                     status: row.status,
                     phase: row.phase,
+                    managementCapabilities: row.managementCapabilities,
                 });
             }
             finally {
@@ -203,17 +284,36 @@ export class ImRuntime {
             return null;
         }
     }
-    /** Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。 */
+    /**
+     * Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。
+     * @deprecated Host callers should use `getEndpointManagement()`.
+     */
     getLiveEndpoint(adapter, endpointId) {
         return this.#liveEndpoint(adapter, endpointId);
     }
+    /**
+     * Narrow Host seam for Console social/group management. An empty object means
+     * the Endpoint exists but implements no management operations; null means it
+     * cannot be resolved.
+     */
+    getEndpointManagement(adapter, endpointId) {
+        const endpoint = this.#liveEndpoint(adapter, endpointId);
+        if (!endpoint)
+            return null;
+        return resolveEndpointManagement(endpoint) ?? Object.freeze({});
+    }
     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,
@@ -229,6 +329,14 @@ export class ImRuntime {
                 ...(request.parent ? { parent: request.parent } : {}),
             });
         }, 'outbound');
+        this.#emitMessage({
+            direction: 'outbound',
+            adapter: request.adapter,
+            target: request.target,
+            requester: request.requester,
+            contentPreview: previewText(envelope.payload),
+            timestamp: Date.now(),
+        });
         return result;
     }
     #acquire() {
@@ -236,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);
@@ -297,3 +423,42 @@ function normalizeConsoleContent(content) {
         return content;
     return String(content);
 }
+/** target 前缀场景：`group:123` → `group`；无前缀返回 undefined。 */
+function channelTypeOf(target) {
+    const match = /^([a-z0-9-]+):/iu.exec(target);
+    return match?.[1];
+}
+/** 消息内容 → 预览文本（截断 200 字）；wire 段取 `data.text`，其余段记 `[type]`。 */
+function previewText(content) {
+    const text = flattenContent(content);
+    return text.length > messagePreviewLimit
+        ? `${text.slice(0, messagePreviewLimit)}…`
+        : text;
+}
+function flattenContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content == null)
+        return '';
+    if (Array.isArray(content)) {
+        return content.map((item) => flattenContent(item)).join('');
+    }
+    if (typeof content === 'object') {
+        const record = content;
+        const data = record.data;
+        if (typeof record.type === 'string') {
+            if (data && typeof data.text === 'string')
+                return data.text;
+            return `[${record.type}]`;
+        }
+        if (typeof record.text === 'string')
+            return record.text;
+        try {
+            return JSON.stringify(content) ?? '';
+        }
+        catch {
+            return String(content);
+        }
+    }
+    return String(content);
+}

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.d.ts

@@ -1,7 +1,17 @@
 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 prefix;
-    constructor(prefix?: string);
+    private readonly resolvePrefix;
+    constructor(resolvePrefix?: CommandPrefixResolver);
     dispatch(message: Message, snapshot: RuntimeSnapshot): Promise<MessageDispatchResult>;
 }

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

@@ -1,26 +1,167 @@
-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];
+}
+/**
+ * 默认解析：读消息所属适配器实例 config 的 `commandPrefix`（默认 `''`）；
+ * 实例声明 `endpoints` 数组时，按消息 endpoint 名找 entry，`entry.commandPrefix` 覆盖顶层。
+ */
+export const defaultCommandPrefixResolver = (message, snapshot) => {
+    const config = snapshot.config.get(ownerOfMessage(message));
+    if (!config)
+        return '';
+    const endpointName = typeof message.metadata?.endpoint === 'string'
+        ? message.metadata.endpoint
+        : undefined;
+    if (endpointName && Array.isArray(config.endpoints)) {
+        const entry = config.endpoints.find((item) => !!item && typeof item === 'object'
+            && item.name === endpointName);
+        if (typeof entry?.commandPrefix === 'string')
+            return entry.commandPrefix;
+    }
+    return typeof config.commandPrefix === 'string' ? config.commandPrefix : '';
+};
 export class MessageDispatcher {
-    prefix;
-    constructor(prefix = '/') {
-        this.prefix = prefix;
-        if (!prefix)
-            throw new TypeError('Command prefix cannot be empty');
+    resolvePrefix;
+    constructor(resolvePrefix = defaultCommandPrefixResolver) {
+        this.resolvePrefix = resolvePrefix;
     }
     async dispatch(message, snapshot) {
-        if (!message.content.startsWith(this.prefix))
-            return Object.freeze({ matched: false });
-        const input = message.content.slice(this.prefix.length).trim();
-        if (!input)
+        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)) {
+                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) {
+            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>;