@heybox/hb-sdk 0.8.1-alpha.2 → 0.8.1-alpha.6

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 本文件随 `@heybox/hb-sdk` npm 包公开分发，只记录外部小程序开发者可观察到的变化。内部集成、实现策略和审查证据不在此维护。
 
+## 0.8.1-alpha.6
+
+- 修复远端权限快照包含未知权限且 `config` 为 `null` 时，`hb-sdk remote info` 把已批准的网络权限和官方域名配置误判为未批准的问题。
+
+## 0.8.1-alpha.5
+
+- 修复调试台页脚显示的 `@heybox/hb-sdk` 版本号不会随实际安装版本更新的问题。
+
+## 0.8.1-alpha.4
+
+- 新增受管 `companion` 能力：小程序可显式准备、启动并控制随审核版本发布的桌面辅助应用。
+- Companion 配置统一放到 `package.json#heybox.companions`，构建与本地调试共用；原 `miniappManifest({ companions })` 参数须迁移。
+- `prepare()` 与 `launch()` 分别要求可信用户手势和 Host 授权，启动不会隐式下载。
+- V1 仅支持普通权限启动，不接受动态路径、参数、工作目录、环境变量或 shell。
+- 可选 stdio 使用原始 `Uint8Array`；Attachment 通过只读 `FileHandle` 访问。
+- `hb-sdk dev` 支持在 COA 批准 `companion` 后直接调试本地 Manifest 与 ZIP，无需先上传小程序版本。
+- 本地桌面调试固定使用 `127.0.0.1`，并将不可变 Manifest 摘要绑定到短期启动票。
+- 调试台分别展示浏览器、手机与 PC Companion 就绪状态；授权弹窗区分本地未审核产物并显示签名状态。
+- Browser Dev Host 新增桌面端入口，并按来源展示日志、脱敏详情和来源/级别筛选。
+- 修复 pnpm workspace 项目执行 `hb-sdk skill install` 时将 `workspace:^` 误判为 CLI 版本不一致的问题。
+- 修复 npm bundle 中 Agent Skill 包根定位错误，确保项目级安装读取随当前 `@heybox/hb-sdk` 分发的 Skill。
+- 修复 Companion 旧 PC Host 被错误判定为缺少全部 Companion 能力的问题；准备操作在页面 reload 时继续由 Host 持有，`launch()` 不再使用固定请求超时。
+- Companion alias、错误码和本地启动票摘要校验统一；本地开发产物仅在 `hb-sdk dev` 中提供，生产构建不再携带 smoke runner。
+
+## 0.8.1-alpha.3
+
+- 目标平台声明统一迁移到 `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 版本的冻结快照。
@@ -60,6 +89,15 @@
 
 - 更新权限声明、文件与下载、分享和 API Reference 文档，并提供公开更新日志与 RSS 订阅。
 
+## 0.8.0-alpha.15
+
+- 新增受管 `companion` 能力：小程序可显式准备、启动并控制随审核版本发布的桌面辅助应用。
+- `prepare()` 与 `launch()` 分别要求可信用户手势和 Host 授权，启动不会隐式下载。
+- V1 仅支持普通权限启动，不接受动态路径、参数、工作目录、环境变量或 shell。
+- 可选 stdio 使用原始 `Uint8Array`；Attachment 通过只读 `FileHandle` 访问。
+- Browser Dev Host 新增与二维码同风格的桌面端入口，选择正式版或 Debug 版后通过统一 URI 立即打开当前本地小程序。
+- Browser Dev Host 日志按来源展示事件、毫秒级时间、结果和耗时，支持脱敏详情展开、连续重复计数以及来源/级别筛选。
+
 ## 0.8.0-alpha.14
 
 - 摘要：修复移动端 `network.request()` 请求第三方接口时受 WebView CORS 限制的问题，统一交由 App Host 网络层执行。
@@ -73,6 +111,9 @@
 ## 0.8.0-alpha.13
 
 - 预发布版本：更新日志 RSS 与页面保持一致，仅展示公开变化分类，并按页面发布日期输出订阅时间。
+- 新增受管 `companion` 能力：新 PC 可显式准备、启动并控制随审核版本发布的桌面辅助应用。
+- `prepare()` 与 `launch()` 分别要求新的可信用户手势和 Host 授权；启动不隐式准备，公开 API 不接受动态路径、参数、环境变量或 shell。
+- 可选 stdio 使用原始 `Uint8Array` 和 at-least-once 输出语义；Browser Dev Host 的固定 Fake 不能作为桌面真机发布证据。
 
 ## 0.8.0-alpha.12
 

package/README.md

@@ -10,6 +10,8 @@ SDK 只提供面向小程序开发者的稳定接口，不提供客户端内部
 
 ## 快速开始
 
+多设备 console / SDK 调用日志与 Agent 查询命令见 [多设备开发日志](docs/device-logs.md)。
+
 ### 创建新项目
 
 ```bash
