@heybox/hb-sdk 0.6.9 → 0.7.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.7.0-alpha.2
+
+### CLI
+
+- `hb-sdk dev` 绑定远端小程序后签发并轮换 local_dev 启动票，把独立的 `preview_token` 写入扫码 URL，供 Host 兑换 unpublished 公开详情。
+
+### Runtime
+
+- 允许的 `mini_url` 调试入口会绑定 Host 上的 `mini_program_id`；公开详情对 unpublished 失败时也不丢这个身份。
+
+## 0.7.0-alpha.1
+
+### Docs / Agent Skill
+
+- 开发者服务端改为调用 `GET /user_miniprogram/openapi/v1/user` 读取当前用户，不再使用已下线的 `/user/identity` 与 `/user/profile`。
+
+### Runtime
+
+- 公开详情关网时的合法空权限快照视为未开通 `network.request`，允许本地身份读取与撤销授权。
+
+## 0.7.0-alpha.0
+
+### Release
+
+- 硬切小程序隐私用户身份 v2 契约，并保留 v1 bridge 握手兼容。
+- 排行榜记录的公开用户标识从 `userId` 硬切为按小程序隔离的 `appUserId`。
+
+### SDK
+
+- 已开通网络权限的小程序统一通过 `auth.login({ scopes? })` 获取 5 分钟短期授权码；identity 隐式强制包含，返回值不再携带用户、资料或 `appUserId`。
+- 未开通网络权限的小程序通过 `user.getLocalIdentity()` 读取当前小程序内隔离的 `appUserId`，不能获取授权码或调用 OpenAPI。
+- 新增 `user.revokeAuthorization()`，在两种网络模式下由可信用户操作撤销当前账号对当前小程序的授权。
+- 已开通网络权限时，Host current-user 资料与平台账号读取统一提示 `SERVER_API_REQUIRED`，由开发者服务端通过 OpenAPI 获取。
+
+### Security
+
+- 授权码只能交给开发者服务端换取 token；小程序页面不得持有服务端应用凭据，`network.request` 也不能访问平台保留的 runtime auth 与 OpenAPI 内部路径。
+- 需要授权 UI 且缺少可信用户手势时返回 `USER_GESTURE_REQUIRED`；用户取消或关闭时返回 `AUTHORIZATION_CANCELLED`，已授权场景可静默签发新 code。
+
+### Docs / Agent Skill
+
+- README、用户身份 Guide、快速开始、登录门禁、错误处理、生命周期、CLI 与排行榜文档同步新身份边界，并移除旧用户授权 API 指引。
+
 ## 0.6.9
 
 ### SDK
@@ -45,16 +88,17 @@
 
 ### SDK
 
-- `network.request` 失败时输出脱敏诊断日志，覆盖 HTTP 非 2xx、无效响应与 bridge/runtime 错误；`HbMiniProgramNetworkError` 文案补充 statusText/method/url（message 为诊断字符串，业务请用 `instanceof` + `status`/`data` 等字段，勿精确匹配全文） (@heybox/hb-sdk).
-- 诊断日志与错误文案统一脱敏：敏感 header/query/body 字段、URL userinfo；Mock Host / mock network proxy 复用同一套脱敏原语 (@heybox/hb-sdk).
-- 日志前缀：`[hb-sdk][network.request]` / `[hb-sdk][mock-host][network.request]` / `[hb-sdk][mock-network]` (@heybox/hb-sdk).
-- `network.request` 提前拒绝 `multipart/form-data`（含手写 boundary body），以 `INVALID_PARAMS` 给出可操作中文说明；Mock 网络代理同步拒绝，避免本地 fetch 能通、App Host heybox 代发失败 (@heybox/hb-sdk).
-- `HbMiniProgramNetworkError` 识别宿主伪装的 `network_error` / `unsupported-request-shape` 失败，在 message 中标明“非目标站 HTTP 状态”并补充 form/json 用法提示 (@heybox/hb-sdk).
+- 用户身份 API 收敛为 `auth.requireHeyboxAppLogin()`、`user.getInfo()` 与 `user.authorize()`；登录不再返回资料，身份使用按小程序隔离的 `app_user_id`，资料按授权 scope 披露。
+- Vue 3 模板、调试示例与公开文档同步使用 v2 登录和资料授权流程。
 
 ### Runtime
 
