@heybox/hb-sdk 0.5.18 → 0.6.1

package/README.md

@@ -332,7 +332,7 @@ await network.request({
 
 ## 生命周期事件
 
-SDK 实例创建后会自动开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时，默认单例会被懒创建并自动开始握手；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
+导入 SDK 根包时会 eager 创建唯一默认实例并立即开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时不会创建第二个实例；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
 
 ```ts
 import { on } from '@heybox/hb-sdk';
@@ -390,7 +390,7 @@ try {
 | `hb-sdk remote bind <mini-program-id> [--force]`                                                         | 校验当前 CLI 用户可管理目标小程序后，再把它绑定到当前项目。                                                             |
 | `hb-sdk remote info`                                                                                     | 查看当前项目绑定的小程序详情及完整只读 Runtime 权限/config。                                                             |
 | `hb-sdk remote allowlist list/add/remove/set ...`                                                        | 管理绑定小程序的预览白名单。                                                                                            |
-| `hb-sdk remote deploy --release-note <text> [--skip-build \| --from-version <version>] [--auto-publish]` | 构建、上传并提交当前小程序版本审核；`--skip-build` 跳过 build 直接上传 `dist/`，`--from-version` 复用指定历史版本产物。 |
+| `hb-sdk remote deploy --release-note <text> [--from-version <version>] [--auto-publish]` | 构建、上传并提交当前小程序版本审核；`--from-version` 复用指定历史版本产物。 |
 | `hb-sdk remote versions`                                                                                 | 列出绑定小程序的远端版本。                                                                                              |
 | `hb-sdk remote preview <version>`                                                                        | 查看指定版本的远端预览入口。                                                                                            |
 | `hb-sdk remote release <version> [--yes]`                                                                | 发布审核通过的版本；非 TTY 环境必须传 `--yes`。                                                                         |
@@ -431,23 +431,20 @@ try {
 1. 校验 `heybox.miniProgramId`、发布日志和登录态。
 2. 读取服务端 current entity 和绑定小程序详情，确认 `detail.entity_id` 与 current entity 一致；主体不一致时直接失败，不触发 precheck、build、upload 或 submit audit。
 3. 普通 remote deploy 读取 `package.json.version`，主体校验通过后、build 前调用 `/mall/developer/user_miniprogram/version/precheck`，入参为 `mini_program_id`、`version`、`release_note`、`auto_publish`。
-4. 触发 `<pm> run build`，除非使用 `--skip-build`。
-5. 解析 `dist/manifest.json`，校验 `version` 为 `x.y.z`，自动剥离 BOM；普通 remote deploy 要求该版本与 precheck 使用的 `package.json.version` 一致。
-6. `--skip-build` 会先读取已有 `dist/manifest.json.version`，再调用 precheck。
-7. `--from-version <version>` 会跳过本地 build、`dist/` 读取和 CDN 上传，直接让远端复用指定历史版本产物提交审核；它与 `--skip-build` 互斥。
-8. 遍历 `dist/` 文件，跳过 `manifest.json`、`.DS_Store`、`.map`；遇到 symlink 或 `node_modules` 直接报错。
-9. 校验所有上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
-10. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 COS。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
-11. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
-12. 全部上传成功后调用 `/mall/developer/user_miniprogram/version/submit_audit`；`--from-version` 路径会直接调用提交审核接口并传入 `source_version`。CLI 输出提交审核成功、发布策略和可用的 preview URL；后端原始失败细节只在 `--verbose` 下展示。
+4. 触发 `<pm> run build`。
+5. 解析 `dist/manifest.json`，校验 `version` 与自动生成的 `sdkVersion` 均为合法 SemVer，自动剥离 BOM；普通 remote deploy 要求业务版本与 precheck 使用的 `package.json.version` 一致。
+6. `--from-version <version>` 会跳过本地 build、`dist/` 读取和 CDN 上传，直接让远端复用指定历史版本产物提交审核。
+7. 遍历 `dist/` 文件，跳过 `manifest.json`、`.DS_Store`、`.map`；遇到 symlink 或 `node_modules` 直接报错。
+8. 校验所有上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
+9. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 COS。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
+10. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
+11. 全部上传成功后调用 `/mall/developer/user_miniprogram/version/submit_audit`；`--from-version` 路径会直接调用提交审核接口并传入 `source_version`。CLI 输出提交审核成功、发布策略和可用的 preview URL；后端原始失败细节只在 `--verbose` 下展示。
 
 默认 `auto_publish=false`，审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布；使用 `--auto-publish` 时提交 `auto_publish=true`，审核通过后自动发布。未发布候选版本可通过 `hb-sdk remote allowlist add <heybox_id>` 加入预览白名单，让指定用户在广场看到；正式入口使用 `mini_program_id`，`mini_url` 仅用于本地调试。
 
-`--skip-build` 用于 CI 双阶段：上一步已经 build 完缓存好了 `dist/`，本步只做预检、上传和提交审核。`dist/manifest.json` 或 `dist/index.html` 缺失会立即报错。
+`--from-version <version>` 用于复用已经上传过的远端历史版本产物提交新一轮审核。该模式不读取本地 `dist/`，也不会执行 build 或上传；目标审核版本由服务端根据版本表最高 SemVer 自动派生。
 
-`--from-version <version>` 用于复用已经上传过的远端历史版本产物提交新一轮审核。该模式不读取本地 `dist/`，也不会执行 build 或上传；目标审核版本由服务端根据版本表最高 SemVer 自动派生。不要和 `--skip-build` 同时使用。
-
-`manifest.json` 不会上传到 CDN，只作为 submit audit 请求的 `manifest` 字段提交。这与 Vite 插件文档中的契约一致。名称、icon 和介绍图从 `package.json.heybox.miniProgramProfile` 读取，并随 precheck 和 submit audit 一起提交：
+`manifest.json` 不会上传到 CDN，只作为 submit audit 请求的 `manifest` 字段提交。`sdkVersion` 由 SDK 构建自动生成，业务配置不能覆盖；复用历史 Version Artifact 时继续使用源 Artifact 的 `sdkVersion`。名称、icon 和介绍图从 `package.json.heybox.miniProgramProfile` 读取，并随 precheck 和 submit audit 一起提交：
 
 ```json
 {
@@ -491,9 +488,9 @@ hb-sdk remote deploy --env-file .env.local --release-note "本地联调"   # 显
 hb-sdk remote deploy --env test --service-tag other-tag --release-note "灰度"   # 单项 flag 覆盖预设
 ```
 
-`--env <name>` 会读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级高于 `--env`；两者也可通过 `HB_SDK_ENV=<name>` 触发。加载遵循 dotenv 惯例：不覆盖进程已有的同名变量，因此 CI 或命令行显式设置的值优先。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。`--verbose` 会打印生效的文件路径和被跳过的 key。
+`--env <name>` 会读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级高于 `--env`；两者也可通过 `HB_SDK_ENV=<name>` 触发。加载遵循 dotenv 惯例：不覆盖进程已有的同名变量，因此 CI 或命令行显式设置的值优先。使用 `--env <name>` 或 `HB_SDK_ENV=<name>` 执行 `remote deploy` 时，CLI 还会把同一个 `name` 作为 `--mode <name>` 传给项目 build，使 CLI 后端环境与 Vite mode 保持一致。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。`--verbose` 会打印生效的文件路径和被跳过的 key。
 
-`--api-base-url` 优先于 `HB_SDK_API_BASE_URL`，影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`--login-base-url` 优先于 `HB_SDK_LOGIN_BASE_URL`，用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。`--service-tag <tag>` 优先于 `HB_SDK_SERVICE_TAG`，给 Heybox 后台请求附加 `x-rylai-service-tag` header，并复用命中的 tag 追加 `special_tag` 请求参数，用于开发环境路由或灰度验证；仓库内开发也可继续在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置 path-prefix 级 `special_tag`。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。`hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
+`--api-base-url` 优先于 `HB_SDK_API_BASE_URL`，影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`--login-base-url` 优先于 `HB_SDK_LOGIN_BASE_URL`，用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。`--service-tag <tag>` 优先于 `HB_SDK_SERVICE_TAG`，给 Heybox 后台请求附加 `x-rylai-service-tag` header，并复用命中的 tag 追加 `special_tag` 请求参数，用于开发环境路由或灰度验证。手动 Vite build 的最低 SDK 版本门禁请求会同时携带该 header 和 query；`remote deploy` 的子构建不执行客户端最低版本门禁。仓库内开发也可继续在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置 path-prefix 级 `special_tag`。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。`hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
 
 ## hb-sdk remote 命令参考
 
@@ -513,7 +510,7 @@ hb-sdk remote deploy --env test --service-tag other-tag --release-note "灰度"
 | `hb-sdk remote allowlist add <heybox-id...>`                                                             | 添加十进制 Heybox ID 到预览白名单。                                                                                                                |
 | `hb-sdk remote allowlist remove <heybox-id...>`                                                          | 从预览白名单移除非 owner 条目。                                                                                                                    |
 | `hb-sdk remote allowlist set <heybox-id...>`                                                             | 替换非 owner 白名单条目，并保留平台返回的 owner 语义。                                                                                             |
-| `hb-sdk remote deploy --release-note <text> [--skip-build \| --from-version <version>] [--auto-publish]` | 构建、上传或复用历史产物并提交当前版本审核。                                                                                                       |
+| `hb-sdk remote deploy --release-note <text> [--from-version <version>] [--auto-publish]` | 构建、上传或复用历史产物并提交当前版本审核。                                                                                                       |
 | `hb-sdk remote versions`                                                                                 | 列出当前绑定小程序的远端版本。                                                                                                                     |
 | `hb-sdk remote preview <version>`                                                                        | 查看指定版本的远端预览入口。                                                                                                                       |
 | `hb-sdk remote release <version> [--yes]`                                                                | 发布审核通过的版本；交互式终端会确认，非 TTY 必须传 `--yes`。                                                                                      |
@@ -535,14 +532,13 @@ CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe
 
 ## 能力边界
 
-- SDK 实例创建后会自动开始握手；默认单例仍按需懒创建，`ready()`、`on()` 或任意模块能力调用都会创建默认单例并开始握手。
+- 导入 SDK 根包时会 eager 创建唯一默认实例并立即开始握手；`ready()` 只等待这次握手结果。
 - `ready()` 只等待已有握手结果，不主动触发新的握手；调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
 - `user.getInfo()`、`user.getCurrentUserDetail()`、`user.getCurrentUserProfile()`、`user.getPlatformAccountOverview()`、`user.getPlatformAccountInfo(platform)` 和 `user.getSteamGameList(options)` 不会触发登录；登录必须由业务在用户操作后调用 `auth.login()`。
 - 当前用户详情和平台账号 API 只允许读取当前登录用户，不支持传入 `userid` 查询其他人，也不透传 `/account/home_v2/` 原始响应。
 - 分享、截图、UI、设备、导航、storage 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。
 - `network.request()` 的 `validateStatus` 只在 SDK 本地执行，不会被序列化给父容器。
 - `on()` 返回取消监听函数；组件卸载或页面销毁时应主动取消监听。
-- 使用 `createMiniProgramSDK()` 创建独立实例后，不再需要时应调用 `destroy()`。
 - 构建产物可以包含 `dist/manifest.json`，业务代码不应自行 fetch 已部署的 manifest；这个文件由发布流水线读取并上送后台。
 
 ## Manifest
@@ -551,11 +547,12 @@ CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe
 
 ```json
 {
-  "version": "1.2.3"
+  "version": "1.2.3",
+  "sdkVersion": "0.6.1"
 }
 ```
 
-`version` 来自小程序项目自身的 `package.json.version`。`hb-sdk create` 生成的模板默认已注册插件；现有 Vite 项目可以在 `vite.config.ts` 中手动接入：
+`version` 来自小程序项目自身的 `package.json.version`，`sdkVersion` 来自当前安装 SDK 的构建版本且不能由业务覆盖。`hb-sdk create` 生成的模板默认已注册插件；现有 Vite 项目可以在 `vite.config.ts` 中手动接入：
 
 ```ts
 import { miniappManifest } from '@heybox/hb-sdk/vite';
@@ -569,12 +566,18 @@ export default defineConfig({
 
 `base: './'` 用于让构建产物里的 JS/CSS/图片资源以 `./assets/...` 相对路径引用，避免小程序资源目录不是站点根路径时访问 `/assets/...` 失败。若没有显式配置 `base`，`miniappManifest()` 也会在 build 时默认补成 `./`。
 
+工坊小程序构建产物只能在兼容的小黑盒 Runtime 中启动。普通浏览器直接打开时不会执行标准业务脚本，并会提示在小黑盒 APP 内打开。项目应使用标准 Vite module 入口。
+
+插件只接受单页应用：输出目录只能存在入口 `index.html`。build 会用结构化 HTML parser 校验入口，并把平台 CSP 插入 `<head>` 首位；已有 CSP 会原样保留，两份策略按浏览器交集生效。正式策略禁止 `fetch`、XHR、WebSocket、EventSource、Beacon、Worker、iframe、表单和对象加载等浏览器原生出口；业务网络请求应使用 `network.request()`。dev 使用相同策略，只额外放行当前 Vite 的精确 HMR WebSocket 地址。
+
+meta refresh、外部 anchor、`dns-prefetch`、`preconnect`、`prerender`、外部资源 URL 和额外 HTML 会使 build 失败。内联 script/style 允许，但 `unsafe-eval` 不允许。`dev` 和手动 Vite build 会读取 `/user_miniprogram/public/sdk_config` 的 `minimumSdkVersion`；最新请求失败时只回退当前 Remote Environment 下 24 小时内的有效缓存，无缓存则默认阻断并提示升级 `@heybox/hb-sdk@latest`。`hb-sdk remote deploy`（包括 `--from-version`）不执行客户端最低版本查询或比较，但仍校验 Manifest 结构并经过服务端 precheck / submit-audit 策略。
+
 失败与警告语义：
 
 - 读取 `package.json` 失败或 JSON 解析失败：`vite build` 直接失败，并输出具体原因。
 - `package.json.version` 不是非空字符串：`vite build` 直接失败。
-- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 输出 warning 并写入 manifest；`hb-sdk remote deploy` 会拒绝发布，必须改成实际 `x.y.z` 版本。
-- 版本号不满足极简 semver 形态 `x.y.z`：只输出 Rollup/Vite warning，仍会写入 manifest。
+- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 直接失败，必须改成实际 SemVer。
+- 版本号不是严格 SemVer、包含 build metadata 或缺少 `sdkVersion`：build/deploy 直接失败。
 
 `manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
 
@@ -586,7 +589,6 @@ export default defineConfig({
 
 - `ready`、`on`、`off`
 - `auth`、`user`、`share`、`viewport`、`storage`、`cloud`、`network`、`ui`、`device`、`navigation`
-- `createMiniProgramSDK`、`MiniProgramSDK`
 - `HbMiniProgramSDKError`、`HbMiniProgramNetworkError`
 - 各模块公开类型，例如 `MiniProgramNetworkRequestConfig`、`MiniProgramNetworkResponse`、`MiniProgramUserInfoResult`
 
@@ -594,6 +596,8 @@ export default defineConfig({
 
 构建时插件 `miniappManifest` 通过 `@heybox/hb-sdk/vite` 子入口导出，仅供 `vite.config.ts` 使用，不应在小程序业务代码里 import。
 
+从 0.5 升级时请阅读 [0.6 迁移说明](./docs/migration-0.6.md)。
+
 ## 本仓库开发
 
 ```bash

package/dist/cli-chunks/{context-CKJlNcSN.cjs → context-D0BowvGu.cjs}

@@ -1,10 +1,30 @@
 'use strict';
 
-var session = require('./session-dRGPpyS1.cjs');
+var session = require('./session-0XuUaVOO.cjs');
+var index = require('./index-BnCDW-BB.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
 
+const APIUserMiniprogramPublicSdkConfigPath = '/user_miniprogram/public/sdk_config';
+function createUserMiniprogramPublicSdkConfigRequest(serviceTag) {
+    return {
+        path: APIUserMiniprogramPublicSdkConfigPath,
+        searchParams: serviceTag ? { special_tag: serviceTag } : {},
+        headers: serviceTag ? { 'x-rylai-service-tag': serviceTag } : {},
+    };
+}
+function parseUserMiniprogramPublicSdkConfigResult(value) {
+    if (!isRecord(value) ||
+        typeof value.minimum_sdk_version !== 'string') {
+        throw new Error('公共 SDK 配置响应无效');
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+
 var re = {exports: {}};
 
 var constants;
@@ -2794,6 +2814,7 @@ const MINIAPP_UPLOAD_SCOPE = 'activity';
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 const MINIAPP_UPLOAD_BATCH_SIZE = 50;
 const MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES = 100 * 1024 * 1024;
+const PUBLIC_USER_MINIPROGRAM_SDK_CONFIG_API_PATH = APIUserMiniprogramPublicSdkConfigPath;
 const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = '/mall/developer/user_miniprogram/access_status';
 const DEVELOPER_ENTITY_LIST_API_PATH = '/mall/developer/entity/list';
 const DEVELOPER_ENTITY_SWITCH_API_PATH = '/mall/developer/entity/switch';
@@ -2909,6 +2930,20 @@ function createRemoteApiClient(options) {
         listUserMiniprogramVersions: (requestOptions) => listUserMiniprogramVersions(requestOptions, options),
     };
 }
+async function getPublicSdkConfig(runtime) {
+    const fetchImpl = runtime.fetchImpl ?? fetch;
+    const serviceTag = index.resolveHeyboxRylaiServiceTag(PUBLIC_USER_MINIPROGRAM_SDK_CONFIG_API_PATH);
+    const request = createUserMiniprogramPublicSdkConfigRequest(serviceTag);
+    const response = await fetchImpl(session.createHeyboxApiUrl(runtime.baseUrl ?? 'https://api.xiaoheihe.cn', request.path, request.searchParams), {
+        method: 'GET',
+        headers: {
+            Referer: session.HEYBOX_WEB_REFERER,
+            ...request.headers,
+        },
+    });
+    const result = await readRequiredResult(response, request.path);
+    return parseUserMiniprogramPublicSdkConfigResult(result);
+}
 async function listDeveloperEntities(runtime) {
     return remoteGet(DEVELOPER_ENTITY_LIST_API_PATH, {}, runtime);
 }
@@ -3188,6 +3223,7 @@ exports.SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH = SUBMIT_USER_MINIPROGRAM_AUDIT_A
 exports.createRemoteApiClientForEnvironment = createRemoteApiClientForEnvironment;
 exports.getBoundMiniProgram = getBoundMiniProgram;
 exports.getMiniappUploadKey = getMiniappUploadKey;
+exports.getPublicSdkConfig = getPublicSdkConfig;
 exports.normalizeRelativePath = normalizeRelativePath;
 exports.readBoundMiniProgramId = readBoundMiniProgramId;
 exports.readBoundMiniProgramIdFromPackageJson = readBoundMiniProgramIdFromPackageJson;

package/dist/cli-chunks/{create-OZOIdeBz.cjs → create-C0afRvs9.cjs}

@@ -5,7 +5,7 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var require$$0 = require('fs');
 var require$$1 = require('path');
-var index = require('./index-CsOcGUzF.cjs');
+var index = require('./index-BnCDW-BB.cjs');
 require('node:module');
 require('os');
 require('readline');

package/dist/cli-chunks/{dev-DXz8izSJ.cjs → dev-CN307p_G.cjs}

@@ -9,8 +9,9 @@ var node_url = require('node:url');
 var net = require('node:net');
 var node_http = require('node:http');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-CsOcGUzF.cjs');
-var context = require('./context-CKJlNcSN.cjs');
+var index = require('./index-BnCDW-BB.cjs');
+var context = require('./context-D0BowvGu.cjs');
+var session = require('./session-0XuUaVOO.cjs');
 require('node:process');
 require('node:buffer');
 require('node:util');
@@ -24,7 +25,6 @@ require('events');
 require('stream');
 require('buffer');
 require('util');
-require('./session-dRGPpyS1.cjs');
 require('node:crypto');
 require('fs');
 require('constants');
@@ -599,6 +599,7 @@ function readErrorMessage(error) {
 
 const MINI_PROGRAM_URL_QUERY_PARAM = 'mini_url';
 const MINI_PROGRAM_RUNTIME_URL_QUERY_PARAM = 'runtime_url';
+const MINI_PROGRAM_SDK_VERSION_QUERY_PARAM = 'sdk_version';
 const MINI_PROGRAM_DEV_SHELL_URL = 'heybox-mini-dev://sandbox';
 const OPEN_IN_APP_URL = 'https://api.xiaoheihe.cn/open_inapp/';
 function createMacAppProtocol(appUrl, options = {}) {
@@ -636,6 +637,10 @@ function createPartiallyEncodedMiniProgramDevShellUrl(appUrl, options) {
     if (hasRuntimeUrl(options.runtimeUrl)) {
         devShellUrl += `&${MINI_PROGRAM_RUNTIME_URL_QUERY_PARAM}=${encodeURIComponent(options.runtimeUrl)}`;
     }
+    const sdkVersion = options.sdkVersion?.trim();
+    if (sdkVersion) {
+        devShellUrl += `&${MINI_PROGRAM_SDK_VERSION_QUERY_PARAM}=${encodeURIComponent(sdkVersion)}`;
+    }
     return devShellUrl;
 }
 function createEncodedMiniProgramDevShellUrl(appUrl, options) {
@@ -648,6 +653,10 @@ function createEncodedMiniProgramDevShellUrl(appUrl, options) {
     if (hasRuntimeUrl(options.runtimeUrl)) {
         devShellUrl.searchParams.set(MINI_PROGRAM_RUNTIME_URL_QUERY_PARAM, options.runtimeUrl);
     }
+    const sdkVersion = options.sdkVersion?.trim();
+    if (sdkVersion) {
+        devShellUrl.searchParams.set(MINI_PROGRAM_SDK_VERSION_QUERY_PARAM, sdkVersion);
+    }
     return devShellUrl.toString();
 }
 function hasRuntimeUrl(runtimeUrl) {
@@ -657,6 +666,96 @@ function createHeyboxProtocol(payload) {
     return `heybox://${encodeURIComponent(JSON.stringify(payload))}`;
 }
 
+const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+const CACHE_FILE_NAME = 'minimum-sdk-versions.json';
+async function resolveMinimumSdkVersion(options) {
+    const now = options.now ?? Date.now();
+    const cachePath = path.join(options.cacheDir, CACHE_FILE_NAME);
+    const cache = await readCache(cachePath);
+    let minimumSdkVersion;
+    try {
+        minimumSdkVersion = validateStableSdkVersion(await options.fetchMinimumSdkVersion(), 'minimumSdkVersion');
+    }
+    catch {
+        const cached = cache.environments[options.environment];
+        const cacheAge = cached ? now - cached.fetchedAt : Number.NaN;
+        if (cached && Number.isFinite(cached.fetchedAt) && cacheAge >= 0 && cacheAge <= CACHE_MAX_AGE_MS) {
+            try {
+                return validateStableSdkVersion(cached.minimumSdkVersion, 'cached minimumSdkVersion');
+            }
+            catch {
+                // 非法缓存按不存在处理。
+            }
+        }
+        throw new Error('MINIMUM_SDK_VERSION_UNAVAILABLE：无法获取最低 SDK 版本，且没有 24 小时内的有效缓存');
+    }
+    cache.environments[options.environment] = { fetchedAt: now, minimumSdkVersion };
+    try {
+        await writeCache(cachePath, cache);
+    }
+    catch {
+        // 已校验的远端策略仍然可信；缓存只是离线回退优化。
+    }
+    return minimumSdkVersion;
+}
+function validateCurrentSdkVersion(currentSdkVersion, minimumSdkVersion, options) {
+    const current = validateSdkVersion(currentSdkVersion, '当前 SDK 版本');
+    const minimum = validateStableSdkVersion(minimumSdkVersion, 'minimumSdkVersion');
+    if (!options.allowPrerelease && context.semverExports.prerelease(current) !== null) {
+        throw new Error('正式发布不允许使用预发布 SDK，请运行 pnpm add @heybox/hb-sdk@latest 后重新构建');
+    }
+    if (!context.semverExports.satisfies(current, `>=${minimum}`, { includePrerelease: options.allowPrerelease })) {
+        throw new Error(`SDK_VERSION_TOO_LOW：当前 @heybox/hb-sdk@${current} 低于最低版本 ${minimum}，请运行 pnpm add @heybox/hb-sdk@latest`);
+    }
+    return current;
+}
+function validateSdkVersion(value, label) {
+    const normalized = String(value).trim();
+    const parsed = context.semverExports.parse(normalized);
+    if (!parsed || parsed.version !== normalized || parsed.build.length > 0) {
+        throw new Error(`${label} 必须是合法 SemVer：${normalized}`);
+    }
+    return normalized;
+}
+function validateStableSdkVersion(value, label) {
+    const normalized = validateSdkVersion(value, label);
+    if (context.semverExports.prerelease(normalized) !== null)
+        throw new Error(`${label} 必须是稳定 SemVer：${normalized}`);
+    return normalized;
+}
+async function readCache(cachePath) {
+    try {
+        const parsed = JSON.parse(await fs$1.readFile(cachePath, 'utf8'));
+        if (parsed && typeof parsed === 'object' && parsed.environments && typeof parsed.environments === 'object')
+            return parsed;
+    }
+    catch {
+        // 缓存缺失或损坏时继续请求最新配置。
+    }
+    return { environments: {} };
+}
+async function writeCache(cachePath, cache) {
+    await fs$1.mkdir(path.dirname(cachePath), { recursive: true });
+    const temporaryPath = `${cachePath}.${process.pid}.tmp`;
+    await fs$1.writeFile(temporaryPath, `${JSON.stringify(cache, null, 2)}\n`, { mode: 0o600 });
+    await fs$1.rename(temporaryPath, cachePath);
+}
+
+const paths = index.envPaths('hb-sdk');
+async function enforceRemoteSdkVersion(options) {
+    const minimumSdkVersion = await resolveMinimumSdkVersion({
+        cacheDir: options.cacheDir ?? paths.cache,
+        environment: options.environment,
+        fetchMinimumSdkVersion: async () => (await context.getPublicSdkConfig({ baseUrl: options.environment, fetchImpl: options.fetchImpl })).minimum_sdk_version,
+    });
+    return validateCurrentSdkVersion(options.sdkVersion, minimumSdkVersion, { allowPrerelease: options.allowPrerelease });
+}
+
+/** 构建时替换为当前发布包的实际版本。 */
+const HB_SDK_VERSION = typeof undefined === 'string'
+    ? undefined
+    : '0.6.1';
+
 const DEFAULT_APP_PORT = 5173;
 const DEFAULT_MOCK_PORT = 5174;
 const DEV_LISTEN_HOST = '0.0.0.0';
@@ -667,6 +766,13 @@ const VITE_LOG_LEVEL = 'warn';
 async function runDevCommand(options, runtime = {}) {
     const logger = runtime.logger ?? index.createCliLogger();
     const fetchImpl = runtime.fetchImpl ?? fetch;
+    const environment = session.resolveHeyboxApiBaseUrl({ env: runtime.env });
+    await (runtime.enforceRemoteSdkVersion ?? enforceRemoteSdkVersion)({
+        sdkVersion: HB_SDK_VERSION,
+        environment,
+        fetchImpl,
+        allowPrerelease: true,
+    });
     const openUrl = runtime.openExternalUrl ?? browser.openExternalUrl;
     const networkInterfaceSnapshot = (runtime.networkInterfaces ?? os.networkInterfaces)();
     const getPortImpl = runtime.getPort ?? getPorts;
@@ -678,6 +784,7 @@ async function runDevCommand(options, runtime = {}) {
     });
     const resolvedOptions = {
         ...options,
+        hmrHost: createLanInterfaceCandidates(networkInterfaceSnapshot)[0]?.address,
         port: appPort,
     };
     const projectRoot = findProjectRoot(runtime.cwd ?? process.cwd());
@@ -697,9 +804,11 @@ async function runDevCommand(options, runtime = {}) {
     });
     const lanAddresses = createLanAddressCandidates({
         appUrl,
+        hmrHost: resolvedOptions.hmrHost,
         interfaces: networkInterfaceSnapshot,
         miniProgramId: devLaunchContext.miniProgramId,
         runtimeUrl: options.runtimeUrl,
+        sdkVersion: HB_SDK_VERSION,
         viteNetworkUrls: appServer.resolvedUrls?.network ?? [],
     });
     const closers = [() => appServer.close()];
@@ -715,6 +824,7 @@ async function runDevCommand(options, runtime = {}) {
                 ? createMacAppProtocol(appUrl, {
                     miniProgramId: devLaunchContext.miniProgramId,
                     runtimeUrl: options.runtimeUrl,
+                    sdkVersion: HB_SDK_VERSION,
                 })
                 : undefined,
             nativeAppLaunchUnavailableReason: devLaunchContext.nativeAppLaunchUnavailableReason,
@@ -822,6 +932,7 @@ function createViteServerOptions(projectRoot, options) {
         cors: true,
         hmr: {
             clientPort: options.port ?? DEFAULT_APP_PORT,
+            ...(options.hmrHost ? { host: options.hmrHost } : {}),
         },
         host: DEV_LISTEN_HOST,
         port: options.port ?? DEFAULT_APP_PORT,
@@ -972,6 +1083,7 @@ function createLanAddressCandidates(options) {
         .map((url) => [readUrlHost(url), url])
         .filter((entry) => Boolean(entry[0])));
     const candidates = createLanInterfaceCandidates(options.interfaces)
+        .filter(({ address }) => address === options.hmrHost)
         .map(({ address, id, name }) => {
         const appUrl = viteNetworkUrlByHost.get(address) ?? replaceUrlHost(options.appUrl, address);
         if (!appUrl) {
@@ -988,11 +1100,13 @@ function createLanAddressCandidates(options) {
             candidate.mobileAppQrPayload = createMobileAppQrPayload(appUrl, {
                 miniProgramId: options.miniProgramId,
                 runtimeUrl,
+                sdkVersion: options.sdkVersion,
             });
         }
         else {
             candidate.mobileAppQrPayload = createMobileAppQrPayload(appUrl, {
                 miniProgramId: options.miniProgramId,
+                sdkVersion: options.sdkVersion,
             });
         }
         return candidate;

package/dist/cli-chunks/{doctor-DjMSJoQ5.cjs → doctor-VW0nKg5q.cjs}

@@ -4,7 +4,7 @@ var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var os = require('node:os');
 var path = require('node:path');
-var index = require('./index-CsOcGUzF.cjs');
+var index = require('./index-BnCDW-BB.cjs');
 require('node:module');
 require('path');
 require('os');

package/dist/cli-chunks/{index-CsOcGUzF.cjs → index-BnCDW-BB.cjs}

@@ -234,19 +234,19 @@ function requireArgument () {
 
 var command = {};
 
-const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-CsOcGUzF.cjs', document.baseURI).href)));
+const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BnCDW-BB.cjs', document.baseURI).href)));
 function __require$4() { return require$5("node:events"); }
 
-const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-CsOcGUzF.cjs', document.baseURI).href)));
+const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BnCDW-BB.cjs', document.baseURI).href)));
 function __require$3() { return require$4("node:child_process"); }
 
-const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-CsOcGUzF.cjs', document.baseURI).href)));
+const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BnCDW-BB.cjs', document.baseURI).href)));
 function __require$2() { return require$3("node:path"); }
 
-const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-CsOcGUzF.cjs', document.baseURI).href)));
+const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BnCDW-BB.cjs', document.baseURI).href)));
 function __require$1() { return require$2("node:fs"); }
 
-const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-CsOcGUzF.cjs', document.baseURI).href)));
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BnCDW-BB.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -13203,6 +13203,13 @@ function loadEnvPreset(argv, options = {}) {
         targetEnv[key] = value;
         appliedKeys.push(key);
     }
+    const explicitName = readEnvNameArgFromArgv(argv);
+    if (explicitName) {
+        targetEnv.HB_SDK_ENV = explicitName;
+        if (!appliedKeys.includes('HB_SDK_ENV')) {
+            appliedKeys.push('HB_SDK_ENV');
+        }
+    }
     return { filePath, appliedKeys, skippedKeys };
 }
 /**
@@ -13316,7 +13323,7 @@ function getPathname(pathWithQuery) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.5.18';
+const BUILT_CLI_VERSION = '0.6.1';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13389,7 +13396,7 @@ function createCliProgram(overrides = {}) {
         .description('hb-sdk developer tools')
         .version(getCliVersion())
         .option('-v, --verbose', '输出详细调试信息')
-        .option('--env <name>', '加载项目根下 .env.<name> 预设，把其中的 HB_SDK_* 变量注入当前进程（不覆盖已有值）')
+        .option('--env <name>', '加载项目根下 .env.<name> 预设，并将 deploy 构建的 Vite mode 设为 name')
         .option('--env-file <path>', '显式指定 .env 文件路径，优先级高于 --env')
         .showHelpAfterError()
         .exitOverride();
@@ -13526,7 +13533,6 @@ function installRemoteCommands(program, handlers, resolveLogger) {
     addRemotePublicOptions(remote
         .command('deploy')
         .description('构建并提交当前小程序版本审核')
-        .option('--skip-build', '跳过 build，直接读 dist 目录上传并提交审核')
         .option('--from-version <version>', '复用指定历史版本产物提交审核')
         .option('--release-note <text>', '发布日志，提交审核必填')
         .option('--auto-publish', '审核通过后自动发布；默认需在 CLI 中手动发布')).action(createRemoteAction(handlers, resolveLogger, 'deploy', (command) => {
@@ -13535,7 +13541,6 @@ function installRemoteCommands(program, handlers, resolveLogger) {
             autoPublish: Boolean(options.autoPublish),
             fromVersion: readStringOption(options.fromVersion),
             releaseNote: readStringOption(options.releaseNote),
-            skipBuild: Boolean(options.skipBuild),
         };
     }));
     addRemotePublicOptions(remote.command('versions').description('列出当前绑定小程序的远程版本')).action(createRemoteAction(handlers, resolveLogger, 'versions'));
@@ -13639,31 +13644,31 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-Ct-46gLx.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-BsyENL1d.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-Ct-46gLx.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-BsyENL1d.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-Ct-46gLx.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-BsyENL1d.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-OZOIdeBz.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-C0afRvs9.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DXz8izSJ.cjs'); });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-CN307p_G.cjs'); });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-DjMSJoQ5.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-VW0nKg5q.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-C77axNSw.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-BSvvxvVv.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{index-Cl5HFTBW.cjs → index-DcZLSI_y.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-CsOcGUzF.cjs');
+var index$2 = require('./index-BnCDW-BB.cjs');
 var require$$0$2 = require('fs');
 var require$$2$1 = require('crypto');
 var require$$1$2 = require('path');
 var require$$0$3 = require('assert');
 var require$$4$2 = require('events');
 var require$$1$1 = require('util');
-var context$1 = require('./context-CKJlNcSN.cjs');
+var context$1 = require('./context-D0BowvGu.cjs');
 var require$$0$5 = require('net');
 var require$$0$4 = require('url');
 var require$$2$2 = require('http');

package/dist/cli-chunks/{login-Ct-46gLx.cjs → login-BsyENL1d.cjs}

@@ -3,9 +3,9 @@
 var promises = require('node:readline/promises');
 var node_crypto = require('node:crypto');
 var node_http = require('node:http');
-var session = require('./session-dRGPpyS1.cjs');
+var session = require('./session-0XuUaVOO.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-CsOcGUzF.cjs');
+var index = require('./index-BnCDW-BB.cjs');
 require('node:path');
 require('fs');
 require('constants');