@zhin.js/adapter 1.1.0 → 1.1.2

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

@@ -1,10 +1,12 @@
 export interface EndpointFriend {
-    readonly user_id: number;
+    /** 数字平台（QQ 系）用 number；Slack/LINE/微信系用 string。 */
+    readonly user_id: number | string;
     readonly nickname: string;
     readonly remark: string;
 }
 export interface EndpointGroup {
-    readonly group_id: number;
+    /** 数字平台（QQ 系）用 number；Slack/LINE/微信系用 string。 */
+    readonly group_id: number | string;
     readonly name: string;
 }
 export interface EndpointChannelParent {

package/lib/index.d.ts

@@ -1,6 +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,6 +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.1.0",
+  "version": "1.1.2",
   "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.2",
+    "yaml": "^2.9.0",
+    "@zhin.js/feature-kit": "1.0.4",
     "@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",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "@zhin.js/command": "1.0.4"
   },
   "zhin": {
     "protocol": 1,

package/src/adapter-index.ts

@@ -10,6 +10,7 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import type {
   AdapterCapability,
   AdapterDefinition,
+  AdapterSegmentPolicy,
   EndpointInstance,
   EndpointSendRequest,
 } from './definition.js';
@@ -41,6 +42,7 @@ export type AdapterEndpointPhase =
 
 interface AdapterRecord extends AdapterDescriptor {
   readonly endpoint: EndpointInstance;
+  readonly segments?: AdapterSegmentPolicy;
   readonly unconfigured: boolean;
   started: boolean;
   open: boolean;
@@ -96,6 +98,7 @@ export class AdapterIndex {
             source: slot.source,
             capabilities: slot.definition.capabilities,
             endpoint: endpoint.instance,
+            ...(slot.definition.segments ? { segments: slot.definition.segments } : {}),
             unconfigured: endpoint.unconfigured,
             started: false,
             open: false,
@@ -127,7 +130,8 @@ export class AdapterIndex {
   list(): readonly AdapterDescriptor[] {
     return this.#order.map(({ endpoint: _endpoint, unconfigured: _unconfigured,
       started: _started, open: _open, stopped: _stopped, failed: _failed,
-      startAttempted: _startAttempted, ...descriptor }) => Object.freeze(descriptor));
+      startAttempted: _startAttempted, segments: _segments,
+      ...descriptor }) => Object.freeze(descriptor));
   }
 
   /** Endpoint rows for Console `endpoint.list` / `endpoint.info`. */
@@ -175,6 +179,14 @@ export class AdapterIndex {
     return record.owner;
   }
 
