@heybox/hb-sdk 0.9.2-alpha.6 → 0.9.2-alpha.8

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 0.9.2-alpha.8 - 2026-10-20
+
+### 新增能力
+
+- 新增 `hb-sdk remote games search "游戏名" --json`，查询平台游戏 appid、中英文名称和分页结果，无需先绑定小程序项目。
+- CLI 游戏搜索增加请求频率保护，操作过于频繁时提示稍后重试。
+
+### 行为调整
+
+- 开发启动、构建和部署时，对简介缺失、工具类未关联游戏给出非阻断提醒；部署不重复输出内部构建的资料提示。
+- Agent Skill 主动检查小程序分类、简介和游戏绑定，保留已有内容，通用工具可保持不关联游戏。
+
+### 问题修复
+
+- 修复 Vite 5/6 开发服务在输出资料或旧模板平台提醒时无法启动的问题。
+
+## 0.9.2-alpha.7 - 2026-10-20
+
+### 行为调整
+
+- `hb-sdk dev` 启动前要求 CLI 已登录、项目已绑定小程序且远端配置校验通过；失败时提供修复指引并退出，不再自动进入匿名 Browser Mock。临时网络异常和短期限流仅重试一次，启动后的签票失败或临时断网仍保留浏览器调试服务。
+
 ## 0.9.2-alpha.6
 
 ### 新增能力

package/README.md

@@ -26,7 +26,7 @@ npm run dev
 
 脚手架已包含 SDK、Vite 配置和常用开发命令。浏览器调试通过后，再从调试台的二维码入口使用手机小黑盒 APP 验收。
 
-手机二维码的短链先打开普通中间页，再进入专用 dev-shell。最终 `openWindow` 协议会把 CLI 校验后的用户小程序字符串 ID（UUID）写入根字段 `user_miniprogram_id`；原生不会从 URL 查询参数补读，也不能用传统小程序数字 ID 代替。匿名调试不生成小程序 ID，原生未开放的横屏能力仍返回 `supported: false`。入口排查与验证记录见 [Android 396 入口审计](./docs/android-396-launch-identity.md)。
+手机二维码的短链先打开普通中间页，再进入专用 dev-shell。最终 `openWindow` 协议会把 CLI 校验后的用户小程序字符串 ID（UUID）写入根字段 `user_miniprogram_id`；原生不会从 URL 查询参数补读，也不能用传统小程序数字 ID 代替。原生未开放的横屏能力仍返回 `supported: false`。入口排查与验证记录见 [Android 396 入口审计](./docs/android-396-launch-identity.md)。
 
 创建命令使用 `@latest`，实际安装版本以 npm 的 `latest` 为准。
 
