@heybox/hb-sdk 0.4.5 → 0.4.6

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>]
@@ -164,9 +168,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 +184,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 +238,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 +268,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 +355,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` 已删除，不再作为兼容别名保留。
 
 ## 更多能力
 

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.6+skill.1c7149a95a0b",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.4.5",
-    "compatibility": "0.4.5"
+    "version": "0.4.6",
+    "compatibility": "0.4.6"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-f7eeb07997a5926a9f1d636d9e4d46ad412635a66da4a444095970ed17857c0e"
+  "integrity": "sha256-1c7149a95a0b5d0ffeaa479456186dab5f3bc06865fd5c28a975682381267811"
 }

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

@@ -1,6 +1,8 @@
 export declare const MINIAPP_UPLOAD_SCOPE = "activity";
 export declare const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 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";