@aiot-nexus/plugin-sdk 3.3.1 → 3.3.2

package/README.md

@@ -1,6 +1,6 @@
 # @aiot-nexus/plugin-sdk
 
-> 当前 SDK 包版本为 `3.3.1`，Framework API 为 `3.2.0`，manifest schema 保持 `1`。Framework 3 将可信插件的 `mainEntry` 直接加载到 AIoT Toolkits Electron 主进程；它不是安全沙箱。PluginFrame iframe 仍保持 sandbox、无 Node/Electron 访问。宿主运行模型见 [Framework v3 架构](../docs/plugin-framework-v3-architecture.md)。
+> 当前 SDK 包版本为 `3.3.2`，Framework API 为 `3.2.0`，manifest schema 保持 `1`。Framework 3 将可信插件的 `mainEntry` 直接加载到 AIoT Toolkits Electron 主进程；它不是安全沙箱。PluginFrame iframe 仍保持 sandbox、无 Node/Electron 访问。宿主运行模型见 [Framework v3 架构](../docs/plugin-framework-v3-architecture.md)。
 
 本包提供公开 TypeScript 契约、PluginFrame 浏览器客户端和 `nexus-plugin` CLI。v2 项目升级前请先阅读 [v2 到 v3 迁移说明](../docs/plugin-framework-v2-v3-migration.md)。完整开发流程见 [独立插件开发指南](../docs/standalone-plugin-development-guide.md)。
 
@@ -13,7 +13,7 @@
 
 | 项目 | 固定值 |
 | --- | --- |
-| SDK | `3.3.1` |
+| SDK | `3.3.2` |
 | Framework API | `3.2.0` |
 | Manifest schema | `1` |
 | Node 安装和构建 | `>=16.20.0 <17` |
@@ -53,15 +53,15 @@ npm run publish:sdk
 registry 升级与只读预检：
 
 ```bash
-npx --package=@aiot-nexus/plugin-sdk@3.3.1 nexus-plugin upgrade . --check
-npx --package=@aiot-nexus/plugin-sdk@3.3.1 nexus-plugin upgrade .
+npx --package=@aiot-nexus/plugin-sdk@3.3.2 nexus-plugin upgrade . --check
+npx --package=@aiot-nexus/plugin-sdk@3.3.2 nexus-plugin upgrade .
 ```
 
 发布前或本地 tgz：
 
 ```bash
-npx --package=./aiot-nexus-plugin-sdk-3.3.1.tgz nexus-plugin upgrade . \
-  --sdk-source ./aiot-nexus-plugin-sdk-3.3.1.tgz
+npx --package=./aiot-nexus-plugin-sdk-3.3.2.tgz nexus-plugin upgrade . \
+  --sdk-source ./aiot-nexus-plugin-sdk-3.3.2.tgz
 ```
 
 CI 可以追加 `--json` 获得 `up-to-date`、`upgrade-available`、`upgraded`、`rolled-back` 或 `blocked`。`--allow-major` 只解除 major 保护，不会改写业务源码；跨 major 必须先阅读迁移指南。`--skip-project-checks` 只跳过项目 typecheck/build，安装后的 SDK、package 和 lockfile 一致性仍会验证。
@@ -72,7 +72,7 @@ CI 可以追加 `--json` 获得 `up-to-date`、`upgrade-available`、`upgraded`
 
 安装或项目验证失败时恢复备份，并在原 lockfile 存在时运行 `npm ci`。没有原 lockfile 时会运行 `npm install` 并恢复原 SDK，但无法证明完整传递依赖树与升级前一致，因此返回 `blocked` 并保留恢复数据。标准脚手架 build 的 `dist/<pluginId>` 在回滚范围内；自定义 typecheck/build 若修改其他路径，这些副作用不属于升级事务，项目必须自行管理。
 
-SDK `3.0.x` / `3.1.x` 插件可以由 3.2.x 宿主继续加载。升级到 SDK `3.2.0` 只提供主题能力和新的契约；插件必须引用 `--nexus-color-*` 或读取 `context.theme` 才会使用宿主主题色。没有引用新变量的插件保持原有颜色；需要自定义主题时传入 `autoApplyHostTheme: false`。原有 `hostApiVersion: 3.0.0` 可以保持不变，只有实际使用 `showHostStatusBar` 时才需要声明 `hostApiVersion: 3.1.0` 或更高。SDK 3.1.1 修复 registry 升级命令丢失 npm 包名的问题，SDK 3.3.0 将 `dev:nexus --host` 目录查找目标改为 `AIoT Toolkits.exe`，SDK 3.3.1 修复 npx 启动升级器时误用 `npx-cli.js` 执行 npm 命令的问题，均作为历史兼容说明保留。
+SDK `3.0.x` / `3.1.x` 插件可以由 3.2.x 宿主继续加载。升级到 SDK `3.2.0` 只提供主题能力和新的契约；插件必须引用 `--nexus-color-*` 或读取 `context.theme` 才会使用宿主主题色。没有引用新变量的插件保持原有颜色；需要自定义主题时传入 `autoApplyHostTheme: false`。原有 `hostApiVersion: 3.0.0` 可以保持不变，只有实际使用 `showHostStatusBar` 时才需要声明 `hostApiVersion: 3.1.0` 或更高。SDK 3.1.1 修复 registry 升级命令丢失 npm 包名的问题，SDK 3.3.0 将 `dev:nexus --host` 目录查找目标改为 `AIoT Toolkits.exe`，SDK 3.3.1 修复 npx 启动升级器时误用 `npx-cli.js` 执行 npm 命令的问题。SDK 3.3.2 是 `@aiot-nexus/plugin-sdk` 的最后一个发布版本：包名将迁移到 `@aiot-toolkits/plugin-sdk`（4.0.0 起，bin 双名过渡），迁移说明见 [插件 SDK 包名迁移说明](../docs/plugin-package-rename-migration.md)。均作为历史兼容说明保留。
 
 ## 创建插件
 
