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

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

@@ -1,9 +1,9 @@
 'use strict';
 
-var context = require('./context-DlcETCGM.cjs');
+var context = require('./context-B15FzPf9.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-DR89buKQ.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-Dd_eGaDz.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-CRiCQkg-.cjs');
+var session = require('./session-BiT-5VHK.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-ckDtbYtt.cjs');
+var version = require('./version-CJ7rfbl-.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-tAThflC6.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-tAThflC6.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-Bw3R5BAL.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -15212,6 +15218,142 @@ 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';
+/** 失败上下文的缓存窗口；成功上下文复用到绑定或声明变化。 */
+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;
+/** 新声明已替代在途请求；旧结果不应用，也不作为远端失败提示。 */
+class DevContextSupersededError extends Error {
+}
+/** 读取 Dev Context 缓存 TTL；非法值回落到默认 30 秒，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,14 +15379,70 @@ 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，
+     * 立即重新请求远端，而不是等缓存过期后才发现换了小程序。
+     * 读绑定是本地文件读取，不打远端，符合「只读本地快照」的高频读范式。
+     */
+    const readDevLaunchContext = async (reuseSnapshot = false) => {
+        const boundMiniProgramId = await context.readBoundMiniProgramId(projectRoot).catch(() => undefined);
+        const key = `${projectRoot}\0${boundMiniProgramId ?? ''}`;
+        const snapshot = reuseSnapshot ? devContextCache.peek(key) : undefined;
+        if (snapshot?.context.source === 'remote' && !snapshot.context.rateLimit?.limited)
+            return snapshot;
+        return devContextCache.read(key);
+    };
+    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 devContextGeneration = 0;
     let contextRevision = 1;
     let launchRuntimePermissions = context.createMobileDevSessionRuntimePermissions(devLaunchContext);
     const mobileDevContextUrlsByOrigin = new Map();
@@ -15253,6 +15451,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 +15470,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 +15577,28 @@ 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 generation = devContextGeneration;
+                    const refreshed = await readDevLaunchContext(true);
+                    if (generation !== devContextGeneration)
+                        return currentDevContext;
+                    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 +15624,14 @@ 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 generation = devContextGeneration;
+                const refreshed = await readDevLaunchContext();
+                if (generation !== devContextGeneration)
+                    throw new DevContextSupersededError();
+                // 限流必须原样抛出，才能走 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 +15657,24 @@ async function runDevCommand(options, runtime = {}) {
                 });
             },
             onReadiness: devReadiness => browserDevHost.updateBootstrap({ devReadiness }),
+            // 主动失效：项目绑定变更或开发者点重试后立即重新请求（key 会带上新绑定，这里清空全部）。
+            onInvalidate: () => {
+                devContextGeneration += 1;
+                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 +15684,36 @@ async function runDevCommand(options, runtime = {}) {
         });
     }
     const packagePath = path.join(projectRoot, 'package.json');
+    /**
+     * 上一次生效的声明指纹。
+     *
+     * `watchFile` 是 mtime 轮询、不比较内容，版本号或依赖的普通写入也会触发；不比对就直接
+     * `refresh()` 会清空缓存并立刻打一次远端 `detail`（密集写入可达数十次/分钟）。
+     */
+    let lastDeclarationFingerprint;
+    const readBindingFingerprint = () => context.readBoundMiniProgramIdFromPackageJson(JSON.parse(fs.readFileSync(packagePath, 'utf8')));
+    const readDeclarationFingerprint = () => JSON.stringify([
+        runtimePermissionEnv.readMiniappPermissionsFromPackageJson(projectRoot, runtimePermissionEnv.resolveMiniappSdkVersion()).permissions ?? null,
+        runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot),
+        readBindingFingerprint(),
+    ]);
+    // 先记录启动时已生效的声明，这样与调试声明无关的写入（版本号、依赖等）不会触发远端刷新。
+    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, readBindingFingerprint()]);
+            if (fingerprint === lastDeclarationFingerprint)
+                return;
+            lastDeclarationFingerprint = fingerprint;
             contextRevision++;
             currentDevContext = { ...currentDevContext, declaredPermissions: local.permissions ?? {}, platforms,
                 runtimePermissions: runtimePermissionEnv.composeMiniappRuntimePermissions(local, currentDevContext.runtimePermissions).runtimePermissions };