+  /**
+   * Endpoint 的消息段能力声明（出站协商降级依据）；
+   * 未声明或未知 id 返回 undefined（调用方按历史行为处理）。
+   */
+  segmentPolicy(id: CapabilityId): AdapterSegmentPolicy | undefined {
+    return this.#records.get(id)?.segments;
+  }
+
   async start(): Promise<void> {
     // Soft-start in parallel with a short wait so kitchen-sink Roots do not
     // stall generation. Configured platforms that need longer (QQ auth, Slack

package/src/definition.ts

@@ -6,6 +6,12 @@ const adapterBrand = 'zhin.adapter/1' as const;
 
 export type AdapterCapability = 'inbound' | 'outbound';
 
+/** 端点可消费的出站媒体来源形式。 */
+export type AdapterOutboundMedia = 'url' | 'path' | 'base64' | 'upload';
+
+/** 交互段（卡片/按钮等富交互）的端点消费方式。 */
+export type AdapterInteractiveMode = 'native' | 'text';
+
 export interface EndpointSendRequest {
   readonly target: string;
   readonly payload: unknown;
@@ -31,14 +37,62 @@ export interface AdapterContext<TConfig = unknown> extends CapabilityContext<TCo
   readonly name: string;
 }
 
+/**
+ * html 段出站策略：
+ * - `direct`：端点直接消费 html 段（Console UI 类端点），核心不做任何转换；
+ * - `image`：经 html-renderer 渲染成 image 段，无渲染器时降级 text（缺省）；
+ * - `text`：直接降级为 text 段。
+ */
+export type HtmlOutboundMode = 'direct' | 'image' | 'text';
+
+/**
+ * 端点消息段能力声明（出站协商降级的依据）。
+ * 缺省（未声明 `segments`）保持历史行为：仅 html 段按 image/text 处理，
+ * 其余段原样透传给端点。
+ */
+export interface AdapterSegmentPolicy {
+  /**
+   * 端点原生可消费的 wire 段类型（如 `['text', 'image', 'at']`）。
+   * 声明后，未列出的段由核心按 `formatSegmentPreview` 降级为 text 段；
+   * 不声明则不过滤（全部透传）。
+   */
+  readonly supported?: readonly string[];
+  /** html 段处理策略，缺省 `image`。 */
+  readonly html?: HtmlOutboundMode;
+  /** 端点可消费的媒体来源形式；缺省表示不做媒体来源协商。 */
+  readonly outboundMedia?: readonly AdapterOutboundMedia[];
+  /**
+   * 交互段（卡片/按钮等富交互）消费方式：`native` 原生渲染 / `text` 降级纯文本。
+   * 目前仅为声明（供出站协商与门禁消费），`text` 的降级执行随 Wave 2 落地。
+   */
+  readonly interactive?: AdapterInteractiveMode;
+}
+
+const HTML_OUTBOUND_MODES: readonly HtmlOutboundMode[] = ['direct', 'image', 'text'];
+
+const OUTBOUND_MEDIA_FORMS: readonly AdapterOutboundMedia[] = [
+  'url', 'path', 'base64', 'upload',
+];
+
 export interface AdapterDefinition<TConfig = unknown, TResult = unknown> {
   readonly $feature: typeof adapterBrand;
   readonly capabilities: readonly AdapterCapability[];
+  /** 可选：端点消息段能力声明（出站协商降级挂载点）。 */
+  readonly segments?: AdapterSegmentPolicy;
   create(
     context: AdapterContext<TConfig>,
   ): EndpointInstance<TResult> | Promise<EndpointInstance<TResult>>;
 }
 
+declare module '@zhin.js/plugin-runtime' {
+  interface PluginSetupContext<TConfig> {
+    addAdapter<TResult = unknown>(
+      localName: string,
+      definition: AdapterDefinition<TConfig, TResult>,
+    ): void;
+  }
+}
+
 export function defineAdapter<TConfig = unknown, TResult = unknown>(
   definition: Omit<AdapterDefinition<TConfig, TResult>, '$feature'>,
 ): Readonly<AdapterDefinition<TConfig, TResult>> {
@@ -52,10 +106,58 @@ export function defineAdapter<TConfig = unknown, TResult = unknown>(
   ) {
     throw new TypeError('Adapter capabilities must contain inbound and/or outbound');
   }
+  const segments = normalizeSegmentPolicy(definition.segments);
   return Object.freeze({
     ...definition,
     $feature: adapterBrand,
     capabilities: Object.freeze(capabilities),
+    ...(segments ? { segments } : {}),
+  });
+}
+
+function normalizeSegmentPolicy(
+  policy: AdapterSegmentPolicy | undefined,
+): AdapterSegmentPolicy | undefined {
+  if (policy === undefined) return undefined;
+  if (!policy || typeof policy !== 'object') {
+    throw new TypeError('Adapter segments policy must be an object');
+  }
+  if (
+    policy.supported !== undefined
+    && (!Array.isArray(policy.supported)
+      || policy.supported.some((type) => typeof type !== 'string' || !type))
+  ) {
+    throw new TypeError('Adapter segments.supported must be an array of segment type names');
+  }
+  if (policy.html !== undefined && !HTML_OUTBOUND_MODES.includes(policy.html)) {
+    throw new TypeError('Adapter segments.html must be direct, image or text');
+  }
+  if (
+    policy.outboundMedia !== undefined
+    && (!Array.isArray(policy.outboundMedia)
+      || policy.outboundMedia.length === 0
+      || policy.outboundMedia.some(
+        (form) => !OUTBOUND_MEDIA_FORMS.includes(form as AdapterOutboundMedia),
+      ))
+  ) {
+    throw new TypeError(
+      "Adapter segments.outboundMedia must be a non-empty array of 'url' | 'path' | 'base64' | 'upload'",
+    );
+  }
+  if (
+    policy.interactive !== undefined
+    && policy.interactive !== 'native'
+    && policy.interactive !== 'text'
+  ) {
+    throw new TypeError("Adapter segments.interactive must be 'native' or 'text'");
+  }
+  return Object.freeze({
+    ...(policy.supported ? { supported: Object.freeze([...new Set(policy.supported)]) } : {}),
+    ...(policy.html ? { html: policy.html } : {}),
+    ...(policy.outboundMedia
+      ? { outboundMedia: Object.freeze([...new Set(policy.outboundMedia)]) }
+      : {}),
+    ...(policy.interactive ? { interactive: policy.interactive } : {}),
   });
 }
 
@@ -71,6 +173,8 @@ export function parseAdapterDefinition(value: unknown): AdapterDefinition {
       (capability) => capability !== 'inbound' && capability !== 'outbound',
     )
   ) throw invalidAdapter();
+  // defineAdapter 已校验过形状；外部手工构造的 definition 也在此兜底
+  normalizeSegmentPolicy(definition.segments);
   return definition as AdapterDefinition;
 }