lightAppBridge

招商随行（WorkLink）**插件窗口（plugin）与轻应用窗口（lightapp）**之间的双向通信 SDK。

基于 id 关联的请求 / 响应消息机制：发消息时生成唯一 id，对端回调的返回值原样带相同 id 回复，靠 id 配对请求与结果。

本包是 hkvs-llm-chat（plugin）与 vue-talent-cockpit（lightapp）两端的共享权威源，消除各自 copy 的版本漂移。

依赖（构造时校验，缺失直接抛异常）

必需：

| 依赖 | 用途 | 来源 | |------|------|------| | window.worklink（含 invokeModuleMethodSync） | 发送消息 / 取 webContentsId | preload 注入 | | window.worklink.plugin.getContentContext | 解析目标轻应用 webContentsId（仅 plugin 角色） | pluginLightAppPreload 注入 |

收消息（自动选择，不强依赖 waltz）：

| 监听后端 | 优先级 | 适用环境 | 说明 | |---------|--------|---------|------| | window.waltz.event.on('native-call-js') | 高（优先） | 有 waltz 注入的环境 | 推荐路径，立即可用 | | window.handleMessageFromNative | 低（回退） | 无 waltz 的环境 | 由 SDK 定义此全局方法（该方法原本由 waltz.min.js 注册；无 waltz 时为 undefined，renderer 投递消息前会检查其类型，没人定义则消息被丢弃）。renderer 收到消息后主动调用它传入消息。若该方法已存在则包装透传，不破坏原逻辑 |

• SDK 内部按 waltz → handleMessageFromNative 顺序探测，无需手动指定
• 握手会等监听绑定后才开始，避免早到的 ack/hello 丢失

安装（两个项目）

共享包位于仓库根 packages/lightAppBridge（与 hkvs-llm-chat、vue-talent-cockpit 同级），两个项目以 file: 相对路径引用（npm 7+ 软链式安装，源码改动实时生效）。

vue-talent-cockpit / hkvs-llm-chat（相同）

"dependencies": { "lightAppBridge": "file:../packages/lightAppBridge" }

注意：本包源码为 ES2019 兼容写法（不含 ?./??），hkvs 的 webpack4 可直接解析，无需 transpileDependencies。

用法

import LightAppBridge, { createBridge } from 'lightAppBridge'

// 插件窗口（发起方）
const bridge = new LightAppBridge('plugin')
await bridge.ready()
const result = await bridge.send({ action: 'getUser', id: 1 })

// 轻应用窗口（接收方，return 即回复）
const bridge = new LightAppBridge('lightapp')
bridge.onMessage((data, id) => {
  return { name: 'tom' }   // 返回值 = 回复内容（可 return Promise）
})

动态绑定与 ping（1.1.0+，仅 plugin 角色生效）

默认 bindMode: 'fixed'（首绑后固定对端，失联自动向原对端重连）。 多轻应用窗口场景用 dynamic：插件轮询 getContentContext() 感知用户切换窗口，向新窗口探测握手——成功即切换绑定（onRebind），失败（新窗口未集成 SDK）保持旧绑定。

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 即判定存活，不会误断；新旧版本可混布。

消息信封

{
  __sdk: 'LightAppBridge',    // SDK 标识：过滤出本 SDK 的消息，隔离其它消息
  v: 1,                       // 协议版本号
  id: 'r_xxx',                // 关联 id：send 生成，回复原样带回
  type: 'hello'|'ack'|'req'|'res',  // 握手 hello/ack；业务 req/res
  data: any                   // 任意业务数据
}

连接与生命周期

• 构造即自动握手（插件发 hello 每秒重试；轻应用持续等待、不超时）
• 握手失败后再次 connect() 可重连（自动重置状态，无需重建实例）
• destroy() 销毁实例：解绑监听、拒绝未完成请求；销毁后 send/connect 立即 reject

文件

• src/lightAppBridge.ts —— SDK 源码（TypeScript，构建产物为 ESM）
• src/index.ts —— barrel re-export