@heybox/hb-sdk 0.8.0-alpha.10 → 0.8.0-alpha.13

package/skill/references/recipes.md

@@ -135,15 +135,14 @@ try {
 
 | Host             | `files.sandbox` | 外部 picker | `network.download()` |
 | ---------------- | --------------- | ----------- | -------------------- |
-| 旧版 PC          | 不支持          | 不支持      | 不支持               |
+| 新 PC            | 支持            | 支持        | 支持                 |
 | Mobile           | 不支持          | 不支持      | 不支持               |
 | Web              | 不支持          | 不支持      | 不支持               |
 | Browser Dev Host | 不支持          | 不支持      | 不支持               |
 
 当前 Runtime 认识但 Host 未实现时返回 `METHOD_FORBIDDEN`；旧 Runtime 收到新 method 时返回
-`METHOD_NOT_FOUND`。此前曾实现面向旧版小黑盒 PC 的 Host 适配；由于新版 PC 即将启用，该适配
-不再发布。文件/下载 API、协议和 Runtime 体系保持不变，后续直接按照新版 PC Host 架构接入。
-当前任何 Host 都不提供 Blob 或内存假下载。
+`METHOD_NOT_FOUND`。新 PC V1 注入真实文件与流式下载 primitive；其他当前 Host 未实现时仍不
+提供 throwing stub、Blob 或内存假下载。
 
 ### 路径与创建
 
@@ -169,9 +168,10 @@ async function saveFromUserAction(text: string) {
 }
 ```
 
-`saveFile()` 打开系统保存对话框并返回精确 File 授权，不会同时创建或保留 Directory
-授权。V1 不接受 `accept`；扩展名过滤只属于 `pickFiles({ accept: ['.json'] })`。外部授权仅在当前
-Runtime session 有效。
+`saveFile()` 请求 Host 返回精确 File 授权，不会同时创建或保留 Directory 授权。新 PC 当前先让
+用户选择保存目录，再以 `suggestedName` 独占创建空文件；同名文件抛出 `FILE_ALREADY_EXISTS`，
+不会静默覆盖。V1 不接受 `accept`；扩展名过滤只属于 `pickFiles({ accept: ['.json'] })`。外部授权
+仅在当前 Runtime session 有效。
 
 `pickFiles()` / `pickDirectory()` 默认返回 `mode: 'read'` 的授权；只有显式传入
 `multiple: true` 时，`pickFiles()` 才允许 Host 返回多个文件。需要修改文件、在所选目录中创建

package/skill/references/safety-boundaries.md

@@ -22,7 +22,9 @@
 - 公开 `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`，文件上传请走专用上传能力。
-- 当前 Host（包括旧版 PC、Mobile、Web 与 Browser Dev Host）均未开放 `files` / `network.download()`；新版 PC 将按同一公开合同重新接入，期间不提供内存或 Blob 假实现。
+- 新 PC 开放持久 sandbox、单文件/目录 picker、精确 File 保存与公网 `network.download()`；多选和小黑盒域名流式下载暂不支持。Mobile、Web 与 Browser Dev Host 仍未开放这些 primitive。
+- 新 PC 支持 `network.request`，但会忽略 `withCredentials`；它不改变请求路由或凭据行为。其他平台继续遵循各自的 Host 语义。
+- 新 PC 不支持振动、分享菜单和截图分享；`navigation.openAppPage` 仅支持 `game_detail`，用户/帖子详情会明确失败。调用平台相关能力时应处理 `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。
 - picker 必须来自可信用户手势；取消选择返回 `FILE_PICKER_CANCELLED`。`saveFile()` 只接受 `suggestedName`，不接受 `accept`。
 - `pickFiles()` / `pickDirectory()` 默认只读；`pickFiles()` 仅在显式传入 `multiple: true` 时允许 Host 返回多个文件。要写入或作为下载目标时显式请求 `mode: 'readwrite'`。
 - `file()` / `directory()` 只接受以 `/` 分隔的规范相对路径；拒绝绝对路径、空 segment、`.`、`..`、反斜杠、尾分隔符和控制字符。
@@ -35,6 +37,10 @@
 - 仅当当前版本声明且平台已批准 `network` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
 - 构建必须启用 `miniappManifest({ platforms })` 并显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
 
+私有 Page Channel 适配没有修改 `@heybox/hb-sdk` 公开 API 或 iframe wire；本次 files/download
+Runtime 能力随 `0.8.0-alpha.11` release family 发布，部署 detail 前必须保证
+`@heybox/hb-sdk`、`@heybox/hb-sdk-runtime` 与 `@heybox/hb-sdk-protocol` 三个 package 均可解析。
+
 ## Agent rules
 
 - Do not instruct mini-program code to read, extract, forward, store, or depend on token, cookie, phone number, or private credentials.

package/skill/skill.json

@@ -1,16 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.0-alpha.10+skill.4d468f0653d9",
+  "skillVersion": "0.8.0-alpha.13+skill.6ba4b858af29",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.0-alpha.10",
-    "compatibility": "0.8.0-alpha.10"
+    "version": "0.8.0-alpha.13",
+    "compatibility": "0.8.0-alpha.13"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.0-alpha.10",
+    "version": "0.8.0-alpha.13",
     "path": "skill"
   },
