@zhin.js/adapter-onebot11 6.0.14 → 7.0.1

package/lib/wss-endpoint.js

@@ -1,36 +1,46 @@
 /**
  * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
-import { clearInterval } from 'node:timers';
+import { ClientEndpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createOneBot11EndpointManagement } from './endpoint-management.js';
-import { registerOnebot11AgentEndpoint } from './onebot11-agent-deps.js';
 import { buildSendAction, formatInboundContent, formatInboundMetadata, formatOutboundSegments, isMessageEvent, onebot11InboundConversation, senderDisplayName, senderUserId, } from './protocol.js';
 import { receiveOneBot11SideEvent } from './side-event-dispatch.js';
 import { createOneBot11ContentPort } from './content-port.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
-import { callOneBot11WsAction, handleOneBot11WsMessage, rejectAllPending, startOneBot11Heartbeat, } from './ws-transport.js';
-export class OneBot11WssEndpoint {
+import { callOneBot11WsAction, handleOneBot11WsMessage, rejectAllPending, } from './ws-transport.js';
+import { callOnebot11Client, createOnebot11EndpointClient, forwardOnebot11ClientEvents } from './client.js';
+export class OneBot11WssEndpoint extends ClientEndpoint {
+    client;
     #logger;
     #options;
-    management = createOneBot11EndpointManagement(this);
-    content = createOneBot11ContentPort((action, params) => this.callApi(action, params));
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content;
     #ws;
     #wsRelease;
-    #heartbeatTimer;
+    #lifecycle;
     #requestId = { value: 0 };
     #pending = new Map();
-    #open = false;
-    #started = false;
-    #unregisterAgent;
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('onebot11', options.config.id);
         this.#options = options;
+        this.#lifecycle = createEndpointLifecycle({
+            name: options.config.id,
+            reconnect: false,
+            heartbeat: { intervalMs: options.config.heartbeat_interval },
+        });
+        this.client = createOnebot11EndpointClient(options.config, (action, params) => this.#callApi(action, params));
+        const callApi = (action, params) => callOnebot11Client(this.client, action, params);
+        this.management = createOneBot11EndpointManagement({ callApi });
+        this.content = createOneBot11ContentPort(callApi);
+        this.bindClientEvents((receive) => forwardOnebot11ClientEvents(this.client, receive), (name, payload) => {
+            if (name === 'event')
+                this.#admitRaw(payload);
+        }, (_name, error) => this.#warnPlatformEvent(error));
     }
     async start() {
-        if (this.#started)
-            return;
-        this.#started = true;
         if (!this.#options.config.access_token) {
             // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
             this.#logger.warn(formatCompact({
@@ -40,10 +50,22 @@ export class OneBot11WssEndpoint {
                 error: 'missing access_token',
             }));
         }
-        this.#unregisterAgent = registerOnebot11AgentEndpoint(this.#options.config.id, this);
-        const handle = this.#options.http.ws(this.#options.config.path);
-        this.#wsRelease = handle.onConnection((connection) => {
-            this.#acceptConnection(connection);
+        await this.#lifecycle.start(async (lifecycleHandle) => {
+            const handle = this.#options.http.ws(this.#options.config.path);
+            this.#wsRelease = handle.onConnection((connection) => {
+                this.#acceptConnection(connection);
+            });
+            lifecycleHandle.onForceClose(() => {
+                this.#wsRelease?.();
+                this.#wsRelease = undefined;
+                try {
+                    this.#ws?.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                this.#ws = undefined;
+            });
         });
         this.#logger.info(formatCompact({
             op: 'listen',
@@ -52,67 +74,33 @@ export class OneBot11WssEndpoint {
             path: this.#options.config.path,
         }));
     }
-    open() {
-        this.#open = true;
-    }
-    close() {
-        this.#open = false;
-    }
     async stop() {
-        this.#open = false;
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
-        this.#wsRelease?.();
-        this.#wsRelease = undefined;
-        if (this.#heartbeatTimer) {
-            clearInterval(this.#heartbeatTimer);
-            this.#heartbeatTimer = undefined;
-        }
+        this.close();
+        await this.#lifecycle.stop();
         rejectAllPending(this.#pending);
-        if (this.#ws) {
-            try {
-                this.#ws.close();
-            }
-            catch {
-                /* ignore */
-            }
-            this.#ws = undefined;
-        }
-        this.#started = false;
     }
     async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(conversation, message);
