@zhin.js/adapter-onebot11 1.0.98 → 1.1.0

package/lib/ws-types.d.ts

@@ -0,0 +1,18 @@
+/** 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: OneBot11ActionResponse) => void;
+    reject: (err: Error) => void;
+    timeout: NodeJS.Timeout;
+}
+import type { OneBot11ActionResponse } from './protocol.js';

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,25 @@
+/**
+ * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
+ */
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { type OneBot11WssConfig } from './protocol.js';
+import { type Onebot11Client } from './client.js';
+export interface OneBot11WssEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: OneBot11WssConfig;
+}
+export declare class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
+    #private;
+    readonly client: Onebot11Client;
+    readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    readonly content: import("@zhin.js/adapter").EndpointContentPort;
+    constructor(options: OneBot11WssEndpointOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
+}

package/lib/wss-endpoint.js

@@ -0,0 +1,173 @@
+/**
+ * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
+ */
+import { ClientEndpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { createOneBot11EndpointManagement } from './endpoint-management.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, } from './ws-transport.js';
+import { callOnebot11Client, createOnebot11EndpointClient, forwardOnebot11ClientEvents } from './client.js';
+export class OneBot11WssEndpoint extends ClientEndpoint {
+    client;
+    #logger;
+    #options;
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content;
+    #ws;
+    #wsRelease;
+    #lifecycle;
+    #requestId = { value: 0 };
+    #pending = new Map();
+    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.#options.config.access_token) {
+            // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
+            this.#logger.warn(formatCompact({
+                endpoint: this.#options.config.id,
+                mode: 'wss',
+                ok: false,
+                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;
+            });
+        });
+        this.#logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.id,
+            mode: 'wss',
+            path: this.#options.config.path,
+        }));
+    }
+    async stop() {
+        this.close();
+        await this.#lifecycle.stop();
+        rejectAllPending(this.#pending);
+    }
+    async send({ conversation, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(conversation, message);
+        const data = await callOnebot11Client(this.client, action, params);
+        return data?.message_id != null ? String(data.message_id) : '';
+    }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await callOnebot11Client(this.client, 'delete_msg', { message_id: Number(messageId) });
+    }
+    #callApi(action, params = {}) {
+        return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);
+    }
+    #admitRaw(ev) {
+        if (!isMessageEvent(ev)) {
+            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.emit('message.receive', {
+            conversation,
+            message: { conversation, id: String(ev.message_id) },
+            content: formatInboundContent(ev),
+            sender: {
+                id: senderUserId(ev),
+                name: senderDisplayName(ev) || undefined,
+                ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+            },
+            endpointId: inbound.endpointId,
+            ...(inbound.mentioned ? { mentioned: true } : {}),
+            ...(inbound.replyTo ? { replyTo: inbound.replyTo } : {}),
+            metadata: inbound.metadata,
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'onebot11_gateway_receive_failed',
+                target: `${conversation.kind}:${conversation.id}`,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #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');
+            return;
+        }
+        const socket = connection.socket;
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.#ws = socket;
+        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,
+                ingest: (ev) => this.client.ingest(ev),
+            });
+        });
+        socket.on('close', () => {
+            if (this.#ws === socket) {
+                this.#ws = undefined;
+                this.#lifecycle.stopHeartbeat();
+            }
+        });
+        this.#logger.debug(formatCompact({
+            endpoint: this.#options.config.id,
+            mode: 'wss',
+            peer: connection.request.socket.remoteAddress,
+        }));
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-onebot11",
-  "version": "1.0.98",
-  "description": "Zhin.js adapter for OneBot v11 protocol",
+  "version": "1.1.0",
+  "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,13 @@
     }
   },
   "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "skills",
-    "plugin.yml",
+    "agent",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -32,43 +33,89 @@
     "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"
