@aiot-nexus/plugin-sdk 1.1.0 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@ AIoT Nexus 独立插件开发包，包含公开 TypeScript 契约、PluginFrame
 
 - Node.js `>=16.20.0 <17`
 - npm `>=6.13.4`
-- 插件框架 API `1.0.0`
+- 插件框架 API `2.0.0`
 - manifest schema `1`
 
 ## 命令
@@ -27,6 +27,26 @@ nexus-plugin dev:nexus [plugin-project-directory] --host <nexus.exe-or-directory
 
 `npm run pack:sdk` 将离线安装包写入 `package/`。该目录是本地构建产物，不进入 Git。`npm run publish:sdk` 发布到官方 npm registry；`prepack` 会强制运行测试、构建并核对实际 npm 文件清单，缺少任一公开入口时拒绝发布。
 
+## SDK 版本提示
+
+SDK 提供两层非阻塞版本检查：
+
+- 安装阶段的 `postinstall` 会强制查询 `dist-tags.latest` 并写入当前用户缓存。npm 7+ 默认隐藏依赖包的 lifecycle 输出；需要看到安装阶段 notice 时使用 `npm install --foreground-scripts`。`npm install --ignore-scripts` 会跳过该阶段，但不影响后续 CLI 检查。
+- `nexus-plugin` 启动时先读取缓存。缓存新鲜期为 24 小时；缓存缺失或过期时在后台检查，不等待网络，不改变命令退出码。检测到普通更新时会显示：
+
+  ```text
+  npm notice Update available for @aiot-nexus/plugin-sdk: 2.0.0 -> 2.1.0
+  npm notice Run npm install --save-dev @aiot-nexus/plugin-sdk@latest
+  ```
+
+检查会优先使用 npm 当前配置的 registry（包括私有 registry），主源失败后回退官方 npm registry；不会发送 token、密码或项目路径。离线、超时、registry 返回非法数据或缓存损坏都静默降级，安装、构建、调试和正式宿主启动不会被阻断。
+
+大版本更新会额外提示先确认 Nexus Framework API 兼容性；检查不会自动修改 `package.json`、升级依赖或新增交互式命令。确认兼容后，推荐手动执行 `npm install --save-dev @aiot-nexus/plugin-sdk@latest`。
+
+可用环境变量：`NEXUS_PLUGIN_SDK_UPDATE_CHECK=0` 或 `NO_UPDATE_NOTIFIER=1` 会同时关闭安装和 CLI 检查。内部 SDK 打包环境也会自动跳过联网检查。
+
+使用本地 `--sdk-source ...tgz` 时，生成工程依赖的是 tgz 内记录的 SDK 版本；安装阶段仍可能按 npm registry 写入该版本的缓存，CLI 后续按“当前版本 + registry”读取。完全离线开发可设置上述禁用变量，或接受检查静默失败；本地 SDK 不会自动替换正式 npm SDK，也不会因为有新版本自动升级。
+
 ## 创建插件
 
 ```bash
@@ -44,7 +64,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-1.1.0.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
+默认来源从 npm registry 安装。离线开发时先执行 `npm run pack:sdk`，再通过 `--sdk-source /path/to/aiot-nexus-plugin-sdk-2.0.0.tgz` 指定本地包；CLI 会把本地包一并放入生成工程。
 
 ## 独立调试
 
@@ -57,11 +77,11 @@ npm run dev:debug
 ```
 
 - `npm run dev:web` 先运行模板独立的 `build:web`，只编译 Renderer 到 `.nexus-plugin-dev/web-package/<plugin-id>/`，再启动仅绑定 `127.0.0.1:4173` 的本地 HTTP 宿主并打开系统浏览器；它不执行 native rebuild、不复制原生运行时、不覆盖正式 `dist`，支持浏览器 DevTools 与源码映射。
-- 浏览器模式不加载 `mainEntry`，`invokeMain` 会返回 `PluginCapabilityUnsupported`；设置仅在本次服务进程内保存，日志输出到 CLI。涉及主进程、SQLite 或 Host API 时使用 `npm run dev`。
-- `npm run dev` 先构建和校验插件，再使用工程本地固定的 `electron@22.3.27` 启动 SDK 调试宿主；Renderer DevTools 默认自动打开。
+- 浏览器模式不加载 `mainEntry`，`invokeMain` 会返回 `PluginCapabilityUnsupported`；设置仅在本次服务进程内保存，日志输出到 CLI。涉及插件 worker、SQLite 或 Host API 时使用 `npm run dev`。
+- `npm run dev` 先构建和校验插件，再使用工程本地固定的 `electron@22.3.27` 启动 SDK 调试宿主；宿主渲染 UI，插件 `mainEntry` 在独立 `utilityProcess` worker 中加载，Renderer DevTools 默认自动打开。
 - Electron 调试宿主的 `host.hostVersion` 默认是 SDK 构建时记录的 Nexus 应用版本；使用 `nexus-plugin dev . --host-version <X.Y.Z>` 可模拟其他应用版本，并按 manifest `minHostVersion` 拒绝不兼容组合。
