@zhin.js/adapter-milky 5.0.0 → 5.0.1

package/lib/ws-endpoint.js

@@ -2,33 +2,48 @@
  * Milky WS client endpoint — outbound connect to Milky protocol server.
  */
 import WebSocket from 'ws';
-import { clearInterval, clearTimeout } from 'node:timers';
+import { createEndpointLifecycle, } from '@zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
-import { buildSendAction, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+import { buildSendAction, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 const logger = getLogger('milky');
 const WS_OPEN = 1;
 export class MilkyWsEndpoint {
     #options;
     #callApi;
+    management = createMilkyEndpointManagement(this);
+    #lifecycle;
     #ws;
-    #reconnectTimer;
-    #heartbeatTimer;
     #open = false;
-    #started = false;
-    #stopping = false;
     #unregisterAgent;
     constructor(options) {
         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() {
-        if (this.#started)
+        if (this.#lifecycle.started)
             return;
-        this.#started = true;
-        this.#stopping = false;
         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() {
         this.#open = true;
@@ -38,18 +53,9 @@ export class MilkyWsEndpoint {
     }
     async stop() {
         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();
@@ -59,7 +65,6 @@ export class MilkyWsEndpoint {
             }
             this.#ws = undefined;
         }
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
     async send({ target, payload }) {
         const message = formatOutboundSegments(payload);
@@ -165,6 +170,7 @@ export class MilkyWsEndpoint {
     #admitMessage(data, event) {
         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);
@@ -172,6 +178,7 @@ export class MilkyWsEndpoint {
             adapter: this.#options.id,
             target,
             content,
+            segments,
             sender: String(data.sender_id),
             id: formatInboundMessageId(data),
             metadata: Object.freeze({
@@ -194,7 +201,7 @@ export class MilkyWsEndpoint {
             }));
         });
     }
-    async #connect() {
+    async #connect(handle) {
         const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
         const create = this.#options.createWebSocket
             ?? ((connectUrl, options) => new WebSocket(connectUrl, { headers: options.headers }));
@@ -202,6 +209,14 @@ export class MilkyWsEndpoint {
             let settled = false;
             const ws = create(url, { headers });
             this.#ws = ws;
+            handle.onForceClose(() => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            });
             ws.on('open', () => {
                 if (settled)
                     return;
@@ -218,7 +233,18 @@ export class MilkyWsEndpoint {
                     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();
             });
             ws.on('message', (data) => {
@@ -243,11 +269,12 @@ export class MilkyWsEndpoint {
                     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) => {
                 const error = err instanceof Error ? err : new Error(String(err));
@@ -284,37 +311,4 @@ export class MilkyWsEndpoint {
             }));
         }
     }
-    #startHeartbeat() {
-        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() {
-        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/lib/wss-endpoint.d.ts

@@ -1,4 +1,4 @@
-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 } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -12,6 +12,7 @@ export interface MilkyWssEndpointOptions {
 }
 export declare class MilkyWssEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: MilkyWssEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/wss-endpoint.js

@@ -4,13 +4,15 @@
 import { clearInterval } from 'node:timers';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { verifyMilkyAccessToken } from './milky-auth.js';
+import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
-import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 const logger = getLogger('milky');
 const WS_OPEN = 1;
 export class MilkyWssEndpoint {
     #options;
     #callApi;
+    management = createMilkyEndpointManagement(this);
     #ws;
     #wsRelease;
     #heartbeatTimer;
@@ -166,6 +168,7 @@ export class MilkyWssEndpoint {
     #admitMessage(data, event) {
         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);
@@ -173,6 +176,7 @@ export class MilkyWssEndpoint {
             adapter: this.#options.id,
             target,
             content,
+            segments,
             sender: String(data.sender_id),
             id: formatInboundMessageId(data),
             metadata: Object.freeze({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-milky",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Zhin.js Milky adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -14,6 +14,7 @@
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -39,11 +40,12 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.0"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
@@ -51,16 +53,16 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.5",
-    "@zhin.js/host-http": "1.0.2"
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/host-http": "1.0.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/plugin-runtime": "1.1.0",
-    "zhin.js": "5.0.0",
-    "@zhin.js/agent": "1.0.5"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1",
+    "@zhin.js/agent": "1.0.6"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -95,6 +97,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,8 +1,14 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
+import { milkyRuntimeStateToken } from './src/milky-runtime-state.js';
 
 export default definePlugin({
   name: 'milky',
   metadata: {
     displayName: 'Milky Adapter',
   },
+  setup(context) {
+    // 运行中 endpoint 注册表（milky endpoint list 的"运行中"数据源）
+    context.resources.provide(milkyRuntimeStateToken, createEndpointRuntimeState());
+  },
 });

package/src/endpoint-management.ts

@@ -0,0 +1,74 @@
+/**
+ * Milky endpoint management 语义端口（Console 社交面 RPC 消费，见
+ * packages/im/adapter/src/endpoint-management.ts）。
+ *
+ * Milky 协议响应 data 为包裹对象：get_friend_list → {friends:[...]}、
+ * get_group_list → {groups:[...]}、get_group_member_list → {members:[...]}。
+ * 归一化取舍：
+ * - friend → {user_id:number, nickname, remark: remark ?? ''}
+ * - group → {group_id:number, name: group_name ?? name}
+ * - 群成员列表保持 Milky 原生形状，仅保证数组
+ */
+import type {
+  EndpointFriend,
+  EndpointGroup,
+  EndpointManagement,
+} from '@zhin.js/adapter';
+
+/** 管理面只依赖 endpoint 的 callApi（ws/wss/sse/webhook 四种传输各自实现）。 */
+export interface MilkyManagementCaller {
+  callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+export function createMilkyEndpointManagement(
+  endpoint: MilkyManagementCaller,
+): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    async listFriends(): Promise<readonly EndpointFriend[]> {
+      const data = asRecord(await endpoint.callApi('get_friend_list'));
+      return toArray(data.friends).map((value) => {
+        const friend = asRecord(value);
+        return {
+          user_id: toNumberId(friend.user_id, 'user_id'),
+          nickname: String(friend.nickname ?? ''),
+          remark: String(friend.remark ?? ''),
+        };
+      });
+    },
+    async listGroups(): Promise<readonly EndpointGroup[]> {
+      const data = asRecord(await endpoint.callApi('get_group_list'));
+      return toArray(data.groups).map((value) => {
+        const group = asRecord(value);
+        return {
+          group_id: toNumberId(group.group_id, 'group_id'),
+          name: String(group.group_name ?? group.name ?? ''),
+        };
+      });
+    },
+    async listGroupMembers(groupId: string): Promise<readonly unknown[]> {
+      const data = asRecord(await endpoint.callApi('get_group_member_list', {
+        group_id: toNumberId(groupId, 'group_id'),
+      }));
+      return toArray(data.members);
+    },
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function toArray(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value: unknown, label: string): number {
+  const n = Number(value);
+  if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+    throw new TypeError(`milky ${label} 必须是数字: ${String(value)}`);
+  }
+  return n;
+}

package/src/milky-endpoint-commands.ts

@@ -0,0 +1,19 @@
+/**
+ * `milky endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { milkyRuntimeStateToken } from './milky-runtime-state.js';
+
+export const milkyEndpointCommands = createEndpointCommands({
+  adapterKey: 'milky',
+  adapterDisplayName: 'Milky',
+  fields: [
+    { key: 'baseUrl', required: true, description: 'Milky HTTP API base URL' },
+    { key: 'path', description: 'webhook / reverse-wss 路径' },
+    { key: 'access_token', env: true, description: 'Milky access token' },
+  ],
+  running: (use) => use(milkyRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `baseUrl: ${String(entry.baseUrl)}`,
+}, defineCommand);

package/src/milky-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * Milky 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `milky endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
+
+export const milkyRuntimeStateToken = defineEndpointRuntimeStateToken('milky');

package/src/protocol.ts

@@ -4,6 +4,8 @@
  * Spec: https://milky.ntqqrev.org/
  */
 
+import type { Segment } from '@zhin.js/core/runtime';
+
 /** Transitional legacy endpoint row (`endpoints[]` with `context: milky`). */
 export interface MilkyLegacyEndpointRow {
   readonly context?: string;
@@ -272,6 +274,124 @@ export function formatInboundContent(data: MilkyIncomingMessage): string {
   }).join('');
 }
 
+function firstNonEmptyString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return undefined;
+}
+
+/**
+ * 入站消息段 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 媒体段（image/record/video）优先 temp_url（kind=url），缺 URL 时回退
+ * resource_id（kind=file，平台不透明引用，经协议端 get_resource 解析）；
+ * file 段只有 file_id（kind=file）。未识别段类型按宽松段透传，不丢信息。
+ */
+export function formatInboundSegments(data: MilkyIncomingMessage): Segment[] {
+  const out: Segment[] = [];
+  for (const seg of data.segments) {
+    const segData = seg.data ?? {};
+    switch (seg.type) {
+      case 'text': {
+        const text = String(segData.text ?? '');
+        if (text) out.push({ type: 'text', data: { text } });
+        break;
+      }
+      case 'mention':
+        out.push({
+          type: 'mention',
+          data: {
+            target: String(segData.user_id ?? ''),
+            ...(typeof segData.name === 'string' && segData.name
+              ? { name: segData.name }
+              : {}),
+          },
+        });
+        break;
+      case 'mention_all':
+        out.push({ type: 'mention', data: { target: 'all' } });
+        break;
+      case 'face': {
+        const id = firstNonEmptyString(segData.face_id, segData.id);
+        if (id) out.push({ type: 'face', data: { id } });
+        break;
+      }
+      case 'reply': {
+        const seq = Number(segData.message_seq);
+        if (Number.isFinite(seq)) {
+          // 与 formatInboundMessageId 同一复合格式，保证 reply 链可定位原消息
+          out.push({
+            type: 'reply',
+            data: { message_id: `${data.message_scene}:${data.peer_id}:${seq}` },
+          });
+        }
+        break;
+      }
+      case 'image':
+      case 'record':
+      case 'audio':
+      case 'video': {
+        const url = firstNonEmptyString(segData.temp_url, segData.uri, segData.url);
+        const resourceId = firstNonEmptyString(segData.resource_id);
+        if (!url && !resourceId) break;
+        const type = seg.type === 'image'
+          ? 'image'
+          : seg.type === 'video'
+            ? 'video'
+            : 'audio';
+        out.push({
+          type,
+          data: {
+            media: url
+              ? { kind: 'url', value: url }
+              : { kind: 'file', value: resourceId! },
+            ...(typeof segData.summary === 'string' && segData.summary
+              ? { alt: segData.summary }
+              : {}),
+          },
+        });
+        break;
+      }
+      case 'file': {
+        const fileId = firstNonEmptyString(segData.file_id);
+        if (!fileId) break;
+        out.push({
+          type: 'file',
+          data: {
+            media: { kind: 'file', value: fileId },
+            ...(typeof segData.file_name === 'string' && segData.file_name
+              ? { name: segData.file_name }
+              : {}),
+            ...(typeof segData.file_size === 'number'
+              ? { size: segData.file_size }
+              : {}),
+          },
+        });
+        break;
+      }
+      case 'forward': {
+        const forwardId = firstNonEmptyString(segData.forward_id);
+        if (forwardId) {
+          out.push({
+            type: 'forward',
+            data: {
+              forward_id: forwardId,
+              ...(typeof segData.title === 'string' && segData.title
+                ? { title: segData.title }
+                : {}),
+            },
+          });
+        }
+        break;
+      }
+      default:
+        // 未识别段（market_face / light_app / xml 等）按宽松 canonical 段透传
+        out.push({ type: seg.type, data: segData });
+    }
+  }
+  return out;
+}
+
 /** First audio URI from inbound segments (for Agent Host STT preprocess). */
 export function extractInboundAudioUrl(data: MilkyIncomingMessage): string | undefined {
   for (const seg of data.segments) {