@heybox/hb-sdk 0.8.4 → 0.9.0-alpha.0

package/dist/cli-chunks/{doctor-DImHJjzI.cjs → doctor-PE_MhGBX.cjs}

@@ -3,7 +3,7 @@
 var fs = require('node:fs/promises');
 var os = require('node:os');
 var path = require('node:path');
-var index = require('./index-CO8AEaXW.cjs');
+var index = require('./index-Dd_eGaDz.cjs');
 require('node:module');
 require('node:fs');
 require('path');

package/dist/cli-chunks/{index-CbDWlPpw.cjs → index-CeA8xI0T.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-CO8AEaXW.cjs');
+var index$2 = require('./index-Dd_eGaDz.cjs');
 var require$$0$3 = require('fs');
 var require$$0$2 = require('crypto');
 var require$$1$2 = require('path');
 var require$$0$5 = require('assert');
 var require$$0$4 = require('events');
 var require$$1$1 = require('util');
-var runtimePermissionEnv = require('./runtime-permission-env-9GWrfOTi.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-DR89buKQ.cjs');
 var require$$0$7 = require('net');
 var require$$0$6 = require('url');
 var require$$2$1 = require('http');

package/dist/cli-chunks/{index-CO8AEaXW.cjs → index-Dd_eGaDz.cjs}

@@ -235,19 +235,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-CO8AEaXW.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-Dd_eGaDz.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-CO8AEaXW.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-Dd_eGaDz.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-CO8AEaXW.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-Dd_eGaDz.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-CO8AEaXW.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-Dd_eGaDz.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-CO8AEaXW.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-Dd_eGaDz.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -12942,6 +12942,110 @@ function defaultStreamForLevel(level) {
     return level === 'error' || level === 'warn' || level === 'debug' ? 'stderr' : 'stdout';
 }
 
+class CliError extends Error {
+    httpStatus;
+    verboseMessage;
+    constructor(message, verboseMessage, options = {}) {
+        super(message);
+        this.name = 'CliError';
+        this.httpStatus = options.httpStatus;
+        this.verboseMessage = verboseMessage;
+    }
+}
+/**
+ * 网关限流错误（HTTP 403/429）。
+ *
+ * 与通用 `CliError` 分开，调用方才能区分「被限流」和「普通失败」：限流走 30s 起、
+ * 上限 300s 的退避，并且必须提示开发者不要反复重启。
+ */
+class CliRateLimitedError extends CliError {
+    retryAfterMs;
+    gatewayMessage;
+    constructor(message, options) {
+        super(message, options.verboseMessage, { httpStatus: options.httpStatus });
+        this.name = 'CliRateLimitedError';
+        this.retryAfterMs = options.retryAfterMs;
+        this.gatewayMessage = options.gatewayMessage ?? '';
+    }
+    /**
+     * 转成可下发给调试页/宿主页的加性状态字段。
+     *
+     * 只有正数 `retryAfterMs` 才会带上时长（并据此给出 `untilTs`）；缺失或非正数一律表示
+     * 「网关没有给出时长」，由消费方回落各自的默认窗口。这样下游不需要为 `0` 维护一套
+     * 「立即可重试」的特殊语义，也就不会出现「宿主页立即重连、CLI 仍在压制」的不一致。
+     */
+    toRateLimitState(now = Date.now()) {
+        const retryAfterMs = this.retryAfterMs;
+        return {
+            limited: true,
+            ...(retryAfterMs === undefined || retryAfterMs <= 0
+                ? {}
+                : { retryAfterMs, untilTs: now + retryAfterMs }),
+            ...(this.gatewayMessage ? { message: this.gatewayMessage } : {}),
+        };
+    }
+}
+/** 从任意错误中读取限流状态；非限流错误返回 null。 */
+function readCliRateLimitState(error, now = Date.now()) {
+    return error instanceof CliRateLimitedError ? error.toRateLimitState(now) : null;
+}
+/** 由已解析的限流状态还原错误，供缓存命中的降级路径继续走退避与提示。 */
+function createCliRateLimitedErrorFromState(state) {
+    return new CliRateLimitedError(state.message ?? 'Heybox API 已被网关限流', {
+        httpStatus: 429,
+        ...(state.retryAfterMs === undefined ? {} : { retryAfterMs: state.retryAfterMs }),
+        ...(state.message ? { gatewayMessage: state.message } : {}),
+    });
+}
+/** 面向开发者的限流提示文案；没有可用的等待时长时不给出具体秒数。 */
+function formatCliRateLimitHint(state) {
+    const retryAfterMs = state.retryAfterMs;
+    const seconds = retryAfterMs === undefined || retryAfterMs <= 0 ? undefined : Math.max(1, Math.round(retryAfterMs / 1000));
+    const pause = seconds === undefined ? '已暂停刷新' : `已暂停刷新（预计 ${seconds} 秒后恢复）`;
+    return `已被网关限流，${pause}，请勿反复重启。`;
+}
+function printError(error, options = {}) {
+    const logger = options.logger ?? createCliLogger({ verbose: options.verbose });
+    const message = readErrorMessage(error);
+    logger.error(message);
+    if (options.verbose && error instanceof CliError && error.verboseMessage && error.verboseMessage !== message) {
+        logger.debug(error.verboseMessage);
+    }
+}
+function readErrorMessage(error, options = {}) {
+    if (options.verbose && error instanceof CliError && error.verboseMessage) {
+        return error.verboseMessage;
+    }
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+function readRedactedErrorMessage(error, options = {}) {
+    return redactSensitiveUrls(readErrorMessage(error, options));
+}
+function redactSensitiveUrls(message) {
+    return message.replace(/https?:\/\/[^\s<>"'`]+/gi, (rawUrl) => {
+        try {
+            const url = new URL(rawUrl);
+            url.username = '';
+            url.password = '';
+            for (const key of url.searchParams.keys()) {
+                if (/(?:authorization|cookie|password|passwd|pkey|secret|session|token)/i.test(key)) {
+                    url.searchParams.set(key, '[REDACTED]');
+                }
+            }
+            if (url.hash) {
+                url.hash = '#[REDACTED]';
+            }
+            return url.toString();
+        }
+        catch {
+            return '[REDACTED_URL]';
+        }
+    });
+}
+
 const UPDATE_CHECK_CACHE_VERSION = 1;
 const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_TIMEOUT_MS = 1500;
@@ -12971,6 +13075,41 @@ async function printUpdateReminder(options = {}) {
         // Version checks must never affect the actual hb-sdk command.
     }
 }
+/**
+ * 限流强提示。
+ *
+ * 老版本 CLI 已被安装到开发者本机，无法强制升级，只能在限流时明确提示：
+ * 先说明限流与暂停刷新，再引导升级到已带缓存的版本。
+ */
+async function printRateLimitUpgradeHint(options = {}) {
+    const logger = options.logger ??
+        createCliLogger({
+            stderr: options.stderr,
+            stdout: options.output,
+        });
+    const stream = options.stream ?? (options.output ? 'stdout' : 'stderr');
+    let reminder = null;
+    try {
+        reminder = await getUpdateReminder(options);
+    }
+    catch {
+        // 升级检查失败不能吞掉限流提示本身。
+    }
+    logger.warn(formatRateLimitUpgradeHint({
+        ...(options.gatewayMessage ? { gatewayMessage: options.gatewayMessage } : {}),
+        ...(options.retryAfterMs === undefined ? {} : { retryAfterMs: options.retryAfterMs }),
+        ...(reminder ? { reminder } : {}),
+    }), { stream });
+}
+/** 限流提示 + 升级引导文案；`reminder` 缺失时只保留限流与升级命令。 */
+function formatRateLimitUpgradeHint(input) {
+    const rateLimitHint = formatCliRateLimitHint(input.retryAfterMs === undefined ? {} : { retryAfterMs: input.retryAfterMs });
+    const upgradeHint = input.reminder
+        ? formatUpdateReminder(input.reminder)
+        : `请升级 ${HB_SDK_PACKAGE_NAME} 以获得 Dev Context 结果缓存与指数退避：npm i -D ${HB_SDK_PACKAGE_NAME}@latest`;
+    const gatewayHint = input.gatewayMessage ? `网关原文：${input.gatewayMessage}` : '';
+    return [rateLimitHint, gatewayHint, upgradeHint].filter(Boolean).join(' ');
+}
 async function getUpdateReminder(options = {}) {
     if (isUpdateCheckDisabled(options.env ?? process.env)) {
         return null;
@@ -13187,58 +13326,6 @@ async function pathExists$1(filePath) {
     }
 }
 
-class CliError extends Error {
-    httpStatus;
-    verboseMessage;
-    constructor(message, verboseMessage, options = {}) {
-        super(message);
-        this.name = 'CliError';
-        this.httpStatus = options.httpStatus;
-        this.verboseMessage = verboseMessage;
-    }
-}
-function printError(error, options = {}) {
-    const logger = options.logger ?? createCliLogger({ verbose: options.verbose });
-    const message = readErrorMessage(error);
-    logger.error(message);
-    if (options.verbose && error instanceof CliError && error.verboseMessage && error.verboseMessage !== message) {
-        logger.debug(error.verboseMessage);
-    }
-}
-function readErrorMessage(error, options = {}) {
-    if (options.verbose && error instanceof CliError && error.verboseMessage) {
-        return error.verboseMessage;
-    }
-    if (error instanceof Error && error.message) {
-        return error.message;
-    }
-    return String(error);
-}
-function readRedactedErrorMessage(error, options = {}) {
-    return redactSensitiveUrls(readErrorMessage(error, options));
-}
-function redactSensitiveUrls(message) {
-    return message.replace(/https?:\/\/[^\s<>"'`]+/gi, (rawUrl) => {
-        try {
-            const url = new URL(rawUrl);
-            url.username = '';
-            url.password = '';
-            for (const key of url.searchParams.keys()) {
-                if (/(?:authorization|cookie|password|passwd|pkey|secret|session|token)/i.test(key)) {
-                    url.searchParams.set(key, '[REDACTED]');
-                }
-            }
-            if (url.hash) {
-                url.hash = '#[REDACTED]';
-            }
-            return url.toString();
-        }
-        catch {
-            return '[REDACTED_URL]';
-        }
-    });
-}
-
 /**
  * 极简 .env 文件解析器。
  *
@@ -13467,7 +13554,7 @@ function getPathname(pathWithQuery) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.8.4';
+const BUILT_CLI_VERSION = '0.9.0-alpha.0';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13826,39 +13913,39 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-DbbuUauB.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-5FPaFRi0.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-DbbuUauB.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-5FPaFRi0.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-DbbuUauB.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-5FPaFRi0.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunBuildCommand = async (...args) => {
-    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-DgV-or9j.cjs'); });
+    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-Dv5vWsBh.cjs'); });
     return runBuildCommand(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-BjJ6U5qS.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-BtZUsxJd.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-hIWir4Bp.cjs'); }).then(function (n) { return n.dev; });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-tAThflC6.cjs'); }).then(function (n) { return n.dev; });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-DImHJjzI.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-PE_MhGBX.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunSkillInstallCommand = async (...args) => {
-    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-BZFvZvOT.cjs'); });
+    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-C5EoUf2T.cjs'); });
     return runSkillInstallCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-CWeqNVk_.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-DCHqFvmB.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {
@@ -13951,15 +14038,20 @@ function parseNonNegativeInteger(value) {
 }
 
 exports.CliError = CliError;
+exports.CliRateLimitedError = CliRateLimitedError;
 exports.HB_SDK_PACKAGE_NAME = HB_SDK_PACKAGE_NAME;
 exports.HB_SDK_SKILL_NAME = HB_SDK_SKILL_NAME;
 exports.applyServiceTagIfNeeded = applyServiceTagIfNeeded;
 exports.commonjsGlobal = commonjsGlobal;
 exports.createCliLogger = createCliLogger;
 exports.createCliProgram = createCliProgram;
+exports.createCliRateLimitedErrorFromState = createCliRateLimitedErrorFromState;
 exports.createSkillContentHash = createSkillContentHash;
 exports.envPaths = envPaths;
+exports.formatCliRateLimitHint = formatCliRateLimitHint;
 exports.getDefaultExportFromCjs = getDefaultExportFromCjs;
+exports.printRateLimitUpgradeHint = printRateLimitUpgradeHint;
+exports.readCliRateLimitState = readCliRateLimitState;
 exports.readErrorMessage = readErrorMessage;
 exports.readRedactedErrorMessage = readRedactedErrorMessage;
 exports.requireEnvPaths = requireEnvPaths;

package/dist/cli-chunks/{index.esm-COo1T4B1.cjs → index.esm-Bw3R5BAL.cjs}

@@ -11,8 +11,8 @@ var require$$0$4 = require('url');
 var require$$0 = require('zlib');
 var require$$0$1 = require('buffer');
 var require$$1 = require('util');
-var index = require('./index-CO8AEaXW.cjs');
-var dev = require('./dev-hIWir4Bp.cjs');
+var index = require('./index-Dd_eGaDz.cjs');
+var dev = require('./dev-tAThflC6.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');
@@ -23,12 +23,12 @@ require('node:crypto');
 require('readline');
 require('tty');
 require('assert');
-require('./context-DlcETCGM.cjs');
-require('./runtime-permission-env-9GWrfOTi.cjs');
-require('./version-Bk5ehprU.cjs');
+require('./context-B15FzPf9.cjs');
+require('./runtime-permission-env-DR89buKQ.cjs');
+require('./version-CJ7rfbl-.cjs');
 require('node:async_hooks');
 require('sharp');
-require('./session-CRiCQkg-.cjs');
+require('./session-BiT-5VHK.cjs');
 require('fs');
 require('constants');
 require('node:os');
@@ -42,7 +42,7 @@ require('node:buffer');
 require('node:url');
 require('node:util');
 require('node:child_process');
-require('./project-vite-Dw04aEsD.cjs');
+require('./project-vite-ckDtbYtt.cjs');
 require('node:zlib');
 
 var bufferUtil = {exports: {}};

package/dist/cli-chunks/{login-DbbuUauB.cjs → login-5FPaFRi0.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-CRiCQkg-.cjs');
+var session = require('./session-BiT-5VHK.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-CO8AEaXW.cjs');
+var index = require('./index-Dd_eGaDz.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{project-vite-Dw04aEsD.cjs → project-vite-ckDtbYtt.cjs}

@@ -5,7 +5,7 @@ var fs$1 = require('node:fs/promises');
 var node_module = require('node:module');
 var path = require('node:path');
 var node_url = require('node:url');
-var index = require('./index-CO8AEaXW.cjs');
+var index = require('./index-Dd_eGaDz.cjs');
 
 function findProjectRoot(startDir) {
     let current = path.resolve(startDir);

package/dist/cli-chunks/{remote-CWeqNVk_.cjs → remote-DCHqFvmB.cjs}

@@ -1,18 +1,18 @@
 'use strict';
 
-var runtimePermissionEnv = require('./runtime-permission-env-9GWrfOTi.cjs');
-var context = require('./context-DlcETCGM.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-DR89buKQ.cjs');
+var context = require('./context-B15FzPf9.cjs');
 var promises = require('node:readline/promises');
-var index = require('./index-CO8AEaXW.cjs');
-var session = require('./session-CRiCQkg-.cjs');
+var index = require('./index-Dd_eGaDz.cjs');
+var session = require('./session-BiT-5VHK.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 node_crypto = require('node:crypto');
 require('node:zlib');
-var runtimeGate = require('./runtime-gate-PxUnfrPH.cjs');
-require('./version-Bk5ehprU.cjs');
+var runtimeGate = require('./runtime-gate-DkTbgx4d.cjs');
+require('./version-CJ7rfbl-.cjs');
 require('node:async_hooks');
 require('sharp');
 require('node:module');
@@ -274,7 +274,7 @@ function createDefaultCosClient(uploadToken, COS) {
     };
 }
 async function loadCosConstructor() {
-    const cosModule = await Promise.resolve().then(function () { return require('./index-CbDWlPpw.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-CeA8xI0T.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {

package/dist/cli-chunks/{runtime-gate-PxUnfrPH.cjs → runtime-gate-DkTbgx4d.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var runtimePermissionEnv = require('./runtime-permission-env-9GWrfOTi.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-DR89buKQ.cjs');
 
 // Shorthands
 /**

package/dist/cli-chunks/{runtime-permission-env-9GWrfOTi.cjs → runtime-permission-env-DR89buKQ.cjs}

@@ -2,7 +2,7 @@
 
 var fs = require('node:fs');
 var path = require('node:path');
-var version = require('./version-Bk5ehprU.cjs');
+var version = require('./version-CJ7rfbl-.cjs');
 require('node:crypto');
 var node_async_hooks = require('node:async_hooks');
 

package/dist/cli-chunks/{session-CRiCQkg-.cjs → session-BiT-5VHK.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-CO8AEaXW.cjs');
+var index = require('./index-Dd_eGaDz.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');
@@ -212,6 +212,16 @@ function getApiPathname(pathWithQuery) {
     return new URL(pathWithQuery, HEYBOX_API_BASE_URL).pathname;
 }
 const ENVELOPE_BODY_PREVIEW_LENGTH = 1000;
+/** 网关限流状态码；403（封禁）与 429（限速）走独立错误分支。 */
+const RATE_LIMIT_HTTP_STATUSES = new Set([403, 429]);
+/** HTTP-date 只接受以星期缩写开头的合法形态，避免宽松解析把垃圾值当日期。 */
+const HTTP_DATE_RE = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun)\b/i;
+/** 网关原文里的等待时长；例如 `43200s内请求 ... 6127次，限制访问 86400s`。 */
+const GATEWAY_RETRY_AFTER_PATTERNS = [
+    /限制访问\s*(\d+(?:\.\d+)?)\s*s/i,
+    /retry[\s_-]*after[^0-9]{0,12}(\d+(?:\.\d+)?)\s*s/i,
+    /(\d+(?:\.\d+)?)\s*秒后/,
+];
 async function readHeyboxApiEnvelope(response, options) {
     const rawBody = await response.text();
     let envelope = null;
@@ -235,8 +245,60 @@ async function readHeyboxApiEnvelope(response, options) {
         rawBody,
         pathWithQuery: options.pathWithQuery,
     });
+    if (RATE_LIMIT_HTTP_STATUSES.has(response.status)) {
+        const gatewayMessage = readGatewayRateLimitMessage(envelope, rawBody);
+        const retryAfterMs = readRetryAfterMs(response, gatewayMessage);
+        throw new index.CliRateLimitedError(message, {
+            gatewayMessage,
+            httpStatus: response.status,
+            ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+            verboseMessage,
+        });
+    }
     throw new index.CliError(message, verboseMessage, { httpStatus: response.status });
 }
