@zhin.js/adapter-onebot11 7.0.0 → 7.0.2

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @zhin.js/adapter-onebot11
 
+## 7.0.2
+
+### Patch Changes
+
+- Updated dependencies [736fa04]
+  - @zhin.js/agent@1.1.17
+  - zhin.js@6.0.14
+
+## 7.0.1
+
+### Patch Changes
+
+- 4e8117c: Expose the published imhelper protocol Clients from every Endpoint, preserve native action responses, and route host-owned HTTP, WebSocket, and raw ingress through the Client APIs. Add the shared `ClientEndpoint` deep base so concrete transports inherit one open-gated Client event bridge, and move reverse WebSocket lifecycle and heartbeat cleanup onto the common lifecycle state machine.
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- 2ca9a52: Upgrade the protocol Clients to imhelper 1.0.7, keep receiver ownership exclusively in Endpoint through manual mode, expose structured protocol errors, and support canonical non-message Client events.
+- Updated dependencies [e9c6a73]
+- Updated dependencies [4e8117c]
+- Updated dependencies [902fa35]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/agent@1.1.16
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/host-http@1.0.13
+  - @zhin.js/command@1.0.16
+  - @zhin.js/logger@1.0.77
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+  - @zhin.js/permission@1.0.4
+
 ## 7.0.0
 
 ### Patch Changes

package/README.md

