@heybox/hb-sdk 0.4.4 → 0.4.6

package/skill/references/cli.md

@@ -20,6 +20,8 @@
 - [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)
 - [Update reminders](#update-reminders)
@@ -27,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.
 
@@ -35,341 +37,39 @@ The CLI, templates, and mock host are owned by `@heybox/hb-sdk`. Do not create a
 
 ## Command surface
 
-```ts
-import { Command, CommanderError, InvalidArgumentError } from 'commander';
-import { printUpdateReminder as defaultPrintUpdateReminder } from './update-check';
-import { printError as defaultPrintError } from './utils/errors';
-import { createCliLogger, type CliLogger } from './utils/logger';
-import { getCliVersion } from './version';
-
-type ClearLoginStatus = typeof import('./commands/login').clearLoginStatus;
-type LoginToHeybox = typeof import('./commands/login').loginToHeybox;
-type PrintLoginStatus = typeof import('./commands/login').printLoginStatus;
-type RunCreateCommand = typeof import('./commands/create').runCreateCommand;
-type RunDeployCommand = typeof import('./commands/deploy').runDeployCommand;
-type RunDevCommand = typeof import('./commands/dev').runDevCommand;
-type RunDoctorCommand = typeof import('./commands/doctor').runDoctorCommand;
-
-export interface CliCommandHandlers {
-  clearLoginStatus: ClearLoginStatus;
-  loginToHeybox: LoginToHeybox;
-  printLoginStatus: PrintLoginStatus;
-  printUpdateReminder: typeof defaultPrintUpdateReminder;
-  runCreateCommand: RunCreateCommand;
-  runDeployCommand: RunDeployCommand;
-  runDevCommand: RunDevCommand;
-  runDoctorCommand: RunDoctorCommand;
-}
-
-export interface CliRuntimeOptions extends Partial<CliCommandHandlers> {
-  argv?: string[];
-  createLogger?: (options: { verbose: boolean }) => CliLogger;
-  logger?: CliLogger;
-  printError?: typeof defaultPrintError;
-  process?: Pick<NodeJS.Process, 'exit'>;
-}
-
-export async function runCli(options: CliRuntimeOptions = {}) {
-  const processLike = options.process ?? process;
-  const argv = options.argv ?? process.argv;
-  const verbose = hasVerboseArg(argv);
-
-  try {
-    await createCliProgram(options).parseAsync(argv);
-  } catch (error) {
-    if (error instanceof CommanderError && error.exitCode === 0) {
-      processLike.exit(0);
-      return;
-    }
-
-    if (!(error instanceof CommanderError)) {
-      (options.printError ?? defaultPrintError)(error, { logger: resolveStandaloneLogger(options, verbose), verbose });
-    }
-
-    processLike.exit(error instanceof CommanderError ? error.exitCode : 1);
-  }
-}
-
-export function createCliProgram(overrides: Partial<CliCommandHandlers> & Pick<CliRuntimeOptions, 'createLogger' | 'logger'> = {}) {
-  const handlers: CliCommandHandlers = {
-    clearLoginStatus: defaultClearLoginStatus,
-    loginToHeybox: defaultLoginToHeybox,
-    printLoginStatus: defaultPrintLoginStatus,
-    printUpdateReminder: defaultPrintUpdateReminder,
-    runCreateCommand: defaultRunCreateCommand,
-    runDeployCommand: defaultRunDeployCommand,
-    runDevCommand: defaultRunDevCommand,
-    runDoctorCommand: defaultRunDoctorCommand,
-    ...overrides,
-  };
-  const program = new Command();
-  const resolveLogger = createCommandLoggerResolver(overrides);
-
-  program
-    .name('hb-sdk')
-    .description('hb-sdk developer tools')
-    .version(getCliVersion())
-    .option('-v, --verbose', '输出详细调试信息')
-    .showHelpAfterError()
-    .exitOverride();
-  installVersionUpdateReminder(program, handlers.printUpdateReminder, resolveLogger);
-
-  addVerboseOption(
-    program.command('create').description('创建外部小程序项目开发模板').argument('<project-name>', '项目目录名，例如 my-miniapp'),
-  ).action(
-    withUpdateReminder(
-      async (projectName, _options, command: Command) => {
-        const logger = resolveLogger(command);
-        await handlers.runCreateCommand(projectName, { logger });
-      },
-      handlers.printUpdateReminder,
-      resolveLogger,
-    ),
-  );
-
-  addVerboseOption(
-    program
-      .command('dev')
-      .description('启动当前小程序项目的 Vite dev server 和浏览器 mock runtime host')
-      .option('--port <port>', 'App dev server 端口', parsePositivePort)
-      .option('--mock-port <port>', 'Mock host 端口', parsePositivePort)
-      .option('--runtime-url <url>', '真实客户端调试时使用的自定义 runtime 地址')
-      .option('--no-open', '不自动打开浏览器调试页'),
-  ).action(
-    withUpdateReminder(
-      async (options, command: Command) => {
-        const logger = resolveLogger(command);
-        await handlers.runDevCommand(options, { logger });
-      },
-      handlers.printUpdateReminder,
-      resolveLogger,
-    ),
-  );
-
-  addVerboseOption(
-    program
-      .command('deploy')
-      .description('构建并提交当前小程序版本审核')
-      .option('--skip-build', '跳过 build，直接读 dist 目录上传并提交审核')
-      .option('--release-note <text>', '发布日志，提交审核必填')
-      .option('--auto-publish', '审核通过后自动发布；默认需在开放平台手动发布')
-      .option('--api-base-url <url>', 'Heybox 后台 API origin，默认读取 HB_SDK_API_BASE_URL 或生产地址')
-      .option('--allow-unsafe-api-base-url', '允许向非 Heybox HTTPS API origin 发送登录态，仅限本地调试')
-      .option('--login-base-url <url>', '校验 CLI 登录态使用的登录 origin，默认读取 HB_SDK_LOGIN_BASE_URL 或生产地址'),
-  ).action(
-    withUpdateReminder(
-      async (options, command: Command) => {
-        const logger = resolveLogger(command);
-        await handlers.runDeployCommand(
-          {
-            allowUnsafeApiBaseUrl: Boolean(options.allowUnsafeApiBaseUrl),
-            apiBaseUrl: options.apiBaseUrl,
-            autoPublish: Boolean(options.autoPublish),
-            loginBaseUrl: options.loginBaseUrl,
-            releaseNote: options.releaseNote,
-            skipBuild: Boolean(options.skipBuild),
-          },
-          { logger },
-        );
-      },
-      handlers.printUpdateReminder,
-      resolveLogger,
-    ),
-  );
-
-  addVerboseOption(program.command('doctor').description('诊断 hb-sdk 本地环境和 Agent Skill 版本')).action(async (...args: unknown[]) => {
-    const logger = resolveLogger(readCommandFromActionArgs(args));
-    const result = await handlers.runDoctorCommand({ logger });
-
-    if (result.status !== 'SDK_MISMATCH') {
-      await handlers.printUpdateReminder({ logger });
-    }
-  });
-
-  const login = addVerboseOption(
-    program
-      .command('login')
-      .description('登录 Heybox 并缓存 CLI 登录态')
-      .option('--login-base-url <url>', 'Heybox 登录入口 origin，默认读取 HB_SDK_LOGIN_BASE_URL 或生产地址'),
-  ).action(
-    withUpdateReminder(
-      async (options, command: Command) => {
-        const logger = resolveLogger(command);
-        await handlers.loginToHeybox({
-          logger,
-          loginBaseUrl: options.loginBaseUrl,
-        });
-      },
-      handlers.printUpdateReminder,
-      resolveLogger,
-    ),
-  );
-
-  addVerboseOption(login.command('status').description('查看脱敏后的 Heybox 登录态')).action(
-    withUpdateReminder(
-      async (...args: unknown[]) => {
-        const logger = resolveLogger(readCommandFromActionArgs(args));
-        await handlers.printLoginStatus({ logger });
-      },
-      handlers.printUpdateReminder,
-      resolveLogger,
-    ),
-  );
-
-  addVerboseOption(login.command('clear').description('清理 hb-sdk 命名空间中的 Heybox 登录态')).action(
-    withUpdateReminder(
-      async (...args: unknown[]) => {
-        const logger = resolveLogger(readCommandFromActionArgs(args));
-        await handlers.clearLoginStatus({ logger });
-      },
-      handlers.printUpdateReminder,
-      resolveLogger,
-    ),
-  );
-
-  return program;
-}
-
-function addVerboseOption<T extends Command>(command: T): T {
-  return command.option('-v, --verbose', '输出详细调试信息') as T;
-}
-
-function hasVerboseArg(argv: string[]) {
-  return argv.includes('--verbose') || argv.includes('-v');
-}
-
-type ResolveCommandLogger = (commandOrVerbose?: Command | boolean) => CliLogger;
-
-function createCommandLoggerResolver(options: Pick<CliRuntimeOptions, 'createLogger' | 'logger'>): ResolveCommandLogger {
-  let defaultLogger: CliLogger | undefined;
-  let verboseLogger: CliLogger | undefined;
-
-  return (commandOrVerbose?: Command | boolean) => {
-    if (options.logger) {
-      return options.logger;
-    }
-
-    const verbose = typeof commandOrVerbose === 'boolean' ? commandOrVerbose : readCommandVerbose(commandOrVerbose);
-    if (verbose) {
-      verboseLogger ??= resolveStandaloneLogger(options, true);
-      return verboseLogger;
-    }
-
-    defaultLogger ??= resolveStandaloneLogger(options, false);
-    return defaultLogger;
-  };
-}
-
-const defaultClearLoginStatus: ClearLoginStatus = async (...args) => {
-  const { clearLoginStatus } = await import('./commands/login');
-  return clearLoginStatus(...args);
-};
-
-const defaultLoginToHeybox: LoginToHeybox = async (...args) => {
-  const { loginToHeybox } = await import('./commands/login');
-  return loginToHeybox(...args);
-};
-
-const defaultPrintLoginStatus: PrintLoginStatus = async (...args) => {
-  const { printLoginStatus } = await import('./commands/login');
-  return printLoginStatus(...args);
-};
-
-const defaultRunCreateCommand: RunCreateCommand = async (...args) => {
-  const { runCreateCommand } = await import('./commands/create');
-  return runCreateCommand(...args);
-};
-
-const defaultRunDeployCommand: RunDeployCommand = async (...args) => {
-  const { runDeployCommand } = await import('./commands/deploy');
-  return runDeployCommand(...args);
-};
-
-const defaultRunDevCommand: RunDevCommand = async (...args) => {
-  const { runDevCommand } = await import('./commands/dev');
-  return runDevCommand(...args);
-};
-
-const defaultRunDoctorCommand: RunDoctorCommand = async (...args) => {
-  const { runDoctorCommand } = await import('./commands/doctor');
-  return runDoctorCommand(...args);
-};
-
-function resolveStandaloneLogger(options: Pick<CliRuntimeOptions, 'createLogger' | 'logger'>, verbose: boolean) {
-  return options.logger ?? options.createLogger?.({ verbose }) ?? createCliLogger({ verbose });
-}
-
-function readCommandVerbose(command?: Command) {
-  if (!command) {
-    return false;
-  }
-
-  return Boolean(command.optsWithGlobals?.().verbose || command.opts().verbose);
-}
-
-function installVersionUpdateReminder(program: Command, printUpdateReminder: typeof defaultPrintUpdateReminder, resolveLogger: ResolveCommandLogger) {
-  const parseAsync = program.parseAsync.bind(program);
-
-  program.parseAsync = (async (...args: Parameters<Command['parseAsync']>) => {
-    const [argv, parseOptions] = args;
-
-    if (isVersionRequest(argv, parseOptions)) {
-      const logger = resolveLogger(hasVerboseArg(getUserArgs(argv, parseOptions)));
-      logger.raw(getCliVersion(), { stream: 'stdout' });
-      await printUpdateReminder({ logger });
-      throw new CommanderError(0, 'commander.version', 'version displayed');
-    }
-
-    return parseAsync(...args);
-  }) as Command['parseAsync'];
-}
-
-function isVersionRequest(argv: readonly string[] | undefined, parseOptions: { from?: string } | undefined) {
-  const userArgs = getUserArgs(argv, parseOptions).filter((arg) => arg !== '--verbose' && arg !== '-v');
-
-  return userArgs.length === 1 && (userArgs[0] === '--version' || userArgs[0] === '-V');
-}
-
-function getUserArgs(argv: readonly string[] | undefined, parseOptions: { from?: string } | undefined) {
-  const args = [...(argv ?? process.argv)];
-
-  if (parseOptions?.from === 'user') {
-    return args;
-  }
-
-  if (parseOptions?.from === 'electron') {
-    return args.slice(1);
-  }
-
-  return args.slice(2);
-}
-
-function withUpdateReminder<Args extends unknown[]>(
-  action: (...args: Args) => Promise<void>,
-  printUpdateReminder: typeof defaultPrintUpdateReminder,
-  resolveLogger: ResolveCommandLogger,
-) {
-  return async (...args: Args) => {
-    await action(...args);
-    await printUpdateReminder({ logger: resolveLogger(readCommandFromActionArgs(args)) });
-  };
-}
-
-function readCommandFromActionArgs(args: unknown[]) {
-  const lastArg = args[args.length - 1];
-  return lastArg instanceof Command ? lastArg : undefined;
-}
-
-function parsePositivePort(value: string) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed <= 0) {
-    throw new InvalidArgumentError('必须是正整数端口号');
-  }
-
-  return parsed;
-}
+```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>] [--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>] [--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>]
+hb-sdk remote allowlist list
+hb-sdk remote allowlist add <heybox-id...>
+hb-sdk remote allowlist remove <heybox-id...>
+hb-sdk remote allowlist set <heybox-id...>
+hb-sdk remote deploy --release-note <text> [--skip-build] [--auto-publish]
+hb-sdk remote versions
+hb-sdk remote preview <version>
+hb-sdk remote release <version> [--yes]
+hb-sdk remote withdraw <version> [--yes] [--reason <text>]
+hb-sdk remote take-down [--yes]
+hb-sdk remote reopen [--yes]
+
+Removed: hb-sdk deploy
 ```
 
+Top-level `hb-sdk deploy` has been hard-cut and must not be documented as a valid compatibility alias. Keep `hb-sdk login` top-level because it manages CLI login state, not a specific remote mini-program.
+
 ## Create a mini-program template
 
 ## 创建外部小程序模板
@@ -428,24 +128,24 @@ Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "
 ## 部署发布
 
 ```bash
