@zhin.js/adapter-milky 5.0.0 → 5.0.1

package/src/sse-endpoint.ts

@@ -1,10 +1,17 @@
 /**
  * Milky SSE client endpoint — GET text/event-stream on /event.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import {
+  createEndpointLifecycle,
+  type EndpointConnectHandle,
+  type EndpointInstance,
+  type EndpointLifecycle,
+  type EndpointManagement,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
 import {
   buildSendAction,
@@ -13,6 +20,7 @@ import {
   extractInboundAudioUrl,
   formatInboundContent,
   formatInboundMessageId,
+  formatInboundSegments,
   formatInboundTarget,
   formatOutboundMessageId,
   formatOutboundSegments,
@@ -47,24 +55,38 @@ export interface MilkySseEndpointOptions {
 export class MilkySseEndpoint implements EndpointInstance {
   readonly #options: MilkySseEndpointOptions;
   readonly #callApi: typeof callApi;
+  readonly management: EndpointManagement = createMilkyEndpointManagement(this);
+  readonly #lifecycle: EndpointLifecycle;
   #stream?: SseClientHandle;
-  #reconnectTimer?: NodeJS.Timeout;
   #open = false;
-  #started = false;
-  #stopping = false;
   #unregisterAgent?: () => void;
 
   constructor(options: MilkySseEndpointOptions) {
     this.#options = options;
     this.#callApi = options.callApi ?? callApi;
+    this.#lifecycle = createEndpointLifecycle({
+      name: options.config.name,
+      // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
+      reconnect: {
+        initialIntervalMs: options.config.reconnect_interval,
+        multiplier: 1,
+        maxIntervalMs: Number.MAX_SAFE_INTEGER,
+        jitterMs: 0,
+      },
+    });
   }
 
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
-    this.#stopping = false;
+    if (this.#lifecycle.started) return;
     this.#unregisterAgent = registerMilkyAgentEndpoint(this.#options.config.name, this);
-    await this.#connect();
+    try {
+      await this.#lifecycle.start((handle) => this.#connect(handle));
+    } catch (err) {
+      // 与 WS 对齐：start 失败复位由基座保证；agent 反注册留在适配器侧，允许重试
+      this.#unregisterAgent?.();
+      this.#unregisterAgent = undefined;
+      throw err;
+    }
   }
 
   open(): void {
@@ -77,17 +99,11 @@ export class MilkySseEndpoint implements EndpointInstance {
 
   async stop(): Promise<void> {
     this.#open = false;
-    this.#stopping = true;
-    this.#started = false;
+    await this.#lifecycle.stop();
     this.#unregisterAgent?.();
     this.#unregisterAgent = undefined;
-    if (this.#reconnectTimer) {
-      clearTimeout(this.#reconnectTimer);
-      this.#reconnectTimer = undefined;
-    }
     this.#stream?.close();
     this.#stream = undefined;
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name, mode: 'sse' }));
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
@@ -204,6 +220,7 @@ export class MilkySseEndpoint implements EndpointInstance {
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
     const target = formatInboundTarget(data);
     const content = formatInboundContent(data);
+    const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
@@ -211,6 +228,7 @@ export class MilkySseEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target,
       content,
+      segments,
       sender: String(data.sender_id),
       id: formatInboundMessageId(data),
       metadata: Object.freeze({
@@ -234,7 +252,7 @@ export class MilkySseEndpoint implements EndpointInstance {
     });
   }
 
-  async #connect(): Promise<void> {
+  async #connect(handle: EndpointConnectHandle): Promise<void> {
     const { url, headers, safeUrl } = buildSseConnectOptions(this.#options.config);
     const create = this.#options.createSseStream ?? ((opts) => openSseStream(opts));
 
@@ -268,19 +286,29 @@ export class MilkySseEndpoint implements EndpointInstance {
         },
       });
       this.#stream = stream;
+      handle.onForceClose(() => {
+        try {
+          stream.close();
+        } catch {
+          /* ignore */
+        }
+      });
       void stream.closed.then(() => {
-        if (this.#stopping) return;
-        logger.warn(formatCompact({
-          op: 'disconnect',
-          endpoint: this.#options.config.name,
-          mode: 'sse',
-          reconnect_ms: this.#options.config.reconnect_interval,
-        }));
+        // stop-during-connect 竞态由基座静默 settle（主动停止不算失败），此处仅对运行期断开告警
+        if (this.#lifecycle.state !== 'stopped') {
+          logger.warn(formatCompact({
+            op: 'disconnect',
+            endpoint: this.#options.config.name,
+            mode: 'sse',
+            reconnect_ms: this.#options.config.reconnect_interval,
+          }));
+        }
+        // 基座语义：仅曾 open 的连接才武装重连；初始连接失败由 start() 的 catch 复位
+        handle.notifyClosed(new Error('Milky SSE closed'));
         if (!settled) {
           settled = true;
           reject(new Error('Milky SSE closed before open'));
         }
-        this.#scheduleReconnect();
       });
     });
   }