@@ -94,7 +96,17 @@ async function revokeAuthorizationFromUserAction() {
 
 `user.revokeAuthorization()` 位于无需声明白名单，不接收小程序 ID、黑盒用户 ID 或手势参数。调用必须来自可信用户操作，否则返回 `USER_GESTURE_REQUIRED`。撤销成功后，后续身份或授权读取会重新进入授权流程；SDK 不会替业务清理已经持久化的数据。
 
-已有 Vite 项目还需要启用构建插件：
+已有 Vite 项目先在 `package.json#heybox.platforms` 声明实际承诺适配的平台：
+
+```json
+{
+  "heybox": {
+    "platforms": ["android", "ios", "ohos"]
+  }
+}
+```
+
+再启用构建插件：
 
 ```ts
 import { miniappManifest } from '@heybox/hb-sdk/vite';
@@ -102,7 +114,7 @@ import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
-  plugins: [miniappManifest({ platforms: ['android', 'ios', 'ohos'] })],
+  plugins: [miniappManifest()],
 });
 ```
 
@@ -165,6 +177,37 @@ console.log(await downloaded.readText());
 
 `remove()` 只允许删除 sandbox 对象；外部 picker、`saveFile()` 及其派生项即使是 `readwrite` 也返回 `FILE_ACCESS_DENIED`。单个 Runtime session 最多保留 1024 个外部 direct handle，超限返回 `FILE_QUOTA_EXCEEDED`。Host 文件错误只向 SDK 暴露稳定 code 与 canonical 安全文案，业务不要依赖平台原始 message 或附加 data。
 
+## 受管桌面程序
+
+`companion` 允许获平台批准的小程序携带固定的桌面程序 ZIP，并在新 PC Host 中显式准备和启动。线上与生产环境使用当前已发布版本；`hb-sdk dev` 的真实 PC 联调可以直接使用 `package.json#heybox.companions` 声明的本地产物，无需先上传，但项目仍须绑定且 COA 已批准 `companion`。
+开发者只能使用 canonical Manifest 中的 alias、target、固定入口和固定参数；SDK 不提供真实下载 URL、本机路径、
+PID、动态 args、cwd、环境变量、shell 或任意命令执行。
+
+```ts
+const status = await hbSDK.companion.getPreparationStatus('runner');
+if (status.state !== 'ready') {
+  await hbSDK.companion.prepare('runner', {
+    onProgress(progress) {
+      console.log(progress.phase);
+    },
+  });
+}
+
+const session = await hbSDK.companion.launch('runner');
+session.stdio?.onStdout((bytes) => consumeRunnerBytes(bytes));
+```
+
+`prepare()` 和 `launch()` 是两次独立的高风险操作：每次真正开始下载或创建新进程前，都需要新的可信用户手势和
+Host 授权，`launch()` 不会隐式准备。stdio 只传输原始 `Uint8Array`，不承诺 UTF-8、行边界或业务协议；输出按
+at-least-once 语义投递，业务协议必须能按 sequence 去重并处理重连。Browser Dev Host 只提供固定 Fake 场景，
+不能选择或启动本机程序，也不能作为 Windows/macOS 真机发布证据。完整边界见
+[受管桌面程序](https://docs.xiaoheihe.cn/hb_sdk/guide/companion)。
+
+V1 仅支持普通权限启动；Manifest 的 `elevation` 只能省略或设为 `none`，`required` 会在构建时明确失败。
+管理员权限启动不属于当前版本交付范围。
+`displayName` 最多 120 个 Unicode code point；args 最多 64 项，单项最多 1024 UTF-8 bytes、总计最多
+16384 UTF-8 bytes，并拒绝 NUL、CR 和 LF。
+
 ## 错误处理
 
 握手失败会保留在持久状态中，可在订阅回放时直接处理原始错误：
@@ -201,6 +244,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | `files`      | 声明受控 sandbox 与用户选择授权的文件、目录操作 |
 | `cloud`      | 使用小程序云端排行榜                            |
 | `network`    | 发起经过平台授权的网络请求，并声明受控流式下载  |
+| `companion`  | 准备、启动并控制当前版本审核过的桌面辅助应用    |
 
 具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
 
@@ -231,7 +275,13 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 - Host 文件错误只保留稳定 code 与 canonical 安全文案；原始 message、data、native path 和 credential 不会进入小程序。
 - `FileStat.size` 是非负 safe integer；`modifiedAt` / `createdAt` 若存在，单位为 Unix epoch milliseconds。
 - 仅当当前版本声明且平台已批准 `network` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。`useOfficialDomain` 不参与 CSP 跳过判定。
-- 构建必须启用 `miniappManifest({ platforms })` 并显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
+- 构建必须启用 `miniappManifest()`，并在 `package.json#heybox.platforms` 显式声明实际承诺适配的平台，推荐统一使用 `hb-sdk build`。新项目模板中的 `['android', 'ios', 'ohos']` 只是初始配置，不代表已经完成真机验收。
+- `companion.prepare()` 与 `companion.launch()` 分别需要新的可信用户手势和 Host 授权；启动不会隐式准备。
+- Companion 入口、参数、平台目标和归档摘要只来自 canonical Manifest；线上与生产使用当前已发布版本，本地真 PC 调试使用 `hb-sdk dev` 固定并签发的本地 snapshot。页面不能传动态 path、args、cwd、环境变量或 shell。
+- Companion V1 只支持普通权限启动；`elevation: 'required'` 会在构建阶段失败。
+- Companion stdio 是原始 `Uint8Array` 且输出为 at-least-once 投递；业务自行定义 framing、去重、重放与恢复。
+- Browser Dev Host 的 Companion Fake 只用于状态和 UI 开发，不能作为桌面程序可执行、签名、权限或进程监管的真机证据。
+- 本地真 PC Companion 需要 `package.json#heybox.companions`、本地产物、已绑定项目和 COA `companion` 批准；未配置本地产物时使用 Browser Fake。配置或产物更新后校验并切换不可变快照；已有进程保留原产物，新产物须重新准备与启动。
 
 私有 Page Channel 适配没有修改 `@heybox/hb-sdk` 公开 API 或 iframe wire；本次 files/download
 Runtime 能力随 `0.8.0-alpha.11` release family 发布，部署 detail 前必须保证
@@ -299,7 +349,11 @@ hb-sdk remote deploy --release-note "本次更新说明"
 
 `hb-sdk create` 默认生成可直接删除的 Vanilla JavaScript + Vite HelloWorld，只保留 SDK Toast 示例、三端 Manifest 和开发/构建/部署命令，不绑定业务框架或项目内测试工具。
 
-`hb-sdk dev` 会启动 Vue 3 Browser Dev Host。左侧诊断面板集中展示日志、当前小程序作用域内的 Storage 快照和问题，右侧设备预览可在 iPhone 16 Pro Max（`440 x 956`）与 Pixel 9 Pro（`410 x 914`）间切换。切换预设只改变设备外框和 viewport，不会重新加载 iframe 或重启 Runtime；授权与操作弹窗、Toast、Loading 和振动反馈都限制在预览框内。
+`hb-sdk dev` 会启动 Vue 3 Browser Dev Host。左侧诊断面板集中展示结构化日志、当前小程序作用域内的 Storage 快照和问题；日志区分 App、SDK、Network、Runtime、Host 来源，支持毫秒级时间、结果、耗时、重复计数、脱敏详情展开以及来源/级别筛选。右侧设备预览可在 iPhone 16 Pro Max（`440 x 956`）与 Pixel 9 Pro（`410 x 914`）间切换。切换预设只改变设备外框和 viewport，不会重新加载 iframe 或重启 Runtime；授权与操作弹窗、Toast、Loading 和振动反馈都限制在预览框内。
+
+配置 `package.json#heybox.companions` 并启用 `miniappManifest({ platforms })` 后，dev server 只向 loopback 提供 canonical Companion Manifest 和固定 ZIP 路由。CLI 在每次签发或刷新本地启动票前绑定该 Manifest 摘要；普通 Web HMR 不改变 snapshot，Companion 配置或产物更新后会校验并切换到新快照，已有 Session 固定原有产物。调试台分别展示浏览器、手机和 PC Companion 就绪状态、本地 alias、target 与摘要短前缀。未配置 Companion 时启动票仍可用于本地 identity/detail，真实 PC Companion 会 fail closed，Browser Fake 可继续用于未上传状态联调。
+
+右上角的桌面图标与二维码按钮使用相同样式。点击桌面图标后选择小黑盒正式版或 Debug 版，选择会立即请求客户端打开当前本地页面并在本地记忆，不需要二次确认。桌面端只接受无凭据的 `http://127.0.0.1:<port>`，拒绝 `localhost`、IPv6 和 LAN 地址，不提供地址选择或手工 URL；手机二维码继续独立选择局域网地址。入口仅在项目已绑定且本地调试启动票有效时可用，统一 URI 只携带 `mini_program_id` 和 `mini_url`，启动票继续由 detail 从同源 `launch.json` 发现并交给后端验证。浏览器无法确认客户端是否真正打开，因此调试台只记录“已请求打开”，不会自动切换正式版或 Debug 版。
 
 浏览器调试入口不要求 CLI 登录或项目绑定；需要账号或远端配置的能力会按当前可用上下文返回结果或明确失败。调试台不提供权限修改入口，远端权限快照始终是 Runtime 的规范输入。手机验收统一从右上角二维码入口进入，选择手机可达的局域网网卡后扫码；二维码使用 `open_inapp` 与 `heybox://` `openWindow` 包装的短链。完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。
 

package/dist/cli-chunks/{build-FQoALfGC.cjs → build-B0X9pazW.cjs}

@@ -3,11 +3,13 @@
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
-var runtimePermissionEnv = require('./runtime-permission-env-BPRwn4Yc.cjs');
-var runtimeGate = require('./runtime-gate-BMSY22AL.cjs');
-var index = require('./index-BEn7WaqA.cjs');
-var projectVite = require('./project-vite-BO8oOfcs.cjs');
-require('./version-BONZQWPR.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-DWSscWBT.cjs');
+require('node:crypto');
+require('node:zlib');
+var runtimeGate = require('./runtime-gate-BWb8QIcX.cjs');
+var index = require('./index-CDwwaNvP.cjs');
+var projectVite = require('./project-vite-CE7kyqxl.cjs');
+require('./version-D19lZmYN.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');
@@ -28,6 +30,7 @@ async function runBuildCommand(_options = {}, runtime = {}) {
     const env = runtime.env ?? process.env;
     const mode = env.HB_SDK_ENV?.trim() || undefined;
     const skipPlatformCsp = runtimePermissionEnv.shouldSkipMiniappPlatformCspFromEnv(env);
+    const declaredPlatforms = runtimePermissionEnv.readMiniappPlatformsFromPackageJson(projectRoot);
     runtimePermissionEnv.readMiniappPermissionsFromPackageJson(projectRoot, runtimePermissionEnv.resolveMiniappSdkVersion());
     await fs.rm(distDir, { force: true, recursive: true });
     try {
@@ -46,7 +49,7 @@ async function runBuildCommand(_options = {}, runtime = {}) {
                     write: true,
                 },
             }), { successText: 'Vite 构建完成' });
-            const result = await validateBuildOutput(projectRoot, logger);
+            const result = await validateBuildOutput(projectRoot, logger, declaredPlatforms);
             logger.success(`构建完成: dist/ | manifest version ${result.version} | sdkVersion ${result.sdkVersion} | 待上传文件 ${result.fileCount} 个 | ${formatSize(result.totalBytes)}`);
             return result;
         }, env);
