@heybox/hb-sdk 0.8.4 → 0.8.5

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 0.8.5 - 2026-10-02
+
+> 影响级别：必须操作
+> 开发者动作：使用手机真机调试时升级至 `0.8.5` 并重新运行 `hb-sdk dev`；小程序代码中依赖旧错误码的失败分支需按新的 `RATE_LIMITED` / `RATE_LIMITED_BY_RUNTIME` 调整。
+> 兼容范围：公开 SDK API 形状与权限模型不变；小程序接口遇到平台限流时的错误码由 `REQUEST_FAILED` / `UNAUTHORIZED` 统一为 `RATE_LIMITED`，属有意的行为变更。Runtime 私有接口以外的公开网络能力不受影响。
+
+### 必须操作
+
+- 小程序接口遇到平台限流（HTTP 403/429）时返回的错误码统一为 `RATE_LIMITED`：错误数据里的 `status` 为上游状态码，`retryAfterMs`（可能缺失）为建议退避时长。此前分别返回 `REQUEST_FAILED`（auth / user / home_v2）或 `UNAUTHORIZED`（cloud.leaderboard，401 仍为 `UNAUTHORIZED`）。
+- 新增本地拒绝错误码 `RATE_LIMITED_BY_RUNTIME`：Runtime 自身的每 session 配额与同一接口的循环检测触发时返回，错误数据里的 `origin` 为 `budget` 或 `loop`，请求不会到达上游。遇到上述两个错误码时请停止立即重试，避免把用户 IP 打成被封。
+
+### 行为调整
+
+- `user.getInfo()` / `auth.login()` / 排行榜接口 的同一份结果会在短时间内复用（身份 30s、资料 60s、榜单沿用既有 5 分钟）。账号切换与授权撤销会立即失效；Steam 换绑 / 解绑最多 30s 后生效。
+- `hb-sdk dev` 会短暂复用已读取的调试信息，并在读取失败后逐步延长重试间隔，不再持续请求远端。
+- 被平台限流时会暂停刷新并给出预计恢复时间，提示不要反复重启。
+
+### 问题修复
+
+- 修复手机真机调试反复重连时持续请求远端调试信息、进而触发平台限流的问题。
+
+### 文档与工具
+
+- 被平台限流时提示升级到最新版本。
+
 ## 0.8.4 - 2026-09-25
 
 > 影响级别：常规

package/dist/cli-chunks/{build-DgV-or9j.cjs → build-zYnPSPFa.cjs}

@@ -3,13 +3,13 @@
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-9GWrfOTi.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-Bs_JqpTM.cjs');
 require('node:crypto');
 require('node:zlib');
-var runtimeGate = require('./runtime-gate-PxUnfrPH.cjs');
-var index = require('./index-CO8AEaXW.cjs');
-var projectVite = require('./project-vite-Dw04aEsD.cjs');
-require('./version-Bk5ehprU.cjs');
+var runtimeGate = require('./runtime-gate-DikSEEtm.cjs');
+var index = require('./index-Brq_-WV3.cjs');
+var projectVite = require('./project-vite-TFEwLzYM.cjs');
+require('./version-UEmqQ6A-.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');

package/dist/cli-chunks/{context-DlcETCGM.cjs → context-DWoKsM_O.cjs}

@@ -3,10 +3,10 @@
 var node_crypto = require('node:crypto');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-9GWrfOTi.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-Bs_JqpTM.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var session = require('./session-CRiCQkg-.cjs');
