@zhin.js/adapter-onebot12 5.0.1 → 5.0.4

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @zhin.js/adapter-onebot12
 
+## 5.0.4
+
+### Patch Changes
+
+- Updated dependencies [0de46a8]
+- Updated dependencies [c106ecc]
+- Updated dependencies [ca92e03]
+- Updated dependencies [b0f37ae]
+- Updated dependencies [ba08a2f]
+- Updated dependencies [daffd4c]
+- Updated dependencies [36c7400]
+- Updated dependencies [162fa34]
+- Updated dependencies [e40b048]
+- Updated dependencies [f1708c3]
+- Updated dependencies [e53444f]
+- Updated dependencies [92b0dd7]
+- Updated dependencies [a7df753]
+  - @zhin.js/host-http@1.0.8
+  - @zhin.js/im-contract@1.0.3
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/plugin-runtime@1.1.5
+  - @zhin.js/command@1.0.9
+  - @zhin.js/core@1.5.4
+  - zhin.js@6.0.4
+
+## 5.0.3
+
+### Patch Changes
+
+- f8c7a54: fix: im
+- Updated dependencies [f8c7a54]
+  - @zhin.js/logger@1.0.76
+  - @zhin.js/host-http@1.0.7
+  - @zhin.js/adapter@1.1.6
+  - @zhin.js/command@1.0.8
+  - @zhin.js/core@1.5.3
+  - @zhin.js/im-contract@1.0.2
+  - @zhin.js/plugin-runtime@1.1.4
+  - zhin.js@6.0.3
+
+## 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

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/adapters/onebot12.js

