@zhin.js/adapter-onebot12 1.1.0 → 1.1.3

package/src/ws-endpoint.ts

@@ -2,7 +2,6 @@
  * OneBot12 WS client endpoint — outbound connect to OneBot implementation.
  */
 import WebSocket from 'ws';
-import { clearTimeout } from 'node:timers';
 import {
   ClientEndpoint,
   createRecallEndpointControl,
@@ -27,8 +26,6 @@ import {
   senderNickname,
   senderUserId,
   uploadOneBot12MediaSegments,
-  type OneBot12ActionRequest,
-  type OneBot12ActionResponse,
   type OneBot12Event,
   type OneBot12WsConfig,
 } from './protocol.js';
@@ -36,10 +33,15 @@ import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
 import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents, type Onebot12Client } from './client.js';
 import {
+  type OneBot12PendingAction,
   type OneBot12WsCreateOptions,
   type OneBot12WsSocket,
-  WS_OPEN,
 } from './ws-types.js';
+import {
+  callOneBot12WsAction,
+  handleOneBot12WsMessage,
+  rejectAllPending,
+} from './ws-transport.js';
 
 export interface OneBot12WsEndpointOptions {
   readonly id: CapabilityId;
@@ -60,12 +62,8 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
   readonly content;
   readonly #lifecycle: EndpointLifecycle;
   #ws?: OneBot12WsSocket;
-  #requestId = 0;
-  #pending = new Map<string, {
-    resolve: (value: OneBot12ActionResponse) => void;
-    reject: (err: Error) => void;
-    timeout: NodeJS.Timeout;
-  }>();
+  #requestId = { value: 0 };
+  #pending = new Map<string, OneBot12PendingAction>();
 
   constructor(options: OneBot12WsEndpointOptions) {
     super();
@@ -118,11 +116,7 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
     this.close();
     // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
     await this.#lifecycle.stop();
-    for (const [, pending] of this.#pending) {
-      clearTimeout(pending.timeout);
-      pending.reject(new Error('连接已关闭'));
-    }
-    this.#pending.clear();
+    rejectAllPending(this.#pending);
     this.#ws = undefined;
   }
 
@@ -238,7 +232,15 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
       });
 
       ws.on('message', (data) => {
-        this.#onMessage(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],
+          ),
+        });
       });
 
       ws.on('close', (code, reason) => {
@@ -252,6 +254,10 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
           settled = true;
           reject(new Error(`OneBot12 WS 关闭: ${codeNum} ${reasonStr}`));
         }
+        if (this.#ws === ws) {
+          this.#ws = undefined;
+          rejectAllPending(this.#pending);
+        }
         // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
         // 初始连接失败由 start() 的拒绝路径复位，不产生僵尸重连。
         handle.notifyClosed(`OneBot12 WS 关闭: ${codeNum} ${reasonStr || 'closed'}`);
@@ -273,49 +279,7 @@ export class OneBot12WsEndpoint extends ClientEndpoint<Onebot12Client> {
     });
   }
 
-  #onMessage(data: unknown): void {
-    try {
-      const raw = typeof data === 'string'
-        ? data
-        : Buffer.isBuffer(data)
-          ? data.toString()
-          : data instanceof ArrayBuffer
-            ? new TextDecoder().decode(data)
-            : String(data ?? '');
-      const msg = JSON.parse(raw) as OneBot12Event | OneBot12ActionResponse;
-      if ('echo' in msg && typeof (msg as OneBot12ActionResponse).echo === 'string') {
-        const resp = msg as OneBot12ActionResponse;
-        const pending = this.#pending.get(resp.echo!);
-        if (pending) {
-          this.#pending.delete(resp.echo!);
-          clearTimeout(pending.timeout);
-          pending.resolve(resp);
-        }
-        return;
-      }
-      this.client.ingest(msg as Parameters<Onebot12Client['ingest']>[0]);
-    } catch (error) {
-      this.#logger.warn(formatCompact({
-        op: 'onebot12_parse_failed',
-        endpoint: this.#options.config.id,
-        error: error instanceof Error ? error.message : String(error),
-      }));
-    }
-  }
-
-  #callAction(action: string, params: Record<string, unknown>): Promise<OneBot12ActionResponse> {
-    if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
-      return Promise.reject(new Error('WebSocket 未连接'));
-    }
-    const echo = `ob12_${++this.#requestId}`;
-    const req: OneBot12ActionRequest = { action, params, echo };
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.#pending.delete(echo);
-        reject(new Error(`OneBot12 动作超时: ${action}`));
-      }, 30_000);
-      this.#pending.set(echo, { resolve, reject, timeout });
-      this.#ws!.send(JSON.stringify(req));
-    });
+  #callAction(action: string, params: Record<string, unknown>) {
+    return callOneBot12WsAction(this.#ws, this.#pending, this.#requestId, action, params);
   }
 }

