@heybox/hb-sdk 0.4.5 → 0.4.7

package/skill/SKILL.md

@@ -49,28 +49,30 @@ 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 remote ...` for developer-owned remote mini-program management. Top-level `hb-sdk deploy` has been hard-cut and must not be recommended as a compatibility alias.
-4. Use `hb-sdk remote create --name <name>` to create a remote mini-program and bind the returned id into `package.json.heybox.miniProgramId`; use `hb-sdk remote bind <mini-program-id>` to bind an existing remote mini-program after manageability is verified.
-5. Use `hb-sdk remote info`, `hb-sdk remote update`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for read/basic/preview management workflows. Discovery commands may show multiple remote mini-programs, but write commands target the current project binding rather than arbitrary ids.
-6. Use `hb-sdk remote 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.
-7. Use `hb-sdk remote 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.
-8. 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 with `hb-sdk remote release <version>`; use `--auto-publish` when the audited version should automatically release after approval.
-9. Use `hb-sdk remote release <version>`, `hb-sdk remote withdraw <version>`, `hb-sdk remote take-down`, and `hb-sdk remote reopen` for dangerous remote changes. Interactive terminals should confirm after showing enough context; non-interactive environments must pass `--yes`.
-10. For internal test/staging backend operations, use origin-only custom URLs: `HB_SDK_API_BASE_URL` or `hb-sdk remote ... --api-base-url <url>` for remote platform 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.
-11. 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.
-12. If a remote command targets a custom login environment, pass the same `--login-base-url` or `HB_SDK_LOGIN_BASE_URL` used for `hb-sdk login`; remote commands reject cached CLI login state from a different login origin.
-13. 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.
-14. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
-15. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
-16. 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.
-17. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
-18. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
-19. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
-20. 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`.
-21. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
-22. 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.
-23. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
-24. Do not pass `mini_program_id` as a CLI flag or environment variable; it must come from `package.json.heybox.miniProgramId`.
-25. 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`.
+4. Use `hb-sdk remote entity list`, `hb-sdk remote entity current`, and `hb-sdk remote entity switch <entity-id>` to inspect or change the developer platform server-side current entity before remote management commands.
+5. Use `hb-sdk remote create --name <name>` to create a remote mini-program under the server-side current entity and bind the returned id into `package.json.heybox.miniProgramId`; use `hb-sdk remote bind <mini-program-id>` to bind an existing remote mini-program after current-entity manageability is verified.
+6. Use `hb-sdk remote info`, `hb-sdk remote update`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for read/basic/preview management workflows. Discovery commands show the server-side current entity scope; write commands target the current project binding rather than arbitrary ids.
+7. Use `hb-sdk remote deploy --release-note <text>` to build, upload, and submit the current project for audit. It reads `package.json.heybox.miniProgramId`, validates that the bound mini-program belongs to the server-side current entity before precheck/build/upload, 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. The deploy upload pipeline rejects actual upload artifacts over 100MiB before any upload request, processes CDN upload metadata and callback confirmation at 50 files per batch, keeps 4-way upload concurrency within each batch, and validates CDN-returned keys exactly against the local expected upload keys.
+8. Use `hb-sdk remote 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.
+9. 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 with `hb-sdk remote release <version>`; use `--auto-publish` when the audited version should automatically release after approval.
+10. Use `hb-sdk remote release <version>`, `hb-sdk remote withdraw <version>`, `hb-sdk remote take-down`, and `hb-sdk remote reopen` for dangerous remote changes. Interactive terminals should confirm after showing enough context; non-interactive environments must pass `--yes`.
+11. For internal test/staging backend operations, use origin-only custom URLs: `HB_SDK_API_BASE_URL` or `hb-sdk remote ... --api-base-url <url>` for remote platform 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.
+12. 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.
+13. If a remote command targets a custom login environment, pass the same `--login-base-url` or `HB_SDK_LOGIN_BASE_URL` used for `hb-sdk login`; remote commands reject cached CLI login state from a different login origin.
+14. 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.
+15. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
+16. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
+17. 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.
+18. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
+19. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
+20. Treat `selectedEntity` in the CLI auth cache as a non-authoritative hint snapshot only. Every remote command must use the server-side current entity as the source of truth.
+21. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
+22. 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`.
+23. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+24. 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.
+25. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
+26. Do not pass `mini_program_id` or `entity_id` as general CLI flags or environment variables; the mini-program id must come from `package.json.heybox.miniProgramId`, and the entity must come from the server-side current entity.
+27. 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
 

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.4.5`
+- Version at generation time: `0.4.7`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -341,11 +341,14 @@ import { share } from '@heybox/hb-sdk';
 await share.showShareMenu({
   title: '我的小程序页面',
   desc: '来自黑盒小程序的分享',
-  url: window.location.href,
   imageUrl: 'https://imgheybox.max-c.com/demo.png',
 });
 ```
 
+用户小程序通常不要传 `url`；宿主 runtime 会按当前小程序生成
+`/tools/common_share?user_miniprogram_id=...` 分享落地页。只有确实要分享外部
+HTTP(S) 页面时才显式传 `url`。
+
 截图分享：
 
 ```ts