@@ -25,8 +25,8 @@ export default defineAdapter({
         const config = resolveOneBot12Config(context.config);
         const gateway = context.use(messageGatewayToken);
         // 注册到插件运行时状态（onebot12.endpoint list 的"运行中"数据源）
-        context.use(onebot12RuntimeStateToken).endpoints.set(config.name, {
-            name: config.name,
+        context.use(onebot12RuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
             mode: config.connection,
         });
         if (config.connection === 'webhook') {

package/adapters/onebot12.ts

@@ -33,8 +33,8 @@ export default defineAdapter<OneBot12AdapterConfig>({
     const config = resolveOneBot12Config(context.config);
     const gateway = context.use(messageGatewayToken);
     // 注册到插件运行时状态（onebot12.endpoint list 的"运行中"数据源）
-    context.use(onebot12RuntimeStateToken).endpoints.set(config.name, {
-      name: config.name,
+    context.use(onebot12RuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
       mode: config.connection,
     });
     if (config.connection === 'webhook') {

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,11 +4,12 @@
  * 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;
     readonly connection?: 'ws' | 'webhook' | 'wss';
-    readonly name?: string;
+    readonly id?: string;
     readonly access_token?: string;
     readonly url?: string;
     readonly path?: string;
@@ -19,7 +20,7 @@ export interface OneBot12LegacyEndpointRow {
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface OneBot12AdapterConfig {
     readonly connection?: 'ws' | 'webhook' | 'wss';
-    readonly name?: string;
+    readonly id?: string;
     readonly access_token?: string;
     readonly url?: string;
     readonly path?: string;
@@ -31,7 +32,7 @@ export interface OneBot12AdapterConfig {
 }
 export interface OneBot12ConfigBase {
     readonly context: 'onebot12';
-    readonly name: string;
+    readonly id: string;
     readonly access_token?: string;
 }
 /** 正向 WebSocket：应用连 OneBot 实现的 WS 服务器 */
@@ -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(endpointKey: 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

@@ -11,8 +11,8 @@ export function resolveOneBot12Config(config = {}) {
     const connection = config.connection
         ?? entry?.connection
         ?? 'ws';
-    const name = (typeof config.name === 'string' && config.name)
-        || (typeof entry?.name === 'string' && entry.name)
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
         || process.env.ONEBOT12_BOT_NAME
         || 'onebot12-bot';
     const access_token = config.access_token ?? entry?.access_token;
@@ -24,7 +24,7 @@ export function resolveOneBot12Config(config = {}) {
         return {
             context: 'onebot12',
             connection: 'ws',
-            name,
+            id,
             access_token,
             url,
             reconnect_interval: config.reconnect_interval ?? entry?.reconnect_interval ?? 5000,
@@ -39,7 +39,7 @@ export function resolveOneBot12Config(config = {}) {
         return {
             context: 'onebot12',
             connection: 'webhook',
-            name,
+            id,
             access_token,
             path,
             api_url: config.api_url ?? entry?.api_url,
@@ -53,7 +53,7 @@ export function resolveOneBot12Config(config = {}) {
         return {
             context: 'onebot12',
             connection: 'wss',
-            name,
+            id,
             access_token,
             path,
             heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
@@ -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(endpointKey, ev) {
+    const endpoint = { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey };
+    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 {
@@ -21,7 +21,7 @@ export class OneBot12WebhookEndpoint {
         if (!this.#options.config.access_token) {
             // webhook 模式未配 access_token 时任何 POST 都会被放行（verifyOneBotAccessToken 直接 return true）
             logger.warn(formatCompact({
-                endpoint: this.#options.config.name,
+                endpoint: this.#options.config.id,
                 mode: 'webhook',
                 ok: false,
                 error: 'missing access_token',
@@ -30,7 +30,7 @@ export class OneBot12WebhookEndpoint {
         this.#setupRoutes();
         logger.info(formatCompact({
             op: 'listen',
-            endpoint: this.#options.config.name,
+            endpoint: this.#options.config.id,
             mode: 'webhook',
             path: this.#options.config.path,
         }));
@@ -46,24 +46,25 @@ export class OneBot12WebhookEndpoint {
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#started = false;
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.id }));
     }
-    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',
-                endpoint: this.#options.config.name,
+                endpoint: this.#options.config.id,
                 error: error instanceof Error ? error.message : String(error),
             }));
         });
         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,
+            endpoint: this.#options.config.id,
+            kind: conversation.kind,
+            conversationId: conversation.id,
             messageId,
         }));
         return messageId;
@@ -80,31 +81,31 @@ 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,
+            sender: { id: senderUserId(ev), ...(nickname ? { name: nickname } : {}) },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
             metadata: Object.freeze({
                 detail_type: ev.detail_type,
                 user_id: ev.user_id,
                 group_id: ev.group_id,
                 channel_id: ev.channel_id,
                 guild_id: ev.guild_id,
-                endpoint: this.#options.config.name,
                 time: ev.time,
                 ...(nickname ? { nickname } : {}),
-                ...(mentioned ? { mentioned: true } : {}),
             }),
         }).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

@@ -4,12 +4,12 @@
 import WebSocket from 'ws';
 import { clearTimeout } from 'node:timers';
 import { createEndpointLifecycle, } from '@zhin.js/adapter';
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger } 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 {
+    #logger;
     #options;
     management = createOneBot12EndpointManagement(this);
     #lifecycle;
@@ -18,10 +18,11 @@ export class OneBot12WsEndpoint {
     #pending = new Map();
     #open = false;
     constructor(options) {
+        this.#logger = getAdapterLogger('onebot12', options.config.id);
         this.#options = options;
         const { config } = options;
         this.#lifecycle = createEndpointLifecycle({
-            name: config.name,
+            name: config.id,
             reconnect: {
                 initialIntervalMs: config.reconnect_interval,
                 // 固定间隔（multiplier 1、无抖动），对齐旧 reconnect_interval 语义
@@ -69,22 +70,23 @@ 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({
+            this.#logger.warn(formatCompact({
                 op: 'onebot12_upload_failed',
-                endpoint: this.#options.config.name,
+                endpoint: this.#options.config.id,
                 error: error instanceof Error ? error.message : String(error),
             }));
         });
         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({
+        this.#logger.debug(formatCompact({
             op: 'onebot12_send',
-            endpoint: this.#options.config.name,
-            target,
+            endpoint: this.#options.config.id,
+            kind: conversation.kind,
+            conversationId: conversation.id,
             messageId,
         }));
         return messageId;
@@ -102,31 +104,31 @@ 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,
+            sender: { id: senderUserId(ev), name: senderNickname(ev) },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
             metadata: Object.freeze({
                 detail_type: ev.detail_type,
                 user_id: ev.user_id,
                 group_id: ev.group_id,
                 channel_id: ev.channel_id,
                 guild_id: ev.guild_id,
-                endpoint: this.#options.config.name,
                 time: ev.time,
                 ...(nickname ? { nickname } : {}),
-                ...(mentioned ? { mentioned: true } : {}),
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'onebot12_gateway_receive_failed',
-                target,
+                kind: conversation.kind,
+                conversationId: conversation.id,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -151,8 +153,8 @@ export class OneBot12WsEndpoint {
                 if (settled)
                     return;
                 settled = true;
-                logger.debug(formatCompact({
-                    endpoint: this.#options.config.name,
+                this.#logger.debug(formatCompact({
+                    endpoint: this.#options.config.id,
                     mode: 'ws',
                     url: safeUrl,
                 }));
@@ -181,9 +183,9 @@ export class OneBot12WsEndpoint {
             });
             ws.on('error', (err) => {
                 const error = err instanceof Error ? err : new Error(String(err));
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'ws_error',
-                    endpoint: this.#options.config.name,
+                    endpoint: this.#options.config.id,
                     ok: false,
                     error: error.message,
                 }));
@@ -220,9 +222,9 @@ export class OneBot12WsEndpoint {
             this.admit(msg);
         }
         catch (error) {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'onebot12_parse_failed',
-                endpoint: this.#options.config.name,
+                endpoint: this.#options.config.id,
                 error: error instanceof Error ? error.message : String(error),
             }));
         }

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>;