@heybox/hb-sdk 0.6.3 → 0.6.4-alpha.0

package/README.md

@@ -57,7 +57,9 @@ SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注
 npm run dev
 ```
 
-调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；浏览器 Mock 从 mock host 的同源只读 bootstrap 接口读取服务端保留的 Runtime 权限快照，URL query 不能提供或覆盖权限。项目已绑定 `heybox.miniProgramId` 时，可以点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码；真机 dev shell 只携带绑定的小程序 ID 和本地页面地址，H5 宿主按 ID 从公开详情接口读取可信 Runtime 权限快照。项目未绑定时仍可使用默认拒绝受管能力的浏览器 Mock，但 Mac 和手机真机入口会明确提示先运行 `hb-sdk remote create` 或 `hb-sdk remote bind <mini-program-id>`，并保持不可用。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境。`hb-sdk dev` 的基础启动只依赖本地页面地址：即使项目未绑定、CLI 未登录或远端暂时不可用，浏览器 Mock、Mac 启动协议和手机二维码也会继续生成，真机 dev shell 以匿名本地沙箱加载 `mini_url`，不会把公开 `detail` 查询作为启动门禁。项目已绑定时会限时 3 秒读取远端 dev context；成功后 Mock Host 用真实 Runtime 权限快照初始化本地模拟，失败或超时则显示脱敏警告，并默认拒绝 `network.request` 等受管能力。
+
+Mock Host 可以在内存中调整 devtools-only 权限模拟，不会重建 iframe，因此不影响 Vite HMR；本地设置不会修改线上权限。调试页会对比已读取的线上快照，提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。权限快照只通过 mock host 的同源只读 bootstrap 接口传递，URL query 不能提供或覆盖权限。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
 

package/dist/cli-chunks/{context-Bu0Zusj_.cjs → context-BCwksd8H.cjs}

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

package/dist/cli-chunks/{create-CgAGcRtZ.cjs → create-BO8GHVi0.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--P321c8v.cjs');
+var index = require('./index-Q0G1SsEs.cjs');
 require('node:module');
 require('os');
 require('readline');

package/dist/cli-chunks/{dev-g35-QcIa.cjs → dev-DmgKnEC2.cjs}

@@ -9,8 +9,8 @@ var node_url = require('node:url');
 var net = require('node:net');
 var node_http = require('node:http');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index--P321c8v.cjs');
-var context = require('./context-Bu0Zusj_.cjs');
+var index = require('./index-Q0G1SsEs.cjs');
+var context = require('./context-BCwksd8H.cjs');
 require('node:process');
 require('node:buffer');
 require('node:util');
@@ -24,7 +24,7 @@ require('events');
 require('stream');
 require('buffer');
 require('util');
-require('./session-vlPGi1Z8.cjs');
+require('./session-CC3Oz3Xc.cjs');
 require('node:crypto');
 require('fs');
 require('constants');
@@ -223,6 +223,7 @@ async function startMiniProgramMockHostServer(options) {
     assertCompleteMiniProgramMockHostRoot(root);
     const bootstrapJson = serializeMockHostBootstrap({
         defaultLanAddressId: options.defaultLanAddressId,
+        devContext: options.devContext,
         lanAddresses: options.lanAddresses ?? [],
         macAppProtocol: options.macAppProtocol,
         nativeAppLaunchUnavailableReason: options.nativeAppLaunchUnavailableReason,
@@ -669,12 +670,14 @@ function createHeyboxProtocol(payload) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.3';
+    : '0.6.4-alpha.0';
 
 const DEFAULT_APP_PORT = 5173;
 const DEFAULT_MOCK_PORT = 5174;
+const DEFAULT_DEV_CONTEXT_TIMEOUT_MS = 3000;
 const DEV_LISTEN_HOST = '0.0.0.0';
 const LOCAL_DEV_URL_HOST = '127.0.0.1';
+const DEV_CONTEXT_UNAVAILABLE_WARNING = '远端 dev context 不可用，已继续匿名调试。';
 // Shared with Heybox H5 Vite plugins so hb-sdk can own the launch output.
 const MANAGED_DEV_OUTPUT_ENV = 'HEYBOX_DEV_SERVER_MANAGED_OUTPUT';
 const VITE_LOG_LEVEL = 'warn';
@@ -701,6 +704,7 @@ async function runDevCommand(options, runtime = {}) {
         fetchImpl,
         logger,
         projectRoot,
+        timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
     });
     const vite = await logger.task('正在加载项目 Vite', () => loadProjectVite(projectRoot), { successText: '已加载项目 Vite' });
     const appServer = await logger.task('正在创建 Vite dev server', () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions)), runtime.env), { successText: '已创建 Vite dev server' });
@@ -724,18 +728,16 @@ async function runDevCommand(options, runtime = {}) {
     try {
         mockHost = await logger.task('正在启动 Mock runtime host', () => startMiniProgramMockHostServer({
             appUrl,
+            devContext: devLaunchContext,
             fetchImpl,
             getPort: getPortImpl,
             defaultLanAddressId: lanAddresses[0]?.id,
             lanAddresses,
-            macAppProtocol: devLaunchContext.miniProgramId
-                ? createMacAppProtocol(appUrl, {
-                    miniProgramId: devLaunchContext.miniProgramId,
-                    runtimeUrl: options.runtimeUrl,
-                    sdkVersion: HB_SDK_VERSION,
-                })
-                : undefined,
-            nativeAppLaunchUnavailableReason: devLaunchContext.nativeAppLaunchUnavailableReason,
+            macAppProtocol: createMacAppProtocol(appUrl, {
+                miniProgramId: devLaunchContext.miniProgramId,
+                runtimeUrl: options.runtimeUrl,
+                sdkVersion: HB_SDK_VERSION,
+            }),
             port: options.mockPort ?? DEFAULT_MOCK_PORT,
             root: runtime.mockHostRoot,
             rootCandidates: runtime.mockHostRootCandidates,
@@ -750,12 +752,10 @@ async function runDevCommand(options, runtime = {}) {
     logger.success('Mock runtime host 已就绪');
     logger.info(`Mock runtime host: ${mockHost.url}`);
     logger.info(`Mini program URL: ${appUrl}`);
-    if (devLaunchContext.miniProgramId) {
-        logger.info('Mac APP: use the button in Mock runtime host');
-        logger.info('Mobile APP: scan the QR code in Mock runtime host');
-    }
-    else {
-        logger.warn(`Mac/Mobile APP 真机调试不可用：${devLaunchContext.nativeAppLaunchUnavailableReason}`);
+    logger.info('Mac APP: use the button in Mock runtime host');
+    logger.info('Mobile APP: scan the QR code in Mock runtime host');
+    if (devLaunchContext.source === 'anonymous') {
+        logger.warn('当前使用匿名本地沙箱；真机调试可用，但不会携带远端小程序身份或权限。');
     }
     if (options.open !== false) {
         logger.debug('正在打开浏览器调试页');
@@ -766,40 +766,61 @@ async function runDevCommand(options, runtime = {}) {
 async function loadDevLaunchContext(options) {
     const miniProgramId = await context.readBoundMiniProgramId(options.projectRoot);
     if (!miniProgramId) {
-        const nativeAppLaunchUnavailableReason = '当前项目未绑定小程序。请先运行 hb-sdk remote create 或 hb-sdk remote bind <mini-program-id>。';
-        options.logger.warn(`未读取到远端 Runtime 权限，Mock runtime 将默认拒绝受管能力：${nativeAppLaunchUnavailableReason}`);
-        return { nativeAppLaunchUnavailableReason };
+        const anonymousReason = '当前项目未绑定小程序。请先运行 hb-sdk remote create 或 hb-sdk remote bind <mini-program-id>。';
+        options.logger.warn(`未读取到远端 Runtime 权限，Mock runtime 将默认拒绝受管能力：${anonymousReason}`);
+        return {
+            source: 'anonymous',
+            warning: anonymousReason,
+        };
     }
     try {
-        const { detail, miniProgramId: verifiedMiniProgramId } = await options.logger.task('正在读取远端小程序权限', () => context.getBoundMiniProgram({
-            cwd: options.projectRoot,
-            env: options.env,
+        const { detail, miniProgramId: verifiedMiniProgramId } = await options.logger.task('正在读取远端小程序权限', () => loadRemoteDevContextWithTimeout({
             fetchImpl: options.fetchImpl,
+            load: fetchImpl => context.getBoundMiniProgram({
+                cwd: options.projectRoot,
+                env: options.env,
+                fetchImpl,
+            }),
+            timeoutMs: options.timeoutMs,
         }), { successText: '已读取远端小程序权限' });
-        return { miniProgramId: verifiedMiniProgramId, runtimePermissions: detail.runtime_permissions };
+        return {
+            source: 'remote',
+            miniProgramId: verifiedMiniProgramId,
+            runtimePermissions: detail.runtime_permissions,
+        };
     }
     catch (error) {
-        if (!canFallbackToDefaultRuntimePermissions(error)) {
+        if (error instanceof context.MiniProgramProjectBindingError &&
+            error.code !== 'MINI_PROGRAM_UNBOUND') {
             throw error;
         }
-        options.logger.warn(`未读取到远端 Runtime 权限，Mock runtime 将默认拒绝受管能力：${index.readErrorMessage(error)}`);
+        options.logger.warn(`未读取到远端 Runtime 权限，Mock runtime 将默认拒绝受管能力：${DEV_CONTEXT_UNAVAILABLE_WARNING}`);
         return {
-            nativeAppLaunchUnavailableReason: '当前绑定尚未通过开发者权限验证。请先运行 hb-sdk login，并确认网络可用后重试。',
+            source: 'anonymous',
+            warning: DEV_CONTEXT_UNAVAILABLE_WARNING,
         };
     }
 }
-function canFallbackToDefaultRuntimePermissions(error) {
-    if (error instanceof context.MiniProgramProjectBindingError) {
-        return error.code === 'MINI_PROGRAM_UNBOUND';
-    }
-    if (error instanceof TypeError && error.message === 'fetch failed') {
-        return true;
+async function loadRemoteDevContextWithTimeout(options) {
+    const controller = new AbortController();
+    const fetchImpl = ((input, init) => options.fetchImpl(input, { ...init, signal: controller.signal }));
+    let timeout;
+    try {
+        return await Promise.race([
+            options.load(fetchImpl),
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error('dev context timeout'));
+                }, Math.max(1, options.timeoutMs));
+            }),
+        ]);
     }
-    if (error instanceof index.CliError) {
-        return (error.httpStatus === 429 ||
-            (error.httpStatus !== undefined && error.httpStatus >= 500 && error.httpStatus < 600));
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
     }
-    return error instanceof Error && 'code' in error && error.code === 'AUTH_SESSION_MISSING';
 }
 function findProjectRoot(startDir) {
     let current = path.resolve(startDir);
@@ -984,9 +1005,6 @@ async function closeAll(closers) {
     await Promise.allSettled(closers.map((close) => close()));
 }
 function createLanAddressCandidates(options) {
-    if (!options.miniProgramId) {
-        return [];
-    }
     const viteNetworkUrlByHost = new Map(options.viteNetworkUrls
         .map((url) => [readUrlHost(url), url])
         .filter((entry) => Boolean(entry[0])));

package/dist/cli-chunks/{doctor-klsQg82G.cjs → doctor-BlKB4f78.cjs}

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

package/dist/cli-chunks/{index-CbsbCgtf.cjs → index-PxkpQ5of.cjs}

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

package/dist/cli-chunks/{index--P321c8v.cjs → index-Q0G1SsEs.cjs}

@@ -234,19 +234,19 @@ function requireArgument () {
 
 var command = {};
 
-const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index--P321c8v.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-Q0G1SsEs.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--P321c8v.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-Q0G1SsEs.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--P321c8v.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-Q0G1SsEs.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--P321c8v.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-Q0G1SsEs.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--P321c8v.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-Q0G1SsEs.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -13323,7 +13323,7 @@ function getPathname(pathWithQuery) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.6.3';
+const BUILT_CLI_VERSION = '0.6.4-alpha.0';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13644,31 +13644,31 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-DEoReXOe.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-Cxdo4B6Z.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-DEoReXOe.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-Cxdo4B6Z.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-DEoReXOe.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-Cxdo4B6Z.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-CgAGcRtZ.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-BO8GHVi0.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-g35-QcIa.cjs'); });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DmgKnEC2.cjs'); });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-klsQg82G.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-BlKB4f78.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-CZ-G3RSH.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-C1Rsb1dx.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{login-DEoReXOe.cjs → login-Cxdo4B6Z.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-vlPGi1Z8.cjs');
+var session = require('./session-CC3Oz3Xc.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index--P321c8v.cjs');
+var index = require('./index-Q0G1SsEs.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{remote-CZ-G3RSH.cjs → remote-C1Rsb1dx.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
 var promises = require('node:readline/promises');
-var index = require('./index--P321c8v.cjs');
-var session = require('./session-vlPGi1Z8.cjs');
+var index = require('./index-Q0G1SsEs.cjs');
+var session = require('./session-CC3Oz3Xc.cjs');
 var childProcess = require('node:child_process');
 var fs = require('node:fs');
 var fs$1 = require('node:fs/promises');
 var path = require('node:path');
-var context = require('./context-Bu0Zusj_.cjs');
+var context = require('./context-BCwksd8H.cjs');
 require('node:module');
 require('path');
 require('os');
@@ -264,7 +264,7 @@ async function createDefaultCosClient(uploadToken) {
     };
 }
 async function loadCosConstructor() {
-    const cosModule = await Promise.resolve().then(function () { return require('./index-CbsbCgtf.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-PxkpQ5of.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {

package/dist/cli-chunks/{session-vlPGi1Z8.cjs → session-CC3Oz3Xc.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index--P321c8v.cjs');
+var index = require('./index-Q0G1SsEs.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');

package/dist/cli.cjs

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

package/dist/devtools/mock-host/index.html

@@ -20,7 +20,8 @@
       }
 
       button,
-      input {
+      input,
+      select {
         font: inherit;
       }
 
@@ -190,6 +191,38 @@
         background: #fff;
       }
 
+      .inline-field {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        margin-top: 10px;
+        color: #475569;
+        font-size: 13px;
+      }
+
+      .inline-field input {
+        width: 16px;
+        height: 16px;
+        margin: 0;
+      }
+
+      .release-diagnostics {
+        display: grid;
+        gap: 6px;
+        margin: 10px 0 0;
+        padding: 0;
+        list-style: none;
+      }
+
+      .release-diagnostics li {
+        border-left: 3px solid #d97706;
+        padding: 7px 8px;
+        color: #92400e;
+        background: #fffbeb;
+        font-size: 12px;
+        line-height: 1.5;
+      }
+
       .mobile-qr {
         display: grid;
         justify-items: center;
@@ -353,6 +386,26 @@
           <strong id="mini-url"></strong>
         </section>
 
+        <section class="block">
+          <span>Dev Context</span>
+          <strong id="dev-context-status"></strong>
+          <label class="field" style="margin-top: 10px">
+            <span>network.request</span>
+            <select id="network-permission-select">
+              <option value="disabled">拒绝</option>
+              <option value="enabled">允许</option>
+            </select>
+          </label>
+          <label class="inline-field">
+            <input id="official-domain-checkbox" type="checkbox" />
+            <span>允许访问小黑盒官方域名</span>
+          </label>
+          <div class="actions" style="margin-top: 10px">
+            <button id="reset-permissions-button" type="button">恢复初始权限</button>
+          </div>
+          <ul class="release-diagnostics" id="release-diagnostics"></ul>
+        </section>
+
         <section class="csp-violations" id="csp-violations" hidden>
           <strong>网络或资源请求已被 CSP 阻止</strong>
         </section>

package/dist/devtools/mock-host/main.js

@@ -3445,6 +3445,120 @@ function formatBlockedResource(payload) {
     return '未知资源';
 }
 
+const DEFAULT_PERMISSION_STATE = {
+    networkRequest: {
+        status: 'disabled',
+        useOfficialDomain: false,
+    },
+};
+function createMiniProgramMockPermissionState(context) {
+    const parsed = parseRuntimePermissions(context.runtimePermissions);
+    return parsed.valid && parsed.networkRequest
+        ? { networkRequest: { ...parsed.networkRequest } }
+        : cloneDefaultPermissionState();
+}
+function createMiniProgramMockRuntimePermissions(state) {
+    return {
+        schema_version: 1,
+        entries: [
+            {
+                key: 'network.request',
+                status: state.networkRequest.status,
+                config: {
+                    useOfficialDomain: state.networkRequest.useOfficialDomain,
+                },
+            },
+        ],
+    };
+}
+function createMiniProgramDevReleaseDiagnostics(context, localState) {
+    if (context.source === 'anonymous') {
+        return [
+            {
+                code: 'REMOTE_CONTEXT_UNAVAILABLE',
+                severity: 'warning',
+                message: `未获取到线上权限配置，本地模拟不代表上线状态${context.warning ? `：${context.warning}` : ''}`,
+            },
+        ];
+    }
+    const parsedRemote = parseRuntimePermissions(context.runtimePermissions);
+    if (!parsedRemote.valid) {
+        return [
+            {
+                code: 'REMOTE_PERMISSIONS_INVALID',
+                severity: 'warning',
+                message: '线上权限配置不可用，本地模拟不代表上线状态。',
+            },
+        ];
+    }
+    const remoteState = parsedRemote.networkRequest ?? DEFAULT_PERMISSION_STATE.networkRequest;
+    if (localState.networkRequest.status === 'enabled' &&
+        remoteState.status !== 'enabled') {
+        return [
+            {
+                code: 'NETWORK_REQUEST_DISABLED_ONLINE',
+                severity: 'warning',
+                message: '当前本地允许 network.request，但线上权限已关闭；上线后请求会返回 PERMISSION_DENIED。',
+            },
+        ];
+    }
+    if (localState.networkRequest.status === 'enabled' &&
+        localState.networkRequest.useOfficialDomain &&
+        !remoteState.useOfficialDomain) {
+        return [
+            {
+                code: 'OFFICIAL_DOMAIN_DISABLED_ONLINE',
+                severity: 'warning',
+                message: '当前本地允许访问小黑盒官方域名，但线上权限未开放；上线后相关请求会返回 PERMISSION_DENIED。',
+            },
+        ];
+    }
+    return [];
+}
+function parseRuntimePermissions(snapshot) {
+    if (!isRecord$2(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false };
+    }
+    if (snapshot.revision !== undefined &&
+        (typeof snapshot.revision !== 'number' ||
+            !Number.isInteger(snapshot.revision) ||
+            snapshot.revision < 0)) {
+        return { valid: false };
+    }
+    const seenKeys = new Set();
+    let networkRequest;
+    for (const entry of snapshot.entries) {
+        if (!isRecord$2(entry) || typeof entry.key !== 'string' || !entry.key.trim()) {
+            return { valid: false };
+        }
+        const key = entry.key.trim();
+        if (seenKeys.has(key) ||
+            (entry.status !== 'enabled' && entry.status !== 'disabled') ||
+            !isRecord$2(entry.config)) {
+            return { valid: false };
+        }
+        seenKeys.add(key);
+        if (key === 'network.request') {
+            if (typeof entry.config.useOfficialDomain !== 'boolean') {
+                return { valid: false };
+            }
+            networkRequest = {
+                status: entry.status,
+                useOfficialDomain: entry.config.useOfficialDomain,
+            };
+        }
+    }
+    return { valid: true, networkRequest };
+}
+function cloneDefaultPermissionState() {
+    return {
+        networkRequest: { ...DEFAULT_PERMISSION_STATE.networkRequest },
+    };
+}
+function isRecord$2(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 async function getMiniProgramRuntimeUserInfo(platformAdapter) {
     const userId = await resolveCurrentUserId(platformAdapter);
     if (!userId) {
@@ -6306,6 +6420,7 @@ const elements = {
     cspViolations: queryElement('#csp-violations'),
     debugPageCopyStatus: queryElement('#debug-page-copy-status'),
     debugPageUrl: queryElement('#debug-page-url'),
+    devContextStatus: queryElement('#dev-context-status'),
     device: queryElement('#device'),
     logs: queryElement('#logs'),
     macAppButton: queryElement('#mac-app-button'),
@@ -6315,6 +6430,10 @@ const elements = {
     mobileQrImage: queryElement('#mobile-qr-image'),
     mobileQrStatus: queryElement('#mobile-qr-status'),
     nicknameInput: queryElement('#nickname-input'),
+    networkPermissionSelect: queryElement('#network-permission-select'),
+    officialDomainCheckbox: queryElement('#official-domain-checkbox'),
+    releaseDiagnostics: queryElement('#release-diagnostics'),
+    resetPermissionsButton: queryElement('#reset-permissions-button'),
     storageSnapshot: queryElement('#storage-snapshot'),
     userStatus: queryElement('#user-status'),
 };
@@ -6325,13 +6444,15 @@ if (!miniUrl) {
 }
 const miniProgramUrl = miniUrl;
 const bootstrap = await loadMockHostBootstrap();
-const runtimePermissions = bootstrap.runtimePermissions;
+const devContext = bootstrap.devContext;
+const initialPermissionState = createMiniProgramMockPermissionState(devContext);
+let permissionState = clonePermissionState(initialPermissionState);
 const iframe = document.createElement('iframe');
 iframe.src = appendNonce(miniProgramUrl, nonce);
 iframe.allow = 'clipboard-read; clipboard-write';
 elements.device.appendChild(iframe);
 elements.miniUrl.textContent = miniProgramUrl;
-const runtime = new MiniProgramMockRuntime(createBrowserMockRuntimePlatformAdapter({
+const platformAdapter = createBrowserMockRuntimePlatformAdapter({
     iframe,
     getCurrentHref: () => location.href,
     getCurrentUser: () => currentUser,
@@ -6353,12 +6474,11 @@ const runtime = new MiniProgramMockRuntime(createBrowserMockRuntimePlatformAdapt
         storage.set(key, value);
         updateStorageSnapshot();
     },
-}), {
-    onAuthChange: (result) => postEvent('authChange', result),
-    runtimePermissions,
 });
+let runtime = createRuntime();
 updateUserStatus();
 updateStorageSnapshot();
+updatePermissionControls();
 window.addEventListener('message', handleMessage);
 window.addEventListener('beforeunload', () => {
     postEvent('unload', { timestamp: Date.now() });
@@ -6386,7 +6506,48 @@ elements.copyDebugPageUrlButton.addEventListener('click', () => {
 elements.mobileLanSelect.addEventListener('change', () => {
     void updateMobileQrCode();
 });
+elements.networkPermissionSelect.addEventListener('change', () => {
+    permissionState.networkRequest.status =
+        elements.networkPermissionSelect.value === 'enabled' ? 'enabled' : 'disabled';
+    rebuildRuntimeWithPermissions();
+});
+elements.officialDomainCheckbox.addEventListener('change', () => {
+    permissionState.networkRequest.useOfficialDomain = elements.officialDomainCheckbox.checked;
+    rebuildRuntimeWithPermissions();
+});
+elements.resetPermissionsButton.addEventListener('click', () => {
+    permissionState = clonePermissionState(initialPermissionState);
+    rebuildRuntimeWithPermissions();
+});
 const mobileAppQrReady = setupMobileAppQr();
+function createRuntime() {
+    return new MiniProgramMockRuntime(platformAdapter, {
+        onAuthChange: (result) => postEvent('authChange', result),
+        runtimePermissions: createMiniProgramMockRuntimePermissions(permissionState),
+    });
+}
+function rebuildRuntimeWithPermissions() {
+    runtime = createRuntime();
+    updatePermissionControls();
+}
+function updatePermissionControls() {
+    elements.devContextStatus.textContent =
+        devContext.source === 'remote'
+            ? `已连接线上配置${devContext.miniProgramId ? ` · ${devContext.miniProgramId}` : ''}`
+            : '匿名本地沙箱';
+    elements.networkPermissionSelect.value = permissionState.networkRequest.status;
+    elements.officialDomainCheckbox.checked = permissionState.networkRequest.useOfficialDomain;
+    elements.officialDomainCheckbox.disabled = permissionState.networkRequest.status !== 'enabled';
+    const diagnostics = createMiniProgramDevReleaseDiagnostics(devContext, permissionState);
+    elements.releaseDiagnostics.innerHTML = diagnostics
+        .map((diagnostic) => `<li>${escapeHtml(diagnostic.message)}</li>`)
+        .join('');
+}
+function clonePermissionState(state) {
+    return {
+        networkRequest: { ...state.networkRequest },
+    };
+}
 function handleMessage(event) {
     if (event.source !== iframe.contentWindow || !isBridgeMessage(event.data)) {
         return;
@@ -6599,10 +6760,17 @@ async function loadMockHostBootstrap() {
         });
         const payload = await response.json();
         if (!isRecord(payload)) {
-            return { lanAddresses: [] };
+            return {
+                devContext: {
+                    source: 'anonymous',
+                    warning: 'dev context 响应格式无效。',
+                },
+                lanAddresses: [],
+            };
         }
         return {
             defaultLanAddressId: typeof payload.defaultLanAddressId === 'string' ? payload.defaultLanAddressId : undefined,
+            devContext: readDevContext(payload.devContext, payload.runtimePermissions),
             lanAddresses: Array.isArray(payload.lanAddresses) ? payload.lanAddresses.filter(isLanAddress) : [],
             macAppProtocol: typeof payload.macAppProtocol === 'string' ? payload.macAppProtocol : undefined,
             nativeAppLaunchUnavailableReason: typeof payload.nativeAppLaunchUnavailableReason === 'string'
@@ -6613,11 +6781,33 @@ async function loadMockHostBootstrap() {
     }
     catch {
         return {
+            devContext: {
+                source: 'anonymous',
+                warning: '真机调试配置加载失败，请重启 hb-sdk dev 后重试。',
+            },
             lanAddresses: [],
             nativeAppLaunchUnavailableReason: '真机调试配置加载失败，请重启 hb-sdk dev 后重试。',
         };
     }
 }
+function readDevContext(value, legacyRuntimePermissions) {
+    if (isRecord(value) && value.source === 'remote') {
+        return {
+            source: 'remote',
+            miniProgramId: typeof value.miniProgramId === 'string' ? value.miniProgramId : undefined,
+            runtimePermissions: value.runtimePermissions ?? legacyRuntimePermissions,
+        };
+    }
+    if (isRecord(value) && value.source === 'anonymous') {
+        return {
+            source: 'anonymous',
+            warning: typeof value.warning === 'string' ? value.warning : undefined,
+        };
+    }
+    return legacyRuntimePermissions === undefined
+        ? { source: 'anonymous', warning: '未获取到 dev context。' }
+        : { source: 'remote', runtimePermissions: legacyRuntimePermissions };
+}
 function setupMobileLanSelect() {
     elements.mobileLanSelect.innerHTML = '';
     lanAddresses.forEach((address) => {

package/dist/index.cjs.js

@@ -325,7 +325,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.3';
+    : '0.6.4-alpha.0';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。

package/dist/index.esm.js

@@ -321,7 +321,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.3';
+    : '0.6.4-alpha.0';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。

package/dist/vite.cjs.js

@@ -7,7 +7,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.3';
+    : '0.6.4-alpha.0';
 
 var re = {exports: {}};
 

package/dist/vite.esm.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.3';
+    : '0.6.4-alpha.0';
 
 var re = {exports: {}};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.6.3",
+  "version": "0.6.4-alpha.0",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -92,7 +92,7 @@
     "vue": "^2.7.16",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox/hb-api": "~1.25.1"
+    "@heybox/hb-api": "~1.25.3"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/SKILL.md

@@ -49,7 +49,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 ## Step 5: Use CLI workflows
 
 1. Use `hb-sdk create <project-name>` to scaffold a standalone external mini-program template.
-2. Use `hb-sdk dev` for local browser debugging through the built-in mock runtime host. The project must bind `package.json.heybox.miniProgramId` and the CLI must be logged in so dev can load the real Runtime permission snapshot before starting Vite.
+2. Use `hb-sdk dev` for local browser, Mac App, or mobile App debugging through the built-in mock runtime host. Vite and native dev-shell entrypoints only require the local `mini_url`: a missing project binding, CLI login, remote dev-context failure, or the 3-second context timeout must fall back to an anonymous local sandbox instead of blocking startup. Anonymous mode denies managed capabilities by default. When a verified remote dev context is available, the Mock Host uses its Runtime permission snapshot as the initial local simulation and reports local-versus-online permission differences.
 3. Use `hb-sdk remote ...` for developer-owned remote mini-program management. Top-level `hb-sdk deploy` has been hard-cut and must not be recommended as a compatibility alias.
 4. Use `hb-sdk remote entity list`, `hb-sdk remote entity current`, and `hb-sdk remote entity switch <entity-id>` to inspect or change the developer platform server-side current entity before remote management commands.
 5. Use `hb-sdk remote create` to create a remote mini-program under the server-side current entity and bind the returned id into `package.json.heybox.miniProgramId`; use `hb-sdk remote bind <mini-program-id>` to bind an existing remote mini-program after current-entity manageability is verified. CLI project configuration contains only `package.json.heybox.miniProgramId`; mini-program name, icon, and cover images are maintained on the Open platform version-publish flow. On first submit without prior approved profile, the server injects a default name and default images.
@@ -64,7 +64,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 14. Add `--verbose` / `-v` only when diagnosing failures; default CLI errors are intentionally concise, while verbose output includes backend envelope, HTTP status, trace fields, raw body, or original submit-audit failure details.
 15. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
 16. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
-17. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; the phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
+17. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; these entrypoints remain available in anonymous mode. The phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
 18. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
 19. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
 20. Treat `selectedEntity` in the CLI auth cache as a non-authoritative hint snapshot only. Every remote command must use the server-side current entity as the source of truth.
@@ -93,6 +93,8 @@ For CLI and local development:
 2. Do not use `hb-sdk login` as a workaround for iframe SDK authentication.
 3. Do not bypass `hb-sdk dev` by adding a second browser mock host.
 4. Keep the Vite `miniappManifest()` plugin enabled so builds only start in a compatible APP Runtime. Normal deploy always runs the project build.
+5. Keep Mock Host permission overrides in devtools-only memory. They must not rebuild the iframe, interrupt Vite HMR, mutate online permissions, or be passed through URL query parameters.
+6. Treat remote dev context as optional diagnostics and initialization data. Do not use a public mini-program detail request as a dev startup gate.
 
 For host/runtime/protocol-maintenance code:
 

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.3`
+- Version at generation time: `0.6.4-alpha.0`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -450,7 +450,9 @@ SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注
 npm run dev
 ```
 
-调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；浏览器 Mock 从 mock host 的同源只读 bootstrap 接口读取服务端保留的 Runtime 权限快照，URL query 不能提供或覆盖权限。项目已绑定 `heybox.miniProgramId` 时，可以点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码；真机 dev shell 只携带绑定的小程序 ID 和本地页面地址，H5 宿主按 ID 从公开详情接口读取可信 Runtime 权限快照。项目未绑定时仍可使用默认拒绝受管能力的浏览器 Mock，但 Mac 和手机真机入口会明确提示先运行 `hb-sdk remote create` 或 `hb-sdk remote bind <mini-program-id>`，并保持不可用。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境。`hb-sdk dev` 的基础启动只依赖本地页面地址：即使项目未绑定、CLI 未登录或远端暂时不可用，浏览器 Mock、Mac 启动协议和手机二维码也会继续生成，真机 dev shell 以匿名本地沙箱加载 `mini_url`，不会把公开 `detail` 查询作为启动门禁。项目已绑定时会限时 3 秒读取远端 dev context；成功后 Mock Host 用真实 Runtime 权限快照初始化本地模拟，失败或超时则显示脱敏警告，并默认拒绝 `network.request` 等受管能力。
+
+Mock Host 可以在内存中调整 devtools-only 权限模拟，不会重建 iframe，因此不影响 Vite HMR；本地设置不会修改线上权限。调试页会对比已读取的线上快照，提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。权限快照只通过 mock host 的同源只读 bootstrap 接口传递，URL query 不能提供或覆盖权限。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
 

package/skill/references/cli.md

@@ -103,7 +103,7 @@ Agent rules:
 hb-sdk dev
 ```
 