+/**
+ * 优先读 `Retry-After` 响应头，其次从网关原文解析等待时长。
+ *
+ * 只返回**正数毫秒**：`Retry-After: 0`、已过期的 HTTP-date、负数与非法值一律按「网关没有
+ * 给出时长」处理，由消费方回落默认窗口（CLI 30s 起、宿主页 30s）。这样两端对同一个状态
+ * 的解读一致，也不会出现「宿主页立即重连、CLI 仍在压制」的分歧。
+ */
+function readRetryAfterMs(response, gatewayMessage) {
+    const headerValue = response.headers?.get('retry-after')?.trim();
+    if (headerValue) {
+        // 纯数字才是 delta-seconds；其余按 HTTP-date 解析，避免 `Date.parse('-5')` 产出垃圾值。
+        if (/^\d+$/.test(headerValue)) {
+            const headerMs = Number(headerValue) * 1000;
+            if (headerMs > 0)
+                return Math.round(headerMs);
+        }
+        else if (HTTP_DATE_RE.test(headerValue)) {
+            const headerDate = Date.parse(headerValue);
+            if (Number.isFinite(headerDate) && headerDate > Date.now()) {
+                return headerDate - Date.now();
+            }
+        }
+    }
+    for (const pattern of GATEWAY_RETRY_AFTER_PATTERNS) {
+        const matched = gatewayMessage.match(pattern);
+        const seconds = matched ? Number(matched[1]) : Number.NaN;
+        if (Number.isFinite(seconds) && seconds > 0) {
+            return Math.round(seconds * 1000);
+        }
+    }
+    return undefined;
+}
+/** 网关原文：优先 envelope 的 msg，退化为响应体原文，最后回落到通用文案。 */
+function readGatewayRateLimitMessage(envelope, rawBody) {
+    const msg = typeof envelope?.msg === 'string' ? envelope.msg.trim() : '';
+    if (msg)
+        return msg;
+    const sbeUserMessage = readSbeUserMessage(envelope?.result);
+    if (sbeUserMessage)
+        return sbeUserMessage;
+    return rawBody.trim() ? truncate(rawBody.trim(), ENVELOPE_BODY_PREVIEW_LENGTH) : '';
+}
 function formatHeyboxEnvelopeError(input) {
     const parts = [`Heybox API ${input.pathWithQuery} failed`, `HTTP ${input.response.status}`];
     if (input.envelope) {

package/dist/cli-chunks/{skill-BZFvZvOT.cjs → skill-C5EoUf2T.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
-var version = require('./version-Bk5ehprU.cjs');
+var version = require('./version-CJ7rfbl-.cjs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
 var childProcess = require('node:child_process');
-var index = require('./index-CO8AEaXW.cjs');
+var index = require('./index-Dd_eGaDz.cjs');
 require('node:module');
 require('node:fs');
 require('path');

package/dist/cli-chunks/{version-Bk5ehprU.cjs → version-CJ7rfbl-.cjs}

@@ -3,6 +3,6 @@
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.4';
+    : '0.9.0-alpha.0';
 
 exports.HB_SDK_VERSION = HB_SDK_VERSION;

package/dist/cli.cjs

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