@zhin.js/adapter-onebot12 1.1.18 → 1.1.19

package/src/response.ts

@@ -0,0 +1,19 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import type { OneBotV12Response } from '@imhelper/onebot-v12';
+
+/**
+ * One classifier for native SDK, HTTP and WS results.
+ * @see https://12.onebot.dev/connect/data-protocol/action-response/
+ */
+export function readOnebot12Response<T = unknown>(response: unknown): T | undefined {
+  if (response && typeof response === 'object') {
+    const result = response as Partial<OneBotV12Response>;
+    if (result.status === 'ok' && result.retcode === 0) return result.data as T | undefined;
+    if (result.status === 'failed' && typeof result.retcode === 'number' && Number.isSafeInteger(result.retcode) && result.retcode >= 10000 && result.retcode <= 99999) {
+      throw new EndpointDeliveryError('platform_rejected',
+        `OneBot 12 API rejected: retcode=${result.retcode}${result.message ? ` ${result.message}` : ''}`, 'rejected');
+    }
+  }
+  // OB12 defines only ok/0 or failed with an error code; inconsistent envelopes prove neither result.
+  throw new EndpointDeliveryError('delivery_unconfirmed', 'OneBot 12 response did not confirm the action result', 'unknown');
+}

package/src/side-event-dispatch.ts

@@ -7,13 +7,15 @@ export interface OneBot12SideEventCaller {
   callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
 }
 
