@zhin.js/adapter-onebot11 1.1.3 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @zhin.js/adapter-onebot11
 
+## 1.1.5
+
+### Patch Changes
+
+- b9b3953: Fix adapter connection races, transport health reporting, candidate rollback and delivery acknowledgement boundaries. Separate generation admission from locally observed connectivity, reject unconfirmed message receipts, and mark uncertain delivery results without recommending automatic replay.
+
+  Class and compact endpoints should expose a `transportState` getter to report physical connection or local listener health. Unobserved endpoints now report an unknown transport and remain offline in diagnostics. Platform stability tiers remain unchanged until real account acceptance evidence is available.
+
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+  - @zhin.js/adapter@1.1.16
+  - @zhin.js/im-contract@1.1.3
+  - @zhin.js/core@1.1.40
+  - @zhin.js/host-http@1.1.3
+  - @zhin.js/tool@1.1.3
+  - @zhin.js/skill@1.1.3
+  - @zhin.js/agent-feature@1.1.3
+
+## 1.1.4
+
+### Patch Changes
+
+- Updated dependencies [43eda99]
+- Updated dependencies [0de4836]
+  - @zhin.js/core@1.1.39
+  - @zhin.js/permission@1.1.3
+  - @zhin.js/adapter@1.1.15
+
 ## 1.1.3
 
 ### Patch Changes

package/README.md

@@ -103,3 +103,7 @@ plugins:
 ## 许可证
 
 MIT License
+
+### 高阶消息支持边界
+
+OneBot11 标准支持链接分享：canonical share 的 url/title/description/image 分别映射标准 url/title/content/image，保留标题与描述。具体桥是否实现需实机确认；NapCat 的 share 发送限制不能以标准支持推断通过。标准没有 Markdown 与 keyboard 段，直接出站明确 `unsupported_operation / not_sent`；文字交互降级不能算原生按钮支持。参考：[OneBot11 消息段规范](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md)。

package/lib/protocol.js

@@ -3,7 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://github.com/botuniverse/onebot-11
  */
