@heybox/hb-sdk 0.9.1-alpha.9 → 0.9.2-alpha.0

package/CHANGELOG.md

@@ -2,6 +2,113 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 0.9.2-alpha.0 - 2026-10-19
+
+### 问题修复
+
+- 修复旧版 Android WebView 中本地存储读写和清理失败的问题。
+
+## 0.9.1 - 2026-10-17
+
+### 必须操作
+
+- [真机调试](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)请将项目中的 `@heybox/hb-sdk` 升级至 `0.9.1`，重新运行 `hb-sdk dev` 并打开调试会话。
+- [截图分享](https://docs.xiaoheihe.cn/hb_sdk/recipes/community-share#%E6%88%AA%E5%9B%BE%E5%88%86%E4%BA%AB)从正式版 `0.9.1` 起新增品牌水印，截图区域底部须预留至少 57 个逻辑像素；旧版及 `0.9.1` 预发布版保持无水印截图。
+- CLI 反馈统一使用 [`hb-sdk feedback`](https://docs.xiaoheihe.cn/hb_sdk/guide/faq#%E8%83%BD%E5%90%A6%E7%9B%B4%E6%8E%A5%E7%94%A8-cli-%E6%8F%90%E4%BA%A4%E5%8F%8D%E9%A6%88)，须提供问题描述、SDK 版本、平台、日志和截图。
+- `storage.setStorage()` 最多保存 1000 个不同的 key；超额返回 `STORAGE_QUOTA_EXCEEDED`，大量数据请使用文件沙箱，详见[本地存储](https://docs.xiaoheihe.cn/hb_sdk/guide/storage)。
+
+### 新增能力
+
+- 新增 `network.upload()`，支持 [raw 和 multipart 上传](https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox#%E4%B8%8A%E4%BC%A0%E5%8F%97%E6%8E%A7%E6%96%87%E4%BB%B6)、进度及取消。
+- `share.screenshot()` 新增 `watermarkTheme`：浅色背景用 `light`，深色背景用 `dark`（默认）。
+- CLI 支持[查询、回复反馈工单](https://docs.xiaoheihe.cn/hb_sdk/guide/faq#%E8%83%BD%E5%90%A6%E7%9B%B4%E6%8E%A5%E7%94%A8-cli-%E6%8F%90%E4%BA%A4%E5%8F%8D%E9%A6%88)及上传图片和日志。
+- 新增 [PC 游戏工作区卡片](https://docs.xiaoheihe.cn/hb_sdk/guide/workspace-cards)构建、刷新与本地调试，需使用支持该能力的 PC 客户端。
+- CLI 支持[查询权限、申请 Network 和 Companion 权限](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions#%E7%BB%88%E7%AB%AF%E6%9D%83%E9%99%90%E7%94%B3%E8%AF%B7)，调试台提供申请入口。
+- 支持通过 [`package.json#heybox.desc`](https://docs.xiaoheihe.cn/hb_sdk/guide/project-configuration) 配置小程序简介。
+- 用户可在支持该能力的宿主简介页[查看并清理本地数据](https://docs.xiaoheihe.cn/hb_sdk/guide/storage)。
+
+### 行为调整
+
+- 权限不在当前授权快照中时返回 `PERMISSION_NOT_IN_SNAPSHOT`，处理方式见[错误处理](https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling)。
+- 调试台与 `hb-sdk remote info` 分别展示本地权限和线上状态，本地可用不代表发布后已获批准。
+
+### 问题修复
+
+- 修复开启网络权限后用户信息和 Steam 游戏库接口不可用的问题。
+- 修复授权状态变化时错误原因不明确的问题；小程序启动失败时显示具体原因，版本已更新时提示重新打开。
+- 修复本地声明权限受线上版本限制的问题；权限刷新失败后自动重试，重开调试会话时刷新过期状态。
+- 修复文件选择和截图超时、连续截图冲突及水印缺失的问题。
+- 修复反馈附件上传错误，加强日志文件校验。
+- 修复桌面调试中存储写入失败、清理后仍出现残留数据，以及历史空值未按未设置处理的问题。
+
+## 0.9.1-alpha.15 - 2026-10-17
+
+### 问题修复
+
+- 修复桌面调试中存储读取正常但写入失败的问题。
+- 修复取消存储写入后，清理完成仍可能出现迟到数据的问题。
+
+## 0.9.1-alpha.14 - 2026-10-16
+
+### 问题修复
+
+- 授权状态发生变化时保留明确错误码，避免被误报为普通请求失败。
+- 小程序启动失败时显示具体原因，版本已更新时提示重新打开。
+
+## 0.9.1-alpha.13
+
+### 问题修复
+
+- 修复真机调试中部分用户信息接口不可用的问题，授权状态读取失败时明确提示重试。
+- 本地权限刷新遇到临时故障或限流后自动重试，重新打开调试会话时刷新过期权限缓存。
+
+## 0.9.1-alpha.12 - 2026-10-16
+
+### 行为调整
+
+- 新宿主仅对正式 SDK `0.9.1` 及以上启用默认截图水印；较旧版本（含 `0.9.1-alpha.*`）或缺少版本记录的兼容模式静默保留无水印截图。
+- SDK 每次调用 `share.screenshot()` 时输出行为变更提醒，说明水印版本门槛、底部至少预留 57 个逻辑像素及明暗配色；日志输出失败不影响截图。
+
+### 文档与工具
+
+- Agent Skill 强制检查截图升级影响，提醒同步核对页面布局、版本兼容和主题选择。
+
+## 0.9.1-alpha.11 - 2026-10-16
+
+### 新增能力
+
+- 支持通过 `package.json#heybox.desc` 配置小程序简介，并在构建产物中保留 `manifest.desc`。
+
+### 问题修复
+
+- 支持查看并清理当前小程序的本地数据；历史空值读取为未设置。
+
+## 0.9.1-alpha.10 - 2026-10-16
+
+> 影响级别：必须操作
+> 开发者动作：为调用 `share.screenshot()` 的页面，在目标截图区域底部预留至少 57 个逻辑像素的空白背景，避免遮挡重要内容，并按背景选择水印主题以保证对比度。
+> 兼容范围：公开 API 与参数保持兼容；水印由更新后的宿主自动添加，无需自行绘制或增加调用参数。系统按键截图暂不支持，新 PC 的截图分享能力限制保持不变。
+
+### 新增能力
+
+- `share.screenshot()` 增加可选 `watermarkTheme`：`light` 适合浅色背景，显示黑色水印；`dark` 适合深色背景，显示白色水印。默认 `dark`，不自动跟随系统主题。
+
+### 行为调整
+
+- 小程序内截图分享自动添加小黑盒品牌搜索胶囊，搜索词使用当前小程序名称，下方显示灰色「小黑盒工坊小程序」。
+- 同一小程序的连续截图请求依次处理，避免水印与分享面板重叠。
+
+### 问题修复
+
+- 修复客户端尚未完成截图时水印被提前移除、导致成图没有水印的问题。
+- 截图等待不再受 SDK 普通请求超时限制，支持超过 10 秒的延迟和连续排队；取消的请求不会继续从排队或延迟阶段投递原生截图。
+
+### 文档与工具
+
+- 补充截图底部预留区域与背景对比度的要求，说明自定义截图区域同样适用。
+
+
+
 ## 0.9.1-alpha.9 - 2026-10-16
 
 ### 新增能力
@@ -16,7 +123,7 @@
 
 ### 问题修复
 
-- 修复反馈附件上传授权请求缺少表单类型，导致服务端无法读取上传范围并返回“参数错误:1000”的问题。
+- 修复反馈附件上传时提示“参数错误:1000”的问题。
 - 反馈日志上传前校验 ZIP 目录、结束记录和 CRC，拒绝损坏或未写完的压缩包；修复普通日志末尾残缺 UTF-8 字符被漏检的问题。
 
 ### 文档与工具
@@ -25,10 +132,7 @@
 
 ## 0.9.1-alpha.8 - 2026-10-16
 
-### 问题修复
-
-- 修复第一方小程序已声明权限在 CLI 查询、本地调试和发布检查中被误判为不可用的问题。
-- 权限查询区分原始审批与有效权限，并展示第一方自动批准来源。
+- 本次预发布无面向外部开发者的功能变更。
 
 ## 0.9.1-alpha.7 - 2026-10-16
 
@@ -61,20 +165,7 @@
 
 ## 0.9.1-alpha.4 - 2026-10-14
 
-### 新增能力
-
-- 预留 `hbSDK.device.executeProtocol()`（暂不对外开放）：在获得平台批准的 `appProtocol` 权限后执行任意小黑盒协议，支持完整协议字符串与 JSON 协议对象；返回 `Promise<void>`，成功只表示已投递，不转发协议业务返回值或回调。
-- 预留最高危险等级权限 `appProtocol`（暂不对外开放，不提供开发者申请入口）：批准后该入口可执行任意协议，并绕过其他 SDK 能力权限及其专用授权流程；该总授权只作用于 `device.executeProtocol()`，其他 SDK 方法仍执行各自权限与授权规则。
-- `hb-sdk dev` 支持为已声明但未获线上批准的 `appProtocol` 生成当前 Dev Session 的本地临时授权；浏览器调试台记录协议类型并以 Mock 投递成功，不模拟真实协议效果。
-
-### 问题修复
-
-- 协议执行收到取消后停止尚未投递的后续动作；调用超时或 SDK 销毁时通知 Host 取消，已投递的系统动作不会撤销。
-- 协议对象中的函数、Symbol 等无法发送的参数统一返回 `INVALID_PARAMS`，保留原始原因供排查。
-
-### 文档与工具
-
-- 权限指南、API Reference、CLI 调试说明与 `hb-sdk remote permission apply` 同步 `appProtocol` 与 `device.executeProtocol`。
+- 本次预发布无面向外部开发者的功能变更。
 
 ## 0.9.1-alpha.3 - 2026-10-14
 

package/README.md

@@ -28,7 +28,7 @@ npm run dev
 
 手机二维码的短链先打开普通中间页，再进入专用 dev-shell。最终 `openWindow` 协议会把 CLI 校验后的用户小程序字符串 ID（UUID）写入根字段 `user_miniprogram_id`；原生不会从 URL 查询参数补读，也不能用传统小程序数字 ID 代替。匿名调试不生成小程序 ID，原生未开放的横屏能力仍返回 `supported: false`。入口排查与验证记录见 [Android 396 入口审计](./docs/android-396-launch-identity.md)。
 
-当前 `0.8` 已发布为稳定版本，创建命令使用 `@latest`。
+创建命令使用 `@latest`，实际安装版本以 npm 的 `latest` 为准。
 
 ### 接入已有项目
 
@@ -56,7 +56,7 @@ hb-sdk skill install --all-agents
 
 SDK 会在导入时启动握手，能力调用会自动等待 SDK 就绪。声明 `userInfo` 后，可通过 `user.getInfo()` 读取当前小程序内的隔离身份和已授权资料：
 
-使用受保护能力前，需要在项目根 `package.json#heybox.permissions` 中显式声明。`auth.login()` 和 `user.getInfo()` 都只需要 `userInfo`，不依赖公开 `network` 权限；`network` 约束 `network.request()`、`network.download()` 与 `network.upload()`，线上使用仍需平台批准。`network` 和 `companion` 可在开放平台“小程序管理 → 权限申请”中提交申请，开发者不能申请访问官方域名。`hb-sdk dev` 可临时补齐普通网络和 Companion 的批准缺口，但不能补齐官方域名，调试台会持续提示发布后不可用。完整配置、本地调试边界和 0.8/0.9 迁移规则见[权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)。
+使用受保护能力前，需要在项目根 `package.json#heybox.permissions` 中显式声明。`auth.login()` 和 `user.getInfo()` 的方法权限都是 `userInfo`；用户资料读取不依赖 `network`，但启用 Steam 账号能力后的无网络 `local` 模式不能调用 `auth.login()`，会返回 `SERVER_API_REQUIRED`。`network` 约束 `network.request()`、`network.download()` 与 `network.upload()`，线上使用仍需平台批准。`network` 和 `companion` 可在开放平台“小程序管理 → 权限申请”中提交申请，开发者不能申请访问官方域名。`hb-sdk dev` 可临时补齐普通网络和 Companion 的批准缺口，但不能补齐官方域名，调试台会持续提示发布后不可用。完整配置、本地调试边界和 0.8/0.9 迁移规则见[权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)。
 
 需要可信用户手势的按钮不能在点击回调里等待握手。页面加载时先用 `getHandshakeState()` 读取当前状态，再用 `onHandshakeStateChange()` 订阅并立即接收当前状态；仅在 `status === 'ready'` 时启用按钮，并在组件或页面销毁时调用订阅返回的取消函数。`ready` 生命周期事件只是握手成功瞬间派发、不会重放的边沿通知，不能用来判断当前状态。
 
@@ -332,6 +332,8 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | `network`    | 发起经过平台授权的网络请求及受控文件传输  |
 | `companion`  | 准备、启动并控制当前版本审核过的桌面辅助应用    |
 
+`share.screenshot()` 每次调用都会在 SDK 侧输出行为变更 warning，提醒升级后的布局与配色要求；日志失败不阻断调用。截图从正式 SDK `0.9.1` 起默认添加水印。新 Runtime 对低于 `0.9.1` 的 SDK（包含 `0.9.1-alpha.*`）或缺少 SDK 版本记录的兼容模式静默保持无水印截图；升级前需同步调整布局。启用水印时，会在截图区域底部添加当前小程序名称的品牌搜索胶囊及灰色「小黑盒工坊小程序」。请在目标区域底部预留至少 57 个逻辑像素的空白背景，避免遮挡重要内容，并保证背景与水印有足够对比度。`watermarkTheme: 'light'` 适合浅色背景（黑色水印），`'dark'` 适合深色背景（白色水印，默认）；不自动跟随系统主题。水印仅在 SDK 截图期间展示，不增加图片尺寸；系统按键截图暂不支持。截图等待不受 SDK 普通请求超时限制；排队和延迟期间会响应会话终止，Mobile Host 从投递原生截图起最多等待 15 秒成图回调。详见 [截图分享布局要求](https://docs.xiaoheihe.cn/hb_sdk/recipes/community-share#截图分享)。
+
 具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
 
 ## 关键约束
@@ -341,9 +343,10 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - `ready` 生命周期事件是不可重放的边沿通知，不代表可查询状态，也不能替代握手状态 API。
 - `auth.login({ scopes? })` 只返回 `{ code, expiresIn: 300, scopes }`；identity 隐式强制包含，code 只能提交给开发者服务端。
 - 需要授权 UI 时，`auth.login()` 必须来自可信用户手势，否则返回 `USER_GESTURE_REQUIRED`；用户取消或关闭时返回 `AUTHORIZATION_CANCELLED`。已授权时可以静默返回新 code。
-- `auth.login()`、`user.getInfo()` 和 `user.getSteamGameList()` 的可用性不由 `network` 决定；它们分别要求 `userInfo` 或 `steamLibrary`，并继续遵循各自的用户授权和数据规则。
+- `user.getInfo()` 和 `user.getSteamGameList()` 不依赖 `network`，分别要求 `userInfo` 和 `steamLibrary`；`auth.login()` 的方法权限是 `userInfo`，但无网络的 `local` 模式返回 `SERVER_API_REQUIRED`，`legacy` 模式保留原有行为。
 - `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()` 与 `network.download()` 均使用 no-follow redirect policy；3xx 不会在 Host 内静默跳转。
 - `network.request()` 不能访问平台保留的 runtime auth 与 OpenAPI 内部路径；页面不得持有或交换服务端应用凭据。
@@ -351,7 +354,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - 新 PC 开放持久 sandbox、单文件/目录 picker、精确 File 保存与公网 `network.download()`；Android/iOS `1.3.396+` 通过独立 Native host contract 提供 Files/Download，并用 `system.describe` 的实际 operation 集逐项启用，缺失 handler、握手超时或 operation 不完整时对应能力 fail closed。`pickFiles()` 默认单文件；显式传入 `multiple: true` 时允许 Host 返回多个文件，实际返回数量由宿主 picker 决定。小黑盒域名流式下载暂不支持；Web 与 Browser Dev Host 仍未开放这些 primitive。
 - `withCredentials` 不再是支持的配置字段，也不会进入新 SDK、协议或 Host contract；旧 SDK 构建产物的 wire 字段仅由 Runtime 兼容忽略。Mobile 对官方 HTTPS 默认端口目标自动启用 Native Cookie，第三方关闭；应用可显式提供 `Cookie`、`Authorization` 等请求头。`Origin`、`Referer`、`User-Agent` 由 Host 接管；`Host`、分帧及逐跳请求头由传输层管理，不能由小程序设置。Web Host 使用浏览器 Fetch，无法发送显式 `Cookie` 等浏览器禁止的头，会返回 `REQUEST_UNSUPPORTED`；需要第三方 Cookie 会话时请在支持原始请求头的 Mobile/PC Host 验收。已启用的 Mobile 下载走无凭据 Native transfer；需要鉴权的下载请使用服务端签发的限时 URL。
 - 新 PC 不支持振动、分享菜单和截图分享；`navigation.openAppPage` 支持 `game_detail` 与 `mini_program`，用户/帖子详情会明确失败。调用平台相关能力时应处理 `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。
-- picker 必须来自可信用户手势；取消选择返回 `FILE_PICKER_CANCELLED`。`saveFile()` 只接受 `suggestedName`，不接受 `accept`；Mobile 上 Android 不提供 `saveFile()`，`pickFiles()` 选中的 Android 精确 SAF 文件仅支持只读（对这类目标请求 `mode: 'readwrite'` 返回 `FILE_ACCESS_DENIED`）。可用性由 Host 通过 `system.describe` 宣告的 operation 集协商，Runtime/H5 不按操作系统分支判定能力。
+- picker 必须来自可信用户手势；取消选择返回 `FILE_PICKER_CANCELLED`。`saveFile()` 只接受 `suggestedName`，不接受 `accept`；已适配 Android 客户端支持 `saveFile()` 和精确 SAF 文件的 `readwrite` 授权，需系统授予写入权限；这类目标写入不保证原子替换。可用性由 Host 通过 `system.describe` 宣告的 operation 集协商，Runtime/H5 不按操作系统分支判定能力。
 - `pickFiles()` / `pickDirectory()` 默认只读；`pickFiles()` 仅在显式传入 `multiple: true` 时允许 Host 返回多个文件。要写入或作为下载目标时显式请求 `mode: 'readwrite'`。
 - `file()` / `directory()` 只接受以 `/` 分隔的规范相对路径；拒绝绝对路径、空 segment、`.`、`..`、反斜杠、尾分隔符和控制字符。
 - `create()` 的 `recursive` / `exclusive` 默认都是 `false`；`exists()` 仅把缺失祖先、缺失目标或 kind mismatch 归一为 `false`，不会吞授权和 I/O 错误。
@@ -480,7 +483,9 @@ 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 的公开 `network.request()` 通过开发机的 HTTP 代理转发，因此 HTTPS `localhost` 指向开发机；代理不管理独立租约，不判断黑盒域名或改写应用层凭据。正式版本和 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` 在未登录、未绑定或远端不可用时仍启动 Browser Mock；真实手机/PC 入口须有有效启动票。CLI 自动从本地声明生成普通 `network` / `companion` 的临时批准缺口，不提供第二套权限开关。调试台顶部的“查看全部权限申请”在新标签页打开当前小程序的权限列表；尚未获批的 Network、Companion 单项提供“去申请”，直接打开对应申请表单。未获取到小程序 ID 时先选择小程序，再进入对应权限；已获批或审核中的权限不重复打开申请表单。真实 Host 每次打开会话确认临时权限，拒绝后仍可按线上批准基线打开；官方域名始终只认声明与线上批准的交集。真机 Dev Session 的公开 `network.request()` 通过开发机的 HTTP 代理转发，因此 HTTPS `localhost` 指向开发机；代理不管理独立租约，不判断黑盒域名或改写应用层凭据。正式版本和 Runtime 私有请求仍走 Host 网络。CLI 连续失联约 30 秒、期限或快照变化会销毁旧 Runtime，并清理临时 Companion 进程树；恢复后重新确认。手机验收统一从右上角二维码进入并选择可达的局域网网卡。调试会话、权限刷新与完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
+
+开发上下文按需读取并默认缓存 30 秒；重新打开真机会话时，过期缓存会刷新。权限刷新遇到临时故障或限流会按退避自动重试，恢复前暂停签发新启动票。真机按确认后的有效网络权限选择身份模式；身份上下文读取失败会提示重试，不会静默切换旧身份模式。
 
 远端提交前需要完成 CLI 登录和小程序绑定。完整的登录、绑定、预览、版本与发布流程见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)。
 
@@ -499,13 +504,13 @@ Host/Runtime 集成维护者请先阅读 [`@heybox/hb-sdk-runtime` README](../hb
 
 ## 版本名称与图片（0.8.2）
 
-在 `package.json#heybox` 配置 `name`、`icon`、`coverImages`。图片为项目内文件，icon 200×200、封面 1–5 张，单张不超过 10 MiB 和 4000 万像素。构建原样复制到版本产物，发布时才更新线上资料。全缺失配置可通过 bind/dev/deploy 从当前正式发布快照自动迁移；离线 build 不迁移。详见[版本资料与迁移指南](https://docs.xiaoheihe.cn/hb_sdk/guide/version-profile)。
+在 `package.json#heybox` 配置 `name`、`icon`、`coverImages`；`desc` 可配置不超过 200 个字符的小程序简介，字段规则见[项目配置](https://docs.xiaoheihe.cn/hb_sdk/guide/project-configuration)。图片为项目内文件，icon 200×200、封面 1–5 张，单张不超过 10 MiB 和 4000 万像素。构建原样复制到版本产物，发布时才更新线上资料。全缺失配置可通过 bind/dev/deploy 从当前正式发布快照自动迁移；离线 build 不迁移。详见[版本资料与迁移指南](https://docs.xiaoheihe.cn/hb_sdk/guide/version-profile)。
 
 ### 终端权限申请
 
 绑定小程序后，可用 `hb-sdk remote permission list` 查看原始审批、本地声明下的有效状态和最近申请；使用 `hb-sdk remote permission apply network --reason "访问业务接口" --domains "api.example.com"` 或 `hb-sdk remote permission apply companion --reason "运行桌面辅助应用"` 提交申请。两种命令均支持 `--json`，无需上传版本；获批后仍需声明 Manifest 权限。第一方已声明的受审批权限自动批准，原始审批为 `disabled` 不表示有效权限被禁用；CLI 会单独标明批准来源。完整语义见[终端权限申请](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions#终端权限申请)。
 
-### 工作区卡片（开发中）
+### 工作区卡片
 
 在支持该能力的 PC 游戏工作区展示小程序概览和操作。项目声明指定一个 Controller 文件；
 Controller 使用 `@heybox/hb-sdk/card-controller` 编写，普通页面使用根 SDK 的 `workspaceCards` 模块。
@@ -521,19 +526,15 @@ Controller 使用 `@heybox/hb-sdk/card-controller` 编写，普通页面使用
 小程序工坊开发者反馈统一进入现有私有客服工单。登录后只能查看自己的反馈，客服通过现有后台派单和回复。
 
 ```bash
-hb-sdk feedback --desc "调用接口时发生异常" --sdk-version 0.9.1-alpha.7 --platform ios --log ./error.log --screenshot ./error.png --app-id app123 --api hb.network.request
-hb-sdk feedback --desc "页面运行时出现崩溃" --sdk-version 0.9.1-alpha.7 --platform android --log ./error.log --screenshot ./error.png --json
+hb-sdk feedback --desc "调用接口时发生异常" --sdk-version 0.9.1 --platform ios --log ./error.log --screenshot ./error.png --app-id app123 --api hb.network.request
+hb-sdk feedback --desc "页面运行时出现崩溃" --sdk-version 0.9.1 --platform android --log ./error.log --screenshot ./error.png --json
 hb-sdk feedback list --json            # 先查看本人已有的小程序工坊工单
 hb-sdk feedback detail 9527 --json     # 查看内容和客服回复
 hb-sdk feedback reply 9527 --desc "补充复现步骤" --screenshot ./error.png --log "Error: retry failed" --json
 ```
 
-CLI 仅直接提交工单，不打开或输出反馈提交页面地址。新建反馈必须提供至少 5 个字符的问题描述、问题项目实际使用的 SDK 版本、问题发生的平台、非空报错日志和至少一张截图。使用 `--sdk-version` 填写有效版本号，不能用 CLI 自身版本代替；使用 `--platform` 指定 `ios`、`android`、`windows`、`macos`、`linux` 或 `web`，不会把执行 CLI 的电脑平台当作问题平台。日志统一通过 `--log` 提供，可传本地 `.log`、ZIP 日志包路径或日志文本，提交前请脱敏。缺少或填写无效时在登录、上传和提交前拒绝。AppID、关联 API、补充运行环境、复现步骤选填。追加回复只要求至少 5 个字符的补充描述，日志和附件可选，不重复要求原工单的 SDK 版本与平台。使用 `--scene` 补充复现步骤。`--log ./error.log` 上传非空 UTF-8 `.log` 文件；`--log "Error: request failed"` 将原始文本包装成 `feedback-text.log` 后上传。`--log ./logs.zip` 支持多个日志文件打包上传：只允许非空 UTF-8 `.log` 文件，最多 50 份，解压后合计不超过 20 MiB；不接受其他附件或嵌套压缩包。日志文件或压缩包单个不超过 10 MiB；日志全文不写入正文，正文只记录日志下载链接。完整正文最多 5000 字符；使用 `--screenshot` 传本地图片路径或已上传的 HTTP(S) 图片链接，可重复，图片和 GIF 合计最多 10 张，日志不占图片额度。普通图片单张不超过 20 MiB，GIF 单张不超过 10 MiB。暂不支持视频附件。图片沿用帮助与反馈的上传流程。
-
-提交时从现有分类接口查找“小程序工坊”分类（兼容原“小程序工坊开发者”和“小程序工坊开发者反馈”名称）及“开发中的常见问题”问题项，再调用 `/bbs/web/feedback/user/post`。分类未配置时拒绝提交；回复前先检查原工单属于本人小程序工坊且尚未关闭。所有本地附件先校验，再使用同一登录账号上传并提交，上传失败不会继续提交工单；附件不会单独作为上传命令对外提供。日志复用现有上传接口，正文使用接口返回的完整下载链接，不要求下载地址保留 `.log` 后缀。上线前需配置分类、问题项，并绑定客服组和派单优先级。提交结果包含原有工单 ID 和详情链接，不再创建独立 SDK 反馈记录。提交前会明确提示将创建私有反馈工单；使用提交时的同一小黑盒账号，在 App「设置 → 帮助与反馈 → 我的反馈」查看进展、客服回复或补充信息，也可打开返回的工单详情链接。`--json` 的成功结果包含 `message` 和 `follow_up` 说明，提交前提示输出到 stderr，不影响 stdout JSON 解析。
-
-反馈命令会显示检查文件、上传附件和提交工单的阶段提示，附件按顺序串行上传，全部上传成功后才提交工单；上传失败会提示具体文件和阶段，不继续提交。进度输出到 stderr，`--json` 的 stdout 只输出最终结果。不保存本地上传进度或提交缓存。提交超时、连接中断或响应不明确时，不自动查询或重试，请先到 App「帮助与反馈 → 我的反馈」核对结果，确认未成功后再重试。
+新建反馈须提供至少 5 个字符的问题描述、问题项目实际使用的 SDK 版本、问题发生的平台、非空日志和至少一张截图。`--sdk-version` 请填写项目版本；`--platform` 支持 `ios`、`android`、`windows`、`macos`、`linux` 或 `web`。
 
-列表支持 `--offset` 和 `--limit`（最多 50 条），详情和回复只允许访问当前登录账号在小程序工坊分类 `71` 下的工单。回复复用原工单，不占新建额度；已解决或关闭的工单不能继续回复。新能力需要后端支持范围隔离；服务未更新时会明确报错，不回退为读取全部工单。
+`--log` 支持 `.log`、ZIP 日志包或日志文本；`--screenshot` 支持本地图片、GIF 或已上传图片链接。日志请先脱敏。附件限制、分页与完整参数见[反馈常见问题](https://docs.xiaoheihe.cn/hb_sdk/guide/faq#能否直接用-cli-提交反馈)。
 
-新建前先用 `feedback list` 查看已有工单，必要时用 `detail` 确认是否为同一问题；同一问题优先 `reply`。CLI 不会自动进行语义查重或合并，不能确认时由用户判断。
+使用提交时的同一账号，在 App「设置 → 帮助与反馈 → 我的反馈」或 CLI 中跟进。同一问题优先回复已有工单；已解决或关闭的工单不能继续回复。提交超时或结果不明确时，先核对是否成功，再决定是否重试，避免重复提交。

package/dist/cli-chunks/{build-mIRvG3a8.cjs → build-D_WFX7k0.cjs}

@@ -1,14 +1,14 @@
 'use strict';
 
-var runtimeGate = require('./runtime-gate-B0YPKxEd.cjs');
+var runtimeGate = require('./runtime-gate-DwBSYQOE.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-CzhGcDRj.cjs');
-var index = require('./index-MMLoNdeZ.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-Dx1msYpN.cjs');
+var index = require('./index-HprlZ2zE.cjs');
 require('node:crypto');
 require('node:zlib');
-var projectVite = require('./project-vite-Si5Tyi7Q.cjs');
+var projectVite = require('./project-vite-B81ymoLT.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-B1aYSptt.cjs');
+require('./version-0WiS_IOu.cjs');
 require('node:async_hooks');
 require('readline');
 require('tty');

package/dist/cli-chunks/{context-0uq4_H2M.cjs → context-9AzsNffz.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-CzhGcDRj.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-Dx1msYpN.cjs');
 var fs$1 = require('node:fs');
 var sharp = require('sharp');
-var index = require('./index-MMLoNdeZ.cjs');
+var index = require('./index-HprlZ2zE.cjs');
 
 async function inspectBasicInfoImage(bytes, sourcePath, kind) {
     const inspected = await inspectDecodedBasicInfoImage(bytes, kind);
@@ -376,13 +376,17 @@ function createBrowserDevPermissionState(context) {
         }
         : cloneDefaultPermissionState();
 }
-/** Mobile Dev Session 只接受线上远端权限快照，不读取 Browser 本地权限状态。 */
+/** Mobile Dev Session 使用本地声明与平台基线，不读取 Browser 模拟权限状态。 */
 function createMobileDevSessionRuntimePermissions(context) {
     if (context.source !== 'remote') {
         return { schema_version: 1, entries: [] };
     }
-    const state = createBrowserDevPermissionState({ ...context, localDevGrant: undefined });
-    return createDevRuntimePermissions(context.runtimePermissions, state, state.networkRequest.useOfficialDomain);
+    // 历史内部调用没有本地声明，沿用旧快照适配；新 CLI 始终显式提供声明（可为空）。
+    if (context.declaredPermissions === undefined) {
+        const state = createBrowserDevPermissionState(context);
+        return createDevRuntimePermissions(context.runtimePermissions, state, state.networkRequest.useOfficialDomain);
+    }
+    return runtimePermissionEnv.composeLocalDevRuntimePermissions({ declaredPermissions: context.declaredPermissions, runtimePermissions: context.runtimePermissions }).runtimePermissions;
 }
 function cloneDefaultPermissionState() {
     return {
@@ -623,6 +627,7 @@ async function createLocalDevLaunchToken(options, runtime = {}) {
     const api = await resolveRemoteApiClient(options, runtime);
     return api.createLocalDevLaunchToken({
         mini_program_id: miniProgramId,
+        ...(options.developmentSnapshot ? { development_snapshot: options.developmentSnapshot } : {}),
         ...(options.companionManifestSha256
             ? { companion_manifest_sha256: options.companionManifestSha256 }
             : {}),

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