-- Runtime 侧记录 `network.request` 参数校验失败、adapter 失败与非 2xx 诊断日志（前缀 `[hb-sdk-runtime][network.request]`；非 2xx 仍保持 bridge success） (@heybox/hb-sdk-runtime).
-- Runtime 参数校验同步拒绝 multipart，避免落到 heybox transport 后变成含糊的 500 `network_error` (@heybox/hb-sdk-runtime).
+- Host 集成改用稳定的用户身份隔离接口，并由 Runtime 构造授权结果，避免转发后端额外字段。
+- `user.authorize` 对畸形 payload 稳定返回 `INVALID_PARAMS`；浏览器 Mock 使用 `heybox_app_login_change` 与 `user_info_authorization_change` 事件，并保持授权事件不携带身份资料。
+
+### Docs / Agent Skill
+
+- 同步 README、Guide、Recipe、API Reference 与 Agent Skill，移除已删除的用户 API 指引。
 
 ## 0.6.8-alpha.2
 

package/README.md

@@ -23,20 +23,49 @@ npm run dev
 npm install @heybox/hb-sdk
 ```
 
-页面启动时等待 SDK 就绪，再读取当前用户状态：
+页面启动时先等待 SDK 就绪。未开通网络权限的小程序可以读取当前小程序内的隔离身份：
 
 ```ts
 import hbSDK from '@heybox/hb-sdk';
 