-hb-sdk deploy --release-note "修复登录状态展示，补充异常提示"
-hb-sdk deploy --release-note "审核通过后自动发布" --auto-publish
-hb-sdk deploy --skip-build --release-note "复用已有 dist 构建产物"
-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 "本地后台联调"
+hb-sdk remote deploy --release-note "修复登录状态展示，补充异常提示"
+hb-sdk remote deploy --release-note "审核通过后自动发布" --auto-publish
+hb-sdk remote deploy --skip-build --release-note "复用已有 dist 构建产物"
+hb-sdk remote deploy --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "测试环境验证"
+hb-sdk remote 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 remote deploy --api-base-url http://127.0.0.1:8080 --release-note "本地后台联调"
 ```
 
-`hb-sdk deploy` 把预检、构建、上传和提交审核串成一条命令：
+`hb-sdk remote deploy` 把预检、构建、上传和提交审核串成一条命令。顶层 `hb-sdk deploy` 已硬切删除，不再作为兼容别名保留：
 
 1. 读取 `package.json.heybox.miniProgramId`，缺失即报错。
 2. 校验登录态，需先 `hb-sdk login`。
 3. 如果需要以公司的名义发布小程序，需先找 @秦浩东 申请小程序开发权限。
 4. 读取并校验 `--release-note`；TTY 环境缺失时会提示输入，CI / 非 TTY 环境缺失时直接失败。建议让 AI 生成 1-5 条简短发布日志。
-5. 普通 deploy 先读取 `package.json.version`，登录后、build 前调用版本预检接口；预检通过后才执行 `<pm> run build`。
+5. 普通 remote deploy 先读取 `package.json.version`，登录后、build 前调用版本预检接口；预检通过后才执行 `<pm> run build`。
 6. `--skip-build` 跳过构建，但会先读取已有 `dist/manifest.json.version`，再调用版本预检接口。
 7. 解析 `dist/manifest.json`，自动剥离 BOM，并校验 `version` 是合法 SemVer：允许 prerelease，例如 `1.2.3-rc.1`；拒绝 build metadata，例如 `1.2.3+build.1`；拒绝 `0.0.0`。
-8. 普通 deploy 的 `dist/manifest.json.version` 必须与预检使用的 `package.json.version` 一致，否则失败且不上传。
+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。
@@ -462,22 +162,91 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk deploy --api-base-url http://127.0.0.1
 
 `manifest.json` 仅作为提交审核接口的 `manifest` 字段提交，不会上传到 CDN。Vite 项目通过 `miniappManifest()` 插件生成；CLI 不会自动注入插件，请在 `vite.config.ts` 中显式挂载。小程序构建产物需要使用相对资源路径；`hb-sdk create` 模板会显式配置 `base: './'`，未配置 `base` 的项目也会由 `miniappManifest()` 在 build 时默认补成 `./`。
 
-默认发布策略是 `auto_publish=false`：运营审核通过后需在开放平台手动发布。需要审核通过后自动发布并下架旧线上版本时，使用 `--auto-publish`。
+默认发布策略是 `auto_publish=false`：运营审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布。需要审核通过后自动发布并下架旧线上版本时，使用 `--auto-publish`。如需让指定用户预览未发布候选版本，使用 `hb-sdk remote allowlist add <heybox_id>` 管理预览白名单。
 
-内部测试或预发环境可通过 `HB_SDK_API_BASE_URL` / `HB_SDK_LOGIN_BASE_URL` 设置默认后台环境，也可以用 `--api-base-url` / `--login-base-url` 覆盖单次命令。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。`apiBaseUrl` 只影响 deploy 里的预检、CDN 上传凭证/回调、提交审核；`loginBaseUrl` 用于 `hb-sdk login` 的登录入口，以及 deploy 前校验当前 CLI 登录态是否属于同一个登录环境。开发环境如需给后台请求带 `x-rylai-service-tag` 和 `special_tag`，可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置 `default_tag` 或 path-prefix 级 `special_tag`。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。
+内部测试或预发环境可通过 `HB_SDK_API_BASE_URL` / `HB_SDK_LOGIN_BASE_URL` 设置默认后台环境，也可以用 `--api-base-url` / `--login-base-url` 覆盖单次命令。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。`apiBaseUrl` 影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情、基础信息和白名单等调用；`loginBaseUrl` 用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。开发环境如需给后台请求带 `x-rylai-service-tag` 和 `special_tag`，可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置 `default_tag` 或 path-prefix 级 `special_tag`。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。
 
 `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 deploy --release-note <text>` for normal build, upload, and submit-audit flows.
-- Use `--api-base-url <url>` or `HB_SDK_API_BASE_URL` only for deploy backend APIs.
+- 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.
+- Use `--api-base-url <url>` or `HB_SDK_API_BASE_URL` for remote platform backend APIs.
 - Use `--allow-unsafe-api-base-url` or `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` only for local backend debugging against non-Heybox or non-HTTPS API origins.
-- Use `--login-base-url <url>` or `HB_SDK_LOGIN_BASE_URL` for CLI browser login and deploy login-environment validation.
+- Use `--login-base-url <url>` or `HB_SDK_LOGIN_BASE_URL` for CLI browser login and remote command login-environment validation.
 - Use `packages/hb-sdk/src/cli/config.ts` with `RylaiServiceTagConfig` only when Heybox backend API requests need the development-only `x-rylai-service-tag` header and matching `special_tag` query parameter.
 - 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
+
+## 远端管理命令
+
+远端平台操作统一放在 `hb-sdk remote` 命令组下，默认作用于当前项目绑定的小程序，也就是 `package.json.heybox.miniProgramId`。`remote list` 只用于发现可管理的小程序；会改变远端状态的命令仍然只操作当前绑定的小程序，不接受临时 `mini_program_id` 参数。
+
+常用命令：
+
+```bash
+hb-sdk remote access
+hb-sdk remote list
+hb-sdk remote create --name "我的小程序"
+hb-sdk remote bind mp_xxxxxxxx
+hb-sdk remote info
+hb-sdk remote update --name "新名称"
+hb-sdk remote allowlist add 12345678
+hb-sdk remote versions
+hb-sdk remote preview 1.2.3
+hb-sdk remote release 1.2.3
+hb-sdk remote withdraw 1.2.3 --reason "需要修复说明"
+hb-sdk remote take-down
+hb-sdk remote reopen
+```
+
+`hb-sdk remote create` 会创建远端用户小程序并写入当前项目绑定；已有绑定时必须传 `--force-bind` 才能覆盖。`hb-sdk remote bind <mini-program-id>` 会先校验当前 CLI 用户可管理目标小程序，再写入本地配置；`--force` 只允许覆盖本地绑定，不跳过远端校验。
+
+`hb-sdk remote release`、`hb-sdk remote withdraw`、`hb-sdk remote take-down` 和 `hb-sdk remote reopen` 会改变审核、发布或用户侧可见状态。交互式终端会展示小程序 id、名称、当前状态、目标版本和操作，再要求确认；非 TTY 环境必须传 `--yes`。
+
+所有 `hb-sdk remote` 子命令都支持 `--json`。开启后 stdout 只输出一个 JSON 对象；进度、警告、版本提醒和 verbose 诊断不能污染 stdout。
+
+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`.
+- Use `--json` for script consumption and keep stdout as exactly one JSON object.
+
 ## CLI login cache
 
 ## CLI 登录态
