@jhh96/light-app-bridge 1.0.0

package/README.md

@@ -0,0 +1,60 @@
+# lightAppBridge
+
+> 招商随行（WorkLink）**插件窗口（plugin）**与**轻应用窗口（lightapp）**之间的双向通信 SDK。
+
+基于 `id` 关联的请求 / 响应消息机制：发消息时生成唯一 `id`，对端回调的返回值原样带相同 `id` 回复，靠 `id` 配对请求与结果。
+
+本包是 hkvs-llm-chat（plugin）与 vue-talent-cockpit（lightapp）两端的**共享权威源**，消除各自 copy 的版本漂移。
+
+## 依赖（构造时校验，缺失直接抛异常）
+
+| 依赖 | 用途 | 来源 |
+|------|------|------|
+| `window.waltz.event.on` | 接收消息 | preload 注入的 waltz SDK |
+| `window.worklink`（含 `invokeModuleMethodSync`） | 发送消息 / 取 webContentsId | preload 注入 |
+| `window.worklink.plugin.getContentContext` | 解析目标轻应用 webContentsId（**仅 plugin 角色**） | pluginLightAppPreload 注入 |
+
+## 安装（两个项目）
+
+共享包位于仓库根 `packages/lightAppBridge`（与 hkvs-llm-chat、vue-talent-cockpit 同级），两个项目以 `file:` 相对路径引用（npm 7+ 软链式安装，源码改动实时生效）。
+
+### vue-talent-cockpit / hkvs-llm-chat（相同）
+
+```json
+"dependencies": { "lightAppBridge": "file:../packages/lightAppBridge" }
+```
+
+注意：本包源码为 ES2019 兼容写法（不含 `?.`/`??`），hkvs 的 webpack4 可直接解析，无需 `transpileDependencies`。
+
+## 用法
+
+```js
+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）
+})
+```
+
+## 消息信封
+
+```js
+{
+  __sdk: 'lightAppBridge',   // 标识：在 plugin-message 流中过滤出本 SDK 的消息
+  id: 'r_xxx',               // 关联 id：send 生成，回复原样带回
+  type: 'req' | 'res',       // 请求 / 响应
+  data: any                  // 任意业务数据
+}
+```
+
+## 文件
+
+- `src/lightAppBridge.js` —— SDK 源码（ESM，可直接 import）
+- `src/index.js` —— barrel re-export

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,2 @@
+export { default } from './lightAppBridge.js';
+export { createBridge } from './lightAppBridge.js';

package/dist/lightAppBridge.d.ts

