@aiot-nexus/plugin-sdk 3.3.0 → 3.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @aiot-nexus/plugin-sdk
 
-> 当前 SDK 包版本为 `3.3.0`，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.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)。
 
 本包提供公开 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.0` |
+| SDK | `3.3.1` |
 | 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.0 nexus-plugin upgrade . --check
-npx --package=@aiot-nexus/plugin-sdk@3.3.0 nexus-plugin upgrade .
+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 .
 ```
 
 发布前或本地 tgz：
 
 ```bash
-npx --package=./aiot-nexus-plugin-sdk-3.3.0.tgz nexus-plugin upgrade . \
-  --sdk-source ./aiot-nexus-plugin-sdk-3.3.0.tgz
+npx --package=./aiot-nexus-plugin-sdk-3.3.1.tgz nexus-plugin upgrade . \
+  --sdk-source ./aiot-nexus-plugin-sdk-3.3.1.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.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 命令的问题，均作为历史兼容说明保留。
 
 ## 创建插件
 
@@ -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.0.tgz --install
+nexus-plugin create my-frame-plugin --sdk-source ./package/aiot-nexus-plugin-sdk-3.3.1.tgz --install
 ```
 
 生成插件后，可以在 `src/manifest.json` 的业务入口中静态控制 AIoT Toolkits 宿主状态栏。相关 manifest 片段如下，其余必填字段沿用脚手架生成值：

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

@@ -1,4 +1,4 @@
-export declare const PLUGIN_SDK_VERSION = "3.3.0";
+export declare const PLUGIN_SDK_VERSION = "3.3.1";
 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.0";
+exports.PLUGIN_SDK_VERSION = "3.3.1";
 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/dist/src/upgrade.d.ts

@@ -42,3 +42,9 @@ export interface PluginSdkUpgradeRuntime {
 }
 export declare function runPluginSdkUpgrade(options: PluginSdkUpgradeOptions, runtime?: PluginSdkUpgradeRuntime): PluginSdkUpgradeResult;
 export declare function formatPluginSdkUpgradeResult(result: PluginSdkUpgradeResult): string;
+/**
+ * npm_execpath points at npm-cli.js under `npm run`, but at npx-cli.js under
+ * `npx`; routing npm commands through npx-cli.js fails on the first npm-only
+ * flag. npx-cli.js and npm-cli.js live in the same npm bin directory.
+ */
+export declare function resolveNpmCliEntryPoint(npmExecPath: string | undefined): string | undefined;

package/dist/src/upgrade.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatPluginSdkUpgradeResult = exports.runPluginSdkUpgrade = void 0;
+exports.resolveNpmCliEntryPoint = exports.formatPluginSdkUpgradeResult = exports.runPluginSdkUpgrade = void 0;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -1070,12 +1070,32 @@ function defaultRuntime() {
     };
 }
 function runNpm(args, cwd) {
-    const npmExecPath = process.env.npm_execpath;
-    if (npmExecPath) {
-        return runProcess(process.execPath, [npmExecPath, ...args], cwd);
+    const npmCliEntryPoint = resolveNpmCliEntryPoint(process.env.npm_execpath);
+    if (npmCliEntryPoint) {
+        return runProcess(process.execPath, [npmCliEntryPoint, ...args], cwd);
     }
     return runProcess(process.platform === "win32" ? "npm.cmd" : "npm", args, cwd);
 }
+/**
+ * npm_execpath points at npm-cli.js under `npm run`, but at npx-cli.js under
+ * `npx`; routing npm commands through npx-cli.js fails on the first npm-only
+ * flag. npx-cli.js and npm-cli.js live in the same npm bin directory.
+ */
+function resolveNpmCliEntryPoint(npmExecPath) {
+    if (!npmExecPath) {
+        return undefined;
+    }
+    const base = path.basename(npmExecPath).toLowerCase();
+    if (base === "npm-cli.js") {
+        return npmExecPath;
+    }
+    if (base === "npx-cli.js") {
+        const sibling = path.join(path.dirname(npmExecPath), "npm-cli.js");
+        return fs.existsSync(sibling) ? sibling : undefined;
+    }
+    return undefined;
+}
+exports.resolveNpmCliEntryPoint = resolveNpmCliEntryPoint;
 function runProcess(command, args, cwd) {
     const result = (0, child_process_1.spawnSync)(command, args, {
         cwd,

package/package.json

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