@@ -95,7 +95,7 @@ nexus-plugin create my-frame-plugin \
 
 ```bash
 npm run pack:sdk
-nexus-plugin create my-frame-plugin --sdk-source ./package/aiot-nexus-plugin-sdk-3.3.1.tgz --install
+nexus-plugin create my-frame-plugin --sdk-source ./package/aiot-nexus-plugin-sdk-3.3.2.tgz --install
 ```
 
 生成插件后，可以在 `src/manifest.json` 的业务入口中静态控制 AIoT Toolkits 宿主状态栏。相关 manifest 片段如下，其余必填字段沿用脚手架生成值：

package/dist/src/cli/update-notice.d.ts

@@ -17,4 +17,10 @@ export interface SdkUpdateCheckModule {
         currentVersion: string;
     }): SdkUpdateResult | null;
 }
+/**
+ * Bridge-release notice for the 3.3.2 -> 4.0.0 package rename.
+ * Remove the call site in cli.ts when publishing 4.0.0 under
+ * @aiot-toolkits/plugin-sdk.
+ */
+export declare function showSdkPackageRenameNotice(args: string[], stdout: (message: string) => void, isDisabled: (env: NodeJS.ProcessEnv) => boolean): void;
 export declare function showSdkUpdateNotice(args: string[], stdout: (message: string) => void, updateCheck: SdkUpdateCheckModule, currentVersion: string): void;

package/dist/src/cli/update-notice.js

@@ -1,6 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.showSdkUpdateNotice = void 0;
+exports.showSdkUpdateNotice = exports.showSdkPackageRenameNotice = void 0;
+const packageRenameNoticeLines = [
+    "@aiot-nexus/plugin-sdk is moving to @aiot-toolkits/plugin-sdk.",
+    "This 3.3.2 release is the final one published under the old package name.",
+    "Migrate with: npx --package=@aiot-toolkits/plugin-sdk@4.0.0 nexus-plugin upgrade . --allow-major",
+    "Migration guide: https://github.com/ke4nec/aiot-nexus/blob/master/docs/plugin-package-rename-migration.md"
+];
+/**
+ * Bridge-release notice for the 3.3.2 -> 4.0.0 package rename.
+ * Remove the call site in cli.ts when publishing 4.0.0 under
+ * @aiot-toolkits/plugin-sdk.
+ */
+function showSdkPackageRenameNotice(args, stdout, isDisabled) {
+    if (args.includes("--help") || args.includes("-h") || args.includes("--json") || isDisabled(process.env)) {
+        return;
+    }
+    for (const line of packageRenameNoticeLines) {
+        stdout("npm notice " + line);
+    }
+}
+exports.showSdkPackageRenameNotice = showSdkPackageRenameNotice;
 function showSdkUpdateNotice(args, stdout, updateCheck, currentVersion) {
     if (args.includes("--help") || args.includes("-h") || args.includes("--json") || updateCheck.isDisabled(process.env)) {
         return;

package/dist/src/cli.js

@@ -37,6 +37,7 @@ const io = {
     stderr: (message) => process.stderr.write(message + "\n")
 };
 (0, update_notice_1.showSdkUpdateNotice)(args, io.stdout, sdkUpdateCheck, index_1.PLUGIN_SDK_VERSION);
+(0, update_notice_1.showSdkPackageRenameNotice)(args, io.stdout, sdkUpdateCheck.isDisabled);
 const result = (0, run_1.runCli)(args, io);
 if (typeof result === "number") {
     process.exitCode = result;

package/dist/src/sdk-info.d.ts

@@ -1,4 +1,4 @@
-export declare const PLUGIN_SDK_VERSION = "3.3.1";
+export declare const PLUGIN_SDK_VERSION = "3.3.2";
 export declare const PLUGIN_SDK_NODE_ENGINE = ">=16.20.0 <17";
 export declare const PLUGIN_SDK_NPM_ENGINE = ">=6.13.4";
 export declare const PLUGIN_SDK_ELECTRON_VERSION = "22.3.27";

package/dist/src/sdk-info.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPluginSdkInfo = exports.PLUGIN_SDK_TYPES_NODE_VERSION = exports.PLUGIN_SDK_TYPESCRIPT_VERSION = exports.PLUGIN_SDK_ELECTRON_VERSION = exports.PLUGIN_SDK_NPM_ENGINE = exports.PLUGIN_SDK_NODE_ENGINE = exports.PLUGIN_SDK_VERSION = void 0;
 const plugin_framework_version_1 = require("../.generated/plugin-framework-version");
-exports.PLUGIN_SDK_VERSION = "3.3.1";
+exports.PLUGIN_SDK_VERSION = "3.3.2";
 exports.PLUGIN_SDK_NODE_ENGINE = ">=16.20.0 <17";
 exports.PLUGIN_SDK_NPM_ENGINE = ">=6.13.4";
 exports.PLUGIN_SDK_ELECTRON_VERSION = "22.3.27";

package/package.json

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