@jhh96/light-app-bridge 1.2.0 → 1.3.0

package/dist/index.d.ts

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

package/dist/lightAppBridge.d.ts

@@ -30,6 +30,17 @@ export type BridgeRole = 'plugin' | 'lightapp';
  *             向新窗口探测握手（成功即切换绑定；失败——如未集成 SDK——保持旧绑定）。
  */
 export type BindMode = 'fixed' | 'dynamic';
+/**
+ * 指令执行结果的上报模式（轻应用角色语义声明，默认 'plugin'）：
+ *   - plugin 默认。轻应用不在本窗口回传 ai-controller，执行结果随 reply 返回
+ *             插件窗口，由插件统一上报。reply 无需额外字段。
+ *   - self   轻应用业务自行 POST ai-controller/callback（如需 AI 闭环），
+ *             并在 onMessage 的 reply 上带 result_reported: true，
+ *             插件据此跳过补报，避免双重上报。
+ * 纯语义声明：SDK 不执行上报，读取方是插件侧业务代码（经 reply 字段判定），
+ * 两 SDK 间零依赖。
+ */
+export type ReportMode = 'plugin' | 'self';
 /** 信封类型 */
 export type EnvelopeType = 'hello' | 'ack' | 'req' | 'res' | 'ping' | 'pong';
 /** 消息信封：所有跨窗口通信的统一包装 */