-`hb-sdk dev` 会从当前目录向上查找最近的 `package.json`，并在项目已绑定且 CLI 已登录时尝试查询真实 Runtime 权限快照。项目未绑定、未登录或远端暂时不可用时，命令会输出警告并继续启动 Vite 和内置 mock runtime host；此时使用缺失权限快照，`network.request` 等受管能力默认拒绝。远端权限读取成功时，mock host 使用真实快照，远端明确关闭的能力仍稳定返回 `PERMISSION_DENIED`。本地 `package.json` 无法解析等配置错误不会被降级，命令会直接报错。调试页默认自动打开；需要真实黑盒小程序容器加载同一页面时，点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码。
+`hb-sdk dev` 会从当前目录向上查找最近的 `package.json`。Vite、内置 mock runtime host、Mac 启动协议和手机二维码的基础启动只依赖本地页面地址，不要求项目先绑定或 CLI 先登录。项目已绑定时，CLI 会限时 3 秒读取远端 dev context；成功后用真实 Runtime 权限快照初始化 Mock Host，失败或超时则输出脱敏警告并继续匿名调试，`network.request` 等受管能力默认拒绝。公开 `detail` 查询不再是 dev 启动门禁。本地 `package.json` 无法解析等配置错误不会被降级，命令会直接报错。调试页默认自动打开；需要真实黑盒小程序容器加载同一页面时，点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码。
 
 常用参数：
 
