@zhin.js/adapter-icqq 1.1.4 → 1.1.6

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @zhin.js/adapter-icqq
 
+## 1.1.6
+
+### Patch Changes
+
+- badcc1f: Unify lazy JSX and HTML delivery across commands, inbound middleware and registered components. Remove the former JSX/template component runtimes, respect declared adapter HTML policies, and preserve author/generation ownership for automatic and explicit replies.
+
+  Add the optional @zhin.js/components library with composable JSXRenderable display props, shared themes, symmetric spacing and local style/text overrides. Include tables, lists, Markdown with highlighted code blocks, and display-only checkbox, radio, switch and button states; provide a reusable preview gallery. Update scaffolds, examples and public authoring documentation together.
+
+  Add optional official Tailwind static-utility compilation to inline styles. Consolidate raster rendering on @pixel.js/shotium, remove the Satori image toolkit, and align raster format contracts with actual PNG/JPEG/WebP results.
+
+  Reject cascade-dependent Tailwind values including unset, track the installed Tailwind version in the bundled theme provenance, and preserve both repository and upstream MIT attribution. Keep optional gallery dependency failures visible and document asynchronous Tailwind initialization.
+
+- Updated dependencies [badcc1f]
+  - @zhin.js/core@1.1.41
+  - @zhin.js/feature-kit@1.1.3
+  - @zhin.js/adapter@1.1.17
+  - @zhin.js/agent-feature@1.1.4
+  - @zhin.js/skill@1.1.4
+  - @zhin.js/tool@1.1.4
+  - @zhin.js/permission@1.1.4
+
+## 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

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

@@ -3,6 +3,7 @@ import { inspect } from 'node:util';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Endpoint, } from 'zhin.js/adapter';
 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');

package/lib/icqq-inbound.js

@@ -624,7 +624,8 @@ function mergeReplyFromSource(content, data) {
 }
 function quoteIdFromSegments(content) {
     const reply = content.find((item) => item.type === 'reply');
-    const value = reply?.data?.message_id ?? reply?.data?.id;
+    const data = reply?.data;
+    const value = data?.message_id ?? data?.id;
     return value == null || !String(value).trim() ? undefined : String(value).trim();
 }
 export function resolveInboundContent(data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-icqq",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "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.39",
-    "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/im-contract": "1.1.2",
+    "@zhin.js/adapter": "1.1.17",
+    "@zhin.js/agent-feature": "1.1.4",
+    "@zhin.js/core": "1.1.41",
+    "@zhin.js/feature-kit": "1.1.3",
+    "@zhin.js/im-contract": "1.1.3",
     "@zhin.js/logger": "1.1.1",
-    "@zhin.js/permission": "1.1.3",
-    "@zhin.js/skill": "1.1.2",
-    "@zhin.js/tool": "1.1.2"
+    "@zhin.js/permission": "1.1.4",
+    "@zhin.js/skill": "1.1.4",
+    "@zhin.js/tool": "1.1.4"
   },
   "peerDependencies": {
     "@icqqjs/icqq": "^1.12.2",
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.15",
-    "@zhin.js/command": "^1.1.3",
-    "@zhin.js/core": "^1.1.39",
-    "@zhin.js/prompt-section": "^1.1.2",
-    "zhin.js": "^1.1.4"
+    "@zhin.js/adapter": "^1.1.17",
+    "@zhin.js/command": "^1.1.5",
+    "@zhin.js/core": "^1.1.41",
+    "@zhin.js/prompt-section": "^1.1.3",
+    "zhin.js": "^1.1.6"
   },
   "peerDependenciesMeta": {
     "@icqqjs/icqq": {
@@ -76,8 +76,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/prompt-section": "1.1.2",
-    "zhin.js": "1.1.4"
+    "@zhin.js/prompt-section": "1.1.3",
+    "zhin.js": "1.1.6"
   },
   "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, buildSystem, toCanonicalSegments, type LoginAssist } from '@zhin.js/core';
-import type { MessageRef } from '@zhin.js/im-contract';
+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');

package/src/icqq-inbound.ts

@@ -781,7 +781,8 @@ function mergeReplyFromSource(
 
 function quoteIdFromSegments(content: readonly MessageSegment[]): string | undefined {
   const reply = content.find((item) => item.type === 'reply');
-  const value = reply?.data?.message_id ?? reply?.data?.id;
+  const data = reply?.data as Readonly<Record<string, unknown>> | undefined;
+  const value = data?.message_id ?? data?.id;
   return value == null || !String(value).trim() ? undefined : String(value).trim();
 }