@@ -124,6 +124,8 @@ async function revokeAuthorizationFromUserAction() {
 
 小程序类别需在 `package.json#heybox.category` 声明为 `tool`、`game` 或 `other`，构建后写入 Manifest，CLI/Open 提审自动采用，发布后生效。开发者提审页不展示或提供手动选择类别；新上传版本（含已有小程序更新）必须声明，缺少类别的项目须补配置后重新构建上传，详见 [小程序类别](https://docs.xiaoheihe.cn/hb_sdk/guide/cli#小程序类别)。
 
+使用 `hb-sdk remote games search "游戏名" --json` 查询平台游戏候选，无需先绑定项目；核对后将返回的字符串 `appid` 填入 `heybox.bindAppIds`，能否绑定以部署预检为准。简介缺失、工具类未关联游戏时，开发启动、构建和部署会给出非阻断提醒；具体流程见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)。
+
 `bindAppIds` 只接受规范十进制字符串（形如 `/^[1-9]\d*$/`，拒绝前导零、空串与非数字），每项必须是正 int32（最大 `2147483647`），数组内不允许重复，最多 20 项，并按数值升序写入 Manifest。它不是权限，构建不联网；游戏真实性在远端预检和提审时校验。字段缺失或 `[]` 都表示清空绑定。PC 展示仍受 `platforms` 过滤。
 
 再启用构建插件：
@@ -498,7 +500,7 @@ CLI 会复用已验证产物、跳过该 ZIP 的网络上传；Web 文件及发
 
 右上角的桌面图标与二维码按钮使用相同样式。桌面图标只在该项目于 `package.json#heybox.platforms` 声明了桌面平台（`windows`、`macos` 或 `linux`）时展示，未声明桌面平台的项目不显示该入口。点击桌面图标后选择小黑盒正式版或 Debug 版，选择会立即请求客户端打开当前本地页面并在本地记忆，不需要二次确认。桌面端只接受无凭据的 `http://127.0.0.1:<port>`，拒绝 `localhost`、IPv6 和 LAN 地址，不提供地址选择或手工 URL；手机二维码继续独立选择局域网地址。入口在项目已绑定且本地调试启动票有效时可用，统一 URI 只携带 `mini_program_id` 和 `mini_url`，启动票继续由 detail 从同源 `launch.json` 发现并交给后端验证。浏览器无法确认客户端是否真正打开，因此调试台只记录“已请求打开”，不会自动切换正式版或 Debug 版。
 
-`hb-sdk dev` 在未登录、未绑定或远端不可用时仍启动 Browser Mock；真实手机/PC 入口须有有效启动票。CLI 自动从本地声明生成普通 `network` / `companion` 的临时批准缺口，不提供第二套权限开关。调试台顶部的“查看全部权限申请”在新标签页打开当前小程序的权限列表；尚未获批的 Network、Companion 单项提供“去申请”，直接打开对应申请表单。未获取到小程序 ID 时先选择小程序，再进入对应权限；已获批或审核中的权限不重复打开申请表单。真实 Host 每次打开会话确认临时权限，拒绝后仍可按线上批准基线打开；官方域名始终只认声明与线上批准的交集。手机真机 Dev Session 仅将目标 hostname 为 `localhost` 或 `127.0.0.*` 的公开 `network.request()` 交给开发机 HTTP 代理转发，因此这些地址指向开发机；其它域名、LAN 地址和其它 IP 使用设备自身网络；代理不管理独立租约，不判断黑盒域名或改写应用层凭据。正式版本和 Runtime 私有请求仍走 Host 网络。CLI 连续失联约 30 秒、期限或快照变化会销毁旧 Runtime，并清理临时 Companion 进程树；恢复后重新确认。手机验收统一从右上角二维码进入并选择可达的局域网网卡。调试会话、权限刷新与完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
+`hb-sdk dev` 启动前要求 CLI 已登录、项目已绑定小程序，并成功校验远端配置；未满足时直接退出，不启动服务或打开浏览器。网络或服务临时异常等待 1 秒后重试一次；限流仅在服务端给出的等待窗口不超过 30 秒时重试一次，仍失败则退出并保留绑定。启动后，真实手机/PC 入口须有有效启动票，签票失败不阻断 Browser Mock，运行中的临时网络故障也不关闭浏览器服务。CLI 自动从本地声明生成普通 `network` / `companion` 的临时批准缺口，不提供第二套权限开关。调试台顶部的“查看全部权限申请”在新标签页打开当前小程序的权限列表；尚未获批的 Network、Companion 单项提供“去申请”，直接打开对应申请表单。未获取到小程序 ID 时先选择小程序，再进入对应权限；已获批或审核中的权限不重复打开申请表单。真实 Host 每次打开会话确认临时权限，拒绝后仍可按线上批准基线打开；官方域名始终只认声明与线上批准的交集。手机真机 Dev Session 仅将目标 hostname 为 `localhost` 或 `127.0.0.*` 的公开 `network.request()` 交给开发机 HTTP 代理转发，因此这些地址指向开发机；其它域名、LAN 地址和其它 IP 使用设备自身网络；代理不管理独立租约，不判断黑盒域名或改写应用层凭据。正式版本和 Runtime 私有请求仍走 Host 网络。CLI 连续失联约 30 秒、期限或快照变化会销毁旧 Runtime，并清理临时 Companion 进程树；恢复后重新确认。手机验收统一从右上角二维码进入并选择可达的局域网网卡。调试会话、权限刷新与完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
 
 开发上下文按需读取并默认缓存 30 秒；重新打开真机会话时，过期缓存会刷新。权限刷新遇到临时故障或限流会按退避自动重试，恢复前暂停签发新启动票。真机按确认后的有效网络权限选择身份模式；身份上下文读取失败会提示重试，不会静默切换旧身份模式。
 

package/dist/cli-chunks/{build-ffQNXsFk.cjs → build-BinntZJf.cjs}

@@ -1,14 +1,14 @@
 'use strict';
 
-var runtimeGate = require('./runtime-gate-BcKHky95.cjs');
+var runtimeGate = require('./runtime-gate-g3afiufR.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-BQ7lPfhg.cjs');
-var index = require('./index-CN_l895H.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CDx5qO-T.cjs');
+var index = require('./index-CY67PpQk.cjs');
 require('node:crypto');
 require('node:zlib');
-var projectVite = require('./project-vite-CNubrzp5.cjs');
+var projectVite = require('./project-vite-Dm128JTE.cjs');
 require('node:module');
 require('node:url');
 require('./_commonjs-dynamic-modules-DUamuDzp.cjs');
@@ -16,7 +16,7 @@ require('fs');
 require('path');
 require('os');
 require('inspector');
-require('./version-ai8lcNbJ.cjs');
+require('./version-D40WHkF9.cjs');
 require('node:async_hooks');
 require('readline');
 require('tty');

package/dist/cli-chunks/{context-DlFt5Q7p.cjs → context-BI3QMxw2.cjs}

@@ -3,10 +3,10 @@
 var node_crypto = require('node:crypto');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-BQ7lPfhg.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CDx5qO-T.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var index = require('./index-CN_l895H.cjs');
+var index = require('./index-CY67PpQk.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);

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

package/dist/cli-chunks/deploy-lock-pKDDxTKm.cjs

@@ -0,0 +1,148 @@
+'use strict';
+
+var node_crypto = require('node:crypto');
+var fs = require('node:fs/promises');
+var path = require('node:path');
+var index = require('./index-CY67PpQk.cjs');
+
+const DEPLOY_LOCKED_MESSAGE = '当前设备已有同版本产物正在上传，请等待完成后重试';
+const DEPLOY_LOCK_DIRECTORY_NAME = 'deploy-locks';
+const DEPLOY_LOCK_OWNER_FILE = 'owner.json';
+const INCOMPLETE_LOCK_GRACE_MS = 30_000;
+const defaultPaths = index.envPaths('hb-sdk', { suffix: '' });
+class DeployLockConflictError extends Error {
+}
+async function withDeployLock(scope, operation, options = {}) {
+    let lock;
+    try {
+        lock = await acquireDeployLock(scope, options);
+    }
+    catch (error) {
+        if (error instanceof DeployLockConflictError) {
+            throw error;
+        }
+        // 本地文件锁只减少重复操作，文件系统异常不阻断服务端上传流程。
+        return operation();
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        await lock.release().catch(() => undefined);
+    }
+}
+async function acquireDeployLock(scope, options = {}) {
+    const lockDirectory = getDeployLockDirectory(scope, options.cacheRoot);
+    const ownerFile = path.join(lockDirectory, DEPLOY_LOCK_OWNER_FILE);
+    const owner = {
+        version: 1,
+        pid: options.pid ?? process.pid,
+        token: options.token ?? node_crypto.randomBytes(16).toString('hex'),
+    };
+    await fs.mkdir(path.dirname(lockDirectory), { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        let created = false;
+        try {
+            await fs.mkdir(lockDirectory, { mode: 0o700 });
+            created = true;
+            await fs.writeFile(ownerFile, `${JSON.stringify(owner)}\n`, { encoding: 'utf8', mode: 0o600 });
+            return createDeployLock(lockDirectory, ownerFile, owner.token);
+        }
+        catch (error) {
+            if (created) {
+                await fs.rm(lockDirectory, { force: true, recursive: true });
+                throw error;
+            }
+            if (!isNodeError(error) || error.code !== 'EEXIST') {
+                throw error;
+            }
+            if (!(await canReclaimDeployLock(lockDirectory, ownerFile, options))) {
+                throw new DeployLockConflictError(DEPLOY_LOCKED_MESSAGE);
+            }
+            await reclaimDeployLock(lockDirectory, owner.token);
+        }
+    }
+    throw new DeployLockConflictError(DEPLOY_LOCKED_MESSAGE);
+}
+function getDeployLockDirectory(scope, cacheRoot = defaultPaths.cache) {
+    const scopeHash = node_crypto.createHash('sha256').update(`${scope.apiBaseUrl}\0${scope.miniProgramId}\0${scope.version}`).digest('hex');
+    return path.join(cacheRoot, DEPLOY_LOCK_DIRECTORY_NAME, scopeHash);
+}
+function createDeployLock(lockDirectory, ownerFile, token) {
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            await removeOwnedLock(lockDirectory, ownerFile, token);
+        },
+    };
+}
+async function canReclaimDeployLock(lockDirectory, ownerFile, options) {
+    const owner = await readDeployLockOwner(ownerFile);
+    if (owner) {
+        return !(options.isProcessRunning ?? isProcessRunning)(owner.pid);
+    }
+    try {
+        const lockStat = await fs.stat(lockDirectory);
+        return (options.now ?? Date.now)() - lockStat.mtimeMs >= INCOMPLETE_LOCK_GRACE_MS;
+    }
+    catch (error) {
+        return isNodeError(error) && error.code === 'ENOENT';
+    }
+}
+async function removeOwnedLock(lockDirectory, ownerFile, token) {
+    const owner = await readDeployLockOwner(ownerFile);
+    if (owner?.token === token) {
+        await fs.rm(lockDirectory, { force: true, recursive: true });
+    }
+}
+async function reclaimDeployLock(lockDirectory, token) {
+    const reclaimDirectory = `${lockDirectory}.reclaim-${node_crypto.createHash('sha256').update(token).digest('hex')}`;
+    try {
+        await fs.rename(lockDirectory, reclaimDirectory);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    await fs.rm(reclaimDirectory, { force: true, recursive: true });
+}
+async function readDeployLockOwner(ownerFile) {
+    try {
+        const value = JSON.parse(await fs.readFile(ownerFile, 'utf8'));
+        return isDeployLockOwner(value) ? value : null;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return null;
+        if (error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+function isDeployLockOwner(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.version === 1 &&
+        Number.isInteger(value.pid) &&
+        typeof value.token === 'string');
+}
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !isNodeError(error) || error.code !== 'ESRCH';
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+
+exports.DEPLOY_LOCKED_MESSAGE = DEPLOY_LOCKED_MESSAGE;
+exports.acquireDeployLock = acquireDeployLock;
+exports.withDeployLock = withDeployLock;

package/dist/cli-chunks/{dev-CNDIlDmL.cjs → dev-DeNzUY6g.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
-var index = require('./index-CN_l895H.cjs');
-var context = require('./context-DlFt5Q7p.cjs');
+var index = require('./index-CY67PpQk.cjs');
+var context = require('./context-BI3QMxw2.cjs');
 var node_crypto = require('node:crypto');
 var fs = require('node:fs');
-var runtimePermissionEnv = require('./runtime-permission-env-BQ7lPfhg.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CDx5qO-T.cjs');
 var os = require('node:os');
 var path = require('node:path');
 var net = require('node:net');
@@ -16,8 +16,8 @@ var fs$1 = require('node:fs/promises');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-CNubrzp5.cjs');
-var version = require('./version-ai8lcNbJ.cjs');
+var projectVite = require('./project-vite-Dm128JTE.cjs');
+var version = require('./version-D40WHkF9.cjs');
 require('node:zlib');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -1995,8 +1995,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-CNDIlDmL.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-CNDIlDmL.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-DeNzUY6g.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-DeNzUY6g.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'),
@@ -11100,7 +11100,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-mmJekGrr.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-DQdwzMhB.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -15584,21 +15584,6 @@ async function runDevCommand(options, runtime = {}) {
     const logger = runtime.logger ?? index.createCliLogger();
     const fetchImpl = runtime.fetchImpl ?? fetch;
     const openUrl = runtime.openExternalUrl ?? browser.openExternalUrl;
-    const networkInterfaceSnapshot = (runtime.networkInterfaces ?? os.networkInterfaces)();
-    const getPortImpl = runtime.getPort ?? getPorts;
-    const requestedAppPort = options.port ?? DEFAULT_APP_PORT;
-    const appPort = await selectAvailableVitePort({
-        getPort: getPortImpl,
-        isPortListening: runtime.isTcpPortListening ?? isTcpPortListening,
-        startPort: requestedAppPort,
-    });
-    if (appPort !== requestedAppPort)
-        logger.warn(`端口 ${requestedAppPort} 已被占用，已自动切换到 ${appPort}`);
-    const resolvedOptions = {
-        ...options,
-        hmrHost: createLanInterfaceCandidates(networkInterfaceSnapshot)[0]?.address,
-        port: appPort,
-    };
     const projectRoot = projectVite.findProjectRoot(runtime.cwd ?? process.cwd());
     const workspaceCardsDeclared = runtimePermissionEnv.readMiniappWorkspaceCardsFromPackageJson(projectRoot).declaration !== undefined;
     const companionArtifactAccessToken = (runtime.randomBytes ?? node_crypto.randomBytes)(32).toString('base64url');
@@ -15608,7 +15593,8 @@ async function runDevCommand(options, runtime = {}) {
     const miniProgramPlatforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
     // A1：Dev Context 结果缓存。启动读取、设备会话读取和权限刷新共用同一份结果，
     // 手机端重连不再 1:1 产生远端 `detail` 请求；限流时按网关建议时长延长压制。
-    const defaultSleep = (ms) => new Promise(resolve => { setTimeout(resolve, ms).unref?.(); });
+    // 启动等待期间尚无监听服务，定时器必须保持进程存活。
+    const defaultSleep = (ms) => new Promise(resolve => { setTimeout(resolve, ms); });
     const devContextCache = createDevContextCache({
         load: () => loadDevLaunchContext({
             env: runtime.env,
@@ -15632,9 +15618,9 @@ async function runDevCommand(options, runtime = {}) {
         const key = `${projectRoot}\0${boundMiniProgramId ?? ''}`;
         return devContextCache.read(key);
     };
-    let { context: devLaunchContext, miniProgram } = await readDevLaunchContext();
+    let startup = await readDevLaunchContext();
     let lastRateLimitHint = '';
-    // A3：提示只在内容变化时输出一次，避免手机端反复重连刷屏。
+    // 提示只在内容变化时输出一次，避免手机端反复重连刷屏。
     const reportRateLimitOnce = (state) => {
         const hint = index.formatCliRateLimitHint(state);
         if (hint === lastRateLimitHint)
@@ -15642,29 +15628,40 @@ async function runDevCommand(options, runtime = {}) {
         lastRateLimitHint = hint;
         reportDevContextRateLimit(logger, state, runtime.env);
     };
-    if (devLaunchContext.rateLimit?.limited)
-        reportRateLimitOnce(devLaunchContext.rateLimit);
-    // 启动即被限流时 `miniProgramId` 缺失，后面不会创建 token session，也就没有任何刷新路径
-    // （三条读取入口都以 `source === 'remote'` 为前提），开发者只能重启 CLI。这里先等网关窗口
-    // 过去再重试一次：窗口短就自动恢复，窗口长（例如封禁 24h）则不再空等，转为按限流原因阻塞
-    // 真机调试，而不是误报「未登录 / 未绑定」。
-    const startupRateLimit = devLaunchContext.rateLimit;
-    if (!devLaunchContext.miniProgramId && startupRateLimit?.limited) {
-        const windowMs = startupRateLimit.retryAfterMs;
-        if (windowMs !== undefined && windowMs <= DEV_CONTEXT_STARTUP_RATE_LIMIT_WAIT_MAX_MS) {
-            logger.warn(`已被网关限流，等待 ${Math.round(windowMs / 1000)} 秒后重试一次…`);
-            await (runtime.sleep ?? defaultSleep)(windowMs);
-            // 限流结果在缓存里最多压制 300s，重试前必须先失效，否则读到的还是同一条。
-            devContextCache.invalidate();
-            const retried = await readDevLaunchContext();
-            if (retried.context.miniProgramId) {
-                devLaunchContext = retried.context;
-                miniProgram = retried.miniProgram;
-                // 已恢复正常：允许后续再次限流时重新提示。
-                lastRateLimitHint = '';
-            }
-        }
-    }
+    const startupRateLimit = startup.context.rateLimit;
+    if (startupRateLimit?.limited)
+        reportRateLimitOnce(startupRateLimit);
+    // 首次启动只对临时错误重试一次；限流必须遵守服务端窗口，不能用普通退避绕过。
+    const retryDelay = startupRateLimit?.limited
+        ? startupRateLimit.retryAfterMs
+        : startup.retryable ? DEFAULT_DEV_CONTEXT_BACKOFF_START_MS : undefined;
+    if (startup.error && retryDelay !== undefined && retryDelay <= DEV_CONTEXT_STARTUP_RATE_LIMIT_WAIT_MAX_MS) {
+        logger.warn(`${startupRateLimit?.limited ? '已被网关限流' : '远端配置暂不可用'}，等待 ${Math.round(retryDelay / 1000)} 秒后重试一次…`);
+        await (runtime.sleep ?? defaultSleep)(retryDelay);
+        devContextCache.invalidate();
+        startup = await readDevLaunchContext();
+    }
+    if (startup.error) {
+        throw new index.CliError(`无法启动调试：${startup.error.message}`, startup.error.verboseMessage, { httpStatus: startup.error.httpStatus });
+    }
+    const { context: devLaunchContext, miniProgram } = startup;
+    lastRateLimitHint = '';
+    // 完成项目身份与配置校验后，才选择端口、创建服务和打开浏览器。
+    const networkInterfaceSnapshot = (runtime.networkInterfaces ?? os.networkInterfaces)();
+    const getPortImpl = runtime.getPort ?? getPorts;
+    const requestedAppPort = options.port ?? DEFAULT_APP_PORT;
+    const appPort = await selectAvailableVitePort({
+        getPort: getPortImpl,
+        isPortListening: runtime.isTcpPortListening ?? isTcpPortListening,
+        startPort: requestedAppPort,
+    });
+    if (appPort !== requestedAppPort)
+        logger.warn(`端口 ${requestedAppPort} 已被占用，已自动切换到 ${appPort}`);
+    const resolvedOptions = {
+        ...options,
+        hmrHost: createLanInterfaceCandidates(networkInterfaceSnapshot)[0]?.address,
+        port: appPort,
+    };
     let currentDevContext = devLaunchContext;
     // 候选输入不对真机公开；签票成功后才替换整份运行上下文。
     let candidateDevContext = devLaunchContext;
@@ -15933,6 +15930,8 @@ async function runDevCommand(options, runtime = {}) {
                 if (refreshed.context.rateLimit?.limited) {
                     throw index.createCliRateLimitedErrorFromState(refreshed.context.rateLimit);
                 }
+                if (refreshed.error)
+                    throw refreshed.error;
                 if (refreshed.context.miniProgramId !== devLaunchContext.miniProgramId)
                     throw new Error('项目绑定已变更，请重新启动调试');
                 if (refreshed.context.source !== 'remote')
@@ -16085,17 +16084,20 @@ function runDevStartupTask(logger, text, action, successText) {
     return logger.task(text, () => action(), { successText });
 }
 async function loadDevLaunchContext(options) {
-    // 声明错误始终阻断；远端不可用只影响真实 Host。
+    // 声明错误始终阻断；远端失败保留结构化原因，启动与运行阶段分别处理。
     const localPermissions = runtimePermissionEnv.readMiniappPermissionsFromPackageJson(options.projectRoot, runtimePermissionEnv.resolveMiniappSdkVersion());
     const platforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(options.projectRoot);
-    const anonymous = (warning) => ({ context: { source: 'anonymous', warning,
+    const unavailable = (message, error = new index.CliError(message), retryable = false) => ({
+        context: { source: 'anonymous', warning: message,
             declaredPermissions: localPermissions.permissions ?? {}, platforms,
-            runtimePermissions: runtimePermissionEnv.composeMiniappRuntimePermissions(localPermissions, undefined).runtimePermissions }, miniProgram: null });
-    if (!(await index.readHeyboxAuthSession({ env: options.env })))
-        return anonymous('尚未登录 CLI，真实手机和 PC 调试不可用');
+            runtimePermissions: runtimePermissionEnv.composeMiniappRuntimePermissions(localPermissions, undefined).runtimePermissions },
+        miniProgram: null, error, retryable,
+    });
     const miniProgramId = await context.readBoundMiniProgramId(options.projectRoot);
     if (!miniProgramId)
-        return anonymous('尚未绑定小程序，真实手机和 PC 调试不可用');
+        return unavailable('当前项目尚未绑定小程序。请先运行 hb-sdk remote create 或 hb-sdk remote bind <mini-program-id>，完成后重新运行 hb-sdk dev。');
+    if (!(await index.readHeyboxAuthSession({ env: options.env })))
+        return unavailable('尚未登录 CLI。请先运行 hb-sdk login，完成后重新运行 hb-sdk dev。');
     let migratingProfile = false;
     try {
         const { detail, miniProgramId: verifiedMiniProgramId } = await runDevStartupTask(options.logger, '正在读取远端小程序权限', () => loadRemoteDevContextWithTimeout({
@@ -16113,7 +16115,7 @@ async function loadDevLaunchContext(options) {
         if (migration.changed)
             options.logger.info('已迁移当前正式发布名称与图片，继续启动开发环境');
         if (!runtimePermissionEnv.parseMiniProgramRuntimePermissions(detail.runtime_permissions).valid)
-            return anonymous('线上权限快照无效，真实手机和 PC 调试不可用');
+            return unavailable('线上权限快照无效，请稍后重试；持续失败时请联系平台支持。');
         const effectivePermissions = runtimePermissionEnv.composeMiniappRuntimePermissions(localPermissions, detail.runtime_permissions, detail.party_type).runtimePermissions;
         return {
             context: {
@@ -16132,18 +16134,25 @@ async function loadDevLaunchContext(options) {
             throw new Error(`版本资料配置失败：${index.readRedactedErrorMessage(error)}。请配置 heybox.name/icon/coverImages 后重试。`, { cause: error });
         if (error instanceof context.MiniProgramProjectBindingError && error.code.startsWith('PACKAGE_JSON_'))
             throw error;
-        // A3：限流要作为结构化状态继续透出；不能和其它错误一样只报「未连接线上上下文」。
         const rateLimitState = index.readCliRateLimitState(error);
         if (rateLimitState) {
-            return {
-                context: {
-                    ...anonymous(index.formatCliRateLimitHint(rateLimitState)).context,
-                    rateLimit: rateLimitState,
-                },
-                miniProgram: null,
-            };
-        }
-        return anonymous('未连接线上上下文，请检查 CLI 登录态、项目绑定和网络');
+            const failure = unavailable(index.formatCliRateLimitHint(rateLimitState));
+            failure.context.rateLimit = rateLimitState;
+            return failure;
+        }
+        const status = error instanceof index.CliError ? error.httpStatus : undefined;
+        const reason = status === 401
+            ? 'CLI 登录态已失效，请运行 hb-sdk login 后重试。'
+            : status === 403 || status === 404
+                ? '无法访问已绑定的小程序，请检查当前账号的管理权限和小程序是否存在，必要时运行 hb-sdk remote bind <mini-program-id> 重新绑定。'
+                : error instanceof context.MiniProgramProjectBindingError
+                    ? `${index.readRedactedErrorMessage(error)}。请运行 hb-sdk remote create 或 hb-sdk remote bind <mini-program-id> 后重试。`
+                    : `读取远端小程序配置失败：${index.readRedactedErrorMessage(error)}。请检查网络或稍后重试，当前项目绑定已保留。`;
+        const retryable = error instanceof TypeError
+            || (error instanceof Error && error.message === 'dev context timeout')
+            || status === 408
+            || (status !== undefined && status >= 500);
+        return unavailable(reason, new index.CliError(reason, undefined, { httpStatus: status }), retryable);
     }
 }
 /**

package/dist/cli-chunks/{doctor-BkFUZH17.cjs → doctor-BOfbKnN2.cjs}

@@ -3,7 +3,7 @@
 var fs = require('node:fs/promises');
 var os = require('node:os');
 var path = require('node:path');
-var index = require('./index-CN_l895H.cjs');
+var index = require('./index-CY67PpQk.cjs');
 require('node:module');
 require('readline');
 require('os');