@heybox/hb-sdk 0.5.17 → 0.6.0

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
 {
@@ -473,10 +470,27 @@ hb-sdk login --login-base-url https://login.test.xiaoheihe.cn
 hb-sdk remote deploy --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "测试环境验证"
 hb-sdk remote deploy --verbose --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "排查预检失败"
 
-HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://127.0.0.1:8080 --release-note "本地后台联调"
+HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://127.0.1:8080 --release-note "本地后台联调"
+```
+
+切换测试环境时往往需要同时配置后台 host、登录 host 和 service tag。为避免每条命令都重复书写这些 env/flag，CLI 支持加载 `.env.<name>` 预设：
+
+```bash
+# 在项目根准备 .env.test（可提交当团队默认，或 gitignore 仅本地保留）
+#   HB_SDK_API_BASE_URL=https://api.test.xiaoheihe.cn
+#   HB_SDK_LOGIN_BASE_URL=https://login.test.xiaoheihe.cn
+#   HB_SDK_SERVICE_TAG=my-test-tag
+
+hb-sdk remote deploy --env test --release-note "测试环境验证"   # 一次加载三项配置
+hb-sdk remote info --env test                                  # 复用同一预设
+HB_SDK_ENV=test hb-sdk remote versions                        # 环境变量形式，CI 友好
+hb-sdk remote deploy --env-file .env.local --release-note "本地联调"   # 显式指定文件路径
+hb-sdk remote deploy --env test --service-tag other-tag --release-note "灰度"   # 单项 flag 覆盖预设
 ```
 
-`--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 登录态是否属于同一个登录环境。仓库内开发可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置 `default_tag` 或 path-prefix 级 `special_tag`，给 Heybox 后台请求附加 `x-rylai-service-tag` header，并复用命中的 tag 追加 `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()` 不受这些配置影响。
+`--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` 请求参数，用于开发环境路由或灰度验证。deploy 子构建会继承 `.env.<name>` 中的 `HB_SDK_SERVICE_TAG`，Vite 最低 SDK 版本门禁请求也会同时携带该 header 和 query；仓库内开发也可继续在 `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 命令参考
 
@@ -496,7 +510,7 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 | `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`。                                                                                      |
@@ -518,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
@@ -534,11 +547,12 @@ CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe
 
 ```json
 {
-  "version": "1.2.3"
+  "version": "1.2.3",
+  "sdkVersion": "0.6.0"
 }
 ```
 
-`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';
@@ -552,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`、build 和 deploy 会读取 `/user_miniprogram/public/sdk_config` 的 `minimumSdkVersion`；最新请求失败时只回退当前 Remote Environment 下 24 小时内的有效缓存，无缓存则默认阻断并提示升级 `@heybox/hb-sdk@latest`。
+
 失败与警告语义：
 
 - 读取 `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 打包器未来通过其他子入口扩展。
 
@@ -569,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`
 
@@ -577,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/{create-CPIjDM-n.cjs → create-DYb53EQ-.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-Dor8wa6R.cjs');
+var index = require('./index-CCeHouBU.cjs');
 require('node:module');
 require('os');
 require('readline');

package/dist/cli-chunks/{dev-Cr2u9ajy.cjs → dev-CPKTuA6q.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-Dor8wa6R.cjs');
-var context = require('./context-mav2gs13.cjs');
+var index = require('./index-CCeHouBU.cjs');
+var sdkVersionPolicy = require('./sdk-version-policy-B1CFC1Dk.cjs');
+var session = require('./session-DIcRjyDY.cjs');
 require('node:process');
 require('node:buffer');
 require('node:util');
@@ -24,7 +25,6 @@ require('events');
 require('stream');
 require('buffer');
 require('util');
-require('./session-BMSThs93.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,11 @@ function createHeyboxProtocol(payload) {
     return `heybox://${encodeURIComponent(JSON.stringify(payload))}`;
 }
 
+/** 构建时替换为当前发布包的实际版本。 */
+const HB_SDK_VERSION = typeof undefined === 'string'
+    ? undefined
+    : '0.6.0';
+
 const DEFAULT_APP_PORT = 5173;
 const DEFAULT_MOCK_PORT = 5174;
 const DEV_LISTEN_HOST = '0.0.0.0';
@@ -667,6 +681,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 ?? sdkVersionPolicy.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 +699,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 +719,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 +739,7 @@ async function runDevCommand(options, runtime = {}) {
                 ? createMacAppProtocol(appUrl, {
                     miniProgramId: devLaunchContext.miniProgramId,
                     runtimeUrl: options.runtimeUrl,
+                    sdkVersion: HB_SDK_VERSION,
                 })
                 : undefined,
             nativeAppLaunchUnavailableReason: devLaunchContext.nativeAppLaunchUnavailableReason,
@@ -746,14 +771,14 @@ async function runDevCommand(options, runtime = {}) {
     installShutdownHandlers(closers, runtime.process ?? process);
 }
 async function loadDevLaunchContext(options) {
-    const miniProgramId = await context.readBoundMiniProgramId(options.projectRoot);
+    const miniProgramId = await sdkVersionPolicy.readBoundMiniProgramId(options.projectRoot);
     if (!miniProgramId) {
         const nativeAppLaunchUnavailableReason = '当前项目未绑定小程序。请先运行 hb-sdk remote create 或 hb-sdk remote bind <mini-program-id>。';
         options.logger.warn(`未读取到远端 Runtime 权限，Mock runtime 将默认拒绝受管能力：${nativeAppLaunchUnavailableReason}`);
         return { nativeAppLaunchUnavailableReason };
     }
     try {
-        const { detail, miniProgramId: verifiedMiniProgramId } = await options.logger.task('正在读取远端小程序权限', () => context.getBoundMiniProgram({
+        const { detail, miniProgramId: verifiedMiniProgramId } = await options.logger.task('正在读取远端小程序权限', () => sdkVersionPolicy.getBoundMiniProgram({
             cwd: options.projectRoot,
             env: options.env,
             fetchImpl: options.fetchImpl,
@@ -771,7 +796,7 @@ async function loadDevLaunchContext(options) {
     }
 }
 function canFallbackToDefaultRuntimePermissions(error) {
-    if (error instanceof context.MiniProgramProjectBindingError) {
+    if (error instanceof sdkVersionPolicy.MiniProgramProjectBindingError) {
         return error.code === 'MINI_PROGRAM_UNBOUND';
     }
     if (error instanceof TypeError && error.message === 'fetch failed') {
@@ -822,6 +847,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 +998,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 +1015,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-mIgvLfLl.cjs → doctor-TshFvqHC.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-Dor8wa6R.cjs');
+var index = require('./index-CCeHouBU.cjs');
 require('node:module');
 require('path');
 require('os');