@@ -75,7 +78,7 @@ function createFixedBuildOutputPlugin(projectRoot) {
         },
     };
 }
-async function validateBuildOutput(projectRoot, logger) {
+async function validateBuildOutput(projectRoot, logger, declaredPlatforms) {
     const distDir = path.join(projectRoot, 'dist');
     const entryHtmlPath = path.join(distDir, 'index.html');
     const manifestPath = path.join(distDir, 'manifest.json');
@@ -89,14 +92,17 @@ async function validateBuildOutput(projectRoot, logger) {
     if (!runtimeGate.hasMiniappRuntimeGate(entryHtml)) {
         throw new Error('dist/index.html 缺少平台 Runtime 启动门禁，请在 Vite 配置中显式启用 miniappManifest()');
     }
-    const { manifest, hadBom } = runtimeGate.parseMiniappManifestJson(await fs.readFile(manifestPath, 'utf8'), 'dist/manifest.json');
+    const { manifest, hadBom } = runtimePermissionEnv.parseMiniappManifestJson(await fs.readFile(manifestPath, 'utf8'), 'dist/manifest.json');
     if (hadBom) {
         logger.warn('dist/manifest.json 包含 BOM，已自动剥离');
     }
-    const { platforms, sdkVersion, version, permissions } = runtimeGate.validateMiniappManifestForDeploy(manifest);
+    const { platforms, sdkVersion, version, permissions } = runtimePermissionEnv.validateMiniappManifestForDeploy(manifest);
+    if (!runtimePermissionEnv.areMiniappPlatformsEqual(platforms, declaredPlatforms)) {
+        throw new Error('dist/manifest.json.platforms 与 package.json#heybox.platforms 不一致，请重新 build');
+    }
     const allFiles = await walkDistFiles(distDir);
     const uploadFiles = allFiles.filter((file) => runtimePermissionEnv.shouldUploadDistFile(file.relativePath));
-    const sizeError = runtimePermissionEnv.validateUploadTotalSize(uploadFiles);
+    const sizeError = runtimePermissionEnv.validateMiniappUploadSizeBudgets(uploadFiles);
     if (sizeError) {
         throw new Error(sizeError.replace('重新 deploy', '重新 build'));
     }

package/dist/cli-chunks/{context-CA_Q1lyH.cjs → context-DVfWZ6d1.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
-var runtimePermissionEnv = require('./runtime-permission-env-BPRwn4Yc.cjs');
-var session = require('./session-C0eIKZ6V.cjs');
+var runtimePermissionEnv = require('./runtime-permission-env-DWSscWBT.cjs');
+var session = require('./session-DZXRQ4Dp.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var path = require('node:path');
@@ -365,7 +365,12 @@ async function createLocalDevLaunchToken(options, runtime = {}) {
         throw new Error('mini-program-id 不能为空');
     }
     const api = await resolveRemoteApiClient(options, runtime);
-    return api.createLocalDevLaunchToken({ mini_program_id: miniProgramId });
+    return api.createLocalDevLaunchToken({
+        mini_program_id: miniProgramId,
+        ...(options.companionManifestSha256
+            ? { companion_manifest_sha256: options.companionManifestSha256 }
+            : {}),
+    });
 }
 async function resolveRemoteApiClient(options, runtime) {
     if (runtime.apiClient) {

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