@aiot-nexus/plugin-sdk 2.0.1 → 2.0.2

package/README.md

@@ -1,9 +1,11 @@
 # @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.0.2`，只面向 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 运行模型兼容层。
 
 AIoT Nexus 独立插件开发包，包含公开 TypeScript 契约、PluginFrame 浏览器客户端和 `nexus-plugin` 命令行工具。
 
+通信边界、`postMessage` 消息格式、`invokeMain` 请求/响应、分层超时和 worker 终止策略、长任务轮询示例见仓库文档：[插件 IPC 与事件通知示例](../docs/plugin-ipc-event-notification-example.md)。当前 SDK 提供 `onContextChanged()` 用于语言、主题和启动 context 更新，但不提供通用业务事件订阅 API。
+
 ## 环境
 
 - Node.js `>=16.20.0 <17`
@@ -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.0.2 -> 2.1.0
   npm notice Run npm install --save-dev @aiot-nexus/plugin-sdk@latest
   ```
 
@@ -66,7 +68,7 @@ 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.0.2.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
 
 ## 独立调试
 

package/dev-host/main.js

@@ -16,6 +16,7 @@ const pluginPermissions = ["businessLog", "settings", "filesystem", "udp", "seri
 const implementedPermissions = new Set(["businessLog", "settings"]);
 const routeGuardPermissions = new Set(["filesystem", "udp", "serial", "dialog"]);
 const workerProtocolVersion = 2;
+const workerOperationTimeoutMs = 15000;
 
 protocol.registerSchemesAsPrivileged([
   {
@@ -263,11 +264,30 @@ 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)));
       }
     });
@@ -358,6 +378,7 @@ class PluginWorkerClient {
         return;
       }
       this.pending.delete(message.requestId);
+      clearPendingTimer(pending);
       if (pending.kind === "shutdown") {
         clearTimeout(this.shutdownTimer);
         this.shutdownTimer = undefined;
@@ -398,6 +419,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 +467,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;
 }

package/dev-host/plugin-host.js

@@ -16,6 +16,7 @@ if (!port) {
 
 const operations = new Map();
 const pendingHostRequests = new Map();
+const inFlightOperations = new Set();
 let initialized = false;
 let ready = false;
 let shuttingDown = false;
@@ -56,7 +57,7 @@ async function handleMessage(message) {
     return;
   }
   if (message.type === "invoke") {
-    await invoke(message);
+    await invokeTracked(message);
     return;
   }
   if (message.type === "shutdown") {
@@ -162,12 +163,23 @@ async function invoke(message) {
   }
 }
 
+async function invokeTracked(message) {
+  const operation = invoke(message);
+  inFlightOperations.add(operation);
+  try {
+    await operation;
+  } finally {
+    inFlightOperations.delete(operation);
+  }
+}
+
 async function shutdown(message) {
   if (shuttingDown || !isWorkerRequestId(message.requestId)) {
     return;
   }
   shuttingDown = true;
   try {
+    await Promise.allSettled(Array.from(inFlightOperations));
     const deactivate = pluginModule && (typeof pluginModule.deactivate === "function"
       ? pluginModule.deactivate
       : pluginModule.default && typeof pluginModule.default.deactivate === "function"
@@ -262,7 +274,7 @@ function createHostApi() {
 }
 
 function requestHost(method, params) {
-  if (exiting || shuttingDown) {
+  if (exiting) {
     return Promise.resolve(fail("PluginWorkerExited", "Plugin worker is stopping."));
   }
   const requestId = pluginId + "-host-" + String(++requestSequence);

package/dist/browser/frame-client.mjs

@@ -4,7 +4,7 @@ const readyMessageType = "nexus-plugin:ready";
 const requestMessageType = "nexus-plugin:request";
 const responseMessageType = "nexus-plugin:response";
 const resizeMessageType = "nexus-plugin:resize";
-const defaultRequestTimeoutMs = 15000;
+const defaultRequestTimeoutMs = 20000;
 export class PluginFrameClientError extends Error {
     constructor(code, message) {
         super(message);

package/dist/src/browser/frame-client.js

@@ -7,7 +7,7 @@ const readyMessageType = "nexus-plugin:ready";
 const requestMessageType = "nexus-plugin:request";
 const responseMessageType = "nexus-plugin:response";
 const resizeMessageType = "nexus-plugin:resize";
-const defaultRequestTimeoutMs = 15000;
+const defaultRequestTimeoutMs = 20000;
 class PluginFrameClientError extends Error {
     constructor(code, message) {
         super(message);

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 import pluginManifestSchema from "../.generated/plugin-manifest.schema.json";
-export declare const PLUGIN_SDK_VERSION = "2.0.1";
+export declare const PLUGIN_SDK_VERSION = "2.0.2";
 export { pluginManifestSchema };
 export * from "../.generated/plugin-framework-version";
 export * from "./types";

package/dist/src/index.js

@@ -20,7 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pluginManifestSchema = exports.PLUGIN_SDK_VERSION = void 0;
 const plugin_manifest_schema_json_1 = __importDefault(require("../.generated/plugin-manifest.schema.json"));
 exports.pluginManifestSchema = plugin_manifest_schema_json_1.default;
-exports.PLUGIN_SDK_VERSION = "2.0.1";
+exports.PLUGIN_SDK_VERSION = "2.0.2";
 __exportStar(require("../.generated/plugin-framework-version"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./browser/frame-client"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiot-nexus/plugin-sdk",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Types, PluginFrame client, and CLI for AIoT Nexus independent plugins.",
   "license": "UNLICENSED",
   "publishConfig": {

package/templates/minimal/README.md.tmpl

@@ -21,6 +21,8 @@ The renderer calls the plugin-worker `demo.echo` operation through `@aiot-nexus/
 
 The renderer follows `context.language` and `context.themeMode` from Nexus, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host and simulate Nexus context changes. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