package/src/ws-transport.ts

@@ -0,0 +1,88 @@
+import { clearTimeout, setTimeout } from 'node:timers';
+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';
+
+const logger = getLogger('onebot12');
+
+export interface OneBot12WsMessageOptions {
+  readonly endpointId: string;
+  readonly pending: Map<string, OneBot12PendingAction>;
+  readonly ingest: (event: OneBot12Event) => void;
+}
+
+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 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));
+  });
+}
+
+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 {
+  if (typeof data === 'string') return data;
+  if (Buffer.isBuffer(data)) return data.toString();
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+  return String(data ?? '');
+}

package/src/ws-types.ts

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

package/src/wss-endpoint.ts

@@ -24,8 +24,6 @@ import {
   senderNickname,
   senderUserId,
   uploadOneBot12MediaSegments,
-  type OneBot12ActionRequest,
-  type OneBot12ActionResponse,
   type OneBot12Event,
   type OneBot12WssConfig,
 } from './protocol.js';
@@ -33,7 +31,12 @@ import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
 import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents, type Onebot12Client } from './client.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
-import { type OneBot12WsSocket, WS_OPEN } from './ws-types.js';
+import { type OneBot12PendingAction, type OneBot12WsSocket } from './ws-types.js';
+import {
+  callOneBot12WsAction,
+  handleOneBot12WsMessage,
+  rejectAllPending,
+} from './ws-transport.js';
 
 export interface OneBot12WssEndpointOptions {
   readonly id: CapabilityId;
@@ -51,22 +54,19 @@ export class OneBot12WssEndpoint extends ClientEndpoint<Onebot12Client> {
   readonly content;
   #ws?: OneBot12WsSocket;
   #wsRelease?: () => void;
-  readonly #lifecycle: EndpointLifecycle;
-  #requestId = 0;
-  #pending = new Map<string, {
-    resolve: (value: OneBot12ActionResponse) => void;
-    reject: (err: Error) => void;
-    timeout: NodeJS.Timeout;
-  }>();
+  readonly #connectionLifecycle: EndpointLifecycle;
+  #connectionTask = Promise.resolve();
+  #requestId = { value: 0 };
+  #pending = new Map<string, OneBot12PendingAction>();
+  #started = false;
 
   constructor(options: OneBot12WssEndpointOptions) {
     super();
     this.#logger = getAdapterLogger('onebot12', options.config.id);
     this.#options = options;
-    this.#lifecycle = createEndpointLifecycle({
-      name: options.config.id,
+    this.#connectionLifecycle = createEndpointLifecycle({
+      name: `${options.config.id}:inbound`,
       reconnect: false,
-      heartbeat: { intervalMs: options.config.heartbeat_interval },
     });
     this.client = createOnebot12EndpointClient(options.config, (action, params) => this.#callAction(action, params ?? {}));
     const callApi = (action: string, params?: Record<string, unknown>) => callOnebot12Client(this.client, action, params);
@@ -82,6 +82,7 @@ export class OneBot12WssEndpoint extends ClientEndpoint<Onebot12Client> {
   }
 
   async start(): Promise<void> {
+    if (this.#started) return;
     if (!this.#options.config.access_token) {
       // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
       this.#logger.warn(formatCompact({
@@ -91,22 +92,19 @@ export class OneBot12WssEndpoint extends ClientEndpoint<Onebot12Client> {
         error: 'missing access_token',
       }));
     }
-    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;
-      });
+    const handle = this.#options.http.ws(this.#options.config.path);
+    this.#wsRelease = handle.onConnection((connection) => {
+      this.#connectionTask = this.#connectionTask
+        .then(() => this.#acceptConnection(connection))
+        .catch((error) => {
+          this.#logger.warn(formatCompact({
+            op: 'wss_connection_failed',
+            endpoint: this.#options.config.id,
+            error: error instanceof Error ? error.message : String(error),
+          }));
+        });
     });
