@aiot-nexus/plugin-sdk 2.0.0 → 2.0.2

package/README.md

@@ -1,7 +1,11 @@
 # @aiot-nexus/plugin-sdk
 
+> 版本适用性：当前包版本为 `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`
@@ -35,7 +39,7 @@ SDK 提供两层非阻塞版本检查：
 - `nexus-plugin` 启动时先读取缓存。缓存新鲜期为 24 小时；缓存缺失或过期时在后台检查，不等待网络，不改变命令退出码。检测到普通更新时会显示：
 
   ```text
-  npm notice Update available for @aiot-nexus/plugin-sdk: 2.0.0 -> 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
   ```
 
@@ -64,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.0.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
+默认来源从 npm registry 安装。离线开发时先执行 `npm run pack:sdk`，再通过 `--sdk-source /path/to/aiot-nexus-plugin-sdk-2.0.2.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
 
 ## 独立调试
 
@@ -117,6 +121,21 @@ npm run dev:nexus -- --host D:\prj\tmp\aiot-nexus\dist\electron\nexus-win32-x64\
 | --- | --- |
 | `src/renderer/**` | 只运行 `build:web` 并替换 renderer；宿主 PID 不变，iframe 重新完成 `ready/init`。 |
 | `src/manifest.json` 的展示、贡献点等安全字段 | 构建 renderer、原子替换 manifest 后重扫插件目录；宿主 PID 不变。 |
-| `src/main.ts`、依赖、原生模块或主进程相关 manifest 字段 | 完整构建成功后先停止插件 worker，原子替换完整插件包，再在同一 Nexus 进程中启动新 worker；宿主 PID 不变。 |
+| `src/main.ts`、依赖、原生模块或 worker 相关 manifest 字段 | 完整构建成功后先停止插件 worker，原子替换完整插件包，再在同一 Nexus 进程中启动新 worker；宿主 PID 不变。 |
 
 更新构建或 worker 重载失败时保留上一个可运行部署，并回滚插件包后重新激活旧 worker。`mainEntry` 不通过清理 `require.cache` 热替换；每次包更新都执行 `deactivate`、替换包和新的 worker 激活，但不重启整个 Nexus。默认打开 Renderer DevTools；可传 `--no-devtools`。`--inspect[=<port>]` 和 `--inspect-brk[=<port>]` 调试的是插件 worker，贡献点选择支持 `--surface` 与 `--contribution-id`。按 `Ctrl+C` 停止 CLI 时，CLI 会先请求插件 worker 关闭，再关闭其启动的正式宿主。
+
+## v1 SDK 历史说明（不适用于当前包）
+
+SDK 1.x 对应 Framework API `1.0.0`：`mainEntry` 在 Electron 主进程中加载，Host API 直接返回同步 `NexusResult<T>`，完整插件包变化需要重启 Nexus。旧离线包名使用 `aiot-nexus-plugin-sdk-1.1.1.tgz`，旧调试目标是 `Attach Nexus plugin main (9229)`。
+
+| v1 项目 | 历史行为 | v2 替代 |
+| --- | --- | --- |
+| `npm run dev` | Electron 调试宿主在主进程加载 `mainEntry` | 调试宿主创建独立插件 worker |
+| `npm run dev:debug` | `--inspect-brk=9229` 暂停 Electron 主进程 | inspect 端口连接插件 worker，宿主 UI 可独立启动 |
+| `npm run dev:nexus` 完整包变化 | 退出旧 Nexus、替换包、启动新 Nexus，PID 改变 | 停止目标 worker、替换包、启动新 worker，Nexus PID 不变 |
+| Host API 调用 | 直接获得 `NexusResult<T>` | `await` `Promise<NexusResult<T>>` |
+| Renderer-only 调试 | 不执行 `mainEntry`，`invokeMain` 返回 unsupported | 该限制在 v2 继续成立 |
+| 更新失败 | 恢复旧包并重新启动宿主 | 恢复旧包和旧 worker，不重启 Nexus |
+
+这些约定只用于阅读旧插件和历史报告。迁移到当前 SDK 时必须把 manifest 升到 2.x、异步等待 Host API、实现资源关闭，并改用插件 worker 调试和生命周期；不能只修改 npm 包版本而保留同步调用。

package/dev-host/host.html

@@ -115,6 +115,8 @@
       }
 
       .frame-shell {
+        display: flex;
+        flex-direction: column;
         flex: 1 1 auto;
         min-width: 0;
         padding: 12px;
@@ -123,6 +125,7 @@
 
       iframe {
         display: block;
+        flex: 1 1 auto;
         width: 100%;
         min-height: 360px;
         border: 1px solid var(--border);

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.0";
+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.0";
+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.0",
+  "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.

package/templates/sqlite/src/renderer/index.html

@@ -36,7 +36,7 @@
         <p id="formError" class="error" hidden></p>
       </section>
 
-      <section class="panel">
+      <section class="panel recent-rows-panel">
         <div class="panel-heading">
           <h2 data-i18n="section.recentRows">Recent Rows</h2>
           <span id="statusLog" data-i18n="status.idle">Idle</span>

package/templates/sqlite/src/renderer/plugin.css

@@ -15,13 +15,15 @@
 
 body {
   margin: 0;
-  min-height: 0;
+  min-height: 100vh;
   background: #f3f5f7;
 }
 
 .plugin-shell {
   display: grid;
+  grid-template-rows: auto auto auto minmax(0, 1fr);
   gap: 12px;
+  min-height: 100vh;
   padding: 16px;
 }
 
@@ -100,6 +102,17 @@ h2 {
   padding: 14px 16px;
 }
 
+.recent-rows-panel {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.recent-rows-panel .table-wrap {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
 .entry-form {
   display: grid;
   grid-template-columns: minmax(150px, 1fr) minmax(220px, 2fr) auto;