@heybox/hb-sdk 0.8.0-alpha.3 → 0.8.0

package/README.md

@@ -21,6 +21,8 @@ npm run dev
 
 脚手架已包含 SDK、Vite 配置和常用开发命令。浏览器调试通过后，再从调试台的二维码入口使用手机小黑盒 APP 验收。
 
+当前 `0.8` 已发布为稳定版本，创建命令使用 `@latest`。
+
 ### 接入已有项目
 
 ```bash
@@ -45,7 +47,9 @@ hb-sdk skill install --all-agents
 
 使用 `hb-sdk doctor` 或 `hb-sdk doctor --json` 检查各 Agent 的 Skill 是否与当前 npm 包匹配；已有内容被修改时，使用 `--force` 才会覆盖。
 
-SDK 会在导入时启动握手，能力调用会自动等待 SDK 就绪。未开通网络权限的小程序通过 `user.getInfo()` 静默读取当前小程序内的隔离身份和公开资料：
+SDK 会在导入时启动握手，能力调用会自动等待 SDK 就绪。声明 `userInfo` 后，可通过 `user.getInfo()` 读取当前小程序内的隔离身份和已授权资料：
+
+使用受保护能力前，需要在项目根 `package.json#heybox.permissions` 中显式声明。`auth.login()` 和 `user.getInfo()` 都只需要 `userInfo`，不依赖公开 `network` 权限；`network` 仅约束 `network.request()` 与 `network.download()`，并且声明后仍需平台批准。完整配置、无需声明白名单和 0.8/0.9 迁移规则见[权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)。
 
 需要可信用户手势的按钮不能在点击回调里等待握手。页面加载时先用 `getHandshakeState()` 读取当前状态，再用 `onHandshakeStateChange()` 订阅并立即接收当前状态；仅在 `status === 'ready'` 时启用按钮，并在组件或页面销毁时调用订阅返回的取消函数。`ready` 生命周期事件只是握手成功瞬间派发、不会重放的边沿通知，不能用来判断当前状态。
 