+    this.#started = true;
     this.#logger.info(formatCompact({
       op: 'listen',
       endpoint: this.#options.config.id,
@@ -117,12 +115,13 @@ export class OneBot12WssEndpoint extends ClientEndpoint<Onebot12Client> {
 
   async stop(): Promise<void> {
     this.close();
-    await this.#lifecycle.stop();
-    for (const [, pending] of this.#pending) {
-      clearTimeout(pending.timeout);
-      pending.reject(new Error('连接已关闭'));
-    }
-    this.#pending.clear();
+    this.#wsRelease?.();
+    this.#wsRelease = undefined;
+    await this.#connectionTask;
+    await this.#connectionLifecycle.stop();
+    rejectAllPending(this.#pending);
+    this.#ws = undefined;
+    this.#started = false;
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
@@ -195,32 +194,45 @@ export class OneBot12WssEndpoint extends ClientEndpoint<Onebot12Client> {
     }));
   }
 
-  #acceptConnection(connection: WsConnection): void {
+  async #acceptConnection(connection: WsConnection): Promise<void> {
     if (!verifyOneBotAccessToken(this.#options.config.access_token, connection.request)) {
       connection.socket.close(4003, 'Unauthorized');
       return;
     }
     const socket = connection.socket as unknown as OneBot12WsSocket;
-    if (this.#ws) {
-      try {
-        this.#ws.close();
-      } catch {
-        /* ignore */
-      }
-    }
-    this.#ws = socket;
-    this.#lifecycle.startHeartbeat(() => {
-      this.#callAction('get_status', {}).catch(() => {});
-    });
-    socket.on('message', (data) => {
-      this.#lifecycle.notifyHeartbeatAck();
-      this.#onMessage(data);
-    });
-    socket.on('close', () => {
-      if (this.#ws === socket) {
-        this.#ws = undefined;
-        this.#lifecycle.stopHeartbeat();
-      }
+    await this.#connectionLifecycle.stop();
+    rejectAllPending(this.#pending, '连接已替换');
+    await this.#connectionLifecycle.start(async (lifecycleHandle) => {
+      this.#ws = socket;
+      lifecycleHandle.onForceClose(() => {
+        try {
+          socket.close();
+        } catch {
+          /* ignore */
+        }
+        if (this.#ws === socket) this.#ws = undefined;
+      });
+      this.#connectionLifecycle.startHeartbeat(() => {
+        this.#callAction('get_status', {}).catch(() => {});
+      }, this.#options.config.heartbeat_interval);
+      socket.on('message', (data) => {
+        if (this.#ws !== socket) return;
+        this.#connectionLifecycle.notifyHeartbeatAck();
+        handleOneBot12WsMessage(data, {
+          endpointId: this.#options.config.id,
+          pending: this.#pending,
+          ingest: (event) => this.client.ingest(
+            event as Parameters<Onebot12Client['ingest']>[0],
+          ),
+        });
+      });
+      socket.on('close', () => {
+        if (this.#ws === socket) {
+          this.#ws = undefined;
+          rejectAllPending(this.#pending);
+        }
+        lifecycleHandle.notifyClosed(new Error('OneBot12 reverse WebSocket closed'));
+      });
     });
     this.#logger.debug(formatCompact({
       endpoint: this.#options.config.id,
@@ -229,50 +241,8 @@ export class OneBot12WssEndpoint extends ClientEndpoint<Onebot12Client> {
     }));
   }
 