+    "@imhelper/onebot-v11": "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/permission": "1.1.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.88",
-    "@zhin.js/client": "2.0.2",
-    "zhin.js": "1.0.93"
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.1.23",
+    "@zhin.js/host-http": "1.1.0",
+    "zhin.js": "1.1.0"
   },
   "peerDependencies": {
-    "@zhin.js/host-router": "0.0.3",
-    "zhin.js": "1.0.93"
+    "zod": "^4.0.0",
+    "@zhin.js/adapter": "^1.1.12",
+    "@zhin.js/agent": "^1.1.23",
+    "@zhin.js/command": "^1.1.0",
+    "@zhin.js/core": "^1.1.35",
+    "zhin.js": "^1.1.0"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
+    "@zhin.js/agent": {
+      "optional": true
+    },
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "zhin.js": {
+      "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"
   },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "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.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from 'zhin.js/adapter';
+import { definePlugin } from 'zhin.js';
+import { permissionHostToken, createSceneRolePlatformChecker } from '@zhin.js/permission';
+import { onebot11RuntimeStateToken } from "./lib/onebot11-runtime-state.js";
+export default definePlugin({
+    name: 'onebot11',
+    metadata: {
+        displayName: 'OneBot 11 Adapter',
+    },
+    setup(context) {
+        context.resources.provide(onebot11RuntimeStateToken, createEndpointRuntimeState());
+        if (context.resources.has(permissionHostToken)) {
+            const host = context.resources.use(permissionHostToken);
+            return host.registerPlatform('onebot11', createSceneRolePlatformChecker());
+        }
+    },
+});

package/schema.json

@@ -0,0 +1,97 @@
+{
+  "$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)"
+    },
+    "reconnect_interval": {
+      "type": "number",
+      "default": 5000
+    },
+    "heartbeat_interval": {
+      "type": "number",
+      "default": 30000
+    },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（platform user id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted platform user id"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（platform user id）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted platform user id"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "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",
+            "description": "OneBot access token"
+          },
+          "id": {
+            "type": "string",
+            "description": "OneBot11 bot name"
+          }
+        },
+        "required": [
+          "id"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

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/content-port.ts

@@ -0,0 +1,66 @@
+import type { EndpointContentPort, EndpointContentResolveContext } from 'zhin.js/adapter';
+import { toCanonicalSegments } from '@zhin.js/core';
+import type { ConversationMessage, ConversationReference, ForwardEntry } from '@zhin.js/im-contract';
+
+type CallApi = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+
+export function createOneBot11ContentPort(callApi: CallApi): EndpointContentPort {
+  return Object.freeze({
+    async resolve(reference: ConversationReference, context: EndpointContentResolveContext) {
+      try {
+        context.signal.throwIfAborted();
+        if (reference.kind === 'media') {
+          return reference.media.kind === 'file'
+            ? Object.freeze({ status: 'unsupported' as const, code: 'onebot11_opaque_media' })
+            : Object.freeze({ status: 'resolved' as const, reference, value: reference.media });
+        }
+        if (reference.kind === 'message') {
+          const row = await callApi('get_msg', { message_id: reference.message.id }) as Record<string, unknown>;
+          context.signal.throwIfAborted();
+          const segments = normalizeSegments(row.message ?? row.raw_message);
+          const sender = row.sender as Record<string, unknown> | undefined;
+          const value: ConversationMessage = Object.freeze({
+            ref: reference.message,
+            ...(sender?.user_id != null ? { actor: Object.freeze({
+              id: String(sender.user_id),
+              ...(sender.nickname ? { displayName: String(sender.nickname) } : {}),
+            }) } : {}),
+            segments,
+            timestamp: toMillis(row.time),
+          });
+          return Object.freeze({ status: 'resolved' as const, reference, value });
+        }
+        const raw = await callApi('get_forward_msg', { id: reference.forwardId }) as Record<string, unknown>;
+        context.signal.throwIfAborted();
+        const nodes = Array.isArray(raw.messages) ? raw.messages.slice(0, context.maxEntries) : [];
+        const value: readonly ForwardEntry[] = Object.freeze(nodes.map((node) => {
+          const row = node as Record<string, unknown>;
+          const sender = row.sender as Record<string, unknown> | undefined;
+          return Object.freeze({
+            ...(sender?.user_id != null ? { actor: Object.freeze({
+              id: String(sender.user_id),
+              ...(sender.nickname ? { displayName: String(sender.nickname) } : {}),
+            }) } : {}),
+            timestamp: toMillis(row.time),
+            segments: normalizeSegments(row.content ?? row.message),
+          });
+        }));
+        return Object.freeze({ status: 'resolved' as const, reference, value, truncated: nodes.length >= context.maxEntries });
+      } catch (error) {
+        if (context.signal.aborted) return Object.freeze({ status: 'expired' as const, code: 'turn_aborted' });
+        return Object.freeze({ status: 'failed' as const, code: 'onebot11_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+      }
+    },
+  });
+}
+
+function normalizeSegments(value: unknown) {
+  if (Array.isArray(value)) return Object.freeze(toCanonicalSegments(value as never));
+  return Object.freeze([{ type: 'text', data: Object.freeze({ text: String(value ?? '') }) }]);
+}
+
+function toMillis(value: unknown): number {
+  const time = Number(value);
+  if (!Number.isFinite(time)) return Date.now();
+  return time < 10_000_000_000 ? time * 1000 : time;
+}