@heybox/hb-sdk 0.3.3 → 0.4.0

package/README.md

@@ -13,7 +13,7 @@ npm install
 npm run dev
 ```
 
-模板默认使用 Vue 3、Vite、TypeScript 和 npm。`npm run dev` 会启动小程序页面服务，并打开 `hb-sdk` 内置的浏览器 mock 宿主环境，适合在普通浏览器里调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。Codex、VSCode 等内嵌浏览器可能无法转交 `heybox://` 协议；需要从调试页唤起 Mac 版 APP 时，请先在系统浏览器中打开调试页。
+模板默认使用 Vue 3、Vite、TypeScript 和 npm。`npm run dev` 会启动小程序页面服务，并打开 `hb-sdk` 内置的浏览器 mock 宿主环境，适合在普通浏览器里调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面，也可以选择局域网网卡后用手机小黑盒 APP 扫码调试。手机需要与电脑处在同一局域网，并使用支持小程序调试壳的新版小黑盒 APP。Codex、VSCode 等内嵌浏览器可能无法转交 `heybox://` 协议；需要从调试页唤起 Mac 版 APP 时，请先在系统浏览器中打开调试页。
 
 在已有项目中安装：
 
@@ -57,7 +57,7 @@ SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注
 npm run dev
 ```
 
-调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；如果需要真实黑盒小程序容器加载同一页面，可以点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
 
@@ -120,6 +120,18 @@ const windowInfo = await viewport.getWindowInfo();
 console.log(windowInfo.windowWidth, windowInfo.windowHeight, windowInfo.safeArea.top);
 ```
 
+### 导航栏样式
+
+```ts
+import { viewport } from '@heybox/hb-sdk';
+
+await viewport.setNavigationBarStyle({
+  foregroundStyle: 'light',
+});
+```
+
+`foregroundStyle` 设置导航栏关闭按钮与状态栏图标/文字的明暗样式：`light` 表示白色前景，适合深色背景；`dark` 表示黑色前景，适合浅色背景。该能力不设置导航栏背景色，也不支持关闭按钮与状态栏分别配置。
+
 ### 隔离 Storage
 
 ```ts
@@ -168,7 +180,7 @@ try {
 ```ts
 await network.request({
   url: 'https://api.example.com/demo',
-  validateStatus: status => status < 500,
+  validateStatus: (status) => status < 500,
 });
 ```
 
@@ -181,11 +193,11 @@ await network.request({
 ```ts
 import { on } from '@heybox/hb-sdk';
 
