@heybox/hb-sdk 0.3.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "",
   "exports": {
     ".": {
@@ -63,6 +63,8 @@
     "@types/ejs": "^3.1.5",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "24.10.1",
+    "@types/qrcode": "^1.5.6",
+    "@types/semver": "^7.7.1",
     "@vitest/coverage-v8": "^3.2.4",
     "commander": "^12.1.0",
     "cos-nodejs-sdk-v5": "2.15.4",
@@ -72,9 +74,12 @@
     "get-port": "^7.1.0",
     "happy-dom": "^19.0.2",
     "open": "^10.2.0",
+    "ora": "^5.4.1",
     "picocolors": "^1.1.1",
+    "qrcode": "^1.5.4",
     "rimraf": "^5.0.5",
     "rollup": "^4.52.4",
+    "semver": "^7.8.0",
     "typescript": "^5.9.3",
     "vue": "^2.7.16",
     "vite": "^8.0.12",

package/skill/SKILL.md

@@ -48,18 +48,24 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 
 1. Use `hb-sdk create <project-name>` to scaffold a standalone external mini-program template.
 2. Use `hb-sdk dev` for local browser debugging through the built-in mock runtime host.
-3. Use `hb-sdk deploy` to build and publish the current project. It reads `package.json.heybox.miniProgramId`, runs the project's `build` script via the package manager auto-detected by lockfile, then uploads `dist/` to CDN (skipping `manifest.json`, `.DS_Store`, `.map`) and calls the publish API.
-4. Use `hb-sdk deploy --skip-build` only when the `dist/` directory is already prepared by an upstream CI stage. Missing `dist/manifest.json` or `dist/index.html` aborts the run.
-5. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container; if the mock host is open inside Codex, VSCode, or another embedded browser, ask the user to open the same debug page in the system browser before retrying because embedded browsers may block the `heybox://` protocol handoff.
-6. Use `--port`, `--mock-port`, `--host`, and `--no-open` when the default Vite/mock ports, host, or browser opening behavior need to be controlled.
-7. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache.
-8. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
-9. Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
-10. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
-11. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
-12. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
-13. Do not pass `mini_program_id` as a CLI flag or environment variable; it must come from `package.json.heybox.miniProgramId`.
-14. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publishing is `@heybox/hb-sdk/miniapp-publish`.
+3. Use `hb-sdk deploy --release-note <text>` to build, upload, and submit the current project for audit. It reads `package.json.heybox.miniProgramId`, prechecks `package.json.version` before build, runs the project's `build` script via the package manager auto-detected by lockfile, uploads `dist/` to CDN (skipping `manifest.json`, `.DS_Store`, `.map`), then calls the submit-audit API.
+4. Use `hb-sdk deploy --skip-build --release-note <text>` only when the `dist/` directory is already prepared by an upstream CI stage. In this mode the CLI reads `dist/manifest.json.version` before precheck. Missing `dist/manifest.json` or `dist/index.html` aborts the run.
+5. Always provide a concise release note before deploy. Non-interactive environments must pass `--release-note`; interactive terminals may prompt for it. The default is manual release after approval; use `--auto-publish` when the audited version should automatically release after approval.
+6. For internal test/staging backend operations, use origin-only custom URLs: `HB_SDK_API_BASE_URL` or `hb-sdk deploy --api-base-url <url>` for deploy APIs, and `HB_SDK_LOGIN_BASE_URL` or `hb-sdk login --login-base-url <url>` for browser login. CLI flags override env vars. API base URLs must be Heybox trusted HTTPS origins by default; use `--allow-unsafe-api-base-url` or `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` only for local backend debugging. Do not include path, query, or hash in these URLs.
+7. For development routing or gray validation, configure `packages/hb-sdk/src/cli/config.ts` with `@heybox/hb-types` `RylaiServiceTagConfig` (`default_tag` / path-specific `special_tag`) to attach `x-rylai-service-tag` and the matching `special_tag` query parameter to Heybox backend API requests.
+8. If deploy targets a custom login environment, pass the same `--login-base-url` or `HB_SDK_LOGIN_BASE_URL` used for `hb-sdk login`; deploy rejects cached CLI login state from a different login origin.
+9. Add `--verbose` / `-v` only when diagnosing failures; default CLI errors are intentionally concise, while verbose output includes backend envelope, HTTP status, trace fields, raw body, or original submit-audit failure details.
+10. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
+11. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; the phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
+12. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
+13. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache.
+14. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
+15. Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
+16. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+17. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
+18. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
+19. Do not pass `mini_program_id` as a CLI flag or environment variable; it must come from `package.json.heybox.miniProgramId`.
+20. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publish-pipeline helpers is `@heybox/hb-sdk/miniapp-publish`.
 
 ## Step 6: Preserve capability boundaries
 
@@ -101,6 +107,6 @@ For host/runtime/protocol-maintenance code:
    - `pnpm --filter @heybox/hb-sdk run check:boundary`
    - `pnpm --filter @heybox/hb-sdk run test:unit`
    - Verify `dist/cli.cjs` does not have any `require('cos-nodejs-sdk-v5')` left after `build:cli`; the boundary check enforces this automatically.
-6. Verify public payload sync before publishing:
+7. Verify public payload sync before publishing:
    - `pnpm --filter @heybox-spa/open run sync:agent-skills`
    - `pnpm --filter @heybox-spa/open run check:agent-skills`

package/skill/references/api-protocol.md

@@ -46,6 +46,7 @@ export {
   STORAGE_SET_STORAGE_METHOD,
   USER_GET_INFO_METHOD,
   VIEWPORT_GET_WINDOW_INFO_METHOD,
+  VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD,
 } from './protocol/capabilities';
 export type {
   MiniProgramAuthMethod,
@@ -86,8 +87,12 @@ export type {
 export type {
   GetWindowInfoPayload,
   GetWindowInfoResult,
+  MiniProgramNavigationBarForegroundStyle,
   MiniProgramSafeArea,
+  MiniProgramSetNavigationBarStyleOptions,
   MiniProgramWindowInfoResult,
+  SetNavigationBarStylePayload,
+  SetNavigationBarStyleResult,
 } from './modules/viewport';
 export type {
   MiniProgramNetworkHeaders,
@@ -131,5 +136,5 @@ Reference 由 `packages/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 3 | 4 | 22 | 17 | 0 |
-| Protocol API | 0 | 1 | 20 | 29 | 13 |
+| Root API | 3 | 4 | 23 | 20 | 0 |
+| Protocol API | 0 | 1 | 21 | 32 | 14 |

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.3.3`
+- Version at generation time: `0.4.0`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -58,9 +58,13 @@ export type {
 export type {
   GetWindowInfoPayload,
   GetWindowInfoResult,
+  MiniProgramNavigationBarForegroundStyle,
   MiniProgramSafeArea,
+  MiniProgramSetNavigationBarStyleOptions,
   MiniProgramViewportModule,
   MiniProgramWindowInfoResult,
+  SetNavigationBarStylePayload,
+  SetNavigationBarStyleResult,
 } from './modules/viewport';
 export type {
   GetStoragePayload,
@@ -105,8 +109,8 @@ Use `@heybox/hb-sdk/vite` only in `vite.config.ts`. Do not import it from iframe
 import { mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import {
-  getMiniappManifestBuildWarning,
   renderMiniappManifest,
+  validateMiniappPackageVersionForBuild,
 } from '../miniapp-manifest/schema';
 import { readMiniappVersionFromPackageJson } from '../miniapp-manifest/node';
 
@@ -140,12 +144,7 @@ export function miniappManifest(): MiniappManifestPlugin {
       outDir = resolved.build.outDir;
     },
     writeBundle() {
-      const version = readMiniappVersionFromPackageJson(root);
-      const warning = getMiniappManifestBuildWarning(version);
-
-      if (warning) {
-        this.warn(warning);
-      }
+      const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
 
       const manifestPath = path.resolve(root, outDir, 'manifest.json');
       mkdirSync(path.dirname(manifestPath), { recursive: true });
@@ -198,7 +197,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 时，请先在系统浏览器中打开调试页。
 
 在已有项目中安装：
 
@@ -242,7 +241,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`：
 
@@ -325,6 +324,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
@@ -373,7 +384,7 @@ try {
 ```ts
 await network.request({
   url: 'https://api.example.com/demo',
-  validateStatus: status => status < 500,
+  validateStatus: (status) => status < 500,
 });
 ```
 
@@ -386,11 +397,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);
 });