@@ -0,0 +1,133 @@
+/*!
+ * LightAppBridge —— 插件窗口(plugin)与轻应用窗口(lightapp)之间的双向通信 SDK
+ *
+ * 核心特性：
+ *   1. 连接建立：插件主动 connect() 发起握手，双向交换 webContentsId，确认连接后才能收发。
+ *   2. 请求/响应：基于 id 关联，对端 onMessage 回调的「返回值」带相同 id 回复。
+ *   3. SDK 标识：所有消息携带 __sdk 标识 + 版本号，隔离其它消息，防止混淆。
+ *
+ * 依赖（构造时校验，缺失直接抛异常，请确保依赖注入完成后再 new）：
+ *   - window.waltz.event.on        收消息
+ *   - window.worklink              发消息 / 取 webContentsId
+ *   - window.worklink.plugin.getContentContext  （仅 plugin 角色需要）
+ *
+ * 消息信封：
+ *   { __sdk: 'LightAppBridge', v: 1, id, type, data }
+ *   type ∈ 'hello' | 'ack' | 'req' | 'res'
+ */
+/** 角色：plugin=插件窗口（发起方），lightapp=轻应用窗口（接收方） */
+export type BridgeRole = 'plugin' | 'lightapp';
+/** 信封类型 */
+export type EnvelopeType = 'hello' | 'ack' | 'req' | 'res';
+/** 消息信封：所有跨窗口通信的统一包装 */
+export interface Envelope {
+    __sdk: string;
+    v: number;
+    id: string;
+    type: EnvelopeType;
+    data: any;
+}
+/** 构造选项 */
+export interface BridgeOptions {
+    /** send 默认超时(ms)，默认 3000 */
+    timeout?: number;
+    /** 握手超时(ms)，默认 30000 */
+    handshakeTimeout?: number;
+}
+/** send 单次调用选项 */
+export interface SendOptions {
+    /** 本次超时(ms)，不传用实例默认值 */
+    timeout?: number;
+}
+/**
+ * 请求消息处理器。返回值（含 Promise 解析值）会作为回复发回发送方。
+ * @param data 请求携带的业务数据
+ * @param id 请求 id（与回复配对用）
+ * @param fromWebContentsId 发送方 webContentsId
+ */
+export type MessageHandler = (data: any, id: string, fromWebContentsId: number | null) => any | Promise<any>;
+export default class LightAppBridge {
+    role: BridgeRole;
+    timeout: number;
+    handshakeTimeout: number;
+    private _pending;
+    private _messageHandlers;
+    private _target;
+    private _peer;
+    private _connected;
+    private _connectStarted;
+    private _connectCbs;
+    private _helloTimer;
+    private _handshakeTimer;
+    private _started;
+    private _connectDeferred;
+    private _connectPromise;
+    /**
+     * @param role 角色，省略时按 window.worklink.plugin 是否存在自动探测
+     * @param options 超时配置
+     * @throws 依赖未就绪时抛出（window.waltz / window.worklink）
+     */
+    constructor(role?: BridgeRole, options?: BridgeOptions);
+    /** 校验依赖是否就绪，缺失抛出明确异常 */
+    private _checkDeps;
+    /** 绑定 native-call-js 监听 */
+    private _bindListener;
+    /** 构造消息信封 */
+    private _envelope;
+    /** 处理一条原生消息 */
+    private _onRaw;
+    /**
+     * 建立连接（握手）。构造时已自动调用，通常无需手动调；如需重新握手可再次调用。
+     *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack）
+     *   - 轻应用：启动握手等待（被动等 hello；若插件始终未来则超时）
+     * 多次调用幂等，返回同一个连接 Promise。
+     * @returns 对端 webContentsId
+     */
+    connect(): Promise<number | null>;
+    /** 发送 hello（携带自身 webContentsId） */
+    private _sendHello;
+    /** 收到 hello（轻应用侧）：记录对端、回 ack、完成握手 */
+    private _onHello;
+    /** 收到 ack（插件侧）：确认连接 */
+    private _onAck;
+    private _recordPeer;
+    private _onConnected;
+    private _clearHelloTimer;
+    /** 监听连接建立（握手完成）。若已连接则立即触发 */
+    onConnect(cb: (peerId: number | null) => void): this;
+    /**
+     * 等待连接建立（握手完成）。构造时已自动发起握手，直接 await 即可。
+     * @returns 对端 webContentsId
+     */
+    ready(): Promise<number | null>;
+    /**
+     * 收到 req：调用 onMessage 回调，回调的返回值（含 Promise）作为回复内容。
+     * 多个回调并发执行，取注册顺序中第一个非 undefined 的返回值回复。
+     */
+    private _serveReq;
+    /** 收到 res：按 id 唤醒等待中的 send */
+    private _serveRes;
+    /** 底层发送：把信封投递到指定 webContentsId */
+    private _send;
+    /** 获取自身 webContentsId */
+    getId(): number | null;
+    /**
+     * 发送消息（请求），自动生成 id，等对端用相同 id 回复。
+     * 内部会先等待连接建立（握手完成）。
+     * @param data 任意业务数据
+     * @param options 本次超时(ms)，不传用实例默认值（默认 3000）
+     * @returns 对端回调返回的数据
+     */
+    send(data: any, options?: SendOptions): Promise<any>;
+    /**
+     * 监听收到的请求消息。回调的返回值（含 Promise）即回复内容。
+     * @returns 调用以取消监听
+     */
+    onMessage(handler: MessageHandler): () => void;
+}
+/**
+ * 工厂函数
+ * @param role 角色，省略时自动探测
+ * @param options 超时配置
+ */
+export declare function createBridge(role?: BridgeRole, options?: BridgeOptions): LightAppBridge;

package/dist/lightAppBridge.js