@@ -499,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.
@@ -542,7 +312,7 @@ Agent rules:
 
 ## 版本提醒
 
-`hb-sdk create`、`hb-sdk dev`、`hb-sdk deploy`、`hb-sdk login`、`hb-sdk login status`、`hb-sdk login clear`、`hb-sdk doctor` 会在命令成功执行后检查 npm registry 上 `@heybox/hb-sdk` 的 `latest` 版本。检查结果会缓存 24 小时；检查失败会静默跳过；`CI=true` 时会跳过检查，避免污染 CI 日志。`hb-sdk doctor` 已经诊断出 `SDK_MISMATCH` 时不会再追加统一提醒，避免同一次输出里重复提示升级 SDK。`hb-sdk --version` / `hb-sdk -V` 也会执行同一套检查，但 stdout 只输出版本号，升级提醒继续按 warn 级别写到 stderr。本地可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用检查。
+`hb-sdk create`、`hb-sdk dev`、`hb-sdk remote ...`、`hb-sdk login`、`hb-sdk login status`、`hb-sdk login clear`、`hb-sdk doctor` 会在命令成功执行后检查 npm registry 上 `@heybox/hb-sdk` 的 `latest` 版本。普通命令的检查结果会缓存 24 小时；检查失败会静默跳过；`CI=true` 时会跳过检查，避免污染 CI 日志。`hb-sdk doctor` 已经诊断出 `SDK_MISMATCH` 时不会再追加统一提醒，避免同一次输出里重复提示升级 SDK。`hb-sdk --version` / `hb-sdk -V` 会直接请求 npm registry 获取 latest，不读取本地缓存；stdout 只输出版本号，升级提醒继续按 warn 级别写到 stderr。本地可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用检查。
 
 ## Repository validation commands
 
@@ -585,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 "..."`：构建、上传并提交当前小程序版本审核。部署前需要先把 `package.json` 中的 `heybox.miniProgramId` 改成后台分配的真实小程序 id，并执行过 `npx hb-sdk login`；默认审核通过后需在开放平台手动发布，如需审核通过后自动发布可追加 `--auto-publish`。
+- `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` 已删除，不再作为兼容别名保留。
 
 ## 更多能力