@@ -116,11 +116,13 @@ hb-sdk dev
 
 ## Mock runtime 边界
 
-`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境；浏览器 Mock 的 Runtime 权限只从 mock host 同源只读 bootstrap 接口读取，URL query 不能提供或覆盖权限。项目已绑定时，Mac 协议和手机二维码会把 `package.json.heybox.miniProgramId` 与本地页面地址交给 dev shell；H5 宿主按该 ID 从公开详情接口读取可信 Runtime 权限快照。项目未绑定时仍可使用默认拒绝受管能力的浏览器 Mock，但 Mac 和手机真机入口会明确提示先运行 `hb-sdk remote create` 或 `hb-sdk remote bind <mini-program-id>`，并保持不可用。mock host 内置登录/登出、`show`、`hide`、在 Mac 版 APP 中启动、手机扫码调试等调试入口，并通过同一份 devtools-only runtime adapter 处理 SDK 能力调用。真实 Mac / Mobile App dev shell 加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境。Mac 协议和手机二维码始终携带本地页面地址；远端 dev context 可用时还会携带已验证的小程序 ID，不可用时则进入匿名本地沙箱。真机 dev shell 不依赖公开 `detail` 查询完成启动。真实 Mac / Mobile App dev shell 加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 不要为了本地调试再创建独立 mock runtime 包。CLI、模板和 mock host 都归属 `@heybox/hb-sdk`。
 
-本地 mock runtime 下已授权的 `network.request()` 会通过 `hb-sdk` 本地 mock network proxy 转发真实 HTTP(S) 请求，用于避免浏览器 CORS 影响本地调试。远端权限可用时 Mock Host 使用远端详情返回的同一份权限快照；不可用时使用缺失快照并默认拒绝受管能力。proxy 不会把黑盒客户端私有协议字段暴露给 iframe 业务代码。
+浏览器 Mock 的权限状态只存在于 Mock Host 内存中，URL query 不能提供或覆盖权限。远端 dev context 可用时，Mock Host 以线上快照作为初始值；不可用时匿名状态默认拒绝受管能力。开发者可以在调试页临时调整 `network.request` 和官方域名权限，变更只会重建 devtools-only mock runtime，不会重建 iframe 或中断 Vite HMR，也不会修改线上配置。调试页会对比线上快照并提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。
+
+本地 mock runtime 下已授权的 `network.request()` 会通过 `hb-sdk` 本地 mock network proxy 转发真实 HTTP(S) 请求，用于避免浏览器 CORS 影响本地调试。proxy 不会把黑盒客户端私有协议字段暴露给 iframe 业务代码。CLI 登录态和远端 dev context 也不会注入 iframe。
 
 Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging. The phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell. If the mock host is open inside Codex, VSCode, or another embedded browser, ask the user to open the same debug page in the system browser before retrying because embedded browsers may block the `heybox://` protocol handoff.
 

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.6.3+skill.e46d946d0d66",
+  "skillVersion": "0.6.4-alpha.0+skill.20921fb44039",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.6.3",
-    "compatibility": "0.6.3"
+    "version": "0.6.4-alpha.0",
+    "compatibility": "0.6.4-alpha.0"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-e46d946d0d668d1f9fc60d49d0552ff3f7d8c15d69823e979b20307cdcb42a36"
+  "integrity": "sha256-20921fb44039d21908fb692fc7d593c1dbc3b4f5dfa8f36f24aa0258ce150d13"
 }