@zhin.js/core 1.5.1 → 1.5.2

package/README.md

@@ -36,11 +36,14 @@ export default definePlugin({
 ```
 
 ```typescript
-// commands/hello/[name:string].ts
+// commands/hello/[name].ts
 import { defineCommand } from '@zhin.js/command'
 
 export default defineCommand({
   description: '打招呼',
+  params: {
+    name: { type: 'string' },
+  },
   execute({ params }) {
     return `Hello, ${params.name}!`
   },

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

@@ -1,4 +1,4 @@
-import type { CapabilityId, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { ConversationRef, DeliveryReceipt, MessageRef } from '@zhin.js/im-contract';
 import type { MediaRef, Segment } from '../../built/segment-contract/types.js';
 export type { MediaRef, Segment };
@@ -25,60 +25,33 @@ export declare function isRawContent(value: SendContent): value is RawContent;
 /** canonical Segment 一等公民判定（与 ComponentCall/RawContent 的 $content brand 互斥）。 */
 export declare function isSegmentContent(value: unknown): value is Segment;
 export interface IncomingMessage {
-    readonly adapter: CapabilityId;
-    /** Structured identity supplied by migrated adapters; target remains the bridge. */
-    readonly conversation?: ConversationRef;
-    /** Structured native message identity supplied by migrated adapters. */
+    readonly conversation: ConversationRef;
     readonly message?: MessageRef;
-    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>>;
 }
 export interface SendRequest {
-    readonly adapter: CapabilityId;
-    /** Structured destination supplied to Adapter endpoints in parallel with target. */
-    readonly conversation?: ConversationRef;
-    readonly target: string;
+    readonly conversation: ConversationRef;
     readonly requester: PluginId;
     readonly content: SendContent;
-    readonly parent?: ChannelParent;
-}
-/** Console 通道的来源场景（群临时会话 parent.group / QQ 子频道 parent.guild）。 */
-export interface ChannelParent {
-    readonly type?: string;
-    readonly id?: string;
-    readonly name?: string;
 }
+/**
+ * Host 侧未锚定 endpoint 的会话地址（Console RPC / OutboundHost 入参）；
+ * ImRuntime 解析 adapter/endpointId 后锚定为完整 ConversationRef。
+ */
+export type ConversationAddress = Omit<ConversationRef, 'endpoint'>;
 export interface OutboundEnvelope {
-    readonly adapter: CapabilityId;
-    readonly conversation?: ConversationRef;
-    readonly target: string;
+    readonly conversation: ConversationRef;
     readonly requester: PluginId;
     readonly generation: number;
     readonly payload: unknown;
-    readonly parent?: ChannelParent;
     replace(payload: unknown): void;
 }
 export interface MessageGateway {
     receive(input: IncomingMessage): Promise<MessageDispatchResult>;
-    /**
-     * Compatibility surface for existing Adapter-facing gateway consumers.
-     * Runtime callers that need an outcome use DeliveryMessageGateway instead.
-     */
-    send(request: SendRequest): Promise<unknown>;
+    send(request: SendRequest): Promise<DeliveryReceipt>;
     /**
      * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
      * 平台 callback 的 action 段、'text' 端点的数字回跳与指令预填直出
@@ -92,10 +65,6 @@ export interface MessageGateway {
      */
     setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
 }
-/** Structured outbound gateway exposed by the Plugin Runtime. */
-export interface DeliveryMessageGateway extends MessageGateway {
-    send(request: SendRequest): Promise<DeliveryReceipt>;
-}
 export interface MessageDispatchResult {
     readonly matched: boolean;
     readonly command?: string;
@@ -103,11 +72,9 @@ export interface MessageDispatchResult {
     readonly value?: unknown;
 }
 export declare class Message {
-    readonly adapter: CapabilityId;
-    readonly target: string;
+    readonly conversation: ConversationRef;
     readonly content: string;
     readonly generation: number;
-    readonly id?: string | undefined;
     readonly sender?: string | undefined;
     readonly metadata: Readonly<Record<string, unknown>>;
     /**
@@ -115,20 +82,18 @@ export declare class Message {
      * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
      */
     readonly segments?: readonly Segment[] | undefined;
-    /** Structured inbound conversation when supplied by a migrated adapter. */
-    readonly conversation?: ConversationRef | undefined;
-    /** Structured inbound message identity when supplied by a migrated adapter. */
+    /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
     readonly message?: MessageRef | 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>>, 
+    constructor(conversation: ConversationRef, content: string, generation: number, reply: (content: SendContent, requester?: PluginId) => Promise<DeliveryReceipt>, sender?: string | undefined, metadata?: Readonly<Record<string, unknown>>, 
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
      * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
      */
     segments?: readonly Segment[] | undefined, 
-    /** Structured inbound conversation when supplied by a migrated adapter. */
-    conversation?: ConversationRef | undefined, 
-    /** Structured inbound message identity when supplied by a migrated adapter. */
+    /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
     message?: MessageRef | undefined);
+    /** 平台原生消息 id（`message` 未提供时为 undefined）。 */
+    get id(): string | undefined;
     readonly $reply: (content: SendContent) => Promise<DeliveryReceipt>;
     readonly $replyFrom: (requester: PluginId, content: SendContent) => Promise<DeliveryReceipt>;
 }

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

@@ -33,44 +33,36 @@ export function isSegmentContent(value) {
         && value.data !== null;
 }
 export class Message {
-    adapter;
-    target;
+    conversation;
     content;
     generation;
-    id;
     sender;
     metadata;
     segments;
-    conversation;
     message;
-    constructor(adapter, target, content, generation, 
-    // Compatibility at the construction boundary: legacy tests and embedders
-    // may still supply an untyped reply callback. ImRuntime always supplies a
-    // DeliveryReceipt-producing implementation.
-    reply, id, sender, metadata = Object.freeze({}), 
+    constructor(conversation, content, generation, reply, sender, metadata = Object.freeze({}), 
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
      * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
      */
     segments, 
-    /** Structured inbound conversation when supplied by a migrated adapter. */
-    conversation, 
-    /** Structured inbound message identity when supplied by a migrated adapter. */
+    /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
     message) {
-        this.adapter = adapter;
-        this.target = target;
+        this.conversation = conversation;
         this.content = content;
         this.generation = generation;
-        this.id = id;
         this.sender = sender;
         this.metadata = metadata;
         this.segments = segments;
-        this.conversation = conversation;
         this.message = message;
         this.$reply = (content) => reply(content);
         this.$replyFrom = (requester, content) => reply(content, requester);
         Object.freeze(this);
     }
+    /** 平台原生消息 id（`message` 未提供时为 undefined）。 */
+    get id() {
+        return this.message?.id;
+    }
     $reply;
     $replyFrom;
 }

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

@@ -1,21 +1,18 @@
-import { Scope, type CapabilityId, type PluginId, type RuntimeSnapshot, type SnapshotStore } from '@zhin.js/plugin-runtime';
+import { Scope, type PluginId, type RuntimeSnapshot, type SnapshotStore } from '@zhin.js/plugin-runtime';
 import { type EndpointManagement, type EndpointManagementCapability } from '@zhin.js/adapter';
 import { type ConversationRef, type DeliveryReceipt, type MessageRef } from '@zhin.js/im-contract';
-import { Message, type ChannelParent, type DeliveryMessageGateway, type IncomingMessage, type MessageDispatchResult, type SendRequest } from './contracts.js';
+import { Message, type ConversationAddress, 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<DeliveryMessageGateway>;
+export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<MessageGateway>;
 /** Console 实时消息事件（SSE 推送源；content 仅为截断预览，不含完整原始段）。 */
 export interface RuntimeMessageEvent {
     readonly direction: 'inbound' | 'outbound';
-    readonly adapter: CapabilityId;
-    readonly target: string;
+    readonly conversation: ConversationRef;
     /** inbound：发送者 id。 */
     readonly sender?: string;
     /** outbound：发起方插件。 */
     readonly requester?: PluginId;
-    /** inbound：从 target 前缀解析的场景（`group:xx` → `group`）。 */
-    readonly channelType?: string;
     /** 预览文本，截断至 200 字。 */
     readonly contentPreview: string;
     readonly messageId?: string;
@@ -30,7 +27,7 @@ export interface ImRuntimeOptions {
     readonly commandPrefix?: string;
     readonly renderer?: OutboundRenderer;
 }
-export declare class ImRuntime implements DeliveryMessageGateway {
+export declare class ImRuntime implements MessageGateway {
     #private;
     constructor(options?: ImRuntimeOptions);
     attach(snapshots: SnapshotStore): void;
@@ -74,11 +71,8 @@ export declare class ImRuntime implements DeliveryMessageGateway {
     sendEndpointMessage(input: {
         readonly adapter: string;
         readonly endpointId: string;
-        readonly conversation?: ConversationRef;
-        readonly channelId?: string;
-        readonly channelType?: string;
+        readonly conversation: ConversationAddress;
         readonly content: unknown;
-        readonly parent?: ChannelParent;
     }): Promise<{
         messageId: string;
     }>;
@@ -116,8 +110,7 @@ export declare class ImRuntime implements DeliveryMessageGateway {
     setEndpointTyping(input: {
         readonly adapter: string;
         readonly endpointId: string;
-        readonly conversation?: ConversationRef;
-        readonly target?: string;
+        readonly conversation: ConversationRef;
         readonly active?: boolean;
     }): Promise<void>;
     /**

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

@@ -1,6 +1,6 @@
 import { createToken, htmlRendererToken, } from '@zhin.js/plugin-runtime';
 import { adapterFeatureId, isAdapterIndex, resolveEndpointControl, resolveEndpointManagement, } from '@zhin.js/adapter';
-import { formatLegacyConversationRef, formatLegacyMessageRef, isDeliveryReceipt, } from '@zhin.js/im-contract';
+import { formatLegacyMessageRef, isDeliveryReceipt, } from '@zhin.js/im-contract';
 import { isMiddlewareIndex, middlewareFeatureId } from '@zhin.js/middleware';
 import { formatCompact, getLogger, truncatePreview } from '@zhin.js/logger';
 import { Message, createOutboundEnvelope, } from './contracts.js';
@@ -9,7 +9,7 @@ import { OutboundRenderer } from './outbound-renderer.js';
 import { applyOutboundInteractivePolicy, normalizeOutboundPayload, resolveOutboundInteractivePolicy, resolveOutboundMediaPolicy, } from './outbound-segments.js';
 import { assertCanonicalSegments } from '../../built/segment-contract/assert.js';
 import { keyboardFallbackStore } from '../../built/interactive-segments/fallback-store.js';
-import { findRuntimeInteractiveHandler, resolveRuntimeInteractivePayload, runtimeInteractiveChannelKey, } from './interactive.js';
+import { findRuntimeInteractiveHandler, resolveRuntimeInteractivePayload, runtimeInteractiveConversationKey, } from './interactive.js';
 const logger = getLogger('im');
 export const messageGatewayToken = createToken('zhin.im.message-gateway');
 export const messagePreviewLimit = 200;
@@ -78,28 +78,28 @@ export class ImRuntime {
         const lease = this.#acquire();
         let active = true;
         try {
-            const requester = requireAdapters(lease.value).owner(input.adapter);
+            const conversation = input.conversation;
+            const adapter = conversation.endpoint.id;
+            const requester = requireAdapters(lease.value).owner(adapter);
             logger.debug(formatCompact({
                 op: 'im_inbound_receive',
-                adapter: String(input.adapter).split('\0').pop() ?? String(input.adapter),
-                target: input.target,
+                adapter: String(adapter).split('\0').pop() ?? String(adapter),
+                conversation: formatConversationLog(conversation),
                 sender: input.sender,
-                id: input.id,
+                id: input.message?.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) => {
+            const message = new Message(conversation, input.content, lease.value.generation, (content, replyRequester = requester) => {
                 if (!active)
                     throw new Error('Message reply scope has ended');
                 return this.#sendWithSnapshot({
-                    adapter: input.adapter,
-                    ...(input.conversation ? { conversation: input.conversation } : {}),
-                    target: input.target,
+                    conversation,
                     requester: replyRequester,
                     content,
                 }, lease.value);
-            }, input.id ?? input.message?.id, input.sender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined, input.conversation, input.message);
+            }, input.sender, Object.freeze({ ...input.metadata }), input.segments ? Object.freeze([...input.segments]) : undefined, input.message);
             let result = Object.freeze({ matched: false });
             await runMiddleware(lease.value, message, async () => {
                 result = await this.#dispatchInteractive(message, requester)
@@ -107,8 +107,8 @@ export class ImRuntime {
                 if (!result.matched && this.#unmatchedHandler) {
                     logger.debug(formatCompact({
                         op: 'im_inbound_unmatched_handler',
-                        target: input.target,
-                        id: input.id,
+                        conversation: formatConversationLog(conversation),
+                        id: input.message?.id,
                     }));
                     const handled = await this.#unmatchedHandler(message, lease.value, requester);
                     if (handled) {
@@ -118,24 +118,18 @@ export class ImRuntime {
             }, 'inbound');
             logger.debug(formatCompact({
                 op: 'im_inbound_done',
-                target: input.target,
-                id: input.id,
+                conversation: formatConversationLog(conversation),
+                id: input.message?.id,
                 matched: result.matched,
                 command: result.command,
                 owner: result.owner,
             }));
             this.#emitMessage({
                 direction: 'inbound',
-                adapter: input.adapter,
-                target: input.target,
+                conversation,
                 ...(input.sender !== undefined ? { sender: input.sender } : {}),
-                ...(channelTypeOf(input.target)
-                    ? { channelType: channelTypeOf(input.target) }
-                    : {}),
                 contentPreview: previewText(input.content),
-                ...(input.id ?? input.message?.id
-                    ? { messageId: input.id ?? input.message?.id }
-                    : {}),
+                ...(input.message?.id ? { messageId: input.message.id } : {}),
                 timestamp: Date.now(),
             });
             return result;
@@ -212,22 +206,19 @@ export class ImRuntime {
         const lease = this.#acquire();
         try {
             const index = requireAdapters(lease.value);
-            const capabilityId = index.resolve(input.adapter, input.endpointId);
-            if (!capabilityId)
+            const resolved = index.resolve(input.adapter, input.endpointId);
+            if (!resolved)
                 throw new Error('endpoint not found');
-            const target = input.conversation
-                ? formatLegacyConversationRef(input.conversation)
-                : composeSendTarget(input.channelType ?? '', input.channelId ?? '');
-            if (!target)
-                throw new TypeError('conversation or channelId is required');
+            const requester = index.owner(resolved);
+            const conversation = {
+                endpoint: { id: String(resolved), adapter: String(requester) },
+                ...input.conversation,
+            };
             const content = normalizeConsoleContent(input.content);
             const result = await this.#sendWithSnapshot({
-                adapter: capabilityId,
-                ...(input.conversation ? { conversation: input.conversation } : {}),
-                target,
-                requester: index.owner(capabilityId),
+                conversation,
+                requester,
                 content,
-                ...(input.parent ? { parent: input.parent } : {}),
             }, lease.value);
             return { messageId: result.message?.id ?? result.legacyMessageId ?? '' };
         }
@@ -257,13 +248,8 @@ export class ImRuntime {
             ?.edit?.(legacyMessageTarget(input.message, input.messageId), input.content) ?? null;
     }
     async setEndpointTyping(input) {
-        const target = input.conversation
-            ? formatLegacyConversationRef(input.conversation)
-            : input.target;
-        if (!target)
-            throw new TypeError('conversation or target is required');
         await this.#liveEndpointControl(input.adapter, input.endpointId)
-            ?.typing?.(target, input.active);
+            ?.typing?.(input.conversation, input.active);
     }
     #liveEndpoint(adapter, endpointId) {
         try {
@@ -303,21 +289,19 @@ export class ImRuntime {
         return resolveEndpointManagement(endpoint) ?? Object.freeze({});
     }
     async #sendWithSnapshot(request, snapshot) {
+        const adapter = request.conversation.endpoint.id;
         let initialPayload;
         try {
             const rendered = await this.#renderer.render(request.content, request.requester, snapshot);
-            initialPayload = await prepareOutboundPayload(rendered, request, snapshot);
+            initialPayload = await prepareOutboundPayload(rendered, request.conversation, snapshot);
         }
         catch {
             return rejectedReceipt('outbound_payload_rejected');
         }
         const envelope = createOutboundEnvelope({
-            adapter: request.adapter,
-            ...(request.conversation ? { conversation: request.conversation } : {}),
-            target: request.target,
+            conversation: request.conversation,
             requester: request.requester,
             generation: snapshot.generation,
-            ...(request.parent ? { parent: request.parent } : {}),
         }, initialPayload);
         let terminalEntered = false;
         let receipt;
@@ -326,20 +310,16 @@ export class ImRuntime {
                 terminalEntered = true;
                 let payload;
                 try {
-                    // Middleware may replace a payload with legacy/wire segments. Normalize
-                    // again at the transport boundary so it cannot bypass core policy.
-                    payload = await prepareOutboundPayload(envelope.payload, request, snapshot, true);
+                    payload = await prepareOutboundPayload(envelope.payload, request.conversation, snapshot, true);
                 }
                 catch {
                     receipt = rejectedReceipt('outbound_payload_rejected');
                     return;
                 }
                 try {
-                    const result = await requireAdapters(snapshot).send(request.adapter, {
-                        target: request.target,
-                        ...(request.conversation ? { conversation: request.conversation } : {}),
+                    const result = await requireAdapters(snapshot).send(adapter, {
+                        conversation: request.conversation,
                         payload,
-                        ...(request.parent ? { parent: request.parent } : {}),
                     });
                     receipt = receiptFromEndpointResult(result);
                 }
@@ -349,8 +329,7 @@ export class ImRuntime {
                 if (receipt?.status === 'sent') {
                     this.#emitMessage({
                         direction: 'outbound',
-                        adapter: request.adapter,
-                        target: request.target,
+                        conversation: request.conversation,
                         requester: request.requester,
                         contentPreview: previewText(payload),
                         ...(receipt.message?.id || receipt.legacyMessageId
@@ -362,8 +341,6 @@ export class ImRuntime {
             }, 'outbound');
         }
         catch {
-            // If a middleware fails after the terminal, the endpoint has already
-            // produced its receipt (and, for a real send, its event). Keep that fact.
             return receipt ?? failedReceipt('outbound_middleware_failed');
         }
         if (!terminalEntered)
@@ -423,18 +400,17 @@ function legacyMessageTarget(message, messageId) {
         return messageId;
     throw new TypeError('message or messageId is required');
 }
-async function prepareOutboundPayload(rendered, request, snapshot, finalizeInteractive = false) {
-    const directHtml = isDirectHtmlConsumer(snapshot, request.adapter);
+async function prepareOutboundPayload(rendered, conversation, snapshot, finalizeInteractive = false) {
+    const adapter = conversation.endpoint.id;
+    const directHtml = isDirectHtmlConsumer(snapshot, adapter);
     let payload = directHtml
         ? rendered
         : await normalizeOutboundPayload(rendered, resolveHtmlRenderer(snapshot), {
-            mediaPolicy: resolveOutboundMediaPolicy(request.adapter, snapshot),
+            mediaPolicy: resolveOutboundMediaPolicy(adapter, snapshot),
         });
     if (finalizeInteractive) {
-        payload = applyOutboundInteractivePolicy(payload, resolveOutboundInteractivePolicy(request.adapter, snapshot), (map) => keyboardFallbackStore.remember(runtimeInteractiveChannelKey(String(request.adapter), request.target), map));
+        payload = applyOutboundInteractivePolicy(payload, resolveOutboundInteractivePolicy(adapter, snapshot), (map) => keyboardFallbackStore.remember(runtimeInteractiveConversationKey(conversation), map));
     }
-    // Segment arrays crossing the adapter boundary are canonical after every
-    // middleware transform. Direct html consumers retain their explicit wire API.
     if (!directHtml && Array.isArray(payload))
         assertCanonicalSegments(payload);
     return payload;
@@ -490,18 +466,6 @@ function failedReceipt(code, retryable = false) {
         }),
     });
 }
-/**
- * Build Adapter send target. If channelId already carries a scene prefix
- * (`private:uid` / `group:gid`), do not double-prefix.
- */
-function composeSendTarget(channelType, channelId) {
-    const id = channelId.trim();
-    if (!id)
-        return channelType || '';
-    if (/^(private|group|channel|direct|c2c|temp):/iu.test(id))
-        return id;
-    return channelType ? `${channelType}:${id}` : id;
-}
 /** `@zhin.js/adapter-icqq` → `icqq`；非 adapter 包名原样返回。 */
 function adapterTypeName(packageName) {
     if (!packageName)
@@ -528,10 +492,14 @@ 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];
+/** 日志用会话摘要（`kind:id@parentKind:parentId#threadId`），不拼 legacy target。 */
+function formatConversationLog(conversation) {
+    const base = `${conversation.kind}:${conversation.id}`;
+    const parent = conversation.parent
+        ? `@${conversation.parent.kind}:${conversation.parent.id}`
+        : '';
+    const thread = conversation.threadId ? `#${conversation.threadId}` : '';
+    return `${base}${parent}${thread}`;
 }
 /** 消息内容 → 预览文本（截断 200 字）；wire 段取 `data.text`，其余段记 `[type]`。 */
 function previewText(content) {

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

@@ -1,3 +1,4 @@
+import type { ConversationRef } from '@zhin.js/im-contract';
 import type { Message } from './contracts.js';
 /**
  * Plugin Runtime IM 管线的 interactive action 回跳（旧轨
@@ -14,8 +15,8 @@ export interface RegisteredRuntimeInteractiveHandler {
     readonly prefix: string;
     readonly handler: RuntimeInteractiveHandler;
 }
-/** 频道键：出站降级写入与入站回跳读取共用（`adapter~target`）。 */
-export declare function runtimeInteractiveChannelKey(adapter: string, target: string): string;
+/** 频道键：出站降级写入与入站回跳读取共用（由 ConversationRef 派生，稳定即可）。 */
+export declare function runtimeInteractiveConversationKey(conversation: ConversationRef): string;
 /** prefix 最长匹配（与旧轨 findHandler 一致）。 */
 export declare function findRuntimeInteractiveHandler(handlers: readonly RegisteredRuntimeInteractiveHandler[], payload: string): RuntimeInteractiveHandler | undefined;
 /**

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

@@ -1,8 +1,13 @@
 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}`;
+/** 频道键：出站降级写入与入站回跳读取共用（由 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) {
@@ -27,7 +32,7 @@ export function resolveRuntimeInteractivePayload(message) {
     const raw = message.content.trim();
     if (!raw)
         return undefined;
-    return resolvePayloadFromText(raw, keyboardFallbackStore.mapFor(runtimeInteractiveChannelKey(String(message.adapter), message.target)));
+    return resolvePayloadFromText(raw, keyboardFallbackStore.mapFor(runtimeInteractiveConversationKey(message.conversation)));
 }
 function actionPayloadFromSegments(segments) {
     for (const seg of segments ?? []) {

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

@@ -2,7 +2,7 @@ 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];
+    return message.conversation.endpoint.adapter;
 }
 /**
  * 默认解析：读消息所属适配器实例 config 的 `commandPrefix`（默认 `''`）；

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/core",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -70,16 +70,16 @@
     "segment-matcher": "^1.0.5",
     "smol-toml": "^1.7.1",
     "yaml": "^2.9.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/component": "1.0.5",
-    "@zhin.js/im-contract": "1.0.0",
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/component": "1.0.6",
+    "@zhin.js/database": "1.0.78",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/kernel": "1.0.5",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/middleware": "1.0.5",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "@zhin.js/schema": "1.0.72",
-    "@zhin.js/database": "1.0.78"
+    "@zhin.js/middleware": "1.0.6",
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "@zhin.js/schema": "1.0.72"
   },
   "peerDependencies": {
     "zod": "^4.0.0"