@heybox/hb-sdk 0.9.2-alpha.7 → 0.9.2-alpha.9

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 0.9.2-alpha.9 - 2026-10-20
+
+### 文档与工具
+
+- 公开 API Reference、指南与包 README 中的 API 可用版本只展示正式版，不再出现 `-alpha` 等预发布标记；尚未发布的 API 标注目标正式版。
+- 修正 5 处「可用版本早于实际可导入版本」的标注：`viewport.setDisplay` 改为 `0.8.3`，`workspaceCards.requestRefresh` / `getLaunchContext` / `onLaunchContextChange` 改为 `0.9.1`，`cloud.storage` 四个方法改为目标正式版 `0.9.2`，`hasMiniappRuntimeGate` 与 `validateMiniappManifestForDeploy` 改为 `0.8.2`。
+- 移除 `./miniapp-publish` 中已无调用方的 `getMiniappUploadKey()` 与 `validateUploadPaths()` 及其类型；其余发布流程内部工具仍然导出，供 CLI 与运营后台复用，不再作为文档承诺的 API 契约。
+
+## 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
 
 ### 行为调整
@@ -1134,4 +1158,5 @@
 
 ## 0.5.6
 
+- 未发布到 npm 的稳定版本候选，不进入公开文档投影。
 - 开始维护公开 Package Changelog。

package/README.md

@@ -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` 过滤。
 
 再启用构建插件：
@@ -292,7 +294,7 @@ const stopDisplay = hbSDK.on('display_change', ({ orientation, fullscreen }) =>
 
 全屏同时收起胶囊和宿主额外顶部栏，不保证原生内容铺满容器；页面应按实际 WebView 窗口和安全区适配；这不代表系统状态栏、手势条被隐藏或设备安全区消失，重要控件仍应按实际窗口信息避让。宿主 Runtime 统一提供小尺寸“退出全屏”浮动按钮：首次出现和点击右侧边缘重新唤出后，均在 1 秒后淡出并收至边缘，保留可点击的唤出入口。展开时点击按钮会调用 `setDisplay({ orientation: 'portrait', fullscreen: false })`，恢复竖屏、非全屏；退出全屏或销毁会话时移除按钮。H5 无需另行提供退出控件，也可按需提供自己的入口。业务也可通过 `navigation.close()` 提供退出入口；窗口变化事件本身不代表设备方向发生变化。
 
-该 API 为实验能力，自 SDK `0.8.1-alpha.4` 提供，Android/iOS 原生能力最低客户端版本为 `1.3.396`，实际以桥接能力为准。SDK 将 `METHOD_FORBIDDEN`、`METHOD_NOT_FOUND` 和 `REQUEST_UNSUPPORTED` 统一转换为 `{ supported: false }`。本地 Web/PC Host 不伪造方向或胶囊支持，请在已接入的移动端真机验收。
+该 API 为实验能力，自 SDK `0.8.3` 提供，Android/iOS/OHOS 原生能力最低客户端版本为 `1.3.396`，实际以桥接能力为准。SDK 将 `METHOD_FORBIDDEN`、`METHOD_NOT_FOUND` 和 `REQUEST_UNSUPPORTED` 统一转换为 `{ supported: false }`。本地 Web/PC Host 不伪造方向或胶囊支持，请在已接入的移动端真机验收。
 
 ## 错误处理
 
@@ -347,7 +349,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - `user.revokeAuthorization()` 在两种网络模式下都要求可信用户手势；成功后必须停止使用并清理业务缓存的旧身份、资料和服务端会话。
 - `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
 - `storage.setStorage()` 每个小程序最多写入 1000 个不同的 key（已写过的 key 可反复更新）；超出时返回 `STORAGE_QUOTA_EXCEEDED`。不要用时间戳、URL 等动态值拼 key，批量或大体积数据请写入 `files` sandbox。支持清理的宿主允许用户从简介页清理本地数据，范围与限制见[本地存储](https://docs.xiaoheihe.cn/hb_sdk/guide/storage)。
-- 现有业务网络请求仍使用 `network.request()`；该 API 仍受支持，但目前没有替代调用入口，不要依赖浏览器原生网络出口。自 `0.8.1-alpha.7` 起 `withCredentials` 配置已移除，传入会被忽略且不报错。
+- 现有业务网络请求仍使用 `network.request()`；该 API 仍受支持，但目前没有替代调用入口，不要依赖浏览器原生网络出口。自 `0.8.1` 起 `withCredentials` 配置已移除，传入会被忽略且不报错。
 - 公开 `network.request()` 与 `network.download()` 均使用 no-follow redirect policy；3xx 不会在 Host 内静默跳转。
 - `network.request()` 不能访问平台保留的 runtime auth 与 OpenAPI 内部路径；页面不得持有或交换服务端应用凭据。
 - `network.request` 不支持 `multipart/form-data`；App Host 仅支持 form（`application/x-www-form-urlencoded`）与 JSON。表单请用 `URLSearchParams#toString()` 作为 `data`，文件上传请走专用上传能力。

package/dist/card-controller.cjs.js

@@ -89,6 +89,11 @@ function viewDocument(regions, options = {}) {
   return compact({ schema: VIEW_SCHEMA_VERSION, regions: [...regions], ...options });
 }
 
+/**
+ * 工作区卡片定义入口。
+ *
+ * @since 0.9.1
+ */
 function defineCard(definition) { return definition; }
 const actionInput = {
     string: (options = {}) => ({ type: 'string', ...options }),
@@ -99,6 +104,11 @@ const actionInput = {
         type: 'object', properties, required: Object.keys(properties), additionalProperties: false,
     }),
 };
