@zhin.js/adapter-napcat 1.1.3 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @zhin.js/adapter-napcat
 
+## 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

@@ -97,3 +97,7 @@ endpoint 配置，不会从环境变量推断 endpoint id。
 ## 许可证
 
 MIT License
+
+### 高阶消息支持边界
+
+NapCat 官方消息兼容表标明 share 仅接收，不支持发送；Markdown 仅可在双层合并转发内发送，不支持直接消息。Canonical `markdown`、`share`、`keyboard` 直接出站明确返回 `unsupported_operation / not_sent`，不会将占位段或原始协议猜测报告成功。当前未实现合并转发 Markdown，亦无原生按钮回调闭环。参考：[官方兼容表](https://napneko.github.io/develop/msg)。

package/lib/http-endpoint.d.ts

@@ -1,5 +1,4 @@
-import { Endpoint } from 'zhin.js/adapter';
-import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, 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 { callNapCatHttpAction, type NapCatEvent, type NapCatHttpConfig } from './protocol.js';
@@ -17,6 +16,7 @@ export declare class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
     readonly control: EndpointControl;
     readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: NapCatHttpEndpointOptions);
+    get transportState(): EndpointTransportState;
     start(): Promise<void>;
     open(): void;
     close(): void;

package/lib/http-endpoint.js

