@heybox/hb-sdk 0.8.1-alpha.3 → 0.8.1-alpha.6

package/dist/cli-chunks/{dev-CFubP5kW.cjs → dev-DP7WtQOo.cjs}

@@ -1,24 +1,25 @@
 'use strict';
 
+var node_crypto = require('node:crypto');
 var fs = require('node:fs');
 var os = require('node:os');
 var path = require('node:path');
 var net = require('node:net');
-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-DuxaBL3Y.cjs');
-var runtimePermissionEnv = require('./runtime-permission-env-XAZFauvZ.cjs');
+var context = require('./context-DVfWZ6d1.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-DWSscWBT.cjs');
 var undici = require('undici');
 var fs$1 = require('node:fs/promises');
-var index = require('./index-DCJN-V1y.cjs');
+var index = require('./index-CDwwaNvP.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-BnoHxzFq.cjs');
+var session = require('./session-DZXRQ4Dp.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-DMxdOWsU.cjs');
-var version = require('./version-BGzCIQhE.cjs');
+var projectVite = require('./project-vite-CE7kyqxl.cjs');
+var version = require('./version-D19lZmYN.cjs');
+require('node:zlib');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 class Locked extends Error {
@@ -183,6 +184,82 @@ async function getPorts(options) {
 	throw new Error('No available ports found');
 }
 
+/**
+ * network.request 诊断日志的纯脱敏工具。
+ *
+ * @remarks
+ * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
+ * modules observability、devtools Browser Dev Host / proxy 共用，并满足 boundary
+ *（devtools 不得直接 import runtime capability modules）。
+ */
+/** 敏感字段名：header / query / body key 共用。 */
+const SENSITIVE_KEY_PATTERN$1 = /(authorization|cookie|password|passwd|secret|token|pkey|private[_-]?key|access[_-]?key|client[_-]?secret|api[_-]?key|apikey|session|jwt|refresh[_-]?token|csrf)/i;
+/**
+ * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
+ */
+function sanitizeNetworkRequestUrl(url) {
+    if (!url) {
+        return url;
+    }
+    try {
+        const parsed = new URL(url);
+        parsed.username = '';
+        parsed.password = '';
+        redactUrlSearchParams(parsed.searchParams);
+        if (parsed.hash && parsed.hash.length > 1) {
+            const hashBody = parsed.hash.slice(1);
+            if (hashBody.includes('=')) {
+                const hashParams = new URLSearchParams(hashBody);
+                if (redactUrlSearchParams(hashParams)) {
+                    parsed.hash = hashParams.toString();
+                }
+            }
+        }
+        return parsed.toString();
+    }
+    catch {
+        return redactSensitivePairsInRawText(url);
+    }
+}
+/**
+ * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
+ */
+function sanitizeDiagnosticMessage(message) {
+    if (!message) {
+        return message;
+    }
+    return message.replace(/https?:\/\/[^\s]+/gi, matched => sanitizeNetworkRequestUrl(matched.replace(/[),.;]+$/g, '')));
+}
+function isSensitiveNetworkKey(key) {
+    return SENSITIVE_KEY_PATTERN$1.test(key.trim());
+}
+function redactUrlSearchParams(params) {
+    let changed = false;
+    for (const key of [...params.keys()]) {
+        if (isSensitiveNetworkKey(key)) {
+            params.set(key, '[redacted]');
+            changed = true;
+        }
+    }
+    return changed;
+}
+function redactSensitivePairsInRawText(text) {
+    return text.replace(/([?&#]|^|[?&])([^=&#\s]+)=([^&#\s]*)/g, (full, prefix, key, value) => {
+        if (!isSensitiveNetworkKey(key)) {
+            return full;
+        }
+        return `${prefix}${key}=[redacted]`;
+    });
+}
+
+const DEVICE_LOG_PATH = '/__hb_sdk__/device-logs';
+const registryKey = Symbol.for('@heybox/hb-sdk/device-logs');
+const registry = globalThis;
+const stores = (registry[registryKey] ??= new Map());
+function getDeviceLogs(appUrl) {
+    return stores.get(Number(new URL(appUrl).port));
+}
+
 /** Dev Shell 读取局域网 Dev Session endpoint 的 query 参数。 */
 const MINI_PROGRAM_DEV_CONTEXT_QUERY_PARAM = 'dev_context_url';
 /** Browser Dev Host 创建和读取 Dev Session 的固定路径。 */
@@ -546,74 +623,6 @@ function readErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 
-/**
- * network.request 诊断日志的纯脱敏工具。
- *
- * @remarks
- * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
- * modules observability、devtools Browser Dev Host / proxy 共用，并满足 boundary
- *（devtools 不得直接 import runtime capability modules）。
- */
-/** 敏感字段名：header / query / body key 共用。 */
-const SENSITIVE_KEY_PATTERN$1 = /(authorization|cookie|password|passwd|secret|token|pkey|private[_-]?key|access[_-]?key|client[_-]?secret|api[_-]?key|apikey|session|jwt|refresh[_-]?token|csrf)/i;
-/**
- * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
- */
-function sanitizeNetworkRequestUrl(url) {
-    if (!url) {
-        return url;
-    }
-    try {
-        const parsed = new URL(url);
-        parsed.username = '';
-        parsed.password = '';
-        redactUrlSearchParams(parsed.searchParams);
-        if (parsed.hash && parsed.hash.length > 1) {
-            const hashBody = parsed.hash.slice(1);
-            if (hashBody.includes('=')) {
-                const hashParams = new URLSearchParams(hashBody);
-                if (redactUrlSearchParams(hashParams)) {
-                    parsed.hash = hashParams.toString();
-                }
-            }
-        }
-        return parsed.toString();
-    }
-    catch {
-        return redactSensitivePairsInRawText(url);
-    }
-}
-/**
- * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
- */
-function sanitizeDiagnosticMessage(message) {
-    if (!message) {
-        return message;
-    }
-    return message.replace(/https?:\/\/[^\s]+/gi, matched => sanitizeNetworkRequestUrl(matched.replace(/[),.;]+$/g, '')));
-}
-function isSensitiveNetworkKey(key) {
-    return SENSITIVE_KEY_PATTERN$1.test(key.trim());
-}
-function redactUrlSearchParams(params) {
-    let changed = false;
-    for (const key of [...params.keys()]) {
-        if (isSensitiveNetworkKey(key)) {
-            params.set(key, '[redacted]');
-            changed = true;
-        }
-    }
-    return changed;
-}
-function redactSensitivePairsInRawText(text) {
-    return text.replace(/([?&#]|^|[?&])([^=&#\s]+)=([^&#\s]*)/g, (full, prefix, key, value) => {
-        if (!isSensitiveNetworkKey(key)) {
-            return full;
-        }
-        return `${prefix}${key}=[redacted]`;
-    });
-}
-
 const MAX_BROWSER_DEV_HOST_NETWORK_REQUEST_BODY = 2 * 1024 * 1024;
 const MAX_BROWSER_DEV_HOST_NETWORK_RESPONSE_BODY = 5 * 1024 * 1024;
 const DENIED_NETWORK_TARGETS = createDeniedNetworkTargets();
@@ -1851,8 +1860,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-CFubP5kW.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-CFubP5kW.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-DP7WtQOo.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-DP7WtQOo.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'),
@@ -1886,6 +1895,7 @@ async function startBrowserDevHostServer(options) {
         mobileLaunchRedirect: initialMobileLaunchRedirect,
         nativeAppLaunchUnavailableReason: options.nativeAppLaunchUnavailableReason,
         runtimePermissions: options.runtimePermissions,
+        devReadiness: options.devReadiness,
     };
     let bootstrapJson = serializeBrowserDevHostBootstrap(bootstrap);
     const serverRuntime = createBrowserDevHostServer(root, {
@@ -1950,6 +1960,8 @@ async function startBrowserDevHostServer(options) {
             return closePromise;
         },
         updateBootstrap: (next) => {
+            if (next.devReadiness !== undefined)
+                bootstrap.devReadiness = next.devReadiness;
             if (next.devContext !== undefined)
                 bootstrap.devContext = next.devContext;
             if (next.lanAddresses !== undefined) {
@@ -2172,6 +2184,44 @@ function createBrowserDevHostServer(root, runtime) {
             writeSerializedJsonResponse(response, 200, runtime.readBootstrapJson());
             return;
         }
+        if (pathname === '/__hb_sdk__/sandbox') {
+            if (!isValidSensitiveRequest(request, loopbackPeer, runtime.sessionController.csrfToken)) {
+                writeForbidden(response);
+                return;
+            }
+            if (request.method !== 'POST') {
+                writeMethodNotAllowed(response, 'POST');
+                return;
+            }
+            try {
+                const input = await readJsonRequestBody(request);
+                if (!isRecord$2(input) || typeof input.device !== 'string' || typeof input.path !== 'string') {
+                    writeBadRequest(response);
+                    return;
+                }
+                const store = getDeviceLogs(runtime.appUrl);
+                writeJsonResponse(response, 200, store ? await store.listSandbox(input.device, input.path) : { error: '设备服务不可用' });
+            }
+            catch {
+                writeBadRequest(response);
+            }
+            return;
+        }
+        if (pathname === DEVICE_LOG_PATH) {
+            const origin = request.headers.origin;
+            if (!loopbackPeer || !hasNumericLoopbackHost(request) ||
+                (origin && origin !== `http://${request.headers.host}`)) {
+                writeForbidden(response);
+                return;
+            }
+            if (request.method !== 'GET') {
+                writeMethodNotAllowed(response, 'GET');
+                return;
+            }
+            const store = getDeviceLogs(runtime.appUrl);
+            writeJsonResponse(response, 200, store ? store.query(requestUrl.searchParams) : { epoch: '', items: [], devices: [], nextCursor: 0, hasMore: false, gap: false });
+            return;
+        }
         if (pathname === '/session/status') {
             if (!loopbackPeer || !hasNumericLoopbackHost(request)) {
                 writeForbidden(response);
@@ -10902,7 +10952,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-8hgZlNF8.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-B8pX0BrZ.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -14862,7 +14912,7 @@ function containsSecret(value, secret) {
 
 const LAUNCH_CORS_HEADERS = {
     'access-control-allow-methods': 'GET',
-    'access-control-allow-origin': '*',
+    'access-control-allow-origin': 'https://www.xiaoheihe.cn',
     'access-control-allow-private-network': 'true',
     'cache-control': 'no-store',
 };
@@ -14877,6 +14927,10 @@ function tryHandleMiniProgramDevLaunchRequest(request, response, readSource) {
     if (requestUrl.pathname !== MINI_PROGRAM_DEV_LAUNCH_PATH || requestUrl.search !== '') {
         return false;
     }
+    if (!isAllowedLaunchOrigin(request.headers.origin)) {
+        writeLaunchResponse(response, 403);
+        return true;
+    }
     if (request.method !== 'GET' && request.method !== 'OPTIONS') {
         response.writeHead(405, { allow: 'GET', ...LAUNCH_CORS_HEADERS });
         response.end();
@@ -14911,6 +14965,16 @@ function createLaunchSnapshot(source, requestOrigin) {
     const localDevLaunchToken = source.localDevLaunchToken?.trim();
     if (localDevLaunchToken)
         snapshot.local_dev_launch_token = localDevLaunchToken;
+    if (source.devSessionId)
+        snapshot.dev_session_id = source.devSessionId;
+    if (source.expiresAt)
+        snapshot.expires_at = source.expiresAt;
+    const companionManifestSha256 = source.companionManifestSha256?.trim();
+    if (companionManifestSha256)
+        snapshot.companion_manifest_sha256 = companionManifestSha256;
+    const companionArtifactAccessToken = source.companionArtifactAccessToken?.trim();
+    if (companionArtifactAccessToken)
+        snapshot.companion_artifact_access_token = companionArtifactAccessToken;
     const storedContextUrl = source.devContextUrlsByMiniUrlOrigin.get(requestOrigin.origin);
     if (storedContextUrl) {
         snapshot.dev_context_url = projectStoredDevContextUrl(storedContextUrl, requestOrigin.hostname);
@@ -14954,6 +15018,9 @@ function readNumericRequestOrigin(request) {
 function isAllowedLaunchPeer(address) {
     return isLoopbackOrPrivateLanAddress(address);
 }
+function isAllowedLaunchOrigin(origin) {
+    return origin === undefined || origin === 'https://www.xiaoheihe.cn';
+}
 function writeLaunchResponse(response, status, body) {
     response.writeHead(status, {
         ...LAUNCH_CORS_HEADERS,
@@ -14970,6 +15037,10 @@ const LOCAL_DEV_URL_HOST = '127.0.0.1';
 // 与 Heybox H5 Vite 插件共享，让 hb-sdk 统一管理启动输出。
 const MANAGED_DEV_OUTPUT_ENV = 'HEYBOX_DEV_SERVER_MANAGED_OUTPUT';
 const VITE_LOG_LEVEL = 'warn';
+const COMPANION_DEV_MANIFEST_PATH = '/__hb_sdk__/companion/manifest.json';
+const COMPANION_DEV_MANIFEST_MAX_BYTES = 1024 * 1024;
+const COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = 'HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN';
+const COMPANION_ARTIFACT_ACCESS_TOKEN_HEADER = 'x-hb-sdk-companion-dev-token';
 async function runDevCommand(options, runtime = {}) {
     const logger = runtime.logger ?? index.createCliLogger();
     const fetchImpl = runtime.fetchImpl ?? fetch;
@@ -14991,6 +15062,8 @@ async function runDevCommand(options, runtime = {}) {
         port: appPort,
     };
     const projectRoot = projectVite.findProjectRoot(runtime.cwd ?? process.cwd());
+    const companionArtifactAccessToken = (runtime.randomBytes ?? node_crypto.randomBytes)(32).toString('base64url');
+    const devSessionId = node_crypto.randomBytes(16).toString('hex');
     runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
     const { context: devLaunchContext, miniProgram } = await loadDevLaunchContext({
         env: runtime.env,
@@ -14999,22 +15072,58 @@ async function runDevCommand(options, runtime = {}) {
         projectRoot,
         timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
     });
-    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 开发服务器');
+    let launchRuntimePermissions = context.createBrowserDevRuntimePermissions(devLaunchContext.runtimePermissions, context.createBrowserDevPermissionState(devLaunchContext));
     const mobileDevContextUrlsByOrigin = new Map();
+    let currentCompanionManifestSha256;
     let currentLocalDevLaunchToken = devLaunchContext.localDevLaunchToken;
-    appServer.middlewares.use((request, response, next) => {
-        const handled = tryHandleMiniProgramDevLaunchRequest(request, response, () => ({
-            devContextUrlsByMiniUrlOrigin: mobileDevContextUrlsByOrigin,
-            localDevLaunchToken: currentLocalDevLaunchToken,
-            miniProgramId: devLaunchContext.miniProgramId,
-            runtimePermissions: launchRuntimePermissions,
-            sdkVersion: version.HB_SDK_VERSION,
-        }));
-        if (!handled)
-            next();
+    let currentExpiresAt;
+    let tokenSession;
+    const readLaunchSource = () => ({
+        companionArtifactAccessToken,
+        companionManifestSha256: currentCompanionManifestSha256,
+        devContextUrlsByMiniUrlOrigin: mobileDevContextUrlsByOrigin,
+        localDevLaunchToken: currentLocalDevLaunchToken,
+        devSessionId,
+        expiresAt: currentExpiresAt,
+        miniProgramId: devLaunchContext.miniProgramId,
+        runtimePermissions: launchRuntimePermissions,
+        sdkVersion: version.HB_SDK_VERSION,
+    });
+    const launchPlugin = createMiniProgramDevLaunchVitePlugin(readLaunchSource, async (request, response) => {
+        if (request.url !== MINI_PROGRAM_DEV_LAUNCH_PATH || request.headers[COMPANION_ARTIFACT_ACCESS_TOKEN_HEADER] === undefined)
+            return false;
+        response.setHeader('Cache-Control', 'no-store');
+        const token = request.headers[COMPANION_ARTIFACT_ACCESS_TOKEN_HEADER];
+        const remote = request.socket.remoteAddress;
+        if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(token) ||
+            !node_crypto.timingSafeEqual(Buffer.from(token), Buffer.from(companionArtifactAccessToken)) ||
+            !['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(remote ?? '') ||
+            !/^(127\.0\.0\.1|\[::1\]):\d{1,5}$/.test(request.headers.host ?? '')) {
+            response.writeHead(403).end();
+            return true;
+        }
+        if (request.method !== 'GET') {
+            response.writeHead(405, { Allow: 'GET' }).end();
+            return true;
+        }
+        try {
+            const issued = await tokenSession?.getTicket(currentCompanionManifestSha256);
+            if (!issued)
+                response.writeHead(503).end();
+            else
+                response.writeHead(200, { 'Content-Type': 'application/json', 'X-Content-Type-Options': 'nosniff' }).end(JSON.stringify(createLaunchSnapshot({
+                    ...readLaunchSource(), localDevLaunchToken: issued.token, expiresAt: issued.expiresAt,
+                }, new URL(`http://${request.headers.host}`))));
+        }
+        catch (error) {
+            const status = error instanceof index.CliError && (error.httpStatus === 401 || error.httpStatus === 403) ? error.httpStatus : 503;
+            logger.debug(`本地开发会话续票失败：${index.readRedactedErrorMessage(error, { verbose: true })}`);
+            response.writeHead(status).end();
+        }
+        return true;
     });
+    const vite = await runDevStartupTask(logger, '正在加载项目 Vite', () => projectVite.loadProjectVite(projectRoot), '已加载项目 Vite');
+    const appServer = await runDevStartupTask(logger, '正在创建 Vite 开发服务器', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withCompanionArtifactAccessTokenEnv(companionArtifactAccessToken, () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions, launchPlugin)), runtime.env), runtime.env), runtime.env), '已创建 Vite 开发服务器');
     await runDevStartupTask(logger, '正在启动 Vite 开发服务器', () => appServer.listen(appPort), 'Vite 开发服务器已启动');
     const appUrl = await runDevStartupTask(logger, '正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl), '已确定小程序入口');
     const buildLanAddresses = () => createLanAddressCandidates({
@@ -15060,12 +15169,27 @@ async function runDevCommand(options, runtime = {}) {
     }
     closers.push(() => browserDevHost.close());
     if (devLaunchContext.source === 'remote' && devLaunchContext.miniProgramId) {
-        const tokenSession = startLocalDevLaunchTokenSession({
+        tokenSession = startLocalDevLaunchTokenSession({
             env: runtime.env,
             fetchImpl,
             logger,
+            manifestUrl: new URL(COMPANION_DEV_MANIFEST_PATH, appUrl).toString(),
+            companionArtifactAccessToken,
+            companionApproved: hasCompanionApproval(devLaunchContext.runtimePermissions),
             miniProgramId: devLaunchContext.miniProgramId,
-            onToken: (localDevLaunchToken) => {
+            refreshPermissions: async () => {
+                const refreshed = await loadDevLaunchContext({ env: runtime.env, fetchImpl, logger, projectRoot,
+                    timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS });
+                if (refreshed.context.miniProgramId !== devLaunchContext.miniProgramId)
+                    throw new Error('项目绑定已变更，请重新启动调试');
+                devLaunchContext.runtimePermissions = refreshed.context.runtimePermissions;
+                launchRuntimePermissions = context.createBrowserDevRuntimePermissions(devLaunchContext.runtimePermissions, context.createBrowserDevPermissionState(devLaunchContext));
+                browserDevHost.updateBootstrap({ devContext: { ...devLaunchContext, localDevLaunchToken: currentLocalDevLaunchToken } });
+                return hasCompanionApproval(devLaunchContext.runtimePermissions);
+            },
+            onToken: (localDevLaunchToken, companionManifestSha256, expiresAt) => {
+                currentExpiresAt = expiresAt;
+                currentCompanionManifestSha256 = companionManifestSha256;
                 currentLocalDevLaunchToken = localDevLaunchToken;
                 const tokenContext = {
                     source: 'remote',
@@ -15078,15 +15202,26 @@ async function runDevCommand(options, runtime = {}) {
                     lanAddresses: buildLanAddresses(),
                 });
             },
+            onReadiness: devReadiness => browserDevHost.updateBootstrap({ devReadiness }),
             projectRoot,
             timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
         });
         closers.push(tokenSession.close);
     }
-    logger.success('本地调试已启动');
+    else {
+        const reason = '登录或小程序绑定不可用，请完成 CLI 登录和项目绑定';
+        browserDevHost.updateBootstrap({
+            devReadiness: {
+                browser: { state: 'ready' },
+                mobile: { state: 'blocked', reason },
+                companion: { state: 'blocked', reason },
+            },
+        });
+    }
+    logger.success('Web / Browser Fake 调试已就绪');
     logger.info(`调试页：${browserDevHost.url}`);
     logger.info(`小程序地址：${appUrl}`);
-    logger.info('手机调试：请在调试页扫码');
+    logger.info('手机与 PC Companion 的就绪状态请查看调试页');
     if (options.open !== false) {
         logger.debug('正在打开浏览器调试页');
         void openUrl(browserDevHost.url);
@@ -15166,10 +15301,26 @@ async function loadRemoteDevContextWithTimeout(options) {
         }
     }
 }
-function createViteServerOptions(projectRoot, options) {
+function createMiniProgramDevLaunchVitePlugin(getSnapshot, handleSession) {
+    return {
+        name: 'heybox-mini-program-dev-launch',
+        enforce: 'pre',
+        configureServer(server) {
+            server.middlewares.use(async (request, response, next) => {
+                if (handleSession && await handleSession(request, response))
+                    return;
+                if (!tryHandleMiniProgramDevLaunchRequest(request, response, getSnapshot))
+                    next();
+            });
+        },
+    };
+}
+function createViteServerOptions(projectRoot, options, launchPlugin) {
     const configFile = resolveProjectViteConfig(projectRoot);
     const server = {
-        cors: true,
+        // launch.json 由 mini-program-dev-launch plugin 自己处理 PNA/CORS 预检；
+        // Vite 通用 CORS 会抢先返回 `*`，缺少 Access-Control-Allow-Private-Network。
+        cors: false,
         hmr: {
             clientPort: options.port ?? DEFAULT_APP_PORT,
         },
@@ -15181,11 +15332,13 @@ function createViteServerOptions(projectRoot, options) {
         return {
             configFile,
             logLevel: VITE_LOG_LEVEL,
+            plugins: [launchPlugin],
             server,
         };
     }
     return {
         logLevel: VITE_LOG_LEVEL,
+        plugins: [launchPlugin],
         root: projectRoot,
         server,
     };
@@ -15299,6 +15452,19 @@ async function withManagedDevOutputEnv(action, env = process.env) {
         }
     }
 }
+async function withCompanionArtifactAccessTokenEnv(token, action, env = process.env) {
+    const previous = env[COMPANION_ARTIFACT_ACCESS_TOKEN_ENV];
+    env[COMPANION_ARTIFACT_ACCESS_TOKEN_ENV] = token;
+    try {
+        return await action();
+    }
+    finally {
+        if (previous === undefined)
+            delete env[COMPANION_ARTIFACT_ACCESS_TOKEN_ENV];
+        else
+            env[COMPANION_ARTIFACT_ACCESS_TOKEN_ENV] = previous;
+    }
+}
 function installShutdownHandlers(closers, processLike) {
     const shutdown = async () => {
         await closeAll(closers);
@@ -15319,28 +15485,94 @@ function startLocalDevLaunchTokenSession(options) {
     let expirationTimer;
     let hasReportedTokenFailure = false;
     let refreshTimer;
+    let companionApproved = options.companionApproved;
+    let permissionsRefreshAt = Date.now() + 30_000;
+    let publishedToken;
+    let publishedDigest;
+    let ticket;
+    let pending;
+    const getTicket = async (companionManifestSha256) => {
+        if (closed)
+            return undefined;
+        if (ticket && (companionManifestSha256 === undefined || ticket.companionManifestSha256 === companionManifestSha256) && ticket.refreshAt > Date.now())
+            return ticket;
+        return issueTicket(companionManifestSha256);
+    };
+    const issueTicket = (companionManifestSha256) => {
+        if (pending && pending.digest === companionManifestSha256)
+            return pending.promise;
+        const promise = issueLocalDevLaunchToken({
+            ...options,
+            ...(companionManifestSha256 ? { companionManifestSha256 } : {}),
+        })
+            .then(issued => {
+            ticket = issued;
+            return issued;
+        }).finally(() => { if (pending?.promise === promise)
+            pending = undefined; });
+        pending = { digest: companionManifestSha256, promise };
+        return promise;
+    };
     const refresh = async () => {
         try {
-            const issued = await issueLocalDevLaunchToken(options);
+            if (options.refreshPermissions && Date.now() >= permissionsRefreshAt) {
+                companionApproved = await options.refreshPermissions();
+                permissionsRefreshAt = Date.now() + 30_000;
+            }
+            let manifest;
+            let snapshotError;
+            try {
+                manifest = await loadRemoteDevContextWithTimeout({
+                    fetchImpl: options.fetchImpl,
+                    timeoutMs: options.timeoutMs,
+                    load: fetchImpl => readCompanionManifest(options.manifestUrl, options.companionArtifactAccessToken, fetchImpl),
+                });
+            }
+            catch (error) {
+                snapshotError = error;
+            }
+            const digest = manifest?.digest;
+            const issued = await getTicket(digest);
+            if (!issued)
+                return;
             if (closed)
                 return;
-            options.onToken(issued.token);
+            if (publishedToken !== issued.token || publishedDigest !== digest) {
+                publishedToken = issued.token;
+                publishedDigest = digest;
+                options.onToken(issued.token, digest, issued.expiresAt);
+            }
+            options.onReadiness({
+                browser: { state: 'ready' },
+                mobile: { state: 'ready' },
+                companion: snapshotError
+                    ? { state: snapshotError instanceof Error && snapshotError.message.includes('artifact-updating') ? 'pending' : 'blocked', reason: safeCompanionFailureReason(snapshotError) }
+                    : manifest?.artifacts.length
+                        ? companionApproved
+                            ? { state: 'ready', digest, artifacts: manifest.artifacts, reason: '本地产物和启动票已就绪，PC 授权将在打开后验证' }
+                            : { state: 'blocked', reason: 'Companion 未获 COA 批准或本地权限声明未开启' }
+                        : { state: 'not-configured', reason: '未配置本地 Companion 产物' },
+            });
+            if (snapshotError)
+                options.logger.debug(`PC Companion 快照校验失败：${index.readRedactedErrorMessage(snapshotError, { verbose: true })}`);
             const ttl = Math.max(0, issued.expiresAt - Date.now());
             scheduleExpiration(ttl);
-            schedule(Math.max(1_000, Math.floor(ttl * 0.8)));
+            schedule(Math.min(2_000, Math.max(1_000, Math.floor(ttl * 0.8))));
             if (hasReportedTokenFailure) {
                 hasReportedTokenFailure = false;
-                options.logger.success('手机扫码调试已恢复');
+                options.logger.success('本地调试凭证已恢复');
             }
         }
         catch (error) {
             if (closed)
                 return;
             if (!hasReportedTokenFailure) {
-                options.logger.warn('手机扫码调试凭证获取失败，将自动重试');
+                options.logger.warn('本地调试凭证获取失败，将自动重试；Web / Browser Fake 仍可使用');
             }
             hasReportedTokenFailure = true;
-            options.logger.debug(`手机扫码调试凭证获取失败，详细原因：${index.readRedactedErrorMessage(error, { verbose: true })}`);
+            options.onReadiness({ browser: { state: 'ready' }, mobile: { state: 'blocked', reason: '调试凭证暂不可用' },
+                companion: { state: 'blocked', reason: safeCompanionFailureReason(error) } });
+            options.logger.debug(`本地调试凭证获取失败，详细原因：${index.readRedactedErrorMessage(error, { verbose: true })}`);
             schedule(options.timeoutMs);
         }
     };
@@ -15354,13 +15586,20 @@ function startLocalDevLaunchTokenSession(options) {
         if (expirationTimer)
             clearTimeout(expirationTimer);
         expirationTimer = setTimeout(() => {
-            if (!closed)
-                options.onToken(undefined);
+            if (!closed) {
+                options.onToken(undefined, undefined);
+                publishedToken = undefined;
+                options.onReadiness({ browser: { state: 'ready' }, mobile: { state: 'blocked', reason: '调试凭证已过期' },
+                    companion: { state: 'blocked', reason: '调试凭证已过期' } });
+            }
         }, Math.max(1, ttl));
         expirationTimer.unref?.();
     };
-    void refresh();
+    options.onReadiness({ browser: { state: 'ready' }, mobile: { state: 'pending' }, companion: { state: 'pending' } });
+    const ready = refresh();
     return {
+        getTicket,
+        ready,
         close: () => {
             closed = true;
             if (expirationTimer)
@@ -15374,22 +15613,128 @@ async function issueLocalDevLaunchToken(options) {
     const issued = await loadRemoteDevContextWithTimeout({
         fetchImpl: options.fetchImpl,
         timeoutMs: options.timeoutMs,
-        load: (fetchImpl) => context.createLocalDevLaunchToken({
-            cwd: options.projectRoot,
-            env: options.env,
-            fetchImpl,
-            miniProgramId: options.miniProgramId,
-        }),
+        load: async (fetchImpl) => {
+            const result = await context.createLocalDevLaunchToken({
+                cwd: options.projectRoot,
+                env: options.env,
+                fetchImpl,
+                miniProgramId: options.miniProgramId,
+                ...(options.companionManifestSha256
+                    ? { companionManifestSha256: options.companionManifestSha256 }
+                    : {}),
+            });
+            return { result };
+        },
     });
-    const token = typeof issued.token === 'string' ? issued.token.trim() : '';
+    const token = typeof issued.result.token === 'string' ? issued.result.token.trim() : '';
     if (!token) {
         throw new Error('响应缺少 token');
     }
-    const expiresAt = normalizeExpiresAt(issued.expires_at);
+    const expiresAt = normalizeExpiresAt(issued.result.expires_at);
     if (!expiresAt || expiresAt <= Date.now()) {
         throw new Error('响应缺少有效 expires_at');
     }
-    return { expiresAt, token };
+    return { ...(options.companionManifestSha256 ? { companionManifestSha256: options.companionManifestSha256 } : {}), expiresAt, token,
+        refreshAt: Date.now() + Math.max(1, (expiresAt - Date.now()) * 0.8) };
+}
+function safeCompanionFailureReason(error) {
+    const message = index.readRedactedErrorMessage(error, { verbose: true });
+    if (/artifact-updating/.test(message))
+        return '本地 Companion 产物准备中';
+    if (/artifact-missing/.test(message))
+        return '本地 Companion 产物目录不存在，请先构建产物';
+    if (/snapshot-limit/.test(message))
+        return '本地快照数量或大小已达上限，请结束会话后重启 dev';
+    if (/invalid-manifest/.test(message))
+        return '本地 Manifest 或权限配置无效';
+    if (/invalid-artifact/.test(message))
+        return '本地产物或原生入口校验失败';
+    if (/404|not found/i.test(message))
+        return '调试接口尚未部署或当前登录环境不匹配';
+    if (/403|forbidden|permission|授权|权限/i.test(message))
+        return 'Companion 授权未通过，请检查 COA 批准与开发者身份';
+    if (/401|登录/i.test(message))
+        return 'CLI 登录态已失效，请重新登录';
+    if (/manifest|快照|ZIP|ENOENT/i.test(message))
+        return '本地 Companion ZIP 或 Manifest 校验失败，请检查产物与配置';
+    return 'PC Companion 暂不可用，请检查网络、登录环境和调试接口';
+}
+function hasCompanionApproval(value) {
+    if (!value || typeof value !== 'object' || !('entries' in value) || !Array.isArray(value.entries))
+        return false;
+    return value.entries.some(entry => entry?.key === 'companion' && entry?.status === 'enabled');
+}
+async function readCompanionManifest(manifestUrl, companionArtifactAccessToken, fetchImpl) {
+    try {
+        const response = await fetchImpl(manifestUrl, {
+            cache: 'no-store',
+            credentials: 'omit',
+            headers: {
+                accept: 'application/json',
+                [COMPANION_ARTIFACT_ACCESS_TOKEN_HEADER]: companionArtifactAccessToken,
+            },
+            method: 'GET',
+            redirect: 'error',
+            referrerPolicy: 'no-referrer',
+        });
+        if (response.status === 404) {
+            return undefined;
+        }
+        if (!response.ok) {
+            const code = response.headers.get('x-hb-sdk-companion-error');
+            const safeCode = ['artifact-updating', 'artifact-missing', 'snapshot-limit', 'invalid-manifest', 'invalid-artifact'].includes(code ?? '') ? code : '';
+            throw new Error(`Companion manifest request failed with status ${response.status} ${safeCode}`);
+        }
+        if (!response.headers.get('content-type')?.toLowerCase().includes('application/json')) {
+            throw new Error('Companion manifest response is not JSON');
+        }
+        const contentLength = Number(response.headers.get('content-length'));
+        if (Number.isFinite(contentLength) && contentLength > COMPANION_DEV_MANIFEST_MAX_BYTES) {
+            throw new Error('Companion manifest response is too large');
+        }
+        const bytes = await readBoundedCompanionManifestBytes(response, COMPANION_DEV_MANIFEST_MAX_BYTES);
+        const value = JSON.parse(bytes.toString('utf8'));
+        const artifacts = Object.entries(value.companions ?? {}).flatMap(([alias, definition]) => {
+            if (!/^[a-z][a-z0-9-]{0,31}$/.test(alias) || !definition || typeof definition !== 'object') {
+                throw new Error('Companion invalid-manifest');
+            }
+            return Object.keys(definition.targets ?? {}).map(target => {
+                if (target !== 'windows-x64' && target !== 'macos-arm64')
+                    throw new Error('Companion invalid-manifest');
+                return { alias, target };
+            });
+        });
+        return { digest: node_crypto.createHash('sha256').update(bytes).digest('hex'), artifacts };
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw error;
+        throw new Error('Companion manifest request failed');
+    }
+}
+async function readBoundedCompanionManifestBytes(response, maxBytes) {
+    if (!response.body)
+        return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel('Companion manifest response is too large');
+                throw new Error('Companion manifest response is too large');
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks.map(chunk => Buffer.from(chunk)), total);
 }
 function normalizeExpiresAt(value) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
@@ -15502,8 +15847,10 @@ function isPrivateIPv4(address) {
 
 var dev = /*#__PURE__*/Object.freeze({
 	__proto__: null,
+	createMiniProgramDevLaunchVitePlugin: createMiniProgramDevLaunchVitePlugin,
 	normalizeExpiresAt: normalizeExpiresAt,
-	runDevCommand: runDevCommand
+	runDevCommand: runDevCommand,
+	startLocalDevLaunchTokenSession: startLocalDevLaunchTokenSession
 });
 
 exports.RuntimeError = RuntimeError;