@heybox/hb-sdk 0.9.1-alpha.1 → 0.9.1-alpha.10

package/CHANGELOG.md

@@ -2,6 +2,118 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。
 
+## 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
+
+### 新增能力
+
+- 反馈新建与追加回复支持上传本地图片和 GIF，图片和 GIF 合计最多 10 张，日志不占图片额度；普通图片单张 20 MiB、GIF 单张 10 MiB，暂不支持视频附件。
+- 新建和追加回复统一通过 `--log` 提供日志：支持本地 `.log`、ZIP 日志包，字符串自动包装成 `.log` 文件；单份上传最多 10 MiB，ZIP 内最多 50 份非空 UTF-8 `.log`，解压后合计最多 20 MiB，日志独立于图片额度，正文仅保留上传返回的日志下载链接。
+- 新建反馈强制校验至少 5 个字符的问题描述、问题项目的 SDK 版本、运行平台、非空日志和至少一张截图；追加回复的描述同步至少 5 个字符。
+- 移除重复的 `feedback submit` 子命令，统一使用 `hb-sdk feedback` 提交；工单列表保留分页以查看超过五条的历史记录。
+- 反馈命令仅直接提交工单，不再打开或输出反馈提交页面地址；缺少问题描述时提示补充。
+
+- 反馈提交与追加回复增加检查、上传和提交阶段提示，进度不混入 JSON 结果；附件按顺序串行上传，全部成功后才提交工单；结果不明确时提示在 App 核对，不自动重试，也不保存本地恢复缓存。
+
+### 问题修复
+
+- 修复反馈附件上传授权请求缺少表单类型，导致服务端无法读取上传范围并返回“参数错误:1000”的问题。
+- 反馈日志上传前校验 ZIP 目录、结束记录和 CRC，拒绝损坏或未写完的压缩包；修复普通日志末尾残缺 UTF-8 字符被漏检的问题。
+
+### 文档与工具
+
+- 移除开放平台与文档中的反馈页面直达入口，保留 App 帮助与反馈入口及 CLI 提交说明。
+
+## 0.9.1-alpha.8 - 2026-10-16
+
+### 问题修复
+
+- 修复第一方小程序已声明权限在 CLI 查询、本地调试和发布检查中被误判为不可用的问题。
+- 权限查询区分原始审批与有效权限，并展示第一方自动批准来源。
+
+## 0.9.1-alpha.7 - 2026-10-16
+
+### 新增能力
+
+- 新增 `network.upload()`，使用受控文件发送 raw PUT/POST 或 multipart 上传，支持查询参数、请求头、进度、取消与响应状态校验。
+
+### 问题修复
+
+- 文件和目录选择不再受普通请求超时限制，允许用户完成较长时间的系统选择操作。
+- 补充上传、文件系统与下载验收，并按实际平台能力处理大小边界和多选限制。
+
+## 0.9.1-alpha.6 - 2026-10-15
+
+### 新增能力
+
+- 新增 `hb-sdk feedback`，可打开小程序工坊反馈页面，或提交问题、复现步骤、日志与截图链接，进入现有私有客服工单。
+- 新增 `hb-sdk feedback list`、`detail` 和 `reply`，查看本人小程序工坊工单并向未关闭的原工单追加信息。
+
+### 文档与工具
+
+- 提交前后明确说明私有工单性质、编号与详情链接，并提示在 App「设置 → 帮助与反馈 → 我的反馈」跟进。
+- 智能体新建前先查看已有工单，确认同一问题后优先补充；服务端未确认工单隔离时拒绝读取和回复。
+- 补充开发常见问题及反馈入口。
+
+## 0.9.1-alpha.5
+
+- 工作区卡片 Controller v2 支持在本地开发入口调试，并校验控制器依赖、权限及卡片参数。
+- 旧 Host 不支持工作区卡片时，能力错误保留原始错误数据和原因，便于诊断。
+
+## 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
+
+### 问题修复
+
+- 修复设置 `--service-tag` 后提交小程序时文件上传失败的问题。
+
+## 0.9.1-alpha.2
+
+### 文档与工具
+
+- 浏览器调试台的沙箱面板统一为工作台视觉：设备选择、目录路径与文件列表改用主题 Token、图标按钮和文件类型图标，空目录与加载状态补充对应图示。
+
 ## 0.9.1-alpha.1
 
 ### 行为调整
