@zhin.js/adapter-onebot11 1.1.17 → 1.1.19

package/lib/wss-endpoint.js

@@ -2,33 +2,38 @@ import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
-import { ClientEndpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { createEndpointSpecification, endpointSpec, 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 { createOneBot11Rpc } from './ws-transport.js';
 import { probeOnebot11SelfId, resolveOnebot11SelfId } from './self-id.js';
-import { callOnebot11Client, createOnebot11EndpointClient, forwardOnebot11ClientEvents } from './client.js';
-export class OneBot11WssEndpoint extends ClientEndpoint {
-    client;
+import { callOnebot11Client, readOnebot11Response, onebot11ClientOptions, forwardOnebot11ClientEvents, Onebot11Client } from './client.js';
+export class OneBot11WssEndpoint extends Onebot11Client {
+    [endpointSpec];
+    #open = false;
     #logger;
     #options;
-    management;
-    control = createRecallEndpointControl((id) => this.recallMessage(id));
-    content;
+    #management;
+    #control = createRecallEndpointControl((id, signal) => this.#recallMessage(id, signal));
+    #content;
+    #releaseClientEvents;
     #ws;
     #wsRelease;
     #connectionLifecycle;
     #connectionTask = Promise.resolve();
-    #requestId = { value: 0 };
-    #pending = new Map();
+    #rpc;
     #started = false;
     #stopped = false;
     constructor(options) {
-        super();
+        const rpc = createOneBot11Rpc({ endpointId: options.config.id, signal: options.signal,
+            socket: () => this.#connectionLifecycle.state === 'closed' ? undefined : this.#ws,
+        });
+        super(onebot11ClientOptions(options.config, (action, params) => rpc.call({ action, params })));
+        this.#rpc = rpc;
         this.#logger = getAdapterLogger('onebot11', options.config.id);
         this.#options = options;
         this.#connectionLifecycle = createEndpointLifecycle({
@@ -36,16 +41,29 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
             reconnect: false,
             heartbeat: { intervalMs: options.config.heartbeat_interval, watchdogMisses: 2 },
         });
-        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));
+        const callApi = (request) => this.#rpc.call(request).then(readOnebot11Response);
+        this.#management = createOneBot11EndpointManagement({ callApi });
+        this.#content = createOneBot11ContentPort(callApi);
+        const readTransportState = () => this.#transportState;
+        this[endpointSpec] = createEndpointSpecification(this, {
+            name: options.config.id,
+            start: () => this.#start(), open: () => { this.#open = true; },
+            close: () => { this.#open = false; }, stop: () => this.#stop(),
+            send: request => this.#send(request),
+            get transportState() { return readTransportState(); },
+            management: this.#management, control: this.#control, content: this.#content,
+        });
+        this.#releaseClientEvents = forwardOnebot11ClientEvents(this, (name, payload) => {
+            void this[endpointSpec].events.run(() => {
+                if (this.#stopped || (!this.#open && !this.#started))
+                    return;
+                void this[endpointSpec].events.platform(name, payload).catch(error => this.#warnPlatformEvent(error));
+                if (name === 'event')
+                    this.#admitRaw(payload);
+            }).catch(error => this.#warnPlatformEvent(error));
+        });
     }
-    get transportState() {
+    get #transportState() {
         if (this.#stopped)
             return 'stopped';
         if (!this.#started)
@@ -56,7 +74,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
             return 'open';
         return this.#connectionLifecycle.state === 'connecting' ? 'connecting' : 'idle';
     }
-    async start() {
+    async #start() {
         if (this.#started)
             return;
         this.#stopped = false;
@@ -89,47 +107,56 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
             path: this.#options.config.path,
         }));
     }
-    async stop() {
+    async #stop() {
         this.#stopped = true;
-        this.close();
+        this.#open = false;
         this.#wsRelease?.();
         this.#wsRelease = undefined;
-        await this.#connectionTask;
-        await this.#connectionLifecycle.stop();
-        rejectAllPending(this.#pending);
-        this.#ws = undefined;
-        this.#started = false;
-        this.reportSelfUserId(undefined);
+        try {
+            await this.#connectionTask;
+            await this.#connectionLifecycle.stop();
+        }
+        finally {
+            this.#rpc.dispose();
+            this.#releaseClientEvents();
+            this.#ws = undefined;
+            this.#started = false;
+            this[endpointSpec].reportSelfUserId(undefined);
+        }
     }
-    async send({ conversation, payload }) {
+    async #send({ conversation, payload, signal }) {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(conversation, message);
-        const data = await callOnebot11Client(this.client, action, params);
+        const data = readOnebot11Response(await this.#rpc.call({ action, params, signal }));
         const rawId = data?.message_id;
         if ((typeof rawId !== 'number' && typeof rawId !== 'string') || String(rawId).trim() === '' || (typeof rawId === 'number' && !Number.isFinite(rawId))) {
             throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: platform returned no message_id', 'unknown');
         }
         return String(rawId);
     }
-    async recallMessage(messageId) {
+    async #recallMessage(messageId, signal) {
         if (!messageId)
             return;
-        await callOnebot11Client(this.client, 'delete_msg', { message_id: Number(messageId) });
-    }
-    #callApi(action, params = {}) {
-        return callOneBot11WsAction(this.#connectionLifecycle.state === 'closed' ? undefined : this.#ws, this.#pending, this.#requestId, action, params);
+        await this.#rpc.call({ action: 'delete_msg', params: { message_id: Number(messageId) }, signal }).then(readOnebot11Response);
     }
     #admitRaw(ev) {
         const selfId = resolveOnebot11SelfId(ev.self_id);
-        if (!this.#stopped && selfId && selfId !== this.selfUserId)
-            this.reportSelfUserId(selfId);
+        if (!this.#stopped && selfId)
+            this[endpointSpec].reportSelfUserId(selfId);
         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);
+            receiveOneBot11SideEvent(ev, {
+                emit: (name, payload) => this[endpointSpec].events.emit(name, payload),
+                endpointKey: this.#options.config.id,
+                caller: { callApi: (action, params) => callOnebot11Client({ client: this, action, params }) },
+                logger: this.#logger,
+            });
             return;
         }
-        const conversation = onebot11InboundConversation(String(this.#options.id), ev);
+        const conversation = { ...onebot11InboundConversation(String(this.#options.id), ev), endpoint: this[endpointSpec].identity };
         const inbound = formatInboundMetadata(ev, this.#options.config.id);
-        void this.emit('message.receive', {
+        void this[endpointSpec].events.message({
+            event: ev,
+            ...(typeof ev.time === 'number' ? { platformSentAt: ev.time * 1000 } : {}),
             conversation,
             message: { conversation, id: String(ev.message_id) },
             content: formatInboundContent(ev),
@@ -152,16 +179,16 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
     }
     /** Best-effort 登录账号探测；失败仅 debug，不影响连接。 */
     async #probeSelfUserId() {
-        const selfId = await probeOnebot11SelfId(this.client, (error) => {
+        const selfId = await probeOnebot11SelfId(this, (error) => {
             this.#logger.debug(formatCompact({
                 op: 'onebot11_get_login_info_failed',
                 error: error instanceof Error ? error.message : String(error),
             }));
         });
-        if (this.#stopped || this.transportState !== 'open')
+        if (this.#stopped || this.#transportState !== 'open')
             return;
-        if (selfId && selfId !== this.selfUserId)
-            this.reportSelfUserId(selfId);
+        if (selfId)
+            this[endpointSpec].reportSelfUserId(selfId);
     }
     #warnPlatformEvent(error) {
         this.#logger.warn(formatCompact({
@@ -180,12 +207,12 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
         }
         const socket = connection.socket;
         await this.#connectionLifecycle.stop();
-        rejectAllPending(this.#pending, '连接已替换');
+        this.#rpc.disconnect('连接已替换');
         await this.#connectionLifecycle.start(async (lifecycleHandle) => {
             this.#ws = socket;
             lifecycleHandle.onForceClose(() => {
                 if (this.#ws === socket) {
-                    rejectAllPending(this.#pending);
+                    this.#rpc.disconnect();
                 }
                 try {
                     socket.close();
@@ -212,11 +239,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
                 if (this.#ws !== socket || this.#connectionLifecycle.state === 'closed')
                     return;
                 this.#connectionLifecycle.notifyHeartbeatAck();
-                handleOneBot11WsMessage(data, {
-                    endpointId: this.#options.config.id,
-                    pending: this.#pending,
-                    ingest: (ev) => this.client.ingest(ev),
-                });
+                this.#rpc.receive(data, (ev) => this.ingest(ev));
             });
             socket.on('error', (error) => {
                 if (this.#ws !== socket)
@@ -228,7 +251,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
                     return;
                 if (this.#ws === socket) {
                     this.#ws = undefined;
-                    rejectAllPending(this.#pending);
+                    this.#rpc.disconnect();
                 }
                 lifecycleHandle.notifyClosed(new Error('OneBot11 reverse WebSocket closed'));
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot11",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "description": "Zhin.js OneBot 11 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,6 +14,7 @@
   "files": [
     "adapters",
     "commands",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -44,16 +45,19 @@
     "@imhelper/onebot-v11": "1.0.7",
     "imhelper": "1.0.7",
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.24",
-    "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/core": "1.1.52",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
-    "@zhin.js/im-contract": "1.1.8",
+    "@zhin.js/adapter": "1.1.26",
+    "@zhin.js/agent-feature": "1.1.11",
+    "@zhin.js/client": "1.1.22",
+    "@zhin.js/console-contract": "1.1.3",
+    "@zhin.js/core": "1.1.54",
+    "@zhin.js/feature-kit": "1.1.10",
+    "@zhin.js/host-http": "1.1.12",
+    "@zhin.js/im-contract": "1.1.9",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/permission": "1.1.9",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.11"
+    "@zhin.js/page": "1.1.11",
+    "@zhin.js/permission": "1.1.10",
+    "@zhin.js/skill": "1.1.11",
+    "@zhin.js/tool": "1.1.13"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -61,15 +65,15 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.11",
-    "zhin.js": "1.1.17"
+    "@zhin.js/host-http": "1.1.12",
+    "zhin.js": "1.1.19"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.24",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.52",
-    "zhin.js": "^1.1.17"
+    "@zhin.js/adapter": "^1.1.26",
+    "@zhin.js/command": "^1.1.12",
+    "@zhin.js/core": "^1.1.54",
+    "zhin.js": "^1.1.19"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -103,7 +107,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",
@@ -120,6 +124,10 @@
       {
         "package": "@zhin.js/agent-feature",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/pages/index/index.js

@@ -0,0 +1,15 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+export const meta = definePage({
+    title: 'OneBot 11',
+    titleI18n: { en: 'OneBot 11' },
+    icon: 'Bot',
+    order: 70,
+    requiredPermissions: ['onebot11:read'],
+});
+/**
+ * Convention page: `pages/index/index.ts` → `/onebot11`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('onebot11');

package/pages/index/index.ts

@@ -0,0 +1,16 @@
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+
+export const meta = definePage({
+  title: 'OneBot 11',
+  titleI18n: { en: 'OneBot 11' },
+  icon: 'Bot',
+  order: 70,
+  requiredPermissions: ['onebot11:read'],
+});
+
+/**
+ * Convention page: `pages/index/index.ts` → `/onebot11`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('onebot11');

package/plugin.js

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

package/src/adapter.ts

@@ -0,0 +1,32 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { resolveOneBot11Config, type OneBot11EndpointConfig } from './protocol.js';
+import { OneBot11WsEndpoint } from './ws-endpoint.js';
+import { OneBot11WssEndpoint } from './wss-endpoint.js';
+import { probeOnebot11Identity } from './identity.js';
+import type { Onebot11ClientEventMap } from './client.js';
+
+export class Onebot11Adapter extends Adapter<OneBot11WsEndpoint | OneBot11WssEndpoint, OneBot11EndpointConfig, Onebot11ClientEventMap> {
+  readonly #context: AdapterContext<OneBot11EndpointConfig>;
+  constructor(context: AdapterContext<OneBot11EndpointConfig>) { super(); this.#context = context; }
+  override get configurationIdentityFields(): readonly string[] { return ['id']; }
+  override get configurationIdentityProbeFields(): readonly string[] { return ['connection', 'access_token', 'url']; }
+  override get configurationUpdateFields(): readonly string[] {
+    return ['connection', 'url', 'path', 'access_token', 'reconnect_interval', 'heartbeat_interval'];
+  }
+  protected override validateConfiguration(config: OneBot11EndpointConfig): void { resolveOneBot11Config(config); }
+  protected override async identifyConfiguration(input: OneBot11EndpointConfig, signal: AbortSignal): Promise<string | undefined> {
+    const config = resolveOneBot11Config(input);
+    return config.connection === 'ws' ? probeOnebot11Identity(config, signal) : undefined;
+  }
+  protected createEndpoint(input: OneBot11EndpointConfig, execution: EndpointCreationContext): OneBot11WsEndpoint | OneBot11WssEndpoint {
+    const config = resolveOneBot11Config(input);
+    return config.connection === 'wss'
+      ? new OneBot11WssEndpoint({ id: execution.canonicalId, signal: execution.signal, http: this.#context.use(httpHostToken), config, probeLoginInfo: true })
+      : new OneBot11WsEndpoint({ id: execution.canonicalId, signal: execution.signal, config, probeLoginInfo: true });
+  }
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterRegistry { readonly onebot11: Onebot11Adapter; }
+}

package/src/client.ts

@@ -1,11 +1,11 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import {
   OneBotV11Client,
   type OneBotV11Event as ImHelperOneBot11Event,
   type OneBotV11Response,
 } from '@imhelper/onebot-v11';
-import { EventFactory, type EventMap, type ImHelperEventMap } from 'imhelper';
+import { ProtocolError, EventFactory, type EventMap, type ImHelperEventMap } from 'imhelper';
 import {
-  defineEndpointClient,
   forwardEndpointClientEvents,
   type ClientEventPayloads,
 } from 'zhin.js/adapter';
@@ -25,11 +25,11 @@ type Onebot11ClientEvents = ImHelperEventMap<
 >;
 export type Onebot11ClientEventMap = ClientEventPayloads<Onebot11ClientEvents>;
 
-export function createOnebot11EndpointClient(
+export function onebot11ClientOptions(
   config: ResolvedOneBot11Config,
   request: Onebot11ApiCall,
-): OneBotV11Client {
-  return new OneBotV11Client({
+): ConstructorParameters<typeof OneBotV11Client>[0] {
+  return {
     baseUrl: config.connection === 'ws'
       ? config.url.replace(/^ws(s?):/, 'http$1:')
       : 'http://localhost',
@@ -37,21 +37,42 @@ export function createOnebot11EndpointClient(
     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}` : ''}`,
-    );
+export interface Onebot11ClientRequest {
+  readonly client: OneBotV11Client;
+  readonly action: string;
+  readonly params?: Record<string, unknown>;
+}
+/** Native methods retain ProtocolError; framework ports preserve the underlying delivery evidence. */
+export async function callOnebot11Client<T = unknown>(request: Onebot11ClientRequest): Promise<T | undefined> {
+  try {
+    return readOnebot11Response<T>(await request.client.call<T>(request.action, request.params));
+  } catch (error) {
+    if (error instanceof ProtocolError) {
+      if (error.cause instanceof EndpointDeliveryError) throw error.cause;
+      if (error.response !== undefined) readOnebot11Response(error.response);
+    }
+    throw error;
   }
-  return response.data;
+}
+
+/**
+ * Framework evidence follows the OB11 response envelope, including async/1 submission.
+ * @see https://github.com/botuniverse/onebot-11/blob/master/communication/http.md
+ */
+export function readOnebot11Response<T = unknown>(response: unknown): T | undefined {
+  if (response && typeof response === 'object') {
+    const result = response as Partial<OneBotV11Response>;
+    if (result.status === 'ok' && result.retcode === 0) return result.data as T | undefined;
+    if (result.status === 'failed' && Number.isSafeInteger(result.retcode) && result.retcode !== 0 && result.retcode !== 1) {
+      throw new EndpointDeliveryError('platform_rejected',
+        `OneBot 11 API rejected: retcode=${result.retcode}${result.message ? ` ${result.message}` : ''}`, 'rejected');
+    }
+  }
+  // OB11 async/1 acknowledges submission, never the final outcome.
+  throw new EndpointDeliveryError('delivery_unconfirmed', 'OneBot 11 response did not confirm the action result', 'unknown');
 }
 
 const onebot11ClientEventNames = Object.freeze([
@@ -65,14 +86,3 @@ export function forwardOnebot11ClientEvents(
 ): () => 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/console-spec.ts

@@ -0,0 +1,17 @@
+/**
+ * OneBot 11 Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+
+export const onebot11ConsoleSpec = {
+  adapterKey: 'onebot11',
+  adapterDisplayName: 'OneBot 11',
+  fields: [
+    { key: 'url', description: 'OneBot 实现 WebSocket URL（connection: ws 必填）', descriptionI18n: { en: 'OneBot WebSocket URL (required for connection: ws)' } },
+    { key: 'path', description: 'reverse-wss 路径（connection: wss）', descriptionI18n: { en: 'Reverse WebSocket path (connection: wss)' } },
+    { key: 'access_token', env: true, description: 'OneBot access token' },
+  ] as readonly AdapterConsoleField[],
+  docsUrl: 'https://zhin.js.org/adapters/onebot11',
+  readPermission: 'onebot11:read',
+  writePermission: 'onebot11:write',
+} as const;

package/src/console.ts

@@ -0,0 +1,18 @@
+/**
+ * OneBot 11 Console RPC：运行状态 + endpoint 增删（原 `onebot11 endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc, type AdapterConsoleResources } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+import { onebot11ConsoleSpec } from './console-spec.js';
+
+export function createOnebot11ConsoleRpc(
+  _resources: AdapterConsoleResources,
+  getConfig: () => unknown,
+): PluginConsoleRpc {
+  return createAdapterConsoleRpc({
+    ...onebot11ConsoleSpec,
+    getConfig,
+  });
+}

package/src/content-port.ts

@@ -1,8 +1,8 @@
-import type { EndpointContentPort, EndpointContentResolveContext } from 'zhin.js/adapter';
+import type { EndpointContentPort, EndpointContentResolveContext, PendingRpcRequest } 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>;
+type CallApi = (request: PendingRpcRequest) => Promise<unknown>;
 
 export function createOneBot11ContentPort(callApi: CallApi): EndpointContentPort {
   return Object.freeze({
@@ -15,7 +15,7 @@ export function createOneBot11ContentPort(callApi: CallApi): EndpointContentPort
             : 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>;
+          const row = await callApi({ action: 'get_msg', params: { message_id: reference.message.id }, signal: context.signal }) as Record<string, unknown>;
           context.signal.throwIfAborted();
           const segments = normalizeSegments(row.message ?? row.raw_message);
           const sender = row.sender as Record<string, unknown> | undefined;
@@ -30,7 +30,7 @@ export function createOneBot11ContentPort(callApi: CallApi): EndpointContentPort
           });
           return Object.freeze({ status: 'resolved' as const, reference, value });
         }
-        const raw = await callApi('get_forward_msg', { id: reference.forwardId }) as Record<string, unknown>;
+        const raw = await callApi({ action: 'get_forward_msg', params: { id: reference.forwardId }, signal: context.signal }) 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) => {

package/src/endpoint-management.ts

@@ -7,23 +7,26 @@
  * - group → {group_id:number, name: group_name ?? name}
  * - 群成员列表保持 OneBot11 原生形状，仅保证数组
  */
-import type {
-  EndpointFriend,
-  EndpointGroup,
-  EndpointManagement,
+import {
+  type EndpointFriend,
+  type EndpointGroup,
+  type EndpointManagement,
+  type EndpointManagementRequest,
+  type EndpointGroupRequest,
+  type PendingRpcRequest,
 } from 'zhin.js/adapter';
 
 /** 管理面只依赖 endpoint 的 callApi（ws/wss 两种传输各自实现）。 */
 export interface OneBot11ManagementCaller {
-  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+  callApi(request: PendingRpcRequest): Promise<unknown>;
 }
 
 export function createOneBot11EndpointManagement(
   endpoint: OneBot11ManagementCaller,
 ): EndpointManagement {
   return Object.freeze<EndpointManagement>({
-    async listFriends(): Promise<readonly EndpointFriend[]> {
-      const data = await endpoint.callApi('get_friend_list');
+    async listFriends(request: EndpointManagementRequest = {}): Promise<readonly EndpointFriend[]> {
+      const data = await endpoint.callApi({ action: 'get_friend_list', signal: request.signal });
       return toArray(data).map((value) => {
         const friend = asRecord(value);
         return {
@@ -33,8 +36,8 @@ export function createOneBot11EndpointManagement(
         };
       });
     },
-    async listGroups(): Promise<readonly EndpointGroup[]> {
-      const data = await endpoint.callApi('get_group_list');
+    async listGroups(request: EndpointManagementRequest = {}): Promise<readonly EndpointGroup[]> {
+      const data = await endpoint.callApi({ action: 'get_group_list', signal: request.signal });
       return toArray(data).map((value) => {
         const group = asRecord(value);
         return {
@@ -43,10 +46,10 @@ export function createOneBot11EndpointManagement(
         };
       });
     },
-    async listGroupMembers(groupId: string): Promise<readonly unknown[]> {
-      const data = await endpoint.callApi('get_group_member_list', {
+    async listGroupMembers({ groupId, signal }: EndpointGroupRequest): Promise<readonly unknown[]> {
+      const data = await endpoint.callApi({ action: 'get_group_member_list', signal, params: {
         group_id: toNumberId(groupId, 'group_id'),
-      });
+      } });
       return toArray(data);
     },
   });