@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 读取指定 alias 在当前版本与当前平台上的 Companion 描述快照。

      参数

      • alias: string

        package.json#heybox.companions 中声明的 Companion alias。必须完整匹配 [a-z][a-z0-9-]{0,31}:长度为 1 至 32,第一个字符是小写 ASCII 字母,其余字符 只能是小写字母、数字或连字符;SDK 不会 trim 或改变大小写。

      返回 Promise<CompanionInfo>

      Host 绑定的当前审核版本、精确预览版本或本地开发快照对应的冻结 CompanionInfo。返回只描述当前平台选中的制品,不包含准备状态或活动 Session。

      HbMiniProgramSDKError alias 不符合格式时在请求前以 INVALID_PARAMS 拒绝;当前版本未声明 alias、当前平台没有匹配 target、预览 Host 不支持 Companion、 描述符暂不可用或当前 Host 不支持能力时,可能以 COMPANION_NOT_DECLARED、 COMPANION_TARGET_UNSUPPORTED、COMPANION_PREVIEW_UNSUPPORTED、 COMPANION_DESCRIPTOR_UNAVAILABLE、COMPANION_UNSUPPORTED 或 METHOD_FORBIDDEN 拒绝。 当前运行快照缺少或未启用 companion 权限时分别以 PERMISSION_NOT_IN_SNAPSHOT、 PERMISSION_DENIED 拒绝;Host 返回 alias 不匹配、未知 target/capability/source、非法大小 或签名状态时以 COMPANION_HOST_FAILED 拒绝。握手失败、SDK/Runtime 已销毁、bridge 超时及其他 Host 失败会保留对应 SDK 错误码。

      该方法是只读查询:不会下载、校验、解压、准备或启动程序,也不会创建或取得 Session controller。它不要求可信用户手势,不展示 prepare/launch 的 Host 授权弹窗,但仍需要 Manifest 声明且平台批准 companion 权限。V1 真实能力仅支持新 PC Host 的 windows-x64 与 macos-arm64;Browser Dev Host 返回固定 Fake 描述,仅用于状态联调。

      SDK 不缓存该结果,每次调用都会重新向 Host 查询当前绑定上下文。返回字段包括请求的 alias、展示名 displayName、当前平台选中的 target、去重后的 capabilities、压缩 归档字节数 archiveBytes、签名检查状态 signatureStatus 和可选来源 source。Runtime 会丢弃 Host 提供的路径、下载 URL、SHA-256、entrypoint 等敏感或非公开字段。

      CompanionInfo 没有 state 或版本字段。使用 companion.getPreparationStatus 区分 not-prepared、preparing、ready、failed;需要开始准备时,必须在新的可信 用户操作中显式调用 companion.prepare。 getInfo() 成功不表示制品已经下载、签名有效、可以启动或存在活动 Session。

      import hbSDK from '@heybox/hb-sdk'

      const info = await hbSDK.companion.getInfo('runner')
      const status = await hbSDK.companion.getPreparationStatus('runner')

      renderCompanionSummary({
      name: info.displayName,
      target: info.target,
      archiveBytes: info.archiveBytes,
      source: info.source ?? 'unknown',
      capabilities: info.capabilities,
      preparationState: status.state,
      })

      0.8.1

      windows

      macos

      windows none

      macos none