@heybox/hb-sdk

Appearance

更新日志 ​

这里记录仓库中已经确认的 @heybox/hb-sdk 稳定版更新内容。文档与 npm 包独立发布，实际可安装版本以 npm latest 为准；预发布版本不在此页展示。

RSS 订阅

0.9.5 ​

新增能力 ​

文档与工具 ​

0.9.4 ​

必须操作 ​

  • 使用 esbuild: false 的生产配置需要移除该设置，保留生产构建的语法转换；已有小程序需升级 SDK 后重新构建、提交并发布，已上线旧包不会自动更新。

新增能力 ​

  • 新增游戏存档 API：gameSaves.list() 查询当前用户的 Steam 游戏存档，gameSaves.sync() 同步并等待完成，列表文件对象的 downloadFile() 返回只读 ZIP 文件；解压及游戏数据解析由开发者负责。使用前须声明 gameSaves 权限、登录小黑盒并使用正式发布版本，需要 Host 配套更新。
  • 新增 gameSaves.getLatestStructuredData()，可读取黑神话悟空和任务栏英雄已有的完整结构化数据，不触发解析；数据暂不可用时仍可查询和下载存档文件，需要 Host 与后端配套更新。

行为调整 ​

  • miniappManifest() 的生产构建保留 Chrome 64 / Safari 12 语法目标，项目更保守的目标继续生效；原样复制或远端加载的脚本、运行时 API polyfill 不在转换范围内。
  • hb-sdk build 与 hb-sdk remote deploy 统一拒绝含真实反斜杠的文件名、空 node_modules 目录及符号链接；请调整产物内容后重新构建。

问题修复 ​

  • 修复部分旧 WebView 因构建产物包含现代 JavaScript 语法而无法初始化小程序的问题。
  • 修复未声明工作区卡片的小程序在 PC 本地调试时无法读取窗口尺寸配置的问题，需要 PC 工坊插件配套更新；升级后重新运行 hb-sdk dev。

0.9.3 ​

必须操作 ​

  • user.getSteamGameList() 移除 price 字段及 SteamGamePrice 类型；升级前请删除相关读取和类型引用。

新增能力 ​

  • 新增实验性 media.pick()，支持系统图库、拍照和录像，返回只读媒体文件及预览地址；使用前须声明 media 权限，需要 Android/iOS 1.3.398 或鸿蒙 1.3.396 及以上客户端，并以实际能力发现结果为准。
  • user.getSteamGameList() 的游戏条目新增可选 portraitImage 竖版封面，需要 Host 配套更新；字段不可用时可用 game.portraitImage ?? game.image 回退。

行为调整 ​

  • network.request() 在支持的 Mobile Host 中可发送应用请求头、JSON 和更多 HTTP 方法；旧 Host 无法处理的形态返回 REQUEST_UNSUPPORTED，普通 GET 和可兼容的表单 POST 保持可用。

问题修复 ​

  • 修复 network.request() 请求官方接口时，显式设置表单 Content-Type 导致请求失败的问题。

文档与工具 ​

  • viewport.setDisplay() 补充 1.0.0 返回值迁移预告；当前结果对象与错误行为保持不变，升级前请按说明准备兼容处理。
  • SDK Skill 在实现展示设置或升级 SDK 前主动提醒检查迁移说明、版本门槛及错误处理。
  • 补充 network.request() 的移动端请求头与签名兼容说明，明确请求成功不代表已附加客户端签名。
  • 终端权限申请明确仅第三方主体需要提交申请，权限获批后仍须在项目中声明并启用。
  • 补充云端存储登录要求：四个方法均需登录小黑盒客户端，未登录时 Promise 以 UNAUTHORIZED 拒绝，并说明登录成功后重试的处理方式。

0.9.2 ​

必须操作 ​

  • 真机调试请将项目中的 @heybox/hb-sdk 升级至 0.9.2，重新运行 hb-sdk dev 并打开调试会话。启动前须完成 CLI 登录、小程序绑定及远端配置校验；校验失败时按提示修复后重试。
  • 移除 @heybox/hb-sdk/miniapp-publish 导出的 getMiniappUploadKey()、validateUploadPaths() 及其类型；升级前请检查项目是否直接引用这些导出。

新增能力 ​

行为调整 ​

  • 云存储限制：key 仅支持英文字母、数字、下划线和连字符，最长 128 字符；value 最大 16 KB，不存在的 key 返回 undefined。
  • 手机真机调试时，network.request() 仅对 localhost 和 127.0.0.* 使用开发机代理，其它域名和 IP 使用手机自身网络。
  • hb-sdk dev 启动校验失败时退出并提供修复指引，不再自动进入匿名 Browser Mock；启动后真机调试暂不可用时，仍可继续使用浏览器调试。
  • 开发启动、构建和部署时，对简介缺失、工具类未关联游戏给出非阻断提醒。Agent Skill 主动检查分类、简介和游戏绑定，保留已有内容，通用工具可保持不关联游戏。

