@jhh96/light-app-bridge 1.0.6 → 1.1.1

package/README.md

@@ -54,6 +54,27 @@ bridge.onMessage((data, id) => {
 })
 ```
 
+## 动态绑定与 ping（1.1.0+，仅 plugin 角色生效）
+
+默认 `bindMode: 'fixed'`（首绑后固定对端，失联自动向原对端重连）。
+多轻应用窗口场景用 `dynamic`：插件轮询 `getContentContext()` 感知用户切换窗口，向新窗口探测握手——成功即切换绑定（`onRebind`），失败（新窗口未集成 SDK）保持旧绑定。
+
+```js
+const bridge = new LightAppBridge('plugin', {
+  bindMode: 'dynamic',      // 'fixed'（默认）| 'dynamic'
+  dynamicPollInterval: 2000,  // 轮询当前轻应用间隔(ms)
+  migrateProbeTimeout: 3000,  // 新窗口 hello 探测窗口(ms)
+  pingInterval: 10000,        // 存活探测周期(ms)，0=关闭
+  pingTimeout: 5000,          // 单次 pong 等待(ms)
+  pingFailLimit: 3            // 连续失败阈值，达阈值后 hello/ack 兜底探测
+})
+
+bridge.onRebind((newPeerId, oldPeerId) => { /* 动态绑定已切换 */ })
+bridge.onDisconnect((peerId) => { /* 对端失联（ping 与兜底探测均无响应） */ })
+```
+
+ping 兼容性：对端 ≤1.0.6 不会回 pong，但握手逻辑仍在——连续 ping 失败后自动发 hello 兜底探测，收到 ack 即判定存活，不会误断；新旧版本可混布。
+
 ## 消息信封
 
 ```js

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { default } from './lightAppBridge';
 export { createBridge } from './lightAppBridge';
-export type { BridgeRole, EnvelopeType, Envelope, BridgeOptions, SendOptions, MessageHandler } from './lightAppBridge';
+export type { BridgeRole, BindMode, EnvelopeType, Envelope, BridgeOptions, SendOptions, MessageHandler } from './lightAppBridge';

package/dist/lightAppBridge.d.ts

@@ -23,8 +23,15 @@
  */
 /** 角色：plugin=插件窗口（发起方），lightapp=轻应用窗口（接收方） */
 export type BridgeRole = 'plugin' | 'lightapp';
+/**
+ * 绑定模式（仅 plugin 角色生效）：
+ *   - fixed   默认。首次握手绑定后固定对端，失联后向原对端重连。
+ *   - dynamic 跟随当前激活的轻应用窗口：轮询 getContentContext 感知切换，
+ *             向新窗口探测握手（成功即切换绑定；失败——如未集成 SDK——保持旧绑定）。
+ */
+export type BindMode = 'fixed' | 'dynamic';
 /** 信封类型 */