@@ -8,7 +8,7 @@ Zhin.js [OneBot 11](https://github.com/botuniverse/onebot-11) 适配器（Plugin
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - **正向 WebSocket**（`connection: ws`）：应用连 OneBot 实现的 WS 服务器
 - `access_token` 鉴权（Bearer + query）
-- 入站经 `messageGatewayToken`；出站 `send({ conversation, payload })`
+- 入站经 `Endpoint.emit(...)`；出站 `send({ conversation, payload })`
 
 ## 安装
 
@@ -19,13 +19,23 @@ pnpm add @zhin.js/adapter-onebot11
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/onebot11.ts`（`defineAdapter`）
-- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
+每个 Endpoint 的 `$client` 是 `@imhelper/onebot-v11` 的 `OneBotV11Client`。业务代码直接调用
+`$client.call(action, params)` 和 Client 的公开平台能力；双工 WS 的 `echo` 响应由 Endpoint
+先行分流，只有事件帧进入 Client 的 `ingest()` 和公开事件流。
+
 入站：`gateway.receive({ conversation, message, content, sender, metadata })`（`conversation.kind` 为 `private`/`group`，`id` 为 uid/gid）  
 出站：`send({ conversation, payload })` → WS `send_private_msg` / `send_group_msg`（payload 已由 gateway/core 渲染；无 segment-mapper）
 
+## 前置条件
+
+1. 启动兼容 OneBot 11 的实现，并选定正向或反向 WebSocket。
+2. 正向 WS 需 Zhin 可达实现端；反向 WS 需实现端可达 Zhin HTTP Host。
+3. 两端配置相同的 `access_token`，生产环境不要开放无鉴权连接。
+
 ## 最小配置
 
 ```yaml
@@ -70,8 +80,8 @@ plugins:
 
 ## 迁移说明（Plugin Runtime）
 
-- **notice / request / meta 侧事件**：经 `sideEventGatewayToken` 归一后分发到 `handlers`；消息仍走 `messageGatewayToken`。
-- **群管工具暂未迁移**：旧 Adapter 经 `createSceneManagementTools` 注册踢人 / 禁言 / 群名片等成套 agent 工具；迁移后仅保留 `onebot11_set_title`，其余群管能力可通过 `callApi`（如 `set_group_kick`、`set_group_ban`）作为逃生舱调用。
+- **notice / request / meta 侧事件**：经 the unified `Endpoint.emit(...)` ingress 归一后分发到 `handlers`；消息仍走 `outboundMessageToken`。
+- **群管工具暂未迁移**：旧 Adapter 经 `createSceneManagementTools` 注册踢人 / 禁言 / 群名片等成套 agent 工具；迁移后仅保留 `onebot11_set_title`，其余群管能力可通过 `$client.call()`（如 `set_group_kick`、`set_group_ban`）作为逃生舱调用。
 - **平台权限门禁**：`plugin.ts` setup 已注册 `registerDefaultScenePlatformPermitChecker('onebot11')`，`scene_admin` / `scene_owner` 依据入站 metadata 中的 sender `role`（owner / admin）判定。
 
 ## 文档链接
@@ -79,6 +89,15 @@ plugins:
 - [OneBot 11 标准](https://github.com/botuniverse/onebot-11)
 - [适配器概览](https://zhin.js.org/essentials/adapters)
 
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| WS 无法建立 | 核对连接方向、URL、端口与实现端 WS 服务 |
+| 401 或握手关闭 | 确认 Header/query token 与实现端一致 |
+| 能收不能发 | 检查发送动作支持与账号风控状态 |
+| notice/request 不出现 | 确认实现端上报对应 post type，并查看 Endpoint 请求/通知 |
+
 ## 许可证
 
 MIT License

package/adapters/onebot11.js

@@ -3,7 +3,6 @@
  * Convention entry: discover `adapters/onebot11.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { OneBot11WsEndpoint } from "../lib/ws-endpoint.js";
 import { OneBot11WssEndpoint } from "../lib/wss-endpoint.js";
@@ -21,8 +20,6 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveOneBot11Config(context.config);
-        const gateway = context.use(messageGatewayToken);
-        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（onebot11.endpoint list 的"运行中"数据源）
         context.use(onebot11RuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
@@ -31,16 +28,12 @@ export default defineAdapter({
         if (config.connection === 'wss') {
             return new OneBot11WssEndpoint({
                 id: context.id,
-                gateway,
-                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
         }
         return new OneBot11WsEndpoint({
             id: context.id,
-            gateway,
-            sideEvents,
             config,
         });
     },

package/adapters/onebot11.ts

@@ -2,7 +2,6 @@
  * Convention entry: discover `adapters/onebot11.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { OneBot11WsEndpoint } from '../src/ws-endpoint.js';
 import { OneBot11WssEndpoint } from '../src/wss-endpoint.js';
@@ -34,8 +33,6 @@ export default defineAdapter<OneBot11AdapterConfig>({
   },
   create(context) {
     const config = resolveOneBot11Config(context.config);
-    const gateway = context.use(messageGatewayToken);
-    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（onebot11.endpoint list 的"运行中"数据源）
     context.use(onebot11RuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
@@ -44,16 +41,12 @@ export default defineAdapter<OneBot11AdapterConfig>({
     if (config.connection === 'wss') {
       return new OneBot11WssEndpoint({
         id: context.id,
-        gateway,
-        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
     }
     return new OneBot11WsEndpoint({
       id: context.id,
-      gateway,
-      sideEvents,
       config,
     });
   },

package/agent/tools/set_title.ts

@@ -1,21 +1,24 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getOnebot11AgentDeps } from '../../src/onebot11-agent-deps.js';
-export default defineAgentTool<{ endpoint_id: string; group_id: number; user_id: number; title: string }>({
+export default defineAgentTool<{ group_id: number; user_id: number; title: string }>({
   description: '设置 QQ 群成员的专属头衔。只有群主才能设置。',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     group_id: z.number().describe('目标群号'),
     user_id: z.number().describe('目标成员 QQ号'),
     title: z.string().describe('头衔文字'),
   }),
-  platforms: ['onebot11'],
+  adapter: 'onebot11',
   tags: ['onebot11'],
   permissions: ['platform(onebot11,scene_owner)'],
-  async execute({ endpoint_id, group_id, user_id, title    }: { endpoint_id: string; group_id: number; user_id: number; title: string }) {
-    const endpoint = getOnebot11AgentDeps().getEndpoint(endpoint_id);
-    const success = await endpoint.setTitle(group_id, user_id, title);
+  async execute({ group_id, user_id, title }: { group_id: number; user_id: number; title: string }, context) {
+    const client = context.$client;
+    const response = await client.call('set_group_special_title', {
+      group_id,
+      user_id,
+      special_title: title,
+      duration: -1,
+    });
+    const success = response.status === 'ok';
     return { success, message: success ? `已将 ${user_id} 的头衔设为 "${title}"` : '设置失败' };
   },
 });
-

package/lib/client.d.ts

@@ -0,0 +1,20 @@
+import { OneBotV11Client, type OneBotV11Event as ImHelperOneBot11Event, type OneBotV11Response } from '@imhelper/onebot-v11';
+import { type EventMap, type ImHelperEventMap } from 'imhelper';
+import { type ClientEventPayloads } from 'zhin.js/adapter';
+import type { ResolvedOneBot11Config } from './protocol.js';
+export { OneBotV11Client as Onebot11Client } from '@imhelper/onebot-v11';
+export type Onebot11ApiCall = (action: string, params?: Record<string, unknown>) => Promise<OneBotV11Response>;
+type Onebot11ClientEvents = ImHelperEventMap<number, ImHelperOneBot11Event, EventMap<number>>;
+export type Onebot11ClientEventMap = ClientEventPayloads<Onebot11ClientEvents>;
+export declare function createOnebot11EndpointClient(config: ResolvedOneBot11Config, request: Onebot11ApiCall): OneBotV11Client;
+export declare function callOnebot11Client<T = unknown>(client: OneBotV11Client, action: string, params?: Record<string, unknown>): Promise<T | undefined>;
+export declare function forwardOnebot11ClientEvents(client: OneBotV11Client, receive: (name: string, payload: unknown) => void): () => void;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly onebot11: {
+            readonly client: OneBotV11Client;
+            readonly events: Onebot11ClientEventMap;
+        };
+    }
+}
+export declare const onebot11Client: import("@zhin.js/adapter").EndpointClientToken<OneBotV11Client, ClientEventPayloads<Onebot11ClientEvents>>;

package/lib/client.js

@@ -0,0 +1,30 @@
+import { OneBotV11Client, } from '@imhelper/onebot-v11';
+import { EventFactory } from 'imhelper';
+import { defineEndpointClient, forwardEndpointClientEvents, } from 'zhin.js/adapter';
+export { OneBotV11Client as Onebot11Client } from '@imhelper/onebot-v11';
+export function createOnebot11EndpointClient(config, request) {
+    return new OneBotV11Client({
+        baseUrl: config.connection === 'ws'
+            ? config.url.replace(/^ws(s?):/, 'http$1:')
+            : 'http://localhost',
+        selfId: config.id,
+        accessToken: config.access_token,
+        receiveMode: 'manual',
+        call: request,
+    });
+}
+export async function callOnebot11Client(client, action, params) {
+    const response = await client.call(action, params);
+    if (response.status !== 'ok') {
+        throw new Error(`OneBot 11 API ${action}: retcode=${response.retcode}${response.message ? ` ${response.message}` : ''}`);
+    }
+    return response.data;
+}
+const onebot11ClientEventNames = Object.freeze([
+    ...EventFactory.getSupportedEventTypes(),
+    'event',
+]);
+export function forwardOnebot11ClientEvents(client, receive) {
+    return forwardEndpointClientEvents(client, onebot11ClientEventNames, receive);
+}
+export const onebot11Client = defineEndpointClient('onebot11');

package/lib/index.d.ts

@@ -4,4 +4,7 @@ export { OneBot11WssEndpoint, type OneBot11WssEndpointOptions, } from './wss-end
 export type { OneBot11WsSocket, OneBot11WsCreateOptions } from './ws-types.js';
 export { callOneBot11WsAction, decodeWsPayload, handleOneBot11WsMessage, rejectAllPending, startOneBot11Heartbeat, } from './ws-transport.js';
 export { verifyOneBotAccessToken } from './wss-auth.js';
-export { getOnebot11AgentDeps, registerOnebot11AgentEndpoint, setOnebot11AgentDeps, type Onebot11AgentDeps, type Onebot11AgentEndpoint, } from './onebot11-agent-deps.js';
+export { Onebot11Client, onebot11Client, type Onebot11ClientEventMap, } from './client.js';
+export type { OneBotV11ActionUrlResolver, OneBotV11AdapterConfig as ImHelperOneBotV11AdapterConfig, OneBotV11Call, OneBotV11ClientConfig, OneBotV11Event as ImHelperOneBotV11Event, OneBotV11Response, } from '@imhelper/onebot-v11';
+export { ProtocolError } from '@imhelper/onebot-v11';
+export type { ProtocolErrorKind, ProtocolErrorOptions } from 'imhelper';

package/lib/index.js

@@ -3,4 +3,5 @@ export { OneBot11WsEndpoint, } from './ws-endpoint.js';
 export { OneBot11WssEndpoint, } from './wss-endpoint.js';
 export { callOneBot11WsAction, decodeWsPayload, handleOneBot11WsMessage, rejectAllPending, startOneBot11Heartbeat, } from './ws-transport.js';
 export { verifyOneBotAccessToken } from './wss-auth.js';
-export { getOnebot11AgentDeps, registerOnebot11AgentEndpoint, setOnebot11AgentDeps, } from './onebot11-agent-deps.js';
+export { Onebot11Client, onebot11Client, } from './client.js';
+export { ProtocolError } from '@imhelper/onebot-v11';

package/lib/onebot11-endpoint-commands.d.ts

@@ -1 +1 @@
-export declare const onebot11EndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;
+export declare const onebot11EndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/protocol.d.ts

@@ -82,9 +82,10 @@ export interface OneBot11ActionRequest {
     echo?: string;
 }
 export interface OneBot11ActionResponse {
-    status: string;
+    status: 'ok' | 'failed';
     retcode: number;
     data?: unknown;
+    message?: string;
     echo?: string;
 }
 export interface OneBot11WireSegment {
@@ -104,7 +105,7 @@ export declare function getChannelId(ev: OneBot11Event): string;
  * OneBot 11 无 guild/temp 容器概念，不填 parent。
  */
 export declare function onebot11InboundConversation(endpointKey: string, ev: OneBot11Event): ConversationRef;
-/** Build inbound text for MessageGateway.receive */
+/** Build inbound text for OutboundMessageService.receive */
 export declare function formatInboundContent(ev: OneBot11Event): string;
 export declare function senderDisplayName(ev: OneBot11Event): string;
 /**

package/lib/protocol.js

@@ -83,7 +83,7 @@ export function onebot11InboundConversation(endpointKey, ev) {
         id: getChannelId(ev),
     };
 }
-/** Build inbound text for MessageGateway.receive */
+/** Build inbound text for OutboundMessageService.receive */
 export function formatInboundContent(ev) {
     if (Array.isArray(ev.message)) {
         return ev.message

package/lib/side-event-dispatch.d.ts

@@ -1,7 +1,7 @@
-import type { SideEventGateway } from '@zhin.js/core/runtime';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
 import { type getAdapterLogger } from '@zhin.js/logger';
 import type { OneBot11Event } from './protocol.js';
 export interface OneBot11SideEventCaller {
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
 }
-export declare function receiveOneBot11SideEvent(sideEvents: SideEventGateway | undefined, endpointKey: string, caller: OneBot11SideEventCaller, raw: OneBot11Event, logger: ReturnType<typeof getAdapterLogger>): void;
+export declare function receiveOneBot11SideEvent(emit: EndpointEventEmitter, endpointKey: string, caller: OneBot11SideEventCaller, raw: OneBot11Event, logger: ReturnType<typeof getAdapterLogger>): void;

package/lib/side-event-dispatch.js

@@ -1,14 +1,14 @@
 import { receiveOneBotLikeSideEvent } from '@zhin.js/core';
 import { formatCompact } from '@zhin.js/logger';
-export function receiveOneBot11SideEvent(sideEvents, endpointKey, caller, raw, logger) {
-    if (!sideEvents)
+export function receiveOneBot11SideEvent(emit, endpointKey, caller, raw, logger) {
+    if (!emit)
         return;
     const record = raw;
     const postType = String(record.post_type ?? '');
     const requestType = String(record.request_type ?? '');
     const isRequest = postType === 'request' || postType.startsWith('request.');
     const isFriend = requestType === 'friend' || postType.includes('friend');
-    void receiveOneBotLikeSideEvent(sideEvents, {
+    void receiveOneBotLikeSideEvent(emit, {
         adapter: 'onebot11',
         endpointKey,
         platform: 'onebot',

package/lib/ws-endpoint.d.ts

@@ -1,30 +1,22 @@
-import { type EndpointControl, type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
-import { type OneBot11Event, type OneBot11WsConfig } from './protocol.js';
+import { type OneBot11WsConfig } from './protocol.js';
 import { type OneBot11WsCreateOptions, type OneBot11WsSocket } from './ws-types.js';
+import { type Onebot11Client } from './client.js';
 export interface OneBot11WsEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly config: OneBot11WsConfig;
     readonly createWebSocket?: (url: string, options: OneBot11WsCreateOptions) => OneBot11WsSocket;
 }
-export declare class OneBot11WsEndpoint implements EndpointInstance {
+export declare class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
     #private;
+    readonly client: Onebot11Client;
     readonly management: EndpointManagement;
     readonly control: EndpointControl;
     readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: OneBot11WsEndpointOptions);
     start(): Promise<void>;
-    open(): void;
-    close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
-    /** Public API for agent tools / callers. */
-    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
-    setTitle(groupId: number, userId: number, title: string, duration?: number): Promise<boolean>;
-    /** Test / internal: admit a parsed event when the endpoint is open. */
-    admit(ev: OneBot11Event): void;
 }

package/lib/ws-endpoint.js

@@ -2,29 +2,37 @@
  * OneBot11 WS client endpoint — outbound connect to OneBot implementation.
  */
 import WebSocket from 'ws';
-import { createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
+import { ClientEndpoint, createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createOneBot11EndpointManagement } from './endpoint-management.js';
-import { registerOnebot11AgentEndpoint } from './onebot11-agent-deps.js';
 import { buildSendAction, buildWsConnectOptions, formatInboundContent, formatInboundMetadata, formatOutboundSegments, isMessageEvent, onebot11InboundConversation, senderDisplayName, senderUserId, } from './protocol.js';
 import { receiveOneBot11SideEvent } from './side-event-dispatch.js';
 import { createOneBot11ContentPort } from './content-port.js';
 import { callOneBot11WsAction, handleOneBot11WsMessage, rejectAllPending, } from './ws-transport.js';
-export class OneBot11WsEndpoint {
+import { callOnebot11Client, createOnebot11EndpointClient, forwardOnebot11ClientEvents } from './client.js';
+export class OneBot11WsEndpoint extends ClientEndpoint {
+    client;
     #logger;
     #options;
-    management = createOneBot11EndpointManagement(this);
+    management;
     control = createRecallEndpointControl((id) => this.recallMessage(id));
-    content = createOneBot11ContentPort((action, params) => this.callApi(action, params));
+    content;
     #lifecycle;
     #ws;
     #requestId = { value: 0 };
     #pending = new Map();
-    #open = false;
-    #unregisterAgent;
     constructor(options) {
+        super();
         this.#logger = getAdapterLogger('onebot11', options.config.id);
         this.#options = options;
+        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 { config } = options;
         this.#lifecycle = createEndpointLifecycle({
             name: config.id,
@@ -41,13 +49,11 @@ export class OneBot11WsEndpoint {
     async start() {
         if (this.#lifecycle.started)
             return;
-        // agent 注册/反注册是适配器专有依赖，留在适配器侧（见 endpoint-lifecycle 迁移指引）
-        this.#unregisterAgent = registerOnebot11AgentEndpoint(this.#options.config.id, this);
         try {
             await this.#lifecycle.start((handle) => this.#connect(handle));
         }
         catch (err) {
-            // start 失败必须清理现场（状态复位由基座保证），避免 agent 注册泄漏
+            // start 失败必须清理现场（状态复位由基座保证）
             if (this.#ws) {
                 try {
                     this.#ws.close();
@@ -57,30 +63,20 @@ export class OneBot11WsEndpoint {
                 }
                 this.#ws = undefined;
             }
-            this.#unregisterAgent?.();
-            this.#unregisterAgent = undefined;
             throw err;
         }
     }
-    open() {
-        this.#open = true;
-    }
-    close() {
-        this.#open = false;
-    }
     async stop() {
-        this.#open = false;
+        this.close();
         // 基座负责：清重连/心跳定时器、强关 ws、唤醒 stop-during-connect 竞态
         await this.#lifecycle.stop();
-        this.#unregisterAgent?.();
-        this.#unregisterAgent = undefined;
         rejectAllPending(this.#pending);
         this.#ws = undefined;
     }
     async send({ conversation, payload }) {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(conversation, message);
-        const data = await this.callApi(action, params);
+        const data = await callOnebot11Client(this.client, action, params);
         const messageId = data?.message_id != null ? String(data.message_id) : '';
         this.#logger.debug(formatCompact({
             op: 'onebot11_send',
@@ -93,33 +89,20 @@ export class OneBot11WsEndpoint {
     async recallMessage(messageId) {
         if (!messageId)
             return;
-        await this.callApi('delete_msg', { message_id: Number(messageId) });
+        await callOnebot11Client(this.client, 'delete_msg', { message_id: Number(messageId) });
     }
-    /** Public API for agent tools / callers. */
-    callApi(action, params = {}) {
+    #callApi(action, params = {}) {
         return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);
     }
-    async setTitle(groupId, userId, title, duration = -1) {
-        await this.callApi('set_group_special_title', {
-            group_id: groupId,
-            user_id: userId,
-            special_title: title,
-            duration,
-        });
-        return true;
-    }
-    /** Test / internal: admit a parsed event when the endpoint is open. */
-    admit(ev) {
-        if (!this.#open)
-            return;
+    #admitRaw(ev) {
         if (!isMessageEvent(ev)) {
-            receiveOneBot11SideEvent(this.#options.sideEvents, this.#options.config.id, this, ev, this.#logger);
+            receiveOneBot11SideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, { callApi: (action, params) => callOnebot11Client(this.client, action, params) }, ev, this.#logger);
             return;
         }
         const conversation = onebot11InboundConversation(String(this.#options.id), ev);
         const content = formatInboundContent(ev);
         const inbound = formatInboundMetadata(ev, this.#options.config.id);
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
             conversation,
             message: { conversation, id: String(ev.message_id) },
             content,
@@ -140,6 +123,12 @@ export class OneBot11WsEndpoint {
             }));
         });
     }
+    #warnPlatformEvent(error) {
+        this.#logger.warn(formatCompact({
+            op: 'onebot11_platform_event_failed',
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
     async #connect(handle) {
         const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
         const create = this.#options.createWebSocket
@@ -179,7 +168,7 @@ export class OneBot11WsEndpoint {
                 handleOneBot11WsMessage(data, {
                     endpointId: this.#options.config.id,
                     pending: this.#pending,
-                    admit: (ev) => this.admit(ev),
+                    ingest: (ev) => this.client.ingest(ev),
                 });
             });
             ws.on('close', (code, reason) => {

package/lib/ws-transport.d.ts

@@ -1,13 +1,13 @@
-import { type OneBot11Event } from './protocol.js';
+import { type OneBot11ActionResponse, type OneBot11Event } from './protocol.js';
 import { type OneBot11PendingAction, type OneBot11WsSocket } from './ws-types.js';
 export declare function decodeWsPayload(data: unknown): string;
 export declare function handleOneBot11WsMessage(data: unknown, options: {
     readonly endpointId: string;
     readonly pending: Map<string, OneBot11PendingAction>;
-    readonly admit: (ev: OneBot11Event) => void;
+    readonly ingest: (ev: OneBot11Event) => void;
 }): void;
 export declare function callOneBot11WsAction(ws: OneBot11WsSocket | undefined, pending: Map<string, OneBot11PendingAction>, requestId: {
     value: number;
-}, action: string, params: Record<string, unknown>): Promise<unknown>;
+}, action: string, params: Record<string, unknown>): Promise<OneBot11ActionResponse>;
 export declare function startOneBot11Heartbeat(ws: OneBot11WsSocket | undefined, intervalMs: number, existingTimer?: NodeJS.Timeout): NodeJS.Timeout;
 export declare function rejectAllPending(pending: Map<string, OneBot11PendingAction>, message?: string): void;

package/lib/ws-transport.js

@@ -21,14 +21,11 @@ export function handleOneBot11WsMessage(data, options) {
             if (pending) {
                 options.pending.delete(resp.echo);
                 clearTimeout(pending.timeout);
-                if (resp.status === 'ok')
-                    pending.resolve(resp.data);
-                else
-                    pending.reject(new Error(`OneBot11 retcode=${resp.retcode}`));
+                pending.resolve(resp);
             }
             return;
         }
-        options.admit(msg);
+        options.ingest(msg);
     }
     catch (error) {
         logger.warn(formatCompact({

package/lib/ws-types.d.ts

@@ -11,7 +11,8 @@ export interface OneBot11WsCreateOptions {
 }
 export declare const WS_OPEN = 1;
 export interface OneBot11PendingAction {
-    resolve: (value: unknown) => void;
+    resolve: (value: OneBot11ActionResponse) => void;
     reject: (err: Error) => void;
     timeout: NodeJS.Timeout;
 }
+import type { OneBot11ActionResponse } from './protocol.js';

package/lib/wss-endpoint.d.ts

@@ -1,28 +1,25 @@
-import { type EndpointControl, type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+/**
+ * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
+ */
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
-import { type OneBot11Event, type OneBot11WssConfig } from './protocol.js';
+import { type OneBot11WssConfig } from './protocol.js';
+import { type Onebot11Client } from './client.js';
 export interface OneBot11WssEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: OneBot11WssConfig;
 }
-export declare class OneBot11WssEndpoint implements EndpointInstance {
+export declare class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
     #private;
+    readonly client: Onebot11Client;
     readonly management: EndpointManagement;
     readonly control: EndpointControl;
     readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: OneBot11WssEndpointOptions);
     start(): Promise<void>;
-    open(): void;
-    close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
-    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
-    setTitle(groupId: number, userId: number, title: string, duration?: number): Promise<boolean>;
-    admit(ev: OneBot11Event): void;
 }