@zhin.js/adapter-icqq 1.1.3 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @zhin.js/adapter-icqq
 
+## 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]
+  - @zhin.js/adapter@1.1.16
+  - @zhin.js/im-contract@1.1.3
+  - @zhin.js/core@1.1.40
+  - @zhin.js/tool@1.1.3
+  - @zhin.js/skill@1.1.3
+  - @zhin.js/agent-feature@1.1.3
+
+## 1.1.4
+
+### Patch Changes
+
+- 43eda99: Unify Notice and Request payloads with their public types and runtime exports. Use camelCase fields, preserve native data under metadata, and bind canonical endpoint identity and request actions to the held generation. Remove legacy data aliases and from factories.
+
+  Keep login and lifecycle signals as independent SystemEvent payloads on system.receive, without chat conversation fields or user interaction. Update built-in adapter projections and authoring guidance.
+
+- 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

@@ -175,3 +175,9 @@ IM turn 的场景，才使用 `icqqClient.get(context, endpointId)` 显式选择
 ## License
 
 MIT
+
+### 发送回执与未知结果
+
+发送成功回执只接受平台真实消息 ID。网络超时、断线、缺少消息 ID 的响应会报告 `deliveryUnknown`，框架不会自动重发；手动重发可能重复发送。
+
+ICQQ 原生分享和文件 API 可能已经成功，但只返回空值或文件 ID；这类结果不能当作可引用、可撤回的消息 ID，因此报告投递结果未知。平台操作仍只执行一次。文件撤回应使用平台专用文件 API。

package/lib/endpoint.d.ts

@@ -1,5 +1,5 @@
 import { Client } from '@icqqjs/icqq';
-import { Endpoint, 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 { EndpointContentPort } from '@zhin.js/adapter';
 import { type LoginAssist } from '@zhin.js/core';
 import type { CapabilityId } from 'zhin.js';
@@ -20,6 +20,7 @@ export declare class IcqqEndpoint extends Endpoint<Client> {
     readonly management: EndpointManagement;
     readonly control: EndpointControl;
     constructor(options: IcqqEndpointOptions);
+    get transportState(): EndpointTransportState;
     start(signal: AbortSignal): Promise<void>;
     open(): void;
     close(): Promise<void>;

package/lib/endpoint.js

@@ -2,7 +2,8 @@ import { Client, parseGroupMessageId, } from '@icqqjs/icqq';
 import { inspect } from 'node:util';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Endpoint, } from 'zhin.js/adapter';
-import { receiveOneBotLikeSideEvent, SystemEvent, toCanonicalSegments } from '@zhin.js/core';
+import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments } from '@zhin.js/core';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
 import { IcqqContentResolver } from './content-resolver.js';
@@ -49,6 +50,8 @@ export class IcqqEndpoint extends Endpoint {
     #open = false;
     #retiring = false;
     #started = false;
+    #stopped = false;
+    #everOnline = false;
     #retirementEpoch = 0;
     #retirementArmed = false;
     #disposeNativeEvents;
@@ -144,10 +147,22 @@ export class IcqqEndpoint extends Endpoint {
             }));
         });
     }
