@zhin.js/adapter-onebot12 4.0.0 → 4.0.2

package/lib/ws-endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import { type EndpointInstance, type EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { type OneBot12Event, type OneBot12WsConfig } from './protocol.js';
@@ -11,6 +11,7 @@ export interface OneBot12WsEndpointOptions {
 }
 export declare class OneBot12WsEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: OneBot12WsEndpointOptions);
     start(): Promise<void>;
     open(): void;
@@ -20,6 +21,8 @@ export declare class OneBot12WsEndpoint implements EndpointInstance {
         readonly target: string;
         readonly payload: unknown;
     }): Promise<string>;
+    /** Public API for management surface / callers. */
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     /** Test / internal: admit a parsed event when the endpoint is open. */
     admit(ev: OneBot12Event): void;
 }

package/lib/ws-endpoint.js

@@ -2,30 +2,55 @@
  * OneBot12 WS client endpoint — outbound connect to OneBot implementation.
  */
 import WebSocket from 'ws';
-import { clearInterval, clearTimeout } from 'node:timers';
+import { clearTimeout } from 'node:timers';
+import { createEndpointLifecycle, } from '@zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { buildSendMessageParams, buildWsConnectOptions, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { createOneBot12EndpointManagement } from './endpoint-management.js';
+import { buildSendMessageParams, buildWsConnectOptions, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 import { WS_OPEN, } from './ws-types.js';
 const logger = getLogger('onebot12');
 export class OneBot12WsEndpoint {
     #options;
+    management = createOneBot12EndpointManagement(this);
+    #lifecycle;
     #ws;
-    #reconnectTimer;
-    #heartbeatTimer;
     #requestId = 0;
     #pending = new Map();
     #open = false;
-    #started = false;
-    #stopping = false;
     constructor(options) {
         this.#options = options;
+        const { config } = options;
+        this.#lifecycle = createEndpointLifecycle({
+            name: config.name,
+            reconnect: {
+                initialIntervalMs: config.reconnect_interval,
+                // 固定间隔（multiplier 1、无抖动），对齐旧 reconnect_interval 语义
+                multiplier: 1,
+                maxIntervalMs: config.reconnect_interval,
+                jitterMs: 0,
+            },
+            heartbeat: { intervalMs: config.heartbeat_interval },
+        });
     }
     async start() {
-        if (this.#started)
+        if (this.#lifecycle.started)
             return;
-        this.#started = true;
-        this.#stopping = false;
-        await this.#connect();
+        try {
+            await this.#lifecycle.start((handle) => this.#connect(handle));
+        }
+        catch (err) {
+            // start 失败必须清理现场（状态复位由基座保证）
+            if (this.#ws) {
+                try {
+                    this.#ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                this.#ws = undefined;
+            }
+            throw err;
+        }
     }
     open() {
         this.#open = true;
@@ -35,34 +60,24 @@ export class OneBot12WsEndpoint {
     }
     async stop() {
         this.#open = false;
-        this.#stopping = true;
-        this.#started = false;
-        if (this.#reconnectTimer) {
-            clearTimeout(this.#reconnectTimer);
-            this.#reconnectTimer = undefined;
-        }
-        if (this.#heartbeatTimer) {
-            clearInterval(this.#heartbeatTimer);
-            this.#heartbeatTimer = undefined;
-        }
+        // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
+        await this.#lifecycle.stop();
         for (const [, pending] of this.#pending) {
             clearTimeout(pending.timeout);
             pending.reject(new Error('连接已关闭'));
         }
         this.#pending.clear();
-        if (this.#ws) {
-            try {
-                this.#ws.close();
-            }
-            catch {
-                /* ignore */
-            }
-            this.#ws = undefined;
-        }
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+        this.#ws = undefined;
     }
     async send({ target, payload }) {
-        const message = formatOutboundSegments(payload);
+        const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => this.callApi(action, params), (error) => {
+            logger.warn(formatCompact({
+                op: 'onebot12_upload_failed',
+                endpoint: this.#options.config.name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        const message = formatOutboundSegments(materialized);
         const params = buildSendMessageParams(target, message);
         const data = await this.#callAction('send_message', params);
         const messageId = data?.message_id ?? '';
@@ -74,6 +89,10 @@ export class OneBot12WsEndpoint {
         }));
         return messageId;
     }
+    /** Public API for management surface / callers. */
+    callApi(action, params = {}) {
+        return this.#callAction(action, params);
+    }
     /** Test / internal: admit a parsed event when the endpoint is open. */
     admit(ev) {
         if (!this.#open || !isMessageEvent(ev))
@@ -107,7 +126,7 @@ export class OneBot12WsEndpoint {
             }));
         });
     }
-    async #connect() {
+    async #connect(handle) {
         const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
         const create = this.#options.createWebSocket
             ?? ((connectUrl, options) => new WebSocket(connectUrl, { headers: options.headers }));
@@ -115,6 +134,14 @@ export class OneBot12WsEndpoint {
             let settled = false;
             const ws = create(url, { headers });
             this.#ws = ws;
+            handle.onForceClose(() => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            });
             ws.on('open', () => {
                 if (settled)
                     return;
@@ -124,7 +151,9 @@ export class OneBot12WsEndpoint {
                     mode: 'ws',
                     url: safeUrl,
                 }));
-                this.#startHeartbeat();
+                this.#lifecycle.startHeartbeat(() => {
+                    this.#callAction('get_status', {}).catch(() => { });
+                });
                 resolve();
             });
             ws.on('message', (data) => {
@@ -137,18 +166,13 @@ export class OneBot12WsEndpoint {
                         ? reason.toString()
                         : String(reason ?? '');
                 const codeNum = typeof code === 'number' ? code : Number(code ?? 0);
-                logger.warn(formatCompact({
-                    op: 'disconnect',
-                    endpoint: this.#options.config.name,
-                    code: codeNum,
-                    error: reasonStr || 'closed',
-                    reconnect_ms: this.#options.config.reconnect_interval,
-                }));
                 if (!settled) {
                     settled = true;
                     reject(new Error(`OneBot12 WS 关闭: ${codeNum} ${reasonStr}`));
                 }
-                this.#scheduleReconnect();
+                // 断开日志与重连武装均由基座负责；仅曾 open 的连接才会武装重连，
+                // 初始连接失败由 start() 的拒绝路径复位，不产生僵尸重连。
+                handle.notifyClosed(`OneBot12 WS 关闭: ${codeNum} ${reasonStr || 'closed'}`);
             });
             ws.on('error', (err) => {
                 const error = err instanceof Error ? err : new Error(String(err));
@@ -213,28 +237,4 @@ export class OneBot12WsEndpoint {
             this.#ws.send(JSON.stringify(req));
         });
     }
-    #startHeartbeat() {
-        if (this.#heartbeatTimer) {
-            clearInterval(this.#heartbeatTimer);
-        }
-        this.#heartbeatTimer = setInterval(() => {
-            this.#callAction('get_status', {}).catch(() => { });
-        }, this.#options.config.heartbeat_interval);
-    }
-    #scheduleReconnect() {
-        if (this.#stopping || !this.#started || this.#reconnectTimer)
-            return;
-        const delay = this.#options.config.reconnect_interval;
-        this.#reconnectTimer = setTimeout(() => {
-            this.#reconnectTimer = undefined;
-            void this.#connect().catch((err) => {
-                logger.warn(formatCompact({
-                    op: 'reconnect',
-                    endpoint: this.#options.config.name,
-                    ok: false,
-                    error: err instanceof Error ? err.message : String(err),
-                }));
-            });
-        }, delay);
-    }
 }

