@aiot-nexus/plugin-sdk 2.0.1 → 2.1.0

package/README.md

@@ -1,14 +1,16 @@
 # @aiot-nexus/plugin-sdk
 
-> 版本适用性：当前包版本为 `2.0.1`，只面向 Framework API `2.0.0` 的 v2 worker/RPC 模型。1.x SDK 和同步 Host API 已停止适用，但其历史语义保留在本文末尾和 [v1 到 v2 迁移说明](../docs/plugin-framework-v1-v2-migration.md)；2.x 不提供 1.x 运行模型兼容层。
+> 版本适用性：当前包版本为 `2.1.0`，面向 Framework API `2.1.0` 的 v2 worker/RPC 模型，并兼容仍声明 `2.0.x` 的插件。1.x SDK 和同步 Host API 已停止适用，但其历史语义保留在本文末尾和 [v1 到 v2 迁移说明](../docs/plugin-framework-v1-v2-migration.md)；2.x 不提供 1.x 运行模型兼容层。
 
 AIoT Nexus 独立插件开发包，包含公开 TypeScript 契约、PluginFrame 浏览器客户端和 `nexus-plugin` 命令行工具。
 
+通信边界、`postMessage` 消息格式、`invokeMain` 请求/响应、分层超时和 worker 终止策略、长任务轮询示例见仓库文档：[插件 IPC 与事件通知示例](../docs/plugin-ipc-event-notification-example.md)。文件选择、Node 文件读写、插件窗口、IPC 和 Monaco worker 示例见 [Electron Facade 使用示例](../docs/plugin-electron-facade-examples.md)。Facade 的原生 Electron Event 首参是只读 `PluginElectronFacadeEventSnapshot`，不提供跨异步 RPC 无法成立的 `preventDefault()`。当前 SDK 提供 `onContextChanged()` 用于语言、主题和启动 context 更新，但不提供通用业务事件订阅 API。
+
 ## 环境
 
 - Node.js `>=16.20.0 <17`
 - npm `>=6.13.4`
-- 插件框架 API `2.0.0`
+- 插件框架 API `2.1.0`
 - manifest schema `1`
 
 ## 命令
@@ -37,7 +39,7 @@ SDK 提供两层非阻塞版本检查：
 - `nexus-plugin` 启动时先读取缓存。缓存新鲜期为 24 小时；缓存缺失或过期时在后台检查，不等待网络，不改变命令退出码。检测到普通更新时会显示：
 
   ```text
-  npm notice Update available for @aiot-nexus/plugin-sdk: 2.0.1 -> 2.1.0
+  npm notice Update available for @aiot-nexus/plugin-sdk: 2.1.0 -> 2.2.0
   npm notice Run npm install --save-dev @aiot-nexus/plugin-sdk@latest
   ```
 
@@ -66,7 +68,17 @@ nexus-plugin create my-frame-plugin \
 - 目标目录非空时命令以返回码 `2` 拒绝覆盖。生成或安装失败返回 `1`。
 - 两套模板均读取宿主 `PluginRendererContext.language` 和 `themeMode`，通过 `onContextChanged` 在同一 iframe 内响应运行时语言与主题切换，并内置 `zh-CN` / `en-US` renderer 文案；manifest 使用相同文化资源本地化宿主入口。模板页面自身不提供语言或主题选择控件。
 
