@zhin.js/adapter-onebot12 5.0.0 → 5.0.2

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @zhin.js/adapter-onebot12
 
+## 5.0.2
+
+### 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@6.0.2
+
+## 5.0.1
+
+### Patch Changes
+
+- Updated dependencies [c8f4d45]
+  - @zhin.js/plugin-runtime@1.1.2
+  - @zhin.js/host-http@1.0.5
+  - @zhin.js/adapter@1.1.4
+  - @zhin.js/command@1.0.6
+  - @zhin.js/core@1.5.1
+  - zhin.js@6.0.1
+
 ## 5.0.0
 
 ### Patch Changes

package/README.md

@@ -8,7 +8,7 @@ Zhin.js [OneBot 12](https://12.onebot.dev/) 适配器（Plugin Runtime）。默
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - **正向 WebSocket**（`connection: ws`）：应用连 OneBot 实现的 WS 服务器
 - `access_token` 鉴权（Bearer + query）
-- 入站经 `messageGatewayToken`；出站 `send({ target, payload })`
+- 入站经 `messageGatewayToken`；出站 `send({ conversation, payload })`
 
 ## 安装
 
@@ -23,8 +23,8 @@ pnpm add @zhin.js/adapter-onebot12
 - `@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 })` → WS `send_message`（payload 已由 gateway/core 渲染；无 segment-mapper）
+入站：`gateway.receive({ conversation: ConversationRef, message: { conversation, id }, content, sender, metadata })`  
+出站：`send({ conversation, payload })` → WS `send_message`（payload 已由 gateway/core 渲染；无 segment-mapper）
 
 ## 最小配置
 

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, parseSendTarget, resolveOneBot12Config, senderNickname, senderUserId, uploadOneBot12MediaSegments, type OneBot12ActionRequest, type OneBot12ActionResponse, type OneBot12AdapterConfig, type OneBot12CallAction, type OneBot12ConfigBase, type OneBot12EndpointConfig, type OneBot12Event, type OneBot12HttpOptions, type OneBot12Segment, type OneBot12Self, type OneBot12WebhookConfig, type OneBot12WireSegment, type OneBot12WsConfig, type OneBot12WssConfig, type ParsedSendTarget, type ResolvedOneBot12Config, } from './protocol.js';
+export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, onebot12InboundConversation, resolveOneBot12Config, senderNickname, senderUserId, uploadOneBot12MediaSegments, type OneBot12ActionRequest, type OneBot12ActionResponse, type OneBot12AdapterConfig, type OneBot12CallAction, type OneBot12ConfigBase, type OneBot12EndpointConfig, type OneBot12Event, type OneBot12HttpOptions, type OneBot12Segment, type OneBot12Self, type OneBot12WebhookConfig, type OneBot12WireSegment, type OneBot12WsConfig, type OneBot12WssConfig, type ResolvedOneBot12Config, } from './protocol.js';
 export { OneBot12WebhookEndpoint, type OneBot12WebhookEndpointOptions, } from './webhook.js';
 export { OneBot12WsEndpoint, type OneBot12WsEndpointOptions, } from './ws-endpoint.js';
 export { OneBot12WssEndpoint, type OneBot12WssEndpointOptions, } from './wss-endpoint.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatInboundTarget, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, parseSendTarget, resolveOneBot12Config, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