-export type EnvelopeType = 'hello' | 'ack' | 'req' | 'res';
+export type EnvelopeType = 'hello' | 'ack' | 'req' | 'res' | 'ping' | 'pong';
 /** 消息信封：所有跨窗口通信的统一包装 */
 export interface Envelope {
     __sdk: string;
@@ -39,6 +46,36 @@ export interface BridgeOptions {
     timeout?: number;
     /** 握手超时(ms)，默认 30000。仅 plugin 角色生效；lightapp 端持续等待，不超时 */
     handshakeTimeout?: number;
+    /**
+     * 绑定模式（仅 plugin 生效），默认 'fixed'。
+     * dynamic：轮询 getContentContext 跟随当前激活的轻应用窗口切换绑定。
+     */
+    bindMode?: BindMode;
+    /** dynamic 模式轮询 getContentContext 的间隔(ms)，默认 2000 */
+    dynamicPollInterval?: number;
+    /** dynamic 模式迁移探测窗口：向新窗口发 hello 等 ack 的时长(ms)，默认 3000 */
+    migrateProbeTimeout?: number;
+    /**
+     * ping 周期(ms)，默认 10000；设 0 关闭 ping。
+     * plugin 角色在绑定成功后周期 ping 对端（lightapp 自动回 pong），
+     * 连续 pingTimeout 无 pong 且 hello/ack 兜底探测也失败时判定失联并触发
+     * onDisconnect。
+     */
+    pingInterval?: number;
+    /** 单次 pong 等待(ms)，默认 5000 */
+    pingTimeout?: number;
+    /** 连续 ping 失败阈值（次），默认 3。达到后进入 hello/ack 兜底探测 */
+    pingFailLimit?: number;
+    /**
+     * 调试模式：开启后在控制台打印完整通信轨迹，便于排查 plugin ↔ lightapp
+     * 联调问题。覆盖：
+     *   - 构造（角色/配置）、握手（hello/ack/连接建立/超时/重连）
+     *   - 发送请求（send data + id）、底层投递（目标 webContentsId + 信封）
+     *   - 收到消息（type/id/from/data）、响应返回（res 数据/超时）
+     *   - ping/pong、动态绑定迁移、handler 异常、销毁
+     * 大 payload 截断到 500 字符防刷屏。
+     */
+    debug?: boolean;
 }
 /** send 单次调用选项 */
 export interface SendOptions {
@@ -56,6 +93,12 @@ export default class LightAppBridge {
     role: BridgeRole;
     timeout: number;
     handshakeTimeout: number;
+    bindMode: BindMode;
+    dynamicPollInterval: number;
+    migrateProbeTimeout: number;
+    pingInterval: number;
+    pingTimeout: number;
+    pingFailLimit: number;
     private _pending;
     private _messageHandlers;
     private _target;
@@ -72,12 +115,30 @@ export default class LightAppBridge {
     private _listenerReady;
     private _connectFailed;
     private _destroyed;
+    private _debug;
+    private _helloCount;
+    private _dynamicTimer;
+    private _migrating;
+    private _migrateTargetId;
+    private _migrateTimer;
+    private _migrateRetryTimer;
+    private _rebindCbs;
+    private _pingTimer;
+    private _pingWaiting;
+    private _pingFails;
+    private _pingResolve;
+    private _probeActive;
+    private _probeOk;
+    private _probeTimers;
+    private _disconnectCbs;
     /**
      * @param role 角色，省略时按 window.worklink.plugin 是否存在自动探测
      * @param options 超时配置
      * @throws 依赖未就绪时抛出（window.worklink；监听后端可稍后出现，不算构造失败）
      */
     constructor(role?: BridgeRole, options?: BridgeOptions);
+    /** debug 日志（options.debug 开启时打印，前缀带角色便于双端对照） */
+    private _log;
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     private _checkDeps;
     /** 绑定消息监听：优先 waltz；无 waltz 时定义/包装 window.handleMessageFromNative */
@@ -113,6 +174,42 @@ export default class LightAppBridge {
     private _clearHelloTimer;
     /** 监听连接建立（握手完成）。若已连接则立即触发 */
     onConnect(cb: (peerId: number | null) => void): this;
+    /** 连接建立后启动目标轮询（幂等；非 dynamic / 非 plugin 不启动） */
+    private _startDynamicPoll;
+    private _stopDynamicPoll;
+    /**
+     * 解析当前激活的轻应用 webContentsId；变化则发起迁移探测。
+     * 失联恢复（onDisconnect 后）也复用此入口强制解析。
+     */
+    private _pollTarget;
+    /**
+     * 向新目标发 hello 探测（HELLO_RETRY_INTERVAL 重试）。
+     *   - 探测窗口内收到 ack（_onAck → _rebindTo）：切换绑定
+     *   - 超时（新窗口未集成 SDK）：放弃，保持旧绑定，等下一轮轮询再探
+     */
+    private _startMigrate;
+    private _endMigrate;
+    /** 迁移成功：切换绑定目标并通知（连接语义连续，ready() 不受影响） */
+    private _rebindTo;
+    /** 监听动态绑定切换（bindMode='dynamic' 时目标窗口变化并成功迁移后触发一次） */
+    onRebind(cb: (newPeerId: number | null, oldPeerId: number | null) => void): this;
+    /** 绑定成功后启动周期 ping（幂等；pingInterval=0 或非 plugin 不启动） */
+    private _startPing;
+    private _stopPing;
+    /** 发一次 ping：等 pong → 失败计数 → 达阈值后 hello/ack 兜底探测 → 仍失败判定失联 */
+    private _pingOnce;
+    /** 收到 pong：唤醒在途 ping */
+    private _onPong;
+    /**
+     * ping 连续失败后的兜底探测：向对端发 hello 等 ack。
+     * 旧版对端（无 pong 能力）握手逻辑仍在会回 ack —— 收到即判定存活，避免误杀。
+     * ack 也无响应才判定真失联。
+     */
+    private _probeAlive;
+    /** 判定失联：触发 onDisconnect，并按绑定模式恢复 */
+    private _handleDisconnect;
+    /** 监听对端失联（ping 与 hello 兜底探测均无响应时触发一次） */
+    onDisconnect(cb: (peerId: number | null) => void): this;
     /**
      * 等待连接建立（握手完成）。构造时已自动发起握手，直接 await 即可。
      * @returns 对端 webContentsId
@@ -142,7 +239,7 @@ export default class LightAppBridge {
      * @returns 调用以取消监听
      */
     onMessage(handler: MessageHandler): () => void;
-    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试。销毁后实例不可再用 */
+    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手/轮询/迁移/ping。销毁后实例不可再用 */
     destroy(): void;
 }
 /**

package/dist/lightAppBridge.js

@@ -26,7 +26,27 @@ const PROTOCOL_VERSION = 1; // 协议版本号
 const DEFAULT_TIMEOUT = 3000; // send 默认超时(ms)
 const DEFAULT_HANDSHAKE_TIMEOUT = 30000; // 握手超时(ms)
 const HELLO_RETRY_INTERVAL = 1000; // 插件 hello 重试间隔(ms)
+const DEBUG_PAYLOAD_LIMIT = 500; // debug 日志 payload 截断长度
+const DEFAULT_BIND_MODE = 'fixed'; // 绑定模式默认值
+const DEFAULT_DYNAMIC_POLL_INTERVAL = 2000; // dynamic 轮询间隔(ms)
+const DEFAULT_MIGRATE_PROBE_TIMEOUT = 3000; // 迁移探测窗口(ms)
+const DEFAULT_PING_INTERVAL = 10000; // ping 周期(ms)
+const DEFAULT_PING_TIMEOUT = 5000; // 单次 pong 等待(ms)
+const DEFAULT_PING_FAIL_LIMIT = 3; // 连续 ping 失败阈值(次)
 const genId = () => 'r_' + Date.now().toString(36) + '_' + Math.random().toString(36).slice(2, 7);
+/** debug 日志用：安全序列化 payload，超长截断 */
+function debugPayload(data) {
+    let s;
+    try {
+        s = typeof data === 'string' ? data : JSON.stringify(data);
+    }
+    catch {
+        s = String(data);
+    }
+    if (s === undefined)
+        s = 'undefined';
+    return s.length > DEBUG_PAYLOAD_LIMIT ? s.slice(0, DEBUG_PAYLOAD_LIMIT) + `…(截断,共${s.length}字符)` : s;
+}
 /** 判断是否为本 SDK 的消息（按 __sdk 标识过滤） */
 const isBridgeMsg = (msg) => !!(msg && typeof msg === 'object' && msg.__sdk === SDK_ID);
 /** 创建一个可外部 resolve 的 Promise */
@@ -165,6 +185,23 @@ export default class LightAppBridge {
         this._listenerReady = null;
         this._connectFailed = false;
         this._destroyed = false;
+        this._helloCount = 0;
+        // —— 动态绑定（plugin + bindMode='dynamic'）——
+        this._dynamicTimer = null;
+        this._migrating = false;
+        this._migrateTargetId = null;
+        this._migrateTimer = null;
+        this._migrateRetryTimer = null;
+        this._rebindCbs = [];
+        // —— ping/pong 存活探测（plugin 主动）——
+        this._pingTimer = null;
+        this._pingWaiting = false; // 一次 ping 在途（等 pong）
+        this._pingFails = 0; // 连续 pong 超时计数
+        this._pingResolve = null; // 当前在途 ping 的完成回调
+        this._probeActive = false; // hello/ack 兜底探测进行中
+        this._probeOk = false; // 兜底探测是否收到 ack
+        this._probeTimers = []; // 防 destroy 后悬挂
+        this._disconnectCbs = [];
         let r = role === 'plugin' || role === 'lightapp' ? role : 'lightapp';
         if (role !== 'plugin' && role !== 'lightapp') {
             const wl = window.worklink;
@@ -173,6 +210,20 @@ export default class LightAppBridge {
         this.role = r;
         this.timeout = options.timeout != null ? options.timeout : DEFAULT_TIMEOUT;
         this.handshakeTimeout = options.handshakeTimeout != null ? options.handshakeTimeout : DEFAULT_HANDSHAKE_TIMEOUT;
+        this.bindMode = options.bindMode === 'dynamic' ? 'dynamic' : DEFAULT_BIND_MODE;
+        this.dynamicPollInterval = options.dynamicPollInterval != null ? options.dynamicPollInterval : DEFAULT_DYNAMIC_POLL_INTERVAL;
+        this.migrateProbeTimeout = options.migrateProbeTimeout != null ? options.migrateProbeTimeout : DEFAULT_MIGRATE_PROBE_TIMEOUT;
+        this.pingInterval = options.pingInterval != null ? options.pingInterval : DEFAULT_PING_INTERVAL;
+        this.pingTimeout = options.pingTimeout != null ? options.pingTimeout : DEFAULT_PING_TIMEOUT;
+        this.pingFailLimit = options.pingFailLimit != null ? options.pingFailLimit : DEFAULT_PING_FAIL_LIMIT;
+        this._debug = !!options.debug;
+        this._log('构造: role=' + r + ', timeout=' + this.timeout +
+            ', handshakeTimeout=' + this.handshakeTimeout +
+            ', bindMode=' + this.bindMode +
+            (this.bindMode === 'dynamic' ? '(poll=' + this.dynamicPollInterval + 'ms)' : '') +
+            ', ping=' + (this.pingInterval > 0 ? this.pingInterval + 'ms' : 'off') +
+            ', 监听后端=' + (hasWaltz() ? 'waltz' : 'handleMessageFromNative') +
+            ', 自身id=' + this.getId());
         // 连接 deferred：构造时即建立，保证轻应用收到 hello 也能 resolve（无需显式 connect）
         this._connectDeferred = deferred();
         this._connectPromise = this._connectDeferred.promise.then((peerId) => {
@@ -183,6 +234,12 @@ export default class LightAppBridge {
         this._startListener(); // 绑定消息监听（waltz 或定义 handleMessageFromNative）
         this.connect(); // 构造即自动发起握手（内部会等监听就绪）
     }
+    /** debug 日志（options.debug 开启时打印，前缀带角色便于双端对照） */
+    _log(...args) {
+        if (!this._debug)
+            return;
+        console.log(`[LightAppBridge:${this.role}]`, ...args);
+    }
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     _checkDeps() {
         const w = window;
@@ -218,8 +275,12 @@ export default class LightAppBridge {
     _onMessage(msg) {
         const envelope = msg.envelope;
         const fromId = msg.fromWebContentsId;
-        if (!isBridgeMsg(envelope))
+        if (!isBridgeMsg(envelope)) {
+            this._log('recv← 忽略非本SDK消息: from=' + fromId);
             return;
+        }
+        this._log('recv← type=' + envelope.type + ' id=' + envelope.id +
+            ' from=' + fromId + ' data=' + debugPayload(envelope.data));
         switch (envelope.type) {
             case 'hello':
                 this._onHello(fromId);
@@ -234,6 +295,13 @@ export default class LightAppBridge {
             case 'res':
                 this._serveRes(envelope);
                 break;
+            case 'ping':
+                // 存活探测：立即回 pong（data 原样带回），无论何种角色/模式都应答
+                this._send(fromId, this._envelope('pong', envelope.data, envelope.id));
+                break;
+            case 'pong':
+                this._onPong(envelope);
+                break;
         }
     }
     // —— 连接 / 握手 —— //
@@ -277,7 +345,19 @@ export default class LightAppBridge {
             if (this._connected)
                 return;
             if (this.role === 'plugin') {
-                // 插件：解析目标后发 hello，并重试直到收到 ack
+                // 重连场景（失联后恢复）：已有原目标时不再重新解析 getContentContext——
+                // 失联期间用户可能已切换轻应用窗口，重新解析会让 fixed 模式"漂移"到新窗口，
+                // 违背固定对端语义。固定模式坚持向原对端重连（对端彻底没了则超时失败）。
+                // dynamic 模式的窗口跟随走独立的迁移状态机（_pollTarget），不经此路径。
+                if (this._target != null) {
+                    this._sendHello();
+                    this._helloTimer = setInterval(() => {
+                        if (!this._connected)
+                            this._sendHello();
+                    }, HELLO_RETRY_INTERVAL);
+                    return;
+                }
+                // 首次连接：解析目标后发 hello，并重试直到收到 ack
                 return window.worklink.plugin.getContentContext()
                     .then((ctx) => {
                     if (!ctx || ctx.webContentsId == null) {
@@ -316,12 +396,15 @@ export default class LightAppBridge {
         if (this._destroyed)
             return;
         this._connectFailed = true;
+        this._log('✗ 握手失败: ' + (e && e.message ? e.message : String(e)));
         this._connectDeferred.reject(e instanceof Error ? e : new Error(String(e)));
     }
     /** 发送 hello（携带自身 webContentsId） */
     _sendHello() {
         if (this._target == null)
             return;
+        this._helloCount++;
+        this._log('hello→ 目标=' + this._target + (this._helloCount > 1 ? ' (重试#' + this._helloCount + ')' : ''));
         this._send(this._target, this._envelope('hello', { from: this.getId() }));
     }
     /** 收到 hello（轻应用侧）：记录对端、回 ack、完成握手 */
@@ -338,6 +421,17 @@ export default class LightAppBridge {
     _onAck(fromId) {
         if (fromId == null)
             return; // 无法定位对端则忽略
+        // ping 失败后的 hello/ack 兜底探测：收到 ack 即对端存活（旧版对端不会回 pong
+        // 但握手逻辑仍在），标记探测成功
+        if (this._probeActive) {
+            this._probeOk = true;
+            this._log('✓ ping兜底探测: 对端存活(ack) from=' + fromId);
+        }
+        // 动态绑定迁移中：仅当 ack 来自迁移目标才完成切换
+        if (this._migrating && fromId === this._migrateTargetId) {
+            this._rebindTo(fromId);
+            return;
+        }
         this._recordPeer(fromId);
         this._connectDeferred.resolve(fromId);
     }
@@ -347,11 +441,15 @@ export default class LightAppBridge {
     }
     _onConnected(peerId) {
         this._connected = true;
+        this._log('✓ 连接建立: 对端=' + peerId + (this._helloCount > 1 ? ' (hello共' + this._helloCount + '次)' : ''));
         this._clearHelloTimer();
         if (this._handshakeTimer) {
             clearTimeout(this._handshakeTimer);
             this._handshakeTimer = null;
         }
+        // 绑定成功后启动存活探测与（dynamic 模式）目标轮询
+        this._startPing();
+        this._startDynamicPoll();
         // 触发 onConnect 回调
         const cbs = this._connectCbs.splice(0);
         cbs.forEach((cb) => {
@@ -375,6 +473,230 @@ export default class LightAppBridge {
             this._connectCbs.push(cb);
         return this;
     }
+    // —— 动态绑定（bindMode='dynamic'，仅 plugin）—— //
+    /** 连接建立后启动目标轮询（幂等；非 dynamic / 非 plugin 不启动） */
+    _startDynamicPoll() {
+        if (this.role !== 'plugin' || this.bindMode !== 'dynamic')
+            return;
+        if (this._dynamicTimer || this._destroyed)
+            return;
+        this._log('dynamic: 启动目标轮询 (interval=' + this.dynamicPollInterval + 'ms)');
+        this._dynamicTimer = setInterval(() => {
+            this._pollTarget().catch(() => { });
+        }, this.dynamicPollInterval);
+    }
+    _stopDynamicPoll() {
+        if (this._dynamicTimer) {
+            clearInterval(this._dynamicTimer);
+            this._dynamicTimer = null;
+        }
+        this._endMigrate();
+    }
+    /**
+     * 解析当前激活的轻应用 webContentsId；变化则发起迁移探测。
+     * 失联恢复（onDisconnect 后）也复用此入口强制解析。
+     */
+    async _pollTarget() {
+        if (this._destroyed || this.role !== 'plugin')
+            return;
+        const ctx = await window.worklink.plugin.getContentContext();
+        const ctxId = ctx && ctx.webContentsId != null ? ctx.webContentsId : null;
+        if (ctxId == null || ctxId === this._target)
+            return;
+        if (this._migrating)
+            return; // 上一轮迁移探测进行中，等它结束
+        this._startMigrate(ctxId);
+    }
+    /**
+     * 向新目标发 hello 探测（HELLO_RETRY_INTERVAL 重试）。
+     *   - 探测窗口内收到 ack（_onAck → _rebindTo）：切换绑定
+     *   - 超时（新窗口未集成 SDK）：放弃，保持旧绑定，等下一轮轮询再探
+     */
+    _startMigrate(newTargetId) {
+        const oldId = this._peer;
+        this._migrating = true;
+        this._migrateTargetId = newTargetId;
+        this._log('dynamic: 目标变化 ' + oldId + ' → ' + newTargetId + '，迁移探测开始');
+        const probe = () => {
+            if (!this._migrating)
+                return;
+            this._send(newTargetId, this._envelope('hello', { from: this.getId() }));
+        };
+        probe();
+        this._migrateRetryTimer = setInterval(probe, HELLO_RETRY_INTERVAL);
+        this._migrateTimer = setTimeout(() => {
+            if (this._migrating) {
+                this._log('dynamic: 迁移探测超时(' + this.migrateProbeTimeout + 'ms)，目标 ' +
+                    newTargetId + ' 未集成 SDK，保持原绑定 ' + oldId);
+                this._endMigrate();
+            }
+        }, this.migrateProbeTimeout);
+    }
+    _endMigrate() {
+        this._migrating = false;
+        this._migrateTargetId = null;
+        if (this._migrateTimer) {
+            clearTimeout(this._migrateTimer);
+            this._migrateTimer = null;
+        }
+        if (this._migrateRetryTimer) {
+            clearInterval(this._migrateRetryTimer);
+            this._migrateRetryTimer = null;
+        }
+    }
+    /** 迁移成功：切换绑定目标并通知（连接语义连续，ready() 不受影响） */
+    _rebindTo(newPeerId) {
+        const oldId = this._peer;
+        this._endMigrate();
+        this._target = newPeerId;
+        this._peer = newPeerId;
+        // 失联恢复场景（onDisconnect 后迁移成功）：恢复连接态并重启 ping；
+        // 常规迁移（本来就连接着）时这些操作幂等。
+        this._connected = true;
+        this._startPing();
+        this._startDynamicPoll();
+        this._log('✓ dynamic: 重新绑定 ' + oldId + ' → ' + newPeerId);
+        // ping 计数清零并立即探测新对端（新窗口刚握手成功，顺带验证 pong 能力）
+        this._pingFails = 0;
+        this._pingOnce();
+        const cbs = this._rebindCbs.splice(0);
+        cbs.forEach((cb) => {
+            try {
+                cb(newPeerId, oldId);
+            }
+            catch { /* ignore */ }
+        });
+    }
+    /** 监听动态绑定切换（bindMode='dynamic' 时目标窗口变化并成功迁移后触发一次） */
+    onRebind(cb) {
+        this._rebindCbs.push(cb);
+        return this;
+    }
+    // —— ping/pong 存活探测（plugin 主动发，lightapp 自动回 pong）—— //
+    /** 绑定成功后启动周期 ping（幂等；pingInterval=0 或非 plugin 不启动） */
+    _startPing() {
+        if (this.role !== 'plugin' || this.pingInterval <= 0)
+            return;
+        if (this._pingTimer || this._destroyed)
+            return;
+        this._pingTimer = setInterval(() => this._pingOnce(), this.pingInterval);
+    }
+    _stopPing() {
+        if (this._pingTimer) {
+            clearInterval(this._pingTimer);
+            this._pingTimer = null;
+        }
+        this._pingWaiting = false;
+        this._pingFails = 0;
+    }
+    /** 发一次 ping：等 pong → 失败计数 → 达阈值后 hello/ack 兜底探测 → 仍失败判定失联 */
+    _pingOnce() {
+        if (this._destroyed || !this._connected || this._pingWaiting)
+            return;
+        const id = genId();
+        this._pingWaiting = true;
+        let settled = false;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            this._pingWaiting = false;
+            this._pingResolve = null;
+            if (ok) {
+                if (this._pingFails > 0)
+                    this._log('✓ pong 恢复 (此前失败' + this._pingFails + '次)');
+                this._pingFails = 0;
+                return;
+            }
+            this._pingFails++;
+            this._log('✗ pong 超时 ' + this._pingFails + '/' + this.pingFailLimit);
+            if (this._pingFails >= this.pingFailLimit) {
+                this._probeAlive();
+            }
+        };
+        // pong 到达回调（_onPong 触发）
+        this._pingResolve = () => finish(true);
+        setTimeout(() => finish(false), this.pingTimeout);
+        try {
+            this._send(this._peer, this._envelope('ping', { t: Date.now() }, id));
+        }
+        catch (e) {
+            // 底层投递异常（invoke 瞬时不可用 / peer 为空）按本次失败计，不冒泡进 interval
+            this._log('✗ ping 发送异常: ' + (e instanceof Error ? e.message : String(e)));
+            finish(false);
+        }
+    }
+    /** 收到 pong：唤醒在途 ping */
+    _onPong(envelope) {
+        if (this._pingResolve)
+            this._pingResolve();
+    }
+    /**
+     * ping 连续失败后的兜底探测：向对端发 hello 等 ack。
+     * 旧版对端（无 pong 能力）握手逻辑仍在会回 ack —— 收到即判定存活，避免误杀。
+     * ack 也无响应才判定真失联。
+     */
+    _probeAlive() {
+        if (this._destroyed || !this._connected)
+            return;
+        this._log('ping 兜底探测: 发 hello → ' + this._peer);
+        this._probeActive = true;
+        this._probeOk = false;
+        // 真发一条 hello：旧版对端（无 pong 能力）的握手逻辑仍在，会回 ack 证明存活。
+        // 发送异常按探测失败处理（timer 到期自然判定），不冒泡。
+        try {
+            this._send(this._peer, this._envelope('hello', { from: this.getId() }));
+        }
+        catch { /* timer 到期后按无响应处理 */ }
+        const timer = setTimeout(() => {
+            const active = this._probeActive;
+            const ok = this._probeOk;
+            this._probeActive = false;
+            if (!active)
+                return;
+            if (ok) {
+                // 旧版对端存活（无 pong 能力）：清计数继续常规 ping（下轮失败仍会兜底，无害）
+                this._log('✓ ping 兜底探测: 对端存活(旧版无pong)');
+                this._pingFails = 0;
+            }
+            else {
+                this._handleDisconnect();
+            }
+        }, this.pingTimeout);
+        // 防 destroy 后悬挂 timer
+        this._probeTimers.push(timer);
+    }
+    /** 判定失联：触发 onDisconnect，并按绑定模式恢复 */
+    _handleDisconnect() {
+        const deadId = this._peer;
+        this._log('✗ 对端失联: ' + deadId + '（ping + hello 探测均无响应）');
+        this._connected = false;
+        this._stopPing();
+        const cbs = this._disconnectCbs.splice(0);
+        cbs.forEach((cb) => {
+            try {
+                cb(deadId);
+            }
+            catch { /* ignore */ }
+        });
+        if (this._destroyed)
+            return;
+        if (this.bindMode === 'dynamic') {
+            // dynamic：立即解析当前激活轻应用并尝试迁移（找不到可绑目标则等下轮轮询）
+            this._startDynamicPoll();
+            this._pollTarget().catch(() => { });
+        }
+        else {
+            // fixed：自动向原对端重新握手（复用失败重连逻辑）
+            this._resetConnectState();
+            this.connect().catch(() => { });
+        }
+    }
+    /** 监听对端失联（ping 与 hello 兜底探测均无响应时触发一次） */
+    onDisconnect(cb) {
+        this._disconnectCbs.push(cb);
+        return this;
+    }
     /**
      * 等待连接建立（握手完成）。构造时已自动发起握手，直接 await 即可。
      * @returns 对端 webContentsId
@@ -399,19 +721,24 @@ export default class LightAppBridge {
         Promise.allSettled(results).then((settled) => {
             for (const s of settled) {
                 if (s.status === 'fulfilled' && s.value !== undefined) {
+                    this._log('res→ id=' + id + ' data=' + debugPayload(s.value));
                     this._send(this._peer, this._envelope('res', s.value, id));
                     return;
                 }
             }
+            this._log('✗ req 无可回复值(回调全空/异常): id=' + id);
         });
     }
     /** 收到 res：按 id 唤醒等待中的 send */
     _serveRes(envelope) {
         const p = this._pending.get(envelope.id);
-        if (!p)
+        if (!p) {
+            this._log('recv← res 无等待者(可能已超时): id=' + envelope.id);
             return;
+        }
         clearTimeout(p.timer);
         this._pending.delete(envelope.id);
+        this._log('✓ 收到响应 id=' + envelope.id + ' data=' + debugPayload(envelope.data));
         p.resolve(envelope.data);
     }
     /** 底层发送：把信封投递到指定 webContentsId */
@@ -442,13 +769,18 @@ export default class LightAppBridge {
         if (this._destroyed)
             return Promise.reject(new Error('实例已销毁'));
         const timeout = options.timeout != null ? options.timeout : this.timeout;
-        return this.ready().then((targetId) => {
+        return this.ready().then(() => {
+            // 发送目标取当前 _peer（而非 ready() resolve 的快照）：
+            // dynamic 模式迁移重绑后，后续 send 立即发往新对端。
+            const targetId = this._peer;
             const id = genId();
             const envelope = this._envelope('req', data, id);
+            this._log('send→ id=' + id + ' 目标=' + targetId + ' data=' + debugPayload(data));
             return new Promise((resolve, reject) => {
                 const timer = setTimeout(() => {
                     if (this._pending.has(id)) {
                         this._pending.delete(id);
+                        this._log('✗ 超时 id=' + id + ' (' + timeout + 'ms 无响应)');
                         reject(new Error(`请求超时 (${timeout}ms)`));
                     }
                 }, timeout);
@@ -476,11 +808,12 @@ export default class LightAppBridge {
                 this._messageHandlers.splice(i, 1);
         };
     }
-    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试。销毁后实例不可再用 */
+    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手/轮询/迁移/ping。销毁后实例不可再用 */
     destroy() {
         if (this._destroyed)
             return;
         this._destroyed = true;
+        this._log('销毁实例: 未完成请求=' + this._pending.size);
         if (this._unlisten) {
             try {
                 this._unlisten();
@@ -489,6 +822,11 @@ export default class LightAppBridge {
             this._unlisten = null;
         }
         this._clearHelloTimer();
+        this._stopDynamicPoll();
+        this._stopPing();
+        this._probeTimers.forEach((t) => clearTimeout(t));
+        this._probeTimers.length = 0;
+        this._probeActive = false;
         if (this._handshakeTimer) {
             clearTimeout(this._handshakeTimer);
             this._handshakeTimer = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhh96/light-app-bridge",
-  "version": "1.0.6",
+  "version": "1.1.1",
   "type": "module",
   "description": "招商随行（WorkLink）插件窗口(plugin)与轻应用窗口(lightapp)之间的双向通信 SDK",
   "main": "./dist/index.js",