@@ -1,5 +1,5 @@
-import { Endpoint } from 'zhin.js/adapter';
-import { createRecallEndpointControl, } from 'zhin.js/adapter';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { Endpoint, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
@@ -21,15 +21,20 @@ export class NapCatHttpEndpoint extends Endpoint {
     #routeReleases = [];
     #open = false;
     #started = false;
+    #stopped = false;
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('napcat', options.config.id);
         this.#options = options;
         this.#callHttpAction = options.callHttpAction ?? callNapCatHttpAction;
     }
+    get transportState() {
+        return this.#stopped ? 'stopped' : this.#started ? 'open' : 'idle';
+    }
     async start() {
         if (this.#started)
             return;
+        this.#stopped = false;
         this.#started = true;
         this.#setupRoutes();
         this.#logger.info(formatCompact({
@@ -46,6 +51,7 @@ export class NapCatHttpEndpoint extends Endpoint {
         this.#open = false;
     }
     async stop() {
+        this.#stopped = true;
         this.#open = false;
         for (const release of this.#routeReleases.splice(0))
             release();
@@ -61,7 +67,11 @@ export class NapCatHttpEndpoint extends Endpoint {
             access_token: this.#options.config.access_token,
         }, action, params);
         const data = resp.data;
-        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: 'napcat_send',
             endpoint: this.#options.config.id,

package/lib/protocol.js

@@ -3,7 +3,7 @@
  * No legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-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('napcat');
 function normalizeConnection(connection) {
@@ -189,6 +189,10 @@ function oneBotMediaSegment(type, data) {
 function canonicalToOneBotSegment(segment) {
     const data = segment.data ?? {};
     switch (segment.type) {
+        case 'markdown':
+        case 'share':
+        case 'keyboard':
+            throw new EndpointDeliveryError('unsupported_operation', `NapCat direct ${segment.type} sending is not supported`, 'not_sent');
         case 'mention': {
             const target = data.target ?? data.qq ?? data.id;
             if (target == null)
@@ -295,15 +299,16 @@ export async function callNapCatHttpAction(options, action, params = {}) {
         headers.Authorization = `Bearer ${options.access_token}`;
     }
     const res = await fetch(url, {
+        signal: AbortSignal.timeout(30_000),
         method: 'POST',
         headers,
         body: JSON.stringify(params),
     });
     const text = await res.text();
     if (res.status === 401)
-        throw new Error(`NapCat HTTP auth failed: ${text}`);
+        throw new EndpointDeliveryError('platform_rejected', `NapCat HTTP auth failed: ${text}`, 'rejected');
     if (res.status !== 200)
-        throw new Error(`NapCat HTTP ${res.status}: ${text}`);
+        throw new EndpointDeliveryError(res.status === 429 || res.status === 403 ? 'platform_rejected' : 'delivery_unconfirmed', `NapCat HTTP ${res.status}: ${text}`, res.status === 429 || res.status === 403 ? 'rejected' : 'unknown');
     let data;
     try {
         data = JSON.parse(text);
@@ -312,7 +317,7 @@ export async function callNapCatHttpAction(options, action, params = {}) {
         throw new Error(`NapCat HTTP invalid response: ${text.slice(0, 200)}`);
     }
     if (data.status !== 'ok' && data.retcode !== 0) {
-        throw new Error(`NapCat HTTP action failed [${data.retcode}]: ${data.message || data.wording || 'unknown'}`);
+        throw new EndpointDeliveryError('platform_rejected', `NapCat HTTP action failed [${data.retcode}]: ${data.message || data.wording || 'unknown'}`, 'rejected');
     }
     return data;
 }

package/lib/ws-endpoint.d.ts

@@ -1,5 +1,4 @@
-import { Endpoint } from 'zhin.js/adapter';
-import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest, type EndpointTransportState } from 'zhin.js/adapter';
 import type { CapabilityId } from 'zhin.js';
 import { type NapCatEvent, type NapCatWsConfig } from './protocol.js';
 import { type NapCatWsCreateOptions, type NapCatWsSocket } from './ws-types.js';
@@ -16,6 +15,7 @@ export declare class NapCatWsEndpoint extends Endpoint<NapcatClient> {
     readonly control: EndpointControl;
     readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: NapCatWsEndpointOptions);
+    get transportState(): EndpointTransportState;
     start(): Promise<void>;
     open(): void;
     close(): void;

package/lib/ws-endpoint.js

@@ -1,9 +1,9 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * NapCat WS client endpoint — outbound connect to NapCat.
  */
 import WebSocket from 'ws';
-import { createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
+import { Endpoint, createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
@@ -31,6 +31,7 @@ export class NapCatWsEndpoint extends Endpoint {
         this.#options = options;
         this.#lifecycle = createEndpointLifecycle({
             name: options.config.id,
+            heartbeat: { intervalMs: options.config.heartbeat_interval, watchdogMisses: 2 },
             // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
             reconnect: {
                 initialIntervalMs: options.config.reconnect_interval,
@@ -40,6 +41,9 @@ export class NapCatWsEndpoint extends Endpoint {
             },
         });
     }
+    get transportState() {
+        return this.#lifecycle.state;
+    }
     async start() {
         if (this.#lifecycle.started)
             return;
@@ -70,7 +74,11 @@ export class NapCatWsEndpoint extends Endpoint {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
         const data = await this.client.callApi(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: 'napcat_send',
             endpoint: this.#options.config.id,
@@ -85,7 +93,7 @@ export class NapCatWsEndpoint extends Endpoint {
         await this.client.callApi('delete_msg', { message_id: Number(messageId) });
     }
     #callApi(action, params = {}) {
-        return callNapCatWsAction(this.#ws, this.#pending, this.#requestId, action, params);
+        return callNapCatWsAction(this.#lifecycle.state === 'open' ? this.#ws : undefined, this.#pending, this.#requestId, action, params);
     }
     /** Test / internal: admit a parsed event when the endpoint is open. */
     admit(ev) {
@@ -150,6 +158,9 @@ export class NapCatWsEndpoint extends Endpoint {
             const ws = create(url, { headers });
             this.#ws = ws;
             handle.onForceClose(() => {
+                if (this.#ws === ws) {
+                    rejectAllPending(this.#pending);
+                }
                 try {
                     ws.close();
                 }
@@ -158,7 +169,7 @@ export class NapCatWsEndpoint extends Endpoint {
                 }
             });
             ws.on('open', () => {
-                if (settled)
+                if (settled || this.#ws !== ws || !this.#lifecycle.started)
                     return;
                 settled = true;
                 if (!this.#options.config.access_token) {
@@ -186,7 +197,14 @@ export class NapCatWsEndpoint extends Endpoint {
                 }
                 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();
                 handleNapCatWsMessage(data, {
                     endpointId: this.#options.config.id,
                     pending: this.#pending,
@@ -194,6 +212,10 @@ export class NapCatWsEndpoint extends Endpoint {
                 });
             });
             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)
@@ -219,6 +241,8 @@ export class NapCatWsEndpoint extends Endpoint {
                 }
             });
             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 { clearInterval, clearTimeout, setInterval, setTimeout } from 'node:timers';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { WS_OPEN, } from './ws-types.js';
@@ -24,7 +25,7 @@ export function handleNapCatWsMessage(data, options) {
                 if (resp.status === 'ok')
                     pending.resolve(resp.data);
                 else {
-                    pending.reject(new Error(`API error [${resp.retcode}]: ${resp.message || resp.wording || 'unknown'}`));
+                    pending.reject(new EndpointDeliveryError('platform_rejected', `API error [${resp.retcode}]: ${resp.message || resp.wording || 'unknown'}`, 'rejected'));
                 }
             }
             return;
@@ -41,17 +42,24 @@ export function handleNapCatWsMessage(data, options) {
 }
 export function callNapCatWsAction(ws, pending, requestId, action, params) {
     if (!ws || ws.readyState !== WS_OPEN) {
-        return Promise.reject(new Error('WebSocket is not connected'));
+        return Promise.reject(new EndpointDeliveryError('endpoint_disconnected', 'WebSocket is not connected', 'not_sent'));
     }
     const echo = `req_${++requestId.value}`;
     const req = { action, params, echo };
     return new Promise((resolve, reject) => {
         const timeout = setTimeout(() => {
             pending.delete(echo);
-            reject(new Error(`API call timeout: ${action}`));
+            reject(new EndpointDeliveryError('endpoint_timeout', `API call timeout: ${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 startNapCatHeartbeat(ws, intervalMs, existingTimer) {
@@ -69,7 +77,7 @@ export function startNapCatHeartbeat(ws, intervalMs, existingTimer) {
 export function rejectAllPending(pending, message = 'Connection closed') {
     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 NapCatWsSocket {
     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 NapCatWsCreateOptions {
     readonly headers?: Record<string, string>;

package/lib/wss-endpoint.d.ts

@@ -1,8 +1,7 @@
-import { Endpoint } from 'zhin.js/adapter';
 /**
  * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
  */
-import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, 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 NapCatEvent, type NapCatWssConfig } from './protocol.js';
@@ -19,6 +18,7 @@ export declare class NapCatWssEndpoint extends Endpoint<NapcatClient> {
     readonly control: EndpointControl;
     readonly content: import("@zhin.js/adapter").EndpointContentPort;
     constructor(options: NapCatWssEndpointOptions);
+    get transportState(): EndpointTransportState;
     start(): Promise<void>;
     open(): void;
     close(): void;

package/lib/wss-endpoint.js

@@ -1,8 +1,8 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
  */
-import { createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { Endpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
@@ -28,6 +28,7 @@ export class NapCatWssEndpoint extends Endpoint {
     #pending = new Map();
     #open = false;
     #started = false;
+    #stopped = false;
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('napcat', options.config.id);
@@ -35,11 +36,24 @@ export class NapCatWssEndpoint extends Endpoint {
         this.#connectionLifecycle = createEndpointLifecycle({
             name: `${options.config.id}:inbound`,
             reconnect: false,
+            heartbeat: { intervalMs: options.config.heartbeat_interval, watchdogMisses: 2 },
         });
     }
+    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;
         this.#started = true;
         const handle = this.#options.http.ws(this.#options.config.path);
         this.#wsRelease = handle.onConnection((connection) => {
@@ -67,6 +81,7 @@ export class NapCatWssEndpoint extends Endpoint {
         this.#open = false;
     }
     async stop() {
+        this.#stopped = true;
         this.#open = false;
         this.#wsRelease?.();
         this.#wsRelease = undefined;
@@ -81,7 +96,11 @@ export class NapCatWssEndpoint extends Endpoint {
         const message = formatOutboundSegments(payload);
         const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
         const data = await this.client.callApi(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)
@@ -89,7 +108,7 @@ export class NapCatWssEndpoint extends Endpoint {
         await this.client.callApi('delete_msg', { message_id: Number(messageId) });
     }
     #callApi(action, params = {}) {
-        return callNapCatWsAction(this.#ws, this.#pending, this.#requestId, action, params);
+        return callNapCatWsAction(this.#connectionLifecycle.state === 'closed' ? undefined : this.#ws, this.#pending, this.#requestId, action, params);
     }
     admit(ev) {
         if (!this.#open)
@@ -144,15 +163,23 @@ export class NapCatWssEndpoint extends Endpoint {
         });
     }
     async #acceptConnection(connection) {
+        if (!this.#started || this.#stopped) {
+            connection.socket.close();
+            return;
+        }
         if (!verifyNapCatAccessToken(this.#options.config.access_token, connection.request)) {
             connection.socket.close(4003, 'Unauthorized');
             return;
         }
         const socket = connection.socket;
         await this.#connectionLifecycle.stop();
+        rejectAllPending(this.#pending, 'Connection replaced');
         await this.#connectionLifecycle.start(async (lifecycleHandle) => {
             this.#ws = socket;
             lifecycleHandle.onForceClose(() => {
+                if (this.#ws === socket) {
+                    rejectAllPending(this.#pending);
+                }
                 try {
                     socket.close();
                 }
@@ -168,7 +195,13 @@ export class NapCatWssEndpoint extends Endpoint {
                     /* ignore */
                 }
             }, this.#options.config.heartbeat_interval);
+            socket.on('pong', () => {
+                if (this.#ws === socket)
+                    this.#connectionLifecycle.notifyHeartbeatAck();
+            });
             socket.on('message', (data) => {
+                if (this.#ws !== socket || this.#connectionLifecycle.state === 'closed')
+                    return;
                 this.#connectionLifecycle.notifyHeartbeatAck();
                 handleNapCatWsMessage(data, {
                     endpointId: this.#options.config.id,
@@ -176,9 +209,16 @@ export class NapCatWssEndpoint extends Endpoint {
                     admit: (event) => this.admit(event),
                 });
             });
+            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)
-                    this.#ws = undefined;
+                if (this.#ws !== socket)
+                    return;
+                this.#ws = undefined;
+                rejectAllPending(this.#pending);
                 lifecycleHandle.notifyClosed(new Error('NapCat reverse WebSocket closed'));
             });
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-napcat",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Zhin.js NapCat adapter for Plugin Runtime (WebSocket client, OneBot11 + NapCat extensions)",
   "type": "module",
   "main": "./lib/index.js",
@@ -45,16 +45,16 @@
   },
   "dependencies": {
     "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/http-endpoint.ts

@@ -1,13 +1,15 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * NapCat HTTP endpoint — POST inbound events + HTTP API outbound.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import {
+  Endpoint,
   createRecallEndpointControl,
   type EndpointControl,
   type EndpointManagement,
   type EndpointSendRequest,
+  type EndpointTransportState,
 } from 'zhin.js/adapter';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
@@ -59,6 +61,7 @@ export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
   #routeReleases: HttpRouteRegistration[] = [];
   #open = false;
   #started = false;
+  #stopped = false;
 
   constructor(options: NapCatHttpEndpointOptions) {
     super();
@@ -67,8 +70,13 @@ export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
     this.#callHttpAction = options.callHttpAction ?? callNapCatHttpAction;
   }
 
+  get transportState(): EndpointTransportState {
+    return this.#stopped ? 'stopped' : this.#started ? 'open' : 'idle';
+  }
+
   async start(): Promise<void> {
     if (this.#started) return;
+    this.#stopped = false;
     this.#started = true;
     this.#setupRoutes();
     this.#logger.info(formatCompact({
@@ -88,6 +96,7 @@ export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
   }
 
   async stop(): Promise<void> {
+    this.#stopped = true;
     this.#open = false;
     for (const release of this.#routeReleases.splice(0)) release();
     this.#inboundDeduper.clear();
@@ -107,7 +116,11 @@ export class NapCatHttpEndpoint extends Endpoint<NapcatClient> {
       params,
     );
     const data = resp.data as { message_id?: number | string } | undefined;
-    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: 'napcat_send',
       endpoint: this.#options.config.id,

package/src/protocol.ts

@@ -3,7 +3,7 @@
  * No legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-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('napcat');
@@ -318,6 +318,11 @@ function oneBotMediaSegment(
 function canonicalToOneBotSegment(segment: NapCatWireSegment): MessageSegment | null {
   const data = segment.data ?? {};
   switch (segment.type) {
+    case 'markdown':
+    case 'share':
+    case 'keyboard':
+      throw new EndpointDeliveryError('unsupported_operation', `NapCat direct ${segment.type} sending is not supported`, 'not_sent');
+
     case 'mention': {
       const target = data.target ?? data.qq ?? data.id;
       if (target == null) return { type: segment.type, data };
@@ -443,13 +448,14 @@ export async function callNapCatHttpAction(
     headers.Authorization = `Bearer ${options.access_token}`;
   }
   const res = await fetch(url, {
+    signal: AbortSignal.timeout(30_000),
     method: 'POST',
     headers,
     body: JSON.stringify(params),
   });
   const text = await res.text();
-  if (res.status === 401) throw new Error(`NapCat HTTP auth failed: ${text}`);
-  if (res.status !== 200) throw new Error(`NapCat HTTP ${res.status}: ${text}`);
+  if (res.status === 401) throw new EndpointDeliveryError('platform_rejected', `NapCat HTTP auth failed: ${text}`, 'rejected');
+  if (res.status !== 200) throw new EndpointDeliveryError(res.status === 429 || res.status === 403 ? 'platform_rejected' : 'delivery_unconfirmed', `NapCat HTTP ${res.status}: ${text}`, res.status === 429 || res.status === 403 ? 'rejected' : 'unknown');
   let data: NapCatActionResponse;
   try {
     data = JSON.parse(text) as NapCatActionResponse;
@@ -457,8 +463,8 @@ export async function callNapCatHttpAction(
     throw new Error(`NapCat HTTP invalid response: ${text.slice(0, 200)}`);
   }
   if (data.status !== 'ok' && data.retcode !== 0) {
-    throw new Error(
-      `NapCat HTTP action failed [${data.retcode}]: ${data.message || data.wording || 'unknown'}`,
+    throw new EndpointDeliveryError(
+      'platform_rejected', `NapCat HTTP action failed [${data.retcode}]: ${data.message || data.wording || 'unknown'}`, 'rejected',
     );
   }
   return data;

package/src/ws-endpoint.ts

@@ -1,9 +1,10 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * NapCat WS client endpoint — outbound connect to NapCat.
  */
 import WebSocket from 'ws';
 import {
+  Endpoint,
   createRecallEndpointControl,
   createEndpointLifecycle,
   type EndpointConnectHandle,
@@ -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';
@@ -78,6 +80,7 @@ export class NapCatWsEndpoint extends Endpoint<NapcatClient> {
     this.#options = options;
     this.#lifecycle = createEndpointLifecycle({
       name: options.config.id,
+      heartbeat: { intervalMs: options.config.heartbeat_interval, watchdogMisses: 2 },
       // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
       reconnect: {
         initialIntervalMs: options.config.reconnect_interval,
@@ -88,6 +91,10 @@ export class NapCatWsEndpoint extends Endpoint<NapcatClient> {
     });
   }
 
+  get transportState(): EndpointTransportState {
+    return this.#lifecycle.state;
+  }
+
   async start(): Promise<void> {
     if (this.#lifecycle.started) return;
     await this.#lifecycle.start((handle) => this.#connect(handle));
@@ -120,7 +127,11 @@ export class NapCatWsEndpoint extends Endpoint<NapcatClient> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
     const data = await this.client.callApi(action, params) as { message_id?: number | string } | undefined;
-    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: 'napcat_send',
       endpoint: this.#options.config.id,
@@ -136,7 +147,7 @@ export class NapCatWsEndpoint extends Endpoint<NapcatClient> {
   }
 
   #callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
-    return callNapCatWsAction(this.#ws, this.#pending, this.#requestId, action, params);
+    return callNapCatWsAction(this.#lifecycle.state === 'open' ? this.#ws : undefined, this.#pending, this.#requestId, action, params);
   }
 
   /** Test / internal: admit a parsed event when the endpoint is open. */
@@ -208,6 +219,9 @@ export class NapCatWsEndpoint extends Endpoint<NapcatClient> {
       const ws = create(url, { headers });
       this.#ws = ws;
       handle.onForceClose(() => {
+        if (this.#ws === ws) {
+          rejectAllPending(this.#pending);
+        }
         try {
           ws.close();
         } catch {
@@ -216,7 +230,7 @@ export class NapCatWsEndpoint extends Endpoint<NapcatClient> {
       });
 
       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({
@@ -243,7 +257,12 @@ export class NapCatWsEndpoint extends Endpoint<NapcatClient> {
         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();
         handleNapCatWsMessage(data, {
           endpointId: this.#options.config.id,
           pending: this.#pending,
@@ -252,6 +271,9 @@ export class NapCatWsEndpoint extends Endpoint<NapcatClient> {
       });
 
       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)
@@ -278,6 +300,7 @@ export class NapCatWsEndpoint extends Endpoint<NapcatClient> {
       });
 
       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 { clearInterval, clearTimeout, setInterval, setTimeout } from 'node:timers';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import {
@@ -39,8 +40,8 @@ export function handleNapCatWsMessage(
         clearTimeout(pending.timeout);
         if (resp.status === 'ok') pending.resolve(resp.data);
         else {
-          pending.reject(new Error(
-            `API error [${resp.retcode}]: ${resp.message || resp.wording || 'unknown'}`,
+          pending.reject(new EndpointDeliveryError(
+            'platform_rejected', `API error [${resp.retcode}]: ${resp.message || resp.wording || 'unknown'}`, 'rejected',
           ));
         }
       }
@@ -64,17 +65,23 @@ export function callNapCatWsAction(
   params: Record<string, unknown>,
 ): Promise<unknown> {
   if (!ws || ws.readyState !== WS_OPEN) {
-    return Promise.reject(new Error('WebSocket is not connected'));
+    return Promise.reject(new EndpointDeliveryError('endpoint_disconnected', 'WebSocket is not connected', 'not_sent'));
   }
   const echo = `req_${++requestId.value}`;
   const req: NapCatActionRequest = { action, params, echo };
   return new Promise((resolve, reject) => {
     const timeout = setTimeout(() => {
       pending.delete(echo);
-      reject(new Error(`API call timeout: ${action}`));
+      reject(new EndpointDeliveryError('endpoint_timeout', `API call timeout: ${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)));
+    }
   });
 }
 
@@ -99,7 +106,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 NapCatWsSocket {
   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 NapCatWsCreateOptions {

package/src/wss-endpoint.ts

@@ -1,14 +1,16 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 /**
  * NapCat reverse WSS endpoint — accepts inbound WebSocket from NapCat.
  */
 import {
+  Endpoint,
   createEndpointLifecycle,
   createRecallEndpointControl,
   type EndpointLifecycle,
   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';
@@ -70,6 +72,7 @@ export class NapCatWssEndpoint extends Endpoint<NapcatClient> {
   #pending = new Map<string, NapCatPendingAction>();
   #open = false;
   #started = false;
+  #stopped = false;
 
   constructor(options: NapCatWssEndpointOptions) {
     super();
@@ -78,11 +81,21 @@ export class NapCatWssEndpoint extends Endpoint<NapcatClient> {
     this.#connectionLifecycle = createEndpointLifecycle({
       name: `${options.config.id}:inbound`,
       reconnect: false,
+      heartbeat: { intervalMs: options.config.heartbeat_interval, watchdogMisses: 2 },
     });
   }
 
+  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;
     this.#started = true;
     const handle = this.#options.http.ws(this.#options.config.path);
     this.#wsRelease = handle.onConnection((connection) => {
@@ -113,6 +126,7 @@ export class NapCatWssEndpoint extends Endpoint<NapcatClient> {
   }
 
   async stop(): Promise<void> {
+    this.#stopped = true;
     this.#open = false;
     this.#wsRelease?.();
     this.#wsRelease = undefined;
@@ -128,7 +142,11 @@ export class NapCatWssEndpoint extends Endpoint<NapcatClient> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(napcatOutboundTarget(conversation), message);
     const data = await this.client.callApi(action, params) as { message_id?: number | string } | undefined;
-    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> {
@@ -137,7 +155,7 @@ export class NapCatWssEndpoint extends Endpoint<NapcatClient> {
   }
 
   #callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
-    return callNapCatWsAction(this.#ws, this.#pending, this.#requestId, action, params);
+    return callNapCatWsAction(this.#connectionLifecycle.state === 'closed' ? undefined : this.#ws, this.#pending, this.#requestId, action, params);
   }
 
   admit(ev: NapCatEvent): void {
@@ -197,15 +215,23 @@ export class NapCatWssEndpoint extends Endpoint<NapcatClient> {
   }
 
   async #acceptConnection(connection: WsConnection): Promise<void> {
+    if (!this.#started || this.#stopped) {
+      connection.socket.close();
+      return;
+    }
     if (!verifyNapCatAccessToken(this.#options.config.access_token, connection.request)) {
       connection.socket.close(4003, 'Unauthorized');
       return;
     }
     const socket = connection.socket as unknown as NapCatWsSocket;
     await this.#connectionLifecycle.stop();
+    rejectAllPending(this.#pending, 'Connection replaced');
     await this.#connectionLifecycle.start(async (lifecycleHandle) => {
       this.#ws = socket;
       lifecycleHandle.onForceClose(() => {
+        if (this.#ws === socket) {
+          rejectAllPending(this.#pending);
+        }
         try {
           socket.close();
         } catch {
@@ -219,7 +245,11 @@ export class NapCatWssEndpoint extends Endpoint<NapcatClient> {
           /* ignore */
         }
       }, this.#options.config.heartbeat_interval);
+      socket.on('pong', () => {
+        if (this.#ws === socket) this.#connectionLifecycle.notifyHeartbeatAck();
+      });
       socket.on('message', (data) => {
+        if (this.#ws !== socket || this.#connectionLifecycle.state === 'closed') return;
         this.#connectionLifecycle.notifyHeartbeatAck();
         handleNapCatWsMessage(data, {
           endpointId: this.#options.config.id,
@@ -227,8 +257,14 @@ export class NapCatWssEndpoint extends Endpoint<NapcatClient> {
           admit: (event) => this.admit(event),
         });
       });
+      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) this.#ws = undefined;
+        if (this.#ws !== socket) return;
+        this.#ws = undefined;
+        rejectAllPending(this.#pending);
         lifecycleHandle.notifyClosed(new Error('NapCat reverse WebSocket closed'));
       });
     });