@zhin.js/adapter-onebot12 4.0.0 → 4.0.2

package/src/protocol.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://12.onebot.dev/
  */
+import { isMediaRef, mediaRefFromLegacyData, type MediaRef } from '@zhin.js/core';
 
 /** Transitional legacy endpoint row (`endpoints[]` with `context: onebot12`). */
 export interface OneBot12LegacyEndpointRow {
@@ -273,9 +274,85 @@ export function isBotMentioned(ev: OneBot12Event): boolean {
   );
 }
 
+/** OneBot 12 携带媒体的段类型。 */
+const ONEBOT12_MEDIA_TYPES = new Set(['image', 'voice', 'audio', 'video', 'file']);
+
+/** 媒体段 data 里的 canonical-only / legacy 媒体字段，归一后不重复进 wire。 */
+const MEDIA_DATA_SKIP_KEYS = new Set([
+  'media', 'alt', 'mime_type', 'url', 'file', 'base64', 'data', 'path',
+]);
+
+/**
+ * canonical MediaRef → OneBot 12 媒体字段（扩展字段降级形状）。
+ * spec 正式投递形状是 `file_id`（先 upload_file 物化，见
+ * {@link uploadOneBot12MediaSegments}）；上传失败时按常见扩展字段
+ * 降级输出：url → `url`、base64 → `data`、本地路径 → `path`。
+ */
+export function mediaRefToOneBot12Fields(media: MediaRef): Record<string, unknown> {
+  if (media.kind === 'base64') {
+    const value = media.value.startsWith('base64://')
+      ? media.value.slice('base64://'.length)
+      : media.value;
+    return { data: value };
+  }
+  if (media.kind === 'path') {
+    return { path: media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value };
+  }
+  return { url: media.value };
+}
+
+function oneBot12MediaExtra(data: Record<string, unknown>): Record<string, unknown> {
+  const extra: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (!MEDIA_DATA_SKIP_KEYS.has(key)) extra[key] = value;
+  }
+  return extra;
+}
+
+function oneBot12MediaSegment(
+  type: string,
+  data: Record<string, unknown>,
+): OneBot12Segment {
+  // 已物化为 file_id 的段是 spec 正式形状，原样透传。
+  if (typeof data.file_id === 'string' && data.file_id) return { type, data };
+  const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
+  if (!media) return { type, data };
+  return { type, data: { ...oneBot12MediaExtra(data), ...mediaRefToOneBot12Fields(media) } };
+}
+
+/**
+ * canonical Segment → OneBot 12 数组段：
+ * - mention → mention（`user_id: target`，`target: 'all'` → mention_all）；
+ * - reply（`message_id`）→ reply（`message_id`）；
+ * - image / voice / audio / video / file 的 MediaRef → url/data/path 扩展字段；
+ * - 其余（已是 wire 形状的段、平台扩展段）原样透传。
+ */
+function canonicalToOneBotSegment(segment: OneBot12WireSegment): OneBot12Segment {
+  const data = segment.data ?? {};
+  switch (segment.type) {
+    case 'mention': {
+      const target = data.target ?? data.user_id ?? data.id;
+      if (target == null) return { type: segment.type, data };
+      if (String(target) === 'all') return { type: 'mention_all', data: {} };
+      return { type: 'mention', data: { user_id: String(target) } };
+    }
+    case 'reply': {
+      const messageId = data.message_id ?? data.id;
+      if (messageId == null) return { type: segment.type, data };
+      return { type: 'reply', data: { message_id: String(messageId) } };
+    }
+    default:
+      if (ONEBOT12_MEDIA_TYPES.has(segment.type)) {
+        return oneBot12MediaSegment(segment.type, data);
+      }
+      return { type: segment.type, data };
+  }
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 12 message segments.
- * Segment canonicalization is intentionally not done here.
+ * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
+ * 旧 wire 形状（mention / 裸 `{url,file,base64}`）保持兼容透传。
  */
 export function formatOutboundSegments(payload: unknown): OneBot12Segment[] {
   if (typeof payload === 'string') {
@@ -303,11 +380,110 @@ export function formatOutboundSegments(payload: unknown): OneBot12Segment[] {
       segs.push({ type: 'text', data: { text: item } });
       continue;
     }
-    segs.push({ type: item.type, data: item.data ?? {} });
+    segs.push(canonicalToOneBotSegment(item));
   }
   return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
 }
 
+/** 端点动作调用签名（WS echo 请求 / webhook api_url HTTP）。 */
+export type OneBot12CallAction = (
+  action: string,
+  params: Record<string, unknown>,
+) => Promise<unknown>;
+
+/** upload_file 文件名：优先段 data.name/filename，URL/路径取 basename，再按 mime 给默认名。 */
+function oneBot12UploadName(
+  segmentType: string,
+  data: Record<string, unknown>,
+  media: MediaRef,
+): string {
+  const named = data.name ?? data.filename;
+  if (typeof named === 'string' && named) return named;
+  if (media.kind === 'url') {
+    try {
+      const base = new URL(media.value).pathname.split('/').filter(Boolean).pop();
+      if (base) return base;
+    } catch {
+      /* ignore */
+    }
+  }
+  if (media.kind === 'path') {
+    const base = media.value.split(/[\\/]/).filter(Boolean).pop();
+    if (base) return base;
+  }
+  const ext = media.mime_type?.split('/')[1]?.split(';')[0];
+  return `${segmentType}.${ext || 'bin'}`;
+}
+
+/** canonical MediaRef → OB12 `upload_file` 动作参数（spec: type url/path/data）。 */
+export function mediaRefToOneBot12UploadParams(
+  segmentType: string,
+  data: Record<string, unknown>,
+  media: MediaRef,
+): Record<string, unknown> | undefined {
+  const name = oneBot12UploadName(segmentType, data, media);
+  if (media.kind === 'url') return { type: 'url', name, url: media.value };
+  if (media.kind === 'path') {
+    const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
+    return { type: 'path', name, path };
+  }
+  if (media.kind === 'base64') {
+    const value = media.value.startsWith('base64://')
+      ? media.value.slice('base64://'.length)
+      : media.value;
+    return { type: 'data', name, data: value };
+  }
+  return undefined;
+}
+
+async function uploadOneMediaSegment(
+  item: unknown,
+  callAction: OneBot12CallAction,
+  onUploadFailed?: (error: unknown) => void,
+): Promise<unknown> {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return item;
+  const segment = item as OneBot12WireSegment;
+  if (typeof segment.type !== 'string' || !ONEBOT12_MEDIA_TYPES.has(segment.type)) return item;
+  const data = segment.data ?? {};
+  if (typeof data.file_id === 'string' && data.file_id) return item;
+  const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
+  if (!media) return item;
+  // kind=file：平台不透明引用（OB12 file_id 复投），直接物化为 file_id。
+  if (media.kind === 'file') {
+    return { type: segment.type, data: { ...oneBot12MediaExtra(data), file_id: media.value } };
+  }
+  const params = mediaRefToOneBot12UploadParams(segment.type, data, media);
+  if (!params) return item;
+  try {
+    const result = await callAction('upload_file', params) as { file_id?: unknown } | undefined;
+    if (result && typeof result.file_id === 'string' && result.file_id) {
+      return { type: segment.type, data: { ...oneBot12MediaExtra(data), file_id: result.file_id } };
+    }
+    throw new Error('upload_file 响应缺少 file_id');
+  } catch (error) {
+    // 上传失败降级：保留原段，由 formatOutboundSegments 走扩展字段（url/data/path）
+    onUploadFailed?.(error);
+    return item;
+  }
+}
+
+/**
+ * 出站媒体段物化：image/voice/audio/video/file 段的 MediaRef（url/base64/path）
+ * 先经 `upload_file` 换 file_id（spec 正式投递形状），再交给
+ * {@link formatOutboundSegments} 编码；kind=file 的 MediaRef 直接按 file_id 复投。
+ * 上传失败保留原段（降级扩展字段透传）并回调 onUploadFailed。
+ */
+export async function uploadOneBot12MediaSegments(
+  payload: unknown,
+  callAction: OneBot12CallAction,
+  onUploadFailed?: (error: unknown) => void,
+): Promise<unknown> {
+  if (Array.isArray(payload)) {
+    return Promise.all(payload.map((item) => uploadOneMediaSegment(item, callAction, onUploadFailed)));
+  }
+  return uploadOneMediaSegment(payload, callAction, onUploadFailed);
+}
+
 export function buildSendMessageParams(
   target: string,
   message: OneBot12Segment[],
@@ -349,6 +525,7 @@ export async function callOneBot12Action(
     method: 'POST',
     headers,
     body: JSON.stringify(body),
+    signal: AbortSignal.timeout(30_000),
   });
 
   const text = await res.text();

package/src/webhook.ts

@@ -2,11 +2,12 @@
  * OneBot12 HTTP webhook endpoint — POST inbound + api_url outbound.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-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, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import {
   buildSendMessageParams,
   callOneBot12Action,
@@ -17,6 +18,7 @@ import {
   isMessageEvent,
   senderNickname,
   senderUserId,
+  uploadOneBot12MediaSegments,
   type OneBot12Event,
   type OneBot12WebhookConfig,
 } from './protocol.js';
@@ -34,6 +36,7 @@ export interface OneBot12WebhookEndpointOptions {
 
 export class OneBot12WebhookEndpoint implements EndpointInstance {
   readonly #options: OneBot12WebhookEndpointOptions;
+  readonly management: EndpointManagement = createOneBot12EndpointManagement(this);
   readonly #callAction: typeof callOneBot12Action;
   #routeReleases: HttpRouteRegistration[] = [];
   #open = false;
@@ -47,6 +50,15 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
+    if (!this.#options.config.access_token) {
+      // webhook 模式未配 access_token 时任何 POST 都会被放行（verifyOneBotAccessToken 直接 return true）
+      logger.warn(formatCompact({
+        endpoint: this.#options.config.name,
+        mode: 'webhook',
+        ok: false,
+        error: 'missing access_token',
+      }));
+    }
     this.#setupRoutes();
     logger.info(formatCompact({
       op: 'listen',
@@ -72,18 +84,20 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    const apiUrl = this.#options.config.api_url;
-    if (!apiUrl) {
-      throw new Error('OneBot12 connection:webhook requires api_url for outbound send');
-    }
-    const message = formatOutboundSegments(payload);
-    const params = buildSendMessageParams(target, message);
-    const resp = await this.#callAction(
-      { url: apiUrl, access_token: this.#options.config.access_token },
-      'send_message',
-      params,
+    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 data = resp.data as { message_id?: string } | undefined;
+    const message = formatOutboundSegments(materialized);
+    const params = buildSendMessageParams(target, message);
+    const data = await this.callApi('send_message', params) as { message_id?: string } | undefined;
     const messageId = data?.message_id ?? '';
     logger.debug(formatCompact({
       op: 'onebot12_send',
@@ -94,6 +108,20 @@ export class OneBot12WebhookEndpoint implements EndpointInstance {
     return messageId;
   }
 
+  /** Public API for management surface / callers；webhook 模式走 api_url。 */
+  async callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    const apiUrl = this.#options.config.api_url;
+    if (!apiUrl) {
+      throw new Error('OneBot12 connection:webhook requires api_url for outbound api');
+    }
+    const resp = await this.#callAction(
+      { url: apiUrl, access_token: this.#options.config.access_token },
+      action,
+      params,
+    );
+    return resp.data;
+  }
+
   admit(ev: OneBot12Event): void {
     if (!this.#open || !isMessageEvent(ev)) return;
     const target = formatInboundTarget(ev);

package/src/ws-endpoint.ts

@@ -2,11 +2,18 @@
  * OneBot12 WS client endpoint — outbound connect to OneBot implementation.
  */
 import WebSocket from 'ws';
-import { clearInterval, clearTimeout } from 'node:timers';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import { clearTimeout } from 'node:timers';
+import {
+  createEndpointLifecycle,
+  type EndpointConnectHandle,
+  type EndpointInstance,
+  type EndpointLifecycle,
+  type EndpointManagement,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import {
   buildSendMessageParams,
   buildWsConnectOptions,
@@ -17,6 +24,7 @@ import {
   isMessageEvent,
   senderNickname,
   senderUserId,
+  uploadOneBot12MediaSegments,
   type OneBot12ActionRequest,
   type OneBot12ActionResponse,
   type OneBot12Event,
@@ -42,9 +50,9 @@ export interface OneBot12WsEndpointOptions {
 
 export class OneBot12WsEndpoint implements EndpointInstance {
   readonly #options: OneBot12WsEndpointOptions;
+  readonly management: EndpointManagement = createOneBot12EndpointManagement(this);
+  readonly #lifecycle: EndpointLifecycle;
   #ws?: OneBot12WsSocket;
-  #reconnectTimer?: NodeJS.Timeout;
-  #heartbeatTimer?: NodeJS.Timeout;
   #requestId = 0;
   #pending = new Map<string, {
     resolve: (value: unknown) => void;
@@ -52,18 +60,39 @@ export class OneBot12WsEndpoint implements EndpointInstance {
     timeout: NodeJS.Timeout;
   }>();
   #open = false;
-  #started = false;
-  #stopping = false;
 
   constructor(options: OneBot12WsEndpointOptions) {
     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(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
-    this.#stopping = false;
-    await this.#connect();
+    if (this.#lifecycle.started) return;
+    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(): void {
@@ -76,34 +105,29 @@ export class OneBot12WsEndpoint implements EndpointInstance {
 
   async stop(): Promise<void> {
     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 }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    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) as { message_id?: string } | undefined;
     const messageId = data?.message_id ?? '';
@@ -116,6 +140,11 @@ export class OneBot12WsEndpoint implements EndpointInstance {
     return messageId;
   }
 
+  /** Public API for management surface / callers. */
+  callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    return this.#callAction(action, params);
+  }
+
   /** Test / internal: admit a parsed event when the endpoint is open. */
   admit(ev: OneBot12Event): void {
     if (!this.#open || !isMessageEvent(ev)) return;
@@ -149,7 +178,7 @@ export class OneBot12WsEndpoint implements EndpointInstance {
     });
   }
 
-  async #connect(): Promise<void> {
+  async #connect(handle: EndpointConnectHandle): Promise<void> {
     const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
     const create = this.#options.createWebSocket
       ?? ((connectUrl: string, options: OneBot12WsCreateOptions) =>
@@ -159,6 +188,13 @@ export class OneBot12WsEndpoint implements EndpointInstance {
       let settled = false;
       const ws = create(url, { headers });
       this.#ws = ws;
+      handle.onForceClose(() => {
+        try {
+          ws.close();
+        } catch {
+          /* ignore */
+        }
+      });
 
       ws.on('open', () => {
         if (settled) return;
@@ -168,7 +204,9 @@ export class OneBot12WsEndpoint implements EndpointInstance {
           mode: 'ws',
           url: safeUrl,
         }));
-        this.#startHeartbeat();
+        this.#lifecycle.startHeartbeat(() => {
+          this.#callAction('get_status', {}).catch(() => {});
+        });
         resolve();
       });
 
@@ -183,18 +221,13 @@ export class OneBot12WsEndpoint implements EndpointInstance {
             ? 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) => {
@@ -259,29 +292,4 @@ export class OneBot12WsEndpoint implements EndpointInstance {
       this.#ws!.send(JSON.stringify(req));
     });
   }
-
-  #startHeartbeat(): void {
-    if (this.#heartbeatTimer) {
-      clearInterval(this.#heartbeatTimer);
-    }
-    this.#heartbeatTimer = setInterval(() => {
-      this.#callAction('get_status', {}).catch(() => {});
-    }, this.#options.config.heartbeat_interval);
-  }
-
-  #scheduleReconnect(): void {
-    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/src/wss-endpoint.ts

@@ -2,11 +2,12 @@
  * OneBot12 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
 import { clearInterval } from 'node:timers';
-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, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { createOneBot12EndpointManagement } from './endpoint-management.js';
 import {
   buildSendMessageParams,
   formatInboundContent,
@@ -16,6 +17,7 @@ import {
   isMessageEvent,
   senderNickname,
   senderUserId,
+  uploadOneBot12MediaSegments,
   type OneBot12ActionRequest,
   type OneBot12ActionResponse,
   type OneBot12Event,
@@ -35,6 +37,7 @@ export interface OneBot12WssEndpointOptions {
 
 export class OneBot12WssEndpoint implements EndpointInstance {
   readonly #options: OneBot12WssEndpointOptions;
+  readonly management: EndpointManagement = createOneBot12EndpointManagement(this);
   #ws?: OneBot12WsSocket;
   #wsRelease?: () => void;
   #heartbeatTimer?: NodeJS.Timeout;
@@ -54,6 +57,15 @@ export class OneBot12WssEndpoint implements EndpointInstance {
   async start(): Promise<void> {
     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);
@@ -99,12 +111,28 @@ export class OneBot12WssEndpoint implements EndpointInstance {
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    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) as { message_id?: string } | undefined;
     return data?.message_id ?? '';
   }
 
+  /** Public API for management surface / callers. */
+  callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    return this.#callAction(action, params);
+  }
+
   admit(ev: OneBot12Event): void {
     if (!this.#open || !isMessageEvent(ev)) return;
     const target = formatInboundTarget(ev);

package/plugin.ts

@@ -1,8 +0,0 @@
-import { definePlugin } from '@zhin.js/plugin-runtime';
-
-export default definePlugin({
-  name: 'onebot12',
-  metadata: {
-    displayName: 'OneBot 12 Adapter',
-  },
-});