+/**
+ * 工作区卡片 action 定义入口。
+ *
+ * @since 0.9.1
+ */
 function defineAction(definition) {
     let actionId;
     const pending = [];
@@ -121,6 +131,11 @@ function defineAction(definition) {
         } });
     return handle;
 }
+/**
+ * 打开小程序 action 定义入口。
+ *
+ * @since 0.9.1
+ */
 function defineOpenMiniProgramAction(options = {}) {
     let actionId;
     const pending = [];
@@ -142,18 +157,35 @@ function defineOpenMiniProgramAction(options = {}) {
         } });
     return handle;
 }
+/**
+ * 工作区卡片控制器定义入口。
+ *
+ * @since 0.9.1
+ */
 function defineWorkspaceCardsController(controller) {
     for (const [id, action] of Object.entries(controller.actions ?? {}))
         action.bindActionId?.(id);
     return controller;
 }
-/** 定义控制器；构建器和 Host 分别验证静态 action 表。 */
+/**
+ * 定义控制器；构建器和 Host 分别验证静态 action 表。
+ *
+ * @since 0.9.1
+ */
 function defineWorkspaceCardController(controller) { return controller; }
-/** 生成固定受管 invoke 入口；身份由 Host 根据真实卡片绑定。 */
+/**
+ * 生成固定受管 invoke 入口；身份由 Host 根据真实卡片绑定。
+ *
+ * @since 0.9.1
+ */
 function invoke(actionId, params) {
     return { commandId: WORKSPACE_CARD_COMMANDS.invoke, input: { actionId, ...(params === undefined ? {} : { params }) } };
 }
-/** 只允许打开当前小程序。 */
+/**
+ * 只允许打开当前小程序。
+ *
+ * @since 0.9.1
+ */
 function openMiniProgram(actionId, params) {
     return { commandId: WORKSPACE_CARD_COMMANDS.openMiniProgram, input: { actionId, ...(params === undefined ? {} : { params }) } };
 }

package/dist/card-controller.esm.js

@@ -87,6 +87,11 @@ function viewDocument(regions, options = {}) {
   return compact({ schema: VIEW_SCHEMA_VERSION, regions: [...regions], ...options });
 }
 