@@ -60,7 +64,7 @@ async function getCurrentUser() {
 
 `user.getInfo()` 不展示授权弹窗，也不要求可信用户手势。未登录时返回 `isHeyboxAppLoggedIn: false`；已登录时隐式授予当前本地用户 scopes（`identity`、`profile`），返回当前小程序隔离的 `app_user_id` 以及 `profile.nickname`、`profile.avatar`。
 
-已开通网络权限的小程序在按钮点击等明确的用户操作中调用 `auth.login()`：
+声明 `userInfo` 后，小程序可在按钮点击等明确的用户操作中调用 `auth.login()`：
 
 ```ts
 async function loginFromUserAction() {
@@ -74,7 +78,7 @@ async function loginFromUserAction() {
 }
 ```
 
-`auth.login()` 返回 `{ code, expiresIn: 300, scopes }`，其中 `identity` 隐式强制包含；它不返回 user、profile、`app_user_id` 或 token。页面只能把 code 交给开发者服务端，再由服务端按后端 OpenAPI 文档换取 token。未开通网络权限的小程序使用 `user.getInfo()`，无法获取 code 或调用 OpenAPI。完整边界见[用户身份与登录](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)。
+`auth.login()` 返回 `{ code, expiresIn: 300, scopes }`，其中 `identity` 隐式强制包含；它不返回 user、profile、`app_user_id` 或 token。页面只能把 code 交给开发者服务端，再由服务端按后端 OpenAPI 文档换取 token。它内部使用 Host 受信请求，不依赖公开 `network` 权限；示例中的 `network.request()` 本身仍需声明并获得 `network` 平台批准。完整边界见[用户身份与登录](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)。
 
 用户可以在明确的按钮点击和二次确认后撤销当前小程序的授权：
 
@@ -88,7 +92,7 @@ async function revokeAuthorizationFromUserAction() {
 }
 ```
 
-`user.revokeAuthorization()` 在已开通和未开通网络权限的小程序中都可用，不接收小程序 ID、黑盒用户 ID 或手势参数。调用必须来自可信用户操作，否则返回 `USER_GESTURE_REQUIRED`。撤销成功后，后续身份或授权读取会重新进入授权流程；SDK 不会替业务清理已经持久化的数据。
+`user.revokeAuthorization()` 位于无需声明白名单，不接收小程序 ID、黑盒用户 ID 或手势参数。调用必须来自可信用户操作，否则返回 `USER_GESTURE_REQUIRED`。撤销成功后，后续身份或授权读取会重新进入授权流程；SDK 不会替业务清理已经持久化的数据。
 
 已有 Vite 项目还需要启用构建插件：
 
@@ -132,14 +136,14 @@ const downloaded = await hbSDK.network.download({
 console.log(await downloaded.readText());
 ```
 
-本次保留 `files`、`network.download()`、协议 wire 和 Runtime Host Port 体系，但暂不在现有 Host
-开放。此前的实现用于适配旧版小黑盒 PC；由于新版 PC 即将启用，这套旧版适配不再发布，后续会
-直接按照新版 PC 的 Host 架构接入。当前 Host 调用这些 method 时返回 `METHOD_FORBIDDEN`；旧
-Runtime 不认识新 method 时返回 `METHOD_NOT_FOUND`，且不提供 Blob 或内存假实现。
+新 PC 已开放 `files` sandbox、单文件/目录 picker 与公网 `network.download()`；其它 Host 尚未开放
+对应 primitive 时返回 `METHOD_FORBIDDEN`，旧 Runtime 不认识新 method 时返回 `METHOD_NOT_FOUND`。
+新 PC 的下载字节留在插件 Node 并直接原子落盘，不提供 Blob 或内存假实现。
 
-外部 picker 必须从可信用户操作触发。`files.saveFile({ suggestedName })` 会打开系统保存对话框并返回
-精确 File 授权，不会额外保留 Directory 授权；V1 不接受 `accept`。只有 `pickFiles()` 支持扩展名过滤。完整路径、创建、存在性和
-下载语义见[快速开始](https://docs.xiaoheihe.cn/hb_sdk/guide/quick-start#文件与下载)。
+外部 picker 必须从可信用户操作触发。`files.saveFile({ suggestedName })` 返回精确 File 授权，
+不会额外保留 Directory 授权；新 PC 当前先让用户选择保存目录，再以 `suggestedName` 独占创建空文件，
+同名文件返回 `FILE_ALREADY_EXISTS`。V1 不接受 `accept`，只有 `pickFiles()` 支持扩展名过滤。完整路径、
+创建、存在性和下载语义见[快速开始](https://docs.xiaoheihe.cn/hb_sdk/guide/quick-start#文件与下载)。
 
 `remove()` 只允许删除 sandbox 对象；外部 picker、`saveFile()` 及其派生项即使是 `readwrite` 也返回 `FILE_ACCESS_DENIED`。单个 Runtime session 最多保留 1024 个外部 direct handle，超限返回 `FILE_QUOTA_EXCEEDED`。Host 文件错误只向 SDK 暴露稳定 code 与 canonical 安全文案，业务不要依赖平台原始 message 或附加 data。
 
@@ -188,16 +192,16 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - `ready` 生命周期事件是不可重放的边沿通知，不代表可查询状态，也不能替代握手状态 API。
 - `auth.login({ scopes? })` 只返回 `{ code, expiresIn: 300, scopes }`；identity 隐式强制包含，code 只能提交给开发者服务端。
 - 需要授权 UI 时，`auth.login()` 必须来自可信用户手势，否则返回 `USER_GESTURE_REQUIRED`；用户取消或关闭时返回 `AUTHORIZATION_CANCELLED`。已授权时可以静默返回新 code。
-- `user.getSteamGameList()` 仅供未开通网络权限的小程序通过 Host 读取；已开通网络权限时返回 `SERVER_API_REQUIRED`，且授权码与 OpenAPI 不提供 Steam 游戏库 scope 或资源接口。
-- 已开通网络权限时，公开的 `user.getInfo()` 返回 `SERVER_API_REQUIRED`；对应身份和资料数据应由开发者服务端通过 OpenAPI 获取。
-- 未开通网络权限时，`user.getInfo()` 隐式授予 `identity` 与 `profile`，静默返回 `userInfo.app_user_id`、昵称和头像；这条路径仍不能获取 code 或调用 OpenAPI。
+- `auth.login()`、`user.getInfo()` 和 `user.getSteamGameList()` 的可用性不由 `network` 决定；它们分别要求 `userInfo` 或 `steamLibrary`，并继续遵循各自的用户授权和数据规则。
 - `user.revokeAuthorization()` 在两种网络模式下都要求可信用户手势；成功后必须停止使用并清理业务缓存的旧身份、资料和服务端会话。
 - `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
 - 业务网络请求使用 `network.request()`，不要依赖浏览器原生网络出口。
 - 公开 `network.request()` 与 `network.download()` 均使用 no-follow redirect policy；3xx 不会在 Host 内静默跳转。
 - `network.request()` 不能访问平台保留的 runtime auth 与 OpenAPI 内部路径；页面不得持有或交换服务端应用凭据。
 - `network.request` 不支持 `multipart/form-data`；App Host 仅支持 form（`application/x-www-form-urlencoded`）与 JSON。表单请用 `URLSearchParams#toString()` 作为 `data`，文件上传请走专用上传能力。
-- 当前 Host（包括旧版 PC、Mobile、Web 与 Browser Dev Host）均未开放 `files` / `network.download()`；新版 PC 将按同一公开合同重新接入，期间不提供内存或 Blob 假实现。
+- 新 PC 开放持久 sandbox、单文件/目录 picker、精确 File 保存与公网 `network.download()`；多选和小黑盒域名流式下载暂不支持。Mobile、Web 与 Browser Dev Host 仍未开放这些 primitive。
+- 新 PC 支持 `network.request`，但会忽略 `withCredentials`；它不改变请求路由或凭据行为。其他平台继续遵循各自的 Host 语义。
+- 新 PC 不支持振动、分享菜单和截图分享；`navigation.openAppPage` 仅支持 `game_detail`，用户/帖子详情会明确失败。调用平台相关能力时应处理 `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。
 - picker 必须来自可信用户手势；取消选择返回 `FILE_PICKER_CANCELLED`。`saveFile()` 只接受 `suggestedName`，不接受 `accept`。
 - `pickFiles()` / `pickDirectory()` 默认只读；`pickFiles()` 仅在显式传入 `multiple: true` 时允许 Host 返回多个文件。要写入或作为下载目标时显式请求 `mode: 'readwrite'`。
 - `file()` / `directory()` 只接受以 `/` 分隔的规范相对路径；拒绝绝对路径、空 segment、`.`、`..`、反斜杠、尾分隔符和控制字符。
@@ -207,12 +211,16 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - 单个 Runtime session 最多保留 1024 个 picker/saveFile direct handle；整批授权超限时返回 `FILE_QUOTA_EXCEEDED`，不会保留部分结果。
 - Host 文件错误只保留稳定 code 与 canonical 安全文案；原始 message、data、native path 和 credential 不会进入小程序。
 - `FileStat.size` 是非负 safe integer；`modifiedAt` / `createdAt` 若存在，单位为 Unix epoch milliseconds。
-- 仅当远端已启用 `network.request` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
+- 仅当当前版本声明且平台已批准 `network` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
 - 构建必须启用 `miniappManifest({ platforms })` 并显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
 
+私有 Page Channel 适配没有修改 `@heybox/hb-sdk` 公开 API 或 iframe wire；本次 files/download
+Runtime 能力随 `0.8.0-alpha.11` release family 发布，部署 detail 前必须保证
+`@heybox/hb-sdk`、`@heybox/hb-sdk-runtime` 与 `@heybox/hb-sdk-protocol` 三个 package 均可解析。
+
 ## 分享扩展数据
 
-默认分享和复制链接可以携带小程序自行定义的页面状态：
+`share.showShareMenu()` 的落地页固定为当前小程序的 `common_share`，不接受自定义 `url`。分享和复制链接可以携带小程序自行定义的页面状态：
 
 ```ts
 await hbSDK.share.showShareMenu({
@@ -270,7 +278,9 @@ hb-sdk remote deploy --release-note "本次更新说明"
 | `hb-sdk build`         | 执行生产构建与产物校验，不包含类型检查 |
 | `hb-sdk remote deploy` | 构建、上传并提交当前版本审核           |
 
-`hb-sdk dev` 会启动 Vue 3 Browser Dev Host。左侧诊断面板集中展示调用日志、当前小程序作用域内的 Storage 快照和问题，右侧设备预览可在 iPhone 16 Pro Max（`440 x 956`）与 Pixel 9 Pro（`410 x 914`）间切换。切换预设只改变设备外框和 viewport，不会重新加载 iframe 或重启 Runtime；授权与操作弹窗、Toast、Loading 和振动反馈都限制在预览框内。
+`hb-sdk create` 默认生成可直接删除的 Vanilla JavaScript + Vite HelloWorld，只保留 SDK Toast 示例、三端 Manifest 和开发/构建/部署命令，不绑定业务框架或项目内测试工具。
+
+`hb-sdk dev` 会启动 Vue 3 Browser Dev Host。左侧诊断面板集中展示日志、当前小程序作用域内的 Storage 快照和问题，右侧设备预览可在 iPhone 16 Pro Max（`440 x 956`）与 Pixel 9 Pro（`410 x 914`）间切换。切换预设只改变设备外框和 viewport，不会重新加载 iframe 或重启 Runtime；授权与操作弹窗、Toast、Loading 和振动反馈都限制在预览框内。
 
 浏览器调试入口不要求 CLI 登录或项目绑定；需要账号或远端配置的能力会按当前可用上下文返回结果或明确失败。调试台不提供权限修改入口，远端权限快照始终是 Runtime 的规范输入。手机验收统一从右上角二维码入口进入，选择手机可达的局域网网卡后扫码；二维码使用 `open_inapp` 与 `heybox://` `openWindow` 包装的短链。完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
 

package/dist/cli-chunks/{build-qWzAbpS7.cjs → build-PYCNacya.cjs}

@@ -3,10 +3,11 @@
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-CjsCe5bp.cjs');
-var runtimeGate = require('./runtime-gate-DFjw66kF.cjs');
-var index = require('./index-De687C6-.cjs');
-var projectVite = require('./project-vite-1rvkK-M8.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CtL8rsjB.cjs');
+var runtimeGate = require('./runtime-gate-BEFp1w_s.cjs');
+var index = require('./index-MMW2ibQm.cjs');
+var projectVite = require('./project-vite-BQj8YLI4.cjs');
+require('./version-yEn1E2Bg.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');
@@ -27,6 +28,7 @@ async function runBuildCommand(_options = {}, runtime = {}) {
     const env = runtime.env ?? process.env;
     const mode = env.HB_SDK_ENV?.trim() || undefined;
     const skipPlatformCsp = runtimePermissionEnv.shouldSkipMiniappPlatformCspFromEnv(env);
+    runtimePermissionEnv.readMiniappPermissionsFromPackageJson(projectRoot, runtimePermissionEnv.resolveMiniappSdkVersion());
     await fs.rm(distDir, { force: true, recursive: true });
     try {
         return await runtimePermissionEnv.withMiniappPlatformCspEnv(skipPlatformCsp, async () => {
@@ -91,7 +93,7 @@ async function validateBuildOutput(projectRoot, logger) {
     if (hadBom) {
         logger.warn('dist/manifest.json 包含 BOM，已自动剥离');
     }
-    const { platforms, sdkVersion, version } = runtimeGate.validateMiniappManifestForDeploy(manifest);
+    const { platforms, sdkVersion, version, permissions } = runtimeGate.validateMiniappManifestForDeploy(manifest);
     const allFiles = await walkDistFiles(distDir);
     const uploadFiles = allFiles.filter((file) => runtimePermissionEnv.shouldUploadDistFile(file.relativePath));
     const sizeError = runtimePermissionEnv.validateUploadTotalSize(uploadFiles);
@@ -103,6 +105,7 @@ async function validateBuildOutput(projectRoot, logger) {
         fileCount: uploadFiles.length,
         sdkVersion,
         platforms,
+        ...(permissions === undefined ? {} : { permissions }),
         totalBytes: uploadFiles.reduce((total, file) => total + file.size, 0),
         version,
     };

package/dist/cli-chunks/{context-CtS2Thp0.cjs → context-m2W2XbL0.cjs}

@@ -1,53 +1,14 @@
 'use strict';
 
-var session = require('./session-CzaM2Cq3.cjs');
-var runtimePermissionEnv = require('./runtime-permission-env-CjsCe5bp.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CtL8rsjB.cjs');
+var session = require('./session-DjBkjaF8.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
 
-const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
-function isManagedMiniProgramRuntimePermissionKey(key) {
-    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
-}
-function parseMiniProgramRuntimePermissions(snapshot) {
-    if (!isRecord(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(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(rawEntry.config)) {
-            return { valid: false, permissions: {} };
-        }
-        seenKeys.add(key);
-        if (!isManagedMiniProgramRuntimePermissionKey(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 };
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function shouldSkipMiniappPlatformCsp(runtimePermissions) {
-    const parsed = parseMiniProgramRuntimePermissions(runtimePermissions);
-    const networkRequest = parsed.permissions['network.request'];
+    const parsed = runtimePermissionEnv.parseMiniProgramRuntimePermissions(runtimePermissions);
+    const networkRequest = parsed.permissions.network;
     return parsed.valid && networkRequest?.status === 'enabled';
 }
 const DEFAULT_PERMISSION_STATE = {
@@ -57,8 +18,8 @@ const DEFAULT_PERMISSION_STATE = {
     },
 };
 function createBrowserDevPermissionState(context) {
-    const parsed = parseMiniProgramRuntimePermissions(context.runtimePermissions);
-    const networkRequest = parsed.permissions['network.request'];
+    const parsed = runtimePermissionEnv.parseMiniProgramRuntimePermissions(context.runtimePermissions);
+    const networkRequest = parsed.permissions.network;
     return parsed.valid && networkRequest
         ? {
             networkRequest: {
@@ -68,25 +29,48 @@ function createBrowserDevPermissionState(context) {
         }
         : cloneDefaultPermissionState();
 }
-function createBrowserDevRuntimePermissions(state) {
-    return {
-        schema_version: 1,
-        entries: [
-            {
-                key: 'network.request',
-                status: state.networkRequest.status,
-                config: {
-                    useOfficialDomain: state.networkRequest.useOfficialDomain,
-                },
-            },
-        ],
-    };
+function createBrowserDevRuntimePermissions(snapshot, state) {
+    return createDevRuntimePermissions(snapshot, state, state.networkRequest.useOfficialDomain);
 }
 function cloneDefaultPermissionState() {
     return {
         networkRequest: { ...DEFAULT_PERMISSION_STATE.networkRequest },
     };
 }
+function createDevRuntimePermissions(snapshot, state, useOfficialDomain) {
+    const parsed = runtimePermissionEnv.parseMiniProgramRuntimePermissions(snapshot);
+    if (!parsed.valid) {
+        return { schema_version: 1, entries: [] };
+    }
+    const entries = [];
+    for (const key of runtimePermissionEnv.MINI_PROGRAM_PERMISSION_KEYS) {
+        const entry = parsed.permissions[key];
+        if (!entry)
+            continue;
+        entries.push(key === 'network'
+            ? {
+                key,
+                status: state.networkRequest.status,
+                config: { useOfficialDomain },
+            }
+            : {
+                key,
+                status: entry.status,
+                config: {},
+            });
+    }
+    const revision = isPlainRecord(snapshot) && typeof snapshot.revision === 'number' && Number.isInteger(snapshot.revision) && snapshot.revision >= 0
+        ? snapshot.revision
+        : undefined;
+    return {
+        schema_version: 1,
+        ...(revision === undefined ? {} : { revision }),
+        entries,
+    };
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
 
 function createRemoteApiClient(options) {
     return {
@@ -401,7 +385,6 @@ exports.createBrowserDevRuntimePermissions = createBrowserDevRuntimePermissions;
 exports.createLocalDevLaunchToken = createLocalDevLaunchToken;
 exports.createRemoteApiClientForEnvironment = createRemoteApiClientForEnvironment;
 exports.getBoundMiniProgram = getBoundMiniProgram;
-exports.parseMiniProgramRuntimePermissions = parseMiniProgramRuntimePermissions;
 exports.readBoundMiniProgramId = readBoundMiniProgramId;
 exports.readBoundMiniProgramIdFromPackageJson = readBoundMiniProgramIdFromPackageJson;
 exports.readMiniProgramProjectPackage = readMiniProgramProjectPackage;

package/dist/cli-chunks/{create-PV5ua977.cjs → create-BdAg3WGA.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-De687C6-.cjs');
+var index = require('./index-MMW2ibQm.cjs');
 require('node:module');
 require('os');
 require('readline');
@@ -1238,7 +1238,7 @@ function requireEjs () {
 
 var ejsExports = requireEjs();
 
-const TEMPLATE_NAME = 'vue3-vite-ts';
+const TEMPLATE_NAME = 'vanilla-vite-js';
 const TEMPLATE_ROOT_CANDIDATES = [
     path.resolve(__dirname, 'templates', TEMPLATE_NAME),
     path.resolve(__dirname, '..', 'templates', TEMPLATE_NAME),

package/dist/cli-chunks/{dev-CwKbAm_H.cjs → dev-CyZuw7Yn.cjs}

@@ -8,17 +8,17 @@ var node_crypto = require('node:crypto');
 var promises = require('node:dns/promises');
 var node_http = require('node:http');
 var node_module = require('node:module');
-var context = require('./context-CtS2Thp0.cjs');
+var context = require('./context-m2W2XbL0.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CtL8rsjB.cjs');
 var undici = require('undici');
 var fs$1 = require('node:fs/promises');
-var index = require('./index-De687C6-.cjs');
+var index = require('./index-MMW2ibQm.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-CzaM2Cq3.cjs');
+var session = require('./session-DjBkjaF8.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-1rvkK-M8.cjs');
-var version = require('./version-Bz-AfXQU.cjs');
-var runtimePermissionEnv = require('./runtime-permission-env-CjsCe5bp.cjs');
+var projectVite = require('./project-vite-BQj8YLI4.cjs');
+var version = require('./version-yEn1E2Bg.cjs');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 class Locked extends Error {
@@ -1149,11 +1149,11 @@ function validateDevSessionCreatePayload(payload, allowedMiniUrlOrigins) {
         !allowedMiniUrlOrigins.has(miniUrlOrigin.origin)) {
         throw new TypeError('mini_url_origin must be an allowed LAN origin');
     }
-    const parsedPermissions = context.parseMiniProgramRuntimePermissions(payload.runtime_permissions);
+    const parsedPermissions = runtimePermissionEnv.parseMiniProgramRuntimePermissions(payload.runtime_permissions);
     if (!parsedPermissions.valid) {
         throw new TypeError('runtime_permissions is invalid');
     }
-    const networkPermission = parsedPermissions.permissions['network.request'];
+    const networkPermission = parsedPermissions.permissions.network;
     if (networkPermission?.config.useOfficialDomain !== false) {
         throw new TypeError('Dev Session does not allow official domains');
     }
@@ -1605,7 +1605,7 @@ async function selectAvailablePort(options) {
         port: createPortCandidates(options.startPort, maxAttempts),
     });
     if (port < options.startPort || port >= options.startPort + maxAttempts) {
-        throw new Error(`无法找到可用 ${options.label} 端口，起始端口: ${options.startPort}`);
+        throw new Error(`无法找到可用端口（${options.label}），起始端口：${options.startPort}`);
     }
     return port;
 }
@@ -1851,8 +1851,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-CwKbAm_H.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-CwKbAm_H.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-CyZuw7Yn.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-CyZuw7Yn.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'),
@@ -2968,7 +2968,7 @@ async function listenHttpServer(server, options, getPortImpl, listen) {
         const port = await selectAvailablePort({
             getPort: getPortImpl,
             host: DEV_PORT_PROBE_HOST,
-            label: 'browser dev host',
+            label: '浏览器调试页服务',
             maxAttempts: lastCandidate - nextCandidate + 1,
             startPort: nextCandidate,
         });
@@ -2987,7 +2987,7 @@ async function listenHttpServer(server, options, getPortImpl, listen) {
             nextCandidate = port + 1;
         }
     }
-    throw lastAddressInUseError ?? new Error(`无法找到可用 browser dev host 端口，起始端口: ${options.port}`);
+    throw lastAddressInUseError ?? new Error(`无法找到可用浏览器调试页服务端口，起始端口：${options.port}`);
 }
 const listenBrowserDevHostServer = (server, options) => new Promise((resolve, reject) => {
     const onError = (error) => {
@@ -5217,6 +5217,9 @@ function resolveRuntimeLogTelemetryReportId(entry) {
 function shouldReportRuntimeLogToTelemetry(entry, options = {}) {
     const minLevel = options.minLevel ?? DEFAULT_RUNTIME_LOG_TELEMETRY_MIN_LEVEL;
     const ignoreMessages = options.ignoreMessages ?? [...DEFAULT_RUNTIME_LOG_TELEMETRY_IGNORE_MESSAGES];
+    if (options.shouldReport && !options.shouldReport(entry)) {
+        return false;
+    }
     return isRuntimeLogLevelEnabled(entry.level, minLevel) && !ignoreMessages.some((pattern) => pattern.test(entry.message));
 }
 /**
@@ -5518,10 +5521,14 @@ function createTelemetryRuntimeLogSink(telemetry, options = {}) {
                 severity: entry.level,
             });
             const { requestId, ...reportContext } = entry.context ?? {};
+            // 调用方可在上下文里显式给出聚合指纹（例如全局错误捕获已按统一规则算好）；
+            // 显式值优先于按本条日志错误推导的指纹，避免同一错误在直接上报与 sink 转发
+            // 两条出口下落到不同 issue。
+            const contextFingerprint = reportContext.runtime_error_fingerprint;
             currentTelemetry.reportError({
                 addition: {
                     ...reportContext,
-                    runtime_error_fingerprint: entry.errorInfo?.fingerprint,
+                    runtime_error_fingerprint: typeof contextFingerprint === 'string' && contextFingerprint ? contextFingerprint : entry.errorInfo?.fingerprint,
                     runtime_log_domain: entry.domain,
                     runtime_log_id: entry.id,
                     runtime_log_level: entry.level,
@@ -10895,7 +10902,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-B-4yrLNm.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-BiAaAUFC.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -14908,7 +14915,7 @@ function createLaunchSnapshot(source, requestOrigin) {
     if (storedContextUrl) {
         snapshot.dev_context_url = projectStoredDevContextUrl(storedContextUrl, requestOrigin.hostname);
     }
-    if (context.parseMiniProgramRuntimePermissions(source.runtimePermissions).valid && source.runtimePermissions) {
+    if (runtimePermissionEnv.parseMiniProgramRuntimePermissions(source.runtimePermissions).valid && source.runtimePermissions) {
         snapshot.runtime_permissions = JSON.parse(JSON.stringify(source.runtimePermissions));
     }
     return snapshot;
@@ -14960,7 +14967,7 @@ const DEFAULT_BROWSER_DEV_HOST_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';
-// Shared with Heybox H5 Vite plugins so hb-sdk can own the launch output.
+// 与 Heybox H5 Vite 插件共享，让 hb-sdk 统一管理启动输出。
 const MANAGED_DEV_OUTPUT_ENV = 'HEYBOX_DEV_SERVER_MANAGED_OUTPUT';
 const VITE_LOG_LEVEL = 'warn';
 async function runDevCommand(options, runtime = {}) {
@@ -14975,7 +14982,7 @@ async function runDevCommand(options, runtime = {}) {
     const appPort = await selectAvailablePort({
         getPort: getPortImpl,
         host: DEV_LISTEN_HOST,
-        label: 'Vite dev server',
+        label: 'Vite 开发服务器',
         startPort: options.port ?? DEFAULT_APP_PORT,
     });
     const resolvedOptions = {
@@ -14991,9 +14998,9 @@ async function runDevCommand(options, runtime = {}) {
         projectRoot,
         timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
     });
-    const launchRuntimePermissions = context.createBrowserDevRuntimePermissions(context.createBrowserDevPermissionState(devLaunchContext));
-    const vite = await logger.task('正在加载项目 Vite', () => projectVite.loadProjectVite(projectRoot), { successText: '已加载项目 Vite' });
-    const appServer = await logger.task('正在创建 Vite dev server', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions)), runtime.env), runtime.env), { successText: '已创建 Vite dev server' });
+    const launchRuntimePermissions = context.createBrowserDevRuntimePermissions(devLaunchContext.runtimePermissions, context.createBrowserDevPermissionState(devLaunchContext));
+    const vite = await runDevStartupTask(logger, '正在加载项目 Vite', () => projectVite.loadProjectVite(projectRoot), '已加载项目 Vite');
+    const appServer = await runDevStartupTask(logger, '正在创建 Vite 开发服务器', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions)), runtime.env), runtime.env), '已创建 Vite 开发服务器');
     const mobileDevContextUrlsByOrigin = new Map();
     let currentLocalDevLaunchToken = devLaunchContext.localDevLaunchToken;
     appServer.middlewares.use((request, response, next) => {
@@ -15007,12 +15014,8 @@ async function runDevCommand(options, runtime = {}) {
         if (!handled)
             next();
     });
-    await logger.task('正在启动 Vite dev server', () => appServer.listen(appPort), {
-        successText: 'Vite dev server 已启动',
-    });
-    const appUrl = await logger.task('正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl), {
-        successText: '已确定小程序入口',
-    });
+    await runDevStartupTask(logger, '正在启动 Vite 开发服务器', () => appServer.listen(appPort), 'Vite 开发服务器已启动');
+    const appUrl = await runDevStartupTask(logger, '正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl), '已确定小程序入口');
     const buildLanAddresses = () => createLanAddressCandidates({
         appUrl,
         devContextUrlsByMiniUrlOrigin: mobileDevContextUrlsByOrigin,
@@ -15027,7 +15030,7 @@ async function runDevCommand(options, runtime = {}) {
     const closers = [() => appServer.close()];
     let browserDevHost;
     try {
-        browserDevHost = await logger.task('正在启动 Browser Dev Host', () => startBrowserDevHostServer({
+        browserDevHost = await runDevStartupTask(logger, '正在启动浏览器调试页服务', () => startBrowserDevHostServer({
             appUrl,
             devContext: devLaunchContext,
             fetchImpl,
@@ -15048,7 +15051,7 @@ async function runDevCommand(options, runtime = {}) {
             root: runtime.browserDevHostRoot,
             rootCandidates: runtime.browserDevHostRootCandidates,
             runtimePermissions: devLaunchContext.runtimePermissions,
-        }), { successText: 'Browser Dev Host 已启动' });
+        }), '浏览器调试页服务已启动');
     }
     catch (error) {
         await closeAll(closers);
@@ -15079,23 +15082,29 @@ async function runDevCommand(options, runtime = {}) {
         });
         closers.push(tokenSession.close);
     }
-    logger.success('Browser Dev Host 已就绪');
-    logger.info(`Browser Dev Host: ${browserDevHost.url}`);
-    logger.info(`Mini program URL: ${appUrl}`);
-    logger.info('Mobile APP: scan the QR code in Browser Dev Host');
+    logger.success('本地调试已启动');
+    logger.info(`调试页：${browserDevHost.url}`);
+    logger.info(`小程序地址：${appUrl}`);
+    logger.info('手机调试：请在调试页扫码');
     if (options.open !== false) {
         logger.debug('正在打开浏览器调试页');
         void openUrl(browserDevHost.url);
     }
     installShutdownHandlers(closers, runtime.process ?? process);
 }
+function runDevStartupTask(logger, text, action, successText) {
+    if (!logger.verbose) {
+        return action();
+    }
+    return logger.task(text, () => action(), { successText });
+}
 async function loadDevLaunchContext(options) {
     const miniProgramId = await context.readBoundMiniProgramId(options.projectRoot);
     if (!miniProgramId) {
         throw new Error('hb-sdk dev 需要绑定小程序。请先运行 hb-sdk remote create 或 hb-sdk remote bind <mini-program-id>。');
     }
     try {
-        const { detail, miniProgramId: verifiedMiniProgramId } = await options.logger.task('正在读取远端小程序权限', () => loadRemoteDevContextWithTimeout({
+        const { detail, miniProgramId: verifiedMiniProgramId } = await runDevStartupTask(options.logger, '正在读取远端小程序权限', () => loadRemoteDevContextWithTimeout({
             fetchImpl: options.fetchImpl,
             load: (fetchImpl) => context.getBoundMiniProgram({
                 cwd: options.projectRoot,
@@ -15103,12 +15112,16 @@ async function loadDevLaunchContext(options) {
                 fetchImpl,
             }),
             timeoutMs: options.timeoutMs,
-        }), { successText: '已读取远端小程序权限' });
+        }), '已读取远端小程序权限');
+        const localPermissions = runtimePermissionEnv.readMiniappPermissionsFromPackageJson(options.projectRoot, runtimePermissionEnv.resolveMiniappSdkVersion());
+        if (!localPermissions.declared)
+            options.logger.warn(runtimePermissionEnv.getMissingPermissionsWarning());
+        const effectivePermissions = runtimePermissionEnv.composeMiniappRuntimePermissions(localPermissions, detail.runtime_permissions).runtimePermissions;
         return {
             context: {
                 source: 'remote',
                 miniProgramId: verifiedMiniProgramId,
-                runtimePermissions: detail.runtime_permissions,
+                runtimePermissions: effectivePermissions,
             },
             miniProgram: createMiniProgramSummary(verifiedMiniProgramId, detail),
         };
@@ -15303,25 +15316,30 @@ async function closeAll(closers) {
 function startLocalDevLaunchTokenSession(options) {
     let closed = false;
     let expirationTimer;
+    let hasReportedTokenFailure = false;
     let refreshTimer;
     const refresh = async () => {
         try {
             const issued = await issueLocalDevLaunchToken(options);
             if (closed)
                 return;
-            if (!issued) {
-                schedule(options.timeoutMs);
-                return;
-            }
             options.onToken(issued.token);
             const ttl = Math.max(0, issued.expiresAt - Date.now());
             scheduleExpiration(ttl);
             schedule(Math.max(1_000, Math.floor(ttl * 0.8)));
+            if (hasReportedTokenFailure) {
+                hasReportedTokenFailure = false;
+                options.logger.success('手机扫码调试已恢复');
+            }
         }
         catch (error) {
             if (closed)
                 return;
-            options.logger.warn(`刷新本地调试启动票失败，将自动重试：${index.readRedactedErrorMessage(error)}`);
+            if (!hasReportedTokenFailure) {
+                options.logger.warn('手机扫码调试凭证获取失败，将自动重试');
+            }
+            hasReportedTokenFailure = true;
+            options.logger.debug(`手机扫码调试凭证获取失败，详细原因：${index.readRedactedErrorMessage(error, { verbose: true })}`);
             schedule(options.timeoutMs);
         }
     };
@@ -15352,31 +15370,25 @@ function startLocalDevLaunchTokenSession(options) {
     };
 }
 async function issueLocalDevLaunchToken(options) {
-    try {
-        const issued = await loadRemoteDevContextWithTimeout({
-            fetchImpl: options.fetchImpl,
-            timeoutMs: options.timeoutMs,
-            load: (fetchImpl) => context.createLocalDevLaunchToken({
-                cwd: options.projectRoot,
-                env: options.env,
-                fetchImpl,
-                miniProgramId: options.miniProgramId,
-            }),
-        });
-        const token = typeof issued.token === 'string' ? issued.token.trim() : '';
-        if (!token) {
-            throw new Error('响应缺少 token');
-        }
-        const expiresAt = normalizeExpiresAt(issued.expires_at);
-        if (!expiresAt || expiresAt <= Date.now()) {
-            throw new Error('响应缺少有效 expires_at');
-        }
-        return { expiresAt, token };
+    const issued = await loadRemoteDevContextWithTimeout({
+        fetchImpl: options.fetchImpl,
+        timeoutMs: options.timeoutMs,
+        load: (fetchImpl) => context.createLocalDevLaunchToken({
+            cwd: options.projectRoot,
+            env: options.env,
+            fetchImpl,
+            miniProgramId: options.miniProgramId,
+        }),
+    });
+    const token = typeof issued.token === 'string' ? issued.token.trim() : '';
+    if (!token) {
+        throw new Error('响应缺少 token');
     }
-    catch (error) {
-        options.logger.warn(`未能签发本地调试启动票，扫码后公开详情可能仍拿不到未发布小程序身份：${index.readRedactedErrorMessage(error)}`);
-        return undefined;
+    const expiresAt = normalizeExpiresAt(issued.expires_at);
+    if (!expiresAt || expiresAt <= Date.now()) {
+        throw new Error('响应缺少有效 expires_at');
     }
+    return { expiresAt, token };
 }
 function normalizeExpiresAt(value) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)