@@ -51,6 +62,13 @@ export interface BridgeOptions {
      * dynamic：轮询 getContentContext 跟随当前激活的轻应用窗口切换绑定。
      */
     bindMode?: BindMode;
+    /**
+     * 结果上报模式（轻应用角色语义声明），默认 'plugin'：
+     * 'plugin'=结果交插件统一上报（reply 无需额外字段）；
+     * 'self'=业务自行上报并在 reply 带 result_reported: true。
+     * SDK 不执行上报，仅存为实例属性 reportMode 供业务读取。
+     */
+    reportMode?: ReportMode;
     /** dynamic 模式轮询 getContentContext 的间隔(ms)，默认 2000 */
     dynamicPollInterval?: number;
     /** dynamic 模式迁移探测窗口：向新窗口发 hello 等 ack 的时长(ms)，默认 3000 */
@@ -94,6 +112,7 @@ export default class LightAppBridge {
     timeout: number;
     handshakeTimeout: number;
     bindMode: BindMode;
+    reportMode: ReportMode;
     dynamicPollInterval: number;
     migrateProbeTimeout: number;
     pingInterval: number;
@@ -139,6 +158,28 @@ export default class LightAppBridge {
     constructor(role?: BridgeRole, options?: BridgeOptions);
     /** debug 日志（options.debug 开启时打印，前缀带角色便于双端对照） */
     private _log;
+    /**
+     * debug 模式下在 window 挂载控制台测试方法（挂在单一入口 __lightAppBridge 下，
+     * destroy 时注销）：
+     *
+     *   __lightAppBridge.send(data, timeout?) —— 以本实例身份向对端发一条请求，返回 Promise。
+     *     等价于业务代码里的 bridge.send(...)。
+     *       await __lightAppBridge.send({ action: 'ping' })
+     *       await __lightAppBridge.send({ action: 'scroll.to', payload: {...} }, 5000)
+     *
+     *   __lightAppBridge.inject(type, data?, fromId?, id?) —— 模拟对端来一条消息，直接喂给
+     *   本实例的消息分发入口（绕过原生投递层），无需真实对端窗口即可测试收发逻辑。
+     *   type 取信封类型：'hello' | 'ack' | 'req' | 'res' | 'ping'
+     *       __lightAppBridge.inject('ping')                     // 看本端自动回 pong
+     *       __lightAppBridge.inject('req', { action: 'test' })  // 触发本端 onMessage handler
+     *       __lightAppBridge.inject('hello', null, 42)          // 模拟 webContentsId=42 的对端握手
+     *       __lightAppBridge.inject('res', {ok:1}, 77, reqId)   // 回 res：第 4 参传原请求 id 配对唤醒
+     *
+     * 多实例同时开启 debug 时后注册者覆盖前者（控制台操作的是最后创建的实例）。
+     * 不挂实例本身（避免控制台误触内部状态）。
+     */
+    private _registerDebugHelpers;
+    private _debugCleanup;
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     private _checkDeps;
     /** 绑定消息监听：优先 waltz；无 waltz 时定义/包装 window.handleMessageFromNative */

package/dist/lightAppBridge.js

@@ -202,6 +202,7 @@ export default class LightAppBridge {
         this._probeOk = false; // 兜底探测是否收到 ack
         this._probeTimers = []; // 防 destroy 后悬挂
         this._disconnectCbs = [];
+        this._debugCleanup = null;
         let r = role === 'plugin' || role === 'lightapp' ? role : 'lightapp';
         if (role !== 'plugin' && role !== 'lightapp') {
             const wl = window.worklink;
@@ -211,6 +212,7 @@ export default class LightAppBridge {
         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.reportMode = options.reportMode === 'self' ? 'self' : 'plugin';
         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;
@@ -232,6 +234,7 @@ export default class LightAppBridge {
         });
         this._checkDeps(); // 依赖校验，缺失直接抛异常
         this._startListener(); // 绑定消息监听（waltz 或定义 handleMessageFromNative）
+        this._registerDebugHelpers(); // debug 模式：注册控制台测试方法
         this.connect(); // 构造即自动发起握手（内部会等监听就绪）
     }
     /** debug 日志（options.debug 开启时打印，前缀带角色便于双端对照） */
@@ -240,6 +243,58 @@ export default class LightAppBridge {
             return;
         console.log(`[LightAppBridge:${this.role}]`, ...args);
     }
+    // —— debug 控制台测试方法（options.debug 开启时挂 window）—— //
+    /**
+     * debug 模式下在 window 挂载控制台测试方法（挂在单一入口 __lightAppBridge 下，
+     * destroy 时注销）：
+     *
+     *   __lightAppBridge.send(data, timeout?) —— 以本实例身份向对端发一条请求，返回 Promise。
+     *     等价于业务代码里的 bridge.send(...)。
+     *       await __lightAppBridge.send({ action: 'ping' })
+     *       await __lightAppBridge.send({ action: 'scroll.to', payload: {...} }, 5000)
+     *
+     *   __lightAppBridge.inject(type, data?, fromId?, id?) —— 模拟对端来一条消息，直接喂给
+     *   本实例的消息分发入口（绕过原生投递层），无需真实对端窗口即可测试收发逻辑。
+     *   type 取信封类型：'hello' | 'ack' | 'req' | 'res' | 'ping'
+     *       __lightAppBridge.inject('ping')                     // 看本端自动回 pong
+     *       __lightAppBridge.inject('req', { action: 'test' })  // 触发本端 onMessage handler
+     *       __lightAppBridge.inject('hello', null, 42)          // 模拟 webContentsId=42 的对端握手
+     *       __lightAppBridge.inject('res', {ok:1}, 77, reqId)   // 回 res：第 4 参传原请求 id 配对唤醒
+     *
+     * 多实例同时开启 debug 时后注册者覆盖前者（控制台操作的是最后创建的实例）。
+     * 不挂实例本身（避免控制台误触内部状态）。
+     */
+    _registerDebugHelpers() {
+        if (!this._debug)
+            return;
+        const w = window;
+        const sendFn = (data, timeout) => {
+            // eslint-disable-next-line no-console
+            console.log(`[LightAppBridge:${this.role}] send→`, data);
+            return this.send(data, timeout != null ? { timeout } : undefined);
+        };
+        const injectFn = (type, data, fromId, id) => {
+            const envelope = this._envelope(type, data != null ? data : {}, id || genId() // res 场景必须传原请求 id 才能配对唤醒（未传则生成新 id，作为陌生 res 被忽略）
+            );
+            // eslint-disable-next-line no-console
+            console.log(`[LightAppBridge:${this.role}] inject←`, envelope);
+            this._onMessage({ envelope, fromWebContentsId: fromId != null ? fromId : 0 });
+        };
+        const facade = { send: sendFn, inject: injectFn };
+        const prev = w.__lightAppBridge; // 多实例 debug：保留被覆盖者的清理引用链
+        w.__lightAppBridge = facade;
+        // eslint-disable-next-line no-console
+        console.info(`[LightAppBridge:${this.role}] debug 方法已挂载: ` +
+            'await __lightAppBridge.send(data, timeout?) 发请求 / ' +
+            '__lightAppBridge.inject(type, data?, fromId?, id?) 模拟来消息');
+        this._debugCleanup = () => {
+            // 仅当仍是自己挂的 facade 才清理，避免误删后建实例的挂载
+            if (w.__lightAppBridge === facade)
+                delete w.__lightAppBridge;
+            else
+                w.__lightAppBridge = prev;
+        };
+    }
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     _checkDeps() {
         const w = window;
@@ -821,6 +876,14 @@ export default class LightAppBridge {
             catch { /* ignore */ }
             this._unlisten = null;
         }
+        // 注销 debug 控制台测试方法
+        if (this._debugCleanup) {
+            try {
+                this._debugCleanup();
+            }
+            catch { /* ignore */ }
+            this._debugCleanup = null;
+        }
         this._clearHelloTimer();
         this._stopDynamicPoll();
         this._stopPing();

package/package.json

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