问题修复 ​

  • 修复旧版 Android WebView 中本地存储读写和清理失败的问题。
  • 修复同账号登录态刷新导致云存储误报登录状态变化的问题。
  • 修复部分鸿蒙客户端读取 Steam 游戏库时超时的问题。
  • 修复合法内测版本和历史预览入口读取用户信息失败的问题。
  • 修复 Vite 5/6 开发服务在输出资料或旧模板平台提醒时无法启动的问题。

文档与工具 ​

  • API Reference 中的 API 可用版本统一展示正式版，并修正部分版本标注。

0.9.1 ​

必须操作 ​

  • 真机调试请将项目中的 @heybox/hb-sdk 升级至 0.9.1，重新运行 hb-sdk dev 并打开调试会话。
  • 截图分享从正式版 0.9.1 起新增品牌水印，截图区域底部须预留至少 57 个逻辑像素；旧版及 0.9.1 预发布版保持无水印截图。
  • CLI 反馈统一使用 hb-sdk feedback，须提供问题描述、SDK 版本、平台、日志和截图。
  • storage.setStorage() 最多保存 1000 个不同的 key；超额返回 STORAGE_QUOTA_EXCEEDED，大量数据请使用文件沙箱，详见本地存储。

新增能力 ​

行为调整 ​

  • 权限不在当前授权快照中时返回 PERMISSION_NOT_IN_SNAPSHOT，处理方式见错误处理。
  • 调试台与 hb-sdk remote info 分别展示本地权限和线上状态，本地可用不代表发布后已获批准。

问题修复 ​

  • 修复开启网络权限后用户信息和 Steam 游戏库接口不可用的问题。
  • 修复授权状态变化时错误原因不明确的问题；小程序启动失败时显示具体原因，版本已更新时提示重新打开。
  • 修复本地声明权限受线上版本限制的问题；权限刷新失败后自动重试，重开调试会话时刷新过期状态。
  • 修复文件选择和截图超时、连续截图冲突及水印缺失的问题。
  • 修复反馈附件上传错误，加强日志文件校验。
  • 修复桌面调试中存储写入失败、清理后仍出现残留数据，以及历史空值未按未设置处理的问题。

0.9.0 ​

必须操作 ​

  • 补齐 package.json#heybox.permissions：未声明会直接拒绝构建，无权限需求也要配置 {}。
  • 补齐 package.json#heybox.platforms：产物 SDK 版本达到 0.9.0 后，缺少平台声明不再按移动端兜底。
  • 按实际调用补齐最小声明；声明的新增、删除和配置变化会进入版本审核差异。

行为调整 ​

  • 手机真机调试的 network.request() 由开发机转发，请求中的 localhost 指向开发机。
  • hb-sdk dev 只在启动、绑定或权限声明变化时读取远端详情；手机重连复用快照，不再因票据续签反复请求。
  • user.getSteamGameList() 复用已有结果，文件能力不可用时回退内存缓存。
  • navigation.openAppPage({ target: 'mini_program' }) 跳转前先恢复竖屏；恢复失败或跳转超时、SDK 销毁后不再打开目标。
  • Companion ZIP 复用已验证内容，服务端校验通过后再提交审核，中断的部署可续接。

问题修复 ​

  • 修复权限校验失败后仍能获取续签启动票，以及声明变化时旧状态覆盖最新调试状态的问题。
  • 修复扫码调试启动信息缺少当前用户小程序身份，导致部分 Android 调试容器无法使用原生桥接能力的问题。

文档与工具 ​

  • 浏览器调试台支持横竖屏与全屏模拟。
  • 补齐网络超时与重试、Steam 授权、生命周期事件、Android 文件读写与鸿蒙目录选择等能力说明。

0.8.5 ​

必须操作 ​

  • 小程序接口遇到平台限流（HTTP 403/429）时返回的错误码统一为 RATE_LIMITED：错误数据里的 status 为上游状态码，retryAfterMs（可能缺失）为建议退避时长。此前分别返回 REQUEST_FAILED（auth / user / home_v2）或 UNAUTHORIZED（cloud.leaderboard，401 仍为 UNAUTHORIZED）。
  • 新增本地拒绝错误码 RATE_LIMITED_BY_RUNTIME：Runtime 自身的每 session 配额与同一接口的循环检测触发时返回，错误数据里的 origin 为 budget 或 loop，请求不会到达上游。遇到上述两个错误码时请停止立即重试，避免把用户 IP 打成被封。