-const unsubscribeShow = on('show', payload => {
+const unsubscribeShow = on('show', (payload) => {
   console.log('页面展示', payload.timestamp, payload.source);
 });
 
-const unsubscribeAuth = on('authChange', payload => {
+const unsubscribeAuth = on('authChange', (payload) => {
   console.log('登录态变化', payload.isLogin, payload.userInfo);
 });
 
@@ -217,19 +229,21 @@ try {
 
 `@heybox/hb-sdk` 随包提供 `hb-sdk` CLI。脚手架项目已在 npm scripts 中接好常用命令；已有项目也可以自行添加 scripts。
 
-| 命令 | 作用 |
-| --- | --- |
-| `hb-sdk create <project-name>` | 创建外部小程序模板。 |
-| `hb-sdk dev` | 启动当前项目的 Vite dev server 和浏览器 mock 宿主环境，并默认打开调试页。 |
-| `hb-sdk deploy [--skip-build]` | 构建并发布当前小程序到 Heybox 后台。`--skip-build` 跳过 build 直接上传 `dist/` 并 publish。 |
-| `hb-sdk login` | 登录 Heybox，并把 CLI 自己需要的登录态保存在本地缓存中。 |
-| `hb-sdk login status` | 查看脱敏后的 CLI 登录态。 |
-| `hb-sdk login clear` | 清理 CLI 登录态。 |
-| `hb-sdk doctor` | 检查本机 `hb-sdk` Agent Skill 是否匹配当前 SDK，并输出手动安装/刷新命令。 |
+| 命令                                                                     | 作用                                                                                                                                                 |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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，并输出手动安装/刷新命令。                                                                            |
+
+所有命令都支持 `--verbose` / `-v`。默认输出只展示关键阶段状态、可访问 URL、下一步命令和可直接处理的错误提示；需要排查后端 envelope、HTTP 状态、trace id、原始响应体、cache 路径、API origin、逐文件上传进度或提交审核原始失败原因时，再追加 `--verbose` 查看详细调试信息。交互式终端会用颜色、符号和 loading 动画区分成功、警告、错误与耗时步骤；CI、非 TTY 和管道输出会退化为 `[hb-sdk] LEVEL ...` 这种稳定文本行。
 
 ## hb-sdk deploy
 
-`hb-sdk deploy` 把 build、CDN 上传、发布 API 串成单条命令。命令前置要求：
+`hb-sdk deploy` 把版本预检、build、CDN 上传、提交审核 API 串成单条命令。命令前置要求：
 
 1. `package.json` 必须含 `heybox.miniProgramId` 字段，CLI 只从这里读 mini program id：
    ```json
@@ -241,26 +255,47 @@ try {
    ```
 2. 已运行过 `hb-sdk login` 登录 Heybox。
 3. 如果需要以公司的名义发布小程序，需先找 @秦浩东 申请小程序开发权限。
-4. 项目根有 `scripts.build`，会被 CLI 通过 lockfile 自动选用的 `pnpm`、`yarn` 或 `npm` 触发；无 lockfile 时回退 `npm`。
-5. 构建产物落在 `dist/`，包含 `index.html` 和 `manifest.json`。
+4. 每次部署都要准备发布日志：`hb-sdk 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. 触发 `<pm> run build`，除非使用 `--skip-build`。
-3. 解析 `dist/manifest.json`，校验 `version` 为 `x.y.z`，自动剥离 BOM。
-4. 遍历 `dist/` 文件，跳过 `manifest.json`、`.DS_Store`、`.map`；遇到 symlink 或 `node_modules` 直接报错。
-5. 校验所有上传路径长度不超过 64。
-6. 4 并发上传到 COS。任一文件失败立刻 abort，不调 publish。
-7. 全部上传成功后调发布 API，原样透传后端 msg。
+1. 校验 `heybox.miniProgramId`、发布日志和登录态。
+2. 普通 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` 一致。
+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` 下展示。
 
-`--skip-build` 用于 CI 双阶段：上一步已经 build 完缓存好了 `dist/`，本步只做上传和 publish。`dist/manifest.json` 或 `dist/index.html` 缺失会立即报错。
+默认 `auto_publish=false`，审核通过后需在开放平台手动发布；使用 `--auto-publish` 时提交 `auto_publish=true`，审核通过后自动发布。未发布候选版本可通过开放平台"内测白名单"让指定用户在广场看到；正式入口使用 `mini_program_id`，`mini_url` 仅用于本地调试。
+
+`--skip-build` 用于 CI 双阶段：上一步已经 build 完缓存好了 `dist/`，本步只做预检、上传和提交审核。`dist/manifest.json` 或 `dist/index.html` 缺失会立即报错。
+
+`manifest.json` 不会上传到 CDN，只作为 submit audit 请求的 `manifest` 字段提交。这与 Vite 插件文档中的契约一致。
+
+内部测试或预发环境可通过 origin 级别的自定义地址切换后台环境：
+
+```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 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_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk deploy --api-base-url http://127.0.0.1:8080 --release-note "本地后台联调"
+```
 
-`manifest.json` 不会上传到 CDN，只作为 publish 请求的 `manifest` 字段提交。这与 Vite 插件文档中的契约一致。
+`--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()` 不受这些配置影响。
 
-CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe SDK，也不会改变 `auth.login()`、`user.getInfo()`、`network.request()` 或 mock 宿主中的用户状态。
+CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe SDK，也不会改变 `auth.login()`、`user.getInfo()`、`network.request()` 或 mock 宿主中的用户状态。`hb-sdk login status` 默认展示脱敏状态、`heyboxId`、`loginBaseUrl` 和登录时间；`--verbose` 额外展示 cache 路径。不输出 `pkey`、cookie 或完整请求头。
 
-`create`、`dev`、`login`、`login status`、`login clear` 这些 CLI 命令会在成功执行后检查 npm registry 上的 `@heybox/hb-sdk@latest`。如果发现新版本，会在 stderr 打印升级提醒；检查失败会静默跳过，不影响当前命令。`doctor` 不会附带版本提醒，避免把 skill 诊断输出和升级提示混在一起。可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用版本提醒；`CI=true` 时也会自动跳过检查。
+`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` 时也会自动跳过检查。
 
 ## SDK 与 Runtime