@aiot-nexus/plugin-sdk 3.2.0 → 3.3.1

package/README.md

@@ -1,14 +1,19 @@
 # @aiot-nexus/plugin-sdk
 
-> 当前 SDK 包版本为 `3.2.0`，Framework API 为 `3.2.0`，manifest schema 保持 `1`。Framework 3 将可信插件的 `mainEntry` 直接加载到 Nexus 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)。
 
+宿主产品名为 AIoT Toolkits，SDK 包名和 `dev:nexus` 命令保持不变。
+本仓库 SDK 的 `--host` 目录参数只查找 `AIoT Toolkits.exe`，文件不存在时直接报错。
+尚未更新的已发布 SDK 应传完整路径，例如 `--host "C:\Tools\AIoT Toolkits.exe"`；
+目录自动识别的新行为需使用包含本次修改的 SDK 构建。
+
 ## 兼容基线
 
 | 项目 | 固定值 |
 | --- | --- |
-| SDK | `3.2.0` |
+| SDK | `3.3.1` |
 | Framework API | `3.2.0` |
 | Manifest schema | `1` |
 | Node 安装和构建 | `>=16.20.0 <17` |
@@ -27,7 +32,7 @@ nexus-plugin create <plugin-id> --template minimal|sqlite --output <parent-direc
 nexus-plugin upgrade [plugin-project-directory] [--check] [--sdk-source <version-or-local-tgz>]
 nexus-plugin dev [plugin-project-directory]
 nexus-plugin dev:web [plugin-project-directory]
-nexus-plugin dev:nexus [plugin-project-directory] --host <nexus.exe-or-directory>
+nexus-plugin dev:nexus [plugin-project-directory] --host <host-exe-or-directory>
 ```
 
 仓库内 SDK 命令：
@@ -48,15 +53,15 @@ npm run publish:sdk
 registry 升级与只读预检：
 
 ```bash
-npx --package=@aiot-nexus/plugin-sdk@3.2.0 nexus-plugin upgrade . --check
-npx --package=@aiot-nexus/plugin-sdk@3.2.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.2.0.tgz nexus-plugin upgrade . \
-  --sdk-source ./aiot-nexus-plugin-sdk-3.2.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 一致性仍会验证。
@@ -67,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.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 命令的问题，均作为历史兼容说明保留。
 
 ## 创建插件
 