+export { buildSendMessageParams, buildWsConnectOptions, callOneBot12Action, formatInboundContent, formatOutboundSegments, getChannelId, isBotMentioned, isMessageEvent, mediaRefToOneBot12Fields, mediaRefToOneBot12UploadParams, onebot12InboundConversation, resolveOneBot12Config, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 export { OneBot12WebhookEndpoint, } from './webhook.js';
 export { OneBot12WsEndpoint, } from './ws-endpoint.js';
 export { OneBot12WssEndpoint, } from './wss-endpoint.js';

package/lib/protocol.d.ts

@@ -4,6 +4,7 @@
  * Spec: https://12.onebot.dev/
  */
 import { type MediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
 /** Transitional legacy endpoint row (`endpoints[]` with `context: onebot12`). */
 export interface OneBot12LegacyEndpointRow {
     readonly context?: string;
@@ -100,11 +101,6 @@ export interface OneBot12WireSegment {
     readonly type: string;
     readonly data?: Record<string, unknown>;
 }
-export interface ParsedSendTarget {
-    readonly detail_type: 'private' | 'group' | 'channel';
-    readonly id: string;
-    readonly guild_id?: string;
-}
 export declare function resolveOneBot12Config(config?: OneBot12AdapterConfig): ResolvedOneBot12Config;
 /** 判断是否为消息事件（type=message） */
 export declare function isMessageEvent(ev: OneBot12Event): ev is OneBot12Event & {
@@ -114,10 +110,11 @@ export declare function isMessageEvent(ev: OneBot12Event): ev is OneBot12Event &
 /** 从事件得到场景 id：私聊 user_id，群 group_id，频道 channel_id 或 guild_id:channel_id */
 export declare function getChannelId(ev: OneBot12Event): string;
 /**
- * Gateway reply target：`detail_type:channelId`，便于 send() 还原动作参数。
+ * 入站归一化 → ConversationRef：`detail_type` 直映射 kind；channel 的 guild 容器
+ * 进 `parent`（kind 'channel'）；私聊临时会话（private 事件携带 group_id）映射为
+ * group 容器内的 private 会话。
  */
-export declare function formatInboundTarget(ev: OneBot12Event): string;
-export declare function parseSendTarget(target: string): ParsedSendTarget;
+export declare function onebot12InboundConversation(endpointId: string, ev: OneBot12Event): ConversationRef;
 /** Build inbound text for MessageGateway.receive */
 export declare function formatInboundContent(ev: OneBot12Event): string;
 /**
@@ -158,7 +155,11 @@ export declare function mediaRefToOneBot12UploadParams(segmentType: string, data
  * 上传失败保留原段（降级扩展字段透传）并回调 onUploadFailed。
  */
 export declare function uploadOneBot12MediaSegments(payload: unknown, callAction: OneBot12CallAction, onUploadFailed?: (error: unknown) => void): Promise<unknown>;
-export declare function buildSendMessageParams(target: string, message: OneBot12Segment[]): Record<string, unknown>;
+/**
+ * 结构化会话 → OB12 `send_message` 动作参数：kind 直映射 detail_type；
+ * channel 的 guild 容器取自 `conversation.parent`（kind 'channel'）。
+ */
+export declare function buildSendMessageParams(conversation: ConversationRef, message: OneBot12Segment[]): Record<string, unknown>;
 /**
  * 向 OneBot 实现发送动作请求（HTTP POST），返回动作响应。
  * 供 webhook 出站与纯协议测试使用；WS 路径走 WebSocket echo 请求。

package/lib/protocol.js

@@ -77,36 +77,31 @@ export function getChannelId(ev) {
     return ev.user_id ?? ev.group_id ?? '';
 }
 /**
- * Gateway reply target：`detail_type:channelId`，便于 send() 还原动作参数。
+ * 入站归一化 → ConversationRef：`detail_type` 直映射 kind；channel 的 guild 容器
+ * 进 `parent`（kind 'channel'）；私聊临时会话（private 事件携带 group_id）映射为
+ * group 容器内的 private 会话。
  */
-export function formatInboundTarget(ev) {
-    const detail = ev.detail_type === 'private' || ev.detail_type === 'group' || ev.detail_type === 'channel'
-        ? ev.detail_type
-        : 'private';
-    return `${detail}:${getChannelId(ev)}`;
-}
-export function parseSendTarget(target) {
-    const sep = target.indexOf(':');
-    if (sep <= 0) {
-        return { detail_type: 'private', id: target };
-    }
-    const head = target.slice(0, sep);
-    const rest = target.slice(sep + 1);
-    if (head === 'private' || head === 'group') {
-        return { detail_type: head, id: rest };
-    }
-    if (head === 'channel') {
-        const guildSep = rest.indexOf(':');
-        if (guildSep > 0) {
-            return {
-                detail_type: 'channel',
-                guild_id: rest.slice(0, guildSep),
-                id: rest.slice(guildSep + 1),
-            };
-        }
-        return { detail_type: 'channel', id: rest };
+export function onebot12InboundConversation(endpointId, ev) {
+    const endpoint = { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId };
+    if (ev.detail_type === 'group' && ev.group_id) {
+        return { endpoint, kind: 'group', id: ev.group_id };
     }
-    return { detail_type: 'private', id: target };
+    if (ev.detail_type === 'channel' && ev.channel_id) {
+        return {
+            endpoint,
+            kind: 'channel',
+            id: ev.channel_id,
+            ...(ev.guild_id ? { parent: { kind: 'channel', id: ev.guild_id } } : {}),
+        };
+    }
+    return {
+        endpoint,
+        kind: 'private',
+        id: ev.user_id ?? ev.group_id ?? '',
+        ...(ev.detail_type === 'private' && ev.group_id
+            ? { parent: { kind: 'group', id: ev.group_id } }
+            : {}),
+    };
 }
 /** Build inbound text for MessageGateway.receive */
 export function formatInboundContent(ev) {
@@ -347,22 +342,25 @@ export async function uploadOneBot12MediaSegments(payload, callAction, onUploadF
     }
     return uploadOneMediaSegment(payload, callAction, onUploadFailed);
 }
-export function buildSendMessageParams(target, message) {
-    const parsed = parseSendTarget(target);
+/**
+ * 结构化会话 → OB12 `send_message` 动作参数：kind 直映射 detail_type；
+ * channel 的 guild 容器取自 `conversation.parent`（kind 'channel'）。
+ */
+export function buildSendMessageParams(conversation, message) {
     const params = {
         message,
-        detail_type: parsed.detail_type,
+        detail_type: conversation.kind,
     };
-    if (parsed.detail_type === 'private') {
-        params.user_id = parsed.id;
+    if (conversation.kind === 'private') {
+        params.user_id = conversation.id;
     }
-    else if (parsed.detail_type === 'group') {
-        params.group_id = parsed.id;
+    else if (conversation.kind === 'group') {
+        params.group_id = conversation.id;
     }
     else {
-        params.channel_id = parsed.id;
-        if (parsed.guild_id)
-            params.guild_id = parsed.guild_id;
+        params.channel_id = conversation.id;
+        if (conversation.parent?.kind === 'channel')
+            params.guild_id = conversation.parent.id;
     }
     return params;
 }

package/lib/webhook.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 OneBot12WebhookEndpoint 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 management surface / callers；webhook 模式走 api_url。 */
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     admit(ev: OneBot12Event): void;

package/lib/webhook.js

@@ -1,6 +1,6 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
-import { buildSendMessageParams, callOneBot12Action, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
+import { buildSendMessageParams, callOneBot12Action, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 const logger = getLogger('onebot12');
 export class OneBot12WebhookEndpoint {
@@ -48,7 +48,7 @@ export class OneBot12WebhookEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => this.callApi(action, params), (error) => {
             logger.warn(formatCompact({
                 op: 'onebot12_upload_failed',
@@ -57,13 +57,14 @@ export class OneBot12WebhookEndpoint {
             }));
         });
         const message = formatOutboundSegments(materialized);
-        const params = buildSendMessageParams(target, message);
+        const params = buildSendMessageParams(conversation, message);
         const data = await this.callApi('send_message', params);
         const messageId = data?.message_id ?? '';
         logger.debug(formatCompact({
             op: 'onebot12_send',
             endpoint: this.#options.config.name,
-            target,
+            kind: conversation.kind,
+            conversationId: conversation.id,
             messageId,
         }));
         return messageId;
@@ -80,16 +81,15 @@ export class OneBot12WebhookEndpoint {
     admit(ev) {
         if (!this.#open || !isMessageEvent(ev))
             return;
-        const target = formatInboundTarget(ev);
+        const conversation = onebot12InboundConversation(String(this.#options.id), ev);
         const content = formatInboundContent(ev);
         const nickname = senderNickname(ev);
         const mentioned = isBotMentioned(ev);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: ev.message_id },
             content,
             sender: senderUserId(ev),
-            id: ev.message_id,
             metadata: Object.freeze({
                 detail_type: ev.detail_type,
                 user_id: ev.user_id,
@@ -104,7 +104,8 @@ export class OneBot12WebhookEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'onebot12_gateway_receive_failed',
-                target,
+                kind: conversation.kind,
+                conversationId: conversation.id,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

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 { type OneBot12Event, type OneBot12WsConfig } from './protocol.js';
@@ -17,10 +17,7 @@ export declare class OneBot12WsEndpoint 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>;
     recallMessage(messageId: string): Promise<void>;
     /** Public API for management surface / callers. */
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;

package/lib/ws-endpoint.js

@@ -6,7 +6,7 @@ import { clearTimeout } from 'node:timers';
 import { createEndpointLifecycle, } from '@zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
-import { buildSendMessageParams, buildWsConnectOptions, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
+import { buildSendMessageParams, buildWsConnectOptions, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 import { WS_OPEN, } from './ws-types.js';
 const logger = getLogger('onebot12');
 export class OneBot12WsEndpoint {
@@ -69,7 +69,7 @@ export class OneBot12WsEndpoint {
         this.#pending.clear();
         this.#ws = undefined;
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => this.callApi(action, params), (error) => {
             logger.warn(formatCompact({
                 op: 'onebot12_upload_failed',
@@ -78,13 +78,14 @@ export class OneBot12WsEndpoint {
             }));
         });
         const message = formatOutboundSegments(materialized);
-        const params = buildSendMessageParams(target, message);
+        const params = buildSendMessageParams(conversation, message);
         const data = await this.#callAction('send_message', params);
         const messageId = data?.message_id ?? '';
         logger.debug(formatCompact({
             op: 'onebot12_send',
             endpoint: this.#options.config.name,
-            target,
+            kind: conversation.kind,
+            conversationId: conversation.id,
             messageId,
         }));
         return messageId;
@@ -102,16 +103,15 @@ export class OneBot12WsEndpoint {
     admit(ev) {
         if (!this.#open || !isMessageEvent(ev))
             return;
-        const target = formatInboundTarget(ev);
+        const conversation = onebot12InboundConversation(String(this.#options.id), ev);
         const content = formatInboundContent(ev);
         const nickname = senderNickname(ev);
         const mentioned = isBotMentioned(ev);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: ev.message_id },
             content,
             sender: senderUserId(ev),
-            id: ev.message_id,
             metadata: Object.freeze({
                 detail_type: ev.detail_type,
                 user_id: ev.user_id,
@@ -126,7 +126,8 @@ export class OneBot12WsEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'onebot12_gateway_receive_failed',
-                target,
+                kind: conversation.kind,
+                conversationId: conversation.id,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

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';
@@ -17,10 +17,7 @@ export declare class OneBot12WssEndpoint 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>;
     recallMessage(messageId: string): Promise<void>;
     /** Public API for management surface / callers. */
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;

package/lib/wss-endpoint.js

@@ -4,7 +4,7 @@
 import { clearInterval } from 'node:timers';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
-import { buildSendMessageParams, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
+import { buildSendMessageParams, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 import { WS_OPEN } from './ws-types.js';
 const logger = getLogger('onebot12');
@@ -75,7 +75,7 @@ export class OneBot12WssEndpoint {
         }
         this.#started = false;
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => this.callApi(action, params), (error) => {
             logger.warn(formatCompact({
                 op: 'onebot12_upload_failed',
@@ -84,7 +84,7 @@ export class OneBot12WssEndpoint {
             }));
         });
         const message = formatOutboundSegments(materialized);
-        const params = buildSendMessageParams(target, message);
+        const params = buildSendMessageParams(conversation, message);
         const data = await this.#callAction('send_message', params);
         return data?.message_id ?? '';
     }
@@ -100,15 +100,14 @@ export class OneBot12WssEndpoint {
     admit(ev) {
         if (!this.#open || !isMessageEvent(ev))
             return;
-        const target = formatInboundTarget(ev);
+        const conversation = onebot12InboundConversation(String(this.#options.id), ev);
         const nickname = senderNickname(ev);
         const mentioned = isBotMentioned(ev);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: ev.message_id },
             content: formatInboundContent(ev),
             sender: senderUserId(ev),
-            id: ev.message_id,
             metadata: Object.freeze({
                 detail_type: ev.detail_type,
                 user_id: ev.user_id,
@@ -123,7 +122,8 @@ export class OneBot12WssEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'onebot12_gateway_receive_failed',
-                target,
+                kind: conversation.kind,
+                conversationId: conversation.id,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot12",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Zhin.js OneBot 12 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -40,25 +40,26 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.3",
-    "@zhin.js/command": "1.0.5",
-    "@zhin.js/core": "1.5.0",
-    "@zhin.js/host-http": "1.0.4",
+    "@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/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.1"
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "@zhin.js/im-contract": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.0.4"
+    "@zhin.js/host-http": "1.0.6"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.3",
-    "@zhin.js/core": "1.5.0",
-    "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "6.0.0"
+    "@zhin.js/adapter": "1.1.5",
+    "@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

@@ -3,14 +3,13 @@ export {
   buildWsConnectOptions,
   callOneBot12Action,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundSegments,
   getChannelId,
   isBotMentioned,
   isMessageEvent,
   mediaRefToOneBot12Fields,
   mediaRefToOneBot12UploadParams,
-  parseSendTarget,
+  onebot12InboundConversation,
   resolveOneBot12Config,
   senderNickname,
   senderUserId,
@@ -29,7 +28,6 @@ export {
   type OneBot12WireSegment,
   type OneBot12WsConfig,
   type OneBot12WssConfig,
-  type ParsedSendTarget,
   type ResolvedOneBot12Config,
 } from './protocol.js';
 

package/src/protocol.ts

@@ -4,6 +4,7 @@
  * Spec: https://12.onebot.dev/
  */
 import { isMediaRef, type MediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('onebot12');
@@ -118,12 +119,6 @@ export interface OneBot12WireSegment {
   readonly data?: Record<string, unknown>;
 }
 
-export interface ParsedSendTarget {
-  readonly detail_type: 'private' | 'group' | 'channel';
-  readonly id: string;
-  readonly guild_id?: string;
-}
-
 export function resolveOneBot12Config(config: OneBot12AdapterConfig = {}): ResolvedOneBot12Config {
   const entry = config.endpoints?.find((item) => item.context === 'onebot12');
   const connection = config.connection
@@ -204,37 +199,31 @@ export function getChannelId(ev: OneBot12Event): string {
 }
 
 /**
- * Gateway reply target：`detail_type:channelId`，便于 send() 还原动作参数。
+ * 入站归一化 → ConversationRef：`detail_type` 直映射 kind；channel 的 guild 容器
+ * 进 `parent`（kind 'channel'）；私聊临时会话（private 事件携带 group_id）映射为
+ * group 容器内的 private 会话。
  */
-export function formatInboundTarget(ev: OneBot12Event): string {
-  const detail = ev.detail_type === 'private' || ev.detail_type === 'group' || ev.detail_type === 'channel'
-    ? ev.detail_type
-    : 'private';
-  return `${detail}:${getChannelId(ev)}`;
-}
-
-export function parseSendTarget(target: string): ParsedSendTarget {
-  const sep = target.indexOf(':');
-  if (sep <= 0) {
-    return { detail_type: 'private', id: target };
-  }
-  const head = target.slice(0, sep);
-  const rest = target.slice(sep + 1);
-  if (head === 'private' || head === 'group') {
-    return { detail_type: head, id: rest };
+export function onebot12InboundConversation(endpointId: string, ev: OneBot12Event): ConversationRef {
+  const endpoint = { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId };
+  if (ev.detail_type === 'group' && ev.group_id) {
+    return { endpoint, kind: 'group', id: ev.group_id };
   }
-  if (head === 'channel') {
-    const guildSep = rest.indexOf(':');
-    if (guildSep > 0) {
-      return {
-        detail_type: 'channel',
-        guild_id: rest.slice(0, guildSep),
-        id: rest.slice(guildSep + 1),
-      };
-    }
-    return { detail_type: 'channel', id: rest };
+  if (ev.detail_type === 'channel' && ev.channel_id) {
+    return {
+      endpoint,
+      kind: 'channel',
+      id: ev.channel_id,
+      ...(ev.guild_id ? { parent: { kind: 'channel' as const, id: ev.guild_id } } : {}),
+    };
   }
-  return { detail_type: 'private', id: target };
+  return {
+    endpoint,
+    kind: 'private',
+    id: ev.user_id ?? ev.group_id ?? '',
+    ...(ev.detail_type === 'private' && ev.group_id
+      ? { parent: { kind: 'group' as const, id: ev.group_id } }
+      : {}),
+  };
 }
 
 /** Build inbound text for MessageGateway.receive */
@@ -501,22 +490,25 @@ export async function uploadOneBot12MediaSegments(
   return uploadOneMediaSegment(payload, callAction, onUploadFailed);
 }
 
+/**
+ * 结构化会话 → OB12 `send_message` 动作参数：kind 直映射 detail_type；
+ * channel 的 guild 容器取自 `conversation.parent`（kind 'channel'）。
+ */
 export function buildSendMessageParams(
-  target: string,
+  conversation: ConversationRef,
   message: OneBot12Segment[],
 ): Record<string, unknown> {
-  const parsed = parseSendTarget(target);
   const params: Record<string, unknown> = {
     message,
-    detail_type: parsed.detail_type,
+    detail_type: conversation.kind,
   };
-  if (parsed.detail_type === 'private') {
-    params.user_id = parsed.id;
-  } else if (parsed.detail_type === 'group') {
-    params.group_id = parsed.id;
+  if (conversation.kind === 'private') {
+    params.user_id = conversation.id;
+  } else if (conversation.kind === 'group') {
+    params.group_id = conversation.id;
   } else {
-    params.channel_id = parsed.id;
-    if (parsed.guild_id) params.guild_id = parsed.guild_id;
+    params.channel_id = conversation.id;
+    if (conversation.parent?.kind === 'channel') params.guild_id = conversation.parent.id;
   }
   return params;
 }

package/src/webhook.ts

@@ -2,7 +2,7 @@
  * OneBot12 HTTP webhook endpoint — POST inbound + api_url 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';
@@ -12,10 +12,10 @@ import {
   buildSendMessageParams,
   callOneBot12Action,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundSegments,
   isBotMentioned,
   isMessageEvent,
+  onebot12InboundConversation,
   senderNickname,
   senderUserId,
   uploadOneBot12MediaSegments,
@@ -83,7 +83,7 @@ export class OneBot12WebhookEndpoint 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 materialized = await uploadOneBot12MediaSegments(
       payload,
       (action, params) => this.callApi(action, params),
@@ -96,13 +96,14 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
       },
     );
     const message = formatOutboundSegments(materialized);
-    const params = buildSendMessageParams(target, message);
+    const params = buildSendMessageParams(conversation, message);
     const data = await this.callApi('send_message', params) as { message_id?: string } | undefined;
     const messageId = data?.message_id ?? '';
     logger.debug(formatCompact({
       op: 'onebot12_send',
       endpoint: this.#options.config.name,
-      target,
+      kind: conversation.kind,
+      conversationId: conversation.id,
       messageId,
     }));
     return messageId;
@@ -124,16 +125,15 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
 
   admit(ev: OneBot12Event): void {
     if (!this.#open || !isMessageEvent(ev)) return;
-    const target = formatInboundTarget(ev);
+    const conversation = onebot12InboundConversation(String(this.#options.id), ev);
     const content = formatInboundContent(ev);
     const nickname = senderNickname(ev);
     const mentioned = isBotMentioned(ev);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: ev.message_id },
       content,
       sender: senderUserId(ev),
-      id: ev.message_id,
       metadata: Object.freeze({
         detail_type: ev.detail_type,
         user_id: ev.user_id,
@@ -148,7 +148,8 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'onebot12_gateway_receive_failed',
-        target,
+        kind: conversation.kind,
+        conversationId: conversation.id,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/ws-endpoint.ts

@@ -9,6 +9,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';
@@ -18,10 +19,10 @@ import {
   buildSendMessageParams,
   buildWsConnectOptions,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundSegments,
   isBotMentioned,
   isMessageEvent,
+  onebot12InboundConversation,
   senderNickname,
   senderUserId,
   uploadOneBot12MediaSegments,
@@ -115,7 +116,7 @@ export class OneBot12WsEndpoint implements EndpointInstance {
     this.#ws = undefined;
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const materialized = await uploadOneBot12MediaSegments(
       payload,
       (action, params) => this.callApi(action, params),
@@ -128,13 +129,14 @@ export class OneBot12WsEndpoint implements EndpointInstance {
       },
     );
     const message = formatOutboundSegments(materialized);
-    const params = buildSendMessageParams(target, message);
+    const params = buildSendMessageParams(conversation, message);
     const data = await this.#callAction('send_message', params) as { message_id?: string } | undefined;
     const messageId = data?.message_id ?? '';
     logger.debug(formatCompact({
       op: 'onebot12_send',
       endpoint: this.#options.config.name,
-      target,
+      kind: conversation.kind,
+      conversationId: conversation.id,
       messageId,
     }));
     return messageId;
@@ -153,16 +155,15 @@ export class OneBot12WsEndpoint implements EndpointInstance {
   /** Test / internal: admit a parsed event when the endpoint is open. */
   admit(ev: OneBot12Event): void {
     if (!this.#open || !isMessageEvent(ev)) return;
-    const target = formatInboundTarget(ev);
+    const conversation = onebot12InboundConversation(String(this.#options.id), ev);
     const content = formatInboundContent(ev);
     const nickname = senderNickname(ev);
     const mentioned = isBotMentioned(ev);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: ev.message_id },
       content,
       sender: senderUserId(ev),
-      id: ev.message_id,
       metadata: Object.freeze({
         detail_type: ev.detail_type,
         user_id: ev.user_id,
@@ -177,7 +178,8 @@ export class OneBot12WsEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'onebot12_gateway_receive_failed',
-        target,
+        kind: conversation.kind,
+        conversationId: conversation.id,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/wss-endpoint.ts

@@ -2,7 +2,7 @@
  * OneBot12 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
 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';
@@ -11,10 +11,10 @@ import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import {
   buildSendMessageParams,
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundSegments,
   isBotMentioned,
   isMessageEvent,
+  onebot12InboundConversation,
   senderNickname,
   senderUserId,
   uploadOneBot12MediaSegments,
@@ -110,7 +110,7 @@ export class OneBot12WssEndpoint 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 materialized = await uploadOneBot12MediaSegments(
       payload,
       (action, params) => this.callApi(action, params),
@@ -123,7 +123,7 @@ export class OneBot12WssEndpoint implements EndpointInstance {
       },
     );
     const message = formatOutboundSegments(materialized);
-    const params = buildSendMessageParams(target, message);
+    const params = buildSendMessageParams(conversation, message);
     const data = await this.#callAction('send_message', params) as { message_id?: string } | undefined;
     return data?.message_id ?? '';
   }
@@ -140,15 +140,14 @@ export class OneBot12WssEndpoint implements EndpointInstance {
 
   admit(ev: OneBot12Event): void {
     if (!this.#open || !isMessageEvent(ev)) return;
-    const target = formatInboundTarget(ev);
+    const conversation = onebot12InboundConversation(String(this.#options.id), ev);
     const nickname = senderNickname(ev);
     const mentioned = isBotMentioned(ev);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: ev.message_id },
       content: formatInboundContent(ev),
       sender: senderUserId(ev),
-      id: ev.message_id,
       metadata: Object.freeze({
         detail_type: ev.detail_type,
         user_id: ev.user_id,
@@ -163,7 +162,8 @@ export class OneBot12WssEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'onebot12_gateway_receive_failed',
-        target,
+        kind: conversation.kind,
+        conversationId: conversation.id,
         error: err instanceof Error ? err.message : String(err),
       }));
     });