+    get transportState() {
+        if (this.#stopped || this.#retiring)
+            return 'stopped';
+        if (!this.#started)
+            return 'idle';
+        if (this.client.isOnline())
+            return 'open';
+        if (!this.#everOnline)
+            return 'connecting';
+        return this.#options.config.autoReconnect ? 'reconnecting' : 'closed';
+    }
     async start(signal) {
         if (this.#started)
             return;
         signal.throwIfAborted();
+        this.#stopped = false;
         // Invalidate a guard left by a prior lifecycle epoch before admitting a
         // new login attempt on this endpoint instance.
         this.#retirementEpoch += 1;
@@ -204,6 +219,7 @@ export class IcqqEndpoint extends Endpoint {
         await Promise.allSettled([...this.#inflightInbound]);
     }
     async stop() {
+        this.#stopped = true;
         this.#assertExternalLifecycle('stop');
         this.#armRetirementFence();
         await Promise.allSettled([...this.#inflightInbound]);
@@ -259,7 +275,7 @@ export class IcqqEndpoint extends Endpoint {
     }
     async send({ conversation, payload }) {
         if (!this.#started)
-            throw new Error('icqq endpoint 未连接');
+            throw new EndpointDeliveryError('endpoint_disconnected', 'icqq endpoint 未连接', 'not_sent');
         const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
         const prepared = isIcqqSegmentPayload(payload)
             ? prepareIcqqOutboundMedia(payload, mediaMode)
@@ -281,7 +297,11 @@ export class IcqqEndpoint extends Endpoint {
                 }));
                 throw error;
             }
-            const messageId = String(result?.message_id ?? `sent_${Date.now()}`);
+            const rawId = result?.message_id;
+            if ((typeof rawId !== 'string' && typeof rawId !== 'number') || String(rawId).trim() === '' || (typeof rawId === 'number' && !Number.isFinite(rawId))) {
+                throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: ICQQ returned no message_id', 'unknown');
+            }
+            const messageId = String(rawId);
             this.#logger.info(`send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(preview, 80)}`);
             return messageId;
         }
@@ -314,12 +334,12 @@ export class IcqqEndpoint extends Endpoint {
         if (isIcqqFileElement(message)) {
             switch (target.kind) {
                 case 'private': {
-                    const id = await this.client.pickFriend(target.userId).sendFile(message.file, message.name);
-                    return { message_id: id };
+                    await this.client.pickFriend(target.userId).sendFile(message.file, message.name);
+                    return {};
                 }
                 case 'group': {
-                    const stat = await this.client.pickGroup(target.groupId).sendFile(message.file, '/', message.name);
-                    return { message_id: stat.fid };
+                    await this.client.pickGroup(target.groupId).sendFile(message.file, '/', message.name);
+                    return {};
                 }
                 case 'temp':
                 case 'channel':
@@ -489,6 +509,7 @@ export class IcqqEndpoint extends Endpoint {
         this.client.on('system.online', (event) => {
             if (this.#retiring)
                 return;
+            this.#everOnline = true;
             try {
                 this.#resolveStartOnline?.();
                 this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'online');
@@ -578,16 +599,13 @@ export class IcqqEndpoint extends Endpoint {
         });
     }
     #dispatchIcqqSystemSideEvent(type, payload) {
-        const { scene_type, sub_type } = parseIcqqSystemScene(type);
-        void this.emit('system.receive', SystemEvent.from(payload ?? {}, {
-            $id: `system:${this.endpointName}:${type}:${Date.now()}`,
-            $adapter: 'icqq',
-            $endpoint: this.endpointName,
-            $type: 'system',
-            $scene_id: this.endpointName,
-            $scene_type: scene_type,
-            $sub_type: sub_type,
-            $timestamp: Date.now(),
+        void this.emit('system.receive', buildSystem(payload ?? {}, {
+            id: `system:${this.endpointName}:${type}:${Date.now()}`,
+            clientAdapter: 'icqq',
+            endpointId: this.endpointName,
+            type: 'system',
+            name: `system.${type}`,
+            timestamp: Date.now(),
         })).catch((err) => {
             this.#logger.warn(formatCompact({
                 op: 'icqq_system_side_event_failed',
@@ -984,20 +1002,5 @@ function serializeIcqqEvent(event) {
     }
     return Object.keys(out).length > 0 ? out : null;
 }
-function parseIcqqSystemScene(type) {
-    if (type.startsWith('login.')) {
-        return { scene_type: 'login', sub_type: type.slice('login.'.length) || 'unknown' };
-    }
-    if (type.startsWith('offline.')) {
-        return { scene_type: 'offline', sub_type: type.slice('offline.'.length) || 'unknown' };
-    }
-    if (type === 'online') {
-        return { scene_type: 'online', sub_type: 'online' };
-    }
-    if (type === 'offline') {
-        return { scene_type: 'offline', sub_type: 'offline' };
-    }
-    return { scene_type: 'system', sub_type: type };
-}
 const INBOUND_HOLD_LIMIT = 32;
 const ICQQ_SERIALIZE_SKIP = ['group', 'member', 'friend', 'discuss', 'client'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Zhin.js ICQQ adapter — direct connection to @icqqjs/icqq",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,24 +34,24 @@
     "directory": "plugins/adapters/icqq"
   },
   "dependencies": {
-    "@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/im-contract": "1.1.2",
+    "@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"
   },
   "peerDependencies": {
     "@icqqjs/icqq": "^1.12.2",
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.15",
-    "@zhin.js/command": "^1.1.2",
-    "@zhin.js/core": "^1.1.38",
+    "@zhin.js/adapter": "^1.1.16",
+    "@zhin.js/command": "^1.1.4",
+    "@zhin.js/core": "^1.1.40",
     "@zhin.js/prompt-section": "^1.1.2",
-    "zhin.js": "^1.1.3"
+    "zhin.js": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@icqqjs/icqq": {
@@ -77,7 +77,7 @@
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
     "@zhin.js/prompt-section": "1.1.2",
-    "zhin.js": "1.1.3"
+    "zhin.js": "1.1.5"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -16,10 +16,11 @@ import {
   type EndpointManagement,
   type EndpointPendingRequest,
   type EndpointSendRequest,
+  type EndpointTransportState,
 } from 'zhin.js/adapter';
 import type { EndpointContentPort } from '@zhin.js/adapter';
-import { receiveOneBotLikeSideEvent, SystemEvent, toCanonicalSegments, type LoginAssist } from '@zhin.js/core';
-import type { MessageRef } from '@zhin.js/im-contract';
+import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments, type LoginAssist } from '@zhin.js/core';
+import { EndpointDeliveryError, type MessageRef } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
@@ -103,6 +104,8 @@ export class IcqqEndpoint extends Endpoint<Client> {
   #open = false;
   #retiring = false;
   #started = false;
+  #stopped = false;
+  #everOnline = false;
   #retirementEpoch = 0;
   #retirementArmed = false;
   #disposeNativeEvents?: () => void;
@@ -207,9 +210,18 @@ export class IcqqEndpoint extends Endpoint<Client> {
     });
   }
 
+  get transportState(): EndpointTransportState {
+    if (this.#stopped || this.#retiring) return 'stopped';
+    if (!this.#started) return 'idle';
+    if (this.client.isOnline()) return 'open';
+    if (!this.#everOnline) return 'connecting';
+    return this.#options.config.autoReconnect ? 'reconnecting' : 'closed';
+  }
+
   async start(signal: AbortSignal): Promise<void> {
     if (this.#started) return;
     signal.throwIfAborted();
+    this.#stopped = false;
     // Invalidate a guard left by a prior lifecycle epoch before admitting a
     // new login attempt on this endpoint instance.
     this.#retirementEpoch += 1;
@@ -268,6 +280,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
   }
 
   async stop(): Promise<void> {
+    this.#stopped = true;
     this.#assertExternalLifecycle('stop');
     this.#armRetirementFence();
     await Promise.allSettled([...this.#inflightInbound]);
@@ -319,7 +332,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
-    if (!this.#started) throw new Error('icqq endpoint 未连接');
+    if (!this.#started) throw new EndpointDeliveryError('endpoint_disconnected', 'icqq endpoint 未连接', 'not_sent');
     const mediaMode = resolveIcqqOutboundMediaMode(this.#options.config);
     const prepared = isIcqqSegmentPayload(payload)
       ? prepareIcqqOutboundMedia(payload, mediaMode)
@@ -340,7 +353,11 @@ export class IcqqEndpoint extends Endpoint<Client> {
         }));
         throw error;
       }
-      const messageId = String(result?.message_id ?? `sent_${Date.now()}`);
+      const rawId = result?.message_id;
+      if ((typeof rawId !== 'string' && typeof rawId !== 'number') || String(rawId).trim() === '' || (typeof rawId === 'number' && !Number.isFinite(rawId))) {
+        throw new EndpointDeliveryError('delivery_unconfirmed', 'Message delivery is unconfirmed: ICQQ returned no message_id', 'unknown');
+      }
+      const messageId = String(rawId);
       this.#logger.info(
         `send ${conversation.kind}:${conversation.id} | id: ${messageId} | ${truncatePreview(preview, 80)}`,
       );
@@ -378,12 +395,12 @@ export class IcqqEndpoint extends Endpoint<Client> {
     if (isIcqqFileElement(message)) {
       switch (target.kind) {
         case 'private': {
-          const id = await this.client.pickFriend(target.userId).sendFile(message.file, message.name);
-          return { message_id: id };
+          await this.client.pickFriend(target.userId).sendFile(message.file, message.name);
+          return {};
         }
         case 'group': {
-          const stat = await this.client.pickGroup(target.groupId).sendFile(message.file, '/', message.name);
-          return { message_id: stat.fid };
+          await this.client.pickGroup(target.groupId).sendFile(message.file, '/', message.name);
+          return {};
         }
         case 'temp':
         case 'channel':
@@ -560,6 +577,7 @@ export class IcqqEndpoint extends Endpoint<Client> {
   #bindSystemOnlineEvent(): void {
     this.client.on('system.online', (event) => {
       if (this.#retiring) return;
+      this.#everOnline = true;
       try {
         this.#resolveStartOnline?.();
         this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'online');
@@ -659,16 +677,13 @@ export class IcqqEndpoint extends Endpoint<Client> {
   }
 
   #dispatchIcqqSystemSideEvent(type: string, payload: Record<string, unknown> | null): void {
-    const { scene_type, sub_type } = parseIcqqSystemScene(type);
-    void this.emit('system.receive', SystemEvent.from(payload ?? {}, {
-      $id: `system:${this.endpointName}:${type}:${Date.now()}`,
-      $adapter: 'icqq' as never,
-      $endpoint: this.endpointName,
-      $type: 'system',
-      $scene_id: this.endpointName,
-      $scene_type: scene_type,
-      $sub_type: sub_type,
-      $timestamp: Date.now(),
+    void this.emit('system.receive', buildSystem(payload ?? {}, {
+      id: `system:${this.endpointName}:${type}:${Date.now()}`,
+      clientAdapter: 'icqq',
+      endpointId: this.endpointName,
+      type: 'system',
+      name: `system.${type}`,
+      timestamp: Date.now(),
     })).catch((err) => {
       this.#logger.warn(formatCompact({
         op: 'icqq_system_side_event_failed',
@@ -1063,22 +1078,6 @@ function serializeIcqqEvent(event: unknown): Record<string, unknown> | null {
   return Object.keys(out).length > 0 ? out : null;
 }
 
-function parseIcqqSystemScene(type: string): { scene_type: string; sub_type: string } {
-  if (type.startsWith('login.')) {
-    return { scene_type: 'login', sub_type: type.slice('login.'.length) || 'unknown' };
-  }
-  if (type.startsWith('offline.')) {
-    return { scene_type: 'offline', sub_type: type.slice('offline.'.length) || 'unknown' };
-  }
-  if (type === 'online') {
-    return { scene_type: 'online', sub_type: 'online' };
-  }
-  if (type === 'offline') {
-    return { scene_type: 'offline', sub_type: 'offline' };
-  }
-  return { scene_type: 'system', sub_type: type };
-}
-
 const INBOUND_HOLD_LIMIT = 32;
 
 const ICQQ_SERIALIZE_SKIP = ['group', 'member', 'friend', 'discuss', 'client'] as const;