-默认来源从 npm registry 安装。离线开发时先执行 `npm run pack:sdk`，再通过 `--sdk-source /path/to/aiot-nexus-plugin-sdk-2.0.1.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
+默认来源从 npm registry 安装。离线开发时先执行 `npm run pack:sdk`，再通过 `--sdk-source /path/to/aiot-nexus-plugin-sdk-2.1.0.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
+
+### SQLite 数据库浏览器模板
+
+`sqlite` 模板默认打开插件数据目录中的 `plugin.db`，并保留 `plugin_records` 示例表。工具栏中的“打开数据库”通过 worker 调用 `context.host.electron.dialog.showOpenDialog()`；普通插件无需 `electronHostControl`。iframe 只收到当前数据库信息和参数化业务 operation，不接收 Electron 对象，不提供路径输入、任意 SQL、DDL、`ATTACH` 或 SQL 控制台。外部数据库只在用户选择且通过 `sqlite_schema` 验证后以读写模式替换当前连接，取消或打开失败时继续使用原连接。
+
+最近选择的外部路径会原子写入插件数据目录的 `sqlite-browser-state.json`。下次启动会先尝试恢复；文件缺失、损坏或不再是 SQLite 时清除记录、回退 `plugin.db`，并在页面显示恢复提示。外部数据库不会执行示例表建表或 journal pragma。
+
+模板按 `table_list` / `table_xinfo` 动态显示普通用户表、列类型、SQLite affinity、主键、NULL、默认值和生成列。新增字段可选“使用默认值 / NULL / 输入值”，编辑字段可选“不修改 / NULL / 输入值”；INTEGER 使用精确十进制整数，REAL 必须有限，NUMERIC 可输入整数、浮点或文本，BLOB 输入偶数长度十六进制并按解码后的实际字节数计入 1 MiB/4 MiB 限制。普通 rowid 表优先用内建 rowid 定位；`WITHOUT ROWID` 表或 rowid 别名全部被遮蔽的表只回退到全部非空的单/复合主键。没有唯一 locator 的表仍可浏览和新增，但禁用编辑、删除；更新和删除在事务内要求恰好命中一行。表格中的 TEXT 预览最多 16 KiB，BLOB 只显示字节数和前 32 字节。
+
+该模板刻意不依赖 Quasar，以保持独立插件依赖最小化，因此数据库网格使用原生 `<table>`，这是宿主默认 `QTable` 规则之外的 SDK 模板例外。页面仍包含分页、横向表格滚动、中英文、亮暗主题、busy/empty/error 状态和窄窗口布局。
 
 ## 独立调试
 
@@ -79,8 +91,8 @@ npm run dev:debug
 ```
 
 - `npm run dev:web` 先运行模板独立的 `build:web`，只编译 Renderer 到 `.nexus-plugin-dev/web-package/<plugin-id>/`，再启动仅绑定 `127.0.0.1:4173` 的本地 HTTP 宿主并打开系统浏览器；它不执行 native rebuild、不复制原生运行时、不覆盖正式 `dist`，支持浏览器 DevTools 与源码映射。
-- 浏览器模式不加载 `mainEntry`，`invokeMain` 会返回 `PluginCapabilityUnsupported`；设置仅在本次服务进程内保存，日志输出到 CLI。涉及插件 worker、SQLite 或 Host API 时使用 `npm run dev`。
-- `npm run dev` 先构建和校验插件，再使用工程本地固定的 `electron@22.3.27` 启动 SDK 调试宿主；宿主渲染 UI，插件 `mainEntry` 在独立 `utilityProcess` worker 中加载，Renderer DevTools 默认自动打开。
+- 浏览器模式不加载 `mainEntry`，不创建插件 worker，也不提供 Electron Facade；`invokeMain` 会返回 `PluginCapabilityUnsupported`。设置仅在本次服务进程内保存，日志输出到 CLI。涉及插件 worker、SQLite、Node 或 Electron 时使用 `npm run dev`。
+- `npm run dev` 先构建和校验插件，再使用工程本地固定的 `electron@22.3.27` 启动 SDK 调试宿主；宿主渲染 UI，插件 `mainEntry` 在独立 `utilityProcess` worker 中加载，并使用与正式 Nexus 相同的 Electron Facade client、wire codec、Broker、权限分层和资源清理逻辑。Renderer DevTools 默认自动打开。
 - Electron 调试宿主的 `host.hostVersion` 默认是 SDK 构建时记录的 Nexus 应用版本；使用 `nexus-plugin dev . --host-version <X.Y.Z>` 可模拟其他应用版本，并按 manifest `minHostVersion` 拒绝不兼容组合。
 - `npm run dev:debug` 额外把 `--inspect-brk=9229` 传给插件 worker，可在 `src/main.ts` 激活阶段命中断点；宿主 UI 仍保持可启动。
 - 生成工程包含 `.vscode/launch.json`。在 VS Code 中选择 `Debug Nexus plugin` 可直接启动；若本机关闭了子进程自动附加，则先运行 `npm run dev:debug`，再选择 `Attach Nexus plugin worker (9229)`。renderer 断点在自动打开的 DevTools `Sources` 中设置。
@@ -101,7 +113,7 @@ nexus-plugin dev [plugin-project-directory]
   [--no-devtools]
 ```
 