-import { isMediaRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('onebot11');
 function normalizeConnection(connection) {
@@ -224,6 +224,20 @@ function oneBotMediaSegment(type, data) {
 function canonicalToOneBotSegment(segment) {
     const data = segment.data ?? {};
     switch (segment.type) {
+        case 'markdown':
+        case 'keyboard':
+            throw new EndpointDeliveryError('unsupported_operation', `OneBot11 standard has no ${segment.type} message segment`, 'not_sent');
+        case 'share': {
+            if (['audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined)) {
+                throw new EndpointDeliveryError('unsupported_operation', 'onebot11 rich share metadata is not implemented', 'not_sent');
+            }
+            if (typeof data.url !== 'string' || !/^https?:\/\//.test(data.url) || typeof data.title !== 'string' || !data.title) {
+                throw new EndpointDeliveryError('unsupported_operation', 'Invalid OneBot11 share URL or title', 'not_sent');
+            }
+            return { type: 'share', data: { url: data.url, title: data.title,
+                    ...(typeof (data.description ?? data.content) === 'string' ? { content: data.description ?? data.content } : {}),
+                    ...(typeof data.image === 'string' ? { image: data.image } : {}) } };
+        }
         case 'mention': {
             const target = data.target ?? data.qq ?? data.id;
             if (target == null)

package/lib/ws-endpoint.d.ts

@@ -1,4 +1,4 @@
-import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
 import { type OneBot11WsConfig } from './protocol.js';
 import { type OneBot11WsCreateOptions, type OneBot11WsSocket } from './ws-types.js';
@@ -15,6 +15,7 @@ export declare class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
     readonly control: EndpointControl;
     readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: OneBot11WsEndpointOptions);
+    get transportState(): EndpointTransportState;
     start(): Promise<void>;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;

package/lib/ws-endpoint.js

@@ -1,3 +1,4 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * OneBot11 WS client endpoint — outbound connect to OneBot implementation.
  */
@@ -43,9 +44,12 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
                 maxIntervalMs: config.reconnect_interval,
                 jitterMs: 0,
             },
-            heartbeat: { intervalMs: config.heartbeat_interval },
+            heartbeat: { intervalMs: config.heartbeat_interval, watchdogMisses: 2 },
         });
     }
+    get transportState() {
+        return this.#lifecycle.state;
+    }
     async start() {
         if (this.#lifecycle.started)
             return;
@@ -77,7 +81,11 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(conversation, message);
         const data = await callOnebot11Client(this.client, action, params);
-        const messageId = data?.message_id != null ? String(data.message_id) : '';
+        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');
+        }
+        const messageId = String(rawId);
         this.#logger.debug(formatCompact({
             op: 'onebot11_send',
             endpoint: this.#options.config.id,
@@ -92,7 +100,7 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
         await callOnebot11Client(this.client, 'delete_msg', { message_id: Number(messageId) });
     }
     #callApi(action, params = {}) {
-        return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);
+        return callOneBot11WsAction(this.#lifecycle.state === 'open' ? this.#ws : undefined, this.#pending, this.#requestId, action, params);
     }
     #admitRaw(ev) {
         if (!isMessageEvent(ev)) {
@@ -138,6 +146,9 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
             const ws = create(url, { headers });
             this.#ws = ws;
             handle.onForceClose(() => {
+                if (this.#ws === ws) {
+                    rejectAllPending(this.#pending);
+                }
                 try {
                     ws.close();
                 }
@@ -146,7 +157,7 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
                 }
             });
             ws.on('open', () => {
-                if (settled)
+                if (settled || this.#ws !== ws || !this.#lifecycle.started)
                     return;
                 settled = true;
                 if (!this.#options.config.access_token) {
@@ -164,7 +175,14 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
                 this.#lifecycle.startHeartbeat(() => this.#ws?.ping?.());
                 resolve();
             });
+            ws.on('pong', () => {
+                if (this.#ws === ws)
+                    this.#lifecycle.notifyHeartbeatAck();
+            });
             ws.on('message', (data) => {
+                if (this.#ws !== ws || ws.readyState !== 1 || !this.#lifecycle.started)
+                    return;
+                this.#lifecycle.notifyHeartbeatAck();
                 handleOneBot11WsMessage(data, {
                     endpointId: this.#options.config.id,
                     pending: this.#pending,
@@ -172,6 +190,10 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
                 });
             });
             ws.on('close', (code, reason) => {
+                if (this.#ws !== ws)
+                    return;
+                this.#ws = undefined;
+                rejectAllPending(this.#pending);
                 const reasonStr = typeof reason === 'string'
                     ? reason
                     : Buffer.isBuffer(reason)
@@ -192,6 +214,8 @@ export class OneBot11WsEndpoint extends ClientEndpoint {
                 handle.notifyClosed(`OneBot11 WS 关闭: ${codeNum} ${reasonStr || 'closed'}${codeHint}`);
             });
             ws.on('error', (err) => {
+                if (this.#ws !== ws)
+                    return;
                 const error = err instanceof Error ? err : new Error(String(err));
                 this.#logger.warn(formatCompact({
                     op: 'ws_error',

package/lib/ws-transport.js

@@ -1,3 +1,4 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { clearTimeout, setTimeout } from 'node:timers';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { WS_OPEN, } from './ws-types.js';
@@ -37,23 +38,30 @@ export function handleOneBot11WsMessage(data, options) {
 }
 export function callOneBot11WsAction(ws, pending, requestId, action, params) {
     if (!ws || ws.readyState !== WS_OPEN) {
-        return Promise.reject(new Error('WebSocket 未连接'));
+        return Promise.reject(new EndpointDeliveryError('endpoint_disconnected', 'WebSocket 未连接', 'not_sent'));
     }
     const echo = `ob11_${++requestId.value}`;
     const req = { action, params, echo };
     return new Promise((resolve, reject) => {
         const timeout = setTimeout(() => {
             pending.delete(echo);
-            reject(new Error(`OneBot11 动作超时: ${action}`));
+            reject(new EndpointDeliveryError('endpoint_timeout', `OneBot11 动作超时: ${action}`, 'unknown'));
         }, 30_000);
         pending.set(echo, { resolve, reject, timeout });
-        ws.send(JSON.stringify(req));
+        try {
+            ws.send(JSON.stringify(req));
+        }
+        catch (error) {
+            pending.delete(echo);
+            clearTimeout(timeout);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        }
     });
 }
 export function rejectAllPending(pending, message = '连接已关闭') {
     for (const [, entry] of pending) {
         clearTimeout(entry.timeout);
-        entry.reject(new Error(message));
+        entry.reject(new EndpointDeliveryError('endpoint_disconnected', message, 'unknown'));
     }
     pending.clear();
 }

package/lib/ws-types.d.ts

@@ -4,7 +4,7 @@ export interface OneBot11WsSocket {
     send(data: string): void;
     close(code?: number, reason?: string): void;
     ping?(): void;
-    on(event: 'open' | 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+    on(event: 'open' | 'message' | 'close' | 'error' | 'pong', listener: (...args: unknown[]) => void): void;
 }
 export interface OneBot11WsCreateOptions {
     readonly headers?: Record<string, string>;

package/lib/wss-endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
-import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { ClientEndpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type OneBot11WssConfig } from './protocol.js';
@@ -18,6 +18,7 @@ export declare class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client>
     readonly control: EndpointControl;
     readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: OneBot11WssEndpointOptions);
+    get transportState(): EndpointTransportState;
     start(): Promise<void>;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;

package/lib/wss-endpoint.js

@@ -1,3 +1,4 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
@@ -24,6 +25,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
     #requestId = { value: 0 };
     #pending = new Map();
     #started = false;
+    #stopped = false;
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('onebot11', options.config.id);
@@ -31,6 +33,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
         this.#connectionLifecycle = createEndpointLifecycle({
             name: `${options.config.id}:inbound`,
             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);
@@ -41,9 +44,21 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
                 this.#admitRaw(payload);
         }, (_name, error) => this.#warnPlatformEvent(error));
     }
+    get transportState() {
+        if (this.#stopped)
+            return 'stopped';
+        if (!this.#started)
+            return 'idle';
+        if (this.#connectionLifecycle.state === 'closed')
+            return 'closed';
+        if (this.#ws?.readyState === 1)
+            return 'open';
+        return this.#connectionLifecycle.state === 'connecting' ? 'connecting' : 'idle';
+    }
     async start() {
         if (this.#started)
             return;
+        this.#stopped = false;
         if (!this.#options.config.access_token) {
             // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
             this.#logger.warn(formatCompact({
@@ -74,6 +89,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
         }));
     }
     async stop() {
+        this.#stopped = true;
         this.close();
         this.#wsRelease?.();
         this.#wsRelease = undefined;
@@ -87,7 +103,11 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(conversation, message);
         const data = await callOnebot11Client(this.client, action, params);
-        return data?.message_id != null ? String(data.message_id) : '';
+        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) {
         if (!messageId)
@@ -95,7 +115,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
         await callOnebot11Client(this.client, 'delete_msg', { message_id: Number(messageId) });
     }
     #callApi(action, params = {}) {
-        return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);
+        return callOneBot11WsAction(this.#connectionLifecycle.state === 'closed' ? undefined : this.#ws, this.#pending, this.#requestId, action, params);
     }
     #admitRaw(ev) {
         if (!isMessageEvent(ev)) {
@@ -132,6 +152,10 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
         }));
     }
     async #acceptConnection(connection) {
+        if (!this.#started || this.#stopped) {
+            connection.socket.close();
+            return;
+        }
         if (!verifyOneBotAccessToken(this.#options.config.access_token, connection.request)) {
             connection.socket.close(4003, 'Unauthorized');
             return;
@@ -142,6 +166,9 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
         await this.#connectionLifecycle.start(async (lifecycleHandle) => {
             this.#ws = socket;
             lifecycleHandle.onForceClose(() => {
+                if (this.#ws === socket) {
+                    rejectAllPending(this.#pending);
+                }
                 try {
                     socket.close();
                 }
@@ -159,8 +186,12 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
                     /* ignore */
                 }
             }, this.#options.config.heartbeat_interval);
+            socket.on('pong', () => {
+                if (this.#ws === socket)
+                    this.#connectionLifecycle.notifyHeartbeatAck();
+            });
             socket.on('message', (data) => {
-                if (this.#ws !== socket)
+                if (this.#ws !== socket || this.#connectionLifecycle.state === 'closed')
                     return;
                 this.#connectionLifecycle.notifyHeartbeatAck();
                 handleOneBot11WsMessage(data, {
@@ -169,7 +200,14 @@ export class OneBot11WssEndpoint extends ClientEndpoint {
                     ingest: (ev) => this.client.ingest(ev),
                 });
             });
+            socket.on('error', (error) => {
+                if (this.#ws !== socket)
+                    return;
+                this.#logger.warn(formatCompact({ op: 'ws_error', error: String(error) }));
+            });
             socket.on('close', () => {
+                if (this.#ws !== socket)
+                    return;
                 if (this.#ws === socket) {
                     this.#ws = undefined;
                     rejectAllPending(this.#pending);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot11",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Zhin.js OneBot 11 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -45,16 +45,16 @@
     "@imhelper/onebot-v11": "1.0.7",
     "imhelper": "1.0.7",
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.15",
-    "@zhin.js/agent-feature": "1.1.2",
-    "@zhin.js/core": "1.1.38",
+    "@zhin.js/adapter": "1.1.16",
+    "@zhin.js/agent-feature": "1.1.3",
+    "@zhin.js/core": "1.1.40",
     "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/host-http": "1.1.2",
-    "@zhin.js/im-contract": "1.1.2",
+    "@zhin.js/host-http": "1.1.3",
+    "@zhin.js/im-contract": "1.1.3",
     "@zhin.js/logger": "1.1.1",
-    "@zhin.js/permission": "1.1.2",
-    "@zhin.js/skill": "1.1.2",
-    "@zhin.js/tool": "1.1.2"
+    "@zhin.js/permission": "1.1.3",
+    "@zhin.js/skill": "1.1.3",
+    "@zhin.js/tool": "1.1.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -62,15 +62,15 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.2",
-    "zhin.js": "1.1.3"
+    "@zhin.js/host-http": "1.1.3",
+    "zhin.js": "1.1.5"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.15",
-    "@zhin.js/command": "^1.1.2",
-    "@zhin.js/core": "^1.1.38",
-    "zhin.js": "^1.1.3"
+    "@zhin.js/adapter": "^1.1.16",
+    "@zhin.js/command": "^1.1.4",
+    "@zhin.js/core": "^1.1.40",
+    "zhin.js": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {

package/src/protocol.ts

@@ -3,7 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://github.com/botuniverse/onebot-11
  */
-import { isMediaRef, type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef, type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('onebot11');
@@ -340,6 +340,21 @@ function oneBotMediaSegment(
 function canonicalToOneBotSegment(segment: OneBot11WireSegment): OneBot11Segment | null {
   const data = segment.data ?? {};
   switch (segment.type) {
+    case 'markdown':
+    case 'keyboard':
+      throw new EndpointDeliveryError('unsupported_operation', `OneBot11 standard has no ${segment.type} message segment`, 'not_sent');
+    case 'share': {
+      if (['audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined)) {
+        throw new EndpointDeliveryError('unsupported_operation', 'onebot11 rich share metadata is not implemented', 'not_sent');
+      }
+      if (typeof data.url !== 'string' || !/^https?:\/\//.test(data.url) || typeof data.title !== 'string' || !data.title) {
+        throw new EndpointDeliveryError('unsupported_operation', 'Invalid OneBot11 share URL or title', 'not_sent');
+      }
+      return { type: 'share', data: { url: data.url, title: data.title,
+        ...(typeof (data.description ?? data.content) === 'string' ? { content: data.description ?? data.content } : {}),
+        ...(typeof data.image === 'string' ? { image: data.image } : {}) } };
+    }
+
     case 'mention': {
       const target = data.target ?? data.qq ?? data.id;
       if (target == null) return { type: segment.type, data };

package/src/ws-endpoint.ts

@@ -1,3 +1,4 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * OneBot11 WS client endpoint — outbound connect to OneBot implementation.
  */
@@ -11,6 +12,7 @@ import {
   type EndpointLifecycle,
   type EndpointManagement,
   type EndpointSendRequest,
+  type EndpointTransportState,
 } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -89,10 +91,14 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
         maxIntervalMs: config.reconnect_interval,
         jitterMs: 0,
       },
-      heartbeat: { intervalMs: config.heartbeat_interval },
+      heartbeat: { intervalMs: config.heartbeat_interval, watchdogMisses: 2 },
     });
   }
 
+  get transportState(): EndpointTransportState {
+    return this.#lifecycle.state;
+  }
+
   async start(): Promise<void> {
     if (this.#lifecycle.started) return;
     try {
@@ -123,7 +129,11 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(conversation, message);
     const data = await callOnebot11Client<{ message_id?: number | string }>(this.client, action, params);
-    const messageId = data?.message_id != null ? String(data.message_id) : '';
+    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');
+    }
+    const messageId = String(rawId);
     this.#logger.debug(formatCompact({
       op: 'onebot11_send',
       endpoint: this.#options.config.id,
@@ -142,7 +152,7 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
     action: string,
     params: Record<string, unknown> = {},
   ): ReturnType<typeof callOneBot11WsAction> {
-    return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);
+    return callOneBot11WsAction(this.#lifecycle.state === 'open' ? this.#ws : undefined, this.#pending, this.#requestId, action, params);
   }
 
   #admitRaw(ev: OneBot11Event): void {
@@ -199,6 +209,9 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
       const ws = create(url, { headers });
       this.#ws = ws;
       handle.onForceClose(() => {
+        if (this.#ws === ws) {
+          rejectAllPending(this.#pending);
+        }
         try {
           ws.close();
         } catch {
@@ -207,7 +220,7 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
       });
 
       ws.on('open', () => {
-        if (settled) return;
+        if (settled || this.#ws !== ws || !this.#lifecycle.started) return;
         settled = true;
         if (!this.#options.config.access_token) {
           this.#logger.warn(formatCompact({
@@ -225,7 +238,12 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
         resolve();
       });
 
+      ws.on('pong', () => {
+        if (this.#ws === ws) this.#lifecycle.notifyHeartbeatAck();
+      });
       ws.on('message', (data) => {
+        if (this.#ws !== ws || ws.readyState !== 1 || !this.#lifecycle.started) return;
+        this.#lifecycle.notifyHeartbeatAck();
         handleOneBot11WsMessage(data, {
           endpointId: this.#options.config.id,
           pending: this.#pending,
@@ -234,6 +252,9 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
       });
 
       ws.on('close', (code, reason) => {
+        if (this.#ws !== ws) return;
+        this.#ws = undefined;
+        rejectAllPending(this.#pending);
         const reasonStr = typeof reason === 'string'
           ? reason
           : Buffer.isBuffer(reason)
@@ -255,6 +276,7 @@ export class OneBot11WsEndpoint extends ClientEndpoint<Onebot11Client> {
       });
 
       ws.on('error', (err) => {
+        if (this.#ws !== ws) return;
         const error = err instanceof Error ? err : new Error(String(err));
         this.#logger.warn(formatCompact({
           op: 'ws_error',

package/src/ws-transport.ts

@@ -1,3 +1,4 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { clearTimeout, setTimeout } from 'node:timers';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import {
@@ -59,17 +60,23 @@ export function callOneBot11WsAction(
   params: Record<string, unknown>,
 ): Promise<OneBot11ActionResponse> {
   if (!ws || ws.readyState !== WS_OPEN) {
-    return Promise.reject(new Error('WebSocket 未连接'));
+    return Promise.reject(new EndpointDeliveryError('endpoint_disconnected', 'WebSocket 未连接', 'not_sent'));
   }
   const echo = `ob11_${++requestId.value}`;
   const req: OneBot11ActionRequest = { action, params, echo };
   return new Promise((resolve, reject) => {
     const timeout = setTimeout(() => {
       pending.delete(echo);
-      reject(new Error(`OneBot11 动作超时: ${action}`));
+      reject(new EndpointDeliveryError('endpoint_timeout', `OneBot11 动作超时: ${action}`, 'unknown'));
     }, 30_000);
     pending.set(echo, { resolve, reject, timeout });
-    ws.send(JSON.stringify(req));
+    try {
+      ws.send(JSON.stringify(req));
+    } catch (error) {
+      pending.delete(echo);
+      clearTimeout(timeout);
+      reject(error instanceof Error ? error : new Error(String(error)));
+    }
   });
 }
 
@@ -79,7 +86,7 @@ export function rejectAllPending(
 ): void {
   for (const [, entry] of pending) {
     clearTimeout(entry.timeout);
-    entry.reject(new Error(message));
+    entry.reject(new EndpointDeliveryError('endpoint_disconnected', message, 'unknown'));
   }
   pending.clear();
 }

package/src/ws-types.ts

@@ -4,7 +4,7 @@ export interface OneBot11WsSocket {
   send(data: string): void;
   close(code?: number, reason?: string): void;
   ping?(): void;
-  on(event: 'open' | 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+  on(event: 'open' | 'message' | 'close' | 'error' | 'pong', listener: (...args: unknown[]) => void): void;
 }
 
 export interface OneBot11WsCreateOptions {

package/src/wss-endpoint.ts

@@ -1,3 +1,4 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * OneBot11 reverse WSS endpoint — accepts inbound WebSocket from OneBot implementation.
  */
@@ -9,6 +10,7 @@ import {
   type EndpointControl,
   type EndpointManagement,
   type EndpointSendRequest,
+  type EndpointTransportState,
 } from 'zhin.js/adapter';
 import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
@@ -62,6 +64,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
   #requestId = { value: 0 };
   #pending = new Map<string, OneBot11PendingAction>();
   #started = false;
+  #stopped = false;
 
   constructor(options: OneBot11WssEndpointOptions) {
     super();
@@ -70,6 +73,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
     this.#connectionLifecycle = createEndpointLifecycle({
       name: `${options.config.id}:inbound`,
       reconnect: false,
+      heartbeat: { intervalMs: options.config.heartbeat_interval, watchdogMisses: 2 },
     });
     this.client = createOnebot11EndpointClient(options.config, (action, params) => this.#callApi(action, params));
     const callApi = (action: string, params?: Record<string, unknown>) => callOnebot11Client(this.client, action, params);
@@ -84,8 +88,17 @@ export class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
     );
   }
 
+  get transportState(): EndpointTransportState {
+    if (this.#stopped) return 'stopped';
+    if (!this.#started) return 'idle';
+    if (this.#connectionLifecycle.state === 'closed') return 'closed';
+    if (this.#ws?.readyState === 1) return 'open';
+    return this.#connectionLifecycle.state === 'connecting' ? 'connecting' : 'idle';
+  }
+
   async start(): Promise<void> {
     if (this.#started) return;
+    this.#stopped = false;
     if (!this.#options.config.access_token) {
       // wss 模式未配 access_token 时任何连接都会被放行（verifyOneBotAccessToken 直接 return true）
       this.#logger.warn(formatCompact({
@@ -117,6 +130,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
   }
 
   async stop(): Promise<void> {
+    this.#stopped = true;
     this.close();
     this.#wsRelease?.();
     this.#wsRelease = undefined;
@@ -131,7 +145,11 @@ export class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(conversation, message);
     const data = await callOnebot11Client<{ message_id?: number | string }>(this.client, action, params);
-    return data?.message_id != null ? String(data.message_id) : '';
+    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: string): Promise<void> {
@@ -143,7 +161,7 @@ export class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
     action: string,
     params: Record<string, unknown> = {},
   ): ReturnType<typeof callOneBot11WsAction> {
-    return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);
+    return callOneBot11WsAction(this.#connectionLifecycle.state === 'closed' ? undefined : this.#ws, this.#pending, this.#requestId, action, params);
   }
 
   #admitRaw(ev: OneBot11Event): void {
@@ -189,6 +207,10 @@ export class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
   }
 
   async #acceptConnection(connection: WsConnection): Promise<void> {
+    if (!this.#started || this.#stopped) {
+      connection.socket.close();
+      return;
+    }
     if (!verifyOneBotAccessToken(this.#options.config.access_token, connection.request)) {
       connection.socket.close(4003, 'Unauthorized');
       return;
@@ -199,6 +221,9 @@ export class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
     await this.#connectionLifecycle.start(async (lifecycleHandle) => {
       this.#ws = socket;
       lifecycleHandle.onForceClose(() => {
+        if (this.#ws === socket) {
+          rejectAllPending(this.#pending);
+        }
         try {
           socket.close();
         } catch {
@@ -213,8 +238,11 @@ export class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
           /* ignore */
         }
       }, this.#options.config.heartbeat_interval);
+      socket.on('pong', () => {
+        if (this.#ws === socket) this.#connectionLifecycle.notifyHeartbeatAck();
+      });
       socket.on('message', (data) => {
-        if (this.#ws !== socket) return;
+        if (this.#ws !== socket || this.#connectionLifecycle.state === 'closed') return;
         this.#connectionLifecycle.notifyHeartbeatAck();
         handleOneBot11WsMessage(data, {
           endpointId: this.#options.config.id,
@@ -222,7 +250,12 @@ export class OneBot11WssEndpoint extends ClientEndpoint<Onebot11Client> {
           ingest: (ev) => this.client.ingest(ev as Parameters<Onebot11Client['ingest']>[0]),
         });
       });
+      socket.on('error', (error) => {
+        if (this.#ws !== socket) return;
+        this.#logger.warn(formatCompact({ op: 'ws_error', error: String(error) }));
+      });
       socket.on('close', () => {
+        if (this.#ws !== socket) return;
         if (this.#ws === socket) {
           this.#ws = undefined;
           rejectAllPending(this.#pending);