+/**
+ * 工作区卡片定义入口。
+ *
+ * @since 0.9.1
+ */
 function defineCard(definition) { return definition; }
 const actionInput = {
     string: (options = {}) => ({ type: 'string', ...options }),
@@ -97,6 +102,11 @@ const actionInput = {
         type: 'object', properties, required: Object.keys(properties), additionalProperties: false,
     }),
 };
+/**
+ * 工作区卡片 action 定义入口。
+ *
+ * @since 0.9.1
+ */
 function defineAction(definition) {
     let actionId;
     const pending = [];
@@ -119,6 +129,11 @@ function defineAction(definition) {
         } });
     return handle;
 }
+/**
+ * 打开小程序 action 定义入口。
+ *
+ * @since 0.9.1
+ */
 function defineOpenMiniProgramAction(options = {}) {
     let actionId;
     const pending = [];
@@ -140,18 +155,35 @@ function defineOpenMiniProgramAction(options = {}) {
         } });
     return handle;
 }
+/**
+ * 工作区卡片控制器定义入口。
+ *
+ * @since 0.9.1
+ */
 function defineWorkspaceCardsController(controller) {
     for (const [id, action] of Object.entries(controller.actions ?? {}))
         action.bindActionId?.(id);
     return controller;
 }
-/** 定义控制器；构建器和 Host 分别验证静态 action 表。 */
+/**
+ * 定义控制器；构建器和 Host 分别验证静态 action 表。
+ *
+ * @since 0.9.1
+ */
 function defineWorkspaceCardController(controller) { return controller; }
-/** 生成固定受管 invoke 入口；身份由 Host 根据真实卡片绑定。 */
+/**
+ * 生成固定受管 invoke 入口；身份由 Host 根据真实卡片绑定。
+ *
+ * @since 0.9.1
+ */
 function invoke(actionId, params) {
     return { commandId: WORKSPACE_CARD_COMMANDS.invoke, input: { actionId, ...(params === undefined ? {} : { params }) } };
 }
-/** 只允许打开当前小程序。 */
+/**
+ * 只允许打开当前小程序。
+ *
+ * @since 0.9.1
+ */
 function openMiniProgram(actionId, params) {
     return { commandId: WORKSPACE_CARD_COMMANDS.openMiniProgram, input: { actionId, ...(params === undefined ? {} : { params }) } };
 }

package/dist/cli-chunks/{build-Do22AWbq.cjs → build-DvHmPnZZ.cjs}

@@ -1,14 +1,14 @@
 'use strict';
 
-var runtimeGate = require('./runtime-gate-BKc2zPV-.cjs');
+var runtimeGate = require('./runtime-gate-BvcLwvzi.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-B9SqoP85.cjs');
-var index = require('./index-bZIxID9N.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CbqmHz0r.cjs');
+var index = require('./index-hYvQR19Q.cjs');
 require('node:crypto');
 require('node:zlib');
-var projectVite = require('./project-vite-6eLmb4Em.cjs');
+var projectVite = require('./project-vite-BGy9w-Bx.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-CwEOrhL1.cjs');
+require('./version-BQMfLqms.cjs');
 require('node:async_hooks');
 require('readline');
 require('tty');

