@zhin.js/adapter-qq 9.0.0 → 9.0.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @zhin.js/adapter-qq
 
+## 9.0.1
+
+### Patch Changes
+
+- f7ee28d: Use the shared Endpoint lifecycle for QQ WebSocket and HTTP receivers. Isolate each SDK instance and its Webhook routes, close resources created by late startup completion after cancellation, and ignore callbacks queued by replaced SDK instances. Failed startup releases resources before retrying.
+- Updated dependencies [f7ee28d]
+  - @zhin.js/adapter@1.2.2
+  - @zhin.js/core@1.5.16
+  - zhin.js@7.0.1
+  - @zhin.js/agent@1.2.1
+
 ## 9.0.0
 
 ### Patch Changes

package/lib/endpoint.d.ts

@@ -1,8 +1,7 @@
-import { Endpoint } from 'zhin.js/adapter';
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import { type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, type EndpointControl, type EndpointManagement, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type QqInboundMessage, type ResolvedQqHttpConfig, type ResolvedQqWebsocketConfig } from './protocol.js';

package/lib/endpoint.js

@@ -1,8 +1,7 @@
-import { Endpoint } from 'zhin.js/adapter';
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import { createRecallEndpointControl, } from 'zhin.js/adapter';
+import { Endpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import { formatOutbound } from './outbound.js';
 import { formatInboundContent, parseCompoundMessageId, qqInboundConversation, qqOutboundKind, resolveOutboundMessageId, senderDisplayName, } from './protocol.js';
@@ -15,12 +14,14 @@ export class QqWebsocketEndpoint extends Endpoint {
     #createBot;
     #bot = null;
     #open = false;
-    #started = false;
+    #lifecycle;
+    #cleanup;
     management = createQqEndpointManagement(() => this.#requireBot());
     control = createRecallEndpointControl((id) => this.recallMessage(id));
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('qq', options.config.id);
+        this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateBot;
     }
@@ -32,21 +33,51 @@ export class QqWebsocketEndpoint extends Endpoint {
         return this.#options.config.id;
     }
     async start() {
-        if (this.#started)
-            return;
-        this.#started = true;
-        try {
-            this.#bot = this.#createBot(this.#options.config);
-            this.#bindBot(this.#bot);
-            await this.#bot.start();
-            this.#logger.info(`connected (websocket) | appid: ${this.#options.config.appid}`);
-        }
-        catch (error) {
-            await this.stop();
-            this.#logger.error('Failed to connect QQ websocket:', error);
-            const raw = error instanceof Error ? error.message : String(error);
-            throw new Error(`QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`, { cause: error });
-        }
+        await this.#lifecycle.start(async (handle) => {
+            const bot = this.#createBot(this.#options.config);
+            this.#bot = bot;
+            let cancelled = false;
+            let stopping;
+            const stopBot = async () => {
+                try {
+                    bot.removeAllListeners();
+                }
+                catch { /* continue SDK cleanup */ }
+                try {
+                    await bot.stop();
+                }
+                catch { /* best-effort SDK cleanup */ }
+            };
+            const cleanup = () => {
+                cancelled = true;
+                if (this.#bot === bot)
+                    this.#bot = null;
+                return stopping ??= stopBot();
+            };
+            this.#cleanup = cleanup;
+            handle.onForceClose(() => { void cleanup(); });
+            try {
+                this.#bindBot(bot);
+                await bot.start();
+                if (cancelled) {
+                    // SDK startup may create resources after stop; close this exact old client again.
+                    await stopping;
+                    await stopBot();
+                    return;
+                }
+                this.#logger.info(`connected (websocket) | appid: ${this.#options.config.appid}`);
+            }
+            catch (error) {
+                const wasCancelled = cancelled;
+                await cleanup();
+                if (wasCancelled) {
+                    await stopBot();
+                    return;
+                }
+                const raw = error instanceof Error ? error.message : String(error);
+                throw new Error(`QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`, { cause: error });
+            }
+        });
     }
     open() {
         this.#open = true;
@@ -56,17 +87,10 @@ export class QqWebsocketEndpoint extends Endpoint {
     }
     async stop() {
         this.#open = false;
-        if (this.#bot) {
-            try {
-                this.#bot.removeAllListeners();
-                await this.#bot.stop();
-            }
-            catch {
-                /* ignore */
-            }
-            this.#bot = null;
-        }
-        this.#started = false;
+        const cleanup = this.#cleanup;
+        this.#cleanup = undefined;
+        await this.#lifecycle.stop();
+        await cleanup?.();
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
@@ -158,12 +182,16 @@ export class QqWebsocketEndpoint extends Endpoint {
     }
     #bindBot(bot) {
         bindQqBotInboundEvents(bot, (raw) => {
+            if (this.#bot !== bot)
+                return;
             this.#emitPlatformEvent('message', raw);
             const msg = normalizeQqMessage(raw);
             if (msg)
                 this.admit(msg);
         });
         bindQqBotSideEvents(bot, (eventName, raw) => {
+            if (this.#bot !== bot)
+                return;
             this.#emitPlatformEvent(eventName, raw);
             receiveQqSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, bot, eventName, raw, this.#logger);
         });
@@ -189,14 +217,15 @@ export class QqHttpEndpoint extends Endpoint {
     #options;
     #createBot;
     #bot = null;
-    #routeReleases = [];
     #open = false;
-    #started = false;
+    #lifecycle;
+    #cleanup;
     management = createQqEndpointManagement(() => this.#requireBot());
     control = createRecallEndpointControl((id) => this.recallMessage(id));
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('qq', options.config.id);
+        this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateHttpBot;
     }
@@ -208,21 +237,57 @@ export class QqHttpEndpoint extends Endpoint {
         return this.#options.config.id;
     }
     async start() {
-        if (this.#started)
-            return;
-        this.#started = true;
-        try {
-            this.#setupRoutes();
-            this.#bot = this.#createBot(this.#options.config);
-            this.#bindBot(this.#bot);
-            await this.#bot.start();
-            this.#logger.info(`connected (${this.#options.config.mode}) | path: ${this.#options.config.webhookPath}`);
-        }
-        catch (error) {
-            await this.stop();
-            this.#logger.error('Failed to connect QQ HTTP receiver:', error);
-            throw error;
-        }
+        await this.#lifecycle.start(async (handle) => {
+            const bot = this.#createBot(this.#options.config);
+            this.#bot = bot;
+            let cancelled = false;
+            let stopping;
+            const routes = [];
+            const stopBot = async () => {
+                try {
+                    bot.removeAllListeners();
+                }
+                catch { /* continue SDK cleanup */ }
+                try {
+                    await bot.stop();
+                }
+                catch { /* best-effort SDK cleanup */ }
+            };
+            const cleanup = () => {
+                cancelled = true;
+                if (this.#bot === bot)
+                    this.#bot = null;
+                for (const release of routes.splice(0))
+                    release();
+                return stopping ??= stopBot();
+            };
+            this.#cleanup = cleanup;
+            handle.onForceClose(() => { void cleanup(); });
+            try {
+                this.#bindBot(bot);
+                routes.push(...registerQqWebhookRoutes(this.#options.http, {
+                    config: this.#options.config,
+                    getBot: () => cancelled ? null : bot,
+                }));
+                await bot.start();
+                if (cancelled) {
+                    // SDK startup may create resources after stop; close this exact old client again.
+                    await stopping;
+                    await stopBot();
+                    return;
+                }
+                this.#logger.info(`connected (${this.#options.config.mode}) | path: ${this.#options.config.webhookPath}`);
+            }
+            catch (error) {
+                const wasCancelled = cancelled;
+                await cleanup();
+                if (wasCancelled) {
+                    await stopBot();
+                    return;
+                }
+                throw error;
+            }
+        });
     }
     open() {
         this.#open = true;
@@ -232,19 +297,10 @@ export class QqHttpEndpoint extends Endpoint {
     }
     async stop() {
         this.#open = false;
-        for (const release of this.#routeReleases.splice(0))
-            release();
-        if (this.#bot) {
-            try {
-                this.#bot.removeAllListeners();
-                await this.#bot.stop();
-            }
-            catch {
-                /* ignore */
-            }
-            this.#bot = null;
-        }
-        this.#started = false;
+        const cleanup = this.#cleanup;
+        this.#cleanup = undefined;
+        await this.#lifecycle.stop();
+        await cleanup?.();
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
@@ -333,20 +389,18 @@ export class QqHttpEndpoint extends Endpoint {
             }));
         });
     }
-    #setupRoutes() {
-        this.#routeReleases.push(...registerQqWebhookRoutes(this.#options.http, {
-            config: this.#options.config,
-            getBot: () => this.#bot,
-        }));
-    }
     #bindBot(bot) {
         bindQqBotInboundEvents(bot, (raw) => {
+            if (this.#bot !== bot)
+                return;
             this.#emitPlatformEvent('message', raw);
             const msg = normalizeQqMessage(raw);
             if (msg)
                 this.admit(msg);
         });
         bindQqBotSideEvents(bot, (eventName, raw) => {
+            if (this.#bot !== bot)
+                return;
             this.#emitPlatformEvent(eventName, raw);
             receiveQqSideEvent((name, payload) => this.emit(name, payload), this.#options.config.id, bot, eventName, raw, this.#logger);
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "9.0.0",
+  "version": "9.0.1",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,8 +35,8 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.2.3",
-    "@zhin.js/adapter": "1.2.1",
-    "@zhin.js/core": "1.5.15",
+    "@zhin.js/adapter": "1.2.2",
+    "@zhin.js/core": "1.5.16",
     "@zhin.js/feature-kit": "1.0.13",
     "@zhin.js/host-http": "1.0.17",
     "@zhin.js/im-contract": "1.0.4",
@@ -45,12 +45,12 @@
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.2.1",
-    "@zhin.js/agent": "1.2.0",
+    "@zhin.js/adapter": "1.2.2",
+    "@zhin.js/agent": "1.2.1",
     "@zhin.js/command": "1.0.16",
-    "@zhin.js/core": "1.5.15",
+    "@zhin.js/core": "1.5.16",
     "@zhin.js/middleware": "1.0.13",
-    "zhin.js": "7.0.0"
+    "zhin.js": "7.0.1"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -74,9 +74,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.2.0",
+    "@zhin.js/agent": "1.2.1",
     "@zhin.js/host-http": "1.0.17",
-    "zhin.js": "7.0.0"
+    "zhin.js": "7.0.1"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -1,8 +1,8 @@
-import { Endpoint } from 'zhin.js/adapter';
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
 import {
+  Endpoint, createEndpointLifecycle, type EndpointLifecycle,
   createRecallEndpointControl,
   type EndpointControl,
   type EndpointChannel,
@@ -59,13 +59,15 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   readonly #createBot: CreateQqBot;
   #bot: QqBotTransport | null = null;
   #open = false;
-  #started = false;
+  readonly #lifecycle: EndpointLifecycle;
+  #cleanup?: () => Promise<void>;
   readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
   readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
 
   constructor(options: QqEndpointOptions) {
     super();
     this.#logger = getAdapterLogger('qq', options.config.id);
+    this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateBot;
   }
@@ -80,24 +82,46 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
   }
 
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
-    try {
-      this.#bot = this.#createBot(this.#options.config);
-      this.#bindBot(this.#bot);
-      await this.#bot.start();
-      this.#logger.info(
-        `connected (websocket) | appid: ${this.#options.config.appid}`,
-      );
-    } catch (error) {
-      await this.stop();
-      this.#logger.error('Failed to connect QQ websocket:', error);
-      const raw = error instanceof Error ? error.message : String(error);
-      throw new Error(
-        `QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`,
-        { cause: error },
-      );
-    }
+    await this.#lifecycle.start(async (handle) => {
+      const bot = this.#createBot(this.#options.config);
+      this.#bot = bot;
+      let cancelled = false;
+      let stopping: Promise<void> | undefined;
+      const stopBot = async () => {
+        try { bot.removeAllListeners(); } catch { /* continue SDK cleanup */ }
+        try { await bot.stop(); } catch { /* best-effort SDK cleanup */ }
+      };
+      const cleanup = () => {
+        cancelled = true;
+        if (this.#bot === bot) this.#bot = null;
+        return stopping ??= stopBot();
+      };
+      this.#cleanup = cleanup;
+      handle.onForceClose(() => { void cleanup(); });
+      try {
+        this.#bindBot(bot);
+        await bot.start();
+        if (cancelled) {
+          // SDK startup may create resources after stop; close this exact old client again.
+          await stopping;
+          await stopBot();
+          return;
+        }
+        this.#logger.info(`connected (websocket) | appid: ${this.#options.config.appid}`);
+      } catch (error) {
+        const wasCancelled = cancelled;
+        await cleanup();
+        if (wasCancelled) {
+          await stopBot();
+          return;
+        }
+        const raw = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`,
+          { cause: error },
+        );
+      }
+    });
   }
 
   open(): void {
@@ -110,16 +134,10 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
 
   async stop(): Promise<void> {
     this.#open = false;
-    if (this.#bot) {
-      try {
-        this.#bot.removeAllListeners();
-        await this.#bot.stop();
-      } catch {
-        /* ignore */
-      }
-      this.#bot = null;
-    }
-    this.#started = false;
+    const cleanup = this.#cleanup;
+    this.#cleanup = undefined;
+    await this.#lifecycle.stop();
+    await cleanup?.();
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
@@ -217,11 +235,13 @@ export class QqWebsocketEndpoint extends Endpoint<QqBotTransport> {
 
   #bindBot(bot: QqBotTransport): void {
     bindQqBotInboundEvents(bot, (raw) => {
+      if (this.#bot !== bot) return;
       this.#emitPlatformEvent('message', raw);
       const msg = normalizeQqMessage(raw);
       if (msg) this.admit(msg);
     });
     bindQqBotSideEvents(bot, (eventName, raw) => {
+      if (this.#bot !== bot) return;
       this.#emitPlatformEvent(eventName, raw);
       receiveQqSideEvent(
         (name, payload) => this.emit(name, payload),
@@ -264,15 +284,16 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   readonly #options: QqHttpEndpointOptions;
   readonly #createBot: CreateQqHttpBot;
   #bot: QqHttpBotTransport | null = null;
-  #routeReleases: ReturnType<typeof registerQqWebhookRoutes> = [];
   #open = false;
-  #started = false;
+  readonly #lifecycle: EndpointLifecycle;
+  #cleanup?: () => Promise<void>;
   readonly management: EndpointManagement = createQqEndpointManagement(() => this.#requireBot());
   readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
 
   constructor(options: QqHttpEndpointOptions) {
     super();
     this.#logger = getAdapterLogger('qq', options.config.id);
+    this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateHttpBot;
   }
@@ -287,21 +308,48 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
   }
 
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
-    try {
-      this.#setupRoutes();
-      this.#bot = this.#createBot(this.#options.config);
-      this.#bindBot(this.#bot);
-      await this.#bot.start();
-      this.#logger.info(
-        `connected (${this.#options.config.mode}) | path: ${this.#options.config.webhookPath}`,
-      );
-    } catch (error) {
-      await this.stop();
-      this.#logger.error('Failed to connect QQ HTTP receiver:', error);
-      throw error;
-    }
+    await this.#lifecycle.start(async (handle) => {
+      const bot = this.#createBot(this.#options.config);
+      this.#bot = bot;
+      let cancelled = false;
+      let stopping: Promise<void> | undefined;
+      const routes: Array<() => void> = [];
+      const stopBot = async () => {
+        try { bot.removeAllListeners(); } catch { /* continue SDK cleanup */ }
+        try { await bot.stop(); } catch { /* best-effort SDK cleanup */ }
+      };
+      const cleanup = () => {
+        cancelled = true;
+        if (this.#bot === bot) this.#bot = null;
+        for (const release of routes.splice(0)) release();
+        return stopping ??= stopBot();
+      };
+      this.#cleanup = cleanup;
+      handle.onForceClose(() => { void cleanup(); });
+      try {
+        this.#bindBot(bot);
+        routes.push(...registerQqWebhookRoutes(this.#options.http, {
+          config: this.#options.config,
+          getBot: () => cancelled ? null : bot,
+        }));
+        await bot.start();
+        if (cancelled) {
+          // SDK startup may create resources after stop; close this exact old client again.
+          await stopping;
+          await stopBot();
+          return;
+        }
+        this.#logger.info(`connected (${this.#options.config.mode}) | path: ${this.#options.config.webhookPath}`);
+      } catch (error) {
+        const wasCancelled = cancelled;
+        await cleanup();
+        if (wasCancelled) {
+          await stopBot();
+          return;
+        }
+        throw error;
+      }
+    });
   }
 
   open(): void {
@@ -314,17 +362,10 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
 
   async stop(): Promise<void> {
     this.#open = false;
-    for (const release of this.#routeReleases.splice(0)) release();
-    if (this.#bot) {
-      try {
-        this.#bot.removeAllListeners();
-        await this.#bot.stop();
-      } catch {
-        /* ignore */
-      }
-      this.#bot = null;
-    }
-    this.#started = false;
+    const cleanup = this.#cleanup;
+    this.#cleanup = undefined;
+    await this.#lifecycle.stop();
+    await cleanup?.();
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
@@ -419,20 +460,15 @@ export class QqHttpEndpoint extends Endpoint<QqHttpBotTransport> {
     });
   }
 
-  #setupRoutes(): void {
-    this.#routeReleases.push(...registerQqWebhookRoutes(this.#options.http, {
-      config: this.#options.config,
-      getBot: () => this.#bot,
-    }));
-  }
-
   #bindBot(bot: QqBotTransport): void {
     bindQqBotInboundEvents(bot, (raw) => {
+      if (this.#bot !== bot) return;
       this.#emitPlatformEvent('message', raw);
       const msg = normalizeQqMessage(raw);
       if (msg) this.admit(msg);
     });
     bindQqBotSideEvents(bot, (eventName, raw) => {
+      if (this.#bot !== bot) return;
       this.#emitPlatformEvent(eventName, raw);
       receiveQqSideEvent(
         (name, payload) => this.emit(name, payload),