@zhin.js/adapter-milky 6.0.2 → 6.0.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @zhin.js/adapter-milky
 
+## 6.0.3
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - @zhin.js/agent@1.1.3
+  - zhin.js@6.0.2
+
 ## 6.0.2
 
 ### Patch Changes

package/README.md

@@ -8,7 +8,7 @@ Zhin.js [Milky](https://milky.ntqqrev.org/) 协议适配器（Plugin Runtime）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - **正向 WebSocket**（`connection: ws`）：应用连协议端 `ws(s)://baseUrl/event`
 - `access_token` 鉴权（Bearer + query）
-- 入站经 `messageGatewayToken`；出站 `send({ target, payload })` → HTTP `send_*_message`
+- 入站经 `messageGatewayToken`；出站 `send({ conversation, payload })` → HTTP `send_*_message`
 
 ## 安装
 
@@ -23,8 +23,8 @@ pnpm add @zhin.js/adapter-milky
 - `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-入站：`gateway.receive({ adapter, target: "private:uid"|"group:gid", content, sender, metadata })`  
-出站：`send({ target, payload })` → HTTP `send_private_message` / `send_group_message`（payload 已由 gateway/core 渲染；无 segment-mapper）
+入站：`gateway.receive({ conversation: ConversationRef(kind: "private"|"group", id), message, content, sender, metadata })`  
+出站：`send({ conversation, payload })` → HTTP `send_private_message` / `send_group_message`（payload 已由 gateway/core 渲染；无 segment-mapper）
 
 ## 最小配置
 

package/lib/index.d.ts

@@ -1,3 +1,3 @@
-export { buildSendAction, buildSseConnectOptions, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, isMessageReceiveEvent, parseMessageReceiveData, parseMilkyMessageId, parseSendTarget, resolveMilkyConfig, senderNickname, type MilkyAdapterConfig, type MilkyApiClientOptions, type MilkyApiResponse, type MilkyConfigBase, type MilkyEndpointConfig, type MilkyEvent, type MilkyIncomingMessage, type MilkyIncomingSegment, type MilkyOutgoingSegment, type MilkySseConfig, type MilkyWebhookConfig, type MilkyWireSegment, type MilkyWsConfig, type MilkyWssConfig, type ParsedSendTarget, type ResolvedMilkyConfig, } from './protocol.js';
+export { buildSendAction, buildSseConnectOptions, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatOutboundSegments, isMentioned, isMessageReceiveEvent, milkyInboundConversation, parseMessageReceiveData, resolveMilkyConfig, senderNickname, type MilkyAdapterConfig, type MilkyApiClientOptions, type MilkyApiResponse, type MilkyConfigBase, type MilkyEndpointConfig, type MilkyEvent, type MilkyIncomingMessage, type MilkyIncomingSegment, type MilkyOutgoingSegment, type MilkySseConfig, type MilkyWebhookConfig, type MilkyWireSegment, type MilkyWsConfig, type MilkyWssConfig, type ResolvedMilkyConfig, } from './protocol.js';
 export { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, consumeSseBuffer, openSseStream, readRequestBody, verifyMilkyAccessToken, type CreateMilkySseStream, type MilkySseEndpointOptions, type MilkyWebhookEndpointOptions, type MilkyWssEndpointOptions, type MilkyWsCreateOptions, type MilkyWsEndpointOptions, type MilkyWsSocket, } from './endpoint.js';
 export { getMilkyAgentDeps, registerMilkyAgentEndpoint, setMilkyAgentDeps, type MilkyAgentDeps, type MilkyAgentEndpoint, } from './milky-agent-deps.js';

package/lib/index.js

@@ -1,3 +1,3 @@
-export { buildSendAction, buildSseConnectOptions, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, isMessageReceiveEvent, parseMessageReceiveData, parseMilkyMessageId, parseSendTarget, resolveMilkyConfig, senderNickname, } from './protocol.js';
+export { buildSendAction, buildSseConnectOptions, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatOutboundSegments, isMentioned, isMessageReceiveEvent, milkyInboundConversation, parseMessageReceiveData, resolveMilkyConfig, senderNickname, } from './protocol.js';
 export { MilkySseEndpoint, MilkyWebhookEndpoint, MilkyWssEndpoint, MilkyWsEndpoint, consumeSseBuffer, openSseStream, readRequestBody, verifyMilkyAccessToken, } from './endpoint.js';
 export { getMilkyAgentDeps, registerMilkyAgentEndpoint, setMilkyAgentDeps, } from './milky-agent-deps.js';

package/lib/protocol.d.ts

@@ -4,6 +4,7 @@
  * Spec: https://milky.ntqqrev.org/
  */
 import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationRef } from '@zhin.js/im-contract';
 /** Transitional legacy endpoint row (`endpoints[]` with `context: milky`). */
 export interface MilkyLegacyEndpointRow {
     readonly context?: string;
@@ -103,10 +104,6 @@ export interface MilkyOutgoingSegment {
     type: string;
     data: Record<string, unknown>;
 }
-export interface ParsedSendTarget {
-    readonly message_type: 'private' | 'group';
-    readonly id: string;
-}
 export interface MilkyApiClientOptions {
     readonly baseUrl: string;
     readonly access_token?: string;
@@ -122,8 +119,11 @@ export declare function parseMessageReceiveData(event: MilkyEvent): MilkyIncomin
 export declare function isMessageReceiveEvent(event: MilkyEvent): event is MilkyEvent & {
     data: MilkyIncomingMessage;
 };
-/** Gateway reply target：`private:uid` / `group:gid` */
-export declare function formatInboundTarget(data: MilkyIncomingMessage): string;
+/**
+ * 入站归一化 → ConversationRef：`friend`（私聊）→ `private`；`group` → `group`；
+ * `temp`（群临时会话）→ 群容器内的 `private` 会话（parent = 来源群）。
+ */
+export declare function milkyInboundConversation(endpointId: string, data: MilkyIncomingMessage): ConversationRef;
 export declare function formatInboundContent(data: MilkyIncomingMessage): string;
 /**
  * 入站消息段 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
@@ -139,7 +139,6 @@ export declare function senderNickname(data: MilkyIncomingMessage): string | und
 /** 消息段中含 @ 本机（mention 段 user_id 等于协议端上报的 self_id）。 */
 export declare function isMentioned(data: MilkyIncomingMessage, selfId: number | undefined): boolean;
 export declare function formatInboundMessageId(data: MilkyIncomingMessage): string;
-export declare function parseSendTarget(target: string): ParsedSendTarget;
 /**
  * Wire-encode an already-rendered outbound payload into Milky outgoing segments.
  * Segment canonicalization is intentionally not done here.
@@ -147,12 +146,15 @@ export declare function parseSendTarget(target: string): ParsedSendTarget;
  * file 段 Milky 消息 API 无对应 wire 段（文件走 upload_* API），warn + 丢弃。
  */
 export declare function formatOutboundSegments(payload: unknown): MilkyOutgoingSegment[];
-export declare function buildSendAction(target: string, message: MilkyOutgoingSegment[]): {
+export declare function buildSendAction(conversation: ConversationRef, message: MilkyOutgoingSegment[]): {
     action: string;
     params: Record<string, unknown>;
 };
-/** message_seq result → gateway message id */
-export declare function formatOutboundMessageId(target: string, messageSeq: number | undefined): string;
+/**
+ * message_seq result → gateway message id（`scene:peer:seq` 复合格式，
+ * 与 formatInboundMessageId 同源，仅供 recall 链在本端点边界内解析）。
+ */
+export declare function formatOutboundMessageId(conversation: ConversationRef, messageSeq: number | undefined): string;
 export declare function parseMilkyMessageId(msgId: string): {
     message_scene: 'friend' | 'group' | 'temp';
     peer_id: number;

package/lib/protocol.js

@@ -125,10 +125,19 @@ export function parseMessageReceiveData(event) {
 export function isMessageReceiveEvent(event) {
     return parseMessageReceiveData(event) != null;
 }
-/** Gateway reply target：`private:uid` / `group:gid` */
-export function formatInboundTarget(data) {
-    const isGroup = data.message_scene === 'group';
-    return `${isGroup ? 'group' : 'private'}:${data.peer_id}`;
+/**
+ * 入站归一化 → ConversationRef：`friend`（私聊）→ `private`；`group` → `group`；
+ * `temp`（群临时会话）→ 群容器内的 `private` 会话（parent = 来源群）。
+ */
+export function milkyInboundConversation(endpointId, data) {
+    return {
+        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        kind: data.message_scene === 'group' ? 'group' : 'private',
+        id: String(data.peer_id),
+        ...(data.message_scene === 'temp' && data.group
+            ? { parent: { kind: 'group', id: String(data.group.group_id) } }
+            : {}),
+    };
 }
 export function formatInboundContent(data) {
     return data.segments.map((seg) => {
@@ -290,19 +299,6 @@ export function isMentioned(data, selfId) {
 export function formatInboundMessageId(data) {
     return `${data.message_scene}:${data.peer_id}:${data.message_seq}`;
 }
-export function parseSendTarget(target) {
-    const sep = target.indexOf(':');
-    if (sep <= 0) {
-        return { message_type: 'private', id: target };
-    }
-    const head = target.slice(0, sep);
-    const rest = target.slice(sep + 1);
-    if (head === 'group')
-        return { message_type: 'group', id: rest };
-    if (head === 'private')
-        return { message_type: 'private', id: rest };
-    return { message_type: 'private', id: target };
-}
 /**
  * 解析 image/audio/video 段的投递 uri（canonical MediaRef 唯一来源）：
  * - kind=url → http(s):// 直发；
@@ -432,13 +428,12 @@ export function formatOutboundSegments(payload) {
     }
     return out.length ? out : [{ type: 'text', data: { text: '' } }];
 }
-export function buildSendAction(target, message) {
-    const parsed = parseSendTarget(target);
-    if (parsed.message_type === 'group') {
+export function buildSendAction(conversation, message) {
+    if (conversation.kind === 'group') {
         return {
             action: 'send_group_message',
             params: {
-                group_id: parseInt(parsed.id, 10),
+                group_id: parseInt(conversation.id, 10),
                 message,
             },
         };
@@ -446,18 +441,20 @@ export function buildSendAction(target, message) {
     return {
         action: 'send_private_message',
         params: {
-            user_id: parseInt(parsed.id, 10),
+            user_id: parseInt(conversation.id, 10),
             message,
         },
     };
 }
-/** message_seq result → gateway message id */
-export function formatOutboundMessageId(target, messageSeq) {
+/**
+ * message_seq result → gateway message id（`scene:peer:seq` 复合格式，
+ * 与 formatInboundMessageId 同源，仅供 recall 链在本端点边界内解析）。
+ */
+export function formatOutboundMessageId(conversation, messageSeq) {
     if (messageSeq == null)
         return '';
-    const parsed = parseSendTarget(target);
-    const scene = parsed.message_type === 'group' ? 'group' : 'friend';
-    return `${scene}:${parsed.id}:${messageSeq}`;
+    const scene = conversation.kind === 'group' ? 'group' : 'friend';
+    return `${scene}:${conversation.id}:${messageSeq}`;
 }
 export function parseMilkyMessageId(msgId) {
     const parts = msgId.split(':');

package/lib/sse-endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * Milky SSE client endpoint — GET text/event-stream on /event.
  */
-import { type EndpointInstance, type EndpointManagement } from '@zhin.js/adapter';
+import { type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { callApi, type MilkyEvent, type MilkySseConfig } from './protocol.js';
@@ -28,10 +28,7 @@ export declare class MilkySseEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     recallMessage(id: string): Promise<void>;
     kickMember(groupId: number, userId: number, rejectAddRequest?: boolean): Promise<boolean>;

package/lib/sse-endpoint.js

@@ -5,7 +5,7 @@ import { createEndpointLifecycle, } from '@zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
-import { buildSendAction, buildSseConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+import { buildSendAction, buildSseConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatOutboundMessageId, formatOutboundSegments, isMentioned, milkyInboundConversation, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 import { openSseStream } from './sse-client.js';
 const logger = getLogger('milky');
 export class MilkySseEndpoint {
@@ -58,15 +58,15 @@ export class MilkySseEndpoint {
         this.#stream?.close();
         this.#stream = undefined;
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
-        const { action, params } = buildSendAction(target, message);
+        const { action, params } = buildSendAction(conversation, message);
         const data = await this.callApi(action, params);
-        const messageId = formatOutboundMessageId(target, data?.message_seq);
+        const messageId = formatOutboundMessageId(conversation, data?.message_seq);
         logger.debug(formatCompact({
             op: 'milky_send',
             endpoint: this.#options.config.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
             messageId,
             mode: 'sse',
         }));
@@ -159,19 +159,19 @@ export class MilkySseEndpoint {
         };
     }
     #admitMessage(data, event) {
-        const target = formatInboundTarget(data);
+        const conversation = milkyInboundConversation(String(this.#options.id), data);
+        const target = `${conversation.kind}:${conversation.id}`;
         const content = formatInboundContent(data);
         const segments = formatInboundSegments(data);
         const audioUrl = extractInboundAudioUrl(data);
         const nickname = senderNickname(data);
         const mentioned = isMentioned(data, event.self_id);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: formatInboundMessageId(data) },
             content,
             segments,
             sender: String(data.sender_id),
-            id: formatInboundMessageId(data),
             metadata: Object.freeze({
                 message_scene: data.message_scene,
                 peer_id: String(data.peer_id),

package/lib/webhook-endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -18,10 +18,7 @@ export declare class MilkyWebhookEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     recallMessage(id: string): Promise<void>;
     kickMember(groupId: number, userId: number, rejectAddRequest?: boolean): Promise<boolean>;

package/lib/webhook-endpoint.js

@@ -2,7 +2,7 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import { readRequestBody, verifyMilkyAccessToken } from './milky-auth.js';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
-import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatOutboundMessageId, formatOutboundSegments, isMentioned, milkyInboundConversation, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 const logger = getLogger('milky');
 export class MilkyWebhookEndpoint {
     #options;
@@ -44,15 +44,15 @@ export class MilkyWebhookEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
-        const { action, params } = buildSendAction(target, message);
+        const { action, params } = buildSendAction(conversation, message);
         const data = await this.callApi(action, params);
-        const messageId = formatOutboundMessageId(target, data?.message_seq);
+        const messageId = formatOutboundMessageId(conversation, data?.message_seq);
         logger.debug(formatCompact({
             op: 'milky_send',
             endpoint: this.#options.config.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
             messageId,
         }));
         return messageId;
@@ -144,19 +144,19 @@ export class MilkyWebhookEndpoint {
         };
     }
     #admitMessage(data, event) {
-        const target = formatInboundTarget(data);
+        const conversation = milkyInboundConversation(String(this.#options.id), data);
+        const target = `${conversation.kind}:${conversation.id}`;
         const content = formatInboundContent(data);
         const segments = formatInboundSegments(data);
         const audioUrl = extractInboundAudioUrl(data);
         const nickname = senderNickname(data);
         const mentioned = isMentioned(data, event.self_id);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: formatInboundMessageId(data) },
             content,
             segments,
             sender: String(data.sender_id),
-            id: formatInboundMessageId(data),
             metadata: Object.freeze({
                 message_scene: data.message_scene,
                 peer_id: String(data.peer_id),

package/lib/ws-endpoint.d.ts

@@ -1,4 +1,4 @@
-import { type EndpointInstance, type EndpointManagement } from '@zhin.js/adapter';
+import { type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { callApi, type MilkyEvent, type MilkyWsConfig } from './protocol.js';
@@ -18,10 +18,7 @@ export declare class MilkyWsEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Public API for agent tools / callers. */
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     recallMessage(id: string): Promise<void>;

package/lib/ws-endpoint.js

@@ -6,7 +6,7 @@ import { createEndpointLifecycle, } from '@zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
-import { buildSendAction, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+import { buildSendAction, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatOutboundMessageId, formatOutboundSegments, isMentioned, milkyInboundConversation, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 const logger = getLogger('milky');
 const WS_OPEN = 1;
 export class MilkyWsEndpoint {
@@ -66,15 +66,15 @@ export class MilkyWsEndpoint {
             this.#ws = undefined;
         }
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
-        const { action, params } = buildSendAction(target, message);
+        const { action, params } = buildSendAction(conversation, message);
         const data = await this.callApi(action, params);
-        const messageId = formatOutboundMessageId(target, data?.message_seq);
+        const messageId = formatOutboundMessageId(conversation, data?.message_seq);
         logger.debug(formatCompact({
             op: 'milky_send',
             endpoint: this.#options.config.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
             messageId,
         }));
         return messageId;
@@ -168,19 +168,19 @@ export class MilkyWsEndpoint {
         };
     }
     #admitMessage(data, event) {
-        const target = formatInboundTarget(data);
+        const conversation = milkyInboundConversation(String(this.#options.id), data);
+        const target = `${conversation.kind}:${conversation.id}`;
         const content = formatInboundContent(data);
         const segments = formatInboundSegments(data);
         const audioUrl = extractInboundAudioUrl(data);
         const nickname = senderNickname(data);
         const mentioned = isMentioned(data, event.self_id);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: formatInboundMessageId(data) },
             content,
             segments,
             sender: String(data.sender_id),
-            id: formatInboundMessageId(data),
             metadata: Object.freeze({
                 message_scene: data.message_scene,
                 peer_id: String(data.peer_id),

package/lib/wss-endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -18,10 +18,7 @@ export declare class MilkyWssEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     recallMessage(id: string): Promise<void>;
     kickMember(groupId: number, userId: number, rejectAddRequest?: boolean): Promise<boolean>;

package/lib/wss-endpoint.js

@@ -6,7 +6,7 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import { verifyMilkyAccessToken } from './milky-auth.js';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
-import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatOutboundMessageId, formatOutboundSegments, isMentioned, milkyInboundConversation, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 const logger = getLogger('milky');
 const WS_OPEN = 1;
 export class MilkyWssEndpoint {
@@ -66,15 +66,15 @@ export class MilkyWssEndpoint {
         }
         this.#started = false;
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
-        const { action, params } = buildSendAction(target, message);
+        const { action, params } = buildSendAction(conversation, message);
         const data = await this.callApi(action, params);
-        const messageId = formatOutboundMessageId(target, data?.message_seq);
+        const messageId = formatOutboundMessageId(conversation, data?.message_seq);
         logger.debug(formatCompact({
             op: 'milky_send',
             endpoint: this.#options.config.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
             messageId,
         }));
         return messageId;
@@ -166,19 +166,19 @@ export class MilkyWssEndpoint {
         };
     }
     #admitMessage(data, event) {
-        const target = formatInboundTarget(data);
+        const conversation = milkyInboundConversation(String(this.#options.id), data);
+        const target = `${conversation.kind}:${conversation.id}`;
         const content = formatInboundContent(data);
         const segments = formatInboundSegments(data);
         const audioUrl = extractInboundAudioUrl(data);
         const nickname = senderNickname(data);
         const mentioned = isMentioned(data, event.self_id);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: formatInboundMessageId(data) },
             content,
             segments,
             sender: String(data.sender_id),
-            id: formatInboundMessageId(data),
             metadata: Object.freeze({
                 message_scene: data.message_scene,
                 peer_id: String(data.peer_id),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-milky",
-  "version": "6.0.2",
+  "version": "6.0.3",
   "description": "Zhin.js Milky adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -40,12 +40,13 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -53,16 +54,16 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/host-http": "1.0.5"
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/host-http": "1.0.6"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/src/index.ts

@@ -5,15 +5,11 @@ export {
   callApi,
   extractInboundAudioUrl,
   formatInboundContent,
-  formatInboundMessageId,
-  formatInboundTarget,
-  formatOutboundMessageId,
   formatOutboundSegments,
   isMentioned,
   isMessageReceiveEvent,
+  milkyInboundConversation,
   parseMessageReceiveData,
-  parseMilkyMessageId,
-  parseSendTarget,
   resolveMilkyConfig,
   senderNickname,
   type MilkyAdapterConfig,
@@ -30,7 +26,6 @@ export {
   type MilkyWireSegment,
   type MilkyWsConfig,
   type MilkyWssConfig,
-  type ParsedSendTarget,
   type ResolvedMilkyConfig,
 } from './protocol.js';
 

package/src/protocol.ts

@@ -6,6 +6,7 @@
 
 import { isMediaRef } from '@zhin.js/core';
 import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('milky');
@@ -116,11 +117,6 @@ export interface MilkyOutgoingSegment {
   data: Record<string, unknown>;
 }
 
-export interface ParsedSendTarget {
-  readonly message_type: 'private' | 'group';
-  readonly id: string;
-}
-
 export interface MilkyApiClientOptions {
   readonly baseUrl: string;
   readonly access_token?: string;
@@ -261,10 +257,22 @@ export function isMessageReceiveEvent(
   return parseMessageReceiveData(event) != null;
 }
 
-/** Gateway reply target：`private:uid` / `group:gid` */
-export function formatInboundTarget(data: MilkyIncomingMessage): string {
-  const isGroup = data.message_scene === 'group';
-  return `${isGroup ? 'group' : 'private'}:${data.peer_id}`;
+/**
+ * 入站归一化 → ConversationRef：`friend`（私聊）→ `private`；`group` → `group`；
+ * `temp`（群临时会话）→ 群容器内的 `private` 会话（parent = 来源群）。
+ */
+export function milkyInboundConversation(
+  endpointId: string,
+  data: MilkyIncomingMessage,
+): ConversationRef {
+  return {
+    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+    kind: data.message_scene === 'group' ? 'group' : 'private',
+    id: String(data.peer_id),
+    ...(data.message_scene === 'temp' && data.group
+      ? { parent: { kind: 'group' as const, id: String(data.group.group_id) } }
+      : {}),
+  };
 }
 
 export function formatInboundContent(data: MilkyIncomingMessage): string {
@@ -427,18 +435,6 @@ export function formatInboundMessageId(data: MilkyIncomingMessage): string {
   return `${data.message_scene}:${data.peer_id}:${data.message_seq}`;
 }
 
-export function parseSendTarget(target: string): ParsedSendTarget {
-  const sep = target.indexOf(':');
-  if (sep <= 0) {
-    return { message_type: 'private', id: target };
-  }
-  const head = target.slice(0, sep);
-  const rest = target.slice(sep + 1);
-  if (head === 'group') return { message_type: 'group', id: rest };
-  if (head === 'private') return { message_type: 'private', id: rest };
-  return { message_type: 'private', id: target };
-}
-
 /**
  * 解析 image/audio/video 段的投递 uri（canonical MediaRef 唯一来源）：
  * - kind=url → http(s):// 直发；
@@ -570,15 +566,14 @@ export function formatOutboundSegments(payload: unknown): MilkyOutgoingSegment[]
 }
 
 export function buildSendAction(
-  target: string,
+  conversation: ConversationRef,
   message: MilkyOutgoingSegment[],
 ): { action: string; params: Record<string, unknown> } {
-  const parsed = parseSendTarget(target);
-  if (parsed.message_type === 'group') {
+  if (conversation.kind === 'group') {
     return {
       action: 'send_group_message',
       params: {
-        group_id: parseInt(parsed.id, 10),
+        group_id: parseInt(conversation.id, 10),
         message,
       },
     };
@@ -586,21 +581,23 @@ export function buildSendAction(
   return {
     action: 'send_private_message',
     params: {
-      user_id: parseInt(parsed.id, 10),
+      user_id: parseInt(conversation.id, 10),
       message,
     },
   };
 }
 
-/** message_seq result → gateway message id */
+/**
+ * message_seq result → gateway message id（`scene:peer:seq` 复合格式，
+ * 与 formatInboundMessageId 同源，仅供 recall 链在本端点边界内解析）。
+ */
 export function formatOutboundMessageId(
-  target: string,
+  conversation: ConversationRef,
   messageSeq: number | undefined,
 ): string {
   if (messageSeq == null) return '';
-  const parsed = parseSendTarget(target);
-  const scene = parsed.message_type === 'group' ? 'group' : 'friend';
-  return `${scene}:${parsed.id}:${messageSeq}`;
+  const scene = conversation.kind === 'group' ? 'group' : 'friend';
+  return `${scene}:${conversation.id}:${messageSeq}`;
 }
 
 export function parseMilkyMessageId(

package/src/sse-endpoint.ts

@@ -7,6 +7,7 @@ import {
   type EndpointInstance,
   type EndpointLifecycle,
   type EndpointManagement,
+  type EndpointSendRequest,
 } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -21,10 +22,10 @@ import {
   formatInboundContent,
   formatInboundMessageId,
   formatInboundSegments,
-  formatInboundTarget,
   formatOutboundMessageId,
   formatOutboundSegments,
   isMentioned,
+  milkyInboundConversation,
   parseMessageReceiveData,
   parseMilkyMessageId,
   senderNickname,
@@ -106,15 +107,15 @@ export class MilkySseEndpoint implements EndpointInstance {
     this.#stream = undefined;
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
-    const { action, params } = buildSendAction(target, message);
+    const { action, params } = buildSendAction(conversation, message);
     const data = await this.callApi(action, params) as { message_seq?: number } | undefined;
-    const messageId = formatOutboundMessageId(target, data?.message_seq);
+    const messageId = formatOutboundMessageId(conversation, data?.message_seq);
     logger.debug(formatCompact({
       op: 'milky_send',
       endpoint: this.#options.config.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId,
       mode: 'sse',
     }));
@@ -218,19 +219,19 @@ export class MilkySseEndpoint implements EndpointInstance {
   }
 
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
-    const target = formatInboundTarget(data);
+    const conversation = milkyInboundConversation(String(this.#options.id), data);
+    const target = `${conversation.kind}:${conversation.id}`;
     const content = formatInboundContent(data);
     const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: formatInboundMessageId(data) },
       content,
       segments,
       sender: String(data.sender_id),
-      id: formatInboundMessageId(data),
       metadata: Object.freeze({
         message_scene: data.message_scene,
         peer_id: String(data.peer_id),

package/src/webhook-endpoint.ts

@@ -2,7 +2,11 @@
  * Milky webhook endpoint — httpHostToken POST inbound + baseUrl HTTP API outbound.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type {
+  EndpointInstance,
+  EndpointManagement,
+  EndpointSendRequest,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -17,10 +21,10 @@ import {
   formatInboundContent,
   formatInboundMessageId,
   formatInboundSegments,
-  formatInboundTarget,
   formatOutboundMessageId,
   formatOutboundSegments,
   isMentioned,
+  milkyInboundConversation,
   parseMessageReceiveData,
   parseMilkyMessageId,
   senderNickname,
@@ -83,15 +87,15 @@ export class MilkyWebhookEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
-    const { action, params } = buildSendAction(target, message);
+    const { action, params } = buildSendAction(conversation, message);
     const data = await this.callApi(action, params) as { message_seq?: number } | undefined;
-    const messageId = formatOutboundMessageId(target, data?.message_seq);
+    const messageId = formatOutboundMessageId(conversation, data?.message_seq);
     logger.debug(formatCompact({
       op: 'milky_send',
       endpoint: this.#options.config.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId,
     }));
     return messageId;
@@ -194,19 +198,19 @@ export class MilkyWebhookEndpoint implements EndpointInstance {
   }
 
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
-    const target = formatInboundTarget(data);
+    const conversation = milkyInboundConversation(String(this.#options.id), data);
+    const target = `${conversation.kind}:${conversation.id}`;
     const content = formatInboundContent(data);
     const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: formatInboundMessageId(data) },
       content,
       segments,
       sender: String(data.sender_id),
-      id: formatInboundMessageId(data),
       metadata: Object.freeze({
         message_scene: data.message_scene,
         peer_id: String(data.peer_id),

package/src/ws-endpoint.ts

@@ -8,6 +8,7 @@ import {
   type EndpointInstance,
   type EndpointLifecycle,
   type EndpointManagement,
+  type EndpointSendRequest,
 } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -22,10 +23,10 @@ import {
   formatInboundContent,
   formatInboundMessageId,
   formatInboundSegments,
-  formatInboundTarget,
   formatOutboundMessageId,
   formatOutboundSegments,
   isMentioned,
+  milkyInboundConversation,
   parseMessageReceiveData,
   parseMilkyMessageId,
   senderNickname,
@@ -109,15 +110,15 @@ export class MilkyWsEndpoint implements EndpointInstance {
     }
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
-    const { action, params } = buildSendAction(target, message);
+    const { action, params } = buildSendAction(conversation, message);
     const data = await this.callApi(action, params) as { message_seq?: number } | undefined;
-    const messageId = formatOutboundMessageId(target, data?.message_seq);
+    const messageId = formatOutboundMessageId(conversation, data?.message_seq);
     logger.debug(formatCompact({
       op: 'milky_send',
       endpoint: this.#options.config.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId,
     }));
     return messageId;
@@ -222,19 +223,19 @@ export class MilkyWsEndpoint implements EndpointInstance {
   }
 
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
-    const target = formatInboundTarget(data);
+    const conversation = milkyInboundConversation(String(this.#options.id), data);
+    const target = `${conversation.kind}:${conversation.id}`;
     const content = formatInboundContent(data);
     const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: formatInboundMessageId(data) },
       content,
       segments,
       sender: String(data.sender_id),
-      id: formatInboundMessageId(data),
       metadata: Object.freeze({
         message_scene: data.message_scene,
         peer_id: String(data.peer_id),

package/src/wss-endpoint.ts

@@ -2,7 +2,11 @@
  * Milky reverse WSS endpoint — httpHostToken WS upgrade inbound + baseUrl HTTP API outbound.
  */
 import { clearInterval } from 'node:timers';
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type {
+  EndpointInstance,
+  EndpointManagement,
+  EndpointSendRequest,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -17,10 +21,10 @@ import {
   formatInboundContent,
   formatInboundMessageId,
   formatInboundSegments,
-  formatInboundTarget,
   formatOutboundMessageId,
   formatOutboundSegments,
   isMentioned,
+  milkyInboundConversation,
   parseMessageReceiveData,
   parseMilkyMessageId,
   senderNickname,
@@ -102,15 +106,15 @@ export class MilkyWssEndpoint implements EndpointInstance {
     this.#started = false;
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
-    const { action, params } = buildSendAction(target, message);
+    const { action, params } = buildSendAction(conversation, message);
     const data = await this.callApi(action, params) as { message_seq?: number } | undefined;
-    const messageId = formatOutboundMessageId(target, data?.message_seq);
+    const messageId = formatOutboundMessageId(conversation, data?.message_seq);
     logger.debug(formatCompact({
       op: 'milky_send',
       endpoint: this.#options.config.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId,
     }));
     return messageId;
@@ -213,19 +217,19 @@ export class MilkyWssEndpoint implements EndpointInstance {
   }
 
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
-    const target = formatInboundTarget(data);
+    const conversation = milkyInboundConversation(String(this.#options.id), data);
+    const target = `${conversation.kind}:${conversation.id}`;
     const content = formatInboundContent(data);
     const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: formatInboundMessageId(data) },
       content,
       segments,
       sender: String(data.sender_id),
-      id: formatInboundMessageId(data),
       metadata: Object.freeze({
         message_scene: data.message_scene,
         peer_id: String(data.peer_id),