@heybox/hb-sdk 0.5.17 → 0.5.18

package/README.md

@@ -473,10 +473,27 @@ hb-sdk login --login-base-url https://login.test.xiaoheihe.cn
 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_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://127.0.1:8080 --release-note "本地后台联调"
 ```
 
-`--api-base-url` 优先于 `HB_SDK_API_BASE_URL`，影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`--login-base-url` 优先于 `HB_SDK_LOGIN_BASE_URL`，用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。仓库内开发可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置 `default_tag` 或 path-prefix 级 `special_tag`，给 Heybox 后台请求附加 `x-rylai-service-tag` header，并复用命中的 tag 追加 `special_tag` 请求参数，用于开发环境路由或灰度验证。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。`hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
+切换测试环境时往往需要同时配置后台 host、登录 host 和 service tag。为避免每条命令都重复书写这些 env/flag，CLI 支持加载 `.env.<name>` 预设：
+
+```bash
+# 在项目根准备 .env.test（可提交当团队默认，或 gitignore 仅本地保留）
+#   HB_SDK_API_BASE_URL=https://api.test.xiaoheihe.cn
+#   HB_SDK_LOGIN_BASE_URL=https://login.test.xiaoheihe.cn
+#   HB_SDK_SERVICE_TAG=my-test-tag
+
+hb-sdk remote deploy --env test --release-note "测试环境验证"   # 一次加载三项配置
+hb-sdk remote info --env test                                  # 复用同一预设
+HB_SDK_ENV=test hb-sdk remote versions                        # 环境变量形式，CI 友好
+hb-sdk remote deploy --env-file .env.local --release-note "本地联调"   # 显式指定文件路径
+hb-sdk remote deploy --env test --service-tag other-tag --release-note "灰度"   # 单项 flag 覆盖预设
+```
+
+`--env <name>` 会读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级高于 `--env`；两者也可通过 `HB_SDK_ENV=<name>` 触发。加载遵循 dotenv 惯例：不覆盖进程已有的同名变量，因此 CI 或命令行显式设置的值优先。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。`--verbose` 会打印生效的文件路径和被跳过的 key。
+
+`--api-base-url` 优先于 `HB_SDK_API_BASE_URL`，影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`--login-base-url` 优先于 `HB_SDK_LOGIN_BASE_URL`，用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。`--service-tag <tag>` 优先于 `HB_SDK_SERVICE_TAG`，给 Heybox 后台请求附加 `x-rylai-service-tag` header，并复用命中的 tag 追加 `special_tag` 请求参数，用于开发环境路由或灰度验证；仓库内开发也可继续在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置 path-prefix 级 `special_tag`。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。`hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
 
 ## hb-sdk remote 命令参考
 

package/dist/cli-chunks/{context-mav2gs13.cjs → context-CKJlNcSN.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var session = require('./session-BMSThs93.cjs');
+var session = require('./session-dRGPpyS1.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');

package/dist/cli-chunks/{create-CPIjDM-n.cjs → create-OZOIdeBz.cjs}

@@ -5,7 +5,7 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var require$$0 = require('fs');
 var require$$1 = require('path');
-var index = require('./index-Dor8wa6R.cjs');
+var index = require('./index-CsOcGUzF.cjs');
 require('node:module');
 require('os');
 require('readline');

package/dist/cli-chunks/{dev-Cr2u9ajy.cjs → dev-DXz8izSJ.cjs}

@@ -9,8 +9,8 @@ var node_url = require('node:url');
 var net = require('node:net');
 var node_http = require('node:http');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-Dor8wa6R.cjs');
-var context = require('./context-mav2gs13.cjs');
+var index = require('./index-CsOcGUzF.cjs');
+var context = require('./context-CKJlNcSN.cjs');
 require('node:process');
 require('node:buffer');
 require('node:util');
@@ -24,7 +24,7 @@ require('events');
 require('stream');
 require('buffer');
 require('util');
-require('./session-BMSThs93.cjs');
+require('./session-dRGPpyS1.cjs');
 require('node:crypto');
 require('fs');
 require('constants');

package/dist/cli-chunks/{doctor-mIgvLfLl.cjs → doctor-DjMSJoQ5.cjs}

@@ -4,7 +4,7 @@ var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var os = require('node:os');
 var path = require('node:path');
-var index = require('./index-Dor8wa6R.cjs');
+var index = require('./index-CsOcGUzF.cjs');
 require('node:module');
 require('path');
 require('os');

package/dist/cli-chunks/{index-DHWEoki_.cjs → index-Cl5HFTBW.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-Dor8wa6R.cjs');
+var index$2 = require('./index-CsOcGUzF.cjs');
 var require$$0$2 = require('fs');
 var require$$2$1 = require('crypto');
 var require$$1$2 = require('path');
 var require$$0$3 = require('assert');
 var require$$4$2 = require('events');
 var require$$1$1 = require('util');
-var context$1 = require('./context-mav2gs13.cjs');
+var context$1 = require('./context-CKJlNcSN.cjs');
 var require$$0$5 = require('net');
 var require$$0$4 = require('url');
 var require$$2$2 = require('http');

package/dist/cli-chunks/{index-Dor8wa6R.cjs → index-CsOcGUzF.cjs}

@@ -234,19 +234,19 @@ function requireArgument () {
 
 var command = {};
 
-const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-Dor8wa6R.cjs', document.baseURI).href)));
+const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-CsOcGUzF.cjs', document.baseURI).href)));
 function __require$4() { return require$5("node:events"); }
 
-const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-Dor8wa6R.cjs', document.baseURI).href)));
+const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-CsOcGUzF.cjs', document.baseURI).href)));
 function __require$3() { return require$4("node:child_process"); }
 
-const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-Dor8wa6R.cjs', document.baseURI).href)));
+const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-CsOcGUzF.cjs', document.baseURI).href)));
 function __require$2() { return require$3("node:path"); }
 
-const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-Dor8wa6R.cjs', document.baseURI).href)));
+const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-CsOcGUzF.cjs', document.baseURI).href)));
 function __require$1() { return require$2("node:fs"); }
 
-const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-Dor8wa6R.cjs', document.baseURI).href)));
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-CsOcGUzF.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -13095,8 +13095,228 @@ function readErrorMessage(error, options = {}) {
     return String(error);
 }
 
+/**
+ * 极简 .env 文件解析器。
+ *
+ * 只支持 hb-sdk CLI 需要的最小语义：KEY=VALUE、空行、`#` 注释、单/双引号包裹值。
+ * 不做变量插值，不展开 shell 转义，避免引入额外依赖。
+ */
+/**
+ * 解析 .env 文件内容为 key/value 记录，保持原始出现顺序的 key 列表。
+ */
+function parseDotenvFile(content) {
+    const entries = {};
+    const keys = [];
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = stripInlineComment(rawLine).trim();
+        if (!line || line.startsWith('#')) {
+            continue;
+        }
+        const equalsIndex = line.indexOf('=');
+        if (equalsIndex <= 0) {
+            continue;
+        }
+        const key = line.slice(0, equalsIndex).trim();
+        if (!isValidEnvKey(key)) {
+            continue;
+        }
+        const rawValue = line.slice(equalsIndex + 1).trim();
+        const value = unquoteDotenvValue(rawValue);
+        if (!Object.prototype.hasOwnProperty.call(entries, key)) {
+            keys.push(key);
+        }
+        entries[key] = value;
+    }
+    return { entries, keys };
+}
+function stripInlineComment(line) {
+    // 仅处理未被引号包裹的行内注释，避免误伤值里的 #。
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < line.length; i += 1) {
+        const char = line[i];
+        if (char === "'" && !inDouble) {
+            inSingle = !inSingle;
+        }
+        else if (char === '"' && !inSingle) {
+            inDouble = !inDouble;
+        }
+        else if (char === '#' && !inSingle && !inDouble) {
+            return line.slice(0, i);
+        }
+    }
+    return line;
+}
+function unquoteDotenvValue(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if (first === '"' && last === '"') {
+            return value.slice(1, -1).replace(/\\(["\\$])/g, '$1');
+        }
+        if (first === "'" && last === "'") {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+function isValidEnvKey(key) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
+}
+
+const DEFAULT_READ_FILE = (path) => fs$1.readFileSync(path, 'utf8');
+function resolveEnvPresetFilePath(argv, env = process.env, cwd = process.cwd()) {
+    const explicit = readEnvFileArgFromArgv(argv);
+    if (explicit) {
+        return path.resolve(cwd, explicit);
+    }
+    const name = readEnvNameArgFromArgv(argv) ?? env.HB_SDK_ENV;
+    if (name) {
+        return path.resolve(cwd, `.env.${name}`);
+    }
+    return undefined;
+}
+function loadEnvPreset(argv, options = {}) {
+    const targetEnv = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const readFile = options.readFile ?? DEFAULT_READ_FILE;
+    const filePath = resolveEnvPresetFilePath(argv, targetEnv, cwd);
+    if (!filePath) {
+        return { filePath: undefined, appliedKeys: [], skippedKeys: [] };
+    }
+    let content;
+    try {
+        content = readFile(filePath);
+    }
+    catch {
+        // 文件不存在或不可读时静默跳过，与 dotenv 默认行为一致。
+        return { filePath, appliedKeys: [], skippedKeys: [] };
+    }
+    const { entries } = parseDotenvFile(content);
+    const appliedKeys = [];
+    const skippedKeys = [];
+    for (const [key, value] of Object.entries(entries)) {
+        if (targetEnv[key] !== undefined && targetEnv[key] !== '') {
+            skippedKeys.push(key);
+            continue;
+        }
+        targetEnv[key] = value;
+        appliedKeys.push(key);
+    }
+    return { filePath, appliedKeys, skippedKeys };
+}
+/**
+ * 从 argv 中提取 `--env-file <path>` 的值。
+ * 支持 `--env-file path`、`--env-file=path` 两种写法。
+ */
+function readEnvFileArgFromArgv(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--env-file') {
+            return argv[i + 1];
+        }
+        if (arg?.startsWith('--env-file=')) {
+            return arg.slice('--env-file='.length);
+        }
+    }
+    return undefined;
+}
+/**
+ * 从 argv 中提取 `--env <name>` 的值。
+ * 支持 `--env name`、`--env=name` 两种写法。
+ */
+function readEnvNameArgFromArgv(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--env') {
+            return argv[i + 1];
+        }
+        if (arg?.startsWith('--env=')) {
+            return arg.slice('--env='.length);
+        }
+    }
+    return undefined;
+}
+
+const globalHeyboxCliRequestConfig = {};
+function configureHeyboxCliRequestConfig(config) {
+    const normalized = normalizeHeyboxRylaiServiceTagConfig(config);
+    if (normalized.default_tag) {
+        globalHeyboxCliRequestConfig.default_tag = normalized.default_tag;
+    }
+    else {
+        delete globalHeyboxCliRequestConfig.default_tag;
+    }
+    if (normalized.special_tag) {
+        globalHeyboxCliRequestConfig.special_tag = normalized.special_tag;
+    }
+    else {
+        delete globalHeyboxCliRequestConfig.special_tag;
+    }
+}
+function readHeyboxCliRequestConfig() {
+    return normalizeHeyboxRylaiServiceTagConfig(globalHeyboxCliRequestConfig);
+}
+/**
+ * 当 tag 为非空字符串时，把它设为 CLI 全局 default_tag；为空时不改动现有配置，
+ * 避免清掉 env 预设阶段已注入的值。
+ */
+function applyServiceTagIfNeeded(tag) {
+    const normalized = normalizeHeyboxRylaiServiceTag(tag);
+    if (!normalized) {
+        return;
+    }
+    configureHeyboxCliRequestConfig({ default_tag: normalized });
+}
+function resolveHeyboxRylaiServiceTag(pathWithQuery, config = readHeyboxCliRequestConfig()) {
+    const normalized = normalizeHeyboxRylaiServiceTagConfig(config);
+    const pathname = pathWithQuery ? getPathname(pathWithQuery) : '';
+    const specialTag = normalized.special_tag;
+    if (pathname && specialTag?.path_prefix_list.some((prefix) => pathname.startsWith(prefix))) {
+        return specialTag.tag_name;
+    }
+    return normalized.default_tag;
+}
+function normalizeHeyboxRylaiServiceTagConfig(config) {
+    const defaultTag = normalizeHeyboxRylaiServiceTag(config.default_tag);
+    const specialTagName = normalizeHeyboxRylaiServiceTag(config.special_tag?.tag_name);
+    const pathPrefixList = config.special_tag?.path_prefix_list?.filter(isValidPathPrefix) || [];
+    return {
+        ...(defaultTag ? { default_tag: defaultTag } : {}),
+        ...(specialTagName && pathPrefixList.length
+            ? {
+                special_tag: {
+                    tag_name: specialTagName,
+                    path_prefix_list: pathPrefixList,
+                },
+            }
+            : {}),
+    };
+}
+function normalizeHeyboxRylaiServiceTag(value) {
+    const tag = String(value ?? '').trim();
+    if (!tag) {
+        return undefined;
+    }
+    if (/[\r\n]/.test(tag)) {
+        throw new Error('x-rylai-service-tag 不允许包含换行符');
+    }
+    return tag;
+}
+function isValidPathPrefix(value) {
+    return typeof value === 'string' && value.startsWith('/') && !/[\r\n]/.test(value);
+}
+function getPathname(pathWithQuery) {
+    try {
+        return new URL(pathWithQuery, 'https://api.xiaoheihe.cn').pathname;
+    }
+    catch {
+        return '';
+    }
+}
+
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.5.17';
+const BUILT_CLI_VERSION = '0.5.18';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13134,7 +13354,9 @@ async function runCli(options = {}) {
     const processLike = options.process ?? process;
     const argv = options.argv ?? process.argv;
     const verbose = hasVerboseArg(argv);
+    const logger = resolveStandaloneLogger(options, verbose);
     try {
+        preloadCliEnvPreset(argv, { logger });
         await createCliProgram(options).parseAsync(argv);
     }
     catch (error) {
@@ -13143,7 +13365,7 @@ async function runCli(options = {}) {
             return;
         }
         if (!(error instanceof CommanderError)) {
-            (options.printError ?? printError)(error, { logger: resolveStandaloneLogger(options, verbose), verbose });
+            (options.printError ?? printError)(error, { logger, verbose });
         }
         processLike.exit(error instanceof CommanderError ? error.exitCode : 1);
     }
@@ -13167,6 +13389,8 @@ function createCliProgram(overrides = {}) {
         .description('hb-sdk developer tools')
         .version(getCliVersion())
         .option('-v, --verbose', '输出详细调试信息')
+        .option('--env <name>', '加载项目根下 .env.<name> 预设，把其中的 HB_SDK_* 变量注入当前进程（不覆盖已有值）')
+        .option('--env-file <path>', '显式指定 .env 文件路径，优先级高于 --env')
         .showHelpAfterError()
         .exitOverride();
     installVersionUpdateReminder(program, handlers.printUpdateReminder, resolveLogger);
@@ -13222,7 +13446,8 @@ function addRemotePublicOptions(command) {
         .option('--json', '以 JSON 格式输出 remote 命令结果')
         .option('--api-base-url <url>', 'Heybox 后台 API origin，默认读取 HB_SDK_API_BASE_URL 或生产地址')
         .option('--login-base-url <url>', '校验 CLI 登录态使用的登录 origin，默认读取 HB_SDK_LOGIN_BASE_URL 或生产地址')
-        .option('--allow-unsafe-api-base-url', '允许向非 Heybox HTTPS API origin 发送登录态，仅限本地调试'));
+        .option('--allow-unsafe-api-base-url', '允许向非 Heybox HTTPS API origin 发送登录态，仅限本地调试')
+        .option('--service-tag <tag>', '给 Heybox 后台请求附加 x-rylai-service-tag，默认读取 HB_SDK_SERVICE_TAG'));
 }
 function installRemoteCommands(program, handlers, resolveLogger) {
     const remote = addRemotePublicOptions(program.command('remote').description('管理当前项目绑定的远程 Heybox 工坊小程序'));
@@ -13359,6 +13584,7 @@ function readRemoteCommonOptions(command) {
         apiBaseUrl: readStringOption(options.apiBaseUrl),
         json: Boolean(options.json),
         loginBaseUrl: readStringOption(options.loginBaseUrl),
+        serviceTag: readStringOption(options.serviceTag),
         verbose: Boolean(options.verbose),
     };
 }
