@zhin.js/adapter-onebot12 1.1.0 → 1.1.2

package/lib/ws-transport.js

@@ -0,0 +1,58 @@
+import { clearTimeout, setTimeout } from 'node:timers';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { WS_OPEN, } from './ws-types.js';
+const logger = getLogger('onebot12');
+export function handleOneBot12WsMessage(data, options) {
+    try {
+        const message = JSON.parse(decodeOneBot12WsPayload(data));
+        if ('echo' in message && typeof message.echo === 'string') {
+            const response = message;
+            const pending = options.pending.get(response.echo);
+            if (pending) {
+                options.pending.delete(response.echo);
+                clearTimeout(pending.timeout);
+                pending.resolve(response);
+            }
+            return;
+        }
+        options.ingest(message);
+    }
+    catch (error) {
+        logger.warn(formatCompact({
+            op: 'onebot12_parse_failed',
+            endpoint: options.endpointId,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
+}
+export function callOneBot12WsAction(ws, pending, requestId, action, params) {
+    if (!ws || ws.readyState !== WS_OPEN) {
+        return Promise.reject(new Error('WebSocket 未连接'));
+    }
+    const echo = `ob12_${++requestId.value}`;
+    const request = { 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, message = '连接已关闭') {
+    for (const [, entry] of pending) {
+        clearTimeout(entry.timeout);
+        entry.reject(new Error(message));
+    }
+    pending.clear();
+}
+function decodeOneBot12WsPayload(data) {
+    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/lib/ws-types.d.ts

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

package/lib/wss-endpoint.js

@@ -9,7 +9,7 @@ import { receiveOneBot12SideEvent } from './side-event-dispatch.js';
 import { createOneBot12ContentPort } from './content-port.js';
 import { callOnebot12Client, createOnebot12EndpointClient, forwardOnebot12ClientEvents } from './client.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
-import { WS_OPEN } from './ws-types.js';
+import { callOneBot12WsAction, handleOneBot12WsMessage, rejectAllPending, } from './ws-transport.js';
 export class OneBot12WssEndpoint extends ClientEndpoint {
     client;
     #logger;
@@ -19,17 +19,18 @@ export class OneBot12WssEndpoint extends ClientEndpoint {
     content;
     #ws;
     #wsRelease;
-    #lifecycle;
-    #requestId = 0;
+    #connectionLifecycle;
+    #connectionTask = Promise.resolve();
+    #requestId = { value: 0 };
     #pending = new Map();
+    #started = false;
     constructor(options) {
         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, params) => callOnebot12Client(this.client, action, params);
@@ -41,6 +42,8 @@ export class OneBot12WssEndpoint extends ClientEndpoint {
         }, (_name, error) => this.#warnPlatformEvent(error));
     }
     async start() {
+        if (this.#started)
+            return;
         if (!this.#options.config.access_token) {
             // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
             this.#logger.warn(formatCompact({
@@ -50,23 +53,19 @@ export class OneBot12WssEndpoint extends ClientEndpoint {
                 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,
@@ -76,12 +75,13 @@ export class OneBot12WssEndpoint extends ClientEndpoint {
     }
     async stop() {
         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 }) {
         const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => callOnebot12Client(this.client, action, params), (error) => {
@@ -140,33 +140,46 @@ export class OneBot12WssEndpoint extends ClientEndpoint {
             error: error instanceof Error ? error.message : String(error),
         }));
     }
-    #acceptConnection(connection) {
+    async #acceptConnection(connection) {
         if (!verifyOneBotAccessToken(this.#options.config.access_token, connection.request)) {
             connection.socket.close(4003, 'Unauthorized');
             return;
         }
         const socket = connection.socket;
-        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),
+                });
+            });
+            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,
@@ -174,49 +187,7 @@ export class OneBot12WssEndpoint extends ClientEndpoint {
             peer: connection.request.socket.remoteAddress,
         }));
     }
-    #onMessage(data) {
-        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);
-            if ('echo' in msg && typeof msg.echo === 'string') {
-                const resp = msg;
-                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);
-        }
-        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, params) {
-        if (!this.#ws || this.#ws.readyState !== WS_OPEN) {
-            return Promise.reject(new Error('WebSocket 未连接'));
-        }
-        const echo = `ob12_${++this.#requestId}`;
-        const req = { 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));
-        });
+        return callOneBot12WsAction(this.#ws, this.#pending, this.#requestId, action, params);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot12",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Zhin.js OneBot 12 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -19,7 +19,7 @@
     "schema.json",
     "src",
     "lib",
-    "agent",
+    "skills",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -42,26 +42,27 @@
     "@imhelper/onebot-v12": "1.0.7",
     "imhelper": "1.0.7",
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.12",
-    "@zhin.js/core": "1.1.35",
-    "@zhin.js/feature-kit": "1.1.0",
-    "@zhin.js/host-http": "1.1.0",
-    "@zhin.js/im-contract": "1.1.0",
-    "@zhin.js/logger": "1.1.0"
+    "@zhin.js/adapter": "1.1.14",
+    "@zhin.js/core": "1.1.37",
+    "@zhin.js/feature-kit": "1.1.1",
+    "@zhin.js/host-http": "1.1.1",
+    "@zhin.js/im-contract": "1.1.1",
+    "@zhin.js/logger": "1.1.1",
+    "@zhin.js/skill": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.1.0",
-    "zhin.js": "1.1.0"
+    "@zhin.js/host-http": "1.1.1",
+    "zhin.js": "1.1.2"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "^1.1.12",
-    "@zhin.js/command": "^1.1.0",
-    "@zhin.js/core": "^1.1.35",
-    "zhin.js": "^1.1.0"
+    "@zhin.js/adapter": "^1.1.14",
+    "@zhin.js/command": "^1.1.1",
+    "@zhin.js/core": "^1.1.37",
+    "zhin.js": "^1.1.2"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -97,6 +98,10 @@
       {
         "package": "@zhin.js/command",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.js

@@ -8,7 +8,7 @@ export default definePlugin({
         displayName: 'OneBot 12 Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（onebot12.endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（onebot12 endpoint list 的"运行中"数据源）
         context.resources.provide(onebot12RuntimeStateToken, createEndpointRuntimeState());
     },
 });

package/schema.json

@@ -41,10 +41,11 @@
     },
     "endpoints": {
       "type": "array",
+      "minItems": 1,
       "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
-        "additionalProperties": true,
+        "additionalProperties": false,
         "properties": {
           "master": {
             "type": [
@@ -64,6 +65,14 @@
             },
             "description": "本 endpoint 的 trusted 列表"
           },
+          "connection": {
+            "type": "string",
+            "enum": [
+              "ws",
+              "webhook",
+              "wss"
+            ]
+          },
           "url": {
             "type": "string",
             "description": "OneBot implementation WebSocket URL (required for connection: ws)"
@@ -80,6 +89,15 @@
             "type": "string",
             "description": "OneBot access token"
           },
+          "reconnect_interval": {
+            "type": "number"
+          },
+          "heartbeat_interval": {
+            "type": "number"
+          },
+          "commandPrefix": {
+            "type": "string"
+          },
           "id": {
             "type": "string",
             "description": "OneBot12 bot name"

package/src/client.ts

@@ -31,7 +31,7 @@ export function createOnebot12EndpointClient(
 ): OneBotV12Client {
   const baseUrl = config.connection === 'ws'
     ? config.url.replace(/^ws(s?):/, 'http$1:')
-    : config.connection === 'webhook' && config.api_url
+    : config.connection === 'webhook'
       ? config.api_url
       : 'http://localhost';
   return new OneBotV12Client({

package/src/index.ts

@@ -16,7 +16,6 @@ export {
   uploadOneBot12MediaSegments,
   type OneBot12ActionRequest,
   type OneBot12ActionResponse,
-  type OneBot12AdapterConfig,
   type OneBot12CallAction,
   type OneBot12ConfigBase,
   type OneBot12EndpointConfig,

package/src/onebot12-runtime-state.ts

@@ -1,6 +1,6 @@
 /**
  * OneBot12 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `onebot12.endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `onebot12 endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
 

package/src/protocol.ts

@@ -3,37 +3,21 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://12.onebot.dev/
  */
-import { isMediaRef, type MediaRef } from '@zhin.js/core';
-import type { ConversationRef } from '@zhin.js/im-contract';
+import { isMediaRef, type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('onebot12');
 
-/** Transitional legacy endpoint row (`endpoints[]` with `context: onebot12`). */
-export interface OneBot12LegacyEndpointRow {
-  readonly context?: string;
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface OneBot12EndpointConfig {
   readonly connection?: 'ws' | 'webhook' | 'wss';
-  readonly id?: string;
-  readonly access_token?: string;
-  readonly url?: string;
-  readonly path?: string;
-  readonly api_url?: string;
-  readonly reconnect_interval?: number;
-  readonly heartbeat_interval?: number;
-}
-
-/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
-export interface OneBot12AdapterConfig {
-  readonly connection?: 'ws' | 'webhook' | 'wss';
-  readonly id?: string;
+  readonly id: string;
   readonly access_token?: string;
   readonly url?: string;
   readonly path?: string;
   readonly api_url?: string;
   readonly reconnect_interval?: number;
   readonly heartbeat_interval?: number;
-  /** Transitional: legacy root `endpoints[]` with `context: onebot12`. */
-  readonly endpoints?: ReadonlyArray<OneBot12LegacyEndpointRow>;
 }
 
 export interface OneBot12ConfigBase {
@@ -54,7 +38,7 @@ export interface OneBot12WsConfig extends OneBot12ConfigBase {
 export interface OneBot12WebhookConfig extends OneBot12ConfigBase {
   readonly connection: 'webhook';
   readonly path: string;
-  readonly api_url?: string;
+  readonly api_url: string;
 }
 
 /** 反向 WebSocket：httpHostToken WS upgrade 入站/出站 */
@@ -65,7 +49,6 @@ export interface OneBot12WssConfig extends OneBot12ConfigBase {
 }
 
 export type ResolvedOneBot12Config = OneBot12WsConfig | OneBot12WebhookConfig | OneBot12WssConfig;
-export type OneBot12EndpointConfig = ResolvedOneBot12Config;
 
 export interface OneBot12Self {
   readonly platform: string;
@@ -119,68 +102,67 @@ export interface OneBot12WireSegment {
   readonly data?: Record<string, unknown>;
 }
 
-export function resolveOneBot12Config(config: OneBot12AdapterConfig = {}): ResolvedOneBot12Config {
-  const entry = config.endpoints?.find((item) => item.context === 'onebot12');
-  const connection = config.connection
-    ?? entry?.connection
-    ?? 'ws';
-  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;
+export function resolveOneBot12Config(config: OneBot12EndpointConfig): ResolvedOneBot12Config {
+  const connection = config.connection ?? 'ws';
+  const id = requiredEndpointField(config.id, 'id');
+  const access_token = optionalEndpointField(config.access_token);
 
   if (connection === 'ws') {
-    const url = config.url ?? entry?.url;
-    if (!url) {
-      throw new TypeError(
-        'OneBot12 connection:ws requires url (plugins.<key>.url or endpoints with context: onebot12)',
-      );
-    }
+    const url = requiredEndpointField(config.url, 'url');
     return {
       context: 'onebot12',
       connection: 'ws',
       id,
       access_token,
       url,
-      reconnect_interval: config.reconnect_interval ?? entry?.reconnect_interval ?? 5000,
-      heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+      reconnect_interval: config.reconnect_interval ?? 5000,
+      heartbeat_interval: config.heartbeat_interval ?? 30_000,
     };
   }
 
   if (connection === 'webhook') {
-    const path = config.path ?? entry?.path;
-    if (!path) {
-      throw new TypeError('OneBot12 connection:webhook requires path');
-    }
+    const path = requiredEndpointField(config.path, 'path');
+    const api_url = requiredEndpointField(config.api_url, 'api_url');
     return {
       context: 'onebot12',
       connection: 'webhook',
       id,
       access_token,
       path,
-      api_url: config.api_url ?? entry?.api_url,
+      api_url,
     };
   }
 
   if (connection === 'wss') {
-    const path = config.path ?? entry?.path;
-    if (!path) {
-      throw new TypeError('OneBot12 connection:wss requires path');
-    }
+    const path = requiredEndpointField(config.path, 'path');
     return {
       context: 'onebot12',
       connection: 'wss',
       id,
       access_token,
       path,
-      heartbeat_interval: config.heartbeat_interval ?? entry?.heartbeat_interval ?? 30_000,
+      heartbeat_interval: config.heartbeat_interval ?? 30_000,
     };
   }
 
   throw new TypeError(`Unknown OneBot12 connection: ${String(connection)}`);
 }
 
+function requiredEndpointField(
+  value: unknown,
+  field: 'id' | 'url' | 'path' | 'api_url',
+): string {
+  const resolved = optionalEndpointField(value);
+  if (!resolved) {
+    throw new TypeError(`OneBot12 endpoint requires a non-empty ${field}`);
+  }
+  return resolved;
+}
+
+function optionalEndpointField(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
 /** 判断是否为消息事件（type=message） */
 export function isMessageEvent(
   ev: OneBot12Event,
@@ -234,10 +216,29 @@ export function formatInboundContent(ev: OneBot12Event): string {
       .join('');
   }
   return typeof ev.alt_message === 'string'
-    ? ev.alt_message.replace(/\[[^\]]*(?:image|audio|video|file)[^\]]*\]/gi, '').trim()
+    ? stripMediaPlaceholders(ev.alt_message).trim()
     : '';
 }
 
+function stripMediaPlaceholders(input: string): string {
+  const mediaNames = ['image', 'audio', 'video', 'file'];
+  let result = '';
+  let cursor = 0;
+  while (cursor < input.length) {
+    const start = input.indexOf('[', cursor);
+    if (start < 0) return result + input.slice(cursor);
+    const end = input.indexOf(']', start + 1);
+    if (end < 0) return result + input.slice(cursor);
+    result += input.slice(cursor, start);
+    const placeholder = input.slice(start + 1, end).toLowerCase();
+    if (!mediaNames.some((name) => placeholder.includes(name))) {
+      result += input.slice(start, end + 1);
+    }
+    cursor = end + 1;
+  }
+  return result;
+}
+
 /**
  * Runtime Message sender 必须是用户 ID（agent bridge 以 sender 与 endpointMaster 比对）。
  * 显示名经 {@link senderNickname} 放入 metadata.nickname。

package/src/webhook.ts

@@ -131,12 +131,8 @@ export class OneBot12WebhookEndpoint extends ClientEndpoint<Onebot12Client> {
     action: string,
     params: Record<string, unknown> = {},
   ): Promise<import('@imhelper/onebot-v12').OneBotV12Response> {
-    const apiUrl = this.#options.config.api_url;
-    if (!apiUrl) {
-      throw new Error('OneBot12 connection:webhook requires api_url for outbound api');
-    }
     return this.#callAction(
-      { url: apiUrl, access_token: this.#options.config.access_token },
+      { url: this.#options.config.api_url, access_token: this.#options.config.access_token },
       action,
       params,
     );