-        const data = await this.callApi(action, params);
+        const data = await callOnebot11Client(this.client, action, params);
         return data?.message_id != null ? String(data.message_id) : '';
     }
     async recallMessage(messageId) {
         if (!messageId)
             return;
-        await this.callApi('delete_msg', { message_id: Number(messageId) });
+        await callOnebot11Client(this.client, 'delete_msg', { message_id: Number(messageId) });
     }
-    callApi(action, params = {}) {
+    #callApi(action, params = {}) {
         return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);
     }
-    async setTitle(groupId, userId, title, duration = -1) {
-        await this.callApi('set_group_special_title', {
-            group_id: groupId,
-            user_id: userId,
-            special_title: title,
-            duration,
-        });
-        return true;
-    }
-    admit(ev) {
-        if (!this.#open)
-            return;
+    #admitRaw(ev) {
         if (!isMessageEvent(ev)) {
-            receiveOneBot11SideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            receiveOneBot11SideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, { callApi: (action, params) => callOnebot11Client(this.client, action, params) }, ev, this.#logger);
             return;
         }
         const conversation = onebot11InboundConversation(String(this.#options.id), ev);
         const inbound = formatInboundMetadata(ev, this.#options.config.id);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: String(ev.message_id) },
             content: formatInboundContent(ev),
@@ -133,6 +121,12 @@ export class OneBot11WssEndpoint {
             }));
         });
     }