-await hbSDK.ready();
+async function getLocalIdentityFromUserAction() {
+  await hbSDK.ready();
+  const { appUserId } = await hbSDK.user.getLocalIdentity();
+  return appUserId;
+}
+```
+
+把 `getLocalIdentityFromUserAction` 绑定到按钮点击等可信用户操作。首次登录或 identity consent 需要 UI 而缺少可信手势时返回 `USER_GESTURE_REQUIRED`；用户取消或关闭时返回 `AUTHORIZATION_CANCELLED`，不会确认或改变授权状态。
+
+已开通网络权限的小程序在按钮点击等明确的用户操作中调用 `auth.login()`：
+
+```ts
+async function loginFromUserAction() {
+  const { code, expiresIn, scopes } = await hbSDK.auth.login({ scopes: ['profile'] });
+  await hbSDK.network.request({
+    url: 'https://api.example.com/session/heybox',
+    method: 'POST',
+    data: { code },
+  });
+  console.log(expiresIn, scopes);
+}
+```
+
+`auth.login()` 返回 `{ code, expiresIn: 300, scopes }`，其中 `identity` 隐式强制包含；它不返回 user、profile、`appUserId` 或 token。页面只能把 code 交给开发者服务端，再由服务端按后端 OpenAPI 文档换取 token。未开通网络权限的小程序使用 `user.getLocalIdentity()`，无法获取 code 或调用 OpenAPI。完整边界见[用户身份与登录](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)。
+
+用户可以在明确的按钮点击和二次确认后撤销当前小程序的授权：
+
+```ts
+async function revokeAuthorizationFromUserAction() {
+  const confirmed = window.confirm('确定撤销当前小程序的用户授权吗？');
+  if (!confirmed) return;
 
-const result = await hbSDK.user.getInfo();
-if (result.isLogin && result.userInfo) {
-  console.log(result.userInfo.nickname);
+  await hbSDK.user.revokeAuthorization();
+  // 同步清理业务保存的 appUserId、用户资料和服务端会话。
 }
 ```
 
-`ready()` 只表示 SDK 可以调用，不代表用户已经登录。需要登录时，请在按钮点击等明确的用户操作中调用 `hbSDK.auth.login()`。
+`user.revokeAuthorization()` 在已开通和未开通网络权限的小程序中都可用，不接收小程序 ID、黑盒用户 ID 或手势参数。调用必须来自可信用户操作，否则返回 `USER_GESTURE_REQUIRED`。撤销成功后，后续身份或授权读取会重新进入授权流程；SDK 不会替业务清理已经持久化的数据。
 
 已有 Vite 项目还需要启用构建插件：
 
@@ -76,31 +105,65 @@ try {
 
 除 `ready()` 外，SDK 还提供 `on()` 和 `off()` 处理前后台、登录态等生命周期事件。
 
-| 模块         | 用途                             |
-| ------------ | -------------------------------- |
-| `auth`       | 由用户操作触发登录               |
-| `user`       | 读取当前用户、账号资料和游戏数据 |
-| `share`      | 打开分享或截图分享流程           |
-| `ui`         | 展示 Toast 和 Loading            |
-| `device`     | 调用振动和剪贴板能力             |
-| `navigation` | 关闭、刷新页面或打开小黑盒页面   |
-| `viewport`   | 读取窗口信息和设置导航栏样式     |
-| `storage`    | 读写当前小程序的隔离存储         |
-| `cloud`      | 使用小程序云端排行榜             |
-| `network`    | 发起经过平台授权的网络请求       |
+| 模块         | 用途                                                         |
+| ------------ | ------------------------------------------------------------ |
+| `auth`       | 获取交给开发者服务端交换的短期授权码                         |
+| `user`       | 使用 Host current-user APIs 或读取无网络小程序的本地隔离身份 |
+| `share`      | 打开分享或截图分享流程                                       |
+| `ui`         | 展示 Toast 和 Loading                                        |
+| `device`     | 调用振动和剪贴板能力                                         |
+| `navigation` | 关闭、刷新页面或打开小黑盒页面                               |
+| `viewport`   | 读取窗口信息和设置导航栏样式                                 |
+| `storage`    | 读写当前小程序的隔离存储                                     |
+| `cloud`      | 使用小程序云端排行榜                                         |
+| `network`    | 发起经过平台授权的网络请求                                   |
 
 具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
 
 ## 关键约束
 
-- `ready()` 不代表用户已登录；使用 `user.getInfo()` 判断登录状态。
-- `auth.login()` 只能由明确的用户操作触发，不要在页面初始化时自动登录。
+- `ready()` 只表示 SDK 可调用，不表示已取得用户授权。
+- `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()` 和 `user.getLocalIdentity()` 返回 `SERVER_API_REQUIRED`；对应身份和资料数据应由开发者服务端通过 OpenAPI 获取。
+- 未开通网络权限时，只用 `user.getLocalIdentity()` 获取 `{ appUserId }`，不能获取 code 或调用 OpenAPI。
+- `user.revokeAuthorization()` 在两种网络模式下都要求可信用户手势；成功后必须停止使用并清理业务缓存的旧身份、资料和服务端会话。
 - `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
 - 业务网络请求使用 `network.request()`，不要依赖浏览器原生网络出口。
+- `network.request()` 不能访问平台保留的 runtime auth 与 OpenAPI 内部路径；页面不得持有或交换服务端应用凭据。
 - `network.request` 不支持 `multipart/form-data`；App Host 仅支持 form（`application/x-www-form-urlencoded`）与 JSON。表单请用 `URLSearchParams#toString()` 作为 `data`，文件上传请走专用上传能力。
 - 仅当远端已启用 `network.request` 且 `useOfficialDomain=true` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。
 - 构建必须启用 `miniappManifest()`，推荐统一使用 `hb-sdk build`。
 
+## 云端排行榜
+
+删除当前用户的排行榜成绩属于破坏性操作，只能在明确的用户操作和二次确认后执行：
+
+```ts
+async function deleteMyLeaderboardEntryFromUserAction() {
+  const confirmed = window.confirm('确定删除自己的榜单成绩吗？');
+  if (!confirmed) return;
+
+  try {
+    await hbSDK.cloud.leaderboard.deleteCurrentUserEntry({ key: 'cube_run_total' });
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError) {
+      console.error(error.code, error.message);
+    }
+    throw error;
+  }
+}
+```
+
+排行榜记录的 `extra` 会展示给榜单中的其他读取者，只能包含公开展示必需的数据；不得写入个人身份信息（PII）、token、设备标识或非必要行为数据。
+
+管理员删除完整榜单及其排名记录时，必须显式传入匹配的榜单 key 进行确认：
+
+```bash
+hb-sdk remote cloud leaderboard delete <key> --confirm <key>
+```
+
 ## CLI 主流程
 
 ```bash

package/dist/cli-chunks/{build-BtGxhrcV.cjs → build-DLIhlBQA.cjs}

@@ -3,10 +3,10 @@
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-DKrhgVM3.cjs');
-var runtimeGate = require('./runtime-gate-BWlU-R4h.cjs');
-var index = require('./index-tCURDEx8.cjs');
-var projectVite = require('./project-vite-DAUaP0_3.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D-8_jPG3.cjs');
+var runtimeGate = require('./runtime-gate-CtV7rWyX.cjs');
+var index = require('./index-BnBeTd0B.cjs');
+var projectVite = require('./project-vite-CgnCpNDZ.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');

package/dist/cli-chunks/{context-DX1KG-8A.cjs → context-Bl_Q4RKq.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
-var session = require('./session-D6jOKXeu.cjs');
-var runtimePermissionEnv = require('./runtime-permission-env-DKrhgVM3.cjs');
+var session = require('./session-Davw2CMd.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D-8_jPG3.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
@@ -109,6 +109,7 @@ function createRemoteApiClient(options) {
         listUserMiniprograms: (requestOptions = {}) => listUserMiniprograms(requestOptions, options),
         createUserMiniprogram: () => createUserMiniprogram(options),
         getUserMiniprogramDetail: (requestOptions) => getUserMiniprogramDetail(requestOptions, options),
+        createLocalDevLaunchToken: (requestOptions) => createLocalDevLaunchToken$1(requestOptions, options),
         getPreviewAllowlist: (requestOptions) => getPreviewAllowlist(requestOptions, options),
         updatePreviewAllowlist: (requestOptions) => updatePreviewAllowlist(requestOptions, options),
         createUserMiniprogramLeaderboard: (requestOptions) => createUserMiniprogramLeaderboard(requestOptions, options),
@@ -144,6 +145,9 @@ async function createUserMiniprogram(runtime) {
 async function getUserMiniprogramDetail(options, runtime) {
     return remoteGet(runtimePermissionEnv.DETAIL_USER_MINIPROGRAM_API_PATH, options, runtime);
 }
+async function createLocalDevLaunchToken$1(options, runtime) {
+    return remotePostForm(runtimePermissionEnv.CREATE_USER_MINIPROGRAM_LOCAL_DEV_LAUNCH_TOKEN_API_PATH, options, runtime);
+}
 async function getPreviewAllowlist(options, runtime) {
     return remoteGet(runtimePermissionEnv.USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, options, runtime);
 }
@@ -384,6 +388,14 @@ async function getBoundMiniProgram(options = {}, runtime = {}) {
         detail,
     };
 }
+async function createLocalDevLaunchToken(options, runtime = {}) {
+    const miniProgramId = options.miniProgramId.trim();
+    if (!miniProgramId) {
+        throw new Error('mini-program-id 不能为空');
+    }
+    const api = await resolveRemoteApiClient(options, runtime);
+    return api.createLocalDevLaunchToken({ mini_program_id: miniProgramId });
+}
 async function resolveRemoteApiClient(options, runtime) {
     if (runtime.apiClient) {
         return runtime.apiClient;
@@ -397,6 +409,7 @@ function isTruthyEnvFlag(value) {
 }
 
 exports.MiniProgramProjectBindingError = MiniProgramProjectBindingError;
+exports.createLocalDevLaunchToken = createLocalDevLaunchToken;
 exports.createMiniProgramMockPermissionState = createMiniProgramMockPermissionState;
 exports.createMiniProgramMockRuntimePermissions = createMiniProgramMockRuntimePermissions;
 exports.createRemoteApiClientForEnvironment = createRemoteApiClientForEnvironment;

package/dist/cli-chunks/{create-DAD0OF1r.cjs → create-C--pwY0l.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-tCURDEx8.cjs');
+var index = require('./index-BnBeTd0B.cjs');
 require('node:module');
 require('os');
 require('readline');

package/dist/cli-chunks/{dev-Dh4HY0I8.cjs → dev-B1tyT5ql.cjs}

@@ -6,15 +6,15 @@ var path = require('node:path');
 var net = require('node:net');
 var promises = require('node:dns/promises');
 var node_http = require('node:http');
-var context = require('./context-DX1KG-8A.cjs');
+var context = require('./context-Bl_Q4RKq.cjs');
 var node_crypto = require('node:crypto');
 var undici = require('undici');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-tCURDEx8.cjs');
-var projectVite = require('./project-vite-DAUaP0_3.cjs');
+var index = require('./index-BnBeTd0B.cjs');
+var projectVite = require('./project-vite-CgnCpNDZ.cjs');
 var fs$1 = require('node:fs/promises');
-var runtimePermissionEnv = require('./runtime-permission-env-DKrhgVM3.cjs');
-require('./session-D6jOKXeu.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-D-8_jPG3.cjs');
+require('./session-Davw2CMd.cjs');
 require('fs');
 require('constants');
 require('stream');
@@ -896,18 +896,19 @@ const MOCK_HOST_ROOT_CANDIDATES = [
 async function startMiniProgramMockHostServer(options) {
     const root = options.root ?? resolveMiniProgramMockHostRoot(options.rootCandidates);
     assertCompleteMiniProgramMockHostRoot(root);
-    const bootstrapJson = serializeMockHostBootstrap({
+    const bootstrap = {
         defaultLanAddressId: options.defaultLanAddressId,
         devContext: options.devContext,
         lanAddresses: options.lanAddresses ?? [],
         macAppProtocol: options.macAppProtocol,
         nativeAppLaunchUnavailableReason: options.nativeAppLaunchUnavailableReason,
         runtimePermissions: options.runtimePermissions,
-    });
+    };
+    let bootstrapJson = serializeMockHostBootstrap(bootstrap);
     const server = createMiniProgramMockHostServer(root, {
         appUrl: options.appUrl,
         allowedMiniUrlOrigins: new Set((options.lanAddresses ?? []).map(({ appUrl }) => new URL(appUrl).origin)),
-        bootstrapJson,
+        readBootstrapJson: () => bootstrapJson,
         fetchImpl: options.fetchImpl ?? fetch,
         isLoopbackPeer: options.isLoopbackPeer ?? isLoopbackAddress,
         lookupHostname: options.lookupHostname ?? (async (hostname) => promises.lookup(hostname, { all: true, verbatim: true })),
@@ -921,6 +922,17 @@ async function startMiniProgramMockHostServer(options) {
         close: () => new Promise((resolve) => {
             server.close(() => resolve());
         }),
+        updateBootstrap: (next) => {
+            if (next.devContext !== undefined)
+                bootstrap.devContext = next.devContext;
+            if (next.lanAddresses !== undefined)
+                bootstrap.lanAddresses = next.lanAddresses;
+            if (next.macAppProtocol === null)
+                delete bootstrap.macAppProtocol;
+            else if (next.macAppProtocol !== undefined)
+                bootstrap.macAppProtocol = next.macAppProtocol;
+            bootstrapJson = serializeMockHostBootstrap(bootstrap);
+        },
         networkUrls: createMiniProgramMockHostNetworkUrls({
             lanAddresses: options.lanAddresses,
             port,
@@ -988,6 +1000,7 @@ function createMiniProgramMockHostServer(root, runtime) {
         const pathname = decodeURIComponent(requestUrl.pathname);
         const devSessionRoute = devSessionRoutes.match(pathname);
         const loopbackPeer = runtime.isLoopbackPeer(request.socket.remoteAddress);
+        // Dev Session 需要允许手机局域网访问；其余 mock 页仍限制本机。
         if (!loopbackPeer && !devSessionRoute) {
             writeForbidden(response);
             return;
@@ -1012,7 +1025,7 @@ function createMiniProgramMockHostServer(root, runtime) {
                 writeMethodNotAllowed(response, 'GET');
                 return;
             }
-            writeSerializedJsonResponse(response, 200, runtime.bootstrapJson);
+            writeSerializedJsonResponse(response, 200, runtime.readBootstrapJson());
             return;
         }
         if (pathname === DEV_PERMISSIONS_PATH && runtime.permissionController) {
@@ -1224,13 +1237,15 @@ async function listenHttpServer(server, options, getPortImpl) {
 const MINI_PROGRAM_URL_QUERY_PARAM = 'mini_url';
 const MINI_PROGRAM_RUNTIME_URL_QUERY_PARAM = 'runtime_url';
 const MINI_PROGRAM_SDK_VERSION_QUERY_PARAM = 'sdk_version';
+const MINI_PROGRAM_LOCAL_DEV_LAUNCH_TOKEN_QUERY_PARAM = 'local_dev_launch_token';
 const MINI_PROGRAM_DEV_SHELL_URL = 'heybox-mini-dev://sandbox';
 const OPEN_IN_APP_URL = 'https://api.xiaoheihe.cn/open_inapp/';
 function createMacAppProtocol(appUrl, options = {}) {
     return createHeyboxProtocol(createMiniProgramDevShellOpenWindowPayload(appUrl, options));
 }
 function createMobileAppQrPayload(appUrl, options = {}) {
-    return `${OPEN_IN_APP_URL}#${createHeyboxProtocol(createMiniProgramDevShellOpenWindowPayload(appUrl, { ...options, encodeMiniUrl: false }))}`;
+    const protocol = createHeyboxProtocol(createMiniProgramDevShellOpenWindowPayload(appUrl, { ...options, encodeMiniUrl: false }));
+    return options.bareProtocol ? protocol : `${OPEN_IN_APP_URL}#${protocol}`;
 }
 function createMiniProgramDevShellOpenWindowPayload(appUrl, options = {}) {
     const devShellUrl = options.encodeMiniUrl === false
@@ -1258,8 +1273,13 @@ function createPartiallyEncodedMiniProgramDevShellUrl(appUrl, options) {
     if (miniProgramId) {
         devShellUrl += `&mini_program_id=${encodeURIComponent(miniProgramId)}`;
     }
+    const localDevLaunchToken = options.localDevLaunchToken?.trim();
+    if (localDevLaunchToken) {
+        devShellUrl += `&${MINI_PROGRAM_LOCAL_DEV_LAUNCH_TOKEN_QUERY_PARAM}=${encodeURIComponent(localDevLaunchToken)}`;
+    }
     if (hasRuntimeUrl(options.runtimeUrl)) {
-        devShellUrl += `&${MINI_PROGRAM_RUNTIME_URL_QUERY_PARAM}=${encodeURIComponent(options.runtimeUrl)}`;
+        const runtimeUrl = buildRuntimeUrlWithLaunchParams(options.runtimeUrl, appUrl, options);
+        devShellUrl += `&${MINI_PROGRAM_RUNTIME_URL_QUERY_PARAM}=${encodeURIComponent(runtimeUrl)}`;
     }
     const sdkVersion = options.sdkVersion?.trim();
     if (sdkVersion) {
@@ -1274,8 +1294,12 @@ function createEncodedMiniProgramDevShellUrl(appUrl, options) {
     if (miniProgramId) {
         devShellUrl.searchParams.set('mini_program_id', miniProgramId);
     }
+    const localDevLaunchToken = options.localDevLaunchToken?.trim();
+    if (localDevLaunchToken) {
+        devShellUrl.searchParams.set(MINI_PROGRAM_LOCAL_DEV_LAUNCH_TOKEN_QUERY_PARAM, localDevLaunchToken);
+    }
     if (hasRuntimeUrl(options.runtimeUrl)) {
-        devShellUrl.searchParams.set(MINI_PROGRAM_RUNTIME_URL_QUERY_PARAM, options.runtimeUrl);
+        devShellUrl.searchParams.set(MINI_PROGRAM_RUNTIME_URL_QUERY_PARAM, buildRuntimeUrlWithLaunchParams(options.runtimeUrl, appUrl, options));
     }
     const sdkVersion = options.sdkVersion?.trim();
     if (sdkVersion) {
@@ -1286,6 +1310,36 @@ function createEncodedMiniProgramDevShellUrl(appUrl, options) {
 function hasRuntimeUrl(runtimeUrl) {
     return runtimeUrl !== undefined && runtimeUrl !== '';
 }
+/**
+ * 客户端加载 runtime_url 时，常只打开该 URL 本身，不会把 sandbox 上的 mini_url 再拼进去。
+ * 电脑浏览器手开 detail 能成功，是因为 URL 上已经带了 mini_url。
+ * 因此 HTTP(S) runtime host 需要在 runtime_url 内预置启动参数。
+ */
+function buildRuntimeUrlWithLaunchParams(runtimeUrl, appUrl, options) {
+    try {
+        const url = new URL(runtimeUrl);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return runtimeUrl;
+        }
+        url.searchParams.set(MINI_PROGRAM_URL_QUERY_PARAM, appUrl);
+        const miniProgramId = options.miniProgramId?.trim();
+        if (miniProgramId) {
+            url.searchParams.set('mini_program_id', miniProgramId);
+        }
+        const localDevLaunchToken = options.localDevLaunchToken?.trim();
+        if (localDevLaunchToken) {
+            url.searchParams.set(MINI_PROGRAM_LOCAL_DEV_LAUNCH_TOKEN_QUERY_PARAM, localDevLaunchToken);
+        }
+        const sdkVersion = options.sdkVersion?.trim();
+        if (sdkVersion) {
+            url.searchParams.set(MINI_PROGRAM_SDK_VERSION_QUERY_PARAM, sdkVersion);
+        }
+        return url.toString();
+    }
+    catch {
+        return runtimeUrl;
+    }
+}
 function createHeyboxProtocol(payload) {
     return `heybox://${encodeURIComponent(JSON.stringify(payload))}`;
 }
@@ -1293,7 +1347,7 @@ function createHeyboxProtocol(payload) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.9';
+    : '0.7.0-alpha.2';
 
 class DevPermissionOverrideStoreError extends Error {
     code;
@@ -1476,6 +1530,8 @@ async function runDevCommand(options, runtime = {}) {
         hmrHost: resolvedOptions.hmrHost,
         interfaces: networkInterfaceSnapshot,
         miniProgramId: devLaunchContext.miniProgramId,
+        localDevLaunchToken: devLaunchContext.localDevLaunchToken,
+        rawProtocol: options.rawProtocol,
         runtimeUrl: options.runtimeUrl,
         sdkVersion: HB_SDK_VERSION,
         viteNetworkUrls: appServer.resolvedUrls?.network ?? [],
@@ -1493,6 +1549,7 @@ async function runDevCommand(options, runtime = {}) {
             lookupHostname: runtime.lookupHostname,
             macAppProtocol: createMacAppProtocol(appUrl, {
                 miniProgramId: devLaunchContext.miniProgramId,
+                localDevLaunchToken: devLaunchContext.localDevLaunchToken,
                 runtimeUrl: options.runtimeUrl,
                 sdkVersion: HB_SDK_VERSION,
             }),
@@ -1508,6 +1565,45 @@ async function runDevCommand(options, runtime = {}) {
         throw error;
     }
     closers.push(() => mockHost.close());
+    if (devLaunchContext.source === 'remote' && devLaunchContext.miniProgramId) {
+        const tokenSession = startLocalDevLaunchTokenSession({
+            env: runtime.env,
+            fetchImpl,
+            logger,
+            miniProgramId: devLaunchContext.miniProgramId,
+            onToken: (localDevLaunchToken) => {
+                const tokenContext = {
+                    source: 'remote',
+                    miniProgramId: devLaunchContext.miniProgramId,
+                    ...(localDevLaunchToken ? { localDevLaunchToken } : {}),
+                    runtimePermissions: devLaunchContext.runtimePermissions,
+                };
+                mockHost.updateBootstrap({
+                    devContext: tokenContext,
+                    lanAddresses: createLanAddressCandidates({
+                        appUrl,
+                        hmrHost: resolvedOptions.hmrHost,
+                        interfaces: networkInterfaceSnapshot,
+                        miniProgramId: devLaunchContext.miniProgramId,
+                        localDevLaunchToken,
+                        rawProtocol: options.rawProtocol,
+                        runtimeUrl: options.runtimeUrl,
+                        sdkVersion: HB_SDK_VERSION,
+                        viteNetworkUrls: appServer.resolvedUrls?.network ?? [],
+                    }),
+                    macAppProtocol: createMacAppProtocol(appUrl, {
+                        miniProgramId: devLaunchContext.miniProgramId,
+                        localDevLaunchToken,
+                        runtimeUrl: options.runtimeUrl,
+                        sdkVersion: HB_SDK_VERSION,
+                    }),
+                });
+            },
+            projectRoot,
+            timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
+        });
+        closers.push(tokenSession.close);
+    }
     logger.success('Mock runtime host 已就绪');
     logger.info(`Mock runtime host: ${mockHost.url}`);
     logger.info(`Mini program URL: ${appUrl}`);
@@ -1808,6 +1904,89 @@ function installShutdownHandlers(closers, processLike) {
 async function closeAll(closers) {
     await Promise.allSettled(closers.map((close) => close()));
 }
+function startLocalDevLaunchTokenSession(options) {
+    let closed = false;
+    let expirationTimer;
+    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)));
+        }
+        catch (error) {
+            if (closed)
+                return;
+            options.logger.warn(`刷新本地调试启动票失败，将自动重试：${index.readRedactedErrorMessage(error)}`);
+            schedule(options.timeoutMs);
+        }
+    };
+    const schedule = (delayMs) => {
+        refreshTimer = setTimeout(() => {
+            void refresh();
+        }, Math.max(1, delayMs));
+        refreshTimer.unref?.();
+    };
+    const scheduleExpiration = (ttl) => {
+        if (expirationTimer)
+            clearTimeout(expirationTimer);
+        expirationTimer = setTimeout(() => {
+            if (!closed)
+                options.onToken(undefined);
+        }, Math.max(1, ttl));
+        expirationTimer.unref?.();
+    };
+    void refresh();
+    return {
+        close: () => {
+            closed = true;
+            if (expirationTimer)
+                clearTimeout(expirationTimer);
+            if (refreshTimer)
+                clearTimeout(refreshTimer);
+        },
+    };
+}
+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 };
+    }
+    catch (error) {
+        options.logger.warn(`未能签发本地调试启动票，扫码后公开详情可能仍拿不到未发布小程序身份：${index.readRedactedErrorMessage(error)}`);
+        return undefined;
+    }
+}
+function normalizeExpiresAt(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+        return undefined;
+    return value < 1_000_000_000_000 ? value * 1000 : value;
+}
 function createLanAddressCandidates(options) {
     const viteNetworkUrlByHost = new Map(options.viteNetworkUrls.map((url) => [readUrlHost(url), url]).filter((entry) => Boolean(entry[0])));
     const candidates = createLanInterfaceCandidates(options.interfaces)
@@ -1826,14 +2005,18 @@ function createLanAddressCandidates(options) {
         const runtimeUrl = rewriteLoopbackUrlHost(options.runtimeUrl, address);
         if (runtimeUrl !== undefined) {
             candidate.mobileAppQrPayload = createMobileAppQrPayload(appUrl, {
+                bareProtocol: options.rawProtocol,
                 miniProgramId: options.miniProgramId,
+                localDevLaunchToken: options.localDevLaunchToken,
                 runtimeUrl,
                 sdkVersion: options.sdkVersion,
             });
         }
         else {
             candidate.mobileAppQrPayload = createMobileAppQrPayload(appUrl, {
+                bareProtocol: options.rawProtocol,
                 miniProgramId: options.miniProgramId,
+                localDevLaunchToken: options.localDevLaunchToken,
                 sdkVersion: options.sdkVersion,
             });
         }
@@ -1923,4 +2106,5 @@ function isPrivateIPv4(address) {
     return parts[0] === 10 || (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) || (parts[0] === 192 && parts[1] === 168);
 }
 
+exports.normalizeExpiresAt = normalizeExpiresAt;
 exports.runDevCommand = runDevCommand;

package/dist/cli-chunks/{doctor-BfKdiD3H.cjs → doctor-D9M2scaJ.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-tCURDEx8.cjs');
+var index = require('./index-BnBeTd0B.cjs');
 require('node:module');
 require('path');
 require('os');