@heybox/hb-sdk 0.5.16 → 0.5.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +24 -5
- package/dist/cli-chunks/{remote-CdEyGDRq.cjs → context-CKJlNcSN.cjs} +52 -1583
- package/dist/cli-chunks/{create-DUwSoYT4.cjs → create-OZOIdeBz.cjs} +1 -1
- package/dist/cli-chunks/{dev-78XBGRX3.cjs → dev-DXz8izSJ.cjs} +126 -31
- package/dist/cli-chunks/{doctor-CHrjGIQ1.cjs → doctor-DjMSJoQ5.cjs} +1 -1
- package/dist/cli-chunks/{index-B7Ys8ljY.cjs → index-Cl5HFTBW.cjs} +3 -3
- package/dist/cli-chunks/{index-B-lA2GE7.cjs → index-CsOcGUzF.cjs} +265 -16
- package/dist/cli-chunks/{login-CP6xdTYa.cjs → login-Ct-46gLx.cjs} +2 -2
- package/dist/cli-chunks/remote-C77axNSw.cjs +1604 -0
- package/dist/cli-chunks/{session-Cfl5cGf8.cjs → session-dRGPpyS1.cjs} +14 -57
- package/dist/cli.cjs +1 -1
- package/dist/devtools/mock-host/main.js +145 -46
- package/package.json +1 -1
- package/skill/SKILL.md +1 -1
- package/skill/references/api-root.md +4 -2
- package/skill/references/cli.md +21 -4
- package/skill/skill.json +4 -4
package/README.md
CHANGED
|
@@ -57,7 +57,7 @@ SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注
|
|
|
57
57
|
npm run dev
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
-
调试页会通过 iframe 加载本地页面并补齐小程序 bridge
|
|
60
|
+
调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；浏览器 Mock 从 mock host 的同源只读 bootstrap 接口读取服务端保留的 Runtime 权限快照，URL query 不能提供或覆盖权限。项目已绑定 `heybox.miniProgramId` 时，可以点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码；真机 dev shell 只携带绑定的小程序 ID 和本地页面地址，H5 宿主按 ID 从公开详情接口读取可信 Runtime 权限快照。项目未绑定时仍可使用默认拒绝受管能力的浏览器 Mock，但 Mac 和手机真机入口会明确提示先运行 `hb-sdk remote create` 或 `hb-sdk remote bind <mini-program-id>`，并保持不可用。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
|
|
61
61
|
|
|
62
62
|
在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
|
|
63
63
|
|
|
@@ -328,6 +328,8 @@ await network.request({
|
|
|
328
328
|
|
|
329
329
|
支持的 HTTP method 为 `GET`、`POST`、`PUT`、`PATCH`、`DELETE`、`HEAD`、`OPTIONS`。
|
|
330
330
|
|
|
331
|
+
`network.request` 由平台 Runtime 权限控制。未授权时 SDK 会收到 `PERMISSION_DENIED` 和“当前小程序暂不支持网络请求”；即使已开启网络请求，访问黑盒官方域名仍需要运营侧单独开启官方域名配置。业务代码不能自行请求或注入 Cookie、pkey 等官方凭据。
|
|
332
|
+
|
|
331
333
|
## 生命周期事件
|
|
332
334
|
|
|
333
335
|
SDK 实例创建后会自动开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时，默认单例会被懒创建并自动开始握手；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
|
|
@@ -374,7 +376,7 @@ try {
|
|
|
374
376
|
| 命令 | 作用 |
|
|
375
377
|
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
376
378
|
| `hb-sdk create <project-name>` | 创建外部小程序模板。 |
|
|
377
|
-
| `hb-sdk dev [--runtime-url <url>]` |
|
|
379
|
+
| `hb-sdk dev [--runtime-url <url>]` | 启动 Vite 和浏览器 mock 宿主；远端权限可用时使用真实快照，否则以缺失快照启动并默认拒绝受管能力。 |
|
|
378
380
|
| `hb-sdk login [--login-base-url <url>] [--no-select-entity]` | 登录 Heybox，并把 CLI 自己需要的登录态和登录入口环境保存在本地缓存中；默认会引导多主体用户选择服务端 current entity。 |
|
|
379
381
|
| `hb-sdk login status` | 查看脱敏后的 CLI 登录态。 |
|
|
380
382
|
| `hb-sdk login clear` | 清理 CLI 登录态。 |
|
|
@@ -386,7 +388,7 @@ try {
|
|
|
386
388
|
| `hb-sdk remote list [--status <status>] [--keyword <text>]` | 列出当前 CLI 用户可管理的远端工坊小程序，用于发现并绑定当前项目。 |
|
|
387
389
|
| `hb-sdk remote create [--yes] [--force-bind]` | 在服务端 current entity 下创建远端工坊小程序并写入当前项目的 `package.json.heybox.miniProgramId`。 |
|
|
388
390
|
| `hb-sdk remote bind <mini-program-id> [--force]` | 校验当前 CLI 用户可管理目标小程序后，再把它绑定到当前项目。 |
|
|
389
|
-
| `hb-sdk remote info` |
|
|
391
|
+
| `hb-sdk remote info` | 查看当前项目绑定的小程序详情及完整只读 Runtime 权限/config。 |
|
|
390
392
|
| `hb-sdk remote allowlist list/add/remove/set ...` | 管理绑定小程序的预览白名单。 |
|
|
391
393
|
| `hb-sdk remote deploy --release-note <text> [--skip-build \| --from-version <version>] [--auto-publish]` | 构建、上传并提交当前小程序版本审核；`--skip-build` 跳过 build 直接上传 `dist/`，`--from-version` 复用指定历史版本产物。 |
|
|
392
394
|
| `hb-sdk remote versions` | 列出绑定小程序的远端版本。 |
|
|
@@ -471,10 +473,27 @@ hb-sdk login --login-base-url https://login.test.xiaoheihe.cn
|
|
|
471
473
|
hb-sdk remote deploy --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "测试环境验证"
|
|
472
474
|
hb-sdk remote deploy --verbose --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "排查预检失败"
|
|
473
475
|
|
|
474
|
-
HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://127.0.
|
|
476
|
+
HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://127.0.1:8080 --release-note "本地后台联调"
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
切换测试环境时往往需要同时配置后台 host、登录 host 和 service tag。为避免每条命令都重复书写这些 env/flag，CLI 支持加载 `.env.<name>` 预设：
|
|
480
|
+
|
|
481
|
+
```bash
|
|
482
|
+
# 在项目根准备 .env.test（可提交当团队默认，或 gitignore 仅本地保留）
|
|
483
|
+
# HB_SDK_API_BASE_URL=https://api.test.xiaoheihe.cn
|
|
484
|
+
# HB_SDK_LOGIN_BASE_URL=https://login.test.xiaoheihe.cn
|
|
485
|
+
# HB_SDK_SERVICE_TAG=my-test-tag
|
|
486
|
+
|
|
487
|
+
hb-sdk remote deploy --env test --release-note "测试环境验证" # 一次加载三项配置
|
|
488
|
+
hb-sdk remote info --env test # 复用同一预设
|
|
489
|
+
HB_SDK_ENV=test hb-sdk remote versions # 环境变量形式，CI 友好
|
|
490
|
+
hb-sdk remote deploy --env-file .env.local --release-note "本地联调" # 显式指定文件路径
|
|
491
|
+
hb-sdk remote deploy --env test --service-tag other-tag --release-note "灰度" # 单项 flag 覆盖预设
|
|
475
492
|
```
|
|
476
493
|
|
|
477
|
-
`--
|
|
494
|
+
`--env <name>` 会读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级高于 `--env`；两者也可通过 `HB_SDK_ENV=<name>` 触发。加载遵循 dotenv 惯例：不覆盖进程已有的同名变量，因此 CI 或命令行显式设置的值优先。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。`--verbose` 会打印生效的文件路径和被跳过的 key。
|
|
495
|
+
|
|
496
|
+
`--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()` 不受这些配置影响。
|
|
478
497
|
|
|
479
498
|
## hb-sdk remote 命令参考
|
|
480
499
|
|