@heybox/hb-sdk 0.8.5 → 0.9.0-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 0.9.0-alpha.1 - 2026-10-07
+
+> 影响级别：常规
+> 开发者动作：Android 扫码调试用户升级至 `0.9.0-alpha.1` 后重新运行 `hb-sdk dev`。
+> 兼容范围：公开 SDK API 不变；补齐真实客户端扫码调试启动协议中的小程序身份字段，保留原有兼容字段。
+
+### 问题修复
+
+- 修复 CLI 扫码启动协议缺少 `user_miniprogram_id`，导致 Android 1.3.396 调试容器可能无法使用原生桥接能力的问题。
+
+## 0.9.0-alpha.0 - 2026-10-06
+
+> 影响级别：常规
+> 开发者动作：升级至 `0.9.0-alpha.0` 并重新运行 `hb-sdk dev`；运行期间在后台调整权限后，请重启 CLI 同步。
+> 兼容范围：公开 SDK API 不变；调整本地真实客户端调试的详情读取与启动票可用条件。
+
+### 行为调整
+
+- `hb-sdk dev` 只在启动、绑定或权限声明变化时读取远端详情；手机重连复用成功快照，票据续签不再触发详情轮询。
+- 权限校验期间或失败后，真实客户端启动票暂停提供；更新声明并校验成功或重启 CLI 后恢复。
+
+### 问题修复
+
+- 修复仅修改小程序绑定时未触发详情校验的问题。
+- 修复声明连续变化时，旧详情、产物摘要或启动票覆盖最新调试状态的问题。
+- 修复详情校验失败后仍能通过本地启动入口获取续签票据的问题。
+
 ## 0.8.5 - 2026-10-02
 
 > 影响级别：必须操作

package/README.md

@@ -26,6 +26,8 @@ npm run dev
 
 脚手架已包含 SDK、Vite 配置和常用开发命令。浏览器调试通过后，再从调试台的二维码入口使用手机小黑盒 APP 验收。
 
+手机二维码的短链先打开普通中间页，再进入专用 dev-shell。最终 `openWindow` 协议会把 CLI 校验后的用户小程序字符串 ID（UUID）写入根字段 `user_miniprogram_id`；原生不会从 URL 查询参数补读，也不能用传统小程序数字 ID 代替。匿名调试不生成小程序 ID，原生未开放的横屏能力仍返回 `supported: false`。入口排查与验证记录见 [Android 396 入口审计](./docs/android-396-launch-identity.md)。
+
 当前 `0.8` 已发布为稳定版本，创建命令使用 `@latest`。
 
 ### 接入已有项目