行为调整 ​

  • user.getInfo() / auth.login() / 排行榜接口 的同一份结果会在短时间内复用（身份 30s、资料 60s、榜单沿用既有 5 分钟）。账号切换与授权撤销会立即失效；Steam 换绑 / 解绑最多 30s 后生效。
  • hb-sdk dev 会短暂复用已读取的调试信息，并在读取失败后逐步延长重试间隔，不再持续请求远端。
  • 被平台限流时会暂停刷新并给出预计恢复时间，提示不要反复重启。

问题修复 ​

  • 修复手机真机调试反复重连时持续请求远端调试信息、进而触发平台限流的问题。

文档与工具 ​

  • 被平台限流时提示升级到最新版本。

0.8.4 ​

问题修复 ​

  • 修复手机真机调试时详情页无法读取本地启动信息和 Dev Context，导致调试页反复重连或刷新的问题。

0.8.3 ​

必须操作 ​

新增能力 ​

行为调整 ​

  • hb-sdk dev 临时权限 支持普通网络和 Companion 调试，不包含官方域名，也不会带到线上。
  • 新项目和历史缺声明产物 默认覆盖 Android、iOS、OHOS、Windows 与 macOS；显式移动端声明只提示复核。
  • 浏览器调试台移除分端汇总状态，不可用原因改在对应入口展示。

问题修复 ​

  • 对齐浏览器预览与真机的导航栏前景色和顶部安全区。
  • 修复 hb-sdk dev 使用旧 Vite 产物时页面 SDK 版本不一致的问题。
  • 修复开发日志 CSP 循环告警。
  • 修复默认端口占用时 hb-sdk dev 卡在入口探测的问题。

文档与工具 ​

0.8.2 ​

必须操作 ​

  • 在 package.json 项目配置 中补齐 name、icon 和 coverImages，并替换占位图；pnpm 白名单项目还需按安装说明允许 sharp。（安装说明）
  • remote deploy 已移除 --from-version，使用该参数的脚本必须改为从当前项目构建。（remote deploy）
  • 启用 Steam 账号能力的 Host 须提供可信的功能开关、用户数据模式和授权上下文；缺失或不一致时，用户数据请求会被拒绝。

新增能力 ​

  • 新增 Steam 账号授权 scope steam_account、可选 steam_id 和授权状态。联网模式使用 auth.login() 与服务端 OpenAPI，无网络模式使用 user.getInfo()；反向调用返回 SERVER_API_REQUIRED。
  • 版本资料迁移 支持 remote bind、dev 与 remote deploy，会写入 package.json 和 assets/heybox/；已下架项目同样支持，无法比较远端图片时显示 unavailable。
  • @heybox/hb-sdk/miniapp-publish 新增版本资料解析与预览、部署前 Manifest 校验、Runtime Gate 检查及相关公开类型。

行为调整 ​

  • build 保持离线；remote deploy 会校验版本资料，并可在重试同一构建时复用已上传文件。开放平台只读预览构建资料。
  • Companion 确认界面 新增归档大小与可选 SHA-256 展示；SHA-256 不会进入 CompanionInfo。

文档与工具 ​

  • 完善项目配置、API 与 files 文档；随包 Agent Skill 改为读取 LLM 文档索引，hb-sdk doctor 会识别旧 references 和额外文件。

0.8.1 ​

必须操作 ​

  • 平台声明迁移到 package.json#heybox.platforms，Vite 配置中使用无参 miniappManifest()；旧版带 companions 参数的写法已移除，桌面程序改由 package.json#heybox.companions 声明。
  • network.request 不再支持 withCredentials：传入会被忽略且不报错，请从代码中移除；请求凭据由客户端按目标域名决定，应用可显式提供 Cookie 或 Authorization。

