@heybox/hb-sdk 0.5.16 → 0.5.18

package/dist/cli-chunks/{session-Cfl5cGf8.cjs → session-dRGPpyS1.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-B-lA2GE7.cjs');
+var index = require('./index-CsOcGUzF.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');
@@ -67,57 +67,6 @@ function isTruthyEnvFlag(value) {
         .toLowerCase());
 }
 
-const globalHeyboxCliRequestConfig = {};
-function readHeyboxCliRequestConfig() {
-    return normalizeHeyboxRylaiServiceTagConfig(globalHeyboxCliRequestConfig);
-}
-function resolveHeyboxRylaiServiceTag(pathWithQuery, config = readHeyboxCliRequestConfig()) {
-    const normalized = normalizeHeyboxRylaiServiceTagConfig(config);
-    const pathname = pathWithQuery ? getPathname(pathWithQuery) : '';
-    const specialTag = normalized.special_tag;
-    if (pathname && specialTag?.path_prefix_list.some((prefix) => pathname.startsWith(prefix))) {
-        return specialTag.tag_name;
-    }
-    return normalized.default_tag;
-}
-function normalizeHeyboxRylaiServiceTagConfig(config) {
-    const defaultTag = normalizeHeyboxRylaiServiceTag(config.default_tag);
-    const specialTagName = normalizeHeyboxRylaiServiceTag(config.special_tag?.tag_name);
-    const pathPrefixList = config.special_tag?.path_prefix_list?.filter(isValidPathPrefix) || [];
-    return {
-        ...(defaultTag ? { default_tag: defaultTag } : {}),
-        ...(specialTagName && pathPrefixList.length
-            ? {
-                special_tag: {
-                    tag_name: specialTagName,
-                    path_prefix_list: pathPrefixList,
-                },
-            }
-            : {}),
-    };
-}
-function normalizeHeyboxRylaiServiceTag(value) {
-    const tag = String(value ?? '').trim();
-    if (!tag) {
-        return undefined;
-    }
-    if (/[\r\n]/.test(tag)) {
-        throw new Error('x-rylai-service-tag 不允许包含换行符');
-    }
-    return tag;
-}
-function isValidPathPrefix(value) {
-    return typeof value === 'string' && value.startsWith('/') && !/[\r\n]/.test(value);
-}
-function getPathname(pathWithQuery) {
-    try {
-        return new URL(pathWithQuery, 'https://api.xiaoheihe.cn').pathname;
-    }
-    catch {
-        return '';
-    }
-}
-
 const SIGN_VERSION = '999.0.4';
 const SIGN_CHARSET = 'AB45STUVWZEFGJ6CH01D237IXYPQRKLMN89';
 function createHeyboxOpenPlatformSignParams(pathname, options = {}) {
@@ -217,7 +166,7 @@ function resolveHeyboxId(session) {
         ?.slice('heybox_id='.length);
 }
 function createHeyboxAuthHeaders(session, options = {}) {
-    const serviceTag = resolveHeyboxRylaiServiceTag(options.pathWithQuery);
+    const serviceTag = index.resolveHeyboxRylaiServiceTag(options.pathWithQuery);
     return {
         Cookie: session.cookieHeader,
         Referer: HEYBOX_WEB_REFERER,
@@ -227,7 +176,7 @@ function createHeyboxAuthHeaders(session, options = {}) {
 }
 function createHeyboxRequestContext(session, options = {}) {
     const heyboxId = resolveHeyboxId(session);
-    const serviceTag = resolveHeyboxRylaiServiceTag(options.pathWithQuery);
+    const serviceTag = index.resolveHeyboxRylaiServiceTag(options.pathWithQuery);
     return {
         baseUrl: HEYBOX_API_BASE_URL,
         headers: createHeyboxAuthHeaders(session, options),
@@ -286,7 +235,7 @@ async function readHeyboxApiEnvelope(response, options) {
         rawBody,
         pathWithQuery: options.pathWithQuery,
     });
-    throw new index.CliError(message, verboseMessage);
+    throw new index.CliError(message, verboseMessage, { httpStatus: response.status });
 }
 function formatHeyboxEnvelopeError(input) {
     const parts = [`Heybox API ${input.pathWithQuery} failed`, `HTTP ${input.response.status}`];
@@ -3184,6 +3133,14 @@ function requireLib () {
 var libExports = /*@__PURE__*/ requireLib();
 var fs = /*@__PURE__*/index.getDefaultExportFromCjs(libExports);
 
+class AuthSessionError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'AuthSessionError';
+    }
+}
 const AUTH_CACHE_VERSION = 1;
 const paths = index.envPaths('hb-sdk', { suffix: '' });
 function getAuthCacheFilePath(options = {}) {
@@ -3221,7 +3178,7 @@ async function readHeyboxAuthSession(options = {}) {
 async function requireHeyboxAuthSession(options = {}) {
     const session = await readHeyboxAuthSession(options);
     if (!session) {
-        throw new Error('未发现 Heybox 登录态，请先运行 hb-sdk login');
+        throw new AuthSessionError('未发现 Heybox 登录态，请先运行 hb-sdk login', 'AUTH_SESSION_MISSING');
     }
     const expectedLoginBaseUrl = resolveHeyboxLoginBaseUrl(options);
     if (session.loginBaseUrl !== expectedLoginBaseUrl) {
@@ -3256,7 +3213,7 @@ function createSelectedDeveloperEntitySnapshot(input, options = {}) {
 async function setSelectedDeveloperEntitySnapshot(input, options = {}) {
     const cache = await readAuthCache(options);
     if (!cache.heybox) {
-        throw new Error('未发现 Heybox 登录态，请先运行 hb-sdk login');
+        throw new AuthSessionError('未发现 Heybox 登录态，请先运行 hb-sdk login', 'AUTH_SESSION_MISSING');
     }
     const selectedEntity = createSelectedDeveloperEntitySnapshot(input, options);
     return writeAuthCache({

package/dist/cli.cjs

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

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

@@ -4938,6 +4938,95 @@ function isNavigationBarForegroundStyle(value) {
     return value === 'light' || value === 'dark';
 }
 
+const OFFICIAL_MINI_PROGRAM_NETWORK_ROOT_DOMAINS = [
+    'xiaoheihe.cn',
+    'max-c.com',
+    'debugmode.cn',
+    'maxjia.com',
+];
+/** 使用 URL 解析后的 hostname 判断黑盒官方根域及其子域。 */
+function isOfficialMiniProgramNetworkUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return false;
+        }
+        const hostname = url.hostname.toLowerCase().replace(/\.$/, '');
+        return OFFICIAL_MINI_PROGRAM_NETWORK_ROOT_DOMAINS.some(rootDomain => hostname === rootDomain || hostname.endsWith(`.${rootDomain}`));
+    }
+    catch {
+        return false;
+    }
+}
+
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+/** 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。 */
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord$1(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined &&
+        (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord$1(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord$1(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!MANAGED_RUNTIME_PERMISSION_KEYS.has(key)) {
+            continue;
+        }
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+/** 创建只依赖启动快照的纯权限 evaluator，供正式 Runtime 与 Mock Host 共用。 */
+function createMiniProgramRuntimePermissionEvaluator(snapshot) {
+    const parsed = parseMiniProgramRuntimePermissions(snapshot);
+    return (permissionKey, payload) => {
+        if (!MANAGED_RUNTIME_PERMISSION_KEYS.has(permissionKey)) {
+            return { allowed: true };
+        }
+        const entry = parsed.valid ? parsed.permissions[permissionKey] : undefined;
+        if (!entry || entry.status !== 'enabled') {
+            return {
+                allowed: false,
+                code: 'PERMISSION_DENIED',
+                message: permissionKey === 'network.request' ? '当前小程序暂不支持网络请求' : '当前小程序暂不支持该能力',
+            };
+        }
+        if (permissionKey === 'network.request' &&
+            isRecord$1(payload) &&
+            typeof payload.url === 'string' &&
+            isOfficialMiniProgramNetworkUrl(payload.url) &&
+            entry.config.useOfficialDomain !== true) {
+            return {
+                allowed: false,
+                code: 'PERMISSION_DENIED',
+                message: '当前小程序暂不支持访问官方域名',
+            };
+        }
+        return { allowed: true };
+    };
+}
+function isRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 const MOCK_DEFAULT_LEADERBOARD_KEY = 'default';
 const MOCK_LEADERBOARD_CACHE_MAX_ENTRIES = 500;
 const MOCK_LEADERBOARD_CURRENT_ENTRY_RANK_COUNT_LIMIT = 5000;
@@ -5129,6 +5218,7 @@ class MiniProgramMockRuntime {
         this.toasts = [];
         this.vibrates = [];
         this.openAppPages = [];
+        this.evaluateRuntimePermission = createMiniProgramRuntimePermissionEvaluator(options.runtimePermissions);
     }
     async runMethod(method, payload) {
         if (!isMiniProgramMockRuntimeMethod(method)) {
@@ -5137,6 +5227,13 @@ class MiniProgramMockRuntime {
         if (this.closed && method !== NAVIGATION_CLOSE_METHOD) {
             throw createMockBridgeError('INVALID_STATE', '当前小程序容器已关闭');
         }
+        const capability = MINI_PROGRAM_PROTOCOL_CAPABILITIES.find(item => item.method === method);
+        if (capability) {
+            const policyResult = this.evaluateRuntimePermission(capability.permission, payload);
+            if (!policyResult.allowed) {
+                throw createMockBridgeError(policyResult.code, policyResult.message);
+            }
+        }
         const handler = MINI_PROGRAM_MOCK_RUNTIME_METHOD_HANDLERS[method];
         return handler(this, payload);
     }
@@ -6112,16 +6209,14 @@ function isPlainRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-const MINI_PROGRAM_URL_QUERY_PARAM = 'mini_url';
-const MINI_PROGRAM_DEV_SHELL_URL = 'heybox-mini-dev://sandbox';
-const OPEN_IN_APP_URL = 'https://api.xiaoheihe.cn/open_inapp/';
 const NETWORK_PROXY_PATH = '/__hb_sdk_mock_network__';
-const LAN_ADDRESSES_PATH = '/__hb_sdk_lan_addresses__';
+const MOCK_HOST_BOOTSTRAP_PATH = '/__hb_sdk_bootstrap__';
 const params = new URL(location.href).searchParams;
 const miniUrl = params.get('mini_url');
 let lanAddresses = [];
 let defaultLanAddressId;
 let macAppProtocol;
+let nativeAppLaunchUnavailableReason;
 const nonce = createNonce();
 const storage = new Map();
 const logs = [];
@@ -6154,6 +6249,8 @@ if (!miniUrl) {
     throw new Error('Missing mini_url query.');
 }
 const miniProgramUrl = miniUrl;
+const bootstrap = await loadMockHostBootstrap();
+const runtimePermissions = bootstrap.runtimePermissions;
 const iframe = document.createElement('iframe');
 iframe.src = appendNonce(miniProgramUrl, nonce);
 iframe.allow = 'clipboard-read; clipboard-write';
@@ -6183,6 +6280,7 @@ const runtime = new MiniProgramMockRuntime(createBrowserMockRuntimePlatformAdapt
     },
 }), {
     onAuthChange: (result) => postEvent('authChange', result),
+    runtimePermissions,
 });
 updateUserStatus();
 updateStorageSnapshot();
@@ -6388,23 +6486,30 @@ async function copyDebugPageUrl() {
     }
 }
 async function setupMobileAppQr() {
-    const config = await loadMobileLanConfig();
-    lanAddresses = config.lanAddresses;
-    defaultLanAddressId = config.defaultLanAddressId;
-    macAppProtocol = config.macAppProtocol;
+    lanAddresses = bootstrap.lanAddresses;
+    defaultLanAddressId = bootstrap.defaultLanAddressId;
+    macAppProtocol = bootstrap.macAppProtocol;
+    nativeAppLaunchUnavailableReason = bootstrap.nativeAppLaunchUnavailableReason;
+    updateNativeAppLaunchAvailability();
     setupMobileLanSelect();
     await updateMobileQrCode();
 }
 async function openMacApp() {
     await mobileAppQrReady.catch(() => undefined);
-    const protocol = macAppProtocol ?? createMacAppProtocol(miniProgramUrl);
+    if (nativeAppLaunchUnavailableReason) {
+        return;
+    }
+    const protocol = macAppProtocol;
+    if (!protocol) {
+        return;
+    }
     console.log('[hb-sdk] Mac App launch protocol:', protocol);
     showMacAppLaunchHint();
     window.location.href = protocol;
 }
-async function loadMobileLanConfig() {
+async function loadMockHostBootstrap() {
     try {
-        const response = await fetch(LAN_ADDRESSES_PATH, {
+        const response = await fetch(MOCK_HOST_BOOTSTRAP_PATH, {
             cache: 'no-store',
         });
         const payload = await response.json();
@@ -6415,11 +6520,17 @@ async function loadMobileLanConfig() {
             defaultLanAddressId: typeof payload.defaultLanAddressId === 'string' ? payload.defaultLanAddressId : undefined,
             lanAddresses: Array.isArray(payload.lanAddresses) ? payload.lanAddresses.filter(isLanAddress) : [],
             macAppProtocol: typeof payload.macAppProtocol === 'string' ? payload.macAppProtocol : undefined,
+            nativeAppLaunchUnavailableReason: typeof payload.nativeAppLaunchUnavailableReason === 'string'
+                ? payload.nativeAppLaunchUnavailableReason
+                : undefined,
+            runtimePermissions: payload.runtimePermissions,
         };
     }
     catch {
-        elements.mobileQrStatus.textContent = '二维码初始化失败';
-        return { lanAddresses: [] };
+        return {
+            lanAddresses: [],
+            nativeAppLaunchUnavailableReason: '真机调试配置加载失败，请重启 hb-sdk dev 后重试。',
+        };
     }
 }
 function setupMobileLanSelect() {
@@ -6438,6 +6549,12 @@ function setupMobileLanSelect() {
     elements.mobileLanSelect.disabled = !hasLanAddress;
 }
 async function updateMobileQrCode() {
+    if (nativeAppLaunchUnavailableReason) {
+        elements.mobileQrImage.removeAttribute('src');
+        elements.mobileQrImage.hidden = true;
+        elements.mobileQrStatus.textContent = nativeAppLaunchUnavailableReason;
+        return;
+    }
     const selected = readSelectedLanAddress();
     if (!selected) {
         elements.mobileQrImage.removeAttribute('src');
@@ -6445,7 +6562,13 @@ async function updateMobileQrCode() {
         elements.mobileQrStatus.textContent = '';
         return;
     }
-    const payload = selected.mobileAppQrPayload ?? createMobileAppQrPayload(selected.appUrl);
+    const payload = selected.mobileAppQrPayload;
+    if (!payload) {
+        elements.mobileQrImage.removeAttribute('src');
+        elements.mobileQrImage.hidden = true;
+        elements.mobileQrStatus.textContent = '真机调试配置不可用，请重启 hb-sdk dev 后重试。';
+        return;
+    }
     elements.mobileQrStatus.textContent = '正在生成二维码...';
     try {
         elements.mobileQrImage.src = await browserExports.toDataURL(payload, {
@@ -6462,40 +6585,16 @@ async function updateMobileQrCode() {
         elements.mobileQrStatus.textContent = '二维码生成失败';
     }
 }
-function readSelectedLanAddress() {
-    return lanAddresses.find((address) => address.id === elements.mobileLanSelect.value) ?? lanAddresses[0];
-}
-function createMacAppProtocol(appUrl) {
-    return createHeyboxProtocol(createMiniProgramDevShellOpenWindowPayload(appUrl));
-}
-function createMobileAppQrPayload(appUrl) {
-    return `${OPEN_IN_APP_URL}#${createHeyboxProtocol(createMiniProgramDevShellOpenWindowPayload(appUrl, { encodeMiniUrl: false }))}`;
-}
-function createMiniProgramDevShellOpenWindowPayload(appUrl, options = {}) {
-    return {
-        protocol_type: 'openWindow',
-        full_screen: true,
-        mini_program: '1',
-        navigation_bar: {
-            title: '',
-        },
-        webview: {
-            url: createMiniProgramDevShellUrl(appUrl, options),
-            pull: false,
-            refresh: false,
-        },
-    };
-}
-function createMiniProgramDevShellUrl(appUrl, options) {
-    if (options.encodeMiniUrl === false) {
-        return `${MINI_PROGRAM_DEV_SHELL_URL}?${MINI_PROGRAM_URL_QUERY_PARAM}=${appUrl}`;
+function updateNativeAppLaunchAvailability() {
+    const isUnavailable = Boolean(nativeAppLaunchUnavailableReason);
+    elements.macAppButton.disabled = isUnavailable;
+    if (nativeAppLaunchUnavailableReason) {
+        elements.macAppStatus.textContent = nativeAppLaunchUnavailableReason;
+        elements.macAppStatus.hidden = false;
     }
-    const devShellUrl = new URL(MINI_PROGRAM_DEV_SHELL_URL);
-    devShellUrl.searchParams.set(MINI_PROGRAM_URL_QUERY_PARAM, appUrl);
-    return devShellUrl.toString();
 }
-function createHeyboxProtocol(payload) {
-    return `heybox://${encodeURIComponent(JSON.stringify(payload))}`;
+function readSelectedLanAddress() {
+    return lanAddresses.find((address) => address.id === elements.mobileLanSelect.value) ?? lanAddresses[0];
 }
 function isLanAddress(value) {
     return (isRecord(value) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "description": "",
   "exports": {
     ".": {

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.
+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.
 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. Mini-program name, icon, and cover images belong in `package.json.heybox.miniProgramProfile` and are submitted with version audit.

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.5.14`
+- Version at generation time: `0.5.17`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -347,7 +347,7 @@ SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注
 npm run dev
 ```
 
-调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；如果需要真实黑盒小程序容器加载同一页面，可以点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+调试页会通过 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；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：
 
@@ -638,6 +638,8 @@ await network.request({
 
 支持的 HTTP method 为 `GET`、`POST`、`PUT`、`PATCH`、`DELETE`、`HEAD`、`OPTIONS`。
 
+`network.request` 由平台 Runtime 权限控制。未授权时 SDK 会收到 `PERMISSION_DENIED` 和“当前小程序暂不支持网络请求”；即使已开启网络请求，访问黑盒官方域名仍需要运营侧单独开启官方域名配置。业务代码不能自行请求或注入 Cookie、pkey 等官方凭据。
+
 ## 生命周期事件
 
 SDK 实例创建后会自动开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时，默认单例会被懒创建并自动开始握手；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。

package/skill/references/cli.md

@@ -103,7 +103,7 @@ Agent rules:
 hb-sdk dev
 ```
 
-`hb-sdk dev` 会从当前目录向上查找最近的 `package.json` 作为项目根目录，加载该项目安装的 `vite`，并优先使用项目内的 Vite 配置文件。命令会同时启动内置 mock runtime host 并默认打开调试页；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码。手机需要与电脑处在同一局域网，并使用支持小程序调试壳的新版小黑盒 APP。Codex、VSCode 等内嵌浏览器可能无法转交 `heybox://` 协议；需要从调试页唤起 Mac 版 APP 时，请先在系统浏览器中打开调试页。项目没有安装 Vite 时，命令会提示安装依赖或把 Vite 放到 `devDependencies`。
+`hb-sdk dev` 会从当前目录向上查找最近的 `package.json`，并在项目已绑定且 CLI 已登录时尝试查询真实 Runtime 权限快照。项目未绑定、未登录或远端暂时不可用时，命令会输出警告并继续启动 Vite 和内置 mock runtime host；此时使用缺失权限快照，`network.request` 等受管能力默认拒绝。远端权限读取成功时，mock host 使用真实快照，远端明确关闭的能力仍稳定返回 `PERMISSION_DENIED`。本地 `package.json` 无法解析等配置错误不会被降级，命令会直接报错。调试页默认自动打开；需要真实黑盒小程序容器加载同一页面时，点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码。
 
 常用参数：
 
@@ -116,11 +116,11 @@ hb-sdk dev
 
 ## Mock runtime 边界
 
-`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境。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 环境；浏览器 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；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 不要为了本地调试再创建独立 mock runtime 包。CLI、模板和 mock host 都归属 `@heybox/hb-sdk`。
 
-本地 mock runtime 下的 `network.request()` 会通过 `hb-sdk` 本地 mock network proxy 转发真实 HTTP(S) 请求，用于避免浏览器 CORS 影响本地调试。proxy 不会把黑盒客户端私有协议字段暴露给 iframe 业务代码。
+本地 mock runtime 下已授权的 `network.request()` 会通过 `hb-sdk` 本地 mock network proxy 转发真实 HTTP(S) 请求，用于避免浏览器 CORS 影响本地调试。远端权限可用时 Mock Host 使用远端详情返回的同一份权限快照；不可用时使用缺失快照并默认拒绝受管能力。proxy 不会把黑盒客户端私有协议字段暴露给 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.
 
@@ -169,10 +169,27 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 
 默认发布策略是 `auto_publish=false`：运营审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布。需要审核通过后自动发布并下架旧线上版本时，使用 `--auto-publish`。如需让指定用户预览未发布候选版本，使用 `hb-sdk remote allowlist add <heybox_id>` 管理预览白名单。
 
-内部测试或预发环境可通过 `HB_SDK_API_BASE_URL` / `HB_SDK_LOGIN_BASE_URL` 设置默认后台环境，也可以用 `--api-base-url` / `--login-base-url` 覆盖单次命令。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。`apiBaseUrl` 影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`loginBaseUrl` 用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。开发环境如需给后台请求带 `x-rylai-service-tag` 和 `special_tag`，可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置 `default_tag` 或 path-prefix 级 `special_tag`。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。
+内部测试或预发环境可通过 `HB_SDK_API_BASE_URL` / `HB_SDK_LOGIN_BASE_URL` 设置默认后台环境，也可以用 `--api-base-url` / `--login-base-url` 覆盖单次命令。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。`apiBaseUrl` 影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`loginBaseUrl` 用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。开发环境如需给后台请求带 `x-rylai-service-tag` 和 `special_tag`，优先用 `--service-tag <tag>` 或 `HB_SDK_SERVICE_TAG`；path-prefix 级 `special_tag` 仍可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。
 
 `hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
 
+切换测试环境时往往需要同时配置后台 host、登录 host 和 service tag。CLI 支持加载 `.env.<name>` 预设，把其中的 `HB_SDK_*` 变量一次性注入当前进程（不覆盖已有值）：`--env <name>` 读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级更高，也可用 `HB_SDK_ENV=<name>` 触发。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。
+
+```bash
+# 项目根准备 .env.test
+#   HB_SDK_API_BASE_URL=https://api.test.xiaoheihe.cn
+#   HB_SDK_LOGIN_BASE_URL=https://login.test.xiaoheihe.cn
+#   HB_SDK_SERVICE_TAG=my-test-tag
+
+hb-sdk remote deploy --env test --release-note "测试环境验证"
+hb-sdk remote info --env test
+HB_SDK_ENV=test hb-sdk remote versions
+hb-sdk remote deploy --env-file .env.local --release-note "本地联调"
+hb-sdk remote deploy --env test --service-tag other-tag --release-note "灰度"   # 单项 flag 覆盖预设
+```
+
+`--env-file` 优先于 `--env`，`--service-tag` / `--api-base-url` / `--login-base-url` 优先于 `.env` 预设注入的同名变量，而预设又不会覆盖进程已有的环境变量，因此优先级为 flag > 进程 env > `.env` 预设 > 默认值。
+
 Before precheck, build, upload, or submit audit, `hb-sdk remote deploy` must verify that the current project's bound mini-program belongs to the server-side current entity. If `detail.entity_id` differs from the current entity, the command fails with both entity ids/names and suggests `hb-sdk remote entity switch <entity-id>`. It must not auto-switch entities and must not continue into precheck/build/upload/submit on mismatch.
 
 Agent rules:

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.5.14+skill.2ed2b210acdb",
+  "skillVersion": "0.5.17+skill.0ad061ac9da8",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.5.14",
-    "compatibility": "0.5.14"
+    "version": "0.5.17",
+    "compatibility": "0.5.17"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-2ed2b210acdb606888cde6fb80559ce26500c105b143914910b88b3d6b06eaf9"
+  "integrity": "sha256-0ad061ac9da821bfea0db71d30404999c1bd3eb5fcddfb0c22211bd9939db2ae"
 }