-export function receiveOneBot12SideEvent(
-  emit: EndpointEventEmitter,
-  endpointKey: string,
-  caller: OneBot12SideEventCaller,
-  raw: OneBot12Event,
-  logger: ReturnType<typeof getAdapterLogger>,
-): void {
+/** Exact instance-owned dependencies for one canonical side-event projection. */
+export interface OneBot12SideEventContext {
+  readonly emit: EndpointEventEmitter;
+  readonly endpointKey: string;
+  readonly caller: OneBot12SideEventCaller;
+  readonly logger: ReturnType<typeof getAdapterLogger>;
+}
+export function receiveOneBot12SideEvent(raw: OneBot12Event, context: OneBot12SideEventContext): void {
+  const { emit, endpointKey, caller, logger } = context;
   if (!emit) return;
   const record = raw as Record<string, unknown>;
   const eventType = String(record.type ?? record.post_type ?? '');

package/src/webhook.ts

@@ -1,13 +1,16 @@
+import { acceptHttpIngress } from 'imhelper';
 /**
  * OneBot12 HTTP webhook endpoint — POST inbound + api_url outbound.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import {
-  ClientEndpoint,
+  createEndpointSpecification, endpointSpec,
+  type Endpoint, type EndpointSpecification,
   createRecallEndpointControl,
   type EndpointControl,
   type EndpointManagement,
   type EndpointSendRequest,
+  type PendingRpcRequest,
 } from 'zhin.js/adapter';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -15,6 +18,7 @@ import type { CapabilityId } from 'zhin.js';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import {
   buildSendMessageParams,
+  matchesOneBot12Self,
   callOneBot12Action,
   formatInboundContent,
   formatOutboundSegments,
@@ -29,46 +33,55 @@ import {
 } from './protocol.js';
 import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
-import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents, type Onebot12Client } from './client.js';
+import { callOnebot12Client, readOnebot12Response, onebot12ClientOptions, forwardOnebot12ClientEvents, Onebot12Client } from './client.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 
 const logger = getLogger('onebot12');
 
 export interface OneBot12WebhookEndpointOptions {
+  readonly signal?: AbortSignal;
   readonly id: CapabilityId;
   readonly http: HttpHost;
   readonly config: OneBot12WebhookConfig;
   readonly callAction?: typeof callOneBot12Action;
 }
 
-export class OneBot12WebhookEndpoint extends ClientEndpoint<Onebot12Client> {
-  readonly client: Onebot12Client;
+export class OneBot12WebhookEndpoint extends Onebot12Client implements Endpoint {
+  readonly [endpointSpec]: EndpointSpecification;
+  #open = false;
   readonly #options: OneBot12WebhookEndpointOptions;
-  readonly management: EndpointManagement;
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
-  readonly content;
+  readonly #management: EndpointManagement;
+  readonly #control: EndpointControl = createRecallEndpointControl((id, signal?: AbortSignal) => this.#recallMessage(id, signal));
+  readonly #content;
+  readonly #releaseClientEvents: () => void;
   readonly #callAction: typeof callOneBot12Action;
   #routeReleases: HttpRouteRegistration[] = [];
   #started = false;
 
   constructor(options: OneBot12WebhookEndpointOptions) {
-    super();
+    super(onebot12ClientOptions(options.config, (action, params) => this.#callApi({ action, params })));
     this.#options = options;
     this.#callAction = options.callAction ?? callOneBot12Action;
-    this.client = createOnebot12EndpointClient(options.config, (action, params) => this.#callApi(action, params));
-    const callApi = (action: string, params?: Record<string, unknown>) => callOnebot12Client(this.client, action, params);
-    this.management = createOneBot12EndpointManagement({ callApi });
-    this.content = createOneBot12ContentPort(callApi);
-    this.bindClientEvents(
-      (receive) => forwardOnebot12ClientEvents(this.client, receive),
-      (name, payload) => {
+    const callApi = (request: PendingRpcRequest) => this.#callApi(request).then(readOnebot12Response);
+    this.#management = createOneBot12EndpointManagement({ callApi });
+    this.#content = createOneBot12ContentPort(callApi);
+    this[endpointSpec] = createEndpointSpecification(this, {
+      name: options.config.id,
+      start: () => this.#start(), open: () => { this.#open = true; },
+      close: () => { this.#open = false; }, stop: () => this.#stop(),
+      send: request => this.#send(request),
+      management: this.#management, control: this.#control, content: this.#content,
+    });
+    this.#releaseClientEvents = forwardOnebot12ClientEvents(this, (name, payload) => {
+      void this[endpointSpec].events.run(() => {
+        if (!this.#started) return;
+        void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(error));
         if (name === 'event') this.#admitRaw(payload as OneBot12Event);
-      },
-      (_name, error) => this.#warnPlatformEvent(error),
-    );
+      }).catch(error => this.#warnPlatformEvent(error));
+    });
   }
 
-  async start(): Promise<void> {
+  async #start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
     if (!this.#options.config.access_token) {
@@ -89,28 +102,26 @@ export class OneBot12WebhookEndpoint extends ClientEndpoint<Onebot12Client> {
     }));
   }
 
-  async stop(): Promise<void> {
-    this.close();
+  async #stop(): Promise<void> {
+    this.#open = false;
     for (const release of this.#routeReleases.splice(0)) release();
     this.#started = false;
+    this.#releaseClientEvents();
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.id }));
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
-    const materialized = await uploadOneBot12MediaSegments(
-      payload,
-      (action, params) => callOnebot12Client(this.client, action, params),
-      (error) => {
-        logger.warn(formatCompact({
-          op: 'onebot12_upload_failed',
-          endpoint: this.#options.config.id,
-          error: error instanceof Error ? error.message : String(error),
-        }));
+  async #send({ conversation, payload, signal }: EndpointSendRequest): Promise<string> {
+    const materialized = await uploadOneBot12MediaSegments({
+      payload, signal,
+      callAction: (action, params) => this.#callApi({ action, params, signal }).then(readOnebot12Response),
+      onUploadFailed: error => {
+        logger.warn(formatCompact({ op: 'onebot12_upload_failed', endpoint: this.#options.config.id,
+          error: error instanceof Error ? error.message : String(error) }));
       },
-    );
+    });
     const message = formatOutboundSegments(materialized);
     const params = buildSendMessageParams(conversation, message);
-    const data = await callOnebot12Client<{ message_id?: string }>(this.client, 'send_message', params);
+    const data = readOnebot12Response<{ message_id?: string }>(await this.#callApi({ action: 'send_message', params, signal }));
     const messageId = data?.message_id ?? '';
     logger.debug(formatCompact({
       op: 'onebot12_send',
@@ -122,38 +133,38 @@ export class OneBot12WebhookEndpoint extends ClientEndpoint<Onebot12Client> {
     return messageId;
   }
 
-  async recallMessage(messageId: string): Promise<void> {
+  async #recallMessage(messageId: string, signal?: AbortSignal): Promise<void> {
     if (!messageId) return;
-    await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
+    await this.#callApi({ action: 'delete_message', params: { message_id: messageId }, signal }).then(readOnebot12Response);
   }
 
-  async #callApi(
-    action: string,
-    params: Record<string, unknown> = {},
-  ): Promise<import('@imhelper/onebot-v12').OneBotV12Response> {
-    return this.#callAction(
-      { url: this.#options.config.api_url, access_token: this.#options.config.access_token },
-      action,
-      params,
-    );
+  async #callApi(request: PendingRpcRequest): Promise<import('@imhelper/onebot-v12').OneBotV12Response> {
+    const epoch = this.#options.signal;
+    const signal = epoch && request.signal ? AbortSignal.any([epoch, request.signal]) : epoch ?? request.signal;
+    return this.#callAction({ url: this.#options.config.api_url, access_token: this.#options.config.access_token,
+      self: { platform: this.#options.config.platform, user_id: this.#options.config.userId },
+      action: request.action, params: request.params, signal });
   }
 
   #admitRaw(ev: OneBot12Event): void {
+    if (!matchesOneBot12Self(this.#options.config, ev)) return;
+    this[endpointSpec].reportSelfUserId(ev.self.user_id);
     if (!isMessageEvent(ev)) {
-      receiveOneBot12SideEvent(
-        (name, payload) => this.emit(name, payload),
-        this.#options.config.id,
-        { callApi: (action, params) => callOnebot12Client(this.client, action, params) },
-        ev,
-        logger,
-      );
+      receiveOneBot12SideEvent(ev, {
+        emit: (name, payload) => this[endpointSpec].events.emit(name, payload),
+        endpointKey: this.#options.config.id,
+        caller: { callApi: (action, params) => callOnebot12Client({ client: this, action, params }) },
+        logger: logger,
+      });
       return;
     }
-    const conversation = onebot12InboundConversation(String(this.#options.id), ev);
+    const conversation = { ...onebot12InboundConversation(String(this.#options.id), ev), endpoint: this[endpointSpec].identity };
     const content = formatInboundContent(ev);
     const nickname = senderNickname(ev);
     const mentioned = isBotMentioned(ev);
-    void this.emit('message.receive', {
+    void this[endpointSpec].events.message({
+      event: ev,
+      ...(typeof ev.time === 'number' ? { platformSentAt: ev.time * 1000 } : {}),
       conversation,
       message: { conversation, id: ev.message_id },
       content,
@@ -202,12 +213,16 @@ export class OneBot12WebhookEndpoint extends ClientEndpoint<Onebot12Client> {
         response.end(JSON.stringify({ message: 'Unauthorized' }));
         return;
       }
-      if (!this.clientEventsOpen) {
+      if (!this.#open) {
         response.writeHead(200, { 'Content-Type': 'application/json' });
         response.end(JSON.stringify({ status: 'ok' }));
         return;
       }
-      await this.client.acceptHttp(request, response);
+      await acceptHttpIngress<OneBot12Event>(request, response, event => {
+        if (!matchesOneBot12Self(this.#options.config, event)) return;
+        void this[endpointSpec].events.run(() => this.ingest(event as Parameters<Onebot12Client['ingest']>[0]))
+          .catch(error => this.#warnPlatformEvent(error));
+      });
     } catch (error) {
       logger.error('OneBot12 webhook error:', error);
       if (!response.headersSent) {

package/src/ws-endpoint.ts

@@ -3,7 +3,8 @@
  */
 import WebSocket from 'ws';
 import {
-  ClientEndpoint,
+  createEndpointSpecification, endpointSpec,
+  type Endpoint, type EndpointSpecification,
   createRecallEndpointControl,
   createEndpointLifecycle,
   type EndpointConnectHandle,
@@ -11,12 +12,14 @@ import {
   type EndpointLifecycle,
   type EndpointManagement,
   type EndpointSendRequest,
+  type PendingRpcRequest,
 } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import {
   buildSendMessageParams,
+  matchesOneBot12Self,
   buildWsConnectOptions,
   formatInboundContent,
   formatOutboundSegments,
@@ -31,19 +34,15 @@ import {
 } from './protocol.js';
 import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
-import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents, type Onebot12Client } from './client.js';
+import { callOnebot12Client, readOnebot12Response, onebot12ClientOptions, forwardOnebot12ClientEvents, Onebot12Client } from './client.js';
 import {
-  type OneBot12PendingAction,
   type OneBot12WsCreateOptions,
   type OneBot12WsSocket,
 } from './ws-types.js';
-import {
-  callOneBot12WsAction,
-  handleOneBot12WsMessage,
-  rejectAllPending,
-} from './ws-transport.js';
+import { createOneBot12Rpc, type OneBot12Rpc } from './ws-transport.js';
 
 export interface OneBot12WsEndpointOptions {
+  readonly signal?: AbortSignal;
   readonly id: CapabilityId;
   readonly config: OneBot12WsConfig;
   readonly createWebSocket?: (
@@ -52,34 +51,48 @@ export interface OneBot12WsEndpointOptions {
   ) => OneBot12WsSocket;
 }
 
-export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
-  readonly client: Onebot12Client;
+export class OneBot12WsEndpoint extends Onebot12Client implements Endpoint {
+  readonly [endpointSpec]: EndpointSpecification;
+  #open = false;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: OneBot12WsEndpointOptions;
-  readonly management: EndpointManagement;
-  readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
-  readonly content;
+  readonly #management: EndpointManagement;
+  readonly #control: EndpointControl = createRecallEndpointControl((id, signal?: AbortSignal) => this.#recallMessage(id, signal));
+  readonly #content;
+  readonly #releaseClientEvents: () => void;
   readonly #lifecycle: EndpointLifecycle;
   #ws?: OneBot12WsSocket;
-  #requestId = { value: 0 };
-  #pending = new Map<string, OneBot12PendingAction>();
+  readonly #rpc: OneBot12Rpc;
 
   constructor(options: OneBot12WsEndpointOptions) {
-    super();
+    const rpc = createOneBot12Rpc({ endpointId: options.config.id, signal: options.signal,
+      self: { platform: options.config.platform, user_id: options.config.userId },
+      socket: () => this.#lifecycle.state === 'open' ? this.#ws : undefined,
+    });
+    super(onebot12ClientOptions(options.config, (action, params) => rpc.call({ action, params })));
+    this.#rpc = rpc;
     this.#logger = getAdapterLogger('onebot12', options.config.id);
     this.#options = options;
-    this.client = createOnebot12EndpointClient(options.config, (action, params) => this.#callAction(action, params ?? {}));
-    const callApi = (action: string, params?: Record<string, unknown>) => callOnebot12Client(this.client, action, params);
-    this.management = createOneBot12EndpointManagement({ callApi });
-    this.content = createOneBot12ContentPort(callApi);
-    this.bindClientEvents(
-      (receive) => forwardOnebot12ClientEvents(this.client, receive),
-      (name, payload) => {
+    const callApi = (request: PendingRpcRequest) => this.#rpc.call(request).then(readOnebot12Response);
+    this.#management = createOneBot12EndpointManagement({ callApi });
+    this.#content = createOneBot12ContentPort(callApi);
+    const readTransportState = () => this.#lifecycle.state;
+    this[endpointSpec] = createEndpointSpecification(this, {
+      name: options.config.id,
+      start: () => this.#start(), open: () => { this.#open = true; },
+      close: () => { this.#open = false; }, stop: () => this.#stop(),
+      send: request => this.#send(request),
+      get transportState() { return readTransportState(); },
+      management: this.#management, control: this.#control, content: this.#content,
+    });
+    this.#releaseClientEvents = forwardOnebot12ClientEvents(this, (name, payload) => {
+      void this[endpointSpec].events.run(() => {
+        if (!this.#open && !this.#lifecycle.started) return;
+        void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(error));
         if (name === 'event') this.#admitRaw(payload as OneBot12Event);
-      },
-      (_name, error) => this.#warnPlatformEvent(error),
-    );
+      }).catch(error => this.#warnPlatformEvent(error));
+    });
     const { config } = options;
     this.#lifecycle = createEndpointLifecycle({
       name: config.id,
@@ -94,7 +107,7 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
     });
   }
 
-  async start(): Promise<void> {
+  async #start(): Promise<void> {
     if (this.#lifecycle.started) return;
     try {
       await this.#lifecycle.start((handle) => this.#connect(handle));
@@ -112,29 +125,29 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
     }
   }
 
-  async stop(): Promise<void> {
-    this.close();
+  async #stop(): Promise<void> {
+    this.#open = false;
     // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
-    await this.#lifecycle.stop();
-    rejectAllPending(this.#pending);
-    this.#ws = undefined;
+    try { await this.#lifecycle.stop(); }
+    finally {
+      this.#rpc.dispose();
+      this.#releaseClientEvents();
+      this.#ws = undefined;
+    }
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
-    const materialized = await uploadOneBot12MediaSegments(
-      payload,
-      (action, params) => callOnebot12Client(this.client, action, params),
-      (error) => {
-        this.#logger.warn(formatCompact({
-          op: 'onebot12_upload_failed',
-          endpoint: this.#options.config.id,
-          error: error instanceof Error ? error.message : String(error),
-        }));
+  async #send({ conversation, payload, signal }: EndpointSendRequest): Promise<string> {
+    const materialized = await uploadOneBot12MediaSegments({
+      payload, signal,
+      callAction: (action, params) => this.#rpc.call({ action, params, signal }).then(readOnebot12Response),
+      onUploadFailed: error => {
+        this.#logger.warn(formatCompact({ op: 'onebot12_upload_failed', endpoint: this.#options.config.id,
+          error: error instanceof Error ? error.message : String(error) }));
       },
-    );
+    });
     const message = formatOutboundSegments(materialized);
     const params = buildSendMessageParams(conversation, message);
-    const data = await callOnebot12Client<{ message_id?: string }>(this.client, 'send_message', params);
+    const data = readOnebot12Response<{ message_id?: string }>(await this.#rpc.call({ action: 'send_message', params, signal }));
     const messageId = data?.message_id ?? '';
     this.#logger.debug(formatCompact({
       op: 'onebot12_send',
@@ -146,27 +159,30 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
     return messageId;
   }
 
-  async recallMessage(messageId: string): Promise<void> {
+  async #recallMessage(messageId: string, signal?: AbortSignal): Promise<void> {
     if (!messageId) return;
-    await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
+    await this.#rpc.call({ action: 'delete_message', params: { message_id: messageId }, signal }).then(readOnebot12Response);
   }
 
   #admitRaw(ev: OneBot12Event): void {
+    if (!matchesOneBot12Self(this.#options.config, ev)) return;
+    this[endpointSpec].reportSelfUserId(ev.self.user_id);
     if (!isMessageEvent(ev)) {
-      receiveOneBot12SideEvent(
-        (name, payload) => this.emit(name, payload),
-        this.#options.config.id,
-        { callApi: (action, params) => callOnebot12Client(this.client, action, params) },
-        ev,
-        this.#logger,
-      );
+      receiveOneBot12SideEvent(ev, {
+        emit: (name, payload) => this[endpointSpec].events.emit(name, payload),
+        endpointKey: this.#options.config.id,
+        caller: { callApi: (action, params) => callOnebot12Client({ client: this, action, params }) },
+        logger: this.#logger,
+      });
       return;
     }
-    const conversation = onebot12InboundConversation(String(this.#options.id), ev);
+    const conversation = { ...onebot12InboundConversation(String(this.#options.id), ev), endpoint: this[endpointSpec].identity };
     const content = formatInboundContent(ev);
     const nickname = senderNickname(ev);
     const mentioned = isBotMentioned(ev);
-    void this.emit('message.receive', {
+    void this[endpointSpec].events.message({
+      event: ev,
+      ...(typeof ev.time === 'number' ? { platformSentAt: ev.time * 1000 } : {}),
       conversation,
       message: { conversation, id: ev.message_id },
       content,
@@ -234,12 +250,8 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
       ws.on('message', (data) => {
         if (this.#ws !== ws) return;
         this.#lifecycle.notifyHeartbeatAck();
-        handleOneBot12WsMessage(data, {
-          endpointId: this.#options.config.id,
-          pending: this.#pending,
-          ingest: (event) => this.client.ingest(
-            event as Parameters<Onebot12Client['ingest']>[0],
-          ),
+        this.#rpc.receive(data, event => {
+          if (matchesOneBot12Self(this.#options.config, event)) this.ingest(event as Parameters<Onebot12Client['ingest']>[0]);
         });
       });
 
@@ -256,7 +268,7 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
         }
         if (this.#ws === ws) {
           this.#ws = undefined;
-          rejectAllPending(this.#pending);
+          this.#rpc.disconnect();
         }
         // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
         // 初始连接失败由 start() 的拒绝路径复位，不产生僵尸重连。
@@ -280,6 +292,6 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
   }
 
   #callAction(action: string, params: Record<string, unknown>) {
-    return callOneBot12WsAction(this.#ws, this.#pending, this.#requestId, action, params);
+    return this.#rpc.call({ action, params });
   }
 }

package/src/ws-transport.ts

@@ -1,86 +1,50 @@
-import { clearTimeout, setTimeout } from 'node:timers';
+import { createPendingRpc, type PendingRpc, type PendingRpcRequest } from 'zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import type {
-  OneBot12ActionRequest,
-  OneBot12ActionResponse,
-  OneBot12Event,
-} from './protocol.js';
-import {
-  type OneBot12PendingAction,
-  type OneBot12WsSocket,
-  WS_OPEN,
-} from './ws-types.js';
+import type { OneBot12ActionResponse, OneBot12Event, OneBot12Self } from './protocol.js';
+import { WS_OPEN, type OneBot12WsSocket } from './ws-types.js';
 
 const logger = getLogger('onebot12');
-
-export interface OneBot12WsMessageOptions {
+export interface OneBot12RpcOptions {
   readonly endpointId: string;
-  readonly pending: Map<string, OneBot12PendingAction>;
-  readonly ingest: (event: OneBot12Event) => void;
+  readonly signal?: AbortSignal;
+  /** Reads the lifecycle's selected socket; RPC never opens or reconnects it. */
+  readonly socket: () => OneBot12WsSocket | undefined;
+  readonly self: OneBot12Self;
 }
-
-export function handleOneBot12WsMessage(
-  data: unknown,
-  options: OneBot12WsMessageOptions,
-): void {
-  try {
-    const message = JSON.parse(decodeOneBot12WsPayload(data)) as
-      | OneBot12Event
-      | OneBot12ActionResponse;
-    if ('echo' in message && typeof message.echo === 'string') {
-      const response = message as OneBot12ActionResponse;
-      const pending = options.pending.get(response.echo!);
-      if (pending) {
-        options.pending.delete(response.echo!);
-        clearTimeout(pending.timeout);
-        pending.resolve(response);
-      }
-      return;
-    }
-    options.ingest(message as OneBot12Event);
-  } catch (error) {
-    logger.warn(formatCompact({
-      op: 'onebot12_parse_failed',
-      endpoint: options.endpointId,
-      error: error instanceof Error ? error.message : String(error),
-    }));
-  }
+export interface OneBot12Rpc {
+  call(request: PendingRpcRequest): Promise<OneBot12ActionResponse>;
+  receive(data: unknown, ingest: (event: OneBot12Event) => void): void;
+  disconnect: PendingRpc<OneBot12ActionResponse>['disconnect'];
+  dispose(): void;
+  readonly pendingCount: number;
 }
 
-export function callOneBot12WsAction(
-  ws: OneBot12WsSocket | undefined,
-  pending: Map<string, OneBot12PendingAction>,
-  requestId: { value: number },
-  action: string,
-  params: Record<string, unknown>,
-): Promise<OneBot12ActionResponse> {
-  if (!ws || ws.readyState !== WS_OPEN) {
-    return Promise.reject(new Error('WebSocket 未连接'));
-  }
-  const echo = `ob12_${++requestId.value}`;
-  const request: OneBot12ActionRequest = { action, params, echo };
-  return new Promise((resolve, reject) => {
-    const timeout = setTimeout(() => {
-      pending.delete(echo);
-      reject(new Error(`OneBot12 动作超时: ${action}`));
-    }, 30_000);
-    pending.set(echo, { resolve, reject, timeout });
-    ws.send(JSON.stringify(request));
+/** A Client's one request owner serves native SDK actions and framework operations. */
+export function createOneBot12Rpc(options: OneBot12RpcOptions): OneBot12Rpc {
+  const pending = createPendingRpc<OneBot12ActionResponse>({
+    signal: options.signal, requestPrefix: 'ob12_', timeoutMs: 30_000,
+    transport: () => { const socket = options.socket(); return socket?.readyState === WS_OPEN ? socket : undefined; },
+    serialize: request => JSON.stringify({ action: request.action, params: request.params ?? {}, echo: request.id, self: options.self }),
+  });
+  return Object.freeze({
+    call: pending.call, disconnect: pending.disconnect, dispose: pending.dispose,
+    get pendingCount() { return pending.pendingCount; },
+    receive(data: unknown, ingest: (event: OneBot12Event) => void) {
+      try {
+        const message = JSON.parse(decodeWsPayload(data)) as OneBot12Event | OneBot12ActionResponse;
+        if ('echo' in message && typeof message.echo === 'string') {
+          pending.accept({ id: message.echo, value: message as OneBot12ActionResponse }); return;
+        }
+        ingest(message as OneBot12Event);
+      } catch (error) {
+        logger.warn(formatCompact({ op: 'onebot12_parse_failed', endpoint: options.endpointId,
+          error: error instanceof Error ? error.message : String(error) }));
+      }
+    },
   });
 }
 
-export function rejectAllPending(
-  pending: Map<string, OneBot12PendingAction>,
-  message = '连接已关闭',
-): void {
-  for (const [, entry] of pending) {
-    clearTimeout(entry.timeout);
-    entry.reject(new Error(message));
-  }
-  pending.clear();
-}
-
-function decodeOneBot12WsPayload(data: unknown): string {
+export function decodeWsPayload(data: unknown): string {
   if (typeof data === 'string') return data;
   if (Buffer.isBuffer(data)) return data.toString();
   if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);

package/src/ws-types.ts

@@ -1,4 +1,3 @@
-import type { OneBot12ActionResponse } from './protocol.js';
 
 /** Minimal WS surface used by the endpoint (real `ws` or test mock). */
 export interface OneBot12WsSocket {
@@ -13,9 +12,3 @@ export interface OneBot12WsCreateOptions {
 }
 
 export const WS_OPEN = 1;
-
-export interface OneBot12PendingAction {
-  resolve: (value: OneBot12ActionResponse) => void;
-  reject: (err: Error) => void;
-  timeout: NodeJS.Timeout;
-}