+    #warnPlatformEvent(error) {
+        this.#logger.warn(formatCompact({
+            op: 'onebot11_platform_event_failed',
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
     #acceptConnection(connection) {
         if (!verifyOneBotAccessToken(this.#options.config.access_token, connection.request)) {
             connection.socket.close(4003, 'Unauthorized');
@@ -148,21 +142,26 @@ export class OneBot11WssEndpoint {
             }
         }
         this.#ws = socket;
-        this.#heartbeatTimer = startOneBot11Heartbeat(this.#ws, this.#options.config.heartbeat_interval, this.#heartbeatTimer);
+        this.#lifecycle.startHeartbeat(() => {
+            try {
+                this.#ws?.ping?.();
+            }
+            catch {
+                /* ignore */
+            }
+        });
         socket.on('message', (data) => {
+            this.#lifecycle.notifyHeartbeatAck();
             handleOneBot11WsMessage(data, {
                 endpointId: this.#options.config.id,
                 pending: this.#pending,
-                admit: (ev) => this.admit(ev),
+                ingest: (ev) => this.client.ingest(ev),
             });
         });
         socket.on('close', () => {
             if (this.#ws === socket) {
                 this.#ws = undefined;
-                if (this.#heartbeatTimer) {
-                    clearInterval(this.#heartbeatTimer);
-                    this.#heartbeatTimer = undefined;
-                }
+                this.#lifecycle.stopHeartbeat();
             }
         });
         this.#logger.debug(formatCompact({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot11",
-  "version": "6.0.14",
+  "version": "7.0.1",
   "description": "Zhin.js OneBot 11 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -40,13 +40,16 @@
     "directory": "plugins/adapters/onebot11"
   },
   "dependencies": {
+    "@imhelper/onebot-v11": "1.0.7",
+    "imhelper": "1.0.7",
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.11",
-    "@zhin.js/core": "1.5.12",
-    "@zhin.js/host-http": "1.0.11",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/core": "1.5.14",
+    "@zhin.js/feature-kit": "1.0.13",
+    "@zhin.js/host-http": "1.0.13",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/logger": "1.0.76",
-    "@zhin.js/permission": "1.0.3"
+    "@zhin.js/logger": "1.0.77",
+    "@zhin.js/permission": "1.0.4"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -54,17 +57,17 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.14",
-    "@zhin.js/host-http": "1.0.11",
-    "zhin.js": "6.0.12"
+    "@zhin.js/agent": "1.1.16",
+    "@zhin.js/host-http": "1.0.13",
+    "zhin.js": "6.0.14"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.11",
-    "@zhin.js/agent": "1.1.14",
-    "@zhin.js/command": "1.0.15",
-    "@zhin.js/core": "1.5.12",
-    "zhin.js": "6.0.12"
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/agent": "1.1.16",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/core": "1.5.14",
+    "zhin.js": "6.0.14"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {

package/src/client.ts

@@ -0,0 +1,78 @@
+import {
+  OneBotV11Client,
+  type OneBotV11Event as ImHelperOneBot11Event,
+  type OneBotV11Response,
+} from '@imhelper/onebot-v11';
+import { EventFactory, type EventMap, type ImHelperEventMap } from 'imhelper';
+import {
+  defineEndpointClient,
+  forwardEndpointClientEvents,
+  type ClientEventPayloads,
+} from 'zhin.js/adapter';
+import type { ResolvedOneBot11Config } from './protocol.js';
+
+export { OneBotV11Client as Onebot11Client } from '@imhelper/onebot-v11';
+
+export type Onebot11ApiCall = (
+  action: string,
+  params?: Record<string, unknown>,
+) => Promise<OneBotV11Response>;
+
+type Onebot11ClientEvents = ImHelperEventMap<
+  number,
+  ImHelperOneBot11Event,
+  EventMap<number>
+>;
+export type Onebot11ClientEventMap = ClientEventPayloads<Onebot11ClientEvents>;
+
+export function createOnebot11EndpointClient(
+  config: ResolvedOneBot11Config,
+  request: Onebot11ApiCall,
+): OneBotV11Client {
+  return new OneBotV11Client({
+    baseUrl: config.connection === 'ws'
+      ? config.url.replace(/^ws(s?):/, 'http$1:')
+      : 'http://localhost',
+    selfId: config.id,
+    accessToken: config.access_token,
+    receiveMode: 'manual',
+    call: request,
+  });
+}
+
+export async function callOnebot11Client<T = unknown>(
+  client: OneBotV11Client,
+  action: string,
+  params?: Record<string, unknown>,
+): Promise<T | undefined> {
+  const response: OneBotV11Response<T> = await client.call<T>(action, params);
+  if (response.status !== 'ok') {
+    throw new Error(
+      `OneBot 11 API ${action}: retcode=${response.retcode}${response.message ? ` ${response.message}` : ''}`,
+    );
+  }
+  return response.data;
+}
+
+const onebot11ClientEventNames = Object.freeze([
+  ...EventFactory.getSupportedEventTypes<number>(),
+  'event',
+]);
+
+export function forwardOnebot11ClientEvents(
+  client: OneBotV11Client,
+  receive: (name: string, payload: unknown) => void,
+): () => void {
+  return forwardEndpointClientEvents(client, onebot11ClientEventNames, receive);
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly onebot11: {
+      readonly client: OneBotV11Client;
+      readonly events: Onebot11ClientEventMap;
+    };
+  }
+}
+
+export const onebot11Client = defineEndpointClient<OneBotV11Client, Onebot11ClientEventMap>('onebot11');

package/src/index.ts

@@ -51,9 +51,18 @@ export {
 export { verifyOneBotAccessToken } from './wss-auth.js';
 
 export {
-  getOnebot11AgentDeps,
-  registerOnebot11AgentEndpoint,
-  setOnebot11AgentDeps,
-  type Onebot11AgentDeps,
-  type Onebot11AgentEndpoint,
-} from './onebot11-agent-deps.js';
+  Onebot11Client,
+  onebot11Client,
+  type Onebot11ClientEventMap,
+} from './client.js';
+
+export type {
+  OneBotV11ActionUrlResolver,
+  OneBotV11AdapterConfig as ImHelperOneBotV11AdapterConfig,
+  OneBotV11Call,
+  OneBotV11ClientConfig,
+  OneBotV11Event as ImHelperOneBotV11Event,
+  OneBotV11Response,
+} from '@imhelper/onebot-v11';
+export { ProtocolError } from '@imhelper/onebot-v11';
+export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';

package/src/protocol.ts

@@ -96,9 +96,10 @@ export interface OneBot11ActionRequest {
 }
 
 export interface OneBot11ActionResponse {
-  status: string;
+  status: 'ok' | 'failed';
   retcode: number;
   data?: unknown;
+  message?: string;
   echo?: string;
 }
 
@@ -196,7 +197,7 @@ export function onebot11InboundConversation(endpointKey: string, ev: OneBot11Eve
   };
 }
 
