@heybox/hb-sdk 0.4.3 → 0.4.5

package/README.md

@@ -1,6 +1,6 @@
 # @heybox/hb-sdk
 
-黑盒外部小程序前端 SDK。业务页面运行在黑盒父容器创建的 iframe 沙盒中，通过这个 SDK 等待容器 ready、获取登录态、唤起登录、分享、读取窗口信息、使用隔离 storage，以及发起受控网络请求。
+黑盒外部小程序前端 SDK。业务页面运行在黑盒父容器创建的 iframe 沙盒中，通过这个 SDK 等待容器 ready、获取登录态、唤起登录、分享、展示基础 UI、使用设备能力、控制容器导航、读取窗口信息、使用隔离 storage，以及发起受控网络请求。
 
 ## 快速开始
 
@@ -110,6 +110,53 @@ await share.screenshot({
 });
 ```
 
+### 基础 UI
+
+```ts
+import { ui } from '@heybox/hb-sdk';
+
+await ui.showToast({
+  message: '保存成功',
+  status: 'success',
+});
+
+await ui.showLoading({
+  dismissible: true,
+});
+
+await ui.hideLoading();
+```
+
+`showToast()` 的 `message` 会 trim 后发送给宿主，不能为空，最长 120 个字符；`status` 只支持 `success` 和 `error`，不传时展示普通文本 toast。loading 是全局单例，多次 `showLoading()` 会覆盖当前配置，`hideLoading()` 在未展示时也会成功。
+
+### 设备能力
+
+```ts
+import { device } from '@heybox/hb-sdk';
+
+await device.vibrate({
+  intensity: 'light',
+  delay: 0,
+});
+
+await device.setClipboard({
+  text: 'hello',
+});
+```
+
+`vibrate()` 的 `intensity` 默认为 `light`，还支持 `medium` 和 `heavy`；`delay` 默认为 `0`，必须是 `0..5000` 的整数毫秒。`setClipboard()` 第一版只支持文本写入，`text` 必须是非空字符串，最长 10000 个字符，不会自动 trim 写入内容，也不提供读取或清空剪贴板能力。
+
+### 导航控制
+
+```ts
+import { navigation } from '@heybox/hb-sdk';
+
+await navigation.reload();
+await navigation.close();
+```
+
+`navigation.close()` 请求宿主关闭当前小程序容器，`navigation.reload()` 请求宿主重载当前小程序页面/容器。调用后 JS 上下文可能被宿主销毁，不保证后续代码继续执行；这两个能力不接受 `reason`、`force`、`confirm` 或 `fallbackUrl` 等扩展参数。
+
 ### 窗口信息
 
 ```ts
