@heybox/hb-sdk 0.3.3 → 0.4.1

package/skill/references/cli.md

@@ -19,6 +19,7 @@
 - [Command surface](#command-surface)
 - [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)
 - [CLI login cache](#cli-login-cache)
 - [Agent Skill doctor](#agent-skill-doctor)
 - [Update reminders](#update-reminders)
@@ -36,41 +37,45 @@ The CLI, templates, and mock host are owned by `@heybox/hb-sdk`. Do not create a
 
 ```ts
 import { Command, CommanderError, InvalidArgumentError } from 'commander';
-import { runCreateCommand as defaultRunCreateCommand } from './commands/create';
-import { runDeployCommand as defaultRunDeployCommand } from './commands/deploy';
-import { runDevCommand as defaultRunDevCommand } from './commands/dev';
-import { runDoctorCommand as defaultRunDoctorCommand } from './commands/doctor';
-import {
-  clearLoginStatus as defaultClearLoginStatus,
-  loginToHeybox as defaultLoginToHeybox,
-  printLoginStatus as defaultPrintLoginStatus,
-} from './commands/login';
 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: typeof defaultClearLoginStatus;
-  loginToHeybox: typeof defaultLoginToHeybox;
-  printLoginStatus: typeof defaultPrintLoginStatus;
+  clearLoginStatus: ClearLoginStatus;
+  loginToHeybox: LoginToHeybox;
+  printLoginStatus: PrintLoginStatus;
   printUpdateReminder: typeof defaultPrintUpdateReminder;
-  runCreateCommand: typeof defaultRunCreateCommand;
-  runDeployCommand: typeof defaultRunDeployCommand;
-  runDevCommand: typeof defaultRunDevCommand;
-  runDoctorCommand: typeof defaultRunDoctorCommand;
+  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(options.argv ?? process.argv);
+    await createCliProgram(options).parseAsync(argv);
   } catch (error) {
     if (error instanceof CommanderError && error.exitCode === 0) {
       processLike.exit(0);
@@ -78,14 +83,14 @@ export async function runCli(options: CliRuntimeOptions = {}) {
     }
 
     if (!(error instanceof CommanderError)) {
-      (options.printError ?? defaultPrintError)(error);
+      (options.printError ?? defaultPrintError)(error, { logger: resolveStandaloneLogger(options, verbose), verbose });
     }
 
     processLike.exit(error instanceof CommanderError ? error.exitCode : 1);
   }
 }
 
-export function createCliProgram(overrides: Partial<CliCommandHandlers> = {}) {
+export function createCliProgram(overrides: Partial<CliCommandHandlers> & Pick<CliRuntimeOptions, 'createLogger' | 'logger'> = {}) {
   const handlers: CliCommandHandlers = {
     clearLoginStatus: defaultClearLoginStatus,
     loginToHeybox: defaultLoginToHeybox,
@@ -98,94 +103,263 @@ export function createCliProgram(overrides: Partial<CliCommandHandlers> = {}) {
     ...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,
+    ),
+  );
 
-  program
-    .command('create')
-    .description('创建外部小程序项目开发模板')
-    .argument('<project-name>', '项目目录名，例如 my-miniapp')
-    .action(
-      withUpdateReminder(async (projectName) => {
-        await handlers.runCreateCommand(projectName);
-      }, handlers.printUpdateReminder),
-    );
+  return program;
+}
 
-  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('--host <host>', '传给 Vite 和 mock host 的 host')
-    .option('--no-open', '不自动打开浏览器调试页')
-    .action(
-      withUpdateReminder(async (options) => {
-        await handlers.runDevCommand(options);
-      }, handlers.printUpdateReminder),
-    );
+function addVerboseOption<T extends Command>(command: T): T {
+  return command.option('-v, --verbose', '输出详细调试信息') as T;
+}
 
-  program
-    .command('deploy')
-    .description('构建并发布当前小程序到 Heybox 后台')
-    .option('--skip-build', '跳过 build，直接读 dist 目录上传并发布')
-    .action(
-      withUpdateReminder(async (options) => {
-        await handlers.runDeployCommand({ skipBuild: Boolean(options.skipBuild) });
-      }, handlers.printUpdateReminder),
-    );
+function hasVerboseArg(argv: string[]) {
+  return argv.includes('--verbose') || argv.includes('-v');
+}
 
-  program
-    .command('doctor')
-    .description('诊断 hb-sdk 本地环境和 Agent Skill 版本')
-    .action(async () => {
-      await handlers.runDoctorCommand();
-    });
-
-  const login = program
-    .command('login')
-    .description('登录 Heybox 并缓存 CLI 登录态')
-    .action(
-      withUpdateReminder(async () => {
-        await handlers.loginToHeybox();
-      }, handlers.printUpdateReminder),
-    );
-
-  login
-    .command('status')
-    .description('查看脱敏后的 Heybox 登录态')
-    .action(
-      withUpdateReminder(async () => {
-        await handlers.printLoginStatus();
-      }, handlers.printUpdateReminder),
-    );
-
-  login
-    .command('clear')
-    .description('清理 hb-sdk 命名空间中的 Heybox 登录态')
-    .action(
-      withUpdateReminder(async () => {
-        await handlers.clearLoginStatus();
-      }, handlers.printUpdateReminder),
-    );
+type ResolveCommandLogger = (commandOrVerbose?: Command | boolean) => CliLogger;
 
-  return program;
+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();
+    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) {
@@ -228,26 +402,81 @@ Agent rules:
 hb-sdk dev
 ```
 
-`hb-sdk dev` 会从当前目录向上查找最近的 `package.json` 作为项目根目录，加载该项目安装的 `vite`，并优先使用项目内的 Vite 配置文件。命令会同时启动内置 mock runtime host 并默认打开调试页；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。Codex、VSCode 等内嵌浏览器可能无法转交 `heybox://` 协议；需要从调试页唤起 Mac 版 APP 时，请先在系统浏览器中打开调试页。项目没有安装 Vite 时，命令会提示安装依赖或把 Vite 放到 `devDependencies`。
+`hb-sdk dev` 会从当前目录向上查找最近的 `package.json` 作为项目根目录，加载该项目安装的 `vite`，并优先使用项目内的 Vite 配置文件。命令会同时启动内置 mock runtime host 并默认打开调试页；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码。手机需要与电脑处在同一局域网，并使用支持小程序调试壳的新版小黑盒 APP。Codex、VSCode 等内嵌浏览器可能无法转交 `heybox://` 协议；需要从调试页唤起 Mac 版 APP 时，请先在系统浏览器中打开调试页。项目没有安装 Vite 时，命令会提示安装依赖或把 Vite 放到 `devDependencies`。
 
 常用参数：
 
-| 参数 | 说明 |
-| --- | --- |
-| `--port <port>` | 指定小程序 Vite dev server 端口，默认从 `5173` 开始。 |
-| `--mock-port <port>` | 指定 mock host 端口，默认从 `5174` 开始。 |
-| `--host <host>` | 同时传给 Vite 和 mock host 的 host。 |
-| `--no-open` | 不自动打开浏览器调试页。 |
+| 参数                 | 说明                                                  |
+| -------------------- | ----------------------------------------------------- |
+| `--port <port>`      | 指定小程序 Vite dev server 端口，默认从 `5173` 开始。 |
+| `--mock-port <port>` | 指定 mock host 端口，默认从 `5174` 开始。             |
+| `--runtime-url <url>` | 真实客户端调试时传给 dev shell 的自定义 runtime 地址；手机扫码时 loopback host 会自动改写为所选局域网 IP。 |
+| `--no-open`          | 不自动打开浏览器调试页。                              |
 
 ## Mock runtime 边界
 
-`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境。mock host 内置登录/登出、`show`、`hide`、在 Mac 版 APP 中启动等调试按钮，并通过同一份 devtools-only runtime adapter 处理 SDK 能力调用。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境。mock host 内置登录/登出、`show`、`hide`、在 Mac 版 APP 中启动、手机扫码调试等调试入口，并通过同一份 devtools-only runtime adapter 处理 SDK 能力调用。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 不要为了本地调试再创建独立 mock runtime 包。CLI、模板和 mock host 都归属 `@heybox/hb-sdk`。
 
 本地 mock runtime 下的 `network.request()` 会通过 `hb-sdk` 本地 mock network proxy 转发真实 HTTP(S) 请求，用于避免浏览器 CORS 影响本地调试。proxy 不会把黑盒客户端私有协议字段暴露给 iframe 业务代码。
 
-Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container. If the mock host is open inside Codex, VSCode, or another embedded browser, ask the user to open the same debug page in the system browser before retrying because embedded browsers may block the `heybox://` protocol handoff.
+Use `hb-sdk dev` for local browser SDK debugging. 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. If the mock host is open inside Codex, VSCode, or another embedded browser, ask the user to open the same debug page in the system browser before retrying because embedded browsers may block the `heybox://` protocol handoff.
+
+## Deploy and backend operations
+
+## 部署发布
+
+```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 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`。
+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` 一致，否则失败且不上传。
+9. 遍历 `dist/` 文件，过滤掉 `manifest.json`、`.DS_Store`、`*.map`；遇到 symbolic link 或 `node_modules` 路径直接报错。
+10. 4 并发把文件上传到 CDN，默认只展示上传阶段和文件总数；`--verbose` 会展示并发数、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie 或 token。
+11. 全部上传成功后调用提交审核接口，CLI 输出提交审核成功、发布策略和可用的 preview URL。
+
+`mini_program_id` 没有 CLI flag，必须落在 `package.json` 里：
+
+```json
+{
+  "heybox": {
+    "miniProgramId": "mp_xxxxxxxx"
+  }
+}
+```
+
+`manifest.json` 仅作为提交审核接口的 `manifest` 字段提交，不会上传到 CDN。Vite 项目通过 `miniappManifest()` 插件生成；CLI 不会自动注入插件，请在 `vite.config.ts` 中显式挂载。
+
+默认发布策略是 `auto_publish=false`：运营审核通过后需在开放平台手动发布。需要审核通过后自动发布并下架旧线上版本时，使用 `--auto-publish`。
+
+内部测试或预发环境可通过 `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 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 `--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 `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()`.
 
 ## CLI login cache
 
@@ -255,12 +484,14 @@ Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "
 
 ```bash
 hb-sdk login
+hb-sdk login --login-base-url https://login.test.xiaoheihe.cn
 hb-sdk login status
 hb-sdk login clear
 ```
 
 - `hb-sdk login` 会打开 `login.xiaoheihe.cn`，通过本地临时回调服务接收登录结果。
-- `hb-sdk login status` 只展示脱敏状态、`heyboxId`、登录时间和 cache 路径，不输出 `pkey`、cookie 或完整请求头。
+- `hb-sdk login --login-base-url <url>` 会打开指定登录 origin，并把该登录环境写入 CLI 登录态。
+- `hb-sdk login status` 默认展示脱敏状态、`heyboxId`、`loginBaseUrl` 和登录时间；`--verbose` 额外展示 cache 路径。不输出 `pkey`、cookie 或完整请求头。
 - `hb-sdk login clear` 只清理 `hb-sdk` 自己命名空间中的 Heybox 登录态。
 
 这份 CLI 登录态不会注入 iframe SDK，也不会改变 `hb-sdk dev` 的 mock 用户、`auth.login()`、`user.getInfo()` 或 `network.request()` 行为。
@@ -284,13 +515,13 @@ hb-sdk doctor
 
 `doctor` 只诊断，不修改本地文件。需要安装或刷新 skill 时，按输出提示手动执行 `npx skills add`。
 
-| 状态 | 含义 |
-| --- | --- |
-| `OK` | SDK、远端 latest skill、本机 skill 全部匹配。 |
-| `SKILL_MISSING` | 本机没有安装 `hb-sdk` skill。 |
-| `SKILL_OUTDATED` | 本机 `skillVersion` 与远端 latest 不一致。 |
-| `SDK_MISMATCH` | 当前 SDK 版本与远端 latest skill 声明的 SDK 版本不一致。 |
-| `REMOTE_UNAVAILABLE` | 无法读取公开 manifest，诊断失败且不会修改本地文件。 |
+| 状态                 | 含义                                                     |
+| -------------------- | -------------------------------------------------------- |
+| `OK`                 | SDK、远端 latest skill、本机 skill 全部匹配。            |
+| `SKILL_MISSING`      | 本机没有安装 `hb-sdk` skill。                            |
+| `SKILL_OUTDATED`     | 本机 `skillVersion` 与远端 latest 不一致。               |
+| `SDK_MISMATCH`       | 当前 SDK 版本与远端 latest skill 声明的 SDK 版本不一致。 |
+| `REMOTE_UNAVAILABLE` | 无法读取公开 manifest，诊断失败且不会修改本地文件。      |
 
 手动安装或刷新 skill：
 
@@ -311,7 +542,7 @@ Agent rules:
 
 ## 版本提醒
 
-`hb-sdk create`、`hb-sdk dev`、`hb-sdk login`、`hb-sdk login status`、`hb-sdk login clear` 会在命令成功执行后检查 npm registry 上 `@heybox/hb-sdk` 的 `latest` 版本。检查结果会缓存 24 小时；检查失败会静默跳过；`CI=true` 时会跳过检查，避免污染 CI 日志。`hb-sdk doctor` 不会附带版本提醒，避免把 skill 诊断输出和升级提示混在一起。本地可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用检查。
+`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` 禁用检查。
 
 ## Repository validation commands
 
@@ -346,11 +577,15 @@ npm run build
 npm run deploy
 ```
 
+## 依赖说明
+
+`@heybox/hb-sdk` 是小程序页面运行时会 import 的 SDK，因此模板把它放在 `dependencies`。Vite、TypeScript、Vitest 等只参与本地开发、测试或构建的工具放在 `devDependencies`。
+
 ## 开发模式
 
-- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP，需要时请在系统浏览器中打开同一个调试页后重试。
+- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面，也可以选择局域网网卡后用手机小黑盒 APP 扫码调试。手机需要与电脑处在同一局域网，并使用支持小程序调试壳的新版小黑盒 APP。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP，需要时请在系统浏览器中打开同一个调试页后重试。
 - `npm run build`：先执行 TypeScript 检查，再构建生产产物。
-- `npm run deploy`：构建并发布当前小程序。发布前需要先把 `package.json` 中的 `heybox.miniProgramId` 改成后台分配的真实小程序 id，并执行过 `npx hb-sdk login`。
+- `npm run deploy -- --release-note "..."`：构建、上传并提交当前小程序版本审核。部署前需要先把 `package.json` 中的 `heybox.miniProgramId` 改成后台分配的真实小程序 id，并执行过 `npx hb-sdk login`；默认审核通过后需在开放平台手动发布，如需审核通过后自动发布可追加 `--auto-publish`。
 
 ## 更多能力
 

package/skill/scripts/sync-references.mjs

@@ -202,6 +202,7 @@ const cliDevSection = [
   extractSection(cliGuide, '## 本地开发模式'),
   extractSection(cliGuide, '## Mock runtime 边界'),
 ].filter(Boolean).join('\n\n');
+const cliDeploySection = extractSection(cliGuide, '## 部署发布');
 const cliLoginSection = extractSection(cliGuide, '## CLI 登录态');
 const cliDoctorSection = extractSection(cliGuide, '## Agent Skill doctor');
 const cliUpdateSection = extractSection(cliGuide, '## 版本提醒');
@@ -294,6 +295,7 @@ files.set('cli.md', `${header('CLI reference', [
   ['Command surface', 'command-surface'],
   ['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'],
   ['CLI login cache', 'cli-login-cache'],
   ['Agent Skill doctor', 'agent-skill-doctor'],
   ['Update reminders', 'update-reminders'],
@@ -326,7 +328,21 @@ Agent rules:
 
 ${cliDevSection}
 
-Use \`hb-sdk dev\` for local browser SDK debugging. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container. If the mock host is open inside Codex, VSCode, or another embedded browser, ask the user to open the same debug page in the system browser before retrying because embedded browsers may block the \`heybox://\` protocol handoff.
+Use \`hb-sdk dev\` for local browser SDK debugging. 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. If the mock host is open inside Codex, VSCode, or another embedded browser, ask the user to open the same debug page in the system browser before retrying because embedded browsers may block the \`heybox://\` protocol handoff.
+
+## Deploy and backend operations
+
+${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 \`--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 \`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()\`.
 
 ## CLI login cache
 

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.3.3+skill.cb20a91e9529",
+  "skillVersion": "0.4.1+skill.702e134a243e",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.3.3",
-    "compatibility": "0.3.3"
+    "version": "0.4.1",
+    "compatibility": "0.4.1"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-cb20a91e95291420a1f1d1b8a1601bbf21ba8bcd4dac64265d0c033e009d9456"
+  "integrity": "sha256-702e134a243e9f6f9c11b9df1c5db45daebf2b98a270753a89b65afe5f52f7a2"
 }

package/types/index.d.ts

@@ -6,7 +6,7 @@ export type { MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPay
 export type { LoginPayload, LoginResult, MiniProgramAuthModule } from './modules/auth';
 export type { GetUserInfoPayload, GetUserInfoResult, MiniProgramUserInfo, MiniProgramUserInfoResult, MiniProgramUserModule, } from './modules/user';
 export type { MiniProgramScreenshotOptions, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareModule, MiniProgramShowShareMenuOptions, ScreenshotPayload, ScreenshotResult, ShowShareMenuPayload, ShowShareMenuResult, } from './modules/share';
-export type { GetWindowInfoPayload, GetWindowInfoResult, MiniProgramSafeArea, MiniProgramViewportModule, MiniProgramWindowInfoResult, } from './modules/viewport';
+export type { GetWindowInfoPayload, GetWindowInfoResult, MiniProgramNavigationBarForegroundStyle, MiniProgramSafeArea, MiniProgramSetNavigationBarStyleOptions, MiniProgramViewportModule, MiniProgramWindowInfoResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, } from './modules/viewport';
 export type { GetStoragePayload, GetStorageResult, MiniProgramStorageModule, SetStoragePayload, } from './modules/storage';
 export type { MiniProgramNetworkHeaders, MiniProgramNetworkModule, MiniProgramNetworkParams, MiniProgramNetworkRequestConfig, MiniProgramNetworkRequestMethod, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, NetworkRequestPayload, NetworkResponsePayload, } from './modules/network';
 import { off, on, ready } from './core/singleton';

package/types/miniapp-manifest/schema.d.ts

@@ -8,7 +8,8 @@ export interface ParseMiniappManifestResult {
     hadBom: boolean;
 }
 export declare function isValidMiniappManifestVersion(version: string): boolean;
-export declare function getMiniappManifestBuildWarning(version: string): string | undefined;
+export declare function validateMiniappPackageVersionForBuild(version: string): string;
+export declare function validateMiniappManifestVersion(version: unknown, sourceLabel?: string): string;
 export declare function renderMiniappManifest(manifest: MiniappManifest): string;
 export declare function parseMiniappManifestJson(raw: string, sourceLabel?: string): ParseMiniappManifestResult;
 export declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): string;