@@ -90,10 +95,10 @@ 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.2.0.tgz --install
+nexus-plugin create my-frame-plugin --sdk-source ./package/aiot-nexus-plugin-sdk-3.3.1.tgz --install
 ```
 
-生成插件后，可以在 `src/manifest.json` 的业务入口中静态控制 Nexus 宿主状态栏。相关 manifest 片段如下，其余必填字段沿用脚手架生成值：
+生成插件后，可以在 `src/manifest.json` 的业务入口中静态控制 AIoT Toolkits 宿主状态栏。相关 manifest 片段如下，其余必填字段沿用脚手架生成值：
 
 ```json
 {
@@ -183,9 +188,9 @@ function failure(code: string, message: string) {
 - `context.host.*` 直接返回 `NexusResult<T>`，不需要 `await`。
 - 注册的 operation handler 可以返回 Promise，可等待异步文件对话框、网络或其他用户交互。
 - operation 默认没有业务超时。浏览器客户端 `requestTimeoutMs` 默认是 `0`；20 秒仅用于 iframe 初始化握手。
-- 同步 Electron API 也能调用，但 `showOpenDialogSync()`、同步文件 I/O、长 CPU 任务会阻塞 Nexus 主进程、所有窗口和插件，应优先使用异步版本。
+- 同步 Electron API 也能调用，但 `showOpenDialogSync()`、同步文件 I/O、长 CPU 任务会阻塞 AIoT Toolkits 主进程、所有窗口和插件，应优先使用异步版本。
 - Framework 不跟踪插件直接创建的 Electron/Node 资源。插件必须在 `deactivate` 中自行清理。
-- Node 模块图和原生模块不能安全热卸载。已加载 `mainEntry`、依赖、原生模块或相关 manifest 变化必须重启 Nexus。
+- Node 模块图和原生模块不能安全热卸载。已加载 `mainEntry`、依赖、原生模块或相关 manifest 变化必须重启 AIoT Toolkits。
 
 Framework 3 不再提供 `context.host.electron` Facade，也没有 `electronHostControl` 权限。manifest 权限只描述 Host API 能力，不限制可信 `mainEntry` 直接调用 Electron/Node。SDK 保留 `createPluginElectronIpcChannel()` 和 `createPluginElectronProtocolScheme()` 作为命名约定帮助函数；宿主不会自动隔离或清理对应注册。
 
@@ -234,7 +239,7 @@ SDK 升级本身只提供能力。插件需要在 CSS 中引用 `var(--nexus-col
 | `npm run dev:web` | 不执行 | 不可用 | 只调试 Renderer；`invokeMain` 返回 `PluginCapabilityUnsupported`。 |
 | `npm run dev` | Electron 调试宿主主进程直接加载 | 可用 | 调试真实生命周期、对话框、SQLite 和插件窗口。 |
 | `npm run dev:debug` | 同 `dev` | 可用 | Electron 主进程以 `--inspect-brk=9229` 启动。 |
-| `npm run dev:nexus -- --host ...` | 正式 Nexus 主进程直接加载 | 可用 | 最终集成和监听更新。 |
+| `npm run dev:nexus -- --host ...` | 正式 AIoT Toolkits 主进程直接加载 | 可用 | 最终集成和监听更新。 |
 
 Electron 调试壳仅保留 context 工具栏；插件 iframe 无边距、无边框，填满剩余窗口，不设置最小宽高，也不根据内容上报限制尺寸。Renderer DevTools 默认打开。
 
@@ -244,12 +249,12 @@ VS Code 模板提供 `Debug Nexus plugin` 和 `Attach Nexus plugin main process
 
 | 修改范围 | 处理方式 |
 | --- | --- |
-| `src/renderer/**` | 只构建 Renderer 并重载 iframe，Nexus PID 不变。 |
+| `src/renderer/**` | 只构建 Renderer 并重载 iframe，AIoT Toolkits PID 不变。 |
 | 无 `mainEntry` 插件的安全 manifest 展示/贡献字段 | 原子替换 manifest 并重扫，PID 不变。 |
-| 有 `mainEntry` 插件的 manifest 变化 | 完整构建并重启 Nexus。 |
-| `src/main.*`、依赖、原生模块、构建脚本 | 完整构建并重启 Nexus。 |
+| 有 `mainEntry` 插件的 manifest 变化 | 完整构建并重启 AIoT Toolkits。 |
+| `src/main.*`、依赖、原生模块、构建脚本 | 完整构建并重启 AIoT Toolkits。 |
 
-构建失败保留旧部署；新宿主启动或就绪失败会恢复旧包和旧宿主。`--inspect` / `--inspect-brk` 调试的是 Nexus Electron 主进程，因此会同时暂停或暴露宿主代码。按 `Ctrl+C` 时 CLI 关闭自己启动的宿主。
+构建失败保留旧部署；新宿主启动或就绪失败会恢复旧包和旧宿主。`--inspect` / `--inspect-brk` 调试的是 AIoT Toolkits Electron 主进程，因此会同时暂停或暴露宿主代码。按 `Ctrl+C` 时 CLI 关闭自己启动的宿主。
 
 ## 发布前检查
 
@@ -262,4 +267,4 @@ VS Code 模板提供 `Debug Nexus plugin` 和 `Attach Nexus plugin main process
 7. `deactivate` 关闭窗口、Session 监听、IPC、protocol、快捷键、定时器、数据库和子进程。
 8. 没有同步长任务、无限载荷、任意命令/SQL/路径透传或日志敏感信息。
 9. 主题集成明确引用 `--nexus-color-*` / `context.theme`，或显式关闭 `autoApplyHostTheme`。
-10. 运行 `npm test`、插件构建、正式 Nexus 集成和 Windows 7 真机验收。
+10. 运行 `npm test`、插件构建、正式 AIoT Toolkits 集成和 Windows 7 真机验收。

package/dist/.generated/plugin-framework-version.d.ts

@@ -1,6 +1,7 @@
 export declare const PLUGIN_FRAMEWORK_VERSION = "3.2.0";
 export declare const PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
 export declare const PLUGIN_COMPATIBLE_VERSION_PATTERN = "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$";
+export declare const PLUGIN_VERSION_PATTERN = "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$";
 export interface ParsedPluginVersion {
     major: number;
     minor: number;

package/dist/.generated/plugin-framework-version.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isPluginFrameworkVersionCompatible = exports.comparePluginVersions = exports.parsePluginCompatibleVersion = exports.PLUGIN_COMPATIBLE_VERSION_PATTERN = exports.PLUGIN_MANIFEST_SCHEMA_VERSION = exports.PLUGIN_FRAMEWORK_VERSION = void 0;
+exports.isPluginFrameworkVersionCompatible = exports.comparePluginVersions = exports.parsePluginCompatibleVersion = exports.PLUGIN_VERSION_PATTERN = exports.PLUGIN_COMPATIBLE_VERSION_PATTERN = exports.PLUGIN_MANIFEST_SCHEMA_VERSION = exports.PLUGIN_FRAMEWORK_VERSION = void 0;
 exports.PLUGIN_FRAMEWORK_VERSION = "3.2.0";
 exports.PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
 exports.PLUGIN_COMPATIBLE_VERSION_PATTERN = "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$";
+exports.PLUGIN_VERSION_PATTERN = "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$";
 function parsePluginCompatibleVersion(value) {
     const match = /^(0|[1-9][0-9]*)(?:\.(0|[1-9][0-9]*))?(?:\.(0|[1-9][0-9]*))?$/.exec(value.trim());
     if (!match) {

package/dist/.generated/plugin-manifest.schema.json

@@ -20,7 +20,7 @@
         "pluginId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$" },
         "displayNameKey": { "type": "string", "minLength": 1 },
         "descriptionKey": { "type": "string" },
-        "pluginVersion": { "type": "string", "minLength": 1 },
+        "pluginVersion": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$" },
         "hostApiVersion": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$" },
         "minHostVersion": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$" },
         "supportedCultures": {

package/dist/dev-host-metadata.json

@@ -1,3 +1,3 @@
 {
-  "nexusApplicationVersion": "0.0.1"
+  "nexusApplicationVersion": "0.0.3"
 }

package/dist/src/cli/run.js

@@ -102,7 +102,7 @@ function usage() {
         "  nexus-plugin dev:web [plugin-project-directory] [--no-build] [--no-open] [--port <port>]",
         "    [--language <culture>] [--theme system|light|dark] [--surface business|tool|settings]",
         "    [--contribution-id <id>]",
-        "  nexus-plugin dev:nexus [plugin-project-directory] --host <nexus.exe-or-directory>",
+        "  nexus-plugin dev:nexus [plugin-project-directory] --host <host-exe-or-directory>",
         "    [--inspect[=<port>] | --inspect-brk[=<port>]] [--no-devtools]",
         "    [--language <culture>] [--theme system|light|dark] [--surface business|tool|settings]",
         "    [--contribution-id <id>]"
@@ -247,7 +247,7 @@ function runNexusDev(args, io) {
         }
     }
     if (!options.hostPath) {
-        return usageError(io, "dev:nexus requires --host <nexus.exe-or-directory>.");
+        return usageError(io, "dev:nexus requires --host <host-exe-or-directory>.");
     }
     return (0, nexus_dev_1.runPluginNexusDev)(options, io).catch((error) => {
         if (error instanceof dev_1.PluginDevError) {

package/dist/src/nexus-dev-deployment.js

@@ -34,9 +34,9 @@ function resolveNexusExecutable(hostPath) {
         throw new dev_1.PluginDevError("Nexus host path does not exist: " + resolved);
     }
     const stat = fs.statSync(resolved);
-    const executable = stat.isDirectory() ? path.join(resolved, "nexus.exe") : resolved;
+    const executable = stat.isDirectory() ? path.join(resolved, "AIoT Toolkits.exe") : resolved;
     if (!fs.existsSync(executable) || !fs.statSync(executable).isFile()) {
-        throw new dev_1.PluginDevError("Nexus executable is missing: " + executable);
+        throw new dev_1.PluginDevError("AIoT Toolkits executable is missing: " + executable);
     }
     if (process.platform === "win32" && path.extname(executable).toLowerCase() !== ".exe") {
         throw new dev_1.PluginDevError("Nexus host must be a Windows executable: " + executable);

package/dist/src/scaffold.js

@@ -218,7 +218,7 @@ function createPackageJson(options, sdkSource) {
         name: options.pluginId,
         version: "0.1.0",
         private: true,
-        description: options.displayName + " independent plugin for AIoT Nexus.",
+        description: options.displayName + " independent plugin for AIoT Toolkits.",
         scripts
     };
     if (options.template === "sqlite") {

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

@@ -1,4 +1,4 @@
-export declare const PLUGIN_SDK_VERSION = "3.2.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.2.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.2.0",
+  "version": "3.3.1",
   "description": "Types, PluginFrame client, and CLI for AIoT Nexus independent plugins.",
   "license": "UNLICENSED",
   "publishConfig": {

package/templates/minimal/README.md.tmpl

@@ -1,6 +1,6 @@
 # __DISPLAY_NAME_MARKDOWN__
 
-AIoT Nexus independent PluginFrame plugin generated from the `minimal` template.
+AIoT Toolkits independent PluginFrame plugin generated from the `minimal` template.
 
 ```bash
 npm install
@@ -8,14 +8,14 @@ npm run typecheck
 npm run build
 npm run dev:web
 npm run dev
-npm run dev:nexus -- --host C:\path\to\nexus.exe
+npm run dev:nexus -- --host "C:\path\to\AIoT Toolkits.exe"
 ```
 
 SDK checks for a newer `@aiot-nexus/plugin-sdk` in two steps. The package `postinstall` refreshes a user cache; npm 7+ hides dependency lifecycle output by default, so use `npm install --foreground-scripts` to see it. The `nexus-plugin` CLI reads that cache and prints npm-style notices when it is fresh; missing or older-than-24-hours cache data is checked in the background without blocking the command. `npm install --ignore-scripts` skips only the install check, while CLI checks remain available.
 
 The check follows the npm-configured registry, falls back to the official npm registry when needed, and silently ignores offline, timeout, malformed-response, or corrupt-cache failures. Use `NEXUS_PLUGIN_SDK_UPDATE_CHECK=0` or `NO_UPDATE_NOTIFIER=1` to disable both checks. Notices never modify the project. When one appears, substitute the exact version printed by the notice for `X.Y.Z`: `npx --package=@aiot-nexus/plugin-sdk@X.Y.Z nexus-plugin upgrade . --check`, then repeat without `--check`. The transaction synchronizes package.json, package-lock.json, and node_modules, runs project checks, and rolls back on failure. A major update additionally requires `--allow-major` and the migration guide linked by the CLI; source and manifest files are never rewritten.
 
-The deployable plugin package is `dist/__PLUGIN_ID__/`. For a manual installation, stop Nexus before replacing `Plugins/__PLUGIN_ID__/`, then start it again. During development, use `npm run dev:nexus` so the CLI coordinates Nexus shutdown, atomic replacement, and restart for trusted `mainEntry` changes.
+The deployable plugin package is `dist/__PLUGIN_ID__/`. For a manual installation, stop AIoT Toolkits before replacing `Plugins/__PLUGIN_ID__/`, then start it again. During development, use `npm run dev:nexus` so the CLI coordinates AIoT Toolkits shutdown, atomic replacement, and restart for trusted `mainEntry` changes.
 
 ## Native Electron file dialogs
 
@@ -97,21 +97,21 @@ export async function chooseSavePath(): Promise<string | undefined> {
 }
 ```
 
-Call these helpers from an operation registered with `context.host.registerRendererMethod`, then let the renderer invoke that narrow operation through `client.invokeMain()`. Return the `NexusResult` from `chooseAndReadText` directly so the renderer receives the stable `FileNotReadable`, `FileTooLarge`, or `FileReadFailed` code. Do not expose Electron objects or unrestricted file paths to the iframe. For larger files, stream or paginate in `mainEntry` and return only bounded chunks or summaries instead of the whole file. `npm run dev:web` is renderer-only and deliberately has no `mainEntry`, Node filesystem, or Electron main-process API; use `npm run dev` or a formal Nexus host to test these dialogs.
+Call these helpers from an operation registered with `context.host.registerRendererMethod`, then let the renderer invoke that narrow operation through `client.invokeMain()`. Return the `NexusResult` from `chooseAndReadText` directly so the renderer receives the stable `FileNotReadable`, `FileTooLarge`, or `FileReadFailed` code. Do not expose Electron objects or unrestricted file paths to the iframe. For larger files, stream or paginate in `mainEntry` and return only bounded chunks or summaries instead of the whole file. `npm run dev:web` is renderer-only and deliberately has no `mainEntry`, Node filesystem, or Electron main-process API; use `npm run dev` or a formal AIoT Toolkits host to test these dialogs.
 
 The renderer calls the trusted-main `demo.echo` operation through `@aiot-nexus/plugin-sdk`. The main entry also calls the directly imported `app.getName()` during activation, so `npm run dev` verifies the real Electron main-process path. Run `npm run validate` after changing the manifest or output layout.
 
-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. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
+The renderer follows `context.language` and `context.themeMode` from AIoT Toolkits, 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 AIoT Toolkits context changes. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. Add or edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
 SDK 3.2 automatically maps the active `context.theme` palette to `--nexus-color-*` variables and sets `data-nexus-theme="light|dark"` on the document root. This template consumes those variables with local light/dark fallbacks, so it still renders on an older host. Merely upgrading the SDK does not recolor custom CSS: use the namespaced variables or read the optional palette explicitly, for example `const primary = context.theme?.light.primary`.
 
 For a plugin-owned theme, create the client with `createPluginFrameClient({ autoApplyHostTheme: false })`. The palette remains available from `await client.waitForContext()`, but the SDK will not write CSS variables or `data-nexus-theme`. It never overwrites plugin-owned `--bg`, `--accent`, `data-theme`, or `color-scheme` values.
 
-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.
+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 AIoT Toolkits 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`, provide Node or Electron main-process APIs, 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 and Electron integration.
+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`, provide Node or Electron main-process APIs, or overwrite the deployable `dist` package. Language and theme controls still simulate AIoT Toolkits context, while `invokeMain` is intentionally unavailable. Pass `-- --no-open` or `-- --port <port>` when needed; use `npm run dev` for Host API and Electron 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 restart-sensitive manifest changes stop Nexus, replace the complete package, and start a new Nexus process because trusted modules cannot be unloaded safely from Node's module cache. Failed builds keep the previous deployment; launch or readiness failures restore the previous package and host. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
+Use `npm run dev:nexus -- --host "C:\path\to\AIoT Toolkits.exe"` for live development against a compiled, packaged AIoT Toolkits. The CLI atomically deploys this plugin to `<exeDir>/Plugins/__PLUGIN_ID__/`. Renderer changes rebuild and reload the iframe without changing the AIoT Toolkits PID; safe manifest changes rescan contributions in the same process; `mainEntry`, dependency, native-module, or restart-sensitive manifest changes stop AIoT Toolkits, replace the complete package, and start a new AIoT Toolkits process because trusted modules cannot be unloaded safely from Node's module cache. Failed builds keep the previous deployment; launch or readiness failures restore the previous package and host. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
 
 When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed. An explicit local upgrade copies the target archive to `vendor/aiot-nexus-plugin-sdk-<version>.tgz` and updates the exact file dependency.
 
@@ -119,4 +119,4 @@ For a local SDK archive, the tgz version remains the plugin's current SDK versio
 
 For trusted-main breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. To attach manually, start `npm run dev:debug` and select `Attach Nexus plugin main process (9229)`. Renderer DevTools opens automatically, with `src/renderer/app.ts` available through the development source map. `npm run dev` rebuilds before launch; use `npm run dev -- --no-build` only when intentionally reusing the current `dist` output.
 
-The independent host stores data under `.nexus-plugin-dev/` and mirrors the PluginFrame protocol and current Host API surface. Its simulated Nexus application version defaults to the version recorded by the SDK build; pass `npm run dev -- --host-version <X.Y.Z>` to exercise another compatibility branch. Run the deployable `dist/__PLUGIN_ID__/` in Nexus before delivery because the standalone host does not reproduce the full application shell or routing state.
+The independent host stores data under `.nexus-plugin-dev/` and mirrors the PluginFrame protocol and current Host API surface. Its simulated AIoT Toolkits application version defaults to the version recorded by the SDK build; pass `npm run dev -- --host-version <X.Y.Z>` to exercise another compatibility branch. Run the deployable `dist/__PLUGIN_ID__/` in AIoT Toolkits before delivery because the standalone host does not reproduce the full application shell or routing state.

package/templates/sqlite/README.md.tmpl

@@ -1,6 +1,6 @@
 # __DISPLAY_NAME_MARKDOWN__
 
-AIoT Nexus independent PluginFrame plugin generated from the `sqlite` template.
+AIoT Toolkits independent PluginFrame plugin generated from the `sqlite` template.
 
 ```bash
 npm install
@@ -8,7 +8,7 @@ npm run typecheck
 npm run build
 npm run dev:web
 npm run dev
-npm run dev:nexus -- --host C:\path\to\nexus.exe
+npm run dev:nexus -- --host "C:\path\to\AIoT Toolkits.exe"
 ```
 
 SDK checks for a newer `@aiot-nexus/plugin-sdk` in two steps. The package `postinstall` refreshes a user cache; npm 7+ hides dependency lifecycle output by default, so use `npm install --foreground-scripts` to see it. The `nexus-plugin` CLI reads that cache and prints npm-style notices when it is fresh; missing or older-than-24-hours cache data is checked in the background without blocking the command. `npm install --ignore-scripts` skips only the install check, while CLI checks remain available.
@@ -17,7 +17,7 @@ The check follows the npm-configured registry, falls back to the official npm re
 
 Every `npm run build` rebuilds `better-sqlite3@8.7.0` for Electron 22.3.27 with `@electron/rebuild@3.7.2` before packaging. `npm run rebuild:native` remains available as a standalone diagnostic command.
 
-The deployable plugin package is `dist/__PLUGIN_ID__/`. For a manual installation, stop Nexus before replacing `Plugins/__PLUGIN_ID__/`, then start it again. During development, use `npm run dev:nexus` so the CLI coordinates Nexus shutdown, atomic replacement, and restart for trusted `mainEntry` changes. Runtime data is stored in the host-provided plugin data directory and is not written into the plugin package.
+The deployable plugin package is `dist/__PLUGIN_ID__/`. For a manual installation, stop AIoT Toolkits before replacing `Plugins/__PLUGIN_ID__/`, then start it again. During development, use `npm run dev:nexus` so the CLI coordinates AIoT Toolkits shutdown, atomic replacement, and restart for trusted `mainEntry` changes. Runtime data is stored in the host-provided plugin data directory and is not written into the plugin package.
 
 The template is a schema-aware SQLite database browser. It opens `plugin.db` in the plugin data directory by default and initializes the `plugin_records` sample table there. **Open Database** calls Electron's directly imported `dialog.showOpenDialog()` from trusted `mainEntry`; it accepts a single existing SQLite file, including files without an extension. The renderer only displays the selected path and invokes parameterized operations. It never receives an Electron object and does not expose a path input, arbitrary SQL, DDL, `ATTACH`, or a SQL console.
 
@@ -43,23 +43,23 @@ if (!result.canceled && result.filePaths[0]) {
 }
 ```
 
-For related workflows, use `properties: ["openDirectory", "createDirectory"]` to choose a folder or `dialog.showSaveDialog()` to choose a save path. These calls belong in trusted `mainEntry`; the renderer should invoke a registered business operation such as `sqlite.chooseDatabase` through `client.invokeMain()` and receive only the result it needs. Native dialogs are unavailable in `npm run dev:web`; use `npm run dev` or a formal Nexus host.
+For related workflows, use `properties: ["openDirectory", "createDirectory"]` to choose a folder or `dialog.showSaveDialog()` to choose a save path. These calls belong in trusted `mainEntry`; the renderer should invoke a registered business operation such as `sqlite.chooseDatabase` through `client.invokeMain()` and receive only the result it needs. Native dialogs are unavailable in `npm run dev:web`; use `npm run dev` or a formal AIoT Toolkits host.
 
 External files are opened read/write only after a separate candidate connection can query `sqlite_schema`. Canceling the dialog or selecting a corrupt, locked, or inaccessible file keeps the current connection. The latest external path is atomically stored as `sqlite-browser-state.json` in the plugin data directory. Startup restores it when valid; otherwise the template clears the saved selection, falls back to `plugin.db`, and returns a visible notice. External databases do not receive the sample schema or journal pragma.
 
 The table selector lists ordinary user tables from the `main` schema. Dynamic headers show declared type, SQLite affinity, primary-key order, NULL, default, and generated-column metadata. The editor supports default/NULL/value modes for inserts and unchanged/NULL/value modes for updates. INTEGER input uses exact decimal integers, REAL must be finite, NUMERIC accepts integer, real, or text values, and BLOB input uses even-length hexadecimal text. The 1 MiB field and 4 MiB row limits count decoded BLOB bytes rather than hexadecimal characters. Ordinary rowid tables prefer an unshadowed built-in rowid; `WITHOUT ROWID` tables, or tables that shadow every rowid alias, fall back only to primary-key columns that are all non-NULL. A table without a unique locator remains browsable and insertable, but update and delete are unavailable. Primary-key locators larger than 16 KiB are also treated as browse-only so a page cannot copy unbounded keys into the trusted main process and iframe. Update and delete run in a transaction and must affect exactly one row. TEXT previews are capped at 16 KiB of UTF-8 data; BLOB previews show the byte length and first 32 bytes.
 
-The renderer follows `context.language` and `context.themeMode` from Nexus and preserves unfinished editor values during in-place context updates. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. This SDK template deliberately has no Quasar dependency, so its data grid uses a native `<table>` as a dependency-minimized template exception. It still provides pagination, contained horizontal scrolling, light/dark themes, `en-US` / `zh-CN`, and busy/empty/error states. Edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
+The renderer follows `context.language` and `context.themeMode` from AIoT Toolkits and preserves unfinished editor values during in-place context updates. The plugin page has no language or theme selector; the controls shown by `npm run dev` belong to the debug host. Below that toolbar, the iframe has no host padding, border, minimum size, or content-driven height and fills the remaining host viewport. This SDK template deliberately has no Quasar dependency, so its data grid uses a native `<table>` as a dependency-minimized template exception. It still provides pagination, contained horizontal scrolling, light/dark themes, `en-US` / `zh-CN`, and busy/empty/error states. Edit renderer messages in `src/renderer/app.ts`; edit host-shell titles and descriptions in `src/manifest.json` resources.
 
 SDK 3.2 automatically maps the active `context.theme` palette to `--nexus-color-*` variables and sets `data-nexus-theme="light|dark"` on the document root. This template consumes those variables with local light/dark fallbacks, so it still renders on an older host. Merely upgrading the SDK does not recolor custom CSS: use the namespaced variables or read the optional palette explicitly, for example `const primary = context.theme?.light.primary`.
 
 For a plugin-owned theme, create the client with `createPluginFrameClient({ autoApplyHostTheme: false })`. The palette remains available from `await client.waitForContext()`, but the SDK will not write CSS variables or `data-nexus-theme`. It never overwrites plugin-owned `--bg`, `--accent`, `data-theme`, or `color-scheme` values.
 
-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.
+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 AIoT Toolkits 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`, provide Node or Electron main-process APIs, 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. The page explicitly reports `PluginCapabilityUnsupported`; file selection, table loading, and CRUD require `npm run dev` or a formal Nexus host. Pass `-- --no-open` or `-- --port <port>` when needed.
+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`, provide Node or Electron main-process APIs, 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. The page explicitly reports `PluginCapabilityUnsupported`; file selection, table loading, and CRUD require `npm run dev` or a formal AIoT Toolkits host. 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 restart-sensitive manifest changes run the complete build (including the Electron 22.3.27 native rebuild), stop Nexus, replace the package, and start a new Nexus process. The database remains under the host-provided plugin data directory across host restarts. Failed builds keep the previous deployment, and launch or readiness failures roll the package back and restore the previous host. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
+Use `npm run dev:nexus -- --host "C:\path\to\AIoT Toolkits.exe"` to run the plugin inside a compiled, packaged AIoT Toolkits. The initial deployment and every full package replacement are atomic. Renderer-only and safe manifest updates keep the AIoT Toolkits PID; `mainEntry`, dependency, native-module, or restart-sensitive manifest changes run the complete build (including the Electron 22.3.27 native rebuild), stop AIoT Toolkits, replace the package, and start a new AIoT Toolkits process. The database remains under the host-provided plugin data directory across host restarts. Failed builds keep the previous deployment, and launch or readiness failures roll the package back and restore the previous host. Add `--no-devtools`, `--inspect[=<port>]`, `--inspect-brk[=<port>]`, `--surface`, or `--contribution-id` after the second `--` as needed.
 
 When this project was created from a local SDK archive, `vendor/aiot-nexus-plugin-sdk.tgz` is part of the source project and must be kept when the project is moved or committed. An explicit local upgrade copies the target archive to `vendor/aiot-nexus-plugin-sdk-<version>.tgz` and updates the exact file dependency.
 
@@ -67,4 +67,4 @@ For a local SDK archive, the tgz version remains the plugin's current SDK versio
 
 For trusted-main breakpoints, open this plugin directory in VS Code, set breakpoints in `src/main.ts`, and run `Debug Nexus plugin`. To attach manually, start `npm run dev:debug` and select `Attach Nexus plugin main process (9229)`. Renderer DevTools opens automatically, with `src/renderer/app.ts` available through the development source map. The default debug build also runs the Electron 22.3.27 native rebuild before launch. Use `npm run dev -- --no-build` only when intentionally reusing a compatible current `dist` output.
 
-The independent host stores the SQLite database and settings under `.nexus-plugin-dev/data/` and mirrors the PluginFrame protocol and current Host API surface. Its simulated Nexus application version defaults to the version recorded by the SDK build; pass `npm run dev -- --host-version <X.Y.Z>` to exercise another compatibility branch. Run the deployable `dist/__PLUGIN_ID__/` in Nexus before delivery because the standalone host does not reproduce the full application shell or routing state.
+The independent host stores the SQLite database and settings under `.nexus-plugin-dev/data/` and mirrors the PluginFrame protocol and current Host API surface. Its simulated AIoT Toolkits application version defaults to the version recorded by the SDK build; pass `npm run dev -- --host-version <X.Y.Z>` to exercise another compatibility branch. Run the deployable `dist/__PLUGIN_ID__/` in AIoT Toolkits before delivery because the standalone host does not reproduce the full application shell or routing state.