@@ -0,0 +1,335 @@
+/*!
+ * LightAppBridge —— 插件窗口(plugin)与轻应用窗口(lightapp)之间的双向通信 SDK
+ *
+ * 核心特性：
+ *   1. 连接建立：插件主动 connect() 发起握手，双向交换 webContentsId，确认连接后才能收发。
+ *   2. 请求/响应：基于 id 关联，对端 onMessage 回调的「返回值」带相同 id 回复。
+ *   3. SDK 标识：所有消息携带 __sdk 标识 + 版本号，隔离其它消息，防止混淆。
+ *
+ * 依赖（构造时校验，缺失直接抛异常，请确保依赖注入完成后再 new）：
+ *   - window.waltz.event.on        收消息
+ *   - window.worklink              发消息 / 取 webContentsId
+ *   - window.worklink.plugin.getContentContext  （仅 plugin 角色需要）
+ *
+ * 消息信封：
+ *   { __sdk: 'LightAppBridge', v: 1, id, type, data }
+ *   type ∈ 'hello' | 'ack' | 'req' | 'res'
+ */
+const SDK_ID = 'LightAppBridge'; // SDK 标识：所有消息携带，用于隔离其它消息
+const PROTOCOL_VERSION = 1; // 协议版本号
+const DEFAULT_TIMEOUT = 3000; // send 默认超时(ms)
+const DEFAULT_HANDSHAKE_TIMEOUT = 30000; // 握手超时(ms)
+const HELLO_RETRY_INTERVAL = 1000; // 插件 hello 重试间隔(ms)
+const genId = () => 'r_' + Date.now().toString(36) + '_' + Math.random().toString(36).slice(2, 7);
+/** 判断是否为本 SDK 的消息（按 __sdk 标识过滤） */
+const isBridgeMsg = (msg) => !!(msg && typeof msg === 'object' && msg.__sdk === SDK_ID);
+/** 创建一个可外部 resolve 的 Promise */
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+/**
+ * 统一获取同步调用方法。
+ * 插件窗口挂在 worklink.moduleMethodInvoker 上；轻应用窗口直接挂在 worklink 上。
+ */
+function getInvoke() {
+    const wl = window.worklink;
+    if (wl && wl.moduleMethodInvoker && wl.moduleMethodInvoker.invokeModuleMethodSync) {
+        return (...args) => wl.moduleMethodInvoker.invokeModuleMethodSync(...args);
+    }
+    if (wl && wl.invokeModuleMethodSync) {
+        return (...args) => wl.invokeModuleMethodSync(...args);
+    }
+    return null;
+}
+export default class LightAppBridge {
+    /**
+     * @param role 角色，省略时按 window.worklink.plugin 是否存在自动探测
+     * @param options 超时配置
+     * @throws 依赖未就绪时抛出（window.waltz / window.worklink）
+     */
+    constructor(role, options = {}) {
+        this._pending = new Map();
+        this._messageHandlers = [];
+        this._target = null;
+        this._peer = null;
+        this._connected = false;
+        this._connectStarted = false;
+        this._connectCbs = [];
+        this._helloTimer = null;
+        this._handshakeTimer = null;
+        this._started = false;
+        let r = role === 'plugin' || role === 'lightapp' ? role : 'lightapp';
+        if (role !== 'plugin' && role !== 'lightapp') {
+            const wl = window.worklink;
+            r = wl && wl.plugin ? 'plugin' : 'lightapp';
+        }
+        this.role = r;
+        this.timeout = options.timeout != null ? options.timeout : DEFAULT_TIMEOUT;
+        this.handshakeTimeout = options.handshakeTimeout != null ? options.handshakeTimeout : DEFAULT_HANDSHAKE_TIMEOUT;
+        // 连接 deferred：构造时即建立，保证轻应用收到 hello 也能 resolve（无需显式 connect）
+        this._connectDeferred = deferred();
+        this._connectPromise = this._connectDeferred.promise.then((peerId) => {
+            this._onConnected(peerId);
+            return peerId;
+        });
+        this._checkDeps(); // 依赖校验，缺失直接抛异常
+        this._bindListener(); // 绑定 native-call-js 监听
+        this.connect(); // 构造即自动发起握手
+    }
+    /** 校验依赖是否就绪，缺失抛出明确异常 */
+    _checkDeps() {
+        const w = window;
+        if (!(w.waltz && w.waltz.event) || typeof w.waltz.event.on !== 'function') {
+            throw new Error('LightAppBridge 依赖 window.waltz.event.on，当前环境不可用');
+        }
+        if (!getInvoke()) {
+            throw new Error('LightAppBridge 依赖 window.worklink.invokeModuleMethodSync，当前环境不可用');
+        }
+        if (this.role === 'plugin' && typeof (w.worklink.plugin && w.worklink.plugin.getContentContext) !== 'function') {
+            throw new Error('LightAppBridge(plugin) 依赖 window.worklink.plugin.getContentContext，当前环境不可用');
+        }
+    }
+    /** 绑定 native-call-js 监听 */
+    _bindListener() {
+        if (this._started)
+            return;
+        this._started = true;
+        window.waltz.event.on('native-call-js', (raw) => this._onRaw(raw));
+    }
+    /** 构造消息信封 */
+    _envelope(type, data, id = genId()) {
+        return { __sdk: SDK_ID, v: PROTOCOL_VERSION, id, type, data };
+    }
+    /** 处理一条原生消息 */
+    _onRaw(raw) {
+        if (!raw || !raw.body || raw.body.eventName !== 'plugin-message')
+            return;
+        const params = raw.body.params || {};
+        const envelope = params.message;
+        const fromId = params.fromWebContentsId != null ? params.fromWebContentsId : null;
+        if (!isBridgeMsg(envelope))
+            return;
+        switch (envelope.type) {
+            case 'hello':
+                this._onHello(fromId);
+                break;
+            case 'ack':
+                this._onAck(fromId);
+                break;
+            case 'req':
+                this._recordPeer(fromId);
+                this._serveReq(envelope);
+                break;
+            case 'res':
+                this._serveRes(envelope);
+                break;
+        }
+    }
+    // —— 连接 / 握手 —— //
+    /**
+     * 建立连接（握手）。构造时已自动调用，通常无需手动调；如需重新握手可再次调用。
+     *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack）
+     *   - 轻应用：启动握手等待（被动等 hello；若插件始终未来则超时）
+     * 多次调用幂等，返回同一个连接 Promise。
+     * @returns 对端 webContentsId
+     */
+    connect() {
+        if (this._connectStarted)
+            return this._connectPromise;
+        this._connectStarted = true;
+        // 握手超时保护
+        this._handshakeTimer = setTimeout(() => {
+            if (!this._connected) {
+                this._connectDeferred.reject(new Error(`握手超时 (${this.handshakeTimeout}ms)，对端未响应`));
+                this._clearHelloTimer();
+            }
+        }, this.handshakeTimeout);
+        if (this.role === 'plugin') {
+            // 插件：解析目标后发 hello，并重试直到收到 ack
+            ;
+            window.worklink.plugin.getContentContext()
+                .then((ctx) => {
+                if (!ctx || ctx.webContentsId == null) {
+                    throw new Error('getContentContext 未返回 webContentsId');
+                }
+                this._target = ctx.webContentsId;
+                this._sendHello();
+                this._helloTimer = setInterval(() => {
+                    if (!this._connected)
+                        this._sendHello();
+                }, HELLO_RETRY_INTERVAL);
+            })
+                .catch((e) => this._connectDeferred.reject(e));
+        }
+        // lightapp 被动等待 hello（listener 已绑定），收到后在 _onHello 中回 ack 并 resolve
+        return this._connectPromise;
+    }
+    /** 发送 hello（携带自身 webContentsId） */
+    _sendHello() {
+        if (this._target == null)
+            return;
+        this._send(this._target, this._envelope('hello', { from: this.getId() }));
+    }
+    /** 收到 hello（轻应用侧）：记录对端、回 ack、完成握手 */
+    _onHello(fromId) {
+        if (fromId != null)
+            this._recordPeer(fromId);
+        // 回 ack，携带自身 webContentsId
+        if (fromId != null)
+            this._send(fromId, this._envelope('ack', { from: this.getId() }));
+        // 握手完成（resolve 幂等，重复 hello 只回 ack）
+        this._connectDeferred.resolve(fromId);
+    }
+    /** 收到 ack（插件侧）：确认连接 */
+    _onAck(fromId) {
+        this._recordPeer(fromId);
+        this._connectDeferred.resolve(fromId);
+    }
+    _recordPeer(fromId) {
+        if (fromId != null)
+            this._peer = fromId;
+    }
+    _onConnected(peerId) {
+        this._connected = true;
+        this._clearHelloTimer();
+        if (this._handshakeTimer) {
+            clearTimeout(this._handshakeTimer);
+            this._handshakeTimer = null;
+        }
+        // 触发 onConnect 回调
+        const cbs = this._connectCbs.splice(0);
+        cbs.forEach((cb) => {
+            try {
+                cb(peerId);
+            }
+            catch { /* ignore */ }
+        });
+    }
+    _clearHelloTimer() {
+        if (this._helloTimer) {
+            clearInterval(this._helloTimer);
+            this._helloTimer = null;
+        }
+    }
+    /** 监听连接建立（握手完成）。若已连接则立即触发 */
+    onConnect(cb) {
+        if (this._connected)
+            cb(this._peer);
+        else
+            this._connectCbs.push(cb);
+        return this;
+    }
+    /**
+     * 等待连接建立（握手完成）。构造时已自动发起握手，直接 await 即可。
+     * @returns 对端 webContentsId
+     */
+    ready() {
+        return this.connect();
+    }
+    // —— 请求/响应 —— //
+    /**
+     * 收到 req：调用 onMessage 回调，回调的返回值（含 Promise）作为回复内容。
+     * 多个回调并发执行，取注册顺序中第一个非 undefined 的返回值回复。
+     */
+    _serveReq(envelope) {
+        const { id, data } = envelope;
+        if (!this._messageHandlers.length)
+            return; // 无回调，发送端超时
+        const peerId = this._peer;
+        const results = this._messageHandlers.map((h) => Promise.resolve().then(() => h(data, id, peerId)).catch((e) => {
+            console.error('[LightAppBridge] onMessage handler error:', e);
+            return undefined;
+        }));
+        Promise.allSettled(results).then((settled) => {
+            for (const s of settled) {
+                if (s.status === 'fulfilled' && s.value !== undefined) {
+                    this._send(this._peer, this._envelope('res', s.value, id));
+                    return;
+                }
+            }
+        });
+    }
+    /** 收到 res：按 id 唤醒等待中的 send */
+    _serveRes(envelope) {
+        const p = this._pending.get(envelope.id);
+        if (!p)
+            return;
+        clearTimeout(p.timer);
+        this._pending.delete(envelope.id);
+        p.resolve(envelope.data);
+    }
+    /** 底层发送：把信封投递到指定 webContentsId */
+    _send(webContentsId, envelope) {
+        const invoke = getInvoke();
+        if (!invoke)
+            throw new Error('worklink.invokeModuleMethodSync 不可用');
+        if (webContentsId == null)
+            throw new Error('目标 webContentsId 为空，无法发送');
+        invoke('lightApp.pluginLightApp.sendMessageToPluginLightAppById', webContentsId, envelope);
+    }
+    /** 获取自身 webContentsId */
+    getId() {
+        const invoke = getInvoke();
+        if (!invoke)
+            return null;
+        const info = invoke('lightApp.pluginLightApp.getWebContentInfo');
+        return info && info.webContentsId != null ? info.webContentsId : null;
+    }
+    /**
+     * 发送消息（请求），自动生成 id，等对端用相同 id 回复。
+     * 内部会先等待连接建立（握手完成）。
+     * @param data 任意业务数据
+     * @param options 本次超时(ms)，不传用实例默认值（默认 3000）
+     * @returns 对端回调返回的数据
+     */
+    send(data, options = {}) {
+        const timeout = options.timeout != null ? options.timeout : this.timeout;
+        return this.ready().then((targetId) => {
+            const id = genId();
+            const envelope = this._envelope('req', data, id);
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    if (this._pending.has(id)) {
+                        this._pending.delete(id);
+                        reject(new Error(`请求超时 (${timeout}ms)`));
+                    }
+                }, timeout);
+                this._pending.set(id, { resolve, reject, timer });
+                try {
+                    this._send(targetId, envelope);
+                }
+                catch (e) {
+                    clearTimeout(timer);
+                    this._pending.delete(id);
+                    reject(e instanceof Error ? e : new Error(String(e)));
+                }
+            });
+        });
+    }
+    /**
+     * 监听收到的请求消息。回调的返回值（含 Promise）即回复内容。
+     * @returns 调用以取消监听
+     */
+    onMessage(handler) {
+        this._messageHandlers.push(handler);
+        return () => {
+            const i = this._messageHandlers.indexOf(handler);
+            if (i >= 0)
+                this._messageHandlers.splice(i, 1);
+        };
+    }
+}
+/**
+ * 工厂函数
+ * @param role 角色，省略时自动探测
+ * @param options 超时配置
+ */
+export function createBridge(role, options) {
+    return new LightAppBridge(role, options);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@jhh96/light-app-bridge",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "招商随行（WorkLink）插件窗口(plugin)与轻应用窗口(lightapp)之间的双向通信 SDK",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./lightAppBridge": {
+      "types": "./dist/lightAppBridge.d.ts",
+      "import": "./dist/lightAppBridge.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/fix-esm-extensions.mjs",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "typescript": "~5.6.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}