+var session = require('./session-CbisOcE4.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);

package/dist/cli-chunks/{create-BjJ6U5qS.cjs → create-C9FcEn9Y.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-CO8AEaXW.cjs');
+var index = require('./index-Brq_-WV3.cjs');
 require('node:module');
 require('os');
 require('node:crypto');

package/dist/cli-chunks/{dev-hIWir4Bp.cjs → dev-VxeEocjt.cjs}

@@ -1,9 +1,9 @@
 'use strict';
 
-var context = require('./context-DlcETCGM.cjs');
+var context = require('./context-DWoKsM_O.cjs');
 var node_crypto = require('node:crypto');
 var fs = require('node:fs');
-var runtimePermissionEnv = require('./runtime-permission-env-9GWrfOTi.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-Bs_JqpTM.cjs');
 var os = require('node:os');
 var path = require('node:path');
 var net = require('node:net');
@@ -12,13 +12,13 @@ var node_http = require('node:http');
 var node_module = require('node:module');
 var undici = require('undici');
 var fs$1 = require('node:fs/promises');
-var index = require('./index-CO8AEaXW.cjs');
+var index = require('./index-Brq_-WV3.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-CRiCQkg-.cjs');
+var session = require('./session-CbisOcE4.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-Dw04aEsD.cjs');
-var version = require('./version-Bk5ehprU.cjs');
+var projectVite = require('./project-vite-TFEwLzYM.cjs');
+var version = require('./version-UEmqQ6A-.cjs');
 require('node:zlib');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -1247,6 +1247,12 @@ function createContextFields(context) {
         local_dev_launch_token: context.localDevLaunchToken,
         mini_program_id: context.miniProgramId,
         companion_manifest_sha256: context.companionManifestSha256,
+        // 限流状态是加性字段：限流时才写入；显式置 null 表示已恢复，需要覆盖旧快照里的状态。
+        ...(context.rateLimit
+            ? { rate_limit: context.rateLimit }
+            : context.rateLimit === null
+                ? { rate_limit: null }
+                : {}),
     };
 }
 function validateDevSessionCreatePayload(payload, allowedMiniUrlOrigins, runtimePermissions) {
@@ -1986,8 +1992,8 @@ const DEFAULT_CHANNEL_TRANSPORT = {
 };
 const IPV4_LOOPBACK_ADDRESSES = new net.BlockList();
 IPV4_LOOPBACK_ADDRESSES.addSubnet('127.0.0.0', 8, 'ipv4');
-const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-hIWir4Bp.cjs', document.baseURI).href)))('ws');
-const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-hIWir4Bp.cjs', document.baseURI).href)))('parse5');
+const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-VxeEocjt.cjs', document.baseURI).href)))('ws');
+const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-VxeEocjt.cjs', document.baseURI).href)))('parse5');
 const BROWSER_DEV_HOST_ROOT_CANDIDATES = [
     path.resolve(__dirname, 'devtools/browser-dev-host'),
     path.resolve(__dirname, '../devtools/browser-dev-host'),
@@ -11086,7 +11092,7 @@ function assertNodeRuntimeCapabilities(ctx, settings) {
 function createNodeRealtimeDriverRegistry() {
     const registry = createRuntimeRealtimeDriverRegistry();
     registry.registerLazy('node-websocket', async () => {
-        const mod = await Promise.resolve().then(function () { return require('./index.esm-COo1T4B1.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-DMvmTtIS.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -15212,6 +15218,139 @@ const COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = 'HB_SDK_COMPANION_ARTIFACT_ACCESS_TO
 // 本地 PC 调试 manifest 的专用令牌：开窗时扩展还没拿到 LocalDevelopmentBinding，只能靠启动 URI 带来。
 const MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = 'HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN';
 const COMPANION_ARTIFACT_ACCESS_TOKEN_HEADER = 'x-hb-sdk-companion-dev-token';
+/** Dev Context 结果缓存 TTL 默认值；手机端重连不再 1:1 产生远端请求。 */
+const DEFAULT_DEV_CONTEXT_CACHE_TTL_MS = 30_000;
+/** 覆盖 Dev Context 缓存 TTL（毫秒）；设为 0 关闭缓存。 */
+const DEV_CONTEXT_CACHE_TTL_ENV = 'HB_SDK_DEV_CONTEXT_TTL_MS';
+/** 普通失败的指数退避起点。 */
+const DEFAULT_DEV_CONTEXT_BACKOFF_START_MS = 1_000;
+/** 普通失败的指数退避上限（60s）。 */
+const DEFAULT_DEV_CONTEXT_BACKOFF_MAX_MS = 60_000;
+/** 限流类失败（403/429）的退避起点。 */
+const RATE_LIMIT_BACKOFF_START_MS = 30_000;
+/** 限流类失败的退避上限（300s）。 */
+const RATE_LIMIT_BACKOFF_MAX_MS = 300_000;
+/** 退避抖动比例：±20%。 */
+const DEV_CONTEXT_BACKOFF_JITTER_RATIO = 0.2;
+/** 覆盖退避上限（毫秒）；同时作用于普通失败与限流类失败。 */
+const DEV_CONTEXT_BACKOFF_MAX_ENV = 'HB_SDK_BACKOFF_MAX_MS';
+/** 缓存命中的限流结果最长压制时间，避免封禁期内继续打远端。 */
+const DEV_CONTEXT_RATE_LIMIT_CACHE_MAX_MS = 300_000;
+/**
+ * 启动时命中限流、值得等待窗口过去的时长上限（毫秒）。
+ *
+ * 只有网关明确给出、且不超过该上限的窗口才等待并重试一次（自动恢复，不必重启 CLI）；
+ * 更长或未知的窗口直接跳过等待，按限流原因阻塞真机调试——事故里封禁 24h，等下去只会把
+ * `hb-sdk dev` 启动拖住几分钟却依然恢复不了。
+ */
+const DEV_CONTEXT_STARTUP_RATE_LIMIT_WAIT_MAX_MS = 30_000;
+/** 读取 Dev Context 缓存 TTL；非法值回落到默认 30s，0 表示关闭缓存。 */
+function resolveDevContextCacheTtlMs(env = process.env) {
+    const raw = env[DEV_CONTEXT_CACHE_TTL_ENV];
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_DEV_CONTEXT_CACHE_TTL_MS;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_DEV_CONTEXT_CACHE_TTL_MS;
+}
+/**
+ * 带 TTL 的 Dev Context 结果缓存。
+ *
+ * key = `projectRoot` + 当前绑定的 `miniProgramId`：同一项目内的启动读取、设备会话读取和
+ * 权限刷新共用一份结果，避免手机端每次重连都打一次远端 `detail`。TTL 内命中不打远端；
+ * `ttlMs` 为 0 时关闭缓存。
+ */
+function createDevContextCache(options) {
+    const now = options.now ?? Date.now;
+    const entries = new Map();
+    const inflight = new Map();
+    /**
+     * 全局代际：任一次失效都自增，早于本次失效发起的请求不得写回缓存。
+     *
+     * 刻意不用「按 key 记录 generation」：那样全量失效时只能推进已经登记过的 key，
+     * 而首次被全量失效的 key 不在表里，旧结果仍会回填（生产路径走的正是无参失效）。
+     */
+    let generation = 0;
+    const cacheEnabled = options.ttlMs > 0;
+    const resolveTtlMs = (value) => {
+        const dynamic = options.ttlMsOf?.(value);
+        return typeof dynamic === 'number' && Number.isFinite(dynamic) && dynamic > 0
+            ? Math.max(options.ttlMs, Math.min(dynamic, DEV_CONTEXT_RATE_LIMIT_CACHE_MAX_MS))
+            : options.ttlMs;
+    };
+    return {
+        invalidate: (key) => {
+            generation += 1;
+            if (key === undefined) {
+                entries.clear();
+                inflight.clear();
+                return;
+            }
+            entries.delete(key);
+            inflight.delete(key);
+        },
+        peek: (key) => entries.get(key)?.value,
+        read: (key) => {
+            if (cacheEnabled) {
+                const cached = entries.get(key);
+                if (cached && cached.expiresAt > now())
+                    return Promise.resolve(cached.value);
+                if (cached)
+                    entries.delete(key);
+            }
+            const pending = inflight.get(key);
+            if (pending)
+                return pending;
+            const readGeneration = generation;
+            const promise = options
+                .load(key)
+                .then((value) => {
+                // 主动失效后，早先 in-flight 的结果不得写回缓存；ttlMs 为 0 表示完全关闭缓存。
+                if (cacheEnabled && readGeneration === generation) {
+                    const ttlMs = resolveTtlMs(value);
+                    if (ttlMs > 0)
+                        entries.set(key, { expiresAt: now() + ttlMs, value });
+                }
+                return value;
+            })
+                .finally(() => {
+                if (inflight.get(key) === promise)
+                    inflight.delete(key);
+            });
+            inflight.set(key, promise);
+            return promise;
+        },
+    };
+}
+/** 退避上限：普通失败默认 60s，限流类默认 300s；两者都可被 HB_SDK_BACKOFF_MAX_MS 覆盖。 */
+function resolveDevContextBackoffLimits(env = process.env) {
+    const raw = env[DEV_CONTEXT_BACKOFF_MAX_ENV];
+    const parsed = raw === undefined || raw.trim() === '' ? Number.NaN : Number(raw);
+    const override = Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+    return {
+        normalMaxMs: override ?? DEFAULT_DEV_CONTEXT_BACKOFF_MAX_MS,
+        // 限流上限不得低于其起点，否则退避会退化成固定间隔。
+        rateLimitMaxMs: Math.max(RATE_LIMIT_BACKOFF_START_MS, override ?? RATE_LIMIT_BACKOFF_MAX_MS),
+    };
+}
+/**
+ * 计算 Dev Context 失败退避时长。
+ *
+ * 普通失败 `1s → 2s → 4s → … → 60s`；限流类失败（403/429）`30s → 60s → … → 300s`；
+ * 两者都带 ±20% 抖动，避免多个客户端同步重试。
+ */
+function computeDevContextBackoffDelayMs(options) {
+    const limits = resolveDevContextBackoffLimits(options.env);
+    const rateLimited = options.rateLimited === true;
+    const startMs = rateLimited ? RATE_LIMIT_BACKOFF_START_MS : DEFAULT_DEV_CONTEXT_BACKOFF_START_MS;
+    const maxMs = rateLimited ? limits.rateLimitMaxMs : limits.normalMaxMs;
+    const attempt = Number.isFinite(options.attempt) ? Math.max(0, Math.floor(options.attempt)) : 0;
+    const exponentialMs = startMs * 2 ** Math.min(attempt, 24);
+    const random = options.random ?? Math.random;
+    const randomValue = Math.min(1, Math.max(0, random()));
+    const jittered = exponentialMs * (1 - DEV_CONTEXT_BACKOFF_JITTER_RATIO + 2 * DEV_CONTEXT_BACKOFF_JITTER_RATIO * randomValue);
+    // 先抖动再封顶：否则 300s 的限流上限实际会被 ±20% 抖动突破到 360s。
+    return Math.max(1, Math.round(Math.min(maxMs, jittered)));
+}
 async function runDevCommand(options, runtime = {}) {
     const logger = runtime.logger ?? index.createCliLogger();
     const fetchImpl = runtime.fetchImpl ?? fetch;
@@ -15237,13 +15376,64 @@ async function runDevCommand(options, runtime = {}) {
     const devSessionId = node_crypto.randomBytes(16).toString('hex');
     const devContextPath = `/__hb_sdk__/dev-context/${node_crypto.randomBytes(32).toString('hex')}`;
     const miniProgramPlatforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
-    const { context: devLaunchContext, miniProgram } = await loadDevLaunchContext({
-        env: runtime.env,
-        fetchImpl,
-        logger,
-        projectRoot,
-        timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
+    // A1：Dev Context 结果缓存。启动读取、设备会话读取和权限刷新共用同一份结果，
+    // 手机端重连不再 1:1 产生远端 `detail` 请求；限流时按网关建议时长延长压制。
+    const defaultSleep = (ms) => new Promise(resolve => { setTimeout(resolve, ms).unref?.(); });
+    const devContextCache = createDevContextCache({
+        load: () => loadDevLaunchContext({
+            env: runtime.env,
+            fetchImpl,
+            logger,
+            projectRoot,
+            timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
+        }),
+        ttlMs: resolveDevContextCacheTtlMs(runtime.env ?? process.env),
+        ttlMsOf: (result) => result.context.rateLimit?.retryAfterMs,
     });
+    /**
+     * 读取 Dev Context。
+     *
+     * key 里带上当前 `package.json` 绑定的 miniProgramId：项目绑定变更会直接换成另一个缓存 key，
+     * 立即重新请求远端，而不是等 30s TTL（限流时 300s）过期后才发现换了小程序。
+     * 读绑定是本地文件读取，不打远端，符合「只读本地快照」的高频读范式。
+     */
+    const readDevLaunchContext = async () => {
+        const boundMiniProgramId = await context.readBoundMiniProgramId(projectRoot).catch(() => undefined);
+        return devContextCache.read(`${projectRoot}\0${boundMiniProgramId ?? ''}`);
+    };
+    let { context: devLaunchContext, miniProgram } = await readDevLaunchContext();
+    let lastRateLimitHint = '';
+    // A3：提示只在内容变化时输出一次，避免手机端反复重连刷屏。
+    const reportRateLimitOnce = (state) => {
+        const hint = index.formatCliRateLimitHint(state);
+        if (hint === lastRateLimitHint)
+            return;
+        lastRateLimitHint = hint;
+        reportDevContextRateLimit(logger, state, runtime.env);
+    };
+    if (devLaunchContext.rateLimit?.limited)
+        reportRateLimitOnce(devLaunchContext.rateLimit);
+    // 启动即被限流时 `miniProgramId` 缺失，后面不会创建 token session，也就没有任何刷新路径
+    // （三条读取入口都以 `source === 'remote'` 为前提），开发者只能重启 CLI。这里先等网关窗口
+    // 过去再重试一次：窗口短就自动恢复，窗口长（例如封禁 24h）则不再空等，转为按限流原因阻塞
+    // 真机调试，而不是误报「未登录 / 未绑定」。
+    const startupRateLimit = devLaunchContext.rateLimit;
+    if (!devLaunchContext.miniProgramId && startupRateLimit?.limited) {
+        const windowMs = startupRateLimit.retryAfterMs;
+        if (windowMs !== undefined && windowMs <= DEV_CONTEXT_STARTUP_RATE_LIMIT_WAIT_MAX_MS) {
+            logger.warn(`已被网关限流，等待 ${Math.round(windowMs / 1000)} 秒后重试一次…`);
+            await (runtime.sleep ?? defaultSleep)(windowMs);
+            // 限流结果在缓存里最多压制 300s，重试前必须先失效，否则读到的还是同一条。
+            devContextCache.invalidate();
+            const retried = await readDevLaunchContext();
+            if (retried.context.miniProgramId) {
+                devLaunchContext = retried.context;
+                miniProgram = retried.miniProgram;
+                // 已恢复正常：允许后续再次限流时重新提示。
+                lastRateLimitHint = '';
+            }
+        }
+    }
     let currentDevContext = devLaunchContext;
     let contextRevision = 1;
     let launchRuntimePermissions = context.createMobileDevSessionRuntimePermissions(devLaunchContext);
@@ -15253,6 +15443,7 @@ async function runDevCommand(options, runtime = {}) {
     let currentExpiresAt;
     let refreshDevCsp;
     let lastTemporaryWarning = '';
+    let hasReportedBindingChange = false;
     let tokenSession;
     const updateLocalContext = (allowedTemporaryKeys) => {
         const grant = runtimePermissionEnv.createMiniProgramLocalDevGrant({ declaredPermissions: currentDevContext.declaredPermissions ?? {},
@@ -15271,6 +15462,16 @@ async function runDevCommand(options, runtime = {}) {
         launchRuntimePermissions = context.createMobileDevSessionRuntimePermissions(currentDevContext);
         refreshDevCsp?.();
     };
+    // A3：把限流状态透出给浏览器调试页与宿主页，让手机端停止重连自激循环。
+    const applyRateLimitState = (state) => {
+        currentDevContext = { ...currentDevContext, rateLimit: state };
+        updateLocalContext();
+        browserDevHost.updateBootstrap({ devContext: currentDevContext });
+        if (state)
+            reportRateLimitOnce(state);
+        else
+            lastRateLimitHint = '';
+    };
     updateLocalContext();
     const readLaunchSource = () => ({
         devContext: currentDevContext,
@@ -15368,14 +15569,25 @@ async function runDevCommand(options, runtime = {}) {
             },
             readMobileDevSessionContext: async () => {
                 if (currentDevContext.source === 'remote') {
-                    const refreshed = await loadDevLaunchContext({ env: runtime.env, fetchImpl, logger, projectRoot,
-                        timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS });
-                    if (refreshed.context.source === 'remote' && refreshed.context.miniProgramId === currentDevContext.miniProgramId) {
+                    const refreshed = await readDevLaunchContext();
+                    if (refreshed.context.rateLimit?.limited) {
+                        // 被限流时不再替换上下文，只透出限流状态；手机端据此停止重连。
+                        applyRateLimitState(refreshed.context.rateLimit);
+                    }
+                    else if (refreshed.context.source === 'remote' && refreshed.context.miniProgramId === currentDevContext.miniProgramId) {
                         if (JSON.stringify(currentDevContext.runtimePermissions) !== JSON.stringify(refreshed.context.runtimePermissions))
                             contextRevision++;
                         currentDevContext = withCurrentLocalDevLaunchToken(refreshed.context, currentLocalDevLaunchToken);
                         updateLocalContext();
                         browserDevHost.updateBootstrap({ devContext: currentDevContext });
+                        hasReportedBindingChange = false;
+                    }
+                    else if (refreshed.context.source === 'remote' && refreshed.context.miniProgramId !== currentDevContext.miniProgramId) {
+                        // 绑定已变更：保留当前上下文不误发，但必须提示重启，避免真机调试一直用旧小程序。
+                        if (!hasReportedBindingChange) {
+                            hasReportedBindingChange = true;
+                            logger.warn('检测到项目绑定已变更，请重新运行 hb-sdk dev 后再扫码调试');
+                        }
                     }
                 }
                 return currentDevContext;
@@ -15401,8 +15613,11 @@ async function runDevCommand(options, runtime = {}) {
             companionDeclared: currentDevContext.declaredPermissions?.companion?.enabled === true && runtimePermissionEnv.hasMiniappDesktopPlatform(currentDevContext.platforms),
             miniProgramId: devLaunchContext.miniProgramId,
             refreshPermissions: async () => {
-                const refreshed = await loadDevLaunchContext({ env: runtime.env, fetchImpl, logger, projectRoot,
-                    timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS });
+                const refreshed = await readDevLaunchContext();
+                // 限流必须原样抛出，才能走 30s 起、上限 300s 的退避与「请勿反复重启」提示。
+                if (refreshed.context.rateLimit?.limited) {
+                    throw index.createCliRateLimitedErrorFromState(refreshed.context.rateLimit);
+                }
                 if (refreshed.context.miniProgramId !== devLaunchContext.miniProgramId)
                     throw new Error('项目绑定已变更，请重新启动调试');
                 if (refreshed.context.source !== 'remote')
@@ -15428,13 +15643,21 @@ async function runDevCommand(options, runtime = {}) {
                 });
             },
             onReadiness: devReadiness => browserDevHost.updateBootstrap({ devReadiness }),
+            // 主动失效：项目绑定变更或开发者点重试后立即重新请求（key 会带上新绑定，这里清空全部）。
+            onInvalidate: () => devContextCache.invalidate(),
+            // 限流状态与恢复都要透出给调试页与宿主页。
+            onRateLimit: state => applyRateLimitState(state),
             projectRoot,
             timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
         });
         closers.push(tokenSession.close);
     }
     else {
-        const reason = '登录或小程序绑定不可用，请完成 CLI 登录和项目绑定';
+        // 限流与「未登录 / 未绑定」是两回事：前者等窗口过去即可，后者要开发者去操作。
+        // 用限流原因阻塞真机调试，避免把已封禁误报成登录/绑定问题。
+        const reason = devLaunchContext.rateLimit?.limited
+            ? `真机调试暂不可用：${index.formatCliRateLimitHint(devLaunchContext.rateLimit)}`
+            : '登录或小程序绑定不可用，请完成 CLI 登录和项目绑定';
         browserDevHost.updateBootstrap({
             devReadiness: {
                 browser: { state: 'ready' },
@@ -15444,11 +15667,35 @@ async function runDevCommand(options, runtime = {}) {
         });
     }
     const packagePath = path.join(projectRoot, 'package.json');
+    /**
+     * 上一次生效的声明指纹。
+     *
+     * `watchFile` 是 mtime 轮询、不比较内容，版本号或依赖的普通写入也会触发；不比对就直接
+     * `refresh()` 会清空缓存并立刻打一次远端 `detail`（密集写入可达数十次/分钟）。
+     */
+    let lastDeclarationFingerprint;
+    const readDeclarationFingerprint = () => JSON.stringify([
+        runtimePermissionEnv.readMiniappPermissionsFromPackageJson(projectRoot, runtimePermissionEnv.resolveMiniappSdkVersion()).permissions ?? null,
+        runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot),
+        context.readBoundMiniProgramId(projectRoot),
+    ]);
+    // 先记录启动时已生效的声明，这样与调试声明无关的写入（版本号、依赖等）不会触发远端刷新。
+    try {
+        lastDeclarationFingerprint = readDeclarationFingerprint();
+    }
+    catch {
+        // 读不出来就交给下面的 onDeclarationChange 走异常分支。
+    }
     const onDeclarationChange = () => {
         try {
             const previouslyTemporary = new Set(currentDevContext.localDevGrant?.entries.map(entry => entry.key));
             const local = runtimePermissionEnv.readMiniappPermissionsFromPackageJson(projectRoot, runtimePermissionEnv.resolveMiniappSdkVersion());
             const platforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
+            // 与调试声明无关的写入（版本号、依赖等）不触发远端刷新。
+            const fingerprint = JSON.stringify([local.permissions ?? null, platforms, context.readBoundMiniProgramId(projectRoot)]);
+            if (fingerprint === lastDeclarationFingerprint)
+                return;
+            lastDeclarationFingerprint = fingerprint;
             contextRevision++;
             currentDevContext = { ...currentDevContext, declaredPermissions: local.permissions ?? {}, platforms,
                 runtimePermissions: runtimePermissionEnv.composeMiniappRuntimePermissions(local, currentDevContext.runtimePermissions).runtimePermissions };
@@ -15555,9 +15802,33 @@ async function loadDevLaunchContext(options) {
             throw new Error(`版本资料配置失败：${index.readRedactedErrorMessage(error)}。请配置 heybox.name/icon/coverImages 后重试。`, { cause: error });
         if (error instanceof context.MiniProgramProjectBindingError && error.code.startsWith('PACKAGE_JSON_'))
             throw error;
+        // A3：限流要作为结构化状态继续透出；不能和其它错误一样只报「未连接线上上下文」。
+        const rateLimitState = index.readCliRateLimitState(error);
+        if (rateLimitState) {
+            return {
+                context: {
+                    ...anonymous(index.formatCliRateLimitHint(rateLimitState)).context,
+                    rateLimit: rateLimitState,
+                },
+                miniProgram: null,
+            };
+        }
         return anonymous('未连接线上上下文，请检查 CLI 登录态、项目绑定和网络');
     }
 }
+/**
+ * 输出限流提示并强提示升级。
+ *
+ * 老版本 CLI 无法被强制升级，只能在此明确提示「请勿反复重启」并引导更新。
+ */
+function reportDevContextRateLimit(logger, state, env) {
+    void index.printRateLimitUpgradeHint({
+        env,
+        logger,
+        ...(state.retryAfterMs === undefined ? {} : { retryAfterMs: state.retryAfterMs }),
+        ...(state.message ? { gatewayMessage: state.message } : {}),
+    }).catch(() => undefined);
+}
 function createMiniProgramSummary(miniProgramId, detail) {
     const id = typeof detail.mini_program_id === 'string' && detail.mini_program_id.trim() ? detail.mini_program_id.trim() : miniProgramId;
     return {
@@ -15828,6 +16099,7 @@ function startLocalDevLaunchTokenSession(options) {
     let ticket;
     let pending;
     let refreshing = false;
+    let consecutiveFailures = 0;
     const getTicket = async (companionManifestSha256) => {
         if (closed)
             return undefined;
@@ -15856,8 +16128,9 @@ function startLocalDevLaunchTokenSession(options) {
         refreshing = true;
         try {
             if (options.refreshPermissions && Date.now() >= permissionsRefreshAt) {
-                companionDeclared = await options.refreshPermissions();
+                // A-3：无论成败都推进，否则权限刷新失败后每一轮重试都会再打一次远端 detail。
                 permissionsRefreshAt = Date.now() + 30_000;
+                companionDeclared = await options.refreshPermissions();
             }
             let manifest;
             let snapshotError;
@@ -15902,18 +16175,35 @@ function startLocalDevLaunchTokenSession(options) {
                 hasReportedTokenFailure = false;
                 options.logger.success('本地调试凭证已恢复');
             }
+            if (consecutiveFailures > 0) {
+                consecutiveFailures = 0;
+                options.onRateLimit?.(null);
+            }
         }
         catch (error) {
             if (closed)
                 return;
-            if (!hasReportedTokenFailure) {
+            // A2 + A3：限流类错误走 30s 起、上限 300s 的退避，并明确提示不要反复重启。
+            const rateLimitState = index.readCliRateLimitState(error);
+            consecutiveFailures += 1;
+            if (rateLimitState) {
+                // 限流提示统一由 onRateLimit 出口负责（runDevCommand 走 reportRateLimitOnce，
+                // 保证同一文案只输出一次）；这里不再自己 warn，避免同一次限流打印两行。
+                options.onRateLimit?.(rateLimitState);
+            }
+            else if (!hasReportedTokenFailure) {
                 options.logger.warn('本地调试凭证获取失败，将自动重试；Web / Browser Fake 仍可使用');
             }
             hasReportedTokenFailure = true;
-            options.onReadiness({ browser: { state: 'ready' }, mobile: { state: 'blocked', reason: '调试凭证暂不可用' },
+            options.onReadiness({ browser: { state: 'ready' },
+                mobile: { state: 'blocked', reason: rateLimitState ? index.formatCliRateLimitHint(rateLimitState) : '调试凭证暂不可用' },
                 companion: { state: 'blocked', reason: safeCompanionFailureReason(error) } });
             options.logger.debug(`本地调试凭证获取失败，详细原因：${index.readRedactedErrorMessage(error, { verbose: true })}`);
-            schedule(options.timeoutMs);
+            schedule(computeDevContextBackoffDelayMs({
+                attempt: consecutiveFailures - 1,
+                env: options.env,
+                rateLimited: rateLimitState !== null,
+            }));
         }
         finally {
             refreshing = false;
@@ -15943,6 +16233,8 @@ function startLocalDevLaunchTokenSession(options) {
     return {
         getTicket,
         refresh: () => {
+            // 项目绑定变更或开发者主动重试：主动失效 Dev Context 缓存后立即重新请求。
+            options.onInvalidate?.();
             permissionsRefreshAt = 0;
             publishedDigest = undefined;
             if (refreshTimer)
@@ -16194,8 +16486,12 @@ function isPrivateIPv4(address) {
 
 var dev = /*#__PURE__*/Object.freeze({
 	__proto__: null,
+	computeDevContextBackoffDelayMs: computeDevContextBackoffDelayMs,
+	createDevContextCache: createDevContextCache,
 	createMiniProgramDevLaunchVitePlugin: createMiniProgramDevLaunchVitePlugin,
 	normalizeExpiresAt: normalizeExpiresAt,
+	resolveDevContextBackoffLimits: resolveDevContextBackoffLimits,
+	resolveDevContextCacheTtlMs: resolveDevContextCacheTtlMs,
 	runDevCommand: runDevCommand,
 	startLocalDevLaunchTokenSession: startLocalDevLaunchTokenSession
 });

package/dist/cli-chunks/{doctor-DImHJjzI.cjs → doctor-6Cf9o1hD.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-Brq_-WV3.cjs');
 require('node:module');
 require('node:fs');
 require('path');

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

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-CO8AEaXW.cjs');
+var index$2 = require('./index-Brq_-WV3.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-Bs_JqpTM.cjs');
 var require$$0$7 = require('net');
 var require$$0$6 = require('url');
 var require$$2$1 = require('http');