package/dist/cli-chunks/{build-zYnPSPFa.cjs → build-BSeiFi0q.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-Bs_JqpTM.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-B-GwDDT7.cjs');
 require('node:crypto');
 require('node:zlib');
-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');
+var runtimeGate = require('./runtime-gate-BfAGMrE2.cjs');
+var index = require('./index-d1cUUoR9.cjs');
+var projectVite = require('./project-vite-BM7D-pf6.cjs');
+require('./version-hsUgRL0I.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');

package/dist/cli-chunks/{context-DWoKsM_O.cjs → context-D_L2-Hla.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-Bs_JqpTM.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-B-GwDDT7.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var session = require('./session-CbisOcE4.cjs');
+var session = require('./session-mMVA3395.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);

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

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

@@ -1,9 +1,9 @@
 'use strict';
 
-var context = require('./context-DWoKsM_O.cjs');
+var context = require('./context-D_L2-Hla.cjs');
 var node_crypto = require('node:crypto');
 var fs = require('node:fs');
-var runtimePermissionEnv = require('./runtime-permission-env-Bs_JqpTM.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-B-GwDDT7.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-Brq_-WV3.cjs');
+var index = require('./index-d1cUUoR9.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-CbisOcE4.cjs');
+var session = require('./session-mMVA3395.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-TFEwLzYM.cjs');
-var version = require('./version-UEmqQ6A-.cjs');
+var projectVite = require('./project-vite-BM7D-pf6.cjs');
+var version = require('./version-hsUgRL0I.cjs');
 require('node:zlib');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -1871,7 +1871,8 @@ function createMiniProgramDevShellOpenWindowPayload(appUrl, options) {
         protocol_type: 'openWindow',
         full_screen: true,
         mini_program: '1',
-        ...(miniProgramId ? { mini_program_id: miniProgramId } : {}),
+        // 保留既有调试入口字段，同时通过 user_miniprogram_id 传递用户小程序字符串 ID（UUID）；原生不会从 URL 补读。
+        ...(miniProgramId ? { mini_program_id: miniProgramId, user_miniprogram_id: miniProgramId } : {}),
         navigation_bar: { title: '' },
         webview: { url: devShellUrl, pull: false, refresh: false },
     };
@@ -1992,8 +1993,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-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 { 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-DQ7k_fu6.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-DQ7k_fu6.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'),
@@ -5065,9 +5066,9 @@ const DEFAULT_RUNTIME_SANITIZE_MAX_DEPTH = 6;
  */
 const DEFAULT_RUNTIME_SANITIZE_MAX_ARRAY_LENGTH = 50;
 /**
- * 默认最大字符串长度。
+ * 默认不限制字符串长度，避免截断诊断 JSON 或错误现场。
  */
-const DEFAULT_RUNTIME_SANITIZE_MAX_STRING_LENGTH = 2000;
+const DEFAULT_RUNTIME_SANITIZE_MAX_STRING_LENGTH = Number.POSITIVE_INFINITY;
 /**
  * 判断未知值是否为普通对象。
  *
@@ -9448,10 +9449,6 @@ const MAX_DEPTH = 6;
  * 最大数组长度。
  */
 const MAX_ARRAY_LENGTH = 50;
-/**
- * 最大字符串长度。
- */
-const MAX_STRING_LENGTH = 2000;
 /**
  * 安全序列化错误对象。
  *
@@ -9493,7 +9490,7 @@ function sanitizeTelemetryValue(value, key = '', depth = 0, seen = new WeakSet()
         return value;
     }
     if (typeof value === 'string') {
-        return value.length > MAX_STRING_LENGTH ? `${value.slice(0, MAX_STRING_LENGTH)}...` : value;
+        return value;
     }
     if (typeof value === 'bigint') {
         return value.toString();
@@ -11092,7 +11089,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-DMvmTtIS.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-CerEC339.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -15218,7 +15215,7 @@ 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';
@@ -15244,7 +15241,10 @@ const DEV_CONTEXT_RATE_LIMIT_CACHE_MAX_MS = 300_000;
  * `hb-sdk dev` 启动拖住几分钟却依然恢复不了。
  */
 const DEV_CONTEXT_STARTUP_RATE_LIMIT_WAIT_MAX_MS = 30_000;
-/** 读取 Dev Context 缓存 TTL；非法值回落到默认 30s，0 表示关闭缓存。 */
+/** 新声明已替代在途请求；旧结果不应用，也不作为远端失败提示。 */
+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() === '')
@@ -15394,12 +15394,16 @@ async function runDevCommand(options, runtime = {}) {
      * 读取 Dev Context。
      *
      * key 里带上当前 `package.json` 绑定的 miniProgramId：项目绑定变更会直接换成另一个缓存 key，
-     * 立即重新请求远端，而不是等 30s TTL（限流时 300s）过期后才发现换了小程序。
+     * 立即重新请求远端，而不是等缓存过期后才发现换了小程序。
      * 读绑定是本地文件读取，不打远端，符合「只读本地快照」的高频读范式。
      */
-    const readDevLaunchContext = async () => {
+    const readDevLaunchContext = async (reuseSnapshot = false) => {
         const boundMiniProgramId = await context.readBoundMiniProgramId(projectRoot).catch(() => undefined);
-        return devContextCache.read(`${projectRoot}\0${boundMiniProgramId ?? ''}`);
+        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 = '';
@@ -15435,6 +15439,7 @@ async function runDevCommand(options, runtime = {}) {
         }
     }
     let currentDevContext = devLaunchContext;
+    let devContextGeneration = 0;
     let contextRevision = 1;
     let launchRuntimePermissions = context.createMobileDevSessionRuntimePermissions(devLaunchContext);
     const mobileDevContextUrlsByOrigin = new Map();
@@ -15569,7 +15574,10 @@ async function runDevCommand(options, runtime = {}) {
             },
             readMobileDevSessionContext: async () => {
                 if (currentDevContext.source === 'remote') {
-                    const refreshed = await readDevLaunchContext();
+                    const generation = devContextGeneration;
+                    const refreshed = await readDevLaunchContext(true);
+                    if (generation !== devContextGeneration)
+                        return currentDevContext;
                     if (refreshed.context.rateLimit?.limited) {
                         // 被限流时不再替换上下文，只透出限流状态；手机端据此停止重连。
                         applyRateLimitState(refreshed.context.rateLimit);
@@ -15613,7 +15621,10 @@ async function runDevCommand(options, runtime = {}) {
             companionDeclared: currentDevContext.declaredPermissions?.companion?.enabled === true && runtimePermissionEnv.hasMiniappDesktopPlatform(currentDevContext.platforms),
             miniProgramId: devLaunchContext.miniProgramId,
             refreshPermissions: async () => {
+                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);
@@ -15644,7 +15655,10 @@ async function runDevCommand(options, runtime = {}) {
             },
             onReadiness: devReadiness => browserDevHost.updateBootstrap({ devReadiness }),
             // 主动失效：项目绑定变更或开发者点重试后立即重新请求（key 会带上新绑定，这里清空全部）。
-            onInvalidate: () => devContextCache.invalidate(),
+            onInvalidate: () => {
+                devContextGeneration += 1;
+                devContextCache.invalidate();
+            },
             // 限流状态与恢复都要透出给调试页与宿主页。
             onRateLimit: state => applyRateLimitState(state),
             projectRoot,
@@ -15674,10 +15688,11 @@ async function runDevCommand(options, runtime = {}) {
      * `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),
-        context.readBoundMiniProgramId(projectRoot),
+        readBindingFingerprint(),
     ]);
     // 先记录启动时已生效的声明，这样与调试声明无关的写入（版本号、依赖等）不会触发远端刷新。
     try {
@@ -15692,7 +15707,7 @@ async function runDevCommand(options, runtime = {}) {
             const local = runtimePermissionEnv.readMiniappPermissionsFromPackageJson(projectRoot, runtimePermissionEnv.resolveMiniappSdkVersion());
             const platforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
             // 与调试声明无关的写入（版本号、依赖等）不触发远端刷新。
-            const fingerprint = JSON.stringify([local.permissions ?? null, platforms, context.readBoundMiniProgramId(projectRoot)]);
+            const fingerprint = JSON.stringify([local.permissions ?? null, platforms, readBindingFingerprint()]);
             if (fingerprint === lastDeclarationFingerprint)
                 return;
             lastDeclarationFingerprint = fingerprint;
@@ -16093,14 +16108,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;
     let consecutiveFailures = 0;
-    const getTicket = async (companionManifestSha256) => {
+    const acquireTicket = async (companionManifestSha256) => {
         if (closed)
             return undefined;
         if (ticket && (companionManifestSha256 === undefined || ticket.companionManifestSha256 === companionManifestSha256) && ticket.refreshAt > Date.now())
@@ -16110,11 +16128,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)
@@ -16122,16 +16143,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) {
-                // A-3：无论成败都推进，否则权限刷新失败后每一轮重试都会再打一次远端 detail。
-                permissionsRefreshAt = Date.now() + 30_000;
-                companionDeclared = await options.refreshPermissions();
+            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 {
@@ -16144,44 +16199,51 @@ 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) {
+            if (consecutiveFailures > 0 && !permissionsRefreshFailure) {
                 consecutiveFailures = 0;
                 options.onRateLimit?.(null);
             }
         }
         catch (error) {
-            if (closed)
+            if (closed || generation !== permissionsGeneration || error instanceof DevContextSupersededError)
                 return;
             // A2 + A3：限流类错误走 30s 起、上限 300s 的退避，并明确提示不要反复重启。
             const rateLimitState = index.readCliRateLimitState(error);
@@ -16207,6 +16269,12 @@ function startLocalDevLaunchTokenSession(options) {
         }
         finally {
             refreshing = false;
+            // 请求期间有新声明时立即处理最新一代，避免被并发保护丢掉刷新事件。
+            if (permissionsRefreshPending && !closed) {
+                if (refreshTimer)
+                    clearTimeout(refreshTimer);
+                schedule(0);
+            }
         }
     };
     const schedule = (delayMs) => {
@@ -16235,7 +16303,10 @@ function startLocalDevLaunchTokenSession(options) {
         refresh: () => {
             // 项目绑定变更或开发者主动重试：主动失效 Dev Context 缓存后立即重新请求。
             options.onInvalidate?.();
-            permissionsRefreshAt = 0;
+            permissionsGeneration += 1;
+            permissionsRefreshPending = true;
+            ticket = undefined;
+            pending = undefined;
             publishedDigest = undefined;
             if (refreshTimer)
                 clearTimeout(refreshTimer);

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

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

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

package/dist/cli-chunks/{index-Brq_-WV3.cjs → index-d1cUUoR9.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-Brq_-WV3.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-d1cUUoR9.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-Brq_-WV3.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-d1cUUoR9.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-Brq_-WV3.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-d1cUUoR9.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-Brq_-WV3.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-d1cUUoR9.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-Brq_-WV3.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-d1cUUoR9.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -13554,7 +13554,7 @@ function getPathname(pathWithQuery) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.8.5';
+const BUILT_CLI_VERSION = '0.9.0-alpha.1';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13913,39 +13913,39 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-DeZpNrkY.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-lZKDg_9k.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-DeZpNrkY.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-lZKDg_9k.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-DeZpNrkY.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-lZKDg_9k.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunBuildCommand = async (...args) => {
-    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-zYnPSPFa.cjs'); });
+    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-BSeiFi0q.cjs'); });
     return runBuildCommand(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-C9FcEn9Y.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-Dzeodh_-.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-VxeEocjt.cjs'); }).then(function (n) { return n.dev; });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DQ7k_fu6.cjs'); }).then(function (n) { return n.dev; });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-6Cf9o1hD.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-FIcFZiJ0.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunSkillInstallCommand = async (...args) => {
-    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-B82gXQhX.cjs'); });
+    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-BhUlKvyY.cjs'); });
     return runSkillInstallCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-DOU11SNj.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-9-tyxq6l.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{index.esm-DMvmTtIS.cjs → index.esm-CerEC339.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-Brq_-WV3.cjs');
-var dev = require('./dev-VxeEocjt.cjs');
+var index = require('./index-d1cUUoR9.cjs');
+var dev = require('./dev-DQ7k_fu6.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-DWoKsM_O.cjs');
-require('./runtime-permission-env-Bs_JqpTM.cjs');
-require('./version-UEmqQ6A-.cjs');
+require('./context-D_L2-Hla.cjs');
+require('./runtime-permission-env-B-GwDDT7.cjs');
+require('./version-hsUgRL0I.cjs');
 require('node:async_hooks');
 require('sharp');
-require('./session-CbisOcE4.cjs');
+require('./session-mMVA3395.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-TFEwLzYM.cjs');
+require('./project-vite-BM7D-pf6.cjs');
 require('node:zlib');
 
 var bufferUtil = {exports: {}};

package/dist/cli-chunks/{login-DeZpNrkY.cjs → login-lZKDg_9k.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-CbisOcE4.cjs');
+var session = require('./session-mMVA3395.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-Brq_-WV3.cjs');
+var index = require('./index-d1cUUoR9.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{project-vite-TFEwLzYM.cjs → project-vite-BM7D-pf6.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-Brq_-WV3.cjs');
+var index = require('./index-d1cUUoR9.cjs');
 
 function findProjectRoot(startDir) {
     let current = path.resolve(startDir);