@zhin.js/adapter-onebot11 4.0.1 → 4.0.3

package/lib/ws-transport.js

@@ -0,0 +1,74 @@
+import { clearInterval, clearTimeout, setInterval, setTimeout } from 'node:timers';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { WS_OPEN, } from './ws-types.js';
+const logger = getLogger('onebot11');
+export function decodeWsPayload(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 ?? '');
+}
+export function handleOneBot11WsMessage(data, options) {
+    try {
+        const raw = decodeWsPayload(data);
+        const msg = JSON.parse(raw);
+        if ('echo' in msg && typeof msg.echo === 'string') {
+            const resp = msg;
+            const pending = options.pending.get(resp.echo);
+            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}`));
+            }
+            return;
+        }
+        options.admit(msg);
+    }
+    catch (error) {
+        logger.warn(formatCompact({
+            op: 'onebot11_parse_failed',
+            endpoint: options.endpointName,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
+}
+export function callOneBot11WsAction(ws, pending, requestId, action, params) {
+    if (!ws || ws.readyState !== WS_OPEN) {
+        return Promise.reject(new Error('WebSocket 未连接'));
+    }
+    const echo = `ob11_${++requestId.value}`;
+    const req = { action, params, echo };
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            pending.delete(echo);
+            reject(new Error(`OneBot11 动作超时: ${action}`));
+        }, 30_000);
+        pending.set(echo, { resolve, reject, timeout });
+        ws.send(JSON.stringify(req));
+    });
+}
+export function startOneBot11Heartbeat(ws, intervalMs, existingTimer) {
+    if (existingTimer)
+        clearInterval(existingTimer);
+    return setInterval(() => {
+        try {
+            ws?.ping?.();
+        }
+        catch {
+            /* ignore */
+        }
+    }, intervalMs);
+}
+export function rejectAllPending(pending, message = '连接已关闭') {
+    for (const [, entry] of pending) {
+        clearTimeout(entry.timeout);
+        entry.reject(new Error(message));
+    }
+    pending.clear();
+}

package/lib/ws-types.d.ts

@@ -0,0 +1,17 @@
+/** Minimal WS surface used by the endpoint (real `ws` or test mock). */
+export interface OneBot11WsSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    ping?(): void;
+    on(event: 'open' | 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+}
+export interface OneBot11WsCreateOptions {
+    readonly headers?: Record<string, string>;
+}
+export declare const WS_OPEN = 1;
+export interface OneBot11PendingAction {
+    resolve: (value: unknown) => void;
+    reject: (err: Error) => void;
+    timeout: NodeJS.Timeout;
+}

package/lib/ws-types.js

@@ -0,0 +1 @@
+export const WS_OPEN = 1;

package/lib/wss-auth.d.ts

@@ -0,0 +1,2 @@
+import type { IncomingMessage } from 'node:http';
+export declare function verifyOneBotAccessToken(accessToken: string | undefined, request: IncomingMessage): boolean;

package/lib/wss-auth.js

@@ -0,0 +1,16 @@
+export function verifyOneBotAccessToken(accessToken, request) {
+    if (!accessToken)
+        return true;
+    const auth = request.headers.authorization ?? '';
+    if (auth === `Bearer ${accessToken}`)
+        return true;
+    try {
+        const url = new URL(request.url ?? '/', 'http://localhost');
+        if (url.searchParams.get('access_token') === accessToken)
+            return true;
+    }
+    catch {
+        /* ignore */
+    }
+    return false;
+}

package/lib/wss-endpoint.d.ts

@@ -0,0 +1,26 @@
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type OneBot11Event, type OneBot11WssConfig } from './protocol.js';
+export interface OneBot11WssEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: OneBot11WssConfig;
+}
+export declare class OneBot11WssEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: OneBot11WssEndpointOptions);
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+    setTitle(groupId: number, userId: number, title: string, duration?: number): Promise<boolean>;
+    admit(ev: OneBot11Event): void;
+}

package/lib/wss-endpoint.js

@@ -0,0 +1,143 @@
+/**
+ * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
+ */
+import { clearInterval } from 'node:timers';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { registerOnebot11AgentEndpoint } from './onebot11-agent-deps.js';
+import { buildSendAction, formatInboundContent, formatInboundMetadata, formatInboundTarget, formatOutboundSegments, isMessageEvent, senderUserId, } from './protocol.js';
+import { verifyOneBotAccessToken } from './wss-auth.js';
+import { callOneBot11WsAction, handleOneBot11WsMessage, rejectAllPending, startOneBot11Heartbeat, } from './ws-transport.js';
+const logger = getLogger('onebot11');
+export class OneBot11WssEndpoint {
+    #options;
+    #ws;
+    #wsRelease;
+    #heartbeatTimer;
+    #requestId = { value: 0 };
+    #pending = new Map();
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#unregisterAgent = registerOnebot11AgentEndpoint(this.#options.config.name, this);
+        const handle = this.#options.http.ws(this.#options.config.path);
+        this.#wsRelease = handle.onConnection((connection) => {
+            this.#acceptConnection(connection);
+        });
+        logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.name,
+            mode: 'wss',
+            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;
+        }
+        rejectAllPending(this.#pending);
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#ws = undefined;
+        }
+        this.#started = false;
+    }
+    async send({ target, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(target, message);
+        const data = await this.callApi(action, params);
+        return data?.message_id != null ? String(data.message_id) : '';
+    }
+    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 || !isMessageEvent(ev))
+            return;
+        const target = formatInboundTarget(ev);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target,
+            content: formatInboundContent(ev),
+            sender: senderUserId(ev),
+            id: String(ev.message_id),
+            metadata: formatInboundMetadata(ev, this.#options.config.name),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'onebot11_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #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.#heartbeatTimer = startOneBot11Heartbeat(this.#ws, this.#options.config.heartbeat_interval, this.#heartbeatTimer);
+        socket.on('message', (data) => {
+            handleOneBot11WsMessage(data, {
+                endpointName: this.#options.config.name,
+                pending: this.#pending,
+                admit: (ev) => this.admit(ev),
+            });
+        });
+        socket.on('close', () => {
+            if (this.#ws === socket) {
+                this.#ws = undefined;
+                if (this.#heartbeatTimer) {
+                    clearInterval(this.#heartbeatTimer);
+                    this.#heartbeatTimer = undefined;
+                }
+            }
+        });
+        logger.debug(formatCompact({
+            endpoint: this.#options.config.name,
+            mode: 'wss',
+            peer: connection.request.socket.remoteAddress,
+        }));
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-onebot11",
-  "version": "4.0.1",
-  "description": "Zhin.js adapter for OneBot v11 protocol",
+  "version": "4.0.3",
+  "description": "Zhin.js OneBot 11 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,12 +13,12 @@
     }
   },
   "files": [
+    "adapters",
+    "plugin.ts",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "skills",
-    "plugin.yml",
+    "agent",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -32,38 +32,53 @@
     "qq",
     "chatbot"
   ],
-  "author": {
-    "name": "lc-cn",
-    "email": "admin@liucl.cn",
-    "url": "https://github.com/lc-cn"
-  },
   "license": "MIT",
   "repository": {
-    "url": "git+https://github.com/zhinjs/zhin.git",
     "type": "git",
+    "url": "https://github.com/zhinjs/zhin",
     "directory": "plugins/adapters/onebot11"
   },
   "dependencies": {
-    "ws": "^8.21.0"
+    "ws": "^8.21.0",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/plugin-runtime": "1.0.1",
+    "@zhin.js/logger": "1.0.75"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.92",
-    "@zhin.js/client": "2.0.4",
-    "@zhin.js/host-router": "2.0.2",
-    "zhin.js": "4.1.1"
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.0.4",
+    "@zhin.js/host-http": "1.0.1"
   },
   "peerDependencies": {
-    "@zhin.js/host-router": "2.0.2",
-    "zhin.js": "4.1.1"
+    "zod": "^4.0.0",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/plugin-runtime": "1.0.1",
+    "zhin.js": "4.1.3",
+    "@zhin.js/agent": "1.0.4"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
+    "zhin.js": {
+      "optional": true
+    },
+    "@zhin.js/agent": {
+      "optional": true
+    },
+    "zod": {
       "optional": true
     }
   },
+  "author": {
+    "name": "lc-cn",
+    "email": "admin@liucl.cn",
+    "url": "https://github.com/lc-cn"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -71,8 +86,23 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.ts",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "clean": "rimraf lib"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/onebot11/tests"
   }
 }

package/plugin.ts

@@ -0,0 +1,13 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+import { registerDefaultScenePlatformPermitChecker } from '@zhin.js/core';
+
+export default definePlugin({
+  name: 'onebot11',
+  metadata: {
+    displayName: 'OneBot 11 Adapter',
+  },
+  setup() {
+    // 平台权限门禁：scene_admin / scene_owner 由 sender role 判定（见 ws/wss-endpoint admit metadata）
+    return registerDefaultScenePlatformPermitChecker('onebot11');
+  },
+});

package/schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "connection": {
+      "type": "string",
+      "enum": ["ws", "wss"],
+      "default": "ws",
+      "description": "connection: ws (forward WS client, default) or wss (reverse WS via httpHostToken)"
+    },
+    "name": {
+      "type": "string",
+      "default": "onebot11-bot"
+    },
+    "url": {
+      "type": "string",
+      "description": "OneBot implementation WebSocket URL (required for connection: ws)"
+    },
+    "path": {
+      "type": "string",
+      "description": "WS path for reverse-wss (connection: wss)"
+    },
+    "access_token": {
+      "type": "string"
+    },
+    "reconnect_interval": {
+      "type": "number",
+      "default": 5000
+    },
+    "heartbeat_interval": {
+      "type": "number",
+      "default": 30000
+    }
+  }
+}

package/src/index.ts

@@ -1,74 +1,60 @@
-/**
- * OneBot11 适配器入口：单一适配器，支持正向 WS / 反向 WS（connection: ws | wss）
- */
-import { usePlugin, type Plugin, type Context, type ISceneManagement, createSceneManagementTools, registerDefaultScenePlatformPermitChecker, type ToolFeature } from 'zhin.js';
-import type { Router } from '@zhin.js/host-router';
-import { OneBot11Adapter } from './adapter.js';
+export {
+  buildSendAction,
+  buildWsConnectOptions,
+  extractQuoteId,
+  formatInboundContent,
+  formatInboundMetadata,
+  formatInboundTarget,
+  formatOutboundSegments,
+  getChannelId,
+  isMessageEvent,
+  isOneBot11BotMentioned,
+  parseSendTarget,
+  resolveOneBot11Config,
+  senderDisplayName,
+  senderNickname,
+  senderUserId,
+  type OneBot11ActionRequest,
+  type OneBot11ActionResponse,
+  type OneBot11AdapterConfig,
+  type OneBot11ConfigBase,
+  type OneBot11EndpointConfig,
+  type OneBot11Event,
+  type OneBot11Segment,
+  type OneBot11Sender,
+  type OneBot11WireSegment,
+  type OneBot11WsConfig,
+  type OneBot11WssConfig,
+  type ParsedSendTarget,
+  type ResolvedOneBot11Config,
+} from './protocol.js';
 
-export * from './types.js';
-export { OneBot11WsClient } from './endpoint-ws-client.js';
-export { OneBot11WsServer } from './endpoint-ws-server.js';
-export { OneBot11Adapter, type OneBot11Bot } from './adapter.js';
+export {
+  OneBot11WsEndpoint,
+  type OneBot11WsEndpointOptions,
+} from './ws-endpoint.js';
 
-declare module 'zhin.js' {
-  namespace Plugin {
-    interface Contexts {
-      router: import('@zhin.js/host-router').Router;
-    }
-  }
-  interface Adapters {
-    onebot11: OneBot11Adapter;
-  }
-}
+export {
+  OneBot11WssEndpoint,
+  type OneBot11WssEndpointOptions,
+} from './wss-endpoint.js';
 
-const plugin = usePlugin();
-const { provide, useContext } = plugin;
-provide({
-  name: 'onebot11',
-  description: 'OneBot11 协议适配器（正向 WS / 反向 WS）',
-  mounted: async (p: Plugin) => {
-    const adapter = new OneBot11Adapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: OneBot11Adapter) => {
-    await adapter.stop();
-  },
-} as unknown as Context<'onebot11'>);
+export type { OneBot11WsSocket, OneBot11WsCreateOptions } from './ws-types.js';
 
-useContext('tool', 'onebot11', (toolService: ToolFeature, onebot11: OneBot11Adapter) => {
-  const disposers: (() => void)[] = [];
-  disposers.push(registerDefaultScenePlatformPermitChecker('onebot11'));
-  const sceneTools = createSceneManagementTools(
-    onebot11 as unknown as ISceneManagement,
-    'onebot11',
-  );
-  disposers.push(...sceneTools.map(t => toolService.addTool(t, plugin.name)));
+export {
+  callOneBot11WsAction,
+  decodeWsPayload,
+  handleOneBot11WsMessage,
+  rejectAllPending,
+  startOneBot11Heartbeat,
+} from './ws-transport.js';
 
-  // Platform-specific tool: set title
-  disposers.push(toolService.addTool({
-    name: 'onebot11_set_title',
-    description: '设置 QQ 群成员的专属头衔。只有群主才能设置。',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        group_id: { type: 'number', description: '目标群号' },
-        user_id: { type: 'number', description: '目标成员 QQ号' },
-        title: { type: 'string', description: '头衔文字' },
-      },
-      required: ['endpoint_id', 'group_id', 'user_id', 'title'],
-    },
-    platforms: ['onebot11'],
-    tags: ['onebot11'],
-    permissions: ['platform(onebot11,scene_owner)'],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = onebot11.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const success = await endpoint.setTitle(args.group_id, args.user_id, args.title);
-      return { success, message: success ? `已将 ${args.user_id} 的头衔设为 "${args.title}"` : '设置失败' };
-    },
-  }, plugin.name));
+export { verifyOneBotAccessToken } from './wss-auth.js';
 
-  return () => disposers.forEach(d => d());
-});
+export {
+  getOnebot11AgentDeps,
+  registerOnebot11AgentEndpoint,
+  setOnebot11AgentDeps,
+  type Onebot11AgentDeps,
+  type Onebot11AgentEndpoint,
+} from './onebot11-agent-deps.js';

package/src/onebot11-agent-deps.ts

@@ -0,0 +1,49 @@
+/**
+ * Agent tool deps for onebot11 (set_title etc.).
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+
+export interface Onebot11AgentEndpoint {
+  setTitle(
+    groupId: number,
+    userId: number,
+    title: string,
+    duration?: number,
+  ): Promise<boolean>;
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+export interface Onebot11AgentDeps {
+  getEndpoint: (endpointId: string) => Onebot11AgentEndpoint;
+}
+
+const endpoints = new Map<string, Onebot11AgentEndpoint>();
+let override: Onebot11AgentDeps | null = null;
+
+export function registerOnebot11AgentEndpoint(
+  endpointId: string,
+  endpoint: Onebot11AgentEndpoint,
+): () => void {
+  endpoints.set(endpointId, endpoint);
+  return () => {
+    if (endpoints.get(endpointId) === endpoint) {
+      endpoints.delete(endpointId);
+    }
+  };
+}
+
+/** Optional override used by tests / transitional callers. */
+export function setOnebot11AgentDeps(deps: Onebot11AgentDeps): void {
+  override = deps;
+}
+
+export function getOnebot11AgentDeps(): Onebot11AgentDeps {
+  if (override) return override;
+  return {
+    getEndpoint(endpointId: string): Onebot11AgentEndpoint {
+      const registered = endpoints.get(endpointId);
+      if (!registered) throw new Error(`Endpoint ${endpointId} 不存在`);
+      return registered;
+    },
+  };
+}