-  #onMessage(data: unknown): void {
-    try {
-      const raw = typeof data === 'string'
-        ? data
-        : Buffer.isBuffer(data)
-          ? data.toString()
-          : data instanceof ArrayBuffer
-            ? new TextDecoder().decode(data)
-            : String(data ?? '');
-      const msg = JSON.parse(raw) as OneBot12Event | OneBot12ActionResponse;
-      if ('echo' in msg && typeof (msg as OneBot12ActionResponse).echo === 'string') {
-        const resp = msg as OneBot12ActionResponse;
-        const pending = this.#pending.get(resp.echo!);
-        if (pending) {
-          this.#pending.delete(resp.echo!);
-          clearTimeout(pending.timeout);
-          pending.resolve(resp);
-        }
-        return;
-      }
-      this.client.ingest(msg as Parameters<Onebot12Client['ingest']>[0]);
-    } catch (error) {
-      this.#logger.warn(formatCompact({
-        op: 'onebot12_parse_failed',
-        endpoint: this.#options.config.id,
-        error: error instanceof Error ? error.message : String(error),
-      }));
-    }
-  }
-
-  #callAction(action: string, params: Record<string, unknown>): Promise<OneBot12ActionResponse> {
-    if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
-      return Promise.reject(new Error('WebSocket 未连接'));
-    }
-    const echo = `ob12_${++this.#requestId}`;
-    const req: OneBot12ActionRequest = { action, params, echo };
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.#pending.delete(echo);
-        reject(new Error(`OneBot12 动作超时: ${action}`));
-      }, 30_000);
-      this.#pending.set(echo, { resolve, reject, timeout });
-      this.#ws!.send(JSON.stringify(req));
-    });
+  #callAction(action: string, params: Record<string, unknown>) {
+    return callOneBot12WsAction(this.#ws, this.#pending, this.#requestId, action, params);
   }
 
 }

package/agent/skills/onebot12.md

@@ -1,36 +0,0 @@
----
-name: onebot12
-platforms:
-  - onebot12
-description: >-
-  OneBot 12 协议适配器：支持 WebSocket 正向连接、Webhook 回调和反向 WebSocket
-  三种连接模式，兼容 OneBot 12 标准协议。纯消息通道，无额外 AI 工具。
-  支持私聊、群聊、频道消息。
-keywords:
-  - onebot12
-  - onebot
-  - adapter:onebot12
-  - protocol
-  - websocket
-  - webhook
-  - 协议
-tags:
-  - onebot12
-  - protocol
-  - adapter
-tools: []
----
-
-# OneBot 12 协议适配器
-
-纯协议适配器，收发消息。无 AI 工具可调用。
-
-## 连接模式
-
-- **WS 正向**：Bot 主动连接 OneBot 12 服务端
-- **Webhook**：OneBot 12 向配置的 URL 推送事件
-- **WS 反向**：OneBot 12 主动连接 Endpoint 的 WS 服务端
-
-## 与 OneBot11 的区别
-
-OneBot 12 标准化了事件格式、消息段类型和 API 响应结构。如果需要群管理等 AI 工具，使用 OneBot11 适配器。

package/commands/endpoint/add/[id].ts

@@ -1,3 +0,0 @@
-import { onebot12EndpointCommands } from '../../../src/onebot12-endpoint-commands.js';
-
-export default onebot12EndpointCommands.add;

package/commands/endpoint/list.ts

@@ -1,3 +0,0 @@
-import { onebot12EndpointCommands } from '../../src/onebot12-endpoint-commands.js';
-
-export default onebot12EndpointCommands.list;

package/commands/endpoint/remove/[id].ts

@@ -1,3 +0,0 @@
-import { onebot12EndpointCommands } from '../../../src/onebot12-endpoint-commands.js';
-
-export default onebot12EndpointCommands.remove;

package/lib/onebot12-endpoint-commands.d.ts

@@ -1 +0,0 @@
-export declare const onebot12EndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;