@@ -13413,31 +13639,31 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-B63QgKed.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-Ct-46gLx.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-B63QgKed.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-Ct-46gLx.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-B63QgKed.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-Ct-46gLx.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-CPIjDM-n.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-OZOIdeBz.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-Cr2u9ajy.cjs'); });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DXz8izSJ.cjs'); });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-mIgvLfLl.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-DjMSJoQ5.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-Dksa9s5M.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-C77axNSw.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {
@@ -13495,6 +13721,25 @@ function readCommandFromActionArgs(args) {
     const lastArg = args[args.length - 1];
     return lastArg instanceof Command ? lastArg : undefined;
 }
+/**
+ * 在 commander 解析前加载 .env 预设，把其中的 HB_SDK_* 变量注入 process.env（不覆盖已有值），
+ * 并把 HB_SDK_SERVICE_TAG 同步到 CLI 全局请求配置。
+ * 这样后续 resolveHeyboxApiBaseUrl / resolveHeyboxLoginBaseUrl 读 process.env 时即可拿到预设值。
+ */
+function preloadCliEnvPreset(argv, options = {}) {
+    const result = loadEnvPreset(argv);
+    if (!result.filePath) {
+        return;
+    }
+    options.logger?.debug(`已加载 env 预设: ${result.filePath}`);
+    if (result.appliedKeys.length) {
+        options.logger?.debug(`env 预设生效: ${result.appliedKeys.join(', ')}`);
+    }
+    if (result.skippedKeys.length) {
+        options.logger?.debug(`env 预设跳过（已有值）: ${result.skippedKeys.join(', ')}`);
+    }
+    applyServiceTagIfNeeded(process.env.HB_SDK_SERVICE_TAG);
+}
 function parsePositivePort(value) {
     const parsed = Number(value);
     if (!Number.isInteger(parsed) || parsed <= 0) {
@@ -13516,6 +13761,7 @@ exports.HB_SDK_SKILL_INDEX_URL = HB_SDK_SKILL_INDEX_URL;
 exports.HB_SDK_SKILL_INSTALL_COMMAND = HB_SDK_SKILL_INSTALL_COMMAND;
 exports.HB_SDK_SKILL_NAME = HB_SDK_SKILL_NAME;
 exports.HB_SDK_SKILL_SOURCE = HB_SDK_SKILL_SOURCE;
+exports.applyServiceTagIfNeeded = applyServiceTagIfNeeded;
 exports.commonjsGlobal = commonjsGlobal;
 exports.createCliLogger = createCliLogger;
 exports.createCliProgram = createCliProgram;
@@ -13525,4 +13771,5 @@ exports.readErrorMessage = readErrorMessage;
 exports.requireEnvPaths = requireEnvPaths;
 exports.requireOnetime = requireOnetime;
 exports.requireSafeBuffer = requireSafeBuffer;
+exports.resolveHeyboxRylaiServiceTag = resolveHeyboxRylaiServiceTag;
 exports.runCli = runCli;

package/dist/cli-chunks/{login-B63QgKed.cjs → login-Ct-46gLx.cjs}

@@ -3,9 +3,9 @@
 var promises = require('node:readline/promises');
 var node_crypto = require('node:crypto');
 var node_http = require('node:http');
-var session = require('./session-BMSThs93.cjs');
+var session = require('./session-dRGPpyS1.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-Dor8wa6R.cjs');
+var index = require('./index-CsOcGUzF.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{remote-Dksa9s5M.cjs → remote-C77axNSw.cjs}

@@ -1,26 +1,26 @@
 'use strict';
 
 var promises = require('node:readline/promises');
-var session = require('./session-BMSThs93.cjs');
+var index = require('./index-CsOcGUzF.cjs');
+var session = require('./session-dRGPpyS1.cjs');
 var childProcess = require('node:child_process');
 var fs = require('node:fs');
 var fs$1 = require('node:fs/promises');
 var path = require('node:path');
-var context = require('./context-mav2gs13.cjs');
-var index = require('./index-Dor8wa6R.cjs');
-require('node:crypto');
-require('fs');
-require('constants');
-require('stream');
-require('util');
-require('assert');
-require('path');
+var context = require('./context-CKJlNcSN.cjs');
 require('node:module');
+require('path');
 require('os');
 require('readline');
 require('tty');
+require('assert');
 require('events');
+require('stream');
 require('buffer');
+require('util');
+require('node:crypto');
+require('fs');
+require('constants');
 
 function isValidMiniappManifestVersion(version) {
     return getMiniappManifestVersionError(version) === undefined;
@@ -250,7 +250,7 @@ async function createDefaultCosClient(uploadToken) {
     };
 }
 async function loadCosConstructor() {
-    const cosModule = await Promise.resolve().then(function () { return require('./index-DHWEoki_.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-Cl5HFTBW.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {
@@ -839,6 +839,7 @@ async function runRemoteDeployCommand(options, runtime) {
     return finishRemoteCommand(options, runtime, output);
 }
 async function createRemoteCommandContext(options, runtime) {
+    index.applyServiceTagIfNeeded(options.serviceTag);
     const logger = resolveRemoteLogger(options, runtime);
     const environment = await context.resolveRemoteEnvironment({
         allowUnsafeApiBaseUrl: options.allowUnsafeApiBaseUrl,

package/dist/cli-chunks/{session-BMSThs93.cjs → session-dRGPpyS1.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-Dor8wa6R.cjs');
+var index = require('./index-CsOcGUzF.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');
@@ -67,57 +67,6 @@ function isTruthyEnvFlag(value) {
         .toLowerCase());
 }
 
-const globalHeyboxCliRequestConfig = {};
-function readHeyboxCliRequestConfig() {
-    return normalizeHeyboxRylaiServiceTagConfig(globalHeyboxCliRequestConfig);
-}
-function resolveHeyboxRylaiServiceTag(pathWithQuery, config = readHeyboxCliRequestConfig()) {
-    const normalized = normalizeHeyboxRylaiServiceTagConfig(config);
-    const pathname = pathWithQuery ? getPathname(pathWithQuery) : '';
-    const specialTag = normalized.special_tag;
-    if (pathname && specialTag?.path_prefix_list.some((prefix) => pathname.startsWith(prefix))) {
-        return specialTag.tag_name;
-    }
-    return normalized.default_tag;
-}
-function normalizeHeyboxRylaiServiceTagConfig(config) {
-    const defaultTag = normalizeHeyboxRylaiServiceTag(config.default_tag);
-    const specialTagName = normalizeHeyboxRylaiServiceTag(config.special_tag?.tag_name);
-    const pathPrefixList = config.special_tag?.path_prefix_list?.filter(isValidPathPrefix) || [];
-    return {
-        ...(defaultTag ? { default_tag: defaultTag } : {}),
-        ...(specialTagName && pathPrefixList.length
-            ? {
-                special_tag: {
-                    tag_name: specialTagName,
-                    path_prefix_list: pathPrefixList,
-                },
-            }
-            : {}),
-    };
-}
-function normalizeHeyboxRylaiServiceTag(value) {
-    const tag = String(value ?? '').trim();
-    if (!tag) {
-        return undefined;
-    }
-    if (/[\r\n]/.test(tag)) {
-        throw new Error('x-rylai-service-tag 不允许包含换行符');
-    }
-    return tag;
-}
-function isValidPathPrefix(value) {
-    return typeof value === 'string' && value.startsWith('/') && !/[\r\n]/.test(value);
-}
-function getPathname(pathWithQuery) {
-    try {
-        return new URL(pathWithQuery, 'https://api.xiaoheihe.cn').pathname;
-    }
-    catch {
-        return '';
-    }
-}
-
 const SIGN_VERSION = '999.0.4';
 const SIGN_CHARSET = 'AB45STUVWZEFGJ6CH01D237IXYPQRKLMN89';
 function createHeyboxOpenPlatformSignParams(pathname, options = {}) {
@@ -217,7 +166,7 @@ function resolveHeyboxId(session) {
         ?.slice('heybox_id='.length);
 }
 function createHeyboxAuthHeaders(session, options = {}) {
-    const serviceTag = resolveHeyboxRylaiServiceTag(options.pathWithQuery);
+    const serviceTag = index.resolveHeyboxRylaiServiceTag(options.pathWithQuery);
     return {
         Cookie: session.cookieHeader,
         Referer: HEYBOX_WEB_REFERER,
@@ -227,7 +176,7 @@ function createHeyboxAuthHeaders(session, options = {}) {
 }
 function createHeyboxRequestContext(session, options = {}) {
     const heyboxId = resolveHeyboxId(session);
-    const serviceTag = resolveHeyboxRylaiServiceTag(options.pathWithQuery);
+    const serviceTag = index.resolveHeyboxRylaiServiceTag(options.pathWithQuery);
     return {
         baseUrl: HEYBOX_API_BASE_URL,
         headers: createHeyboxAuthHeaders(session, options),

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./cli-chunks/index-Dor8wa6R.cjs');
+var index = require('./cli-chunks/index-CsOcGUzF.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.5.17",
+  "version": "0.5.18",
   "description": "",
   "exports": {
     ".": {

package/skill/references/cli.md

@@ -169,10 +169,27 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 
 默认发布策略是 `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` 影响 `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_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`，优先用 `--service-tag <tag>` 或 `HB_SDK_SERVICE_TAG`；path-prefix 级 `special_tag` 仍可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。
 
 `hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
 
+切换测试环境时往往需要同时配置后台 host、登录 host 和 service tag。CLI 支持加载 `.env.<name>` 预设，把其中的 `HB_SDK_*` 变量一次性注入当前进程（不覆盖已有值）：`--env <name>` 读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级更高，也可用 `HB_SDK_ENV=<name>` 触发。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。
+
+```bash
+# 项目根准备 .env.test
+#   HB_SDK_API_BASE_URL=https://api.test.xiaoheihe.cn
+#   HB_SDK_LOGIN_BASE_URL=https://login.test.xiaoheihe.cn
+#   HB_SDK_SERVICE_TAG=my-test-tag
+
+hb-sdk remote deploy --env test --release-note "测试环境验证"
+hb-sdk remote info --env test
+HB_SDK_ENV=test hb-sdk remote versions
+hb-sdk remote deploy --env-file .env.local --release-note "本地联调"
+hb-sdk remote deploy --env test --service-tag other-tag --release-note "灰度"   # 单项 flag 覆盖预设
+```
+
+`--env-file` 优先于 `--env`，`--service-tag` / `--api-base-url` / `--login-base-url` 优先于 `.env` 预设注入的同名变量，而预设又不会覆盖进程已有的环境变量，因此优先级为 flag > 进程 env > `.env` 预设 > 默认值。
+
 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:

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.5.17+skill.3845db204172",
+  "skillVersion": "0.5.17+skill.0ad061ac9da8",
   "sdk": {
     "package": "@heybox/hb-sdk",
     "version": "0.5.17",
     "compatibility": "0.5.17"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-3845db20417281f2c7a1edf162cb4d081113b8c28a0e0c8d1e69f445f1c5389f"
+  "integrity": "sha256-0ad061ac9da821bfea0db71d30404999c1bd3eb5fcddfb0c22211bd9939db2ae"
 }