@zhin.js/core 1.1.34 → 1.1.35

package/lib/component.js

@@ -176,24 +176,41 @@ function parseAttributeValue(str, startIndex, context) {
 function evaluateQuotedExpression(quotedValue, context) {
     if (!context)
         return quotedValue;
-    // 处理引号内的表达式，将 {expr} 格式转换为 ${expr} 格式
-    let result = quotedValue;
-    const expressionRegex = /\{([^}]+)\}/g;
-    let match;
-    while ((match = expressionRegex.exec(quotedValue)) !== null) {
-        const expr = match[1];
+    let result = '';
+    let cursor = 0;
+    for (const match of readBraceExpressions(quotedValue)) {
+        result += quotedValue.slice(cursor, match.start);
         try {
-            const value = context.getValue(expr);
-            if (value !== undefined && value !== expr) {
+            const value = context.getValue(match.expr);
+            if (value !== undefined && value !== match.expr) {
                 const stringValue = typeof value === 'string' ? value : JSON.stringify(value);
-                result = result.replace(match[0], stringValue);
+                result += stringValue;
+            }
+            else {
+                result += quotedValue.slice(match.start, match.end);
             }
         }
         catch (error) {
-            // 如果求值失败，保持原始表达式
+            result += quotedValue.slice(match.start, match.end);
         }
+        cursor = match.end;
     }
-    return result;
+    return result + quotedValue.slice(cursor);
+}
+function readBraceExpressions(value) {
+    const matches = [];
+    let cursor = 0;
+    while (cursor < value.length) {
+        const start = value.indexOf('{', cursor);
+        if (start < 0)
+            break;
+        const end = value.indexOf('}', start + 1);
+        if (end < 0)
+            break;
+        matches.push({ start, end: end + 1, expr: value.slice(start + 1, end) });
+        cursor = end + 1;
+    }
+    return matches;
 }
 /**
  * 解析表达式值
@@ -546,7 +563,7 @@ export async function renderComponents(componentMap, options, customContext) {
 }
 // 内置组件
 export const Fragment = defineComponent(async (props, context) => {
-    let children = props.children || '';
+    const children = props.children || '';
     if (Array.isArray(children)) {
         return children.join('');
     }
@@ -562,6 +579,5 @@ export const Fragment = defineComponent(async (props, context) => {
     return String(children);
 }, 'Fragment');
 export const Fetch = defineComponent(async ({ url }) => {
-    return await fetch(url).then((r) => r.text());
+    return await fetch(url, { signal: AbortSignal.timeout(30_000) }).then((r) => r.text());
 }, 'fetch');
-//# sourceMappingURL=component.js.map

package/lib/endpoint-capabilities.d.ts

@@ -0,0 +1,46 @@
+import type { Message } from './message.js';
+import type { Notice } from './notice.js';
+import type { Request } from './request.js';
+import type { SendOptions } from './types.js';
+import type { AIAccessScopeConfig } from './built/ai-access.js';
+export type EndpointCapability = 'inbound' | 'outbound';
+export declare const DEFAULT_ENDPOINT_CAPABILITIES: readonly EndpointCapability[];
+/** 入站能力：含连接生命周期 */
+export interface InboundEndpoint<Config extends object = object, Event extends object = object> {
+    $id: string;
+    $config: Config;
+    $connected: boolean;
+    $formatMessage(event: Event): Message<Event>;
+    $formatNotice?(event: unknown): Notice;
+    $formatRequest?(event: unknown): Request;
+    $connect(): Promise<void>;
+    $disconnect(): Promise<void>;
+}
+/** 出站能力：无连接方法 */
+export interface OutboundEndpoint<Config extends object = object> {
+    $id: string;
+    $config: Config;
+    $connected: boolean;
+    $sendMessage(options: SendOptions): Promise<string>;
+}
+export type FullEndpoint<Config extends object = object, Event extends object = object> = InboundEndpoint<Config, Event> & OutboundEndpoint<Config>;
+export type CapableEndpoint<Config extends object, Event extends object, Caps extends readonly EndpointCapability[]> = ('inbound' extends Caps[number] ? InboundEndpoint<Config, Event> : object) & ('outbound' extends Caps[number] ? OutboundEndpoint<Config> : object);
+export declare class OutboundNotSupportedError extends Error {
+    constructor(endpointKey?: string);
+}
+export declare class InboundNotSupportedError extends Error {
+    constructor(endpointKey?: string);
+}
+export declare function registerEndpointCapabilities(endpoint: object, caps: readonly EndpointCapability[]): void;
+export declare function getEndpointCapabilities(endpoint: object): readonly EndpointCapability[] | undefined;
+export declare function resolveEndpointCapabilities(adapterCaps: readonly EndpointCapability[], endpointConfigCaps?: readonly EndpointCapability[]): readonly EndpointCapability[];
+export declare function getAdapterCapabilities(adapter: object): readonly EndpointCapability[];
+export declare function hasInbound(endpoint: object): boolean;
+export declare function hasOutbound(endpoint: object): boolean;
+export declare function assertInbound(endpoint: InboundEndpoint | OutboundEndpoint): asserts endpoint is InboundEndpoint;
+export declare function assertOutbound(endpoint: InboundEndpoint | OutboundEndpoint): asserts endpoint is OutboundEndpoint;
+export interface EndpointCapabilitiesConfig {
+    capabilities?: EndpointCapability[];
+    /** 本 Endpoint 的 AI 访问控制（覆盖 ai.access 全局默认） */
+    aiAccess?: AIAccessScopeConfig;
+}

package/lib/endpoint-capabilities.js

@@ -0,0 +1,55 @@
+export const DEFAULT_ENDPOINT_CAPABILITIES = ['inbound', 'outbound'];
+export class OutboundNotSupportedError extends Error {
+    constructor(endpointKey) {
+        super(endpointKey ? `Endpoint ${endpointKey} does not support outbound` : 'Outbound not supported');
+        this.name = 'OutboundNotSupportedError';
+    }
+}
+export class InboundNotSupportedError extends Error {
+    constructor(endpointKey) {
+        super(endpointKey ? `Endpoint ${endpointKey} does not support inbound` : 'Inbound not supported');
+        this.name = 'InboundNotSupportedError';
+    }
+}
+const endpointCapabilitiesRegistry = new WeakMap();
+export function registerEndpointCapabilities(endpoint, caps) {
+    endpointCapabilitiesRegistry.set(endpoint, caps);
+}
+export function getEndpointCapabilities(endpoint) {
+    return endpointCapabilitiesRegistry.get(endpoint);
+}
+export function resolveEndpointCapabilities(adapterCaps, endpointConfigCaps) {
+    const resolved = endpointConfigCaps?.length ? [...endpointConfigCaps] : [...adapterCaps];
+    if (resolved.length === 0) {
+        throw new Error('Endpoint must declare at least one capability (inbound and/or outbound)');
+    }
+    for (const cap of resolved) {
+        if (!adapterCaps.includes(cap)) {
+            throw new Error(`Endpoint capability "${cap}" exceeds adapter capabilities [${adapterCaps.join(', ')}]`);
+        }
+    }
+    return resolved;
+}
+export function getAdapterCapabilities(adapter) {
+    const ctor = adapter.constructor;
+    const caps = ctor.capabilities;
+    return caps?.length ? caps : DEFAULT_ENDPOINT_CAPABILITIES;
+}
+export function hasInbound(endpoint) {
+    const caps = getEndpointCapabilities(endpoint);
+    return caps ? caps.includes('inbound') : true;
+}
+export function hasOutbound(endpoint) {
+    const caps = getEndpointCapabilities(endpoint);
+    return caps ? caps.includes('outbound') : true;
+}
+export function assertInbound(endpoint) {
+    if (!hasInbound(endpoint)) {
+        throw new InboundNotSupportedError('$id' in endpoint ? String(endpoint.$id) : undefined);
+    }
+}
+export function assertOutbound(endpoint) {
+    if (!hasOutbound(endpoint)) {
+        throw new OutboundNotSupportedError('$id' in endpoint ? String(endpoint.$id) : undefined);
+    }
+}

package/lib/endpoint.d.ts

@@ -0,0 +1,19 @@
+import type { Adapters, Adapter } from './adapter.js';
+import type { EndpointCapabilitiesConfig, FullEndpoint } from './endpoint-capabilities.js';
+import type { EndpointWithControl, EndpointWithManagement } from '@zhin.js/adapter';
+export type { EndpointChannel, EndpointChannelParent, EndpointFriend, EndpointGroup, EndpointManagement, EndpointWithManagement, EndpointManagementCapability, } from '@zhin.js/adapter';
+export { endpointManagementCapabilityIds, listEndpointManagementCapabilities, resolveEndpointManagement, } from '@zhin.js/adapter';
+export type { EndpointControl, EndpointWithControl } from '@zhin.js/adapter';
+export { endpointControlOf } from '@zhin.js/adapter';
+export type { EndpointCapability, EndpointCapabilitiesConfig, InboundEndpoint, OutboundEndpoint, FullEndpoint, CapableEndpoint, } from './endpoint-capabilities.js';
+export { DEFAULT_ENDPOINT_CAPABILITIES, OutboundNotSupportedError, InboundNotSupportedError, resolveEndpointCapabilities, registerEndpointCapabilities, getEndpointCapabilities, getAdapterCapabilities, hasInbound, hasOutbound, assertInbound, assertOutbound, } from './endpoint-capabilities.js';
+/**
+ * Endpoint 接口：全双工平台机器人（入站 + 出站）。
+ * 纯入站 / 纯出站请实现 InboundEndpoint / OutboundEndpoint。
+ */
+export type Endpoint<Config extends object = object, Event extends object = object> = FullEndpoint<Config, Event> & EndpointWithManagement & EndpointWithControl;
+export declare namespace Endpoint {
+    type Config<K extends keyof Adapters = keyof Adapters> = Adapter.EndpointConfig<Adapter.InferEndpoint<Adapters[K]>> & EndpointCapabilitiesConfig & {
+        context: K;
+    };
+}

package/lib/endpoint.js

@@ -0,0 +1,3 @@
+export { endpointManagementCapabilityIds, listEndpointManagementCapabilities, resolveEndpointManagement, } from '@zhin.js/adapter';
+export { endpointControlOf } from '@zhin.js/adapter';
+export { DEFAULT_ENDPOINT_CAPABILITIES, OutboundNotSupportedError, InboundNotSupportedError, resolveEndpointCapabilities, registerEndpointCapabilities, getEndpointCapabilities, getAdapterCapabilities, hasInbound, hasOutbound, assertInbound, assertOutbound, } from './endpoint-capabilities.js';

package/lib/errors.d.ts

@@ -8,8 +8,8 @@ import { ZhinError } from '@zhin.js/kernel';
  */
 export declare class AdapterError extends ZhinError {
     readonly adapterName: string;
-    readonly botName?: string;
-    constructor(message: string, adapterName: string, botName?: string, context?: Record<string, any>);
+    readonly endpointKey?: string;
+    constructor(message: string, adapterName: string, endpointKey?: string, context?: Record<string, any>);
 }
 /**
  * 消息处理错误
@@ -19,4 +19,3 @@ export declare class MessageError extends ZhinError {
     readonly channelId?: string;
     constructor(message: string, messageId?: string, channelId?: string, context?: Record<string, any>);
 }
-//# sourceMappingURL=errors.d.ts.map

package/lib/errors.js

@@ -8,11 +8,11 @@ import { ZhinError } from '@zhin.js/kernel';
  */
 export class AdapterError extends ZhinError {
     adapterName;
-    botName;
-    constructor(message, adapterName, botName, context) {
-        super(message, 'ADAPTER_ERROR', { ...context, adapterName, botName });
+    endpointKey;
+    constructor(message, adapterName, endpointKey, context) {
+        super(message, 'ADAPTER_ERROR', { ...context, adapterName, endpointKey });
         this.adapterName = adapterName;
-        this.botName = botName;
+        this.endpointKey = endpointKey;
     }
 }
 /**
@@ -27,4 +27,3 @@ export class MessageError extends ZhinError {
         this.channelId = channelId;
     }
 }
-//# sourceMappingURL=errors.js.map

package/lib/feature/adapter.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Adapter Feature — implementation in `@zhin.js/adapter`. */
+export * from '@zhin.js/adapter';

package/lib/feature/adapter.js

@@ -0,0 +1,2 @@
+/** Authoring API for Adapter Feature — implementation in `@zhin.js/adapter`. */
+export * from '@zhin.js/adapter';

package/lib/feature/command.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Command Feature — implementation in `@zhin.js/command`. */
+export * from '@zhin.js/command';

package/lib/feature/command.js

@@ -0,0 +1,2 @@
+/** Authoring API for Command Feature — implementation in `@zhin.js/command`. */
+export * from '@zhin.js/command';

package/lib/feature/component.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Component Feature — implementation in `@zhin.js/component`. */
+export * from '@zhin.js/component';

package/lib/feature/component.js

@@ -0,0 +1,2 @@
+/** Authoring API for Component Feature — implementation in `@zhin.js/component`. */
+export * from '@zhin.js/component';

package/lib/feature/handler.d.ts

@@ -0,0 +1,52 @@
+/** Authoring API for Handler Feature — implementation in `@zhin.js/handler`. */
+export { parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, handlerEventFromLocalName, resolveHandlerEvent, type HandlerEventMap, type HandlerDefinition, type HandlerDescriptor, type HandlerContext, type HandlerDispatchOptions, } from '@zhin.js/handler';
+import { type HandlerContext, type HandlerDefinition, type HandlerEventMap } from '@zhin.js/handler';
+import type { Plugin } from '../plugin.js';
+import type { Message } from '../plugin-runtime/im/contracts.js';
+import type { Notice } from '../notice.js';
+import type { Request } from '../request.js';
+import type { SystemEvent } from '../system-event.js';
+import type { AdapterClient, AdapterEvents, EndpointEvent, EndpointIdentity, PlatformEvent, RegisteredAdapterName } from '@zhin.js/adapter';
+type KnownKeys<T> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
+declare module '@zhin.js/handler' {
+    interface HandlerEventMap extends KnownKeys<Omit<Plugin.Lifecycle, 'message.receive' | 'notice.receive' | 'request.receive' | 'system.receive'>> {
+        'message.receive': [event: EndpointEvent<Message>];
+        'notice.receive': [event: EndpointEvent<Notice>];
+        'request.receive': [event: EndpointEvent<Request>];
+        'system.receive': [event: EndpointEvent<SystemEvent>];
+        'platform.receive': [event: EndpointEvent<PlatformEvent>];
+    }
+}
+type NativeEventName<TAdapter extends RegisteredAdapterName> = Extract<keyof AdapterEvents<TAdapter>, string>;
+/** Fully inferred native platform event exposed to plugin handlers. */
+export interface ClientHandlerEvent<TAdapter extends RegisteredAdapterName, TName extends NativeEventName<TAdapter> = NativeEventName<TAdapter>> {
+    readonly name: TName;
+    readonly event: AdapterEvents<TAdapter>[TName];
+    readonly endpoint: EndpointIdentity;
+    readonly client: AdapterClient<TAdapter>;
+}
+export interface ClientHandlerOptions<TAdapter extends RegisteredAdapterName, TName extends NativeEventName<TAdapter>> {
+    readonly adapter: TAdapter;
+    readonly event: TName;
+    handle(this: HandlerContext, event: ClientHandlerEvent<TAdapter, TName>): void | Promise<void>;
+}
+export interface ClientHandlerWildcardEvent<TAdapter extends RegisteredAdapterName> {
+    readonly name: string;
+    readonly event: unknown;
+    readonly endpoint: EndpointIdentity;
+    readonly client: AdapterClient<TAdapter>;
+}
+export interface ClientHandlerWildcardOptions<TAdapter extends RegisteredAdapterName> {
+    readonly adapter: TAdapter;
+    readonly event: '*';
+    handle(this: HandlerContext, event: ClientHandlerWildcardEvent<TAdapter>): void | Promise<void>;
+}
+export declare function defineHandler<TAdapter extends RegisteredAdapterName, TName extends NativeEventName<TAdapter>>(options: ClientHandlerOptions<TAdapter, TName>): Readonly<HandlerDefinition<'platform.receive'>>;
+/** Handle every native event from one Client without pretending unknown payloads are typed. */
+export declare function defineHandler<TAdapter extends RegisteredAdapterName>(options: ClientHandlerWildcardOptions<TAdapter>): Readonly<HandlerDefinition<'platform.receive'>>;
+export declare function defineHandler<K extends keyof HandlerEventMap & string>(options: {
+    readonly event: K;
+    handle(this: HandlerContext, ...args: HandlerEventMap[K] extends unknown[] ? HandlerEventMap[K] : unknown[]): void | Promise<void>;
+}): Readonly<HandlerDefinition<K>>;

package/lib/feature/handler.js

@@ -0,0 +1,26 @@
+/** Authoring API for Handler Feature — implementation in `@zhin.js/handler`. */
+export { parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, handlerEventFromLocalName, resolveHandlerEvent, } from '@zhin.js/handler';
+import { defineHandler as defineHandlerFeature, } from '@zhin.js/handler';
+export function defineHandler(options) {
+    if (!('adapter' in options) || typeof options.adapter !== 'string') {
+        return defineHandlerFeature(options);
+    }
+    const adapter = options.adapter;
+    const expectedName = options.event === '*' ? undefined : options.event;
+    return defineHandlerFeature({
+        event: 'platform.receive',
+        async handle(source) {
+            if (source.endpoint.adapter !== adapter)
+                return;
+            if (expectedName !== undefined && source.payload.name !== expectedName)
+                return;
+            const event = Object.freeze({
+                name: source.payload.name,
+                event: source.payload.event,
+                endpoint: source.endpoint,
+                client: source.client,
+            });
+            await options.handle.call(this, event);
+        },
+    });
+}

package/lib/feature/middleware.d.ts

@@ -0,0 +1,2 @@
+/** Authoring API for Middleware Feature — implementation in `@zhin.js/middleware`. */
+export * from '@zhin.js/middleware';

package/lib/feature/middleware.js

@@ -0,0 +1,2 @@
+/** Authoring API for Middleware Feature — implementation in `@zhin.js/middleware`. */
+export * from '@zhin.js/middleware';

package/lib/host-plugin-registry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @deprecated **已删除**。全局根插件注册表已移除；服务通过 Scope+Token 提供。
+ * 保留 no-op 签名供编译期过渡。
+ */
+/** @deprecated 已删除——不做任何事。 */
+export declare function setHostRootPlugin(_plugin: unknown): void;
+/** @deprecated 已删除——总是返回 null。 */
+export declare function getHostRootPlugin(): null;

package/lib/host-plugin-registry.js

@@ -0,0 +1,12 @@
+/**
+ * @deprecated **已删除**。全局根插件注册表已移除；服务通过 Scope+Token 提供。
+ * 保留 no-op 签名供编译期过渡。
+ */
+/** @deprecated 已删除——不做任何事。 */
+export function setHostRootPlugin(_plugin) {
+    // no-op: legacy host root plugin registry has been removed
+}
+/** @deprecated 已删除——总是返回 null。 */
+export function getHostRootPlugin() {
+    return null;
+}

package/lib/im-scene.d.ts

@@ -0,0 +1,29 @@
+import type { Message, MessageType } from './message.js';
+import type { SendContent, SendOptions } from './types.js';
+export type IMSceneKind = MessageType;
+/** Parent scene kind (distinct from sub-channel MessageType.channel). */
+export type IMSceneParentKind = 'group' | 'guild';
+export interface IMSceneParentRef {
+    kind: IMSceneParentKind;
+    sceneId: string;
+}
+export interface IMSceneRef {
+    platform: string;
+    endpointKey: string;
+    sceneId: string;
+    kind: IMSceneKind;
+    senderId?: string;
+    parent?: IMSceneParentRef;
+}
+export interface IMDeliveryTarget {
+    channel: 'im';
+    scene: IMSceneRef;
+    threadId?: string;
+    quoteId?: string;
+}
+/** Normalize legacy parent.type channel → guild. */
+export declare function normalizeIMSceneParentKind(value: unknown): IMSceneParentKind | undefined;
+export declare function sceneRefFromMessage(message: Partial<Message<any>>): IMSceneRef | undefined;
+export declare function sceneRefToSendOptions(target: IMDeliveryTarget, content: SendContent): SendOptions;
+export declare function resolveIMSceneSessionId(scene: IMSceneRef): string;
+export declare function messageToIMDeliveryTarget(message: Partial<Message<any>>): IMDeliveryTarget | undefined;

package/lib/im-scene.js

@@ -0,0 +1,75 @@
+import { resolveIMSceneSessionId as resolveIMSceneSessionIdKernel, } from '@zhin.js/kernel';
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+/** Normalize legacy parent.type channel → guild. */
+export function normalizeIMSceneParentKind(value) {
+    if (value === 'group' || value === 'guild')
+        return value;
+    if (value === 'channel')
+        return 'guild';
+    return undefined;
+}
+export function sceneRefFromMessage(message) {
+    const platform = nonEmptyString(message.$adapter);
+    const endpointKey = nonEmptyString(message.$endpoint);
+    const kind = message.$channel?.type;
+    if (!platform || !endpointKey || !kind)
+        return undefined;
+    const senderId = nonEmptyString(message.$sender?.id);
+    const channelId = nonEmptyString(message.$channel?.id);
+    const sceneId = kind === 'private'
+        ? senderId ?? channelId
+        : channelId ?? senderId;
+    if (!sceneId)
+        return undefined;
+    const parentKind = message.$channel?.parent
+        ? normalizeIMSceneParentKind(message.$channel.parent.type)
+        : undefined;
+    const parent = parentKind && message.$channel?.parent
+        ? {
+            kind: parentKind,
+            sceneId: String(message.$channel.parent.id),
+        }
+        : undefined;
+    return {
+        platform,
+        endpointKey,
+        sceneId,
+        kind,
+        ...(senderId ? { senderId } : {}),
+        ...(parent ? { parent } : {}),
+    };
+}
+export function sceneRefToSendOptions(target, content) {
+    const { scene } = target;
+    return {
+        context: scene.platform,
+        endpoint: scene.endpointKey,
+        id: scene.sceneId,
+        type: scene.kind,
+        parent: scene.parent
+            ? { type: scene.parent.kind, id: scene.parent.sceneId }
+            : undefined,
+        content,
+        ...(target.quoteId ? { quoteId: target.quoteId } : {}),
+        ...(target.threadId ? { threadId: target.threadId } : {}),
+    };
+}
+export function resolveIMSceneSessionId(scene) {
+    return resolveIMSceneSessionIdKernel({
+        platform: scene.platform,
+        endpointKey: scene.endpointKey,
+        sceneId: scene.sceneId,
+        kind: scene.kind,
+    });
+}
+export function messageToIMDeliveryTarget(message) {
+    const scene = sceneRefFromMessage(message);
+    if (!scene)
+        return undefined;
+    return {
+        channel: 'im',
+        scene,
+    };
+}

package/lib/im-session-id.d.ts

@@ -0,0 +1,39 @@
+/**
+ * IM 会话 ID 解析（SSOT 在 @zhin.js/kernel + im-scene）
+ *
+ * 格式：`platform:endpointKey:kind:sceneId`
+ */
+import { type ResolveIMSessionIdInput } from '@zhin.js/kernel';
+import { type IMSceneKind, type IMSceneRef } from './im-scene.js';
+export type { IMSceneKind, ResolveIMSessionIdInput };
+export declare function resolveIMSessionId(input: ResolveIMSessionIdInput): string;
+export declare function resolveIMSessionIdFromScene(scene: IMSceneRef): string;
+export declare function resolveIMSceneIdForSession(kind: IMSceneKind, sceneId?: string, senderId?: string): string;
+export declare function resolveIMSessionIdFromMessage(message: {
+    $adapter?: string;
+    $endpoint?: string;
+    $channel?: {
+        type?: IMSceneKind;
+        id?: string;
+    };
+    $sender?: {
+        id?: string;
+    };
+}): string;
+/** Canonical scene fields for transcript / session persistence (ADR 0028 SSOT). */
+export declare function resolveSceneFieldsFromMessage(message: {
+    $adapter?: string;
+    $endpoint?: string;
+    $channel?: {
+        type?: IMSceneKind;
+        id?: string;
+    };
+    $sender?: {
+        id?: string;
+    };
+}): {
+    platform: string;
+    endpointKey: string;
+    sceneId: string;
+    sceneType: IMSceneKind;
+};

package/lib/im-session-id.js

@@ -0,0 +1,47 @@
+/**
+ * IM 会话 ID 解析（SSOT 在 @zhin.js/kernel + im-scene）
+ *
+ * 格式：`platform:endpointKey:kind:sceneId`
+ */
+import { resolveIMSceneIdForSession as resolveIMSceneIdForSessionKernel, resolveIMSessionId as resolveIMSessionIdKernel, } from '@zhin.js/kernel';
+import { resolveIMSceneSessionId, sceneRefFromMessage, } from './im-scene.js';
+export function resolveIMSessionId(input) {
+    return resolveIMSessionIdKernel(input);
+}
+export function resolveIMSessionIdFromScene(scene) {
+    return resolveIMSceneSessionId(scene);
+}
+export function resolveIMSceneIdForSession(kind, sceneId, senderId) {
+    return resolveIMSceneIdForSessionKernel(kind, sceneId, senderId);
+}
+export function resolveIMSessionIdFromMessage(message) {
+    const scene = sceneRefFromMessage(message);
+    if (scene)
+        return resolveIMSceneSessionId(scene);
+    const kind = (message.$channel?.type || 'private');
+    return resolveIMSessionId({
+        platform: String(message.$adapter || ''),
+        endpointKey: String(message.$endpoint || ''),
+        kind,
+        sceneId: resolveIMSceneIdForSession(kind, message.$channel?.id, message.$sender?.id),
+    });
+}
+/** Canonical scene fields for transcript / session persistence (ADR 0028 SSOT). */
+export function resolveSceneFieldsFromMessage(message) {
+    const scene = sceneRefFromMessage(message);
+    if (scene) {
+        return {
+            platform: scene.platform,
+            endpointKey: scene.endpointKey,
+            sceneId: scene.sceneId,
+            sceneType: scene.kind,
+        };
+    }
+    const sceneType = (message.$channel?.type || 'private');
+    return {
+        platform: String(message.$adapter || ''),
+        endpointKey: String(message.$endpoint || ''),
+        sceneType,
+        sceneId: resolveIMSceneIdForSession(sceneType, message.$channel?.id, message.$sender?.id),
+    };
+}