@heybox/hb-sdk 0.4.4 → 0.4.5

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 management commands](#remote-management-commands)
 - [CLI login cache](#cli-login-cache)
 - [Agent Skill doctor](#agent-skill-doctor)
 - [Update reminders](#update-reminders)
@@ -35,341 +36,36 @@ 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>]
+hb-sdk login status
+hb-sdk login clear
+hb-sdk doctor
+hb-sdk remote access
+hb-sdk remote list [--status <status>] [--keyword <text>]
+hb-sdk remote create --name <name> [--preview-image-url <url>] [--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 +124,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 +158,63 @@ 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()` 不受这些配置影响。
 
 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.
+- 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 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 create --name <name>` for create-and-bind and `hb-sdk remote bind <mini-program-id>` for binding an existing manageable remote mini-program.
+- 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 登录态
@@ -542,7 +279,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 +322,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`，构建、上传并提交当前小程序版本审核。部署前需要先通过 `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` 已删除，不再作为兼容别名保留。
 
 ## 更多能力
 

package/skill/scripts/sync-references.mjs

@@ -203,9 +203,35 @@ const cliDevSection = [
   extractSection(cliGuide, '## Mock runtime 边界'),
 ].filter(Boolean).join('\n\n');
 const cliDeploySection = extractSection(cliGuide, '## 部署发布');
+const cliRemoteSection = extractSection(cliGuide, '## 远端管理命令');
 const cliLoginSection = extractSection(cliGuide, '## CLI 登录态');
 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 status
+hb-sdk login clear
+hb-sdk doctor
+hb-sdk remote access
+hb-sdk remote list [--status <status>] [--keyword <text>]
+hb-sdk remote create --name <name> [--preview-image-url <url>] [--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`;
 
 const files = new Map();
 
@@ -296,6 +322,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 management commands', 'remote-management-commands'],
   ['CLI login cache', 'cli-login-cache'],
   ['Agent Skill doctor', 'agent-skill-doctor'],
   ['Update reminders', 'update-reminders'],
@@ -311,7 +338,9 @@ The CLI, templates, and mock host are owned by \`${packageJson.name}\`. Do not c
 
 ## Command surface
 
-${fenced('ts', cliEntry)}
+${fenced('text', cliCommandSurface)}
+
+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
 
@@ -336,14 +365,29 @@ ${cliDeploySection}
 
 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.
+- 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 management commands
+
+${cliRemoteSection}
+
+Agent rules:
+
+- 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.
+- 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
 
 ${cliLoginSection}

package/skill/skill.json

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

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

@@ -1,7 +1,20 @@
 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 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";
+export declare const DETAIL_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/detail";
+export declare const USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = "/mall/developer/user_miniprogram/preview_allowlist";
+export declare const UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = "/mall/developer/user_miniprogram/preview_allowlist/update";
 export declare const PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/precheck";
 export declare const SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH = "/mall/developer/user_miniprogram/version/submit_audit";
+export declare const USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH = "/mall/developer/user_miniprogram/version/preview_info";
+export declare const WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/withdraw";
+export declare const RELEASE_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/release";
+export declare const TAKE_DOWN_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/take_down";
+export declare const REOPEN_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/reopen";
+export declare const LIST_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/list";
 export { isValidMiniappManifestVersion as isValidVersion } from '../miniapp-manifest/schema';
 export declare function normalizeRelativePath(relativePath: string): string;
 export declare function relativePathContainsNodeModulesSegment(relativePath: string): boolean;