package/dist/cli-chunks/{context-DQhjWa7X.cjs → context-DYlZV8UG.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-B9SqoP85.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CbqmHz0r.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var index = require('./index-bZIxID9N.cjs');
+var index = require('./index-hYvQR19Q.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);

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

package/dist/cli-chunks/deploy-lock-CmKl9M1c.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-hYvQR19Q.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-KAhj5UTy.cjs → dev-DhEZBjd6.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
-var index = require('./index-bZIxID9N.cjs');
-var context = require('./context-DQhjWa7X.cjs');
+var index = require('./index-hYvQR19Q.cjs');
+var context = require('./context-DYlZV8UG.cjs');
 var node_crypto = require('node:crypto');
 var fs = require('node:fs');
-var runtimePermissionEnv = require('./runtime-permission-env-B9SqoP85.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-CbqmHz0r.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-6eLmb4Em.cjs');
-var version = require('./version-CwEOrhL1.cjs');
+var projectVite = require('./project-vite-BGy9w-Bx.cjs');
+var version = require('./version-BQMfLqms.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-KAhj5UTy.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-KAhj5UTy.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-DhEZBjd6.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-DhEZBjd6.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-EWleN3S5.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-DU7YhFWI.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;

package/dist/cli-chunks/{doctor-DNoQWBpo.cjs → doctor-B8q0UuXs.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-bZIxID9N.cjs');
+var index = require('./index-hYvQR19Q.cjs');
 require('node:module');
 require('readline');
 require('os');

package/dist/cli-chunks/games-CmO-AKXg.cjs

@@ -0,0 +1,140 @@
+'use strict';
+
+var node_crypto = require('node:crypto');
+var fs = require('node:fs/promises');
+var path = require('node:path');
+var index = require('./index-hYvQR19Q.cjs');
+var deployLock = require('./deploy-lock-CmKl9M1c.cjs');
+require('node:module');
+require('readline');
+require('os');
+require('tty');
+require('assert');
+require('events');
+require('stream');
+require('buffer');
+require('util');
+require('path');
+require('fs');
+require('constants');
+require('node:fs');
+require('node:zlib');
+
+const WINDOW_MS = 30 * 60 * 1000;
+const MAX_REQUESTS = 50;
+const INTERVAL_MS = 1000;
+/** 仅限制当前设备 CLI 的出站搜索，账号隔离并跨进程、跨项目持久保存。 */
+async function reserveGameSearchRequest(account, apiBaseUrl, options = {}) {
+    const cacheRoot = options.cacheRoot ?? index.envPaths('hb-sdk', { suffix: '' }).cache;
+    const scope = node_crypto.createHash('sha256').update(`${apiBaseUrl}\0${account}`).digest('hex');
+    let lock;
+    try {
+        lock = await deployLock.acquireDeployLock({ apiBaseUrl, miniProgramId: `game-search:${scope}`, version: 'rate-limit-v1' }, { cacheRoot });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === deployLock.DEPLOY_LOCKED_MESSAGE) {
+            throw new Error('游戏搜索请求正在处理中，请稍后重试');
+        }
+        throw error;
+    }
+    const directory = path.join(cacheRoot, 'game-search-limits');
+    const file = path.join(directory, `${scope}.json`);
+    const temp = `${file}.${node_crypto.randomUUID()}.tmp`;
+    try {
+        const now = (options.now ?? Date.now)();
+        let timestamps = [];
+        try {
+            const raw = await fs.readFile(file, 'utf8');
+            let stored;
+            try {
+                stored = JSON.parse(raw);
+            }
+            catch (error) {
+                if (!(error instanceof SyntaxError))
+                    throw error;
+            }
+            if (Array.isArray(stored) && stored.length <= MAX_REQUESTS && stored.every((value) => Number.isSafeInteger(value) && value >= 0)) {
+                timestamps = stored.filter((value) => value > now - WINDOW_MS).sort((a, b) => a - b);
+            }
+            else {
+                // 在账号锁内清除损坏的辅助缓存，本次按新记录继续，避免永久阻断搜索。
+                await fs.rm(file, { force: true });
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const last = timestamps.at(-1);
+        const intervalWait = last === undefined ? 0 : last + INTERVAL_MS - now;
+        const windowWait = timestamps.length < MAX_REQUESTS ? 0 : timestamps[0] + WINDOW_MS - now;
+        const wait = Math.max(intervalWait, windowWait);
+        if (wait > 0) {
+            throw new Error(`游戏搜索过于频繁，请 ${Math.ceil(wait / 1000)} 秒后重试`);
+        }
+        timestamps.push(now);
+        await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+        await fs.writeFile(temp, JSON.stringify(timestamps), { mode: 0o600, flag: 'wx' });
+        await fs.rename(temp, file);
+    }
+    finally {
+        await fs.rm(temp, { force: true }).finally(() => lock.release());
+    }
+}
+
+const GAME_SEARCH_API_PATH = '/bbs/app/topic/search_game';
+/** 查询平台游戏候选，不依赖项目绑定，也不写入本地配置或远端状态。 */
+async function runGameSearchCommand(query, options = {}, runtime = {}) {
+    const q = query.trim();
+    if (!q || Array.from(q).length > 100)
+        throw new Error('游戏搜索关键词须为 1–100 个字符');
+    const offset = parsePagination(options.offset ?? '0', 'offset', 0, 10_000);
+    const limit = parsePagination(options.limit ?? '10', 'limit', 1, 20);
+    const session = runtime.session ?? (await (runtime.requireAuthSession ?? index.requireHeyboxAuthSession)());
+    const context = index.createHeyboxOpenPlatformRequestContext(session, GAME_SEARCH_API_PATH);
+    await reserveGameSearchRequest(session.heyboxId, context.baseUrl, runtime.rateLimit);
+    const response = await (runtime.fetchImpl ?? fetch)(index.createHeyboxApiUrl(context.baseUrl, GAME_SEARCH_API_PATH, { ...context.platformParams, q, offset, limit: limit + 1 }), { headers: context.headers, redirect: 'error', signal: AbortSignal.timeout(15_000) });
+    const result = await index.readHeyboxApiEnvelope(response, { pathWithQuery: GAME_SEARCH_API_PATH, requireResult: true });
+    if (!Array.isArray(result?.games))
+        throw new Error('游戏搜索返回格式异常：缺少 games 数组');
+    const games = result.games.slice(0, limit).map(normalizeGame);
+    const output = {
+        games,
+        has_more: result.games.length > limit,
+        next_offset: offset + games.length,
+    };
+    const message = options.json
+        ? JSON.stringify(output, null, 2)
+        : [
+            ...(games.length ? games.map((game) => `${game.appid}\t${game.name}${game.name_en ? `（${game.name_en}）` : ''}`) : ['未找到匹配游戏，请尝试中文名或英文名。']),
+            '搜索结果为游戏候选，请核对具体游戏及平台；能否绑定以部署预检为准。',
+            ...(output.has_more ? [`更多结果：--offset ${output.next_offset} --limit ${limit}`] : []),
+        ].join('\n');
+    (runtime.write ?? ((text) => process.stdout.write(`${text}\n`)))(message);
+    return output;
+}
+function parsePagination(value, name, min, max) {
+    if (!/^(0|[1-9]\d*)$/.test(value))
+        throw new Error(`--${name} 必须为 ${min}–${max} 的整数`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max)
+        throw new Error(`--${name} 必须为 ${min}–${max} 的整数`);
+    return parsed;
+}
+function normalizeGame(value) {
+    if (!value || typeof value !== 'object')
+        throw new Error('游戏搜索返回格式异常');
+    const game = value;
+    const appid = typeof game.appid === 'number' || typeof game.appid === 'string' ? String(game.appid) : '';
+    if (!/^[1-9]\d*$/.test(appid) ||
+        !Number.isSafeInteger(Number(appid)) ||
+        Number(appid) > 2_147_483_647 ||
+        typeof game.name !== 'string' ||
+        !game.name.trim()) {
+        throw new Error('游戏搜索返回无效 appid 或名称');
+    }
+    const icon = typeof game.vertical_image === 'string' && game.vertical_image ? game.vertical_image : game.image;
+    return { appid, name: game.name, ...(typeof game.name_en === 'string' && game.name_en.trim() ? { name_en: game.name_en } : {}), ...(typeof icon === 'string' && icon ? { icon_url: icon } : {}) };
+}
+
+exports.runGameSearchCommand = runGameSearchCommand;

package/dist/cli-chunks/{index-DZUYwb3h.cjs → index-CRwNLk5w.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index$2 = require('./index-bZIxID9N.cjs');
+var index$2 = require('./index-hYvQR19Q.cjs');
 var require$$0$3 = require('fs');
 var require$$0$2 = require('crypto');
 var require$$1$2 = require('path');