package/lib/wss-endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } 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';
@@ -11,6 +11,7 @@ export interface OneBot12WssEndpointOptions {
 }
 export declare class OneBot12WssEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: OneBot12WssEndpointOptions);
     start(): Promise<void>;
     open(): void;
@@ -20,5 +21,7 @@ export declare class OneBot12WssEndpoint implements EndpointInstance {
         readonly target: string;
         readonly payload: unknown;
     }): Promise<string>;
+    /** Public API for management surface / callers. */
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     admit(ev: OneBot12Event): void;
 }

package/lib/wss-endpoint.js

@@ -3,12 +3,14 @@
  */
 import { clearInterval } from 'node:timers';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { buildSendMessageParams, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, } from './protocol.js';
+import { createOneBot12EndpointManagement } from './endpoint-management.js';
+import { buildSendMessageParams, formatInboundContent, formatInboundTarget, formatOutboundSegments, isBotMentioned, isMessageEvent, senderNickname, senderUserId, uploadOneBot12MediaSegments, } from './protocol.js';
 import { verifyOneBotAccessToken } from './wss-auth.js';
 import { WS_OPEN } from './ws-types.js';
 const logger = getLogger('onebot12');
 export class OneBot12WssEndpoint {
     #options;
+    management = createOneBot12EndpointManagement(this);
     #ws;
     #wsRelease;
     #heartbeatTimer;
@@ -23,6 +25,15 @@ export class OneBot12WssEndpoint {
         if (this.#started)
             return;
         this.#started = true;
+        if (!this.#options.config.access_token) {
+            // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
+            logger.warn(formatCompact({
+                endpoint: this.#options.config.name,
+                mode: 'wss',
+                ok: false,
+                error: 'missing access_token',
+            }));
+        }
         const handle = this.#options.http.ws(this.#options.config.path);
         this.#wsRelease = handle.onConnection((connection) => {
             this.#acceptConnection(connection);
@@ -65,11 +76,22 @@ export class OneBot12WssEndpoint {
         this.#started = false;
     }
     async send({ target, payload }) {
-        const message = formatOutboundSegments(payload);
+        const materialized = await uploadOneBot12MediaSegments(payload, (action, params) => this.callApi(action, params), (error) => {
+            logger.warn(formatCompact({
+                op: 'onebot12_upload_failed',
+                endpoint: this.#options.config.name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+        const message = formatOutboundSegments(materialized);
         const params = buildSendMessageParams(target, message);
         const data = await this.#callAction('send_message', params);
         return data?.message_id ?? '';
     }
+    /** Public API for management surface / callers. */
+    callApi(action, params = {}) {
+        return this.#callAction(action, params);
+    }
     admit(ev) {
         if (!this.#open || !isMessageEvent(ev))
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot12",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Zhin.js OneBot 12 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,7 +14,8 @@
   },
   "files": [
     "adapters",
-    "plugin.ts",
+    "commands",
+    "plugin.js",
     "schema.json",
     "src",
     "lib",
@@ -39,24 +40,25 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/adapter": "1.1.2",
+    "@zhin.js/command": "1.0.4",
+    "@zhin.js/core": "1.4.2",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.0"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.0.2"
+    "@zhin.js/host-http": "1.0.3"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/plugin-runtime": "1.1.0",
-    "zhin.js": "5.0.0"
+    "@zhin.js/adapter": "1.1.2",
+    "@zhin.js/core": "1.4.2",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -78,13 +80,17 @@
   "zhin": {
     "protocol": 1,
     "type": "plugin",
-    "entry": "./plugin.ts",
+    "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": []

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/plugin-runtime';
+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/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;
+}

package/src/index.ts

@@ -8,13 +8,17 @@ export {
   getChannelId,
   isBotMentioned,
   isMessageEvent,
+  mediaRefToOneBot12Fields,
+  mediaRefToOneBot12UploadParams,
   parseSendTarget,
   resolveOneBot12Config,
   senderNickname,
   senderUserId,
+  uploadOneBot12MediaSegments,
   type OneBot12ActionRequest,
   type OneBot12ActionResponse,
   type OneBot12AdapterConfig,
+  type OneBot12CallAction,
   type OneBot12ConfigBase,
   type OneBot12EndpointConfig,
   type OneBot12Event,

package/src/onebot12-endpoint-commands.ts

@@ -0,0 +1,24 @@
+/**
+ * `onebot12 endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { onebot12RuntimeStateToken } from './onebot12-runtime-state.js';
+
+export const onebot12EndpointCommands = createEndpointCommands({
+  adapterKey: 'onebot12',
+  adapterDisplayName: 'OneBot 12',
+  fields: [
+    { key: 'url', description: 'OneBot 实现 WebSocket URL（connection: ws 必填）' },
+    { key: 'path', description: 'HTTP/WS 路径（webhook / reverse-wss）' },
+    { key: 'api_url', description: 'HTTP action 端点（connection: webhook 出站必填）' },
+    { key: 'access_token', env: true, description: 'OneBot access token' },
+  ],
+  running: (use) => use(onebot12RuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => {
+    if (entry.url) return `url: ${String(entry.url)}`;
+    if (entry.path) return `path: ${String(entry.path)}`;
+    return '';
+  },
+}, defineCommand);

package/src/onebot12-runtime-state.ts

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