@zhin.js/adapter-onebot12 1.0.0 → 1.1.0

package/lib/wss-endpoint.js

@@ -0,0 +1,222 @@
+/**
+ * OneBot12 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 { createOneBot12EndpointManagement } from './endpoint-management.js';
+import { buildSendMessageParams, formatInboundContent, formatOutboundSegments, isBotMentioned, isMessageEvent, onebot12InboundConversation, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
+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';
+export class OneBot12WssEndpoint extends ClientEndpoint {
+    client;
+    #logger;
+    #options;
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    content;
+    #ws;
+    #wsRelease;
+    #lifecycle;
+    #requestId = 0;
+    #pending = new Map();
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('onebot12', options.config.id);
+        this.#options = options;
+        this.#lifecycle = createEndpointLifecycle({
+            name: options.config.id,
+            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);
+        this.management = createOneBot12EndpointManagement({ callApi });
+        this.content = createOneBot12ContentPort(callApi);
+        this.bindClientEvents((receive) => forwardOnebot12ClientEvents(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();
+        for (const [, pending] of this.#pending) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error('连接已关闭'));
+        }
+        this.#pending.clear();
+    }
+    async send({ conversation, payload }) {
+        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),
+            }));
+        });
+        const message = formatOutboundSegments(materialized);
+        const params = buildSendMessageParams(conversation, message);
+        const data = await callOnebot12Client(this.client, 'send_message', params);
+        return data?.message_id ?? '';
+    }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await callOnebot12Client(this.client, 'delete_message', { message_id: messageId });
+    }
+    #admitRaw(ev) {
+        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);
+            return;
+        }
+        const conversation = onebot12InboundConversation(String(this.#options.id), ev);
+        const nickname = senderNickname(ev);
+        const mentioned = isBotMentioned(ev);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: ev.message_id },
+            content: formatInboundContent(ev),
+            sender: { id: senderUserId(ev), name: senderNickname(ev) },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                detail_type: ev.detail_type,
+                user_id: ev.user_id,
+                group_id: ev.group_id,
+                channel_id: ev.channel_id,
+                guild_id: ev.guild_id,
+                time: ev.time,
+                ...(nickname ? { nickname } : {}),
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'onebot12_gateway_receive_failed',
+                kind: conversation.kind,
+                conversationId: conversation.id,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #warnPlatformEvent(error) {
+        this.#logger.warn(formatCompact({
+            op: 'onebot12_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(() => {
+            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();
+            }
+        });
+        this.#logger.debug(formatCompact({
+            endpoint: this.#options.config.id,
+            mode: 'wss',
+            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));
+        });
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-onebot12",
-  "version": "1.0.0",
-  "description": "Zhin.js adapter for OneBot 12 protocol",
+  "version": "1.1.0",
+  "description": "Zhin.js OneBot 12 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,12 +13,15 @@
     }
   },
   "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "skills",
-    "README.md"
+    "agent",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "zhin",
@@ -36,27 +39,71 @@
     "directory": "plugins/adapters/onebot12"
   },
   "dependencies": {
-    "ws": "^8.21.0"
+    "@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"
   },
   "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": "2.0.0"
+    "vitest": "^4.1.10",
+    "@zhin.js/host-http": "1.1.0",
+    "zhin.js": "1.1.0"
   },
   "peerDependencies": {
-    "zhin.js": "2.0.0",
-    "@zhin.js/host-router": "1.0.0"
+    "@zhin.js/adapter": "^1.1.12",
+    "@zhin.js/command": "^1.1.0",
+    "@zhin.js/core": "^1.1.35",
+    "zhin.js": "^1.1.0"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "zhin.js": {
       "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/onebot12/tests"
   }
 }

package/plugin.js

@@ -0,0 +1,14 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from 'zhin.js/adapter';
+import { definePlugin } from 'zhin.js';
+import { onebot12RuntimeStateToken } from "./lib/onebot12-runtime-state.js";
+export default definePlugin({
+    name: 'onebot12',
+    metadata: {
+        displayName: 'OneBot 12 Adapter',
+    },
+    setup(context) {
+        // 运行中 endpoint 注册表（onebot12.endpoint list 的"运行中"数据源）
+        context.resources.provide(onebot12RuntimeStateToken, createEndpointRuntimeState());
+    },
+});

package/schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "connection": {
+      "type": "string",
+      "enum": [
+        "ws",
+        "webhook",
+        "wss"
+      ],
+      "default": "ws",
+      "description": "ws (default), webhook (httpHostToken POST), 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": "HTTP/WS path for webhook or reverse-wss"
+          },
+          "api_url": {
+            "type": "string",
+            "description": "HTTP action endpoint for webhook outbound (required for connection: webhook send)"
+          },
+          "access_token": {
+            "type": "string",
+            "description": "OneBot access token"
+          },
+          "id": {
+            "type": "string",
+            "description": "OneBot12 bot name"
+          }
+        },
+        "required": [
+          "id"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,81 @@
+import {
+  OneBotV12Client,
+  type OneBotV12Event as ImHelperOneBot12Event,
+  type OneBotV12Response,
+} from '@imhelper/onebot-v12';
+import { EventFactory, type EventMap, type ImHelperEventMap } from 'imhelper';
+import {
+  defineEndpointClient,
+  forwardEndpointClientEvents,
+  type ClientEventPayloads,
+} from 'zhin.js/adapter';
+import type { ResolvedOneBot12Config } from './protocol.js';
+
+export { OneBotV12Client as Onebot12Client } from '@imhelper/onebot-v12';
+
+export type Onebot12ApiCall = (
+  action: string,
+  params?: Record<string, unknown>,
+) => Promise<OneBotV12Response>;
+
+type Onebot12ClientEvents = ImHelperEventMap<
+  string,
+  ImHelperOneBot12Event,
+  EventMap<string>
+>;
+export type Onebot12ClientEventMap = ClientEventPayloads<Onebot12ClientEvents>;
+
+export function createOnebot12EndpointClient(
+  config: ResolvedOneBot12Config,
+  request: Onebot12ApiCall,
+): OneBotV12Client {
+  const baseUrl = config.connection === 'ws'
+    ? config.url.replace(/^ws(s?):/, 'http$1:')
+    : config.connection === 'webhook' && config.api_url
+      ? config.api_url
+      : 'http://localhost';
+  return new OneBotV12Client({
+    baseUrl,
+    selfId: config.id,
+    accessToken: config.access_token,
+    receiveMode: 'manual',
+    call: request,
+  });
+}
+
+export async function callOnebot12Client<T = unknown>(
+  client: OneBotV12Client,
+  action: string,
+  params?: Record<string, unknown>,
+): Promise<T | undefined> {
+  const response: OneBotV12Response<T> = await client.call<T>(action, params);
+  if (response.status !== 'ok') {
+    throw new Error(
+      `OneBot 12 API ${action}: retcode=${response.retcode}${response.message ? ` ${response.message}` : ''}`,
+    );
+  }
+  return response.data;
+}
+
+const onebot12ClientEventNames = Object.freeze([
+  ...EventFactory.getSupportedEventTypes<string>(),
+  'event',
+]);
+
+export function forwardOnebot12ClientEvents(
+  client: OneBotV12Client,
+  receive: (name: string, payload: unknown) => void,
+): () => void {
+  return forwardEndpointClientEvents(client, onebot12ClientEventNames, receive);
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly onebot12: {
+      readonly client: OneBotV12Client;
+      readonly events: Onebot12ClientEventMap;
+    };
+  }
+}
+
+export const onebot12Client = defineEndpointClient<OneBotV12Client, Onebot12ClientEventMap>('onebot12');

package/src/content-port.ts

@@ -0,0 +1,49 @@
+import type { EndpointContentPort, EndpointContentResolveContext } from 'zhin.js/adapter';
+import type { ConversationMessage, ConversationReference } from '@zhin.js/im-contract';
+
+type CallApi = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
+
+export function createOneBot12ContentPort(callApi: CallApi): EndpointContentPort {
+  return Object.freeze({
+    async resolve(reference: ConversationReference, context: EndpointContentResolveContext) {
+      try {
+        context.signal.throwIfAborted();
+        if (reference.kind === 'forward') {
+          return Object.freeze({ status: 'unsupported' as const, code: 'onebot12_forward_lookup_not_standardized' });
+        }
+        if (reference.kind === 'media') {
+          return reference.media.kind === 'file'
+            ? Object.freeze({ status: 'unsupported' as const, code: 'onebot12_opaque_media' })
+            : Object.freeze({ status: 'resolved' as const, reference, value: reference.media });
+        }
+        const row = await callApi('get_message', { message_id: reference.message.id }) as Record<string, unknown>;
+        context.signal.throwIfAborted();
+        const message = (row.message && typeof row.message === 'object' ? row.message : row) as Record<string, unknown>;
+        const segments = normalizeSegments(message.message ?? message.content);
+        const value: ConversationMessage = Object.freeze({
+          ref: reference.message,
+          ...(message.user_id != null ? { actor: Object.freeze({ id: String(message.user_id) }) } : {}),
+          segments,
+          timestamp: toMillis(message.time),
+        });
+        return Object.freeze({ status: 'resolved' as const, reference, value });
+      } catch (error) {
+        if (context.signal.aborted) return Object.freeze({ status: 'expired' as const, code: 'turn_aborted' });
+        return Object.freeze({ status: 'failed' as const, code: 'onebot12_content_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+      }
+    },
+  });
+}
+
+function normalizeSegments(value: unknown) {
+  if (!Array.isArray(value)) return Object.freeze([{ type: 'text', data: Object.freeze({ text: String(value ?? '') }) }]);
+  return Object.freeze(value.map((item) => {
+    const row = item as Record<string, unknown>;
+    return Object.freeze({ type: String(row.type ?? 'text'), data: Object.freeze((row.data ?? {}) as Record<string, unknown>) });
+  }));
+}
+
+function toMillis(value: unknown): number {
+  const time = Number(value);
+  return Number.isFinite(time) ? (time < 10_000_000_000 ? time * 1000 : time) : Date.now();
+}

package/src/endpoint-management.ts

@@ -0,0 +1,73 @@
+/**
+ * OneBot12 endpoint management 语义端口（Console 社交面 RPC 消费，见
+ * packages/im/adapter/src/endpoint-management.ts）。
+ *
+ * 动作名对齐 OB12 规范：get_friend_list / get_group_list / get_group_member_list。
+ * 归一化取舍（OB12 id 为字符串，收敛为数字）：
+ * - friend → {user_id:number, nickname: user_name, remark: user_displayname ?? ''}
+ * - group → {group_id:number, name: group_name ?? name}
+ * - 群成员列表保持 OB12 原生形状，仅保证数组
+ */
+import type {
+  EndpointFriend,
+  EndpointGroup,
+  EndpointManagement,
+} from 'zhin.js/adapter';
+
+/** 管理面只依赖 endpoint 的 callApi（ws/wss/webhook 三种传输各自实现）。 */
+export interface OneBot12ManagementCaller {
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+export function createOneBot12EndpointManagement(
+  endpoint: OneBot12ManagementCaller,
+): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    async listFriends(): Promise<readonly EndpointFriend[]> {
+      const data = await endpoint.callApi('get_friend_list');
+      return toArray(data).map((value) => {
+        const friend = asRecord(value);
+        return {
+          user_id: toNumberId(friend.user_id, 'user_id'),
+          nickname: String(friend.user_name ?? friend.nickname ?? ''),
+          remark: String(friend.user_displayname ?? friend.remark ?? ''),
+        };
+      });
+    },
+    async listGroups(): Promise<readonly EndpointGroup[]> {
+      const data = await endpoint.callApi('get_group_list');
+      return toArray(data).map((value) => {
+        const group = asRecord(value);
+        return {
+          group_id: toNumberId(group.group_id, 'group_id'),
+          name: String(group.group_name ?? group.name ?? ''),
+        };
+      });
+    },
+    async listGroupMembers(groupId: string): Promise<readonly unknown[]> {
+      const data = await endpoint.callApi('get_group_member_list', {
+        group_id: groupId,
+      });
+      return toArray(data);
+    },
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function toArray(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/** OB12 id 是字符串；QQ 系实现均为数字串，统一收敛为数字。 */
+function toNumberId(value: unknown, label: string): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+    throw new TypeError(`onebot12 ${label} 必须是数字: ${String(value)}`);
+  }
+  return n;
+}