@zhin.js/adapter-onebot11 1.1.18 → 1.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot11",
-  "version": "1.1.18",
+  "version": "1.1.20",
   "description": "Zhin.js OneBot 11 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -45,19 +45,19 @@
     "@imhelper/onebot-v11": "1.0.7",
     "imhelper": "1.0.7",
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.25",
-    "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/client": "1.1.21",
+    "@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.53",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
+    "@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/page": "1.1.10",
-    "@zhin.js/permission": "1.1.9",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.12"
+    "@zhin.js/page": "1.1.12",
+    "@zhin.js/permission": "1.1.10",
+    "@zhin.js/skill": "1.1.11",
+    "@zhin.js/tool": "1.1.13"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -65,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.18"
+    "@zhin.js/host-http": "1.1.12",
+    "zhin.js": "1.1.19"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.25",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.53",
-    "zhin.js": "^1.1.18"
+    "@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": {
@@ -107,7 +107,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",

package/plugin.js

@@ -1,8 +1,6 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { createEndpointRuntimeState } from 'zhin.js/adapter';
 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',
@@ -10,7 +8,6 @@ export default definePlugin({
         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);

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.ts

@@ -5,17 +5,14 @@
  */
 import { createAdapterConsoleRpc, type AdapterConsoleResources } from 'zhin.js/adapter';
 import type { PluginConsoleRpc } from 'zhin.js';
-import { onebot11RuntimeStateToken } from './onebot11-runtime-state.js';
 import { onebot11ConsoleSpec } from './console-spec.js';
 
 export function createOnebot11ConsoleRpc(
-  resources: AdapterConsoleResources,
+  _resources: AdapterConsoleResources,
   getConfig: () => unknown,
 ): PluginConsoleRpc {
-  const state = resources.use(onebot11RuntimeStateToken);
   return createAdapterConsoleRpc({
     ...onebot11ConsoleSpec,
-    running: () => state.endpoints.values(),
     getConfig,
-  }, resources);
+  });
 }

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);
     },
   });

package/src/identity.ts

@@ -0,0 +1,30 @@
+import WebSocket from 'ws';
+import { buildWsConnectOptions, type OneBot11WsConfig } from './protocol.js';
+import { createOneBot11Rpc } from './ws-transport.js';
+import { resolveOnebot11SelfId } from './self-id.js';
+
+/** Separate read-only connection: never changes credentials or state of the running Endpoint. */
+export async function probeOnebot11Identity(config: OneBot11WsConfig, signal: AbortSignal): Promise<string | undefined> {
+  signal.throwIfAborted();
+  const { url, headers } = buildWsConnectOptions(config);
+  const socket = new WebSocket(url, { headers });
+  const rpc = createOneBot11Rpc({ endpointId: config.id, signal, socket: () => socket, });
+  let rejectOpen: (error: unknown) => void = () => undefined;
+  const abort = () => { rejectOpen(signal.reason); rpc.disconnect(); socket.terminate(); };
+  signal.addEventListener('abort', abort, { once: true });
+  socket.on('message', data => rpc.receive(data, () => undefined));
+  socket.on('close', () => { rejectOpen(new Error('Identity connection closed')); rpc.disconnect(); });
+  try {
+    await new Promise<void>((resolve, reject) => { rejectOpen = reject; socket.once('open', resolve); socket.on('error', reject); });
+    signal.throwIfAborted();
+
+    const response = await rpc.call({ action: 'get_login_info' });
+    signal.throwIfAborted();
+    if (response.status !== 'ok' || response.retcode !== 0) throw new Error('OneBot11 identity lookup failed');
+    const data: unknown = response.data;
+    const id = resolveOnebot11SelfId(data && typeof data === 'object' && 'user_id' in data ? data.user_id : undefined);
+    return id === undefined ? undefined : `qq:${id}`;
+  } finally {
+    signal.removeEventListener('abort', abort); rpc.dispose(); socket.terminate();
+  }
+}

package/src/index.ts

@@ -40,17 +40,16 @@ export {
 export type { OneBot11WsSocket, OneBot11WsCreateOptions } from './ws-types.js';
 
 export {
-  callOneBot11WsAction,
+  createOneBot11Rpc,
+  type OneBot11Rpc,
+  type OneBot11RpcOptions,
   decodeWsPayload,
-  handleOneBot11WsMessage,
-  rejectAllPending,
 } from './ws-transport.js';
 
 export { verifyOneBotAccessToken } from './wss-auth.js';
 
 export {
   Onebot11Client,
-  onebot11Client,
   type Onebot11ClientEventMap,
 } from './client.js';
 
@@ -64,3 +63,4 @@ export type {
 } from '@imhelper/onebot-v11';
 export { ProtocolError } from '@imhelper/onebot-v11';
 export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';
+export { Onebot11Adapter } from './adapter.js';

package/src/self-id.ts

@@ -19,7 +19,7 @@ export async function probeOnebot11SelfId(
   onError: (error: unknown) => void,
 ): Promise<string | undefined> {
   try {
-    const data = await callOnebot11Client<{ user_id?: number | string }>(client, 'get_login_info');
+    const data = await callOnebot11Client<{ user_id?: number | string }>({ client, action: 'get_login_info' });
     return resolveOnebot11SelfId(data?.user_id);
   } catch (error) {
     onError(error);

package/src/side-event-dispatch.ts

@@ -7,13 +7,15 @@ export interface OneBot11SideEventCaller {
   callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
 }
 
-export function receiveOneBot11SideEvent(
-  emit: EndpointEventEmitter,
-  endpointKey: string,
-  caller: OneBot11SideEventCaller,
-  raw: OneBot11Event,
-  logger: ReturnType<typeof getAdapterLogger>,
-): void {
+/** Exact instance-owned dependencies for one canonical side-event projection. */
+export interface OneBot11SideEventContext {
+  readonly emit: EndpointEventEmitter;
+  readonly endpointKey: string;
+  readonly caller: OneBot11SideEventCaller;
+  readonly logger: ReturnType<typeof getAdapterLogger>;
+}
+export function receiveOneBot11SideEvent(raw: OneBot11Event, context: OneBot11SideEventContext): void {
+  const { emit, endpointKey, caller, logger } = context;
   if (!emit) return;
   const record = raw as Record<string, unknown>;
   const postType = String(record.post_type ?? '');