新增能力 ​

  • 窗口尺寸声明 package.json#heybox.window：defaultWidth、defaultHeight、minWidth、minHeight、resizable，构建时写入 Manifest；窗口位置不对开发者开放。
  • 游戏绑定 package.json#heybox.bindAppIds：每个版本最多声明 20 个游戏 appid，部署前校验游戏可用，hb-sdk remote info 只读展示本地与线上绑定差异。
  • 受管桌面程序 companion：显式准备、启动和控制随审核版本发布的桌面辅助程序，支持会话输出、退出通知与只读附件。
  • 移动端（Android/iOS 1.3.396+）开放受控文件空间与流式下载：单文件或目录选择，以及带进度、可取消的公网流式下载。
  • 环境信息 environment.getInfo() 与 environment.getInfoSync()。
  • 手机真机调试会话权限按项目声明与平台批准结果逐项求交；创建会话前会刷新远端批准结果。
  • hb-sdk dev 调试台可在运营审核完成前预览候选版本的桌面程序产物，也可在审核通过后调试正式产物；未发布的预览产物以独立来源标识区分。
  • 平台解析合同：@heybox/hb-sdk/miniapp-publish 新增 resolveMiniappManifestPlatforms()，按项目声明的平台与 hb-sdk 0.9.0 硬切口径解析支持平台；未声明且低于 0.9.0 时按 Android/iOS/OHOS 兼容，0.9.0 起未声明直接失败，声明非法（空数组、未知值、重复值、类型错误）抛错。调用方应复用它，不要自行比较版本或补默认值。
  • hb-sdk dev 新增多设备日志能力：hb-sdk dev logs 查询设备日志并支持 --follow 输出 NDJSON，hb-sdk dev devices 列出已连接设备，hb-sdk dev sandbox list 查看小程序沙箱目录。

行为调整 ​

  • network.request() 仍受支持，但不再支持 withCredentials 配置（传入会被忽略且不报错）；Origin、Referer、User-Agent 由客户端统一接管，路由与逐跳请求头不能由小程序设置。
  • 浏览器调试台按当前 SDK 版本校验握手，使用旧版本 SDK 的页面会被拒绝启动。
  • 调试台桌面端入口只在项目声明了桌面平台时展示；手机扫码调试不受影响。
  • 受管桌面程序的归档总大小上限为 500 MiB，超限时构建与部署直接失败。
  • hb-sdk doctor 现在校验随包 Agent Skill 的内容完整性，并同时探测项目级与全局 .agents/skills；Skill 缺失、版本不匹配或内容被手工修改时返回非零退出码。
  • Host/Runtime 集成：PC 页面通道合同升级到 1.7.0（1.6.0 → 1.7.0 增量），新增窗口通道的 getGeometry 请求与 geometryChanged 上报；只有用户拖拽来源才允许写入本地窗口记忆，detail 页面与工坊插件须成对发布与回滚。

问题修复 ​

  • 修复调试台页脚版本号显示、hb-sdk remote info 权限快照误判，以及旧版桌面宿主能力判定等问题。

文档与工具 ​

  • 补充窗口尺寸、游戏绑定、受管桌面程序、移动端文件与下载的使用说明和能力边界；调试台按平台展示浏览器、手机与桌面程序的就绪状态。

0.8.0 ​

必须操作 ​

  • 新项目或新增受控能力时，在 package.json#heybox.permissions 中声明实际需要的权限，并按平台审核结果使用对应能力。

新增能力 ​

  • 新 PC 工坊小程序支持隔离文件空间、单文件或目录选择、saveFile() 和公网流式下载；其他平台对尚未开放的文件能力保持明确不可用。
  • hb-sdk dev 调试台新增「日志」页签，可实时查看业务 console 日志以及 SDK 诊断信息，生产构建不包含调试代码。
  • hb-sdk create 使用可直接替换的 Vanilla JavaScript + Vite 模板；hb-sdk skill install 和 hb-sdk doctor 随 npm 包提供匹配版本的开发辅助能力。

行为调整 ​

  • 普通 share.showShareMenu() 分享统一使用当前小程序的通用落地页；原有 extra 页面状态、share.copyLink() 和 share.getExtra() 能力保持可用。
  • network 权限只控制公开网络请求与下载能力，不再联动登录、用户资料和排行榜；权限声明、平台批准和能力支持状态会分别反馈。
  • 移动端请求第三方接口时统一由应用网络层执行，原有 URL、method、headers、body、timeout 和 withCredentials 配置保持兼容。

问题修复 ​

  • 修复移动端第三方请求受 WebView CORS 限制而失败的问题。
  • 修复本地设备预览尺寸、底部系统导航条和开发控制台输出等调试体验问题。

文档与工具 ​

  • 更新权限声明、文件与下载、分享和 API Reference 文档，并提供公开更新日志与 RSS 订阅。

0.7.4 ​

新增能力 ​

行为调整 ​

  • hb-sdk dev 启动浏览器、Mac 或移动端调试前，需要先完成 CLI 登录并绑定小程序。
  • 移动端调试链接仅适合在受信任的局域网内使用。

问题修复 ​

  • 修复首次授权确认信息不完整，以及部分旧版 iOS 环境无法完成授权操作的问题。
  • 修复移动端存储对象读取和部分跨端重试场景中的兼容性问题。