@@ -15555,9 +15820,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 {
@@ -15822,13 +16111,17 @@ function startLocalDevLaunchTokenSession(options) {
     let hasReportedTokenFailure = false;
     let refreshTimer;
     let companionDeclared = options.companionDeclared;
-    let permissionsRefreshAt = Date.now() + 30_000;
+    let permissionsRefreshPending = false;
+    let permissionsRefreshFailure;
+    let permissionsGeneration = 0;
+    let validatedPermissionsGeneration = 0;
     let publishedToken;
     let publishedDigest;
     let ticket;
     let pending;
     let refreshing = false;
-    const getTicket = async (companionManifestSha256) => {
+    let consecutiveFailures = 0;
+    const acquireTicket = async (companionManifestSha256) => {
         if (closed)
             return undefined;
         if (ticket && (companionManifestSha256 === undefined || ticket.companionManifestSha256 === companionManifestSha256) && ticket.refreshAt > Date.now())
@@ -15838,11 +16131,14 @@ function startLocalDevLaunchTokenSession(options) {
     const issueTicket = (companionManifestSha256) => {
         if (pending && pending.digest === companionManifestSha256)
             return pending.promise;
+        const generation = permissionsGeneration;
         const promise = issueLocalDevLaunchToken({
             ...options,
             ...(companionManifestSha256 ? { companionManifestSha256 } : {}),
         })
             .then(issued => {
+            if (closed || generation !== permissionsGeneration)
+                throw new DevContextSupersededError();
             ticket = issued;
             return issued;
         }).finally(() => { if (pending?.promise === promise)
@@ -15850,15 +16146,50 @@ function startLocalDevLaunchTokenSession(options) {
         pending = { digest: companionManifestSha256, promise };
         return promise;
     };
+    const getTicket = async (companionManifestSha256) => {
+        if (closed)
+            return undefined;
+        const generation = permissionsGeneration;
+        const assertPermissionsReady = () => {
+            if (generation !== permissionsGeneration)
+                throw new DevContextSupersededError();
+            if (permissionsRefreshFailure)
+                throw permissionsRefreshFailure.error;
+            if (validatedPermissionsGeneration !== permissionsGeneration)
+                throw new Error('远端上下文正在刷新，请稍后再试');
+        };
+        assertPermissionsReady();
+        const issued = await acquireTicket(companionManifestSha256);
+        if (closed)
+            return undefined;
+        assertPermissionsReady();
+        return issued;
+    };
     const refresh = async () => {
         if (refreshing || closed)
             return;
         refreshing = true;
+        const generation = permissionsGeneration;
         try {
-            if (options.refreshPermissions && Date.now() >= permissionsRefreshAt) {
-                companionDeclared = await options.refreshPermissions();
-                permissionsRefreshAt = Date.now() + 30_000;
+            if (options.refreshPermissions && permissionsRefreshPending) {
+                permissionsRefreshPending = false;
+                try {
+                    const nextCompanionDeclared = await options.refreshPermissions();
+                    if (generation !== permissionsGeneration || closed)
+                        return;
+                    companionDeclared = nextCompanionDeclared;
+                    permissionsRefreshFailure = undefined;
+                    validatedPermissionsGeneration = generation;
+                }
+                catch (error) {
+                    if (generation !== permissionsGeneration || error instanceof DevContextSupersededError)
+                        return;
+                    permissionsRefreshFailure = { error };
+                    throw error;
+                }
             }
+            if (!options.refreshPermissions)
+                validatedPermissionsGeneration = generation;
             let manifest;
             let snapshotError;
             try {
@@ -15871,52 +16202,82 @@ function startLocalDevLaunchTokenSession(options) {
             catch (error) {
                 snapshotError = error;
             }
+            if (closed || generation !== permissionsGeneration)
+                return;
             const digest = manifest?.artifacts.length ? manifest.digest : undefined;
-            const issued = await getTicket(digest);
+            const issued = await acquireTicket(digest);
             if (!issued)
                 return;
-            if (closed)
+            if (closed || generation !== permissionsGeneration)
                 return;
-            if (publishedToken !== issued.token || publishedDigest !== digest) {
+            if (!permissionsRefreshFailure && (publishedToken !== issued.token || publishedDigest !== digest)) {
                 publishedToken = issued.token;
                 publishedDigest = digest;
                 options.onToken(issued.token, digest, issued.expiresAt);
             }
             options.onReadiness({
                 browser: { state: 'ready' },
-                mobile: { state: 'ready' },
-                companion: snapshotError
-                    ? { state: snapshotError instanceof Error && snapshotError.message.includes('artifact-updating') ? 'pending' : 'blocked', reason: safeCompanionFailureReason(snapshotError) }
-                    : manifest?.artifacts.length
-                        ? companionDeclared
-                            ? { state: 'ready', digest, artifacts: manifest.artifacts, reason: '本地产物和启动票已就绪，PC 授权将在打开后验证' }
-                            : { state: 'blocked', reason: 'Companion 本地权限或桌面平台声明未开启' }
-                        : { state: 'not-configured', reason: '未配置本地 Companion 产物' },
+                mobile: permissionsRefreshFailure
+                    ? { state: 'blocked', reason: '远端上下文刷新失败，请更新声明或重新启动调试' }
+                    : { state: 'ready' },
+                companion: permissionsRefreshFailure
+                    ? { state: 'blocked', reason: '远端上下文刷新失败，请更新声明或重新启动调试' }
+                    : snapshotError
+                        ? { state: snapshotError instanceof Error && snapshotError.message.includes('artifact-updating') ? 'pending' : 'blocked', reason: safeCompanionFailureReason(snapshotError) }
+                        : manifest?.artifacts.length
+                            ? companionDeclared
+                                ? { state: 'ready', digest, artifacts: manifest.artifacts, reason: '本地产物和启动票已就绪，PC 授权将在打开后验证' }
+                                : { state: 'blocked', reason: 'Companion 本地权限或桌面平台声明未开启' }
+                            : { state: 'not-configured', reason: '未配置本地 Companion 产物' },
             });
             if (snapshotError)
                 options.logger.debug(`PC Companion 快照校验失败：${index.readRedactedErrorMessage(snapshotError, { verbose: true })}`);
             const ttl = Math.max(0, issued.expiresAt - Date.now());
-            scheduleExpiration(ttl);
+            if (!permissionsRefreshFailure)
+                scheduleExpiration(ttl);
             schedule(Math.min(2_000, Math.max(1_000, Math.floor(ttl * 0.8))));
-            if (hasReportedTokenFailure) {
+            if (hasReportedTokenFailure && !permissionsRefreshFailure) {
                 hasReportedTokenFailure = false;
                 options.logger.success('本地调试凭证已恢复');
             }
+            if (consecutiveFailures > 0 && !permissionsRefreshFailure) {
+                consecutiveFailures = 0;
+                options.onRateLimit?.(null);
+            }
         }
         catch (error) {
-            if (closed)
+            if (closed || generation !== permissionsGeneration || error instanceof DevContextSupersededError)
                 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;
+            // 请求期间有新声明时立即处理最新一代，避免被并发保护丢掉刷新事件。
+            if (permissionsRefreshPending && !closed) {
+                if (refreshTimer)
+                    clearTimeout(refreshTimer);
+                schedule(0);
+            }
         }
     };
     const schedule = (delayMs) => {
@@ -15943,7 +16304,12 @@ function startLocalDevLaunchTokenSession(options) {
     return {
         getTicket,
         refresh: () => {
-            permissionsRefreshAt = 0;
+            // 项目绑定变更或开发者主动重试：主动失效 Dev Context 缓存后立即重新请求。
+            options.onInvalidate?.();
+            permissionsGeneration += 1;
+            permissionsRefreshPending = true;
+            ticket = undefined;
+            pending = undefined;
             publishedDigest = undefined;
             if (refreshTimer)
                 clearTimeout(refreshTimer);
@@ -16194,8 +16560,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
 });