@@ -298,21 +326,4 @@ export class MilkySseEndpoint implements EndpointInstance {
       }));
     }
   }
-
-  #scheduleReconnect(): void {
-    if (this.#stopping || !this.#started || this.#reconnectTimer) return;
-    const delay = this.#options.config.reconnect_interval;
-    this.#reconnectTimer = setTimeout(() => {
-      this.#reconnectTimer = undefined;
-      void this.#connect().catch((err) => {
-        logger.warn(formatCompact({
-          op: 'reconnect',
-          endpoint: this.#options.config.name,
-          mode: 'sse',
-          ok: false,
-          error: err instanceof Error ? err.message : String(err),
-        }));
-      });
-    }, delay);
-  }
 }

package/src/webhook-endpoint.ts

@@ -2,12 +2,13 @@
  * Milky webhook endpoint — httpHostToken POST inbound + baseUrl HTTP API outbound.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { readRequestBody, verifyMilkyAccessToken } from './milky-auth.js';
+import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
 import {
   buildSendAction,
@@ -15,6 +16,7 @@ import {
   extractInboundAudioUrl,
   formatInboundContent,
   formatInboundMessageId,
+  formatInboundSegments,
   formatInboundTarget,
   formatOutboundMessageId,
   formatOutboundSegments,
@@ -40,6 +42,7 @@ export interface MilkyWebhookEndpointOptions {
 export class MilkyWebhookEndpoint implements EndpointInstance {
   readonly #options: MilkyWebhookEndpointOptions;
   readonly #callApi: typeof callApi;
+  readonly management: EndpointManagement = createMilkyEndpointManagement(this);
   #routeReleases: HttpRouteRegistration[] = [];
   #open = false;
   #started = false;
@@ -193,6 +196,7 @@ export class MilkyWebhookEndpoint implements EndpointInstance {
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
     const target = formatInboundTarget(data);
     const content = formatInboundContent(data);
+    const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
@@ -200,6 +204,7 @@ export class MilkyWebhookEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target,
       content,
+      segments,
       sender: String(data.sender_id),
       id: formatInboundMessageId(data),
       metadata: Object.freeze({

package/src/ws-endpoint.ts

@@ -2,11 +2,17 @@
  * Milky WS client endpoint — outbound connect to Milky protocol server.
  */
 import WebSocket from 'ws';
-import { clearInterval, clearTimeout } from 'node:timers';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import {
+  createEndpointLifecycle,
+  type EndpointConnectHandle,
+  type EndpointInstance,
+  type EndpointLifecycle,
+  type EndpointManagement,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
 import {
   buildSendAction,
@@ -15,6 +21,7 @@ import {
   extractInboundAudioUrl,
   formatInboundContent,
   formatInboundMessageId,
+  formatInboundSegments,
   formatInboundTarget,
   formatOutboundMessageId,
   formatOutboundSegments,
@@ -45,25 +52,38 @@ export interface MilkyWsEndpointOptions {
 export class MilkyWsEndpoint implements EndpointInstance {
   readonly #options: MilkyWsEndpointOptions;
   readonly #callApi: typeof callApi;
+  readonly management: EndpointManagement = createMilkyEndpointManagement(this);
+  readonly #lifecycle: EndpointLifecycle;
   #ws?: MilkyWsSocket;
-  #reconnectTimer?: NodeJS.Timeout;
-  #heartbeatTimer?: NodeJS.Timeout;
   #open = false;
-  #started = false;
-  #stopping = false;
   #unregisterAgent?: () => void;
 
   constructor(options: MilkyWsEndpointOptions) {
     this.#options = options;
     this.#callApi = options.callApi ?? callApi;
+    this.#lifecycle = createEndpointLifecycle({
+      name: options.config.name,
+      // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
+      reconnect: {
+        initialIntervalMs: options.config.reconnect_interval,
+        multiplier: 1,
+        maxIntervalMs: Number.MAX_SAFE_INTEGER,
+        jitterMs: 0,
+      },
+    });
   }
 
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
-    this.#stopping = false;
+    if (this.#lifecycle.started) return;
     this.#unregisterAgent = registerMilkyAgentEndpoint(this.#options.config.name, this);
-    await this.#connect();
+    try {
+      await this.#lifecycle.start((handle) => this.#connect(handle));
+    } catch (err) {
+      // start 失败复位由基座保证；agent 注册/反注册是适配器专有依赖，留在适配器侧
+      this.#unregisterAgent?.();
+      this.#unregisterAgent = undefined;
+      throw err;
+    }
   }
 
   open(): void {
@@ -76,18 +96,9 @@ export class MilkyWsEndpoint implements EndpointInstance {
 
   async stop(): Promise<void> {
     this.#open = false;
-    this.#stopping = true;
-    this.#started = false;
+    await this.#lifecycle.stop();
     this.#unregisterAgent?.();
     this.#unregisterAgent = undefined;
-    if (this.#reconnectTimer) {
-      clearTimeout(this.#reconnectTimer);
-      this.#reconnectTimer = undefined;
-    }
-    if (this.#heartbeatTimer) {
-      clearInterval(this.#heartbeatTimer);
-      this.#heartbeatTimer = undefined;
-    }
     if (this.#ws) {
       try {
         this.#ws.close();
@@ -96,7 +107,6 @@ export class MilkyWsEndpoint implements EndpointInstance {
       }
       this.#ws = undefined;
     }
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
@@ -214,6 +224,7 @@ export class MilkyWsEndpoint implements EndpointInstance {
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
     const target = formatInboundTarget(data);
     const content = formatInboundContent(data);
+    const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
@@ -221,6 +232,7 @@ export class MilkyWsEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target,
       content,
+      segments,
       sender: String(data.sender_id),
       id: formatInboundMessageId(data),
       metadata: Object.freeze({
@@ -244,7 +256,7 @@ export class MilkyWsEndpoint implements EndpointInstance {
     });
   }
 
-  async #connect(): Promise<void> {
+  async #connect(handle: EndpointConnectHandle): Promise<void> {
     const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
     const create = this.#options.createWebSocket
       ?? ((connectUrl: string, options: MilkyWsCreateOptions) =>
@@ -254,6 +266,13 @@ export class MilkyWsEndpoint implements EndpointInstance {
       let settled = false;
       const ws = create(url, { headers });
       this.#ws = ws;
+      handle.onForceClose(() => {
+        try {
+          ws.close();
+        } catch {
+          /* ignore */
+        }
+      });
 
       ws.on('open', () => {
         if (settled) return;
@@ -270,7 +289,16 @@ export class MilkyWsEndpoint implements EndpointInstance {
           mode: 'ws',
           url: safeUrl,
         }));
-        this.#startHeartbeat();
+        // stop-during-connect 竞态：已停止则不再武装心跳（基座 stop 已清理定时器）
+        if (this.#lifecycle.started) {
+          this.#lifecycle.startHeartbeat(() => {
+            try {
+              if (ws.readyState === WS_OPEN) ws.ping?.();
+            } catch {
+              /* ignore */
+            }
+          }, this.#options.config.heartbeat_interval);
+        }
         resolve();
       });
 
@@ -297,11 +325,12 @@ export class MilkyWsEndpoint implements EndpointInstance {
           error: `${reasonStr || 'closed'}${codeHint}`,
           reconnect_ms: this.#options.config.reconnect_interval,
         }));
+        // 基座语义：仅曾 open 的连接才武装重连；初始连接失败由 start() 的 catch 复位
+        handle.notifyClosed(new Error(`Milky WS 关闭: ${codeNum} ${reasonStr}`));
         if (!settled) {
           settled = true;
           reject(new Error(`Milky WS 关闭: ${codeNum} ${reasonStr}`));
         }
-        this.#scheduleReconnect();
       });
 
       ws.on('error', (err) => {
@@ -339,35 +368,4 @@ export class MilkyWsEndpoint implements EndpointInstance {
       }));
     }
   }
-
-  #startHeartbeat(): void {
-    if (this.#heartbeatTimer) {
-      clearInterval(this.#heartbeatTimer);
-    }
-    const interval = this.#options.config.heartbeat_interval;
-    if (interval <= 0) return;
-    this.#heartbeatTimer = setInterval(() => {
-      try {
-        if (this.#ws?.readyState === WS_OPEN) this.#ws.ping?.();
-      } catch {
-        /* ignore */
-      }
-    }, interval);
-  }
-
-  #scheduleReconnect(): void {
-    if (this.#stopping || !this.#started || this.#reconnectTimer) return;
-    const delay = this.#options.config.reconnect_interval;
-    this.#reconnectTimer = setTimeout(() => {
-      this.#reconnectTimer = undefined;
-      void this.#connect().catch((err) => {
-        logger.warn(formatCompact({
-          op: 'reconnect',
-          endpoint: this.#options.config.name,
-          ok: false,
-          error: err instanceof Error ? err.message : String(err),
-        }));
-      });
-    }, delay);
-  }
 }

package/src/wss-endpoint.ts

@@ -2,12 +2,13 @@
  * Milky reverse WSS endpoint — httpHostToken WS upgrade inbound + baseUrl HTTP API outbound.
  */
 import { clearInterval } from 'node:timers';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { verifyMilkyAccessToken } from './milky-auth.js';
+import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
 import {
   buildSendAction,
@@ -15,6 +16,7 @@ import {
   extractInboundAudioUrl,
   formatInboundContent,
   formatInboundMessageId,
+  formatInboundSegments,
   formatInboundTarget,
   formatOutboundMessageId,
   formatOutboundSegments,
@@ -42,6 +44,7 @@ export interface MilkyWssEndpointOptions {
 export class MilkyWssEndpoint implements EndpointInstance {
   readonly #options: MilkyWssEndpointOptions;
   readonly #callApi: typeof callApi;
+  readonly management: EndpointManagement = createMilkyEndpointManagement(this);
   #ws?: MilkyWsSocket;
   #wsRelease?: () => void;
   #heartbeatTimer?: NodeJS.Timeout;
@@ -212,6 +215,7 @@ export class MilkyWssEndpoint implements EndpointInstance {
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
     const target = formatInboundTarget(data);
     const content = formatInboundContent(data);
+    const segments = formatInboundSegments(data);
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
@@ -219,6 +223,7 @@ export class MilkyWssEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target,
       content,
+      segments,
       sender: String(data.sender_id),
       id: formatInboundMessageId(data),
       metadata: Object.freeze({