-调试宿主工具栏中的语言和主题选择器用于模拟 Nexus 主框架 context，不属于插件页面。切换后调试宿主向同一 iframe 重发框架 `2.0.0` 的 `init` 消息；SDK 将后续 `init` 作为 context 更新并原地刷新语言和主题，同时仍接受可选的 `context-changed` 消息。调试宿主还复用正式的 `nexus-plugin://` 资源协议、iframe sandbox、CSP、消息结构、operation 校验以及当前 Host API 权限语义，但不包含 Nexus 的完整页面路由、Pinia 状态和应用级功能。`mainEntry` 的激活、deactivate、Host API 请求和 renderer operation 调用都通过异步 RPC 连接 worker；交付前仍需把 `dist/<plugin-id>/` 放入正式 Nexus 完成集成验证。
+调试宿主工具栏中的语言和主题选择器用于模拟 Nexus 主框架 context，不属于插件页面。切换后调试宿主向同一 iframe 重发框架 `2.1.0` 的 `init` 消息；SDK 将后续 `init` 作为 context 更新并原地刷新语言和主题，同时仍接受可选的 `context-changed` 消息。调试宿主还复用正式的 `nexus-plugin://` 资源协议、iframe sandbox、CSP、消息结构、operation 校验、Electron Facade 和当前 Host API 权限语义，但不包含 Nexus 的完整页面路由、Pinia 状态和应用级功能。`mainEntry` 的激活、deactivate、Host API 请求和 renderer operation 调用都通过异步 RPC 连接 worker；交付前仍需把 `dist/<plugin-id>/` 放入正式 Nexus 完成集成验证。
 
 浏览器 UI 命令支持 `--no-build`、`--no-open`、`--port <port>`，以及与 Electron 调试宿主相同的 `--language`、`--theme`、`--surface` 和 `--contribution-id` 参数。它使用普通 `http://127.0.0.1` iframe，不模拟 `nexus-plugin://` 协议或 Electron sandbox，因此只作为 UI 开发入口。Renderer-only 输出不会覆盖正式插件制品。
 

package/dev-host/main.js

@@ -5,6 +5,16 @@ const fs = require("fs");
 const path = require("path");
 const { app, BrowserWindow, ipcMain, protocol, utilityProcess } = require("electron");
 const sdk = require(path.join(__dirname, "..", "dist", "src", "index.js"));