-  "integrity": "sha256-4d468f0653d9f6eac9578d47d85b955c01e84dd38b91d123a2b832e60f50b34c"
+  "integrity": "sha256-6ba4b858af29c8da30d6b726110abd32b6fd1863bdd0d32b360055436f9254d3"
 }

package/types/core/mini-dev-console.d.ts

@@ -0,0 +1,36 @@
+/**
+ * iframe 与调试台页面的开发期 console 捕获转发。
+ *
+ * 双条件门控（iframe 转发）：
+ * 1. 构建期：`hb-sdk dev`（vite serve）注入 `__HB_SDK_DEV_LOGGING__`；`hb-sdk build` /
+ *    `vite build`（生产）永不注入或替换为 `false`，本模块被死代码消除。
+ * 2. 运行期：仅在 `window.name` 为 `__hb_sdk_mini_dev__` 的调试 iframe 中激活，
+ *    用户设备上的正式运行环境没有该标记。
+ *
+ * 无侵入 patch `console.log/debug/info/warn/error`：原样放行（DevTools 不受影响）+
+ * 通过 `window.parent.postMessage` 转发给调试台（CSP 的 connect-src 不约束 postMessage，
+ * 网络上报由调试台页面代理）。发送全程静默：失败不得回打 console，避免自触发死循环。
+ *
+ * 激活时机：由 SDK 默认单例初始化时调用（业务 `import '@heybox/hb-sdk'` 即生效）；
+ * iframe 标记由调试台 `iframe.name` 与 vite dev 注入的无依赖 bootstrap 共同设置。
+ * 调试台页面自身（runtime 跑在这里，`[hb-sdk-runtime]` 日志不经过 iframe）另用
+ * `installMiniDevConsoleSelfCapture` 接入「日志」页签（source: 'host'）。
+ */
+export declare const MINI_DEV_IFRAME_WINDOW_NAME = "__hb_sdk_mini_dev__";
+export declare const MINI_DEV_CONSOLE_EVENT_TYPE = "hb-sdk:mini-dev-console";
+/** 对外契约：调试台监听该 postMessage 读取转发日志；message 结构必须稳定。 */
+export interface MiniDevConsoleMessage {
+    type: typeof MINI_DEV_CONSOLE_EVENT_TYPE;
+    detail: MiniDevConsoleEventDetail;
+}
+export type MiniDevConsoleLevel = 'log' | 'debug' | 'info' | 'warn' | 'error';
+export interface MiniDevConsoleEventDetail {
+    level: MiniDevConsoleLevel;
+    args: unknown[];
+    timestamp: number;
+}
+/** 调试台页面与 iframe bootstrap 共用的已安装标记（window/console 上的属性名）。 */
+export declare const MINI_DEV_CONSOLE_INSTALL_FLAG = "__hb_sdk_mini_dev_console_installed__";
+/** 调试台页面（非 iframe）自捕获：runtime/host 侧 console 直接进「日志」页签。 */
+export declare function installMiniDevConsoleSelfCapture(onLog: (level: MiniDevConsoleLevel, args: unknown[]) => void, consoleRef?: Console): void;
+export declare function installMiniDevConsoleForwarding(consoleRef?: Console): void;

package/types/vite/index.d.ts

@@ -1,7 +1,9 @@
 import { MINIAPP_PLATFORM_VALUES, type MiniappPlatform } from '../miniapp-manifest/schema';
 export interface MiniappManifestPlugin {
     name: string;
-    config: (config: MiniappManifestUserConfig) => MiniappManifestUserConfig | void;
+    config: (config: MiniappManifestUserConfig, env?: {
+        command: 'build' | 'serve';
+    }) => MiniappManifestUserConfig | void;
     configResolved: (resolved: MiniappManifestResolvedConfig) => void;
     /** Rollup 在构建失败后仍会跑 closeBundle；用 buildEnd 记录真实错误，避免二次校验掩盖原因。 */
     buildEnd: (error?: Error) => void;