@zhin.js/adapter 1.0.1 → 1.1.1

package/lib/endpoint-lifecycle.js

@@ -0,0 +1,333 @@
+/**
+ * EndpointLifecycle — WS/SSE 长连接端点生命周期基座。
+ *
+ * 把 napcat / milky / onebot11·12 各自重复实现（且重复犯错）的状态机收敛为一处：
+ *
+ * 状态机：idle → connecting → open → reconnecting → open … → stopped / closed
+ *
+ * - start(connectFn)：连接失败自动复位回 idle 且不武装重连（start 的 catch 语义）；
+ *   stop-during-connect 竞态时 start() 静默 settle（视为主动停止，不抛错）。
+ * - stop()：主动断开，清全部定时器、调用已注册的强关函数、唤醒所有竞态等待，绝不重连。
+ * - handle.notifyClosed()：对端断开（ws close / SSE 流结束）时由适配器调用；
+ *   仅在连接曾 open 时才按指数退避 + jitter 武装重连，初始连接失败不武装。
+ * - startHeartbeat(fn, interval)：心跳 + 看门狗——连续 N 轮无回包（notifyHeartbeatAck
+ *   未复位计数）时主动调用 onForceClose 注册的强关函数，由底层 close 事件驱动重连。
+ * - 定时器集中管理：重连 timer 与心跳 timer 均在 close / stop / 看门狗触发时清理。
+ *
+ * 防叠套：重连循环单例（#reconnectRunning），且每次 connect 尝试递增 generation，
+ * 陈旧连接句柄的 notifyClosed / onForceClose 一律忽略。
+ *
+ * 迁移指引（以 napcat/milky/onebot WS endpoint 为例）：
+ * 1. 删除 #started / #stopping / #reconnectTimer / #heartbeatTimer / opened 旗标，
+ *    构造器里 `this.#lifecycle = createEndpointLifecycle({ name: config.name, reconnect, heartbeat })`。
+ * 2. `start()` 改为：
+ *    ```ts
+ *    this.#unregisterAgent = registerXxxAgentEndpoint(name, this); // agent 注册仍在适配器侧
+ *    try {
+ *      await this.#lifecycle.start(async (handle) => {
+ *        this.#handle = handle; // 供 ws 'close' 回调引用
+ *        await new Promise<void>((resolve, reject) => {
+ *          const ws = createWebSocket(...); this.#ws = ws;
+ *          ws.on('open', () => { this.#lifecycle.startHeartbeat(() => beat(), interval); resolve(); });
+ *          ws.on('close', (code, reason) => { handle.notifyClosed(...); rejectIfNotSettled(...); });
+ *          ws.on('error', (err) => rejectIfNotSettled(err));
+ *        });
+ *      });
+ *    } catch (err) {
+ *      this.#unregisterAgent?.(); this.#unregisterAgent = undefined; // 反注册对称
+ *      throw err;
+ *    }
+ *    ```
+ *    start 失败复位由基座保证；agent 注册/反注册是适配器专有依赖，刻意不收入基座。
+ * 3. `stop()` 改为：先 `await this.#lifecycle.stop()`（清定时器 + 强关 ws + 竞态 settle），
+ *    再做适配器专有清理（rejectAllPending、deduper.clear、agent 反注册）。
+ * 4. `handle.onForceClose(() => this.#ws?.close())` 在每次拿到新 socket 后注册，
+ *    供心跳看门狗主动断开；ws 'message'/'pong' 回调里调 `notifyHeartbeatAck()` 喂狗。
+ * 5. 退避参数由配置映射：reconnect_interval → initialIntervalMs，可按需覆盖
+ *    multiplier / maxIntervalMs / jitterMs / maxAttempts；重连成功后退避自动复位。
+ */
+// 使用全局定时器（而非 node:timers 导入）：vitest fake timers 只接管全局绑定，
+// 这样单测可用 vi.useFakeTimers 驱动退避/心跳。
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('adapter');
+const DEFAULT_RECONNECT = {
+    initialIntervalMs: 5_000,
+    multiplier: 2,
+    maxIntervalMs: 60_000,
+    jitterMs: 250,
+    maxAttempts: Number.POSITIVE_INFINITY,
+};
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+class EndpointLifecycleImpl {
+    #name;
+    #reconnect;
+    #heartbeat;
+    #random;
+    #state = 'idle';
+    #connect;
+    /** 每次 connect 尝试 +1，识别陈旧句柄。 */
+    #generation = 0;
+    /** 连续重连失败计数，open 成功后复位。 */
+    #attempt = 0;
+    /** 重连循环单例旗标（防叠套）。 */
+    #reconnectRunning = false;
+    #reconnectTimer;
+    #reconnectWake;
+    #heartbeatTimer;
+    #heartbeatMisses = 0;
+    #forceClose;
+    /** stop() 时唤醒的竞态等待（start / 重连中的 connect 尝试）。 */
+    #stopWaiters = [];
+    constructor(options) {
+        this.#name = options.name;
+        this.#reconnect = options.reconnect === false
+            ? false
+            : { ...DEFAULT_RECONNECT, ...options.reconnect };
+        this.#heartbeat = {
+            intervalMs: options.heartbeat?.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+            watchdogMisses: options.heartbeat?.watchdogMisses ?? 0,
+        };
+        this.#random = options.random ?? Math.random;
+    }
+    get state() {
+        return this.#state;
+    }
+    /**
+     * 并发安全的状态读取：stop() 可能在任意 await 点并发改写 #state，
+     * 经方法调用读取可避免 TS 对字段/getter 的控制流窄化误判（TS2367）。
+     */
+    #currentState() {
+        return this.#state;
+    }
+    get started() {
+        return this.#state === 'connecting' || this.#state === 'open' || this.#state === 'reconnecting';
+    }
+    async start(connect) {
+        if (this.started)
+            return;
+        this.#connect = connect;
+        this.#state = 'connecting';
+        this.#attempt = 0;
+        try {
+            await this.#runConnect(connect);
+        }
+        catch (err) {
+            // 注意：stop() 可能在 await 期间并发改写 #state，必须经 getter 读取避免 TS 窄化误判
+            if (this.#currentState() === 'stopped')
+                return; // stop-during-connect 竞态：静默 settle
+            // start 失败复位：回 idle、不武装重连，允许调用方重试
+            this.#state = 'idle';
+            throw err;
+        }
+        if (this.#currentState() === 'stopped')
+            return; // stop 竞态先于 open
+        this.#state = 'open';
+    }
+    async stop() {
+        const wasActive = this.#state !== 'stopped';
+        this.#state = 'stopped';
+        this.#attempt = 0;
+        this.stopHeartbeat();
+        if (this.#reconnectTimer) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = undefined;
+        }
+        this.#reconnectWake?.(false);
+        this.#reconnectWake = undefined;
+        for (const wake of this.#stopWaiters.splice(0))
+            wake();
+        const close = this.#forceClose;
+        this.#forceClose = undefined;
+        if (close) {
+            try {
+                close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        if (wasActive) {
+            logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#name }));
+        }
+    }
+    startHeartbeat(beat, intervalMs = this.#heartbeat.intervalMs) {
+        this.stopHeartbeat();
+        if (intervalMs <= 0)
+            return;
+        const watchdogMisses = this.#heartbeat.watchdogMisses;
+        this.#heartbeatMisses = 0;
+        this.#heartbeatTimer = setInterval(() => {
+            if (watchdogMisses > 0) {
+                this.#heartbeatMisses += 1;
+                if (this.#heartbeatMisses > watchdogMisses) {
+                    this.stopHeartbeat();
+                    logger.warn(formatCompact({
+                        op: 'heartbeat_watchdog',
+                        endpoint: this.#name,
+                        ok: false,
+                        misses: this.#heartbeatMisses,
+                    }));
+                    const close = this.#forceClose;
+                    if (close) {
+                        try {
+                            close();
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                    }
+                    return;
+                }
+            }
+            try {
+                beat();
+            }
+            catch (err) {
+                logger.warn(formatCompact({
+                    op: 'heartbeat',
+                    endpoint: this.#name,
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+            }
+        }, intervalMs);
+    }
+    stopHeartbeat() {
+        if (this.#heartbeatTimer) {
+            clearInterval(this.#heartbeatTimer);
+            this.#heartbeatTimer = undefined;
+        }
+        this.#heartbeatMisses = 0;
+    }
+    notifyHeartbeatAck() {
+        this.#heartbeatMisses = 0;
+    }
+    #createHandle(generation) {
+        return {
+            notifyClosed: (reason) => {
+                if (generation !== this.#generation)
+                    return; // 陈旧连接的迟到事件
+                this.#forceClose = undefined;
+                this.stopHeartbeat(); // close 清心跳
+                // 仅曾 open 的连接才武装重连；初始连接失败由 start() 的 catch 复位
+                if (this.#state !== 'open')
+                    return;
+                logger.warn(formatCompact({
+                    op: 'disconnect',
+                    endpoint: this.#name,
+                    ok: false,
+                    error: reason instanceof Error ? reason.message : reason != null ? String(reason) : 'closed',
+                }));
+                if (!this.#reconnect) {
+                    this.#state = 'closed';
+                    return;
+                }
+                this.#state = 'reconnecting';
+                this.#scheduleReconnect();
+            },
+            onForceClose: (close) => {
+                if (generation === this.#generation)
+                    this.#forceClose = close;
+            },
+        };
+    }
+    /** 跑一次 connect 尝试；与 stop 信号竞态，stop 先到则静默返回。 */
+    async #runConnect(connect) {
+        const generation = ++this.#generation;
+        this.#forceClose = undefined;
+        const handle = this.#createHandle(generation);
+        // Promise.resolve().then 兜底同步抛错；额外 catch 防止 stop 竞态后迟到拒绝变 unhandled
+        const connecting = Promise.resolve().then(() => connect(handle));
+        connecting.catch(() => { });
+        let wake;
+        const stopped = new Promise((resolve) => {
+            wake = resolve;
+        });
+        this.#stopWaiters.push(wake);
+        try {
+            await Promise.race([connecting, stopped]);
+        }
+        finally {
+            const index = this.#stopWaiters.indexOf(wake);
+            if (index >= 0)
+                this.#stopWaiters.splice(index, 1);
+        }
+    }
+    /** 武装重连循环（单例，防叠套）。 */
+    #scheduleReconnect() {
+        if (this.#reconnectRunning)
+            return;
+        this.#reconnectRunning = true;
+        void this.#reconnectLoop().finally(() => {
+            this.#reconnectRunning = false;
+        });
+    }
+    async #reconnectLoop() {
+        const config = this.#reconnect;
+        const connect = this.#connect;
+        if (!config || !connect)
+            return;
+        while (this.#state === 'reconnecting') {
+            if (this.#attempt >= config.maxAttempts) {
+                this.#state = 'closed';
+                logger.warn(formatCompact({
+                    op: 'reconnect',
+                    endpoint: this.#name,
+                    ok: false,
+                    error: `gave up after ${this.#attempt} attempts`,
+                }));
+                return;
+            }
+            const base = Math.min(config.initialIntervalMs * config.multiplier ** this.#attempt, config.maxIntervalMs);
+            const delay = base + Math.floor(this.#random() * config.jitterMs);
+            // 首次断开 WARN，后续重试静默为 DEBUG，避免刷屏（对齐 icqq）
+            const log = this.#attempt === 0 ? logger.warn.bind(logger) : logger.debug.bind(logger);
+            log(formatCompact({
+                op: 'reconnect',
+                endpoint: this.#name,
+                delay_ms: delay,
+                attempt: this.#attempt + 1,
+            }));
+            const elapsed = await this.#sleep(delay);
+            if (!elapsed || this.#currentState() !== 'reconnecting')
+                return;
+            try {
+                await this.#runConnect(connect);
+            }
+            catch (err) {
+                if (this.#currentState() === 'stopped')
+                    return;
+                this.#attempt += 1;
+                logger.debug(formatCompact({
+                    op: 'reconnect',
+                    endpoint: this.#name,
+                    ok: false,
+                    attempt: this.#attempt,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+                continue;
+            }
+            if (this.#currentState() === 'stopped')
+                return;
+            this.#state = 'open';
+            this.#attempt = 0;
+            logger.info(formatCompact({ op: 'reconnect', endpoint: this.#name, ok: true }));
+            return;
+        }
+    }
+    /** 可中断 sleep：stop() 唤醒并返回 false。 */
+    #sleep(ms) {
+        return new Promise((resolve) => {
+            this.#reconnectTimer = setTimeout(() => {
+                this.#reconnectTimer = undefined;
+                this.#reconnectWake = undefined;
+                resolve(true);
+            }, ms);
+            this.#reconnectWake = resolve;
+        });
+    }
+}
+/** 创建端点生命周期基座实例（见文件头迁移指引）。 */
+export function createEndpointLifecycle(options) {
+    return new EndpointLifecycleImpl(options);
+}

package/lib/endpoint-management.d.ts

@@ -0,0 +1,53 @@
+export interface EndpointFriend {
+    /** 数字平台（QQ 系）用 number；Slack/LINE/微信系用 string。 */
+    readonly user_id: number | string;
+    readonly nickname: string;
+    readonly remark: string;
+}
+export interface EndpointGroup {
+    /** 数字平台（QQ 系）用 number；Slack/LINE/微信系用 string。 */
+    readonly group_id: number | string;
+    readonly name: string;
+}
+export interface EndpointChannelParent {
+    readonly type: string;
+    readonly id: string;
+    readonly name?: string;
+}
+export interface EndpointChannel {
+    readonly id: string;
+    readonly name?: string;
+    readonly parent?: EndpointChannelParent;
+}
+/**
+ * Optional, platform-neutral management surface exposed by an Endpoint.
+ *
+ * Platform adapters own SDK aliases, identifier coercion, and response
+ * normalization. Hosts consume this interface without inspecting adapter
+ * names or transport-specific fields.
+ */
+export interface EndpointManagement {
+    listFriends?(): Promise<readonly EndpointFriend[]>;
+    listGroups?(): Promise<readonly EndpointGroup[]>;
+    listChannels?(): Promise<readonly EndpointChannel[]>;
+    listGroupMembers?(groupId: string): Promise<readonly unknown[]>;
+    approveRequest?(requestId: string, remark?: string): Promise<void>;
+    rejectRequest?(requestId: string, reason?: string): Promise<void>;
+    kickGroupMember?(groupId: string, userId: string): Promise<void>;
+    muteGroupMember?(groupId: string, userId: string, durationSeconds: number): Promise<void>;
+    setGroupAdmin?(groupId: string, userId: string, enabled: boolean): Promise<void>;
+    deleteFriend?(userId: string): Promise<void>;
+}
+export interface EndpointWithManagement {
+    readonly management?: EndpointManagement;
+}
+/**
+ * Stable, transport-neutral capability ids exposed to Host/Console clients.
+ * Values intentionally mirror EndpointManagement method names so adapters only
+ * need to implement the semantic port; no second capability declaration exists.
+ */
+export declare const endpointManagementCapabilityIds: readonly ["listFriends", "listGroups", "listChannels", "listGroupMembers", "approveRequest", "rejectRequest", "kickGroupMember", "muteGroupMember", "setGroupAdmin", "deleteFriend"];
+export type EndpointManagementCapability = (typeof endpointManagementCapabilityIds)[number];
+export declare function resolveEndpointManagement(endpoint: unknown): EndpointManagement | undefined;
+/** Derive advertised capabilities from the live semantic port implementation. */
+export declare function listEndpointManagementCapabilities(endpoint: unknown): readonly EndpointManagementCapability[];

package/lib/endpoint-management.js

@@ -0,0 +1,30 @@
+/**
+ * Stable, transport-neutral capability ids exposed to Host/Console clients.
+ * Values intentionally mirror EndpointManagement method names so adapters only
+ * need to implement the semantic port; no second capability declaration exists.
+ */
+export const endpointManagementCapabilityIds = [
+    'listFriends',
+    'listGroups',
+    'listChannels',
+    'listGroupMembers',
+    'approveRequest',
+    'rejectRequest',
+    'kickGroupMember',
+    'muteGroupMember',
+    'setGroupAdmin',
+    'deleteFriend',
+];
+export function resolveEndpointManagement(endpoint) {
+    if (!endpoint || typeof endpoint !== 'object')
+        return undefined;
+    const management = endpoint.management;
+    return management && typeof management === 'object' ? management : undefined;
+}
+/** Derive advertised capabilities from the live semantic port implementation. */
+export function listEndpointManagementCapabilities(endpoint) {
+    const management = resolveEndpointManagement(endpoint);
+    if (!management)
+        return Object.freeze([]);
+    return Object.freeze(endpointManagementCapabilityIds.filter((capability) => typeof management[capability] === 'function'));
+}

package/lib/index.d.ts

@@ -1,5 +1,10 @@
+/** @internal 适配器 projection（AdapterIndex），框架内部机制，不承诺不 break。 */
 export * from './adapter-index.js';
 export * from './credentials.js';
+/** @public 用户侧创作面：`defineAdapter`（`adapters/` 约定目录默认导出，承诺 semver）。 */
 export * from './definition.js';
+export * from './endpoint-commands.js';
+export * from './endpoint-lifecycle.js';
+export * from './endpoint-management.js';
 export * from './provider.js';
 export { default } from './provider.js';

package/lib/index.js

@@ -1,5 +1,10 @@
+/** @internal 适配器 projection（AdapterIndex），框架内部机制，不承诺不 break。 */
 export * from './adapter-index.js';
 export * from './credentials.js';
+/** @public 用户侧创作面：`defineAdapter`（`adapters/` 约定目录默认导出，承诺 semver）。 */
 export * from './definition.js';
+export * from './endpoint-commands.js';
+export * from './endpoint-lifecycle.js';
+export * from './endpoint-management.js';
 export * from './provider.js';
 export { default } from './provider.js';

package/lib/provider.js

@@ -7,6 +7,7 @@ const adapterFeature = defineFeatureProvider({
     protocol: 1,
     id: adapterFeatureId,
     authoring: {
+        setupMethod: 'addAdapter',
         conventions: [typeScriptModules({
                 id: 'adapters-ts',
                 directory: 'adapters',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Convention-based Adapter and Endpoint Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,13 +17,15 @@
     "src"
   ],
   "dependencies": {
-    "@zhin.js/feature-kit": "1.0.1",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "@zhin.js/logger": "1.0.75"
+    "yaml": "^2.9.0",
+    "@zhin.js/feature-kit": "1.0.3",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "@zhin.js/command": "1.0.3"
   },
   "zhin": {
     "protocol": 1,