+The current SDK has no generic business-event subscription API. For a long-running operation, register a fast `job.start` operation that returns a `taskId`, then expose `job.getStatus` and optional `job.cancel` for renderer polling. See the Nexus repository's plugin IPC and event notification example for the full contract and code.
+
 Use `npm run dev:web` for renderer-only UI work in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. It does not execute `mainEntry` or overwrite the deployable `dist` package. Language and theme controls still simulate Nexus context, while `invokeMain` is intentionally unavailable. Pass `-- --no-open` or `-- --port <port>` when needed; use `npm run dev` for Host API integration.
 
 Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` for live development against a compiled, packaged Nexus. The CLI atomically deploys this plugin to `<exeDir>/Plugins/__PLUGIN_ID__/`. Renderer changes rebuild and reload the iframe without changing the Nexus PID; safe manifest changes rescan contributions in the same process; `mainEntry`, dependency, native-module, or worker-sensitive manifest changes rebuild the full package, stop the old plugin worker, replace the package, and start a new worker while keeping the Nexus PID. Failed builds keep the previous deployment; a failed worker reload rolls the package back and restores the previous worker. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.

package/templates/sqlite/README.md.tmpl

@@ -21,6 +21,8 @@ The deployable plugin package is `dist/__PLUGIN_ID__/`. For a manual installatio
 
 The renderer follows `context.language` and `context.themeMode` from Nexus, subscribes to in-place context updates without reloading the iframe, and includes `en-US` and `zh-CN` message catalogs. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host and simulate Nexus context changes. Static labels, CRUD status messages, action buttons, validation text, and date formatting switch together. Edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
+The current SDK has no generic business-event subscription API. For a long-running operation, register a fast `job.start` operation that returns a `taskId`, then expose `job.getStatus` and optional `job.cancel` for renderer polling. See the Nexus repository's plugin IPC and event notification example for the full contract and code.
+
 Use `npm run dev:web` for renderer-only layout, styling, localization, and responsive checks in the system browser. It runs `build:web`, writes an isolated package under `.nexus-plugin-dev/web-package/`, and does not rebuild or load `better-sqlite3`, execute `mainEntry`, copy native runtime files, or overwrite the deployable `dist` package. It builds with source maps, serves only on `127.0.0.1:4173`, and opens the browser automatically. Database operations report unsupported; use `npm run dev` for SQLite and Host API integration. Pass `-- --no-open` or `-- --port <port>` when needed.
 
 Use `npm run dev:nexus -- --host C:\path\to\nexus.exe` to run the plugin inside a compiled, packaged Nexus. The initial deployment and every full package replacement are atomic. Renderer-only and safe manifest updates keep the Nexus PID; `mainEntry`, dependency, native-module, or worker-sensitive manifest changes run the complete build (including the Electron 22.3.27 native rebuild), stop the old plugin worker, replace the package, and start a new worker in the same Nexus process. The database remains under the host-provided plugin data directory across worker replacements. Failed builds keep the previous deployment, and a failed worker reload rolls the package back and restores the previous worker. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.