package/skill/references/cli.md

@@ -20,6 +20,7 @@
 - [Create a mini-program template](#create-a-mini-program-template)
 - [Local dev and mock runtime](#local-dev-and-mock-runtime)
 - [Deploy and backend operations](#deploy-and-backend-operations)
+- [Remote entity scope](#remote-entity-scope)
 - [Remote management commands](#remote-management-commands)
 - [CLI login cache](#cli-login-cache)
 - [Agent Skill doctor](#agent-skill-doctor)
@@ -28,7 +29,7 @@
 - [Generated template README](#generated-template-readme)
 ## When to use the CLI
 
-Use the bundled `hb-sdk` CLI when the task is about creating an external mini-program project, starting local Vite development, debugging SDK calls in a browser mock runtime host, or managing the CLI's own Heybox auth cache.
+Use the bundled `hb-sdk` CLI when the task is about creating an external mini-program project, starting local Vite development, debugging SDK calls in a browser mock runtime host, managing the CLI's own Heybox auth cache, or inspecting/switching the developer platform current entity for remote mini-program management.
 
 Do not use the CLI to replace iframe SDK calls. `hb-sdk login` is for CLI commands only and does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-host user state.
 
@@ -39,13 +40,16 @@ The CLI, templates, and mock host are owned by `@heybox/hb-sdk`. Do not create a
 ```text
 hb-sdk create <project-name>
 hb-sdk dev [--port <port>] [--mock-port <port>] [--runtime-url <url>] [--no-open]
-hb-sdk login [--login-base-url <url>]
+hb-sdk login [--login-base-url <url>] [--no-select-entity]
 hb-sdk login status
 hb-sdk login clear
 hb-sdk doctor
 hb-sdk remote access
+hb-sdk remote entity list
+hb-sdk remote entity current
+hb-sdk remote entity switch <entity-id>
 hb-sdk remote list [--status <status>] [--keyword <text>]
-hb-sdk remote create --name <name> [--preview-image-url <url>] [--force-bind]
+hb-sdk remote create --name <name> [--preview-image-url <url>] [--yes] [--force-bind]
 hb-sdk remote bind <mini-program-id> [--force]
 hb-sdk remote info
 hb-sdk remote update [--name <name>] [--preview-image-url <url>]
@@ -143,8 +147,10 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 7. 解析 `dist/manifest.json`，自动剥离 BOM，并校验 `version` 是合法 SemVer：允许 prerelease，例如 `1.2.3-rc.1`；拒绝 build metadata，例如 `1.2.3+build.1`；拒绝 `0.0.0`。
 8. 普通 remote deploy 的 `dist/manifest.json.version` 必须与预检使用的 `package.json.version` 一致，否则失败且不上传。
 9. 遍历 `dist/` 文件，过滤掉 `manifest.json`、`.DS_Store`、`*.map`；遇到 symbolic link 或 `node_modules` 路径直接报错。
-10. 4 并发把文件上传到 CDN，默认只展示上传阶段和文件总数；`--verbose` 会展示并发数、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie 或 token。
-11. 全部上传成功后调用提交审核接口，CLI 输出提交审核成功、发布策略和可用的 preview URL。
+10. 校验上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
+11. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 CDN。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
+12. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
+13. 全部上传成功后调用提交审核接口，CLI 输出提交审核成功、发布策略和可用的 preview URL。
 
 `mini_program_id` 没有 CLI flag，必须落在 `package.json` 里：
 
@@ -164,9 +170,12 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 
 `hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
 
+Before precheck, build, upload, or submit audit, `hb-sdk remote deploy` must verify that the current project's bound mini-program belongs to the server-side current entity. If `detail.entity_id` differs from the current entity, the command fails with both entity ids/names and suggests `hb-sdk remote entity switch <entity-id>`. It must not auto-switch entities and must not continue into precheck/build/upload/submit on mismatch.
+
 Agent rules:
 
 - Use `hb-sdk remote deploy --release-note <text>` for normal build, upload, and submit-audit flows.
+- Verify remote deploy guidance says current-entity mismatch fails before precheck/build/upload/submit and never auto-switches the developer entity.
 - Never recommend top-level `hb-sdk deploy`; it has been removed rather than retained as a compatibility alias.
 - After non-auto deploy succeeds, suggest `hb-sdk remote versions` and then `hb-sdk remote release <version>` after approval. Do not send the user to Open for manual publish when the CLI command exists.
 - Use `hb-sdk remote allowlist add <heybox_id>` when preview access needs to be granted.
@@ -177,6 +186,28 @@ Agent rules:
 - Custom base URLs must be origin-only; API origins must be Heybox trusted HTTPS unless the unsafe debug switch is explicit. Do not include path, query, or hash.
 - Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
 
+## Remote entity scope
+
+Developer entity selection lives under `hb-sdk remote entity`:
+
+```bash
+hb-sdk remote entity list
+hb-sdk remote entity current
+hb-sdk remote entity switch <entity-id>
+```
+
+The authoritative current entity is the developer platform server-side current entity. The CLI auth cache may contain a `selectedEntity` value, but that value is only a hint snapshot for `hb-sdk login status` display and drift troubleshooting. Do not use `selectedEntity` as the source of truth for permissions, ownership, create, bind, deploy, or release decisions.
+
+`hb-sdk login` tries to make the server-side current entity explicit after browser login. Zero entities leaves login successful and prints a guidance message. One entity is displayed and, when needed, switched to current. Multiple entities in a TTY prompt for a choice; multiple entities in non-interactive mode do not block login but tell the user to run `hb-sdk remote entity switch <entity-id>`. Passing `--no-select-entity` writes only the login state and does not modify the server-side current entity.
+
+Agent rules:
+
+- Treat the server-side current entity as the authority for remote create, bind, deploy, list, access, versions, preview, release, withdraw, take-down, and reopen workflows.
+- Treat CLI `selectedEntity` as a display/debug snapshot only; it can drift from the server-side current entity and must not be used as a permission source.
+- Use `hb-sdk remote entity current` when a user needs to confirm which entity create/deploy will use.
+- Use `hb-sdk remote entity switch <entity-id>` to change entity scope. Do not recommend `--entity-id` or an environment variable as a remote command override.
+- `hb-sdk remote list` lists mini-programs in the current entity scope only; do not promise cross-entity aggregation.
+
 ## Remote management commands
 
 ## 远端管理命令
@@ -209,7 +240,10 @@ hb-sdk remote reopen
 
 Agent rules:
 
+- Use `hb-sdk remote entity list/current/switch` for developer entity inspection and switching.
 - Use `hb-sdk remote create --name <name>` for create-and-bind and `hb-sdk remote bind <mini-program-id>` for binding an existing manageable remote mini-program.
+- Explain that `remote create` creates under the current entity and that multi-entity non-TTY usage must confirm with `--yes`; `--yes` confirms current-entity usage but does not switch entities.
+- Explain that `remote bind` verifies the mini-program is manageable by the current entity and does not write `package.json.heybox.miniProgramId` on entity mismatch.
 - Use `hb-sdk remote info`, `hb-sdk remote update`, `hb-sdk remote access`, `hb-sdk remote list`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` instead of sending users to Open when a matching CLI command exists.
 - Treat `hb-sdk remote list` as discovery only. Dangerous write commands still target the bound mini-program from `package.json.heybox.miniProgramId`.
 - Require confirmation or `--yes` for `hb-sdk remote release`, `hb-sdk remote withdraw`, `hb-sdk remote take-down`, and `hb-sdk remote reopen`.
@@ -236,6 +270,7 @@ hb-sdk login clear
 Agent rules:
 
 - Keep CLI auth cache separate from iframe SDK login state.
+- Keep `selectedEntity` guidance explicit: it is only a hint snapshot, while every remote command uses the server-side current entity.
 - It is correct to say status output is redacted.
 - Do not expose or template pkey, cookie, token, or private credential values.
 - Use `hb-sdk login clear` only to clear the `hb-sdk` CLI namespace.
@@ -322,7 +357,7 @@ npm run deploy
 
 - `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面，也可以选择局域网网卡后用手机小黑盒 APP 扫码调试。手机需要与电脑处在同一局域网，并使用支持小程序调试壳的新版小黑盒 APP。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP，需要时请在系统浏览器中打开同一个调试页后重试。
 - `npm run build`：先执行 TypeScript 检查，再构建生产产物。
-- `npm run deploy -- --release-note "..."`：运行 `hb-sdk remote deploy`，构建、上传并提交当前小程序版本审核。部署前需要先通过 `hb-sdk remote create --name "..."` 创建并绑定远端小程序，或用 `hb-sdk remote bind <mini-program-id>` 绑定已有小程序，并执行过 `npx hb-sdk login`；默认审核通过后用 `hb-sdk remote versions` 查看状态，再用 `hb-sdk remote release <version>` 发布，如需审核通过后自动发布可追加 `--auto-publish`。顶层 `hb-sdk deploy` 已删除，不再作为兼容别名保留。
+- `npm run deploy -- --release-note "..."`：运行 `hb-sdk remote deploy`，构建、上传并提交当前小程序版本审核。部署前需要先执行过 `npx hb-sdk login`；多主体账号还应通过 `npx hb-sdk remote entity current` 确认服务端 current entity。远端小程序可通过 `npx hb-sdk remote create --name "..."` 在 current entity 下创建并绑定，或用 `npx hb-sdk remote bind <mini-program-id>` 绑定 current entity 可管理的已有小程序。`selectedEntity` 只是 CLI 登录缓存中的提示快照，实际 deploy/create/bind 以服务端 current entity 为准。默认审核通过后用 `hb-sdk remote versions` 查看状态，再用 `hb-sdk remote release <version>` 发布，如需审核通过后自动发布可追加 `--auto-publish`。顶层 `hb-sdk deploy` 已删除，不再作为兼容别名保留。
 
 ## 更多能力
 
@@ -334,7 +369,6 @@ import hbSDK from '@heybox/hb-sdk';
 await hbSDK.share.showShareMenu({
   title: '<%= projectName %>',
   desc: '分享描述',
-  url: window.location.href,
 });
 
 await hbSDK.storage.setStorage({
@@ -347,4 +381,6 @@ const response = await hbSDK.network.request({
   url: 'https://jsonplaceholder.typicode.com/todos/1',
 });
 ```
+
+用户小程序通常不要传 `url`；宿主 runtime 会自动生成当前小程序的通用分享页。只有确实要分享外部 HTTP(S) 页面时才显式传 `url`。
 ````

package/skill/scripts/sync-references.mjs

@@ -209,13 +209,16 @@ const cliDoctorSection = extractSection(cliGuide, '## Agent Skill doctor');
 const cliUpdateSection = extractSection(cliGuide, '## 版本提醒');
 const cliCommandSurface = `hb-sdk create <project-name>
 hb-sdk dev [--port <port>] [--mock-port <port>] [--runtime-url <url>] [--no-open]
-hb-sdk login [--login-base-url <url>]
+hb-sdk login [--login-base-url <url>] [--no-select-entity]
 hb-sdk login status
 hb-sdk login clear
 hb-sdk doctor
 hb-sdk remote access
+hb-sdk remote entity list
+hb-sdk remote entity current
+hb-sdk remote entity switch <entity-id>
 hb-sdk remote list [--status <status>] [--keyword <text>]
-hb-sdk remote create --name <name> [--preview-image-url <url>] [--force-bind]
+hb-sdk remote create --name <name> [--preview-image-url <url>] [--yes] [--force-bind]
 hb-sdk remote bind <mini-program-id> [--force]
 hb-sdk remote info
 hb-sdk remote update [--name <name>] [--preview-image-url <url>]
@@ -233,6 +236,18 @@ hb-sdk remote reopen [--yes]
 
 Removed: hb-sdk deploy`;
 
+const cliRemoteEntitySection = `Developer entity selection lives under \`hb-sdk remote entity\`:
+
+${fenced('bash', `hb-sdk remote entity list
+hb-sdk remote entity current
+hb-sdk remote entity switch <entity-id>`)}
+
+The authoritative current entity is the developer platform server-side current entity. The CLI auth cache may contain a \`selectedEntity\` value, but that value is only a hint snapshot for \`hb-sdk login status\` display and drift troubleshooting. Do not use \`selectedEntity\` as the source of truth for permissions, ownership, create, bind, deploy, or release decisions.
+
+\`hb-sdk login\` tries to make the server-side current entity explicit after browser login. Zero entities leaves login successful and prints a guidance message. One entity is displayed and, when needed, switched to current. Multiple entities in a TTY prompt for a choice; multiple entities in non-interactive mode do not block login but tell the user to run \`hb-sdk remote entity switch <entity-id>\`. Passing \`--no-select-entity\` writes only the login state and does not modify the server-side current entity.`;
+
+const cliRemoteEntityDeploySection = `Before precheck, build, upload, or submit audit, \`hb-sdk remote deploy\` must verify that the current project's bound mini-program belongs to the server-side current entity. If \`detail.entity_id\` differs from the current entity, the command fails with both entity ids/names and suggests \`hb-sdk remote entity switch <entity-id>\`. It must not auto-switch entities and must not continue into precheck/build/upload/submit on mismatch.`;
+
 const files = new Map();
 
 files.set('api-root.md', `${header('Root API reference', [
@@ -322,6 +337,7 @@ files.set('cli.md', `${header('CLI reference', [
   ['Create a mini-program template', 'create-a-mini-program-template'],
   ['Local dev and mock runtime', 'local-dev-and-mock-runtime'],
   ['Deploy and backend operations', 'deploy-and-backend-operations'],
+  ['Remote entity scope', 'remote-entity-scope'],
   ['Remote management commands', 'remote-management-commands'],
   ['CLI login cache', 'cli-login-cache'],
   ['Agent Skill doctor', 'agent-skill-doctor'],
@@ -330,7 +346,7 @@ files.set('cli.md', `${header('CLI reference', [
   ['Generated template README', 'generated-template-readme'],
 ])}## When to use the CLI
 
-Use the bundled \`hb-sdk\` CLI when the task is about creating an external mini-program project, starting local Vite development, debugging SDK calls in a browser mock runtime host, or managing the CLI's own Heybox auth cache.
+Use the bundled \`hb-sdk\` CLI when the task is about creating an external mini-program project, starting local Vite development, debugging SDK calls in a browser mock runtime host, managing the CLI's own Heybox auth cache, or inspecting/switching the developer platform current entity for remote mini-program management.
 
 Do not use the CLI to replace iframe SDK calls. \`hb-sdk login\` is for CLI commands only and does not change \`auth.login()\`, \`user.getInfo()\`, \`network.request()\`, or mock-host user state.
 
@@ -363,9 +379,12 @@ Use \`hb-sdk dev\` for local browser SDK debugging. Use the Mock runtime host's
 
 ${cliDeploySection}
 
+${cliRemoteEntityDeploySection}
+
 Agent rules:
 
 - Use \`hb-sdk remote deploy --release-note <text>\` for normal build, upload, and submit-audit flows.
+- Verify remote deploy guidance says current-entity mismatch fails before precheck/build/upload/submit and never auto-switches the developer entity.
 - Never recommend top-level \`hb-sdk deploy\`; it has been removed rather than retained as a compatibility alias.
 - After non-auto deploy succeeds, suggest \`hb-sdk remote versions\` and then \`hb-sdk remote release <version>\` after approval. Do not send the user to Open for manual publish when the CLI command exists.
 - Use \`hb-sdk remote allowlist add <heybox_id>\` when preview access needs to be granted.
@@ -376,13 +395,28 @@ Agent rules:
 - Custom base URLs must be origin-only; API origins must be Heybox trusted HTTPS unless the unsafe debug switch is explicit. Do not include path, query, or hash.
 - Do not expect custom base URLs to affect \`hb-sdk doctor\`, npm latest checks, or mock-host \`network.request()\`.
 
+## Remote entity scope
+
+${cliRemoteEntitySection}
+
+Agent rules:
+
+- Treat the server-side current entity as the authority for remote create, bind, deploy, list, access, versions, preview, release, withdraw, take-down, and reopen workflows.
+- Treat CLI \`selectedEntity\` as a display/debug snapshot only; it can drift from the server-side current entity and must not be used as a permission source.
+- Use \`hb-sdk remote entity current\` when a user needs to confirm which entity create/deploy will use.
+- Use \`hb-sdk remote entity switch <entity-id>\` to change entity scope. Do not recommend \`--entity-id\` or an environment variable as a remote command override.
+- \`hb-sdk remote list\` lists mini-programs in the current entity scope only; do not promise cross-entity aggregation.
+
 ## Remote management commands
 
 ${cliRemoteSection}
 
 Agent rules:
 
+- Use \`hb-sdk remote entity list/current/switch\` for developer entity inspection and switching.
 - Use \`hb-sdk remote create --name <name>\` for create-and-bind and \`hb-sdk remote bind <mini-program-id>\` for binding an existing manageable remote mini-program.
+- Explain that \`remote create\` creates under the current entity and that multi-entity non-TTY usage must confirm with \`--yes\`; \`--yes\` confirms current-entity usage but does not switch entities.
+- Explain that \`remote bind\` verifies the mini-program is manageable by the current entity and does not write \`package.json.heybox.miniProgramId\` on entity mismatch.
 - Use \`hb-sdk remote info\`, \`hb-sdk remote update\`, \`hb-sdk remote access\`, \`hb-sdk remote list\`, \`hb-sdk remote versions\`, \`hb-sdk remote preview <version>\`, and \`hb-sdk remote allowlist ...\` instead of sending users to Open when a matching CLI command exists.
 - Treat \`hb-sdk remote list\` as discovery only. Dangerous write commands still target the bound mini-program from \`package.json.heybox.miniProgramId\`.
 - Require confirmation or \`--yes\` for \`hb-sdk remote release\`, \`hb-sdk remote withdraw\`, \`hb-sdk remote take-down\`, and \`hb-sdk remote reopen\`.
@@ -395,6 +429,7 @@ ${cliLoginSection}
 Agent rules:
 
 - Keep CLI auth cache separate from iframe SDK login state.
+- Keep \`selectedEntity\` guidance explicit: it is only a hint snapshot, while every remote command uses the server-side current entity.
 - It is correct to say status output is redacted.
 - Do not expose or template pkey, cookie, token, or private credential values.
 - Use \`hb-sdk login clear\` only to clear the \`hb-sdk\` CLI namespace.

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.4.5+skill.f7eeb07997a5",
+  "skillVersion": "0.4.7+skill.c42e9bccd99b",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.4.5",
-    "compatibility": "0.4.5"
+    "version": "0.4.7",
+    "compatibility": "0.4.7"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-f7eeb07997a5926a9f1d636d9e4d46ad412635a66da4a444095970ed17857c0e"
+  "integrity": "sha256-c42e9bccd99b7a9f6119a18ad0bd8bd9040176bdcc99134b0c6f29aa19e9aa59"
 }

package/types/miniapp-publish/index.d.ts

@@ -1,6 +1,10 @@
 export declare const MINIAPP_UPLOAD_SCOPE = "activity";
 export declare const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
+export declare const MINIAPP_UPLOAD_BATCH_SIZE = 50;
+export declare const MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES: number;
 export declare const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = "/mall/developer/user_miniprogram/access_status";
+export declare const DEVELOPER_ENTITY_LIST_API_PATH = "/mall/developer/entity/list";
+export declare const DEVELOPER_ENTITY_SWITCH_API_PATH = "/mall/developer/entity/switch";
 export declare const LIST_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/list";
 export declare const CREATE_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/create";
 export declare const UPDATE_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/update";
@@ -34,4 +38,12 @@ export interface ValidateUploadPathsOptions {
     maxLength?: number;
 }
 export declare function validateUploadPaths(items: UploadPathItem[], options: ValidateUploadPathsOptions): string | undefined;
+export interface UploadSizeItem {
+    relativePath: string;
+    size: number;
+}
+export interface ValidateUploadTotalSizeOptions {
+    limitBytes?: number;
+}
+export declare function validateUploadTotalSize(items: UploadSizeItem[], options?: ValidateUploadTotalSizeOptions): "构建产物总大小超过 100MB，请删除未引用资源或压缩图片后重新 deploy" | undefined;
 export declare function shouldUploadDistFile(relativePath: string): boolean;

package/types/modules/share/types.d.ts

@@ -16,8 +16,8 @@ export interface MiniProgramShowShareMenuOptions {
     title: string;
     /** 分享描述。 */
     desc: string;
-    /** 分享落地页 URL。 */
-    url: string;
+    /** 分享落地页 URL；不传时由宿主 runtime 生成当前小程序的通用分享页。 */
+    url?: string;
     /** 分享缩略图 URL。 */
     imageUrl?: string;
     /** 指定分享渠道；不传则由客户端展示默认分享面板。 */