@zhin.js/adapter-milky 1.0.0 → 1.1.0

package/lib/ws-endpoint.js

@@ -0,0 +1,233 @@
+/**
+ * Milky WS client endpoint — outbound connect to Milky protocol server.
+ */
+import WebSocket from 'ws';
+import { ClientEndpoint, createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { createMilkyEndpointManagement } from './endpoint-management.js';
+import { callMilkyClient, createMilkyEndpointClient, forwardMilkyClientEvents, } from './client.js';
+import { buildSendAction, buildWsConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatOutboundMessageId, formatOutboundSegments, isMentioned, milkyInboundConversation, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+const WS_OPEN = 1;
+export class MilkyWsEndpoint extends ClientEndpoint {
+    client;
+    #logger;
+    #options;
+    #callApi;
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    #lifecycle;
+    #ws;
+    #clientSocketRelease;
+    constructor(options) {
+        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);
+        }, (_name, error) => this.#warnPlatformEvent(error));
+        this.#lifecycle = createEndpointLifecycle({
+            name: options.config.id,
+            // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
+            reconnect: {
+                initialIntervalMs: options.config.reconnect_interval,
+                multiplier: 1,
+                maxIntervalMs: Number.MAX_SAFE_INTEGER,
+                jitterMs: 0,
+            },
+        });
+    }
+    async start() {
+        if (this.#lifecycle.started)
+            return;
+        await this.#lifecycle.start((handle) => this.#connect(handle));
+    }
+    close() {
+        super.close();
+        this.#clientSocketRelease?.();
+        this.#clientSocketRelease = undefined;
+    }
+    async stop() {
+        this.close();
+        await this.#lifecycle.stop();
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#ws = undefined;
+        }
+    }
+    async send({ conversation, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(conversation, message);
+        const data = await callMilkyClient(this.client, action, params);
+        const messageId = formatOutboundMessageId(conversation, data?.message_seq);
+        this.#logger.debug(formatCompact({
+            op: 'milky_send',
+            endpoint: this.#options.config.id,
+            target: `${conversation.kind}:${conversation.id}`,
+            messageId,
+        }));
+        return messageId;
+    }
+    async recallMessage(id) {
+        const parsed = parseMilkyMessageId(id);
+        if (!parsed)
+            throw new Error(`Invalid message id: ${id}`);
+        if (parsed.message_scene === 'group') {
+            await callMilkyClient(this.client, 'recall_group_message', {
+                group_id: parsed.peer_id,
+                message_seq: parsed.message_seq,
+            });
+        }
+        else {
+            await callMilkyClient(this.client, 'recall_private_message', {
+                user_id: parsed.peer_id,
+                message_seq: parsed.message_seq,
+            });
+        }
+    }
+    #admitRaw(event) {
+        const data = parseMessageReceiveData(event);
+        if (!data)
+            return;
+        this.#admitMessage(data, event);
+    }
+    #warnPlatformEvent(error) {
+        this.#logger.warn(formatCompact({
+            op: 'milky_platform_event_failed',
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
+    #admitMessage(data, event) {
+        const conversation = milkyInboundConversation(String(this.#options.id), data);
+        const target = `${conversation.kind}:${conversation.id}`;
+        const content = formatInboundContent(data);
+        const segments = formatInboundSegments(data);
+        const audioUrl = extractInboundAudioUrl(data);
+        const nickname = senderNickname(data);
+        const mentioned = isMentioned(data, event.self_id);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: formatInboundMessageId(data) },
+            content,
+            segments,
+            sender: { id: String(data.sender_id), name: nickname },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                message_scene: data.message_scene,
+                peer_id: String(data.peer_id),
+                sender_id: String(data.sender_id),
+                message_seq: data.message_seq,
+                time: data.time ?? event.time,
+                self_id: event.self_id != null ? String(event.self_id) : undefined,
+                ...(nickname ? { nickname } : {}),
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'milky_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async #connect(handle) {
+        const { url, headers, safeUrl } = buildWsConnectOptions(this.#options.config);
+        const create = this.#options.createWebSocket
+            ?? ((connectUrl, options) => new WebSocket(connectUrl, { headers: options.headers }));
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const ws = create(url, { headers });
+            this.#ws = ws;
+            handle.onForceClose(() => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            });
+            ws.on('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (!this.#options.config.access_token) {
+                    this.#logger.warn(formatCompact({
+                        endpoint: this.#options.config.id,
+                        ok: false,
+                        error: 'missing access_token',
+                    }));
+                }
+                this.#logger.debug(formatCompact({
+                    endpoint: this.#options.config.id,
+                    mode: 'ws',
+                    url: safeUrl,
+                }));
+                // 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();
+            });
+            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)
+                        ? reason.toString()
+                        : String(reason ?? '');
+                const codeNum = typeof code === 'number' ? code : Number(code ?? 0);
+                const codeHint = codeNum === 1005
+                    ? ' [无状态，多为服务端/代理未发 close 帧即断开]'
+                    : codeNum === 1006
+                        ? ' [异常关闭]'
+                        : '';
+                this.#logger.warn(formatCompact({
+                    op: 'disconnect',
+                    code: codeNum,
+                    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}`));
+                }
+            });
+            ws.on('error', (err) => {
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.#logger.warn(formatCompact({
+                    op: 'ws_error',
+                    endpoint: this.#options.config.id,
+                    ok: false,
+                    error: error.message,
+                }));
+                if (!settled) {
+                    settled = true;
+                    reject(error);
+                }
+            });
+        });
+    }
+}

package/lib/ws-types.d.ts

@@ -0,0 +1,11 @@
+/** Minimal WS surface used by the endpoint (real `ws` or test mock). */
+export interface MilkyWsSocket {
+    readonly readyState: number;
+    send?(data: string): void;
+    close(code?: number, reason?: string): void;
+    ping?(): void;
+    on(event: 'open' | 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+}
+export interface MilkyWsCreateOptions {
+    readonly headers?: Record<string, string>;
+}

package/lib/ws-types.js

@@ -0,0 +1 @@
+export {};

package/lib/wss-endpoint.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Milky reverse WSS endpoint — httpHostToken WS upgrade inbound + baseUrl HTTP API outbound.
+ */
+import { ClientEndpoint, 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 MilkyClient } from './client.js';
+import { callApi, type MilkyWssConfig } from './protocol.js';
+export interface MilkyWssEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: MilkyWssConfig;
+    readonly callApi?: typeof callApi;
+}
+export declare class MilkyWssEndpoint extends ClientEndpoint<MilkyClient> {
+    #private;
+    readonly client: MilkyClient;
+    readonly management: EndpointManagement;
+    readonly control: EndpointControl;
+    constructor(options: MilkyWssEndpointOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(id: string): Promise<void>;
+}

package/lib/wss-endpoint.js

@@ -0,0 +1,184 @@
+/**
+ * Milky reverse WSS endpoint — httpHostToken WS upgrade inbound + baseUrl HTTP API outbound.
+ */
+import { ClientEndpoint, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { verifyMilkyAccessToken } from './milky-auth.js';
+import { createMilkyEndpointManagement } from './endpoint-management.js';
+import { callMilkyClient, createMilkyEndpointClient, forwardMilkyClientEvents } from './client.js';
+import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatOutboundMessageId, formatOutboundSegments, isMentioned, milkyInboundConversation, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+const WS_OPEN = 1;
+export class MilkyWssEndpoint extends ClientEndpoint {
+    client;
+    #logger;
+    #options;
+    #callApi;
+    management;
+    control = createRecallEndpointControl((id) => this.recallMessage(id));
+    #ws;
+    #wsRelease;
+    #clientSocketRelease;
+    #lifecycle;
+    constructor(options) {
+        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);
+        }, (_name, error) => this.#warnPlatformEvent(error));
+    }
+    async start() {
+        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',
+            endpoint: this.#options.config.id,
+            mode: 'wss',
+            path: this.#options.config.path,
+        }));
+    }
+    async stop() {
+        this.close();
+        await this.#lifecycle.stop();
+    }
+    async send({ conversation, payload }) {
+        const message = formatOutboundSegments(payload);
+        const { action, params } = buildSendAction(conversation, message);
+        const data = await callMilkyClient(this.client, action, params);
+        const messageId = formatOutboundMessageId(conversation, data?.message_seq);
+        this.#logger.debug(formatCompact({
+            op: 'milky_send',
+            endpoint: this.#options.config.id,
+            target: `${conversation.kind}:${conversation.id}`,
+            messageId,
+        }));
+        return messageId;
+    }
+    async recallMessage(id) {
+        const parsed = parseMilkyMessageId(id);
+        if (!parsed)
+            throw new Error(`Invalid message id: ${id}`);
+        if (parsed.message_scene === 'group') {
+            await callMilkyClient(this.client, 'recall_group_message', {
+                group_id: parsed.peer_id,
+                message_seq: parsed.message_seq,
+            });
+        }
+        else {
+            await callMilkyClient(this.client, 'recall_private_message', {
+                user_id: parsed.peer_id,
+                message_seq: parsed.message_seq,
+            });
+        }
+    }
+    #admitRaw(event) {
+        const data = parseMessageReceiveData(event);
+        if (!data)
+            return;
+        this.#admitMessage(data, event);
+    }
+    #warnPlatformEvent(error) {
+        this.#logger.warn(formatCompact({ op: 'milky_platform_event_failed', error: error instanceof Error ? error.message : String(error) }));
+    }
+    #admitMessage(data, event) {
+        const conversation = milkyInboundConversation(String(this.#options.id), data);
+        const target = `${conversation.kind}:${conversation.id}`;
+        const content = formatInboundContent(data);
+        const segments = formatInboundSegments(data);
+        const audioUrl = extractInboundAudioUrl(data);
+        const nickname = senderNickname(data);
+        const mentioned = isMentioned(data, event.self_id);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: formatInboundMessageId(data) },
+            content,
+            segments,
+            sender: { id: String(data.sender_id) },
+            endpointId: this.#options.config.id,
+            ...(mentioned ? { mentioned: true } : {}),
+            metadata: Object.freeze({
+                message_scene: data.message_scene,
+                peer_id: String(data.peer_id),
+                sender_id: String(data.sender_id),
+                message_seq: data.message_seq,
+                time: data.time ?? event.time,
+                self_id: event.self_id != null ? String(event.self_id) : undefined,
+                ...(nickname ? { nickname } : {}),
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'milky_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    #acceptConnection(connection) {
+        if (!verifyMilkyAccessToken(this.#options.config.access_token, connection.request)) {
+            connection.socket.close(4003, 'Unauthorized');
+            return;
+        }
+        const socket = connection.socket;
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.#ws = socket;
+        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', () => {
+            this.#clientSocketRelease?.();
+            this.#clientSocketRelease = undefined;
+            if (this.#ws === socket) {
+                this.#ws = undefined;
+                this.#lifecycle.stopHeartbeat();
+            }
+        });
+        this.#logger.debug(formatCompact({
+            endpoint: this.#options.config.id,
+            mode: 'wss',
+            peer: connection.request.socket.remoteAddress,
+        }));
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-milky",
-  "version": "1.0.0",
-  "description": "Zhin.js adapter for Milky protocol",
+  "version": "1.1.0",
+  "description": "Zhin.js Milky adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,13 +13,15 @@
     }
   },
   "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
-    "client",
-    "dist",
-    "skills",
-    "plugin.yml",
-    "README.md"
+    "agent",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "zhin",
@@ -37,29 +39,81 @@
     "directory": "plugins/adapters/milky"
   },
   "dependencies": {
-    "eventsource": "^2.0.2",
-    "ws": "^8.21.0"
+    "@imhelper/milky-v1": "1.0.7",
+    "imhelper": "1.0.7",
+    "ws": "^8.21.1",
+    "@zhin.js/adapter": "1.1.12",
+    "@zhin.js/core": "1.1.35",
+    "@zhin.js/feature-kit": "1.1.0",
+    "@zhin.js/host-http": "1.1.0",
+    "@zhin.js/im-contract": "1.1.0",
+    "@zhin.js/logger": "1.1.0"
   },
   "devDependencies": {
-    "@types/eventsource": "^1.1.15",
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.88",
-    "@zhin.js/client": "2.0.2",
-    "zhin.js": "2.0.0"
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.1.23",
+    "@zhin.js/host-http": "1.1.0",
+    "zhin.js": "1.1.0"
   },
   "peerDependencies": {
-    "@zhin.js/host-router": "1.0.0",
-    "zhin.js": "2.0.0"
+    "zod": "^4.0.0",
+    "@zhin.js/adapter": "^1.1.12",
+    "@zhin.js/agent": "^1.1.23",
+    "@zhin.js/command": "^1.1.0",
+    "@zhin.js/core": "^1.1.35",
+    "zhin.js": "^1.1.0"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
+    "@zhin.js/agent": {
+      "optional": true
+    },
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "zhin.js": {
+      "optional": true
+    },
+    "zod": {
       "optional": true
     }
   },
+  "author": {
+    "name": "lc-cn",
+    "email": "admin@liucl.cn",
+    "url": "https://github.com/lc-cn"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "clean": "rimraf lib"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/milky/tests"
   }
 }

package/plugin.js

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