@zhin.js/adapter-milky 7.0.0 → 7.0.1

package/src/ws-endpoint.ts

@@ -3,20 +3,24 @@
  */
 import WebSocket from 'ws';
 import {
+  ClientEndpoint,
   createRecallEndpointControl,
   createEndpointLifecycle,
   type EndpointConnectHandle,
   type EndpointControl,
-  type EndpointInstance,
   type EndpointLifecycle,
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
-import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
+import {
+  callMilkyClient,
+  createMilkyEndpointClient,
+  forwardMilkyClientEvents,
+  type MilkyClient,
+} from './client.js';
 import {
   buildSendAction,
   buildWsConnectOptions,
@@ -42,8 +46,6 @@ const WS_OPEN = 1;
 
 export interface MilkyWsEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly config: MilkyWsConfig;
   readonly createWebSocket?: (
     url: string,
@@ -52,22 +54,34 @@ export interface MilkyWsEndpointOptions {
   readonly callApi?: typeof callApi;
 }
 
-export class MilkyWsEndpoint implements EndpointInstance {
+export class MilkyWsEndpoint extends ClientEndpoint<MilkyClient> {
+  readonly client: MilkyClient;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: MilkyWsEndpointOptions;
   readonly #callApi: typeof callApi;
-  readonly management: EndpointManagement = createMilkyEndpointManagement(this);
+  readonly management: EndpointManagement;
   readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
   readonly #lifecycle: EndpointLifecycle;
   #ws?: MilkyWsSocket;
-  #open = false;
-  #unregisterAgent?: () => void;
+  #clientSocketRelease?: () => void;
 
   constructor(options: MilkyWsEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('milky', options.config.id);
     this.#options = options;
     this.#callApi = options.callApi ?? callApi;
+    this.client = createMilkyEndpointClient(options.config, this.#callApi);
+    this.management = createMilkyEndpointManagement({
+      callApi: (action, params) => callMilkyClient(this.client, action, params),
+    });
+    this.bindClientEvents(
+      (receive) => forwardMilkyClientEvents(this.client, receive),
+      (name, payload) => {
+        if (name === 'event') this.#admitRaw(payload as MilkyEvent);
+      },
+      (_name, error) => this.#warnPlatformEvent(error),
+    );
     this.#lifecycle = createEndpointLifecycle({
       name: options.config.id,
       // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
@@ -82,30 +96,18 @@ export class MilkyWsEndpoint implements EndpointInstance {
 
   async start(): Promise<void> {
     if (this.#lifecycle.started) return;
-    this.#unregisterAgent = registerMilkyAgentEndpoint(this.#options.config.id, this);
-    try {
-      await this.#lifecycle.start((handle) => this.#connect(handle));
-    } catch (err) {
-      // start 失败复位由基座保证；agent 注册/反注册是适配器专有依赖，留在适配器侧
-      this.#unregisterAgent?.();
-      this.#unregisterAgent = undefined;
-      throw err;
-    }
-  }
-
-  open(): void {
-    this.#open = true;
+    await this.#lifecycle.start((handle) => this.#connect(handle));
   }
 
   close(): void {
-    this.#open = false;
+    super.close();
+    this.#clientSocketRelease?.();
+    this.#clientSocketRelease = undefined;
   }
 
   async stop(): Promise<void> {
-    this.#open = false;
+    this.close();
     await this.#lifecycle.stop();
-    this.#unregisterAgent?.();
-    this.#unregisterAgent = undefined;
     if (this.#ws) {
       try {
         this.#ws.close();
@@ -119,7 +121,7 @@ export class MilkyWsEndpoint implements EndpointInstance {
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(conversation, message);
-    const data = await this.callApi(action, params) as { message_seq?: number } | undefined;
+    const data = await callMilkyClient<{ message_seq?: number }>(this.client, action, params);
     const messageId = formatOutboundMessageId(conversation, data?.message_seq);
     this.#logger.debug(formatCompact({
       op: 'milky_send',
@@ -130,102 +132,33 @@ export class MilkyWsEndpoint implements EndpointInstance {
     return messageId;
   }
 
-  /** Public API for agent tools / callers. */
-  callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
-    return this.#callApi(this.apiOptions(), action, params);
-  }
-
   async recallMessage(id: string): Promise<void> {
     const parsed = parseMilkyMessageId(id);
     if (!parsed) throw new Error(`Invalid message id: ${id}`);
     if (parsed.message_scene === 'group') {
-      await this.callApi('recall_group_message', {
+      await callMilkyClient(this.client, 'recall_group_message', {
         group_id: parsed.peer_id,
         message_seq: parsed.message_seq,
       });
     } else {
-      await this.callApi('recall_private_message', {
+      await callMilkyClient(this.client, 'recall_private_message', {
         user_id: parsed.peer_id,
         message_seq: parsed.message_seq,
       });
     }
   }
 
-  async kickMember(groupId: number, userId: number, rejectAddRequest = false): Promise<boolean> {
-    await this.callApi('kick_group_member', {
-      group_id: groupId,
-      user_id: userId,
-      reject_add_request: rejectAddRequest,
-    });
-    return true;
-  }
-
-  async muteMember(groupId: number, userId: number, duration = 600): Promise<boolean> {
-    await this.callApi('set_group_member_mute', {
-      group_id: groupId,
-      user_id: userId,
-      duration,
-    });
-    return true;
-  }
-
-  async muteAll(groupId: number, enable = true): Promise<boolean> {
-    await this.callApi('set_group_whole_mute', { group_id: groupId, is_mute: enable });
-    return true;
-  }
-
-  async setAdmin(groupId: number, userId: number, enable = true): Promise<boolean> {
-    await this.callApi('set_group_member_admin', {
-      group_id: groupId,
-      user_id: userId,
-      is_set: enable,
-    });
-    return true;
-  }
-
-  async setCard(groupId: number, userId: number, card: string): Promise<boolean> {
-    await this.callApi('set_group_member_card', {
-      group_id: groupId,
-      user_id: userId,
-      card,
-    });
-    return true;
-  }
-
-  async setTitle(groupId: number, userId: number, title: string): Promise<boolean> {
-    await this.callApi('set_group_member_special_title', {
-      group_id: groupId,
-      user_id: userId,
-      special_title: title,
-    });
-    return true;
-  }
-
-  async setGroupName(groupId: number, name: string): Promise<boolean> {
-    await this.callApi('set_group_name', { group_id: groupId, new_group_name: name });
-    return true;
-  }
-
-  async getMemberList(groupId: number): Promise<unknown[]> {
-    return this.callApi('get_group_member_list', { group_id: groupId }) as Promise<unknown[]>;
-  }
-
-  async getGroupInfo(groupId: number): Promise<unknown> {
-    return this.callApi('get_group_info', { group_id: groupId });
-  }
-
-  /** Test / internal: admit a parsed event when the endpoint is open. */
-  admit(event: MilkyEvent): void {
+  #admitRaw(event: MilkyEvent): void {
     const data = parseMessageReceiveData(event);
-    if (!this.#open || !data) return;
+    if (!data) return;
     this.#admitMessage(data, event);
   }
 
-  apiOptions(): { baseUrl: string; access_token?: string } {
-    return {
-      baseUrl: this.#options.config.baseUrl,
-      access_token: this.#options.config.access_token,
-    };
+  #warnPlatformEvent(error: unknown): void {
+    this.#logger.warn(formatCompact({
+      op: 'milky_platform_event_failed',
+      error: error instanceof Error ? error.message : String(error),
+    }));
   }
 
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
@@ -236,7 +169,7 @@ export class MilkyWsEndpoint implements EndpointInstance {
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: formatInboundMessageId(data) },
       content,
@@ -308,11 +241,12 @@ export class MilkyWsEndpoint implements EndpointInstance {
         resolve();
       });
 
-      ws.on('message', (data) => {
-        this.#onMessage(data);
-      });
+      this.#clientSocketRelease?.();
+      this.#clientSocketRelease = this.client.acceptWebSocket(ws);
 
       ws.on('close', (code, reason) => {
+        this.#clientSocketRelease?.();
+        this.#clientSocketRelease = undefined;
         const reasonStr = typeof reason === 'string'
           ? reason
           : Buffer.isBuffer(reason)
@@ -354,23 +288,4 @@ export class MilkyWsEndpoint implements EndpointInstance {
     });
   }
 
-  #onMessage(data: unknown): void {
-    try {
-      const raw = typeof data === 'string'
-        ? data
-        : Buffer.isBuffer(data)
-          ? data.toString()
-          : data instanceof ArrayBuffer
-            ? new TextDecoder().decode(data)
-            : String(data ?? '');
-      const event = JSON.parse(raw) as MilkyEvent;
-      this.admit(event);
-    } catch (error) {
-      this.#logger.warn(formatCompact({
-        op: 'milky_parse_failed',
-        endpoint: this.#options.config.id,
-        error: error instanceof Error ? error.message : String(error),
-      }));
-    }
-  }
 }

package/src/wss-endpoint.ts

@@ -1,21 +1,21 @@
 /**
  * Milky reverse WSS endpoint — httpHostToken WS upgrade inbound + baseUrl HTTP API outbound.
  */
-import { clearInterval } from 'node:timers';
 import {
+  ClientEndpoint,
+  createEndpointLifecycle,
   createRecallEndpointControl,
+  type EndpointLifecycle,
   type EndpointControl,
-  type EndpointInstance,
   type EndpointManagement,
   type EndpointSendRequest,
 } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { verifyMilkyAccessToken } from './milky-auth.js';
 import { createMilkyEndpointManagement } from './endpoint-management.js';
-import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
+import { callMilkyClient, createMilkyEndpointClient, forwardMilkyClientEvents, type MilkyClient } from './client.js';
 import {
   buildSendAction,
   callApi,
@@ -40,40 +40,65 @@ const WS_OPEN = 1;
 
 export interface MilkyWssEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly config: MilkyWssConfig;
   readonly callApi?: typeof callApi;
 }
 
-export class MilkyWssEndpoint implements EndpointInstance {
+export class MilkyWssEndpoint extends ClientEndpoint<MilkyClient> {
+  readonly client: MilkyClient;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: MilkyWssEndpointOptions;
   readonly #callApi: typeof callApi;
-  readonly management: EndpointManagement = createMilkyEndpointManagement(this);
+  readonly management: EndpointManagement;
   readonly control: EndpointControl = createRecallEndpointControl((id) => this.recallMessage(id));
   #ws?: MilkyWsSocket;
   #wsRelease?: () => void;
-  #heartbeatTimer?: NodeJS.Timeout;
-  #open = false;
-  #started = false;
-  #unregisterAgent?: () => void;
+  #clientSocketRelease?: () => void;
+  readonly #lifecycle: EndpointLifecycle;
 
   constructor(options: MilkyWssEndpointOptions) {
+    super();
     this.#logger = getAdapterLogger('milky', options.config.id);
     this.#options = options;
     this.#callApi = options.callApi ?? callApi;
+    this.#lifecycle = createEndpointLifecycle({
+      name: options.config.id,
+      reconnect: false,
+      heartbeat: { intervalMs: options.config.heartbeat_interval },
+    });
+    this.client = createMilkyEndpointClient(options.config, this.#callApi);
+    this.management = createMilkyEndpointManagement({
+      callApi: (action, params) => callMilkyClient(this.client, action, params),
+    });
+    this.bindClientEvents(
+      (receive) => forwardMilkyClientEvents(this.client, receive),
+      (name, payload) => {
+        if (name === 'event') this.#admitRaw(payload as MilkyEvent);
+      },
+      (_name, error) => this.#warnPlatformEvent(error),
+    );
   }
 
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
-    this.#unregisterAgent = registerMilkyAgentEndpoint(this.#options.config.id, this);
-    const handle = this.#options.http.ws(this.#options.config.path);
-    this.#wsRelease = handle.onConnection((connection) => {
-      this.#acceptConnection(connection);
+    await this.#lifecycle.start(async (lifecycleHandle) => {
+      const handle = this.#options.http.ws(this.#options.config.path);
+      this.#wsRelease = handle.onConnection((connection) => {
+        this.#acceptConnection(connection);
+      });
+      lifecycleHandle.onForceClose(() => {
+        this.#wsRelease?.();
+        this.#wsRelease = undefined;
+        this.#clientSocketRelease?.();
+        this.#clientSocketRelease = undefined;
+        try {
+          this.#ws?.close();
+        } catch {
+          /* ignore */
+        }
+        this.#ws = undefined;
+      });
     });
     this.#logger.info(formatCompact({
       op: 'listen',
@@ -83,39 +108,15 @@ export class MilkyWssEndpoint implements EndpointInstance {
     }));
   }
 
-  open(): void {
-    this.#open = true;
-  }
-
-  close(): void {
-    this.#open = false;
-  }
-
   async stop(): Promise<void> {
-    this.#open = false;
-    this.#unregisterAgent?.();
-    this.#unregisterAgent = undefined;
-    this.#wsRelease?.();
-    this.#wsRelease = undefined;
-    if (this.#heartbeatTimer) {
-      clearInterval(this.#heartbeatTimer);
-      this.#heartbeatTimer = undefined;
-    }
-    if (this.#ws) {
-      try {
-        this.#ws.close();
-      } catch {
-        /* ignore */
-      }
-      this.#ws = undefined;
-    }
-    this.#started = false;
+    this.close();
+    await this.#lifecycle.stop();
   }
 
   async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const message = formatOutboundSegments(payload);
     const { action, params } = buildSendAction(conversation, message);
-    const data = await this.callApi(action, params) as { message_seq?: number } | undefined;
+    const data = await callMilkyClient<{ message_seq?: number }>(this.client, action, params);
     const messageId = formatOutboundMessageId(conversation, data?.message_seq);
     this.#logger.debug(formatCompact({
       op: 'milky_send',
@@ -126,100 +127,30 @@ export class MilkyWssEndpoint implements EndpointInstance {
     return messageId;
   }
 
-  callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
-    return this.#callApi(this.apiOptions(), action, params);
-  }
-
   async recallMessage(id: string): Promise<void> {
     const parsed = parseMilkyMessageId(id);
     if (!parsed) throw new Error(`Invalid message id: ${id}`);
     if (parsed.message_scene === 'group') {
-      await this.callApi('recall_group_message', {
+      await callMilkyClient(this.client, 'recall_group_message', {
         group_id: parsed.peer_id,
         message_seq: parsed.message_seq,
       });
     } else {
-      await this.callApi('recall_private_message', {
+      await callMilkyClient(this.client, 'recall_private_message', {
         user_id: parsed.peer_id,
         message_seq: parsed.message_seq,
       });
     }
   }
 
-  async kickMember(groupId: number, userId: number, rejectAddRequest = false): Promise<boolean> {
-    await this.callApi('kick_group_member', {
-      group_id: groupId,
-      user_id: userId,
-      reject_add_request: rejectAddRequest,
-    });
-    return true;
-  }
-
-  async muteMember(groupId: number, userId: number, duration = 600): Promise<boolean> {
-    await this.callApi('set_group_member_mute', {
-      group_id: groupId,
-      user_id: userId,
-      duration,
-    });
-    return true;
-  }
-
-  async muteAll(groupId: number, enable = true): Promise<boolean> {
-    await this.callApi('set_group_whole_mute', { group_id: groupId, is_mute: enable });
-    return true;
-  }
-
-  async setAdmin(groupId: number, userId: number, enable = true): Promise<boolean> {
-    await this.callApi('set_group_member_admin', {
-      group_id: groupId,
-      user_id: userId,
-      is_set: enable,
-    });
-    return true;
-  }
-
-  async setCard(groupId: number, userId: number, card: string): Promise<boolean> {
-    await this.callApi('set_group_member_card', {
-      group_id: groupId,
-      user_id: userId,
-      card,
-    });
-    return true;
-  }
-
-  async setTitle(groupId: number, userId: number, title: string): Promise<boolean> {
-    await this.callApi('set_group_member_special_title', {
-      group_id: groupId,
-      user_id: userId,
-      special_title: title,
-    });
-    return true;
-  }
-
-  async setGroupName(groupId: number, name: string): Promise<boolean> {
-    await this.callApi('set_group_name', { group_id: groupId, new_group_name: name });
-    return true;
-  }
-
-  async getMemberList(groupId: number): Promise<unknown[]> {
-    return this.callApi('get_group_member_list', { group_id: groupId }) as Promise<unknown[]>;
-  }
-
-  async getGroupInfo(groupId: number): Promise<unknown> {
-    return this.callApi('get_group_info', { group_id: groupId });
-  }
-
-  admit(event: MilkyEvent): void {
+  #admitRaw(event: MilkyEvent): void {
     const data = parseMessageReceiveData(event);
-    if (!this.#open || !data) return;
+    if (!data) return;
     this.#admitMessage(data, event);
   }
 
-  apiOptions(): { baseUrl: string; access_token?: string } {
-    return {
-      baseUrl: this.#options.config.baseUrl,
-      access_token: this.#options.config.access_token,
-    };
+  #warnPlatformEvent(error: unknown): void {
+    this.#logger.warn(formatCompact({ op: 'milky_platform_event_failed', error: error instanceof Error ? error.message : String(error) }));
   }
 
   #admitMessage(data: MilkyIncomingMessage, event: MilkyEvent): void {
@@ -230,7 +161,7 @@ export class MilkyWssEndpoint implements EndpointInstance {
     const audioUrl = extractInboundAudioUrl(data);
     const nickname = senderNickname(data);
     const mentioned = isMentioned(data, event.self_id);
-    void this.#options.gateway.receive({
+    void this.emit('message.receive', {
       conversation,
       message: { conversation, id: formatInboundMessageId(data) },
       content,
@@ -270,12 +201,22 @@ export class MilkyWssEndpoint implements EndpointInstance {
       }
     }
     this.#ws = socket;
-    this.#startHeartbeat();
-    socket.on('message', (data) => {
-      this.#onMessage(data);
+    this.#lifecycle.startHeartbeat(() => {
+      try {
+        if (this.#ws?.readyState === WS_OPEN) this.#ws.ping?.();
+      } catch {
+        /* ignore */
+      }
     });
+    this.#clientSocketRelease?.();
+    this.#clientSocketRelease = this.client.acceptWebSocket(socket);
     socket.on('close', () => {
-      if (this.#ws === socket) this.#ws = undefined;
+      this.#clientSocketRelease?.();
+      this.#clientSocketRelease = undefined;
+      if (this.#ws === socket) {
+        this.#ws = undefined;
+        this.#lifecycle.stopHeartbeat();
+      }
     });
     this.#logger.debug(formatCompact({
       endpoint: this.#options.config.id,
@@ -284,36 +225,4 @@ export class MilkyWssEndpoint implements EndpointInstance {
     }));
   }
 
-  #onMessage(data: unknown): void {
-    try {
-      const raw = typeof data === 'string'
-        ? data
-        : Buffer.isBuffer(data)
-          ? data.toString()
-          : data instanceof ArrayBuffer
-            ? new TextDecoder().decode(data)
-            : String(data ?? '');
-      const event = JSON.parse(raw) as MilkyEvent;
-      this.admit(event);
-    } catch (error) {
-      this.#logger.warn(formatCompact({
-        op: 'milky_parse_failed',
-        endpoint: this.#options.config.id,
-        error: error instanceof Error ? error.message : String(error),
-      }));
-    }
-  }
-
-  #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);
-  }
 }

package/lib/milky-agent-deps.d.ts

@@ -1,24 +0,0 @@
-/**
- * Agent tool deps for milky (scene management / callApi).
- * Endpoints register themselves on start; tools look up by config name / endpoint id.
- */
-export interface MilkyAgentEndpoint {
-    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
-    kickMember(groupId: number, userId: number, rejectAddRequest?: boolean): Promise<boolean>;
-    muteMember(groupId: number, userId: number, duration?: number): Promise<boolean>;
-    muteAll(groupId: number, enable?: boolean): Promise<boolean>;
-    setAdmin(groupId: number, userId: number, enable?: boolean): Promise<boolean>;
-    setCard(groupId: number, userId: number, card: string): Promise<boolean>;
-    setTitle(groupId: number, userId: number, title: string): Promise<boolean>;
-    setGroupName(groupId: number, name: string): Promise<boolean>;
-    getMemberList(groupId: number): Promise<unknown[]>;
-    getGroupInfo(groupId: number): Promise<unknown>;
-    recallMessage?(id: string): Promise<void>;
-}
-export interface MilkyAgentDeps {
-    getEndpoint: (endpointKey: string) => MilkyAgentEndpoint;
-}
-export declare function registerMilkyAgentEndpoint(endpointKey: string, endpoint: MilkyAgentEndpoint): () => void;
-/** Optional override used by tests / transitional callers. Pass `null` to clear. */
-export declare function setMilkyAgentDeps(deps: MilkyAgentDeps | null): void;
-export declare function getMilkyAgentDeps(): MilkyAgentDeps;

package/lib/milky-agent-deps.js

@@ -1,30 +0,0 @@
-/**
- * Agent tool deps for milky (scene management / callApi).
- * Endpoints register themselves on start; tools look up by config name / endpoint id.
- */
-const endpoints = new Map();
-let override = null;
-export function registerMilkyAgentEndpoint(endpointKey, endpoint) {
-    endpoints.set(endpointKey, endpoint);
-    return () => {
-        if (endpoints.get(endpointKey) === endpoint) {
-            endpoints.delete(endpointKey);
-        }
-    };
-}
-/** Optional override used by tests / transitional callers. Pass `null` to clear. */
-export function setMilkyAgentDeps(deps) {
-    override = deps;
-}
-export function getMilkyAgentDeps() {
-    if (override)
-        return override;
-    return {
-        getEndpoint(endpointKey) {
-            const registered = endpoints.get(endpointKey);
-            if (!registered)
-                throw new Error(`Endpoint ${endpointKey} 不存在`);
-            return registered;
-        },
-    };
-}