+const { PluginElectronFacadeBrokerService } = require(path.join(
+  __dirname,
+  "..",
+  "dist",
+  "internal",
+  "src-electron",
+  "main",
+  "plugins",
+  "plugin-electron-facade-broker.js"
+));
 
 const pluginRendererProtocol = "nexus-plugin";
 const ipcChannels = {
@@ -12,10 +22,13 @@ const ipcChannels = {
   invoke: "nexus-plugin-dev:invoke",
   frameReady: "nexus-plugin-dev:frame-ready"
 };
-const pluginPermissions = ["businessLog", "settings", "filesystem", "udp", "serial", "externalProcess", "dialog"];
+const pluginPermissions = ["businessLog", "settings", "filesystem", "udp", "serial", "externalProcess", "dialog", "electronHostControl"];
 const implementedPermissions = new Set(["businessLog", "settings"]);
+const hostControlPermissions = new Set(["electronHostControl"]);
 const routeGuardPermissions = new Set(["filesystem", "udp", "serial", "dialog"]);
-const workerProtocolVersion = 2;
+const workerProtocolVersion = 3;
+const workerOperationTimeoutMs = 15000;
+const electronFacadeBroker = new PluginElectronFacadeBrokerService();
 
 protocol.registerSchemesAsPrivileged([
   {
@@ -73,6 +86,7 @@ app.on("before-quit", function waitForPluginWorkerShutdown(event) {
       process.stderr.write("[nexus-plugin-dev] plugin worker shutdown failed: " + errorMessage(error) + "\n");
     })
     .finally(function finishPluginWorkerShutdown() {
+      electronFacadeBroker.disposePlugin(configuration.manifest.pluginId);
       workerShutdownComplete = true;
       app.quit();
     });
@@ -174,7 +188,7 @@ function resolvePluginRendererFile(url) {
     path: realPath,
     mimeType: mimeType(realPath),
     headers: {
-      "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'",
+      "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; worker-src 'self' blob:; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'",
       "X-Content-Type-Options": "nosniff"
     }
   });
@@ -185,7 +199,19 @@ async function startPluginWorker() {
     return;
   }
   pluginWorker = new PluginWorkerClient(configuration);
-  const ready = await pluginWorker.start();
+  electronFacadeBroker.attachPlugin(configuration.manifest.pluginId, {
+    pluginDirectory: configuration.packageDirectory,
+    hostControl: configuration.manifest.permissions.includes("electronHostControl"),
+    invokeCallback: (callbackId, args) => pluginWorker.invokeElectronCallback(callbackId, args),
+    emitEvent: (callbackId, args) => pluginWorker.emitElectronEvent(callbackId, args)
+  });
+  let ready;
+  try {
+    ready = await pluginWorker.start();
+  } catch (error) {
+    electronFacadeBroker.disposePlugin(configuration.manifest.pluginId);
+    throw error;
+  }
   process.stdout.write(
     "[nexus-plugin-dev] activated " + configuration.manifest.pluginId
     + " with " + String(ready.operations.length) + " renderer operation(s).\n"
@@ -263,16 +289,89 @@ class PluginWorkerClient {
     }
     const requestId = this.nextRequestId("invoke");
     return new Promise((resolve) => {
-      this.pending.set(requestId, { kind: "invoke", resolve });
+      const pending = {
+        kind: "invoke",
+        resolve,
+        timer: setTimeout(() => {
+          if (this.pending.get(requestId) !== pending) {
+            return;
+          }
+          this.pending.delete(requestId);
+          pending.timer = undefined;
+          this.ready = false;
+          resolve(fail("PluginOperationTimeout", "Plugin worker operation timed out.", {
+            pluginId: this.configuration.manifest.pluginId,
+            operation: payload.operation,
+            timeoutMs: workerOperationTimeoutMs
+          }));
+          this.kill();
+        }, workerOperationTimeoutMs)
+      };
+      this.pending.set(requestId, pending);
       try {
         this.post({ protocolVersion: workerProtocolVersion, type: "invoke", requestId, payload });
       } catch (error) {
         this.pending.delete(requestId);
+        clearPendingTimer(pending);
         resolve(fail("PluginWorkerExited", "Plugin worker request could not be sent.", errorMessage(error)));
       }
     });
   }
 
+  invokeElectronCallback(callbackId, args) {
+    if (!this.child) {
+      return Promise.resolve(fail("PluginProcessNotReady", "Plugin worker is not available for Electron callback."));
+    }
+    const requestId = this.nextRequestId("electron-callback");
+    return new Promise((resolve) => {
+      const pending = {
+        kind: "electronCallback",
+        resolve,
+        timer: setTimeout(() => {
+          if (this.pending.get(requestId) !== pending) {
+            return;
+          }
+          this.pending.delete(requestId);
+          pending.timer = undefined;
+          resolve(fail("PluginOperationTimeout", "Electron facade callback timed out.", {
+            pluginId: this.configuration.manifest.pluginId,
+            callbackId,
+            timeoutMs: workerOperationTimeoutMs
+          }));
+        }, workerOperationTimeoutMs)
+      };
+      this.pending.set(requestId, pending);
+      try {
+        this.post({
+          protocolVersion: workerProtocolVersion,
+          type: "electronCallback",
+          requestId,
+          payload: { callbackId, args }
+        });
+      } catch (error) {
+        this.pending.delete(requestId);
+        clearPendingTimer(pending);
+        resolve(fail("PluginProcessExited", "Electron facade callback could not be sent.", errorMessage(error)));
+      }
+    });
+  }
+
+  emitElectronEvent(callbackId, args) {
+    if (!this.child) {
+      return false;
+    }
+    try {
+      this.post({
+        protocolVersion: workerProtocolVersion,
+        type: "electronEvent",
+        payload: { callbackId, args }
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   shutdown(reason) {
     this.intentionalStop = true;
     if (!this.child) {
@@ -340,7 +439,7 @@ class PluginWorkerClient {
         this.handleProtocolViolation("Plugin worker Host API request id is invalid.");
         return;
       }
-      const result = await handlePluginHostRequest(this.configuration, message.payload);
+      const result = normalizeRpcResult(await handlePluginHostRequest(this.configuration, message.payload));
       try {
         this.post({ protocolVersion: workerProtocolVersion, type: "hostResult", requestId: message.requestId, result });
       } catch {
@@ -357,7 +456,12 @@ class PluginWorkerClient {
       if (!pending) {
         return;
       }
+      if (pending.kind === "electronCallback") {
+        this.handleProtocolViolation("Plugin worker used a normal result for an Electron callback.");
+        return;
+      }
       this.pending.delete(message.requestId);
+      clearPendingTimer(pending);
       if (pending.kind === "shutdown") {
         clearTimeout(this.shutdownTimer);
         this.shutdownTimer = undefined;
@@ -370,6 +474,24 @@ class PluginWorkerClient {
       pending.resolve(message.result);
       return;
     }
+    if (message.type === "electronCallbackResult") {
+      if (!isWorkerRequestId(message.requestId) || !isNexusResult(message.result)) {
+        this.handleProtocolViolation("Plugin worker Electron callback result is invalid.");
+        return;
+      }
+      const pending = this.pending.get(message.requestId);
+      if (!pending) {
+        return;
+      }
+      if (pending.kind !== "electronCallback") {
+        this.handleProtocolViolation("Plugin worker used an Electron callback result for another request.");
+        return;
+      }
+      this.pending.delete(message.requestId);
+      clearPendingTimer(pending);
+      pending.resolve(message.result);
+      return;
+    }
     if (message.type === "fatal") {
       const error = new Error(isRecord(message.payload) && typeof message.payload.message === "string" ? message.payload.message : "Plugin worker failed.");
       if (this.startPromise) {
@@ -384,6 +506,7 @@ class PluginWorkerClient {
   }
 
   handleExit(code) {
+    electronFacadeBroker.disposePlugin(this.configuration.manifest.pluginId);
     this.child = undefined;
     this.ready = false;
     this.initializationRequestId = undefined;
@@ -398,6 +521,7 @@ class PluginWorkerClient {
       this.failStart(new Error(result.error.message));
     }
     for (const pending of this.pending.values()) {
+      clearPendingTimer(pending);
       pending.resolve(result);
     }
     this.pending.clear();
@@ -445,6 +569,13 @@ class PluginWorkerClient {
   }
 }
 
+function clearPendingTimer(pending) {
+  if (pending && pending.timer) {
+    clearTimeout(pending.timer);
+    pending.timer = undefined;
+  }
+}
+
 function readWorkerMessage(message) {
   return isRecord(message) && Object.prototype.hasOwnProperty.call(message, "data") ? message.data : message;
 }
@@ -455,6 +586,9 @@ async function handlePluginHostRequest(workerConfiguration, request) {
   }
   const manifest = workerConfiguration.manifest;
   const params = isRecord(request.params) ? request.params : undefined;
+  if (request.method === "electronFacade") {
+    return electronFacadeBroker.invoke(manifest.pluginId, params);
+  }
   if (request.method === "getCapabilityStatus") {
     return isPluginPermission(params && params.permission)
       ? ok(createPermissionSummary(params.permission))
@@ -801,7 +935,7 @@ function appendLog(level, category, message, exception) {
     level,
     category,
     message,
-    exception
+    ...(exception ? { exception } : {})
   };
   const output = "[nexus-plugin-dev][" + String(level) + "][" + category + "] " + String(message)
     + (exception ? "\n" + exception : "") + "\n";
@@ -850,6 +984,23 @@ function isNexusResult(value) {
     : isRecord(value.error) && typeof value.error.code === "string" && typeof value.error.message === "string";
 }
 
+function normalizeRpcResult(result) {
+  if (!isNexusResult(result)) {
+    return fail("UnexpectedFailure", "Plugin Host API returned an invalid result.");
+  }
+  if (result.ok) {
+    return { ok: true, value: sanitizeJsonValue(result.value) };
+  }
+  return {
+    ok: false,
+    error: {
+      code: result.error.code,
+      message: result.error.message,
+      ...(result.error.details === undefined ? {} : { details: sanitizeJsonValue(result.error.details) })
+    }
+  };
+}
+
 function isWorkerRequestId(value) {
   return typeof value === "string"
     && value.length > 0
@@ -862,6 +1013,9 @@ function isPluginPermission(value) {
 }
 
 function permissionSupportState(permission) {
+  if (hostControlPermissions.has(permission)) {
+    return "hostControl";
+  }
   if (implementedPermissions.has(permission)) {
     return "implemented";
   }
@@ -875,6 +1029,8 @@ function createPermissionSummary(permission) {
   const supportState = permissionSupportState(permission);
   const statusMessage = supportState === "implemented"
     ? "Available to trusted mainEntry Host API."
+    : supportState === "hostControl"
+      ? "Grants direct control of Nexus Electron host objects; global changes can affect the application and may not be reversible."
     : supportState === "routeGuard"
       ? "Declared for renderer route guards; not exposed to trusted mainEntry Host API."
       : "Reserved for a future Host API; trusted mainEntry calls return PluginCapabilityUnsupported.";
@@ -997,7 +1153,7 @@ function ok(value) {
 }
 
 function fail(code, message, details) {
-  return { ok: false, error: { code, message, details } };
+  return { ok: false, error: { code, message, ...(details === undefined ? {} : { details }) } };
 }
 
 function failStartup(error) {