-- `npm run dev:debug` 额外使用 `--inspect-brk=9229` 暂停 Electron 主进程，可在 `src/main.ts` 启动阶段命中断点。
-- 生成工程包含 `.vscode/launch.json`。在 VS Code 中选择 `Debug Nexus plugin` 可直接启动；若本机关闭了子进程自动附加，则先运行 `npm run dev:debug`，再选择 `Attach Nexus plugin main (9229)`。renderer 断点在自动打开的 DevTools `Sources` 中设置。
+- `npm run dev:debug` 额外把 `--inspect-brk=9229` 传给插件 worker，可在 `src/main.ts` 激活阶段命中断点；宿主 UI 仍保持可启动。
+- 生成工程包含 `.vscode/launch.json`。在 VS Code 中选择 `Debug Nexus plugin` 可直接启动；若本机关闭了子进程自动附加，则先运行 `npm run dev:debug`，再选择 `Attach Nexus plugin worker (9229)`。renderer 断点在自动打开的 DevTools `Sources` 中设置。
 - Electron 调试构建会内联 `src/main.ts` 和 `src/renderer/app.ts` source map；浏览器 `build:web` 只内联 Renderer source map。普通 `npm run build` 不内联源码，不改变部署制品形态。模板在收到首个 Host context 前隐藏正文，应用语言和主题后再显示。
 - 调试数据保存在工程的 `.nexus-plugin-dev/`，该目录默认被忽略。关闭调试窗口会结束独立 Electron 进程；修改源码后重新运行调试命令。
 
@@ -79,7 +99,7 @@ nexus-plugin dev [plugin-project-directory]
   [--no-devtools]
 ```
 
-调试宿主工具栏中的语言和主题选择器用于模拟 Nexus 主框架 context，不属于插件页面。切换后调试宿主向同一 iframe 重发框架 `1.0.0` 已有的 `init` 消息；SDK 将后续 `init` 作为 context 更新并原地刷新语言和主题，同时仍接受可选的 `context-changed` 消息。调试宿主还复用正式的 `nexus-plugin://` 资源协议、iframe sandbox、CSP、消息结构、operation 校验以及当前 Host API 权限语义，但不包含 Nexus 的完整页面路由、Pinia 状态和应用级功能。交付前仍需把 `dist/<plugin-id>/` 放入正式 Nexus 完成集成验证。
+调试宿主工具栏中的语言和主题选择器用于模拟 Nexus 主框架 context，不属于插件页面。切换后调试宿主向同一 iframe 重发框架 `2.0.0` 的 `init` 消息；SDK 将后续 `init` 作为 context 更新并原地刷新语言和主题，同时仍接受可选的 `context-changed` 消息。调试宿主还复用正式的 `nexus-plugin://` 资源协议、iframe sandbox、CSP、消息结构、operation 校验以及当前 Host API 权限语义，但不包含 Nexus 的完整页面路由、Pinia 状态和应用级功能。`mainEntry` 的激活、deactivate、Host API 请求和 renderer operation 调用都通过异步 RPC 连接 worker；交付前仍需把 `dist/<plugin-id>/` 放入正式 Nexus 完成集成验证。
 
 浏览器 UI 命令支持 `--no-build`、`--no-open`、`--port <port>`，以及与 Electron 调试宿主相同的 `--language`、`--theme`、`--surface` 和 `--contribution-id` 参数。它使用普通 `http://127.0.0.1` iframe，不模拟 `nexus-plugin://` 协议或 Electron sandbox，因此只作为 UI 开发入口。Renderer-only 输出不会覆盖正式插件制品。
 
@@ -97,6 +117,6 @@ 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 字段 | 完整构建成功后请求旧宿主退出，替换完整插件包并启动新宿主；宿主 PID 变化。 |
+| `src/main.ts`、依赖、原生模块或主进程相关 manifest 字段 | 完整构建成功后先停止插件 worker，原子替换完整插件包，再在同一 Nexus 进程中启动新 worker；宿主 PID 不变。 |
 
-更新构建或 manifest 重扫失败时保留上一个可运行部署；新宿主启动失败时回滚插件包并恢复旧版本。`mainEntry` 不通过清理 `require.cache` 热替换，主进程变化始终使用完整重启。默认打开 Renderer DevTools；可传 `--no-devtools`。主进程调试支持 `--inspect[=<port>]` 和 `--inspect-brk[=<port>]`，贡献点选择支持 `--surface` 与 `--contribution-id`。按 `Ctrl+C` 停止 CLI 时，CLI 会关闭其启动的正式宿主。
+更新构建或 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 关闭，再关闭其启动的正式宿主。