@@ -123,7 +235,7 @@
 
 > 影响级别：常规
 > 开发者动作：升级至 `0.9.0-alpha.0` 并重新运行 `hb-sdk dev`；运行期间在后台调整权限后，请重启 CLI 同步。
-> 兼容范围：公开 SDK API 不变；调整本地真实客户端调试的详情读取与启动票可用条件。
+> 兼容范围：既有公开 SDK API 保持兼容；新增工作区卡片入口，并调整本地真实客户端调试的详情读取与启动票可用条件。
 
 ### 行为调整
 
@@ -136,6 +248,9 @@
 - 修复声明连续变化时，旧详情、产物摘要或启动票覆盖最新调试状态的问题。
 - 修复详情校验失败后仍能通过本地启动入口获取续签票据的问题。
 
+- 新增 `@heybox/hb-sdk/card-controller` 公开入口，用于声明工作区卡片 Controller 和卡片视图。
+- 新增 `workspaceCards.requestRefresh()`、`getLaunchContext()` 和 `onLaunchContextChange()`，用于在支持工作区卡片的桌面 Host 中刷新卡片和读取启动上下文。
+
 ## 0.8.5 - 2026-10-02
 
 > 影响级别：必须操作
@@ -320,7 +435,6 @@
 
 - 补充游戏详情页资源位申请规则、图标制作规范和申请流程说明。
 
-
 ## 0.8.2 - 2026-09-21
 
 > 摘要：版本名称与图片改由项目维护，新增 Steam 账号授权，并调整部署与用户数据边界。
@@ -539,6 +653,7 @@
 
 - 目标平台声明统一迁移到 `package.json#heybox.platforms`；`miniappManifest()` 恢复无参调用，并在构建时将该声明写入 `dist/manifest.json`。
 - `hb-sdk dev`、`hb-sdk build` 和普通 `hb-sdk remote deploy` 会拒绝缺失或非法的平台声明；build/deploy 也会拒绝与项目配置不一致的 Manifest。已有项目升级时需把原 Vite 参数中的 `platforms` 移入 `package.json#heybox`。
+
 ## 0.8.1-alpha.2
 
 - 新增 `environment.getInfo()` 与 `environment.getInfoSync()`，用于读取运行模式、小黑盒 App 版本、canonical 小程序 ID/版本、操作系统和 SDK 版本的冻结快照。

package/README.md