-/** Build inbound text for MessageGateway.receive */
+/** Build inbound text for OutboundMessageService.receive */
 export function formatInboundContent(ev: OneBot11Event): string {
   if (Array.isArray(ev.message)) {
     return ev.message

package/src/side-event-dispatch.ts

@@ -1,5 +1,5 @@
 import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
-import type { SideEventGateway } from '@zhin.js/core/runtime';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
 import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
 import type { OneBot11Event } from './protocol.js';
 
@@ -8,19 +8,19 @@ export interface OneBot11SideEventCaller {
 }
 
 export function receiveOneBot11SideEvent(
-  sideEvents: SideEventGateway | undefined,
+  emit: EndpointEventEmitter,
   endpointKey: string,
   caller: OneBot11SideEventCaller,
   raw: OneBot11Event,
   logger: ReturnType<typeof getAdapterLogger>,
 ): void {
-  if (!sideEvents) return;
+  if (!emit) return;
   const record = raw as Record<string, unknown>;
   const postType = String(record.post_type ?? '');
   const requestType = String(record.request_type ?? '');
   const isRequest = postType === 'request' || postType.startsWith('request.');
   const isFriend = requestType === 'friend' || postType.includes('friend');
-  void receiveOneBotLikeSideEvent(sideEvents, {
+  void receiveOneBotLikeSideEvent(emit, {
     adapter: 'onebot11',
     endpointKey,
     platform: 'onebot',

package/src/ws-endpoint.ts

@@ -3,18 +3,18 @@
  */
 import WebSocket from 'ws';
 import {
+  ClientEndpoint,
+  createRecallEndpointControl,
   createEndpointLifecycle,
   type EndpointConnectHandle,
-  type EndpointInstance,
+  type EndpointControl,
   type EndpointLifecycle,
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createOneBot11EndpointManagement } from './endpoint-management.js';
-import { registerOnebot11AgentEndpoint } from './onebot11-agent-deps.js';
 import {
   buildSendAction,
   buildWsConnectOptions,
@@ -40,11 +40,10 @@ import {
   type OneBot11WsCreateOptions,
   type OneBot11WsSocket,
 } from './ws-types.js';
+import { callOnebot11Client, createOnebot11EndpointClient, forwardOnebot11ClientEvents, type Onebot11Client } from './client.js';
 
 export interface OneBot11WsEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly config: OneBot11WsConfig;
   readonly createWebSocket?: (
     url: string,
@@ -52,22 +51,34 @@ export interface OneBot11WsEndpointOptions {
   ) => OneBot11WsSocket;
 }
 
-export class OneBot11WsEndpoint implements EndpointInstance {
+export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
+  readonly client: Onebot11Client;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: OneBot11WsEndpointOptions;
-  readonly management: EndpointManagement = createOneBot11EndpointManagement(this);
-  readonly content = createOneBot11ContentPort((action, params) => this.callApi(action, params));
+  readonly management: EndpointManagement;
+  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
+  readonly content;
   readonly #lifecycle: EndpointLifecycle;
   #ws?: OneBot11WsSocket;
   #requestId = { value: 0 };
   #pending = new Map<string, OneBot11PendingAction>();
-  #open = false;
-  #unregisterAgent?: () => void;
 
   constructor(options: OneBot11WsEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('onebot11', options.config.id);
     this.#options = options;
+    this.client = createOnebot11EndpointClient(options.config, (action, params) => this.#callApi(action, params));
+    const callApi = (action: string, params?: Record<string, unknown>) => callOnebot11Client(this.client, action, params);
+    this.management = createOneBot11EndpointManagement({ callApi });
+    this.content = createOneBot11ContentPort(callApi);
+    this.bindClientEvents(
+      (receive) => forwardOnebot11ClientEvents(this.client, receive),
+      (name, payload) => {
+        if (name === 'event') this.#admitRaw(payload as OneBot11Event);
+      },
+      (_name, error) => this.#warnPlatformEvent(error),
+    );
     const { config } = options;
     this.#lifecycle = createEndpointLifecycle({
       name: config.id,
@@ -84,12 +95,10 @@ export class OneBot11WsEndpoint implements EndpointInstance {
 
   async start(): Promise<void> {
     if (this.#lifecycle.started) return;
-    // agent 注册/反注册是适配器专有依赖，留在适配器侧（见 endpoint-lifecycle 迁移指引）
-    this.#unregisterAgent = registerOnebot11AgentEndpoint(this.#options.config.id, this);
     try {
       await this.#lifecycle.start((handle) => this.#connect(handle));
     } catch (err) {
-      // start 失败必须清理现场（状态复位由基座保证），避免 agent 注册泄漏
+      // start 失败必须清理现场（状态复位由基座保证）
       if (this.#ws) {
         try {
           this.#ws.close();
@@ -98,26 +107,14 @@ export class OneBot11WsEndpoint implements EndpointInstance {
         }
         this.#ws = undefined;
       }
-      this.#unregisterAgent?.();
-      this.#unregisterAgent = undefined;
       throw err;
     }
   }
 
-  open(): void {
-    this.#open = true;
-  }
-
-  close(): void {
-    this.#open = false;
-  }
-
   async stop(): Promise<void> {
-    this.#open = false;
+    this.close();
     // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
     await this.#lifecycle.stop();
-    this.#unregisterAgent?.();
-    this.#unregisterAgent = undefined;
     rejectAllPending(this.#pending);
     this.#ws = undefined;
   }
@@ -125,7 +122,7 @@ export class OneBot11WsEndpoint implements EndpointInstance {
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(conversation, message);
-    const data = await this.callApi(action, params) as { message_id?: number | string } | undefined;
+    const data = await callOnebot11Client<{ message_id?: number | string }>(this.client, action, params);
     const messageId = data?.message_id != null ? String(data.message_id) : '';
     this.#logger.debug(formatCompact({
       op: 'onebot11_send',
@@ -138,37 +135,22 @@ export class OneBot11WsEndpoint implements EndpointInstance {
 
   async recallMessage(messageId: string): Promise<void> {
     if (!messageId) return;
-    await this.callApi('delete_msg', { message_id: Number(messageId) });
+    await callOnebot11Client(this.client, 'delete_msg', { message_id: Number(messageId) });
   }
 
-  /** Public API for agent tools / callers. */
-  callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
+  #callApi(
+    action: string,
+    params: Record<string, unknown> = {},
+  ): ReturnType<typeof callOneBot11WsAction> {
     return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);
   }
 
-  async setTitle(
-    groupId: number,
-    userId: number,
-    title: string,
-    duration = -1,
-  ): Promise<boolean> {
-    await this.callApi('set_group_special_title', {
-      group_id: groupId,
-      user_id: userId,
-      special_title: title,
-      duration,
-    });
-    return true;
-  }
-
-  /** Test / internal: admit a parsed event when the endpoint is open. */
-  admit(ev: OneBot11Event): void {
-    if (!this.#open) return;
+  #admitRaw(ev: OneBot11Event): void {
     if (!isMessageEvent(ev)) {
       receiveOneBot11SideEvent(
-        this.#options.sideEvents,
+        (name, payload) => this.emit(name, payload),
         this.#options.config.id,
-        this,
+        { callApi: (action, params) => callOnebot11Client(this.client, action, params) },
         ev,
         this.#logger,
       );
@@ -177,7 +159,7 @@ export class OneBot11WsEndpoint implements EndpointInstance {
     const conversation = onebot11InboundConversation(String(this.#options.id), ev);
     const content = formatInboundContent(ev);
     const inbound = formatInboundMetadata(ev, this.#options.config.id);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: String(ev.message_id) },
       content,
@@ -199,6 +181,13 @@ export class OneBot11WsEndpoint implements EndpointInstance {
     });
   }
 
+  #warnPlatformEvent(error: unknown): void {
+    this.#logger.warn(formatCompact({
+      op: 'onebot11_platform_event_failed',
+      error: error instanceof Error ? error.message : String(error),
+    }));
+  }
+
   async #connect(handle: EndpointConnectHandle): Promise<void> {
     const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
     const create = this.#options.createWebSocket
@@ -240,7 +229,7 @@ export class OneBot11WsEndpoint implements EndpointInstance {
         handleOneBot11WsMessage(data, {
           endpointId: this.#options.config.id,
           pending: this.#pending,
-          admit: (ev) => this.admit(ev),
+          ingest: (ev) => this.client.ingest(ev as Parameters<Onebot11Client['ingest']>[0]),
         });
       });
 

package/src/ws-transport.ts

@@ -25,7 +25,7 @@ export function handleOneBot11WsMessage(
   options: {
     readonly endpointId: string;
     readonly pending: Map<string, OneBot11PendingAction>;
-    readonly admit: (ev: OneBot11Event) => void;
+    readonly ingest: (ev: OneBot11Event) => void;
   },
 ): void {
   try {
@@ -37,12 +37,11 @@ export function handleOneBot11WsMessage(
       if (pending) {
         options.pending.delete(resp.echo!);
         clearTimeout(pending.timeout);
-        if (resp.status === 'ok') pending.resolve(resp.data);
-        else pending.reject(new Error(`OneBot11 retcode=${resp.retcode}`));
+        pending.resolve(resp);
       }
       return;
     }
-    options.admit(msg as OneBot11Event);
+    options.ingest(msg as OneBot11Event);
   } catch (error) {
     logger.warn(formatCompact({
       op: 'onebot11_parse_failed',
@@ -58,7 +57,7 @@ export function callOneBot11WsAction(
   requestId: { value: number },
   action: string,
   params: Record<string, unknown>,
-): Promise<unknown> {
+): Promise<OneBot11ActionResponse> {
   if (!ws || ws.readyState !== WS_OPEN) {
     return Promise.reject(new Error('WebSocket 未连接'));
   }

package/src/ws-types.ts

@@ -14,7 +14,8 @@ export interface OneBot11WsCreateOptions {
 export const WS_OPEN = 1;
 
 export interface OneBot11PendingAction {
-  resolve: (value: unknown) => void;
+  resolve: (value: OneBot11ActionResponse) => void;
   reject: (err: Error) => void;
   timeout: NodeJS.Timeout;
 }
+import type { OneBot11ActionResponse } from './protocol.js';