@@ -233,17 +280,34 @@ try {
 | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `hb-sdk create <project-name>`                                           | 创建外部小程序模板。                                                                                                                                 |
 | `hb-sdk dev [--runtime-url <url>]`                                        | 启动当前项目的 Vite dev server 和浏览器 mock 宿主环境，并默认打开调试页；`--runtime-url` 会传给真实客户端 dev shell。                                |
-| `hb-sdk deploy --release-note <text> [--skip-build] [--auto-publish]` | 构建、上传并提交当前小程序版本审核。`--skip-build` 跳过 build 直接上传 `dist/`；默认审核通过后需在开放平台手动发布，`--auto-publish` 改为审核通过后自动发布。 |
 | `hb-sdk login [--login-base-url <url>]`                                  | 登录 Heybox，并把 CLI 自己需要的登录态和登录入口环境保存在本地缓存中。                                                                               |
 | `hb-sdk login status`                                                    | 查看脱敏后的 CLI 登录态。                                                                                                                            |
 | `hb-sdk login clear`                                                     | 清理 CLI 登录态。                                                                                                                                    |
 | `hb-sdk doctor`                                                          | 检查本机 `hb-sdk` Agent Skill 是否匹配当前 SDK，并输出手动安装/刷新命令。                                                                            |
+| `hb-sdk remote access`                                                   | 查看当前 CLI 用户是否具备开发者用户小程序创建和管理资格。                                                                                           |
+| `hb-sdk remote list [--status <status>] [--keyword <text>]`              | 列出当前 CLI 用户可管理的远端用户小程序，用于发现并绑定当前项目。                                                                                   |
+| `hb-sdk remote create --name <name> [--preview-image-url <url>] [--force-bind]` | 创建远端用户小程序并写入当前项目的 `package.json.heybox.miniProgramId`。                                                                       |
+| `hb-sdk remote bind <mini-program-id> [--force]`                         | 校验当前 CLI 用户可管理目标小程序后，再把它绑定到当前项目。                                                                                         |
+| `hb-sdk remote info`                                                     | 查看当前项目绑定的小程序详情。                                                                                                                       |
+| `hb-sdk remote update [--name <name>] [--preview-image-url <url>]`       | 更新绑定小程序的名称或远程预览图 URL。                                                                                                               |
+| `hb-sdk remote allowlist list/add/remove/set ...`                        | 管理绑定小程序的预览白名单。                                                                                                                         |
+| `hb-sdk remote deploy --release-note <text> [--skip-build] [--auto-publish]` | 构建、上传并提交当前小程序版本审核；`--skip-build` 跳过 build 直接上传 `dist/`。                                                                |
+| `hb-sdk remote versions`                                                 | 列出绑定小程序的远端版本。                                                                                                                           |
+| `hb-sdk remote preview <version>`                                        | 查看指定版本的远端预览入口。                                                                                                                         |
+| `hb-sdk remote release <version> [--yes]`                                | 发布审核通过的版本；非 TTY 环境必须传 `--yes`。                                                                                                     |
+| `hb-sdk remote withdraw <version> [--yes] [--reason <text>]`             | 撤回审核中或已通过但未发布的版本；非 TTY 环境必须传 `--yes`。                                                                                       |
+| `hb-sdk remote take-down [--yes]`                                        | 下架当前线上小程序；非 TTY 环境必须传 `--yes`。                                                                                                     |
+| `hb-sdk remote reopen [--yes]`                                           | 重新上架已下架的小程序；非 TTY 环境必须传 `--yes`。                                                                                                 |
+
+远端平台操作统一放在 `hb-sdk remote` 命令组下；顶层 `hb-sdk deploy` 已硬切删除，不再作为兼容别名保留。`hb-sdk login` 仍是顶层命令，因为它管理 CLI 登录态，不绑定到某个具体小程序。
+
+`hb-sdk remote ...` 支持通用参数 `--json`、`--api-base-url <url>`、`--login-base-url <url>`、`--allow-unsafe-api-base-url` 和 `--verbose`。其中 `--json` 会让 stdout 只输出一个 JSON 对象，进度、警告和诊断信息不应污染 stdout。
 
 所有命令都支持 `--verbose` / `-v`。默认输出只展示关键阶段状态、可访问 URL、下一步命令和可直接处理的错误提示；需要排查后端 envelope、HTTP 状态、trace id、原始响应体、cache 路径、API origin、逐文件上传进度或提交审核原始失败原因时，再追加 `--verbose` 查看详细调试信息。交互式终端会用颜色、符号和 loading 动画区分成功、警告、错误与耗时步骤；CI、非 TTY 和管道输出会退化为 `[hb-sdk] LEVEL ...` 这种稳定文本行。
 
-## hb-sdk deploy
+## hb-sdk remote deploy
 
-`hb-sdk deploy` 把版本预检、build、CDN 上传、提交审核 API 串成单条命令。命令前置要求：
+`hb-sdk remote deploy` 把版本预检、build、CDN 上传、提交审核 API 串成单条命令。顶层 `hb-sdk deploy` 已删除；旧脚本必须改成 `hb-sdk remote deploy`。命令前置要求：
 
 1. `package.json` 必须含 `heybox.miniProgramId` 字段，CLI 只从这里读 mini program id：
    ```json
@@ -255,23 +319,23 @@ try {
    ```
 2. 已运行过 `hb-sdk login` 登录 Heybox。
 3. 如果需要以公司的名义发布小程序，需先找 @秦浩东 申请小程序开发权限。
-4. 每次部署都要准备发布日志：`hb-sdk deploy --release-note "..."`。发布日志 trim 后不能为空，最多 500 个字符，允许换行；CI / 非 TTY 环境缺失时会直接失败，TTY 环境会提示输入。
+4. 每次部署都要准备发布日志：`hb-sdk remote deploy --release-note "..."`。发布日志 trim 后不能为空，最多 500 个字符，允许换行；CI / 非 TTY 环境缺失时会直接失败，TTY 环境会提示输入。
 5. 项目根有 `scripts.build`，会被 CLI 通过 lockfile 自动选用的 `pnpm`、`yarn` 或 `npm` 触发；无 lockfile 时回退 `npm`。
 6. 构建产物落在 `dist/`，包含 `index.html` 和 `manifest.json`。
 
 执行流程：
 
 1. 校验 `heybox.miniProgramId`、发布日志和登录态。
-2. 普通 deploy 读取 `package.json.version`，登录后、build 前调用 `/mall/developer/user_miniprogram/version/precheck`，入参为 `mini_program_id`、`version`、`release_note`、`auto_publish`。
+2. 普通 remote deploy 读取 `package.json.version`，登录后、build 前调用 `/mall/developer/user_miniprogram/version/precheck`，入参为 `mini_program_id`、`version`、`release_note`、`auto_publish`。
 3. 触发 `<pm> run build`，除非使用 `--skip-build`。
-4. 解析 `dist/manifest.json`，校验 `version` 为 `x.y.z`，自动剥离 BOM；普通 deploy 要求该版本与 precheck 使用的 `package.json.version` 一致。
+4. 解析 `dist/manifest.json`，校验 `version` 为 `x.y.z`，自动剥离 BOM；普通 remote deploy 要求该版本与 precheck 使用的 `package.json.version` 一致。
 5. `--skip-build` 会先读取已有 `dist/manifest.json.version`，再调用 precheck。
 6. 遍历 `dist/` 文件，跳过 `manifest.json`、`.DS_Store`、`.map`；遇到 symlink 或 `node_modules` 直接报错。
 7. 校验所有上传路径长度不超过 64。
 8. 4 并发上传到 COS。默认只展示上传阶段和文件总数；`--verbose` 会展示并发数、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie 或 token。任一文件失败立刻 abort，不提交审核。
 9. 全部上传成功后调用 `/mall/developer/user_miniprogram/version/submit_audit`，输出提交审核成功、发布策略和可用的 preview URL；后端原始失败细节只在 `--verbose` 下展示。
 
-默认 `auto_publish=false`，审核通过后需在开放平台手动发布；使用 `--auto-publish` 时提交 `auto_publish=true`，审核通过后自动发布。未发布候选版本可通过开放平台"内测白名单"让指定用户在广场看到；正式入口使用 `mini_program_id`，`mini_url` 仅用于本地调试。
+默认 `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` 缺失会立即报错。
 
@@ -282,20 +346,44 @@ try {
 ```bash
 HB_SDK_API_BASE_URL=https://api.test.xiaoheihe.cn \
 HB_SDK_LOGIN_BASE_URL=https://login.test.xiaoheihe.cn \
-hb-sdk deploy --release-note "测试环境验证"
+hb-sdk remote deploy --release-note "测试环境验证"
 
 hb-sdk login --login-base-url https://login.test.xiaoheihe.cn
-hb-sdk deploy --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "测试环境验证"
-hb-sdk deploy --verbose --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "排查预检失败"
+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 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.0.1:8080 --release-note "本地后台联调"
 ```
 
-`--api-base-url` 优先于 `HB_SDK_API_BASE_URL`，只影响 deploy 里的预检、CDN 上传凭证/回调、提交审核等后台 API；`--login-base-url` 优先于 `HB_SDK_LOGIN_BASE_URL`，用于 `hb-sdk login` 的登录入口，以及 deploy 前校验当前 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()` 不受这些配置影响。
+`--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()` 不受这些配置影响。
+
+## hb-sdk remote 命令参考
+
+`hb-sdk remote` 默认作用于当前项目绑定的小程序，即 `package.json.heybox.miniProgramId`。`remote list` 只用于发现可管理的小程序；会改变远端状态的命令仍然只操作当前绑定的小程序，不接受临时 `mini_program_id` 参数。
+
+| 命令 | 说明 |
+| ---- | ---- |
+| `hb-sdk remote access` | 查询当前 CLI 用户是否具备开发者用户小程序管理资格。 |
+| `hb-sdk remote list [--status <status>] [--keyword <text>]` | 列出当前 CLI 用户可管理的小程序，并标出当前绑定项。 |
+| `hb-sdk remote create --name <name> [--preview-image-url <url>] [--force-bind]` | 创建远端小程序并绑定当前项目；已有绑定时必须显式传 `--force-bind` 才能覆盖。 |
+| `hb-sdk remote bind <mini-program-id> [--force]` | 先校验当前 CLI 用户可管理目标小程序，再写入当前项目绑定；`--force` 只允许覆盖本地绑定，不跳过远端校验。 |
+| `hb-sdk remote info` | 查看当前绑定小程序的远端详情。 |
+| `hb-sdk remote update [--name <name>] [--preview-image-url <url>]` | 更新名称或远程预览图 URL，至少传一个变更字段。 |
+| `hb-sdk remote allowlist list` | 查看预览白名单。 |
+| `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] [--auto-publish]` | 构建、上传并提交当前版本审核。 |
+| `hb-sdk remote versions` | 列出当前绑定小程序的远端版本。 |
+| `hb-sdk remote preview <version>` | 查看指定版本的远端预览入口。 |
+| `hb-sdk remote release <version> [--yes]` | 发布审核通过的版本；交互式终端会确认，非 TTY 必须传 `--yes`。 |
+| `hb-sdk remote withdraw <version> [--yes] [--reason <text>]` | 撤回审核中或已通过但未发布的版本；交互式终端会确认，非 TTY 必须传 `--yes`。 |
+| `hb-sdk remote take-down [--yes]` | 下架当前线上小程序；交互式终端会确认，非 TTY 必须传 `--yes`。 |
+| `hb-sdk remote reopen [--yes]` | 重新上架已下架的小程序；交互式终端会确认，非 TTY 必须传 `--yes`。 |
 
 CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe SDK，也不会改变 `auth.login()`、`user.getInfo()`、`network.request()` 或 mock 宿主中的用户状态。`hb-sdk login status` 默认展示脱敏状态、`heyboxId`、`loginBaseUrl` 和登录时间；`--verbose` 额外展示 cache 路径。不输出 `pkey`、cookie 或完整请求头。
 
-`create`、`dev`、`deploy`、`login`、`login status`、`login clear`、`doctor` 这些 CLI 命令会在成功执行后检查 npm registry 上的 `@heybox/hb-sdk@latest`。如果发现新版本，会在 stderr 打印升级提醒；检查失败会静默跳过，不影响当前命令。`doctor` 已经诊断出 `SDK_MISMATCH` 时不会再追加统一提醒，避免同一次输出里重复提示升级 SDK。`hb-sdk --version` / `hb-sdk -V` 也会执行同一套检查，但 stdout 只输出版本号，升级提醒继续按 warn 级别写到 stderr。可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用版本提醒；`CI=true` 时也会自动跳过检查。
+`create`、`dev`、`remote ...`、`login`、`login status`、`login clear`、`doctor` 这些 CLI 命令会在成功执行后检查 npm registry 上的 `@heybox/hb-sdk@latest`。普通命令的检查结果会缓存 24 小时；如果发现新版本，会在 stderr 打印升级提醒；检查失败会静默跳过，不影响当前命令。`doctor` 已经诊断出 `SDK_MISMATCH` 时不会再追加统一提醒，避免同一次输出里重复提示升级 SDK。`hb-sdk --version` / `hb-sdk -V` 会直接请求 npm registry 获取 latest，不读取本地缓存；stdout 只输出版本号，升级提醒继续按 warn 级别写到 stderr。可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用版本提醒；`CI=true` 时也会自动跳过检查。
 
 ## SDK 与 Runtime
 
@@ -307,7 +395,7 @@ CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe
 
 - 调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
 - `user.getInfo()` 不会触发登录；登录必须由业务在用户操作后调用 `auth.login()`。
-- 分享、截图、storage 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。
+- 分享、截图、UI、设备、导航、storage 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。
 - `network.request()` 的 `validateStatus` 只在 SDK 本地执行，不会被序列化给父容器。
 - `on()` 返回取消监听函数；组件卸载或页面销毁时应主动取消监听。
 - 使用 `createMiniProgramSDK()` 创建独立实例后，不再需要时应调用 `destroy()`。
@@ -341,19 +429,19 @@ export default defineConfig({
 
 - 读取 `package.json` 失败或 JSON 解析失败：`vite build` 直接失败，并输出具体原因。
 - `package.json.version` 不是非空字符串：`vite build` 直接失败。
-- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 输出 warning 并写入 manifest；`hb-sdk deploy` 会拒绝发布，必须改成实际 `x.y.z` 版本。
+- `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。
 
 `manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
 
 ## 导出
 
-默认导出 `hbSDK`，包含 `ready`、`on`、`off`、`auth`、`user`、`share`、`viewport`、`storage`、`network`。
+默认导出 `hbSDK`，包含 `ready`、`on`、`off`、`auth`、`user`、`share`、`viewport`、`storage`、`network`、`ui`、`device`、`navigation`。
 
 常用命名导出：
 
 - `ready`、`on`、`off`
-- `auth`、`user`、`share`、`viewport`、`storage`、`network`
+- `auth`、`user`、`share`、`viewport`、`storage`、`network`、`ui`、`device`、`navigation`
 - `createMiniProgramSDK`、`MiniProgramSDK`
 - `HbMiniProgramSDKError`、`HbMiniProgramNetworkError`
 - 各模块公开类型，例如 `MiniProgramNetworkRequestConfig`、`MiniProgramNetworkResponse`、`MiniProgramUserInfoResult`

package/dist/cli-chunks/{create-BV4h2BTs.cjs → create-DpyZCNdo.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-ovy_xoLn.cjs');
+var index = require('./index-BYMTp2I6.cjs');
 require('node:module');
 require('os');
 require('readline');

package/dist/cli-chunks/{dev-DgX88vaK.cjs → dev-DWIpgJnn.cjs}

@@ -9,7 +9,7 @@ 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-ovy_xoLn.cjs');
+var index = require('./index-BYMTp2I6.cjs');
 require('node:process');
 require('node:buffer');
 require('node:util');

package/dist/cli-chunks/{doctor-BIZoQ6go.cjs → doctor-DBotVUQI.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-ovy_xoLn.cjs');
+var index = require('./index-BYMTp2I6.cjs');
 require('node:module');
 require('path');
 require('os');

package/dist/cli-chunks/{index-ovy_xoLn.cjs → index-BYMTp2I6.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-ovy_xoLn.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-BYMTp2I6.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-ovy_xoLn.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-BYMTp2I6.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-ovy_xoLn.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-BYMTp2I6.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-ovy_xoLn.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-BYMTp2I6.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-ovy_xoLn.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-BYMTp2I6.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -12866,7 +12866,7 @@ async function getUpdateReminder(options = {}) {
     }
     const now = options.now?.() ?? new Date();
     const currentVersion = options.currentVersion ?? (await readCurrentSdkVersion$1(options.packageJsonFiles));
-    const cached = await readFreshUpdateCheckCache(getUpdateCheckCacheFilePath(options), now);
+    const cached = options.forceRefresh ? null : await readFreshUpdateCheckCache(getUpdateCheckCacheFilePath(options), now);
     if (cached) {
         return createUpdateReminder(currentVersion, cached.latestVersion);
     }
@@ -12875,10 +12875,12 @@ async function getUpdateReminder(options = {}) {
         latestVersion = await fetchLatestVersion(options);
     }
     catch {
-        await writeUpdateCheckCache({
-            version: UPDATE_CHECK_CACHE_VERSION,
-            checkedAt: now.toISOString(),
-        }, options).catch(() => undefined);
+        if (!options.forceRefresh) {
+            await writeUpdateCheckCache({
+                version: UPDATE_CHECK_CACHE_VERSION,
+                checkedAt: now.toISOString(),
+            }, options).catch(() => undefined);
+        }
         return null;
     }
     await writeUpdateCheckCache({
@@ -13092,7 +13094,7 @@ function readErrorMessage(error, options = {}) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.4.3';
+const BUILT_CLI_VERSION = '0.4.5';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13151,9 +13153,9 @@ function createCliProgram(overrides = {}) {
         printLoginStatus: defaultPrintLoginStatus,
         printUpdateReminder: printUpdateReminder,
         runCreateCommand: defaultRunCreateCommand,
-        runDeployCommand: defaultRunDeployCommand,
         runDevCommand: defaultRunDevCommand,
         runDoctorCommand: defaultRunDoctorCommand,
+        runRemoteCommand: defaultRunRemoteCommand,
         ...overrides,
     };
     const program = new Command();
@@ -13180,25 +13182,7 @@ function createCliProgram(overrides = {}) {
         const logger = resolveLogger(command);
         await handlers.runDevCommand(options, { logger });
     }, handlers.printUpdateReminder, resolveLogger));
-    addVerboseOption(program
-        .command('deploy')
-        .description('构建并提交当前小程序版本审核')
-        .option('--skip-build', '跳过 build，直接读 dist 目录上传并提交审核')
-        .option('--release-note <text>', '发布日志，提交审核必填')
-        .option('--auto-publish', '审核通过后自动发布；默认需在开放平台手动发布')
-        .option('--api-base-url <url>', 'Heybox 后台 API origin，默认读取 HB_SDK_API_BASE_URL 或生产地址')
-        .option('--allow-unsafe-api-base-url', '允许向非 Heybox HTTPS API origin 发送登录态，仅限本地调试')
-        .option('--login-base-url <url>', '校验 CLI 登录态使用的登录 origin，默认读取 HB_SDK_LOGIN_BASE_URL 或生产地址')).action(withUpdateReminder(async (options, command) => {
-        const logger = resolveLogger(command);
-        await handlers.runDeployCommand({
-            allowUnsafeApiBaseUrl: Boolean(options.allowUnsafeApiBaseUrl),
-            apiBaseUrl: options.apiBaseUrl,
-            autoPublish: Boolean(options.autoPublish),
-            loginBaseUrl: options.loginBaseUrl,
-            releaseNote: options.releaseNote,
-            skipBuild: Boolean(options.skipBuild),
-        }, { logger });
-    }, handlers.printUpdateReminder, resolveLogger));
+    installRemoteCommands(program, handlers, resolveLogger);
     addVerboseOption(program.command('doctor').description('诊断 hb-sdk 本地环境和 Agent Skill 版本')).action(async (...args) => {
         const logger = resolveLogger(readCommandFromActionArgs(args));
         const result = await handlers.runDoctorCommand({ logger });
@@ -13229,6 +13213,141 @@ function createCliProgram(overrides = {}) {
 function addVerboseOption(command) {
     return command.option('-v, --verbose', '输出详细调试信息');
 }
+function addRemotePublicOptions(command) {
+    return addVerboseOption(command
+        .option('--json', '以 JSON 格式输出 remote 命令结果')
+        .option('--api-base-url <url>', 'Heybox 后台 API origin，默认读取 HB_SDK_API_BASE_URL 或生产地址')
+        .option('--login-base-url <url>', '校验 CLI 登录态使用的登录 origin，默认读取 HB_SDK_LOGIN_BASE_URL 或生产地址')
+        .option('--allow-unsafe-api-base-url', '允许向非 Heybox HTTPS API origin 发送登录态，仅限本地调试'));
+}
+function installRemoteCommands(program, handlers, resolveLogger) {
+    const remote = addRemotePublicOptions(program.command('remote').description('管理当前项目绑定的远程 Heybox 用户小程序'));
+    addRemotePublicOptions(remote.command('access').description('查看当前账号的用户小程序访问权限')).action(createRemoteAction(handlers, resolveLogger, 'access'));
+    addRemotePublicOptions(remote
+        .command('list')
+        .description('列出当前账号可管理的用户小程序')
+        .option('--status <status>', '按状态筛选')
+        .option('--keyword <text>', '按关键词筛选')).action(createRemoteAction(handlers, resolveLogger, 'list', (command) => pickOptions(command, ['status', 'keyword'])));
+    addRemotePublicOptions(remote
+        .command('create')
+        .description('创建远程用户小程序并绑定当前项目')
+        .requiredOption('--name <name>', '小程序名称')
+        .option('--preview-image-url <url>', '远程预览图 HTTPS URL')
+        .option('--force-bind', '允许覆盖当前 package.json 中已有绑定')).action(createRemoteAction(handlers, resolveLogger, 'create', (command) => ({
+        ...pickOptions(command, ['name', 'previewImageUrl']),
+        forceBind: Boolean(readCommandOptionsWithAncestors(command).forceBind),
+    })));
+    addRemotePublicOptions(remote.command('bind').description('绑定当前项目到已存在的远程用户小程序').argument('<mini-program-id>', '远程小程序 ID').option('--force', '允许覆盖当前 package.json 中已有绑定')).action(createRemoteAction(handlers, resolveLogger, 'bind', (command, miniProgramId) => ({
+        force: Boolean(readCommandOptionsWithAncestors(command).force),
+        miniProgramId: readStringArgument(miniProgramId, 'mini-program-id'),
+    })));
+    addRemotePublicOptions(remote.command('info').description('查看当前绑定的远程用户小程序详情')).action(createRemoteAction(handlers, resolveLogger, 'info'));
+    addRemotePublicOptions(remote
+        .command('update')
+        .description('更新当前绑定的远程用户小程序基础信息')
+        .option('--name <name>', '小程序名称')
+        .option('--preview-image-url <url>', '远程预览图 HTTPS URL')).action(createRemoteAction(handlers, resolveLogger, 'update', (command) => pickOptions(command, ['name', 'previewImageUrl'])));
+    const allowlist = addRemotePublicOptions(remote.command('allowlist').description('管理当前绑定小程序的预览白名单'));
+    addRemotePublicOptions(allowlist.command('list').description('查看预览白名单')).action(createRemoteAction(handlers, resolveLogger, 'allowlist:list'));
+    addRemotePublicOptions(allowlist.command('add').description('添加预览白名单 Heybox ID').argument('<heybox-id...>', 'Heybox ID')).action(createRemoteAction(handlers, resolveLogger, 'allowlist:add', (_command, heyboxIds) => ({
+        heyboxIds: readStringArrayArgument(heyboxIds, 'heybox-id'),
+    })));
+    addRemotePublicOptions(allowlist.command('remove').description('移除预览白名单 Heybox ID').argument('<heybox-id...>', 'Heybox ID')).action(createRemoteAction(handlers, resolveLogger, 'allowlist:remove', (_command, heyboxIds) => ({
+        heyboxIds: readStringArrayArgument(heyboxIds, 'heybox-id'),
+    })));
+    addRemotePublicOptions(allowlist.command('set').description('替换预览白名单 Heybox ID').argument('<heybox-id...>', 'Heybox ID')).action(createRemoteAction(handlers, resolveLogger, 'allowlist:set', (_command, heyboxIds) => ({
+        heyboxIds: readStringArrayArgument(heyboxIds, 'heybox-id'),
+    })));
+    addRemotePublicOptions(remote
+        .command('deploy')
+        .description('构建并提交当前小程序版本审核')
+        .option('--skip-build', '跳过 build，直接读 dist 目录上传并提交审核')
+        .option('--release-note <text>', '发布日志，提交审核必填')
+        .option('--auto-publish', '审核通过后自动发布；默认需在 CLI 中手动发布')).action(createRemoteAction(handlers, resolveLogger, 'deploy', (command) => {
+        const options = readCommandOptionsWithAncestors(command);
+        return {
+            autoPublish: Boolean(options.autoPublish),
+            releaseNote: readStringOption(options.releaseNote),
+            skipBuild: Boolean(options.skipBuild),
+        };
+    }));
+    addRemotePublicOptions(remote.command('versions').description('列出当前绑定小程序的远程版本')).action(createRemoteAction(handlers, resolveLogger, 'versions'));
+    addRemotePublicOptions(remote.command('preview').description('查看指定版本的预览信息').argument('<version>', '版本号')).action(createRemoteAction(handlers, resolveLogger, 'preview', (_command, version) => ({
+        version: readStringArgument(version, 'version'),
+    })));
+    addRemotePublicOptions(remote.command('release').description('发布指定已审核通过的版本').argument('<version>', '版本号').option('--yes', '跳过危险操作确认')).action(createRemoteAction(handlers, resolveLogger, 'release', (command, version) => ({
+        version: readStringArgument(version, 'version'),
+        ...readYesOption(command),
+    })));
+    addRemotePublicOptions(remote
+        .command('withdraw')
+        .description('撤回指定审核中或已通过的版本')
+        .argument('<version>', '版本号')
+        .option('--yes', '跳过危险操作确认')
+        .option('--reason <text>', '撤回原因')).action(createRemoteAction(handlers, resolveLogger, 'withdraw', (command, version) => ({
+        reason: readStringOption(readCommandOptionsWithAncestors(command).reason),
+        version: readStringArgument(version, 'version'),
+        ...readYesOption(command),
+    })));
+    addRemotePublicOptions(remote.command('take-down').description('下架当前在线小程序').option('--yes', '跳过危险操作确认')).action(createRemoteAction(handlers, resolveLogger, 'take-down', (command) => readYesOption(command)));
+    addRemotePublicOptions(remote.command('reopen').description('重新上架已下架小程序').option('--yes', '跳过危险操作确认')).action(createRemoteAction(handlers, resolveLogger, 'reopen', (command) => readYesOption(command)));
+}
+function createRemoteAction(handlers, resolveLogger, commandName, getCommandOptions = () => ({})) {
+    return withUpdateReminder(async (...args) => {
+        const command = readCommandFromActionArgs(args);
+        if (!command) {
+            throw new Error('无法解析 remote 命令上下文');
+        }
+        const logger = resolveLogger(command);
+        const commandArgs = args.slice(0, -2);
+        await handlers.runRemoteCommand({
+            command: commandName,
+            ...readRemoteCommonOptions(command),
+            ...getCommandOptions(command, ...commandArgs),
+        }, { logger });
+    }, handlers.printUpdateReminder, resolveLogger);
+}
+function readRemoteCommonOptions(command) {
+    const options = readCommandOptionsWithAncestors(command);
+    return {
+        allowUnsafeApiBaseUrl: Boolean(options.allowUnsafeApiBaseUrl),
+        apiBaseUrl: readStringOption(options.apiBaseUrl),
+        json: Boolean(options.json),
+        loginBaseUrl: readStringOption(options.loginBaseUrl),
+        verbose: Boolean(options.verbose),
+    };
+}
+function readYesOption(command) {
+    return {
+        yes: Boolean(readCommandOptionsWithAncestors(command).yes),
+    };
+}
+function pickOptions(command, keys) {
+    const options = readCommandOptionsWithAncestors(command);
+    const picked = {};
+    for (const key of keys) {
+        const value = readStringOption(options[key]);
+        if (value !== undefined) {
+            picked[key] = value;
+        }
+    }
+    return picked;
+}
+function readStringOption(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function readStringArgument(value, name) {
+    if (typeof value !== 'string') {
+        throw new Error(`无法解析 ${name} 参数`);
+    }
+    return value;
+}
+function readStringArrayArgument(value, name) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+        throw new Error(`无法解析 ${name} 参数`);
+    }
+    return value;
+}
 function hasVerboseArg(argv) {
     return argv.includes('--verbose') || argv.includes('-v');
 }
@@ -13249,33 +13368,33 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-CoZhlwxt.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-DIgcT1gv.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-CoZhlwxt.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-DIgcT1gv.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-CoZhlwxt.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-DIgcT1gv.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-BV4h2BTs.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-DpyZCNdo.cjs'); });
     return runCreateCommand(...args);
 };
-const defaultRunDeployCommand = async (...args) => {
-    const { runDeployCommand } = await Promise.resolve().then(function () { return require('./deploy-Bz0-WpHy.cjs'); }).then(function (n) { return n.deploy; });
-    return runDeployCommand(...args);
-};
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DgX88vaK.cjs'); });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DWIpgJnn.cjs'); });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-BIZoQ6go.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-DBotVUQI.cjs'); });
     return runDoctorCommand(...args);
 };
+const defaultRunRemoteCommand = async (...args) => {
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-DjaOc1VS.cjs'); }).then(function (n) { return n.remote; });
+    return runRemoteCommand(...args);
+};
 function resolveStandaloneLogger(options, verbose) {
     return options.logger ?? options.createLogger?.({ verbose }) ?? createCliLogger({ verbose });
 }
@@ -13283,7 +13402,16 @@ function readCommandVerbose(command) {
     if (!command) {
         return false;
     }
-    return Boolean(command.optsWithGlobals?.().verbose || command.opts().verbose);
+    return Boolean(readCommandOptionsWithAncestors(command).verbose);
+}
+function readCommandOptionsWithAncestors(command) {
+    const chain = [];
+    let current = command;
+    while (current) {
+        chain.push(current);
+        current = current.parent;
+    }
+    return Object.assign({}, ...chain.reverse().map((item) => item.opts()));
 }
 function installVersionUpdateReminder(program, printUpdateReminder, resolveLogger) {
     const parseAsync = program.parseAsync.bind(program);
@@ -13292,7 +13420,7 @@ function installVersionUpdateReminder(program, printUpdateReminder, resolveLogge
         if (isVersionRequest(argv, parseOptions)) {
             const logger = resolveLogger(hasVerboseArg(getUserArgs(argv, parseOptions)));
             logger.raw(getCliVersion(), { stream: 'stdout' });
-            await printUpdateReminder({ logger });
+            await printUpdateReminder({ forceRefresh: true, logger });
             throw new CommanderError(0, 'commander.version', 'version displayed');
         }
         return parseAsync(...args);

package/dist/cli-chunks/{index-DQAFCtK1.cjs → index-DRsyeAcg.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-ovy_xoLn.cjs');
+var index$2 = require('./index-BYMTp2I6.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 deploy = require('./deploy-Bz0-WpHy.cjs');
+var remote = require('./remote-DjaOc1VS.cjs');
 var require$$0$5 = require('net');
 var require$$0$4 = require('url');
 var require$$2$2 = require('http');
@@ -13707,7 +13707,7 @@ function requireSource () {
 		const ajv_1 = requireAjv$1();
 		const ajv_formats_1 = requireDist();
 		const debounceFn = requireDebounceFn();
-		const semver = deploy.requireSemver();
+		const semver = remote.requireSemver();
 		const onetime = index$2.requireOnetime();
 		const encryptionAlgorithm = 'aes-256-cbc';
 		const createPlainObject = () => {

package/dist/cli-chunks/{login-CoZhlwxt.cjs → login-DIgcT1gv.cjs}

@@ -2,9 +2,9 @@
 
 var node_crypto = require('node:crypto');
 var node_http = require('node:http');
-var session = require('./session-BQs0wf65.cjs');
+var session = require('./session-BAgaqpNL.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-ovy_xoLn.cjs');
+var index = require('./index-BYMTp2I6.cjs');
 require('node:path');
 require('fs');
 require('constants');