@@ -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` 和 `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` 权限；`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` 生命周期事件只是握手成功瞬间派发、不会重放的边沿通知，不能用来判断当前状态。
 
@@ -181,7 +181,9 @@ console.log(info.sdk.version);
 
 `resizable` 只约束**用户手动拖拽**；**位置不开放**：开发者不能声明或设置窗口位置，位置由用户拖拽产生并由宿主按小程序身份本地记忆。完整语义见[窗口尺寸与可缩放性](https://docs.xiaoheihe.cn/hb_sdk/guide/window-size)。
 
-## 文件与下载
+## 文件与传输
+
+`network.upload()` 接收一个可读 `FileHandle`，由 Host 直接流式上传到开发者指定 URL。raw 支持 PUT（默认）/POST，multipart 固定 POST 并可携带字符串字段；支持进度、取消、空闲超时、可选大小限制和标准 HTTP 响应。文件字节不经过 iframe，上传期间应保持源文件不变；首版不自动重试、分片、续传或复制快照。PC、Android、iOS、OHOS 按真实 Host primitive 启用，旧 Host 明确拒绝。完整示例见[文件能力与沙箱](https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox)。
 
 `files` 提供当前小程序私有 sandbox 和由用户选择授予的外部 File/Directory；
 `network.download()` 将 GET 响应直接流式写入受控目标，下载字节不经过 iframe bridge。
@@ -215,7 +217,8 @@ console.log(await downloaded.readText());
 不认识新 method 时返回 `METHOD_NOT_FOUND`。
 新 PC 的下载字节留在插件 Node 并直接原子落盘，不提供 Blob 或内存假实现。
 
-外部 picker 必须从可信用户操作触发。`files.saveFile({ suggestedName })` 返回精确 File 授权，
+外部 picker 必须从可信用户操作触发。`files.pickFiles()`、`files.pickDirectory()` 和
+`files.saveFile()` 的选择等待不设固定超时，不受 SDK 普通请求超时配置影响；确认、取消或 SDK / Runtime 会话结束后才结束操作。`files.saveFile({ suggestedName })` 返回精确 File 授权，
 不会额外保留 Directory 授权；新 PC 当前先让用户选择保存目录，再以 `suggestedName` 独占创建空文件，
 同名文件返回 `FILE_ALREADY_EXISTS`。V1 不接受 `accept`，只有 `pickFiles()` 支持扩展名过滤。完整路径、
 创建、存在性和下载语义见[快速开始](https://docs.xiaoheihe.cn/hb_sdk/guide/quick-start#文件与下载)。
@@ -326,9 +329,11 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | `storage`    | 读写当前小程序的隔离存储                        |
 | `files`      | 声明受控 sandbox 与用户选择授权的文件、目录操作 |
 | `cloud`      | 使用小程序云端排行榜                            |
-| `network`    | 发起经过平台授权的网络请求，并声明受控流式下载  |
+| `network`    | 发起经过平台授权的网络请求及受控文件传输  |
 | `companion`  | 准备、启动并控制当前版本审核过的桌面辅助应用    |
 
+`share.screenshot()` 会在截图区域底部添加当前小程序名称的品牌搜索胶囊及灰色「小黑盒工坊小程序」。请在目标区域底部预留至少 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/)。
 
 ## 关键约束
@@ -500,4 +505,37 @@ Host/Runtime 集成维护者请先阅读 [`@heybox/hb-sdk-runtime` README](../hb
 
 ### 终端权限申请
 
-绑定小程序后，可用 `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 权限。
+绑定小程序后，可用 `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` 模块。
+浏览器调试页只提供登录、绑定、启动和状态，不渲染卡片，须在真实 PC 验收。
+
+完整配置、三个示例、页面协作、调试发布与排障见 [工作区卡片指南](https://docs.xiaoheihe.cn/hb_sdk/guide/workspace-cards)。
+
+卡片合同只在开发构建时依赖私有 `@ai-desktop/view-contract`，发布 JS 与声明已封装所需代码和类型。
+用户安装 hb-sdk 不需要该私有包；`check:bundled-contract` 阻止未内联引用进入发布制品。
+
+## 开发反馈
+
+小程序工坊开发者反馈统一进入现有私有客服工单。登录后只能查看自己的反馈，客服通过现有后台派单和回复。
+
+```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 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「帮助与反馈 → 我的反馈」核对结果，确认未成功后再重试。
+
+列表支持 `--offset` 和 `--limit`（最多 50 条），详情和回复只允许访问当前登录账号在小程序工坊分类 `71` 下的工单。回复复用原工单，不占新建额度；已解决或关闭的工单不能继续回复。新能力需要后端支持范围隔离；服务未更新时会明确报错，不回退为读取全部工单。
+
+新建前先用 `feedback list` 查看已有工单，必要时用 `detail` 确认是否为同一问题；同一问题优先 `reply`。CLI 不会自动进行语义查重或合并，不能确认时由用户判断。

package/dist/card-controller.cjs.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/** 小程序固定受管动作入口。 */
+const WORKSPACE_CARD_COMMANDS = {
+    invoke: 'ai-desktop.heybox-user-miniprogram.workspace-cards.invoke',
+    openMiniProgram: 'ai-desktop.heybox-user-miniprogram.workspace-cards.open-mini-program',
+};
+
+const VIEW_SCHEMA_VERSION = 1;
+function compact(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+}
+function vstack(children, options = {}) {
+  return compact({ type: "vstack", children, ...options });
+}
+function hstack(children, options = {}) {
+  return compact({ type: "hstack", children, ...options });
+}
+function zstack(children, options = {}) {
+  return compact({ type: "zstack", children, ...options });
+}
+function grid(columns, children, options = {}) {
+  return compact({ type: "grid", columns, children, ...options });
+}
+function carousel(id, label, children, options = {}) {
+  return compact({ type: "carousel", id, label, children, ...options });
+}
+function group(children, options = {}) {
+  return compact({ type: "group", children, ...options });
+}
+function spacer(options = {}) {
+  return compact({ type: "spacer", ...options });
+}
+function text(value, options = {}) {
+  return compact({ type: "text", value, ...options });
+}
+function image(src, options = {}) {
+  return compact({ type: "image", src, ...options });
+}
+function icon(name, options = {}) {
+  return compact({ type: "icon", name, ...options });
+}
+function fields(items, options = {}) {
+  return compact({ type: "fields", items, ...options });
+}
+function list(items, options = {}) {
+  return compact({ type: "list", items, ...options });
+}
+function badge(value, options = {}) {
+  return compact({ type: "badge", text: value, ...options });
+}
+function divider(options = {}) {
+  return compact({ type: "divider", ...options });
+}
+function button(value, options = {}) {
+  return compact({ type: "button", text: value, ...options });
+}
+function tabs(id, items, options = {}) {
+  return compact({ type: "tabs", id, items, ...options });
+}
+function textField(id, label, options = {}) {
+  return compact({ type: "textField", id, label, ...options });
+}
+function toggle(id, label, checked, options = {}) {
+  return compact({ type: "switch", id, label, checked, ...options });
+}
+function expandable(id, children, options) {
+  return { type: "expandable", id, children, ...options };
+}
+function renderer(id, rendererViewId, options = {}) {
+  return compact({ type: "renderer", id, rendererViewId, ...options });
+}
+function frame(id, frameId, options = {}) {
+  return compact({ type: "frame", id, frameId, ...options });
+}
+function meter(value, options = {}) {
+  return compact({ type: "meter", value, ...options });
+}
+function radialProgress(value, label, options = {}) {
+  return compact({ type: "radialProgress", value, label, ...options });
+}
+function barChart(label, items, options = {}) {
+  return compact({ type: "barChart", label, items, ...options });
+}
+function region(id, status, nodes = [], options = {}) {
+  return compact({ id, status, nodes, ...options });
+}
+function viewDocument(regions, options = {}) {
+  return compact({ schema: VIEW_SCHEMA_VERSION, regions: [...regions], ...options });
+}
+
+function defineCard(definition) { return definition; }
+const actionInput = {
+    string: (options = {}) => ({ type: 'string', ...options }),
+    number: () => ({ type: 'number' }),
+    boolean: () => ({ type: 'boolean' }),
+    array: (items, options = {}) => ({ type: 'array', items, ...options }),
+    object: (properties) => ({
+        type: 'object', properties, required: Object.keys(properties), additionalProperties: false,
+    }),
+};
+function defineAction(definition) {
+    let actionId;
+    const pending = [];
+    const handle = ((input) => {
+        const value = invoke(actionId ?? '__unbound__', input);
+        if (!actionId)
+            pending.push(value);
+        return value;
+    });
+    handle.kind = 'invoke';
+    handle.input = definition.input;
+    handle.run = definition.run;
+    Object.defineProperty(handle, 'bindActionId', { value: (id) => {
+            if (actionId && actionId !== id)
+                throw new Error('Workspace Card action handle 不能绑定多个 ID');
+            actionId = id;
+            for (const value of pending)
+                value.input.actionId = id;
+            pending.length = 0;
+        } });
+    return handle;
+}
+function defineOpenMiniProgramAction(options = {}) {
+    let actionId;
+    const pending = [];
+    const handle = ((input) => {
+        const value = openMiniProgram(actionId ?? '__unbound__', input);
+        if (!actionId)
+            pending.push(value);
+        return value;
+    });
+    handle.kind = 'openMiniProgram';
+    handle.input = options.input;
+    Object.defineProperty(handle, 'bindActionId', { value: (id) => {
+            if (actionId && actionId !== id)
+                throw new Error('Workspace Card action handle 不能绑定多个 ID');
+            actionId = id;
+            for (const value of pending)
+                value.input.actionId = id;
+            pending.length = 0;
+        } });
+    return handle;
+}
+function defineWorkspaceCardsController(controller) {
+    for (const [id, action] of Object.entries(controller.actions ?? {}))
+        action.bindActionId?.(id);
+    return controller;
+}
+/** 定义控制器；构建器和 Host 分别验证静态 action 表。 */
+function defineWorkspaceCardController(controller) { return controller; }
+/** 生成固定受管 invoke 入口；身份由 Host 根据真实卡片绑定。 */
+function invoke(actionId, params) {
+    return { commandId: WORKSPACE_CARD_COMMANDS.invoke, input: { actionId, ...(params === undefined ? {} : { params }) } };
+}
+/** 只允许打开当前小程序。 */
+function openMiniProgram(actionId, params) {
+    return { commandId: WORKSPACE_CARD_COMMANDS.openMiniProgram, input: { actionId, ...(params === undefined ? {} : { params }) } };
+}
+
+exports.actionInput = actionInput;
+exports.badge = badge;
+exports.barChart = barChart;
+exports.button = button;
+exports.carousel = carousel;
+exports.defineAction = defineAction;
+exports.defineCard = defineCard;
+exports.defineOpenMiniProgramAction = defineOpenMiniProgramAction;
+exports.defineWorkspaceCardController = defineWorkspaceCardController;
+exports.defineWorkspaceCardsController = defineWorkspaceCardsController;
+exports.divider = divider;
+exports.expandable = expandable;
+exports.fields = fields;
+exports.frame = frame;
+exports.grid = grid;
+exports.group = group;
+exports.hstack = hstack;
+exports.icon = icon;
+exports.image = image;
+exports.invoke = invoke;
+exports.list = list;
+exports.meter = meter;
+exports.openMiniProgram = openMiniProgram;
+exports.radialProgress = radialProgress;
+exports.region = region;
+exports.renderer = renderer;
+exports.spacer = spacer;
+exports.tabs = tabs;
+exports.text = text;
+exports.textField = textField;
+exports.toggle = toggle;
+exports.viewDocument = viewDocument;
+exports.vstack = vstack;
+exports.zstack = zstack;

package/dist/card-controller.esm.js

@@ -0,0 +1,159 @@
+/** 小程序固定受管动作入口。 */
+const WORKSPACE_CARD_COMMANDS = {
+    invoke: 'ai-desktop.heybox-user-miniprogram.workspace-cards.invoke',
+    openMiniProgram: 'ai-desktop.heybox-user-miniprogram.workspace-cards.open-mini-program',
+};
+
+const VIEW_SCHEMA_VERSION = 1;
+function compact(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+}
+function vstack(children, options = {}) {
+  return compact({ type: "vstack", children, ...options });
+}
+function hstack(children, options = {}) {
+  return compact({ type: "hstack", children, ...options });
+}
+function zstack(children, options = {}) {
+  return compact({ type: "zstack", children, ...options });
+}
+function grid(columns, children, options = {}) {
+  return compact({ type: "grid", columns, children, ...options });
+}
+function carousel(id, label, children, options = {}) {
+  return compact({ type: "carousel", id, label, children, ...options });
+}
+function group(children, options = {}) {
+  return compact({ type: "group", children, ...options });
+}
+function spacer(options = {}) {
+  return compact({ type: "spacer", ...options });
+}
+function text(value, options = {}) {
+  return compact({ type: "text", value, ...options });
+}
+function image(src, options = {}) {
+  return compact({ type: "image", src, ...options });
+}
+function icon(name, options = {}) {
+  return compact({ type: "icon", name, ...options });
+}
+function fields(items, options = {}) {
+  return compact({ type: "fields", items, ...options });
+}
+function list(items, options = {}) {
+  return compact({ type: "list", items, ...options });
+}
+function badge(value, options = {}) {
+  return compact({ type: "badge", text: value, ...options });
+}
+function divider(options = {}) {
+  return compact({ type: "divider", ...options });
+}
+function button(value, options = {}) {
+  return compact({ type: "button", text: value, ...options });
+}
+function tabs(id, items, options = {}) {
+  return compact({ type: "tabs", id, items, ...options });
+}
+function textField(id, label, options = {}) {
+  return compact({ type: "textField", id, label, ...options });
+}
+function toggle(id, label, checked, options = {}) {
+  return compact({ type: "switch", id, label, checked, ...options });
+}
+function expandable(id, children, options) {
+  return { type: "expandable", id, children, ...options };
+}
+function renderer(id, rendererViewId, options = {}) {
+  return compact({ type: "renderer", id, rendererViewId, ...options });
+}
+function frame(id, frameId, options = {}) {
+  return compact({ type: "frame", id, frameId, ...options });
+}
+function meter(value, options = {}) {
+  return compact({ type: "meter", value, ...options });
+}
+function radialProgress(value, label, options = {}) {
+  return compact({ type: "radialProgress", value, label, ...options });
+}
+function barChart(label, items, options = {}) {
+  return compact({ type: "barChart", label, items, ...options });
+}
+function region(id, status, nodes = [], options = {}) {
+  return compact({ id, status, nodes, ...options });
+}
+function viewDocument(regions, options = {}) {
+  return compact({ schema: VIEW_SCHEMA_VERSION, regions: [...regions], ...options });
+}
+
+function defineCard(definition) { return definition; }
+const actionInput = {
+    string: (options = {}) => ({ type: 'string', ...options }),
+    number: () => ({ type: 'number' }),
+    boolean: () => ({ type: 'boolean' }),
+    array: (items, options = {}) => ({ type: 'array', items, ...options }),
+    object: (properties) => ({
+        type: 'object', properties, required: Object.keys(properties), additionalProperties: false,
+    }),
+};
+function defineAction(definition) {
+    let actionId;
+    const pending = [];
+    const handle = ((input) => {
+        const value = invoke(actionId ?? '__unbound__', input);
+        if (!actionId)
+            pending.push(value);
+        return value;
+    });
+    handle.kind = 'invoke';
+    handle.input = definition.input;
+    handle.run = definition.run;
+    Object.defineProperty(handle, 'bindActionId', { value: (id) => {
+            if (actionId && actionId !== id)
+                throw new Error('Workspace Card action handle 不能绑定多个 ID');
+            actionId = id;
+            for (const value of pending)
+                value.input.actionId = id;
+            pending.length = 0;
+        } });
+    return handle;
+}
+function defineOpenMiniProgramAction(options = {}) {
+    let actionId;
+    const pending = [];
+    const handle = ((input) => {
+        const value = openMiniProgram(actionId ?? '__unbound__', input);
+        if (!actionId)
+            pending.push(value);
+        return value;
+    });
+    handle.kind = 'openMiniProgram';
+    handle.input = options.input;
+    Object.defineProperty(handle, 'bindActionId', { value: (id) => {
+            if (actionId && actionId !== id)
+                throw new Error('Workspace Card action handle 不能绑定多个 ID');
+            actionId = id;
+            for (const value of pending)
+                value.input.actionId = id;
+            pending.length = 0;
+        } });
+    return handle;
+}
+function defineWorkspaceCardsController(controller) {
+    for (const [id, action] of Object.entries(controller.actions ?? {}))
+        action.bindActionId?.(id);
+    return controller;
+}
+/** 定义控制器；构建器和 Host 分别验证静态 action 表。 */
+function defineWorkspaceCardController(controller) { return controller; }
+/** 生成固定受管 invoke 入口；身份由 Host 根据真实卡片绑定。 */
+function invoke(actionId, params) {
+    return { commandId: WORKSPACE_CARD_COMMANDS.invoke, input: { actionId, ...(params === undefined ? {} : { params }) } };
+}
+/** 只允许打开当前小程序。 */
+function openMiniProgram(actionId, params) {
+    return { commandId: WORKSPACE_CARD_COMMANDS.openMiniProgram, input: { actionId, ...(params === undefined ? {} : { params }) } };
+}
+
+export { actionInput, badge, barChart, button, carousel, defineAction, defineCard, defineOpenMiniProgramAction, defineWorkspaceCardController, defineWorkspaceCardsController, divider, expandable, fields, frame, grid, group, hstack, icon, image, invoke, list, meter, openMiniProgram, radialProgress, region, renderer, spacer, tabs, text, textField, toggle, viewDocument, vstack, zstack };

package/dist/cli-chunks/_commonjs-dynamic-modules-DUamuDzp.cjs

@@ -0,0 +1,7 @@
+'use strict';
+
+function commonjsRequire(path) {
+	throw new Error('Could not dynamically require "' + path + '". Please configure the dynamicRequireTargets or/and ignoreDynamicRequires option of @rollup/plugin-commonjs appropriately for this require call to work.');
+}
+
+exports.commonjsRequire = commonjsRequire;

package/dist/cli-chunks/{build-C5jFqooo.cjs → build-BK0MOduC.cjs}

@@ -1,19 +1,23 @@
 'use strict';
 
+var runtimeGate = require('./runtime-gate-wKj1l5xM.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-Bg7f-uj8.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-DBra_0-U.cjs');
+var index = require('./index-BWRDIX1T.cjs');
 require('node:crypto');
 require('node:zlib');
-var runtimeGate = require('./runtime-gate-CKGRK3wC.cjs');
-var index = require('./index-B0eNYO7I.cjs');
-var projectVite = require('./project-vite-BA_CFVq_.cjs');
-require('./version-rxh3jOOI.cjs');
-require('node:async_hooks');
+var projectVite = require('./project-vite-DD3bmbqm.cjs');
 require('node:module');
+require('node:url');
+require('./_commonjs-dynamic-modules-DUamuDzp.cjs');
+require('fs');
 require('path');
 require('os');
+require('inspector');
+require('./version-BF4JQQCU.cjs');
+require('node:async_hooks');
 require('readline');
 require('tty');
 require('assert');
@@ -21,7 +25,7 @@ require('events');
 require('stream');
 require('buffer');
 require('util');
-require('node:url');
+require('constants');
 
 function areStringArraysEqual(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);
@@ -103,6 +107,10 @@ async function validateBuildOutput(projectRoot, logger, declaredPlatforms, decla
         logger.warn('dist/manifest.json 包含 BOM，已自动剥离');
     }
     const validated = runtimePermissionEnv.validateMiniappManifestForDeploy(manifest);
+    if (validated.workspaceCards) {
+        runtimeGate.verifyWorkspaceCardsSnapshot({ ...validated, bindAppIds: validated.bindAppIds ?? [], workspaceCards: validated.workspaceCards });
+        runtimeGate.verifyWorkspaceCardArtifacts(distDir, validated.workspaceCards);
+    }
     const { platforms, sdkVersion, version, permissions, window } = validated;
     const bindAppIds = validated.bindAppIds ?? [];
     if (validated.category !== declaredCategory) {