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

package/skill/references/cli.md

@@ -115,6 +115,14 @@ CLI 会启动页面服务并自动打开 Vue 3 本地调试台。左侧集中放
 
 `hb-sdk dev` 从项目 `package.json` 读取开发者声明，并在远端权限快照可用时读取平台批准结果。只有当前版本声明且平台已批准 `network` 时才跳过平台 CSP；`useOfficialDomain` 不参与该判定。调试台不提供权限或平台批准修改入口；快照缺失或无效时保留平台 CSP。
 
+调试台右上角的桌面图标与手机二维码按钮使用相同样式。点击桌面图标后选择小黑盒正式版或 Debug 版，选择后立即请求客户端打开当前本地小程序，不需要再点一次确认；上次选择的客户端会在本地记忆。桌面调试只接受无凭据的 `http://127.0.0.1:<port>`，拒绝 `localhost`、IPv6 和 LAN 地址，不提供地址选择；手机二维码仍维护独立的局域网选择。项目未绑定或本地调试启动票不可用时，菜单会显示不可用原因。
+
+桌面打开使用 `ai-desktop://v1/extensions/ai-desktop.heybox-user-miniprogram/open`，Debug 客户端使用 `ai-desktop-debug://`。URI 只包含 `mini_program_id` 与 `mini_url`，不包含启动票、权限快照或客户端执行参数；detail 仍从 `mini_url` 同源的 `/__hb_sdk__/launch.json` 读取最新启动事实并由后端验证。浏览器无法取得外部协议的可靠完成回执，所以界面只显示“已请求打开”，不会声明成功，也不会自动 fallback 到另一个客户端。
+
+本地真 PC 调试 Companion 不要求先上传版本，但必须在 `package.json#heybox.companions` 中配置本地 ZIP、绑定项目，并由 COA 批准 `companion`；`miniappManifest()` 只保留构建配置。dev server 只向 loopback 提供 canonical Manifest 与固定 ZIP 路由；CLI 在签发或刷新本地启动票时绑定 Manifest 摘要。配置或 ZIP 变化后会校验并切换到新快照，已有 Session 保持原有产物，新产物须重新准备与启动。调试台分别展示浏览器、手机与 PC Companion 的就绪状态，以及本地 alias、target 和摘要短前缀；产物缺失、校验失败或授权不可用时显示明确阻塞原因，不影响浏览器联调。没有本地 Companion 配置时仍可使用 Browser Fake 做状态联调，但真实 PC Companion 会 fail closed。
+
+手机 Dev Session 仅使用当前版本声明与平台批准结果求交后的有效权限，不接受调试页本地覆盖。两者均允许 `useOfficialDomain: true` 时，真机扫码调试会保留该配置；未批准、未声明或非法快照继续 fail closed。
+
 Browser Mock 会自动在实时与兼容链路间切换。手机调试使用 `open_inapp`/`openWindow` 包裹的 LAN 短链接二维码（先开普通 H5 跳转页，再进入小程序并关闭中间页）。
 
 ### 2. 先用浏览器 Mock 验收
@@ -125,7 +133,7 @@ Browser Mock 会自动在实时与兼容链路间切换。手机调试使用 `op
 - SDK 初始化与用户身份授权流程
 - 生命周期、Storage 和排行榜等能力
 
-调试台提供紧凑的日志、当前小程序隔离作用域内的 Storage 只读快照和问题聚合。日志与网络记录只保留脱敏的诊断字段，不展示 payload、结果、查询参数、凭据或原始错误信息。工坊小程序默认不能进行网络请求，网络权限暂未开放申请，不要把本地结果当成线上能力。
+调试台提供结构化日志、当前小程序隔离作用域内的 Storage 只读快照和问题聚合。日志按 App、SDK、Network、Runtime、Host 标识来源，首行展示事件与毫秒级时间，第二行展示结果、耗时和摘要；连续重复的 console 会合并计数。每条记录可展开查看脱敏详情，并可按来源、级别或搜索词筛选。日志与网络记录不展示请求体、响应体、header、查询参数、凭据或原始错误对象。工坊小程序默认不能进行网络请求，网络权限暂未开放申请，不要把本地结果当成线上能力。
 
 右侧可切换 iPhone 16 Pro Max（`387 x 821`）与 Pixel 9 Pro（`322 x 716`）两个设备预设。尺寸对应固定上游设备外框的真实屏幕 opening；预设同时决定外框、状态栏、安全区和 viewport。切换设备不会重新加载小程序或重启 Runtime，页面状态和调试会话保持不变。授权与操作弹窗、Toast、Loading 和振动反馈均显示在设备预览内部，不会覆盖整个调试台。
 
@@ -162,7 +170,7 @@ Browser Mock uses the Node `hb-sdk login` session to send Host `heybox-session`
 hb-sdk build [--env <name>] [--verbose]
 ```
 
-`hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `vite.config.ts` 中显式注册 `miniappManifest()`。
+`hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `package.json#heybox.platforms` 声明目标平台，并在 `vite.config.ts` 中显式注册无参的 `miniappManifest()`；配置与构建产物不一致时构建失败。
 
 直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端批准结果，并与当前版本声明取交集；仅当有效 `network` 权限启用时才跳过平台 CSP，`useOfficialDomain` 不参与该判定。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
 
@@ -181,7 +189,7 @@ hb-sdk build [--env <name>] [--verbose]
 Agent rules:
 
 - Use `hb-sdk build [--env <name>] [--verbose]` as the recommended production build entry.
-- Require explicit `miniappManifest()` configuration and keep typechecking in the project's `scripts.build`.
+- Require target platforms in `package.json#heybox.platforms`, keep the no-argument `miniappManifest()` configured, and keep typechecking in the project's `scripts.build`.
 - Do not claim `hb-sdk build` needs login, binding, or network access, and do not invent unsupported build flags.
 - Existing `vite build` projects remain compatible and must not be auto-migrated.
 

package/skill/references/examples.md

@@ -165,13 +165,21 @@ hb-sdk login clear
 
 ### Vite manifest plugin
 
+```json
+{
+  "heybox": {
+    "platforms": ["android", "ios", "ohos"]
+  }
+}
+```
+
 ```ts
 import { miniappManifest } from '@heybox/hb-sdk/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
   base: './',
-  plugins: [miniappManifest({ platforms: ['android', 'ios', 'ohos'] })],
+  plugins: [miniappManifest()],
 });
 ```
 
@@ -187,6 +195,10 @@ export default defineConfig({
 - Do not send `multipart/form-data` (or handcrafted multipart bodies) through `network.request`; use form-urlencoded string body or a dedicated upload capability.
 - Do not pass string paths, browser File System Access handles, Blob targets, Range/resume fields, or upload bodies to `network.download`; use SDK-created File/Directory handles on new PC.
 - Do not treat Mobile, Web, Browser Dev Host, or legacy PC as evidence for files/download support. Only new PC currently implements the retained contract; other Hosts return `METHOD_FORBIDDEN` and provide no memory fallback.
+- Do not pass executable paths, dynamic args, cwd, environment variables, shell commands, URLs, hashes, or native process identifiers to `companion`. Only the reviewed Manifest may define launch inputs.
+- Treat `companion.prepare()` and `companion.launch()` as separate trusted-user-gesture and Host-authorization operations. Launch never prepares implicitly.
+- Companion stdio is raw `Uint8Array` with at-least-once output delivery. Business protocols own framing, sequence de-duplication, replay, and reconnection.
+- Browser Dev Host Companion Fake is deterministic development feedback only; never cite it as Windows/macOS executable, integrity, elevation, or process-tree evidence.
 - Do not treat `hb-sdk login` as iframe SDK authentication state.
 - Do not create a second mock runtime package when `hb-sdk dev` is the supported local mock workflow.
 - Do not import `@heybox/hb-sdk/vite` from iframe business code or fetch a deployed `manifest.json` directly.

package/skill/references/recipes.md

@@ -8,6 +8,7 @@
 - apps/docs/hb-sdk/guide/auth.md
 - apps/docs/hb-sdk/guide/lifecycle.md
 - apps/docs/hb-sdk/guide/error-handling.md
+- apps/docs/hb-sdk/guide/companion.md
 - apps/docs/hb-sdk/recipes/login-gate.md
 - apps/docs/hb-sdk/recipes/community-share.md
 - apps/docs/hb-sdk/recipes/custom-instance.md
@@ -18,6 +19,7 @@
 - [User and login](#user-and-login)
 - [Lifecycle events](#lifecycle-events)
 - [Error handling](#error-handling)
+- [Managed Companion](#managed-companion)
 - [Login gate recipe](#login-gate-recipe)
 - [Community share recipe](#community-share-recipe)
 - [Custom instance recipe](#custom-instance-recipe)
@@ -372,6 +374,8 @@ onUnmounted(stopLifecycleEvents)
 - 组件或页面销毁时清理 `on` 注册的监听，避免重复响应。
 - 生命周期事件只派发给注册当时存在的监听器，不会重放；一次性 `launch` 信息应在页面启动阶段通过业务能力调用处理。
 - 收到 `unload` 后，当前 SDK 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。
+- Companion preparation 与进程 Session 由 Host 持有，页面 `hide` 或 reload 不会自动取消或终止；新页面分别通过 `getPreparationStatus()` 与 `getActiveSession()` 恢复观察和控制。
+- 新 Runtime generation 取得活动 Companion Session 后，旧 controller 会收到 ownership-lost 并失去写权限；stdio 输出可能 at-least-once 重放，业务必须按自身协议去重。
 
 ## Error handling
 
@@ -413,8 +417,13 @@ try {
 - `AUTHORIZATION_CANCELLED` 表示用户取消、拒绝或关闭授权页面，应正常结束当前操作。
 - `SERVER_API_REQUIRED` 表示当前用户数据必须经开发者服务端 OpenAPI 获取，不应在页面重试对应 Host API。
 - `METHOD_FORBIDDEN` 表示当前 Host 未实现或关闭对应能力。V1 files/download 在 Mobile、Web 和 Browser Dev Host 都会得到该错误。
+- `ENVIRONMENT_NOT_READY` 表示在 SDK 完成握手前调用了 `environment.getInfoSync()`；一般改用会自动等待的 `environment.getInfo()`。
 - `FILE_PICKER_CANCELLED` 表示用户取消了外部文件或目录选择，应正常结束当前操作。
 - `DOWNLOAD_CANCELLED` 表示取消意图先于 Host 提交生效；Host 已完成提交时仍返回成功。`DOWNLOAD_TIMEOUT` 表示网络空闲超时，失败不会改动原目标。
+- `COMPANION_NOT_PREPARED` 表示启动前尚未显式准备；应由新的用户操作调用 `companion.prepare()`，不要在 `launch()` 中自动重试。
+- `COMPANION_SESSION_OWNERSHIP_LOST` 表示 Session controller 已由新的 Runtime generation 接管；停止旧 controller 写入，需要继续取得控制权时重新取得活动 Session。
+- `COMPANION_DESCRIPTOR_UNAVAILABLE` 表示授权或描述符暂时不可用，Runtime 会保留 `retryable: true`。
+- `COMPANION_INTEGRITY_FAILED`、`COMPANION_ARCHIVE_INVALID` 或操作系统拦截都不能绕过；停止重试并修正归档后提交新审核版本。
 - `DOWNLOAD_HTTP_STATUS` 的 `data` 只包含脱敏后的 `status`、可选 `statusText` 和安全响应头。
 - 超时或运行环境不可用时，允许用户重试或退出当前流程。
 - 上报 `code`、`message` 和必要的业务上下文，不要上报用户凭据或敏感数据。
@@ -468,6 +477,159 @@ function reportSDKError(errorCode: string, message: string, data?: unknown) {
 picker 取消、授权撤销、文件缺失、quota、下载状态或取消，不依赖 `message` 文案，也不要记录
 真实路径、内部 handle 或响应凭据头。
 
+Companion 失败仍使用 `HbMiniProgramSDKError`。prepare 与 launch 的授权取消属于两次独立用户决定；业务不得在一次点击中自动串联授权，也不得用 Browser Fake 成功替代 Windows/macOS 真机错误处理验证。完整状态机见[受管桌面程序](https://docs.xiaoheihe.cn/hb_sdk/guide/companion)。
+
+## Managed Companion
+
+
+# 受管桌面程序
+
+`companion` 用于准备和启动随当前小程序审核版本发布的桌面辅助应用。V1 仅支持新 PC Host 的
+`windows-x64` 与 `macos-arm64`；老 PC、Mobile、Web 和 Linux 不在支持范围内。
+
+## 声明与构建
+
+项目必须在 `package.json` 显式声明高风险权限：
+
+```json
+{
+  "heybox": {
+    "permissions": {
+      "companion": { "enabled": true }
+    },
+    "companions": {
+      "runner": {
+        "displayName": "桌面辅助程序",
+        "capabilities": ["stdio"],
+        "targets": {
+          "windows-x64": {
+            "source": "companion/runner-windows-x64",
+            "entrypoint": { "kind": "executable", "path": "runner.exe" },
+            "elevation": "none",
+            "args": []
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+归档统一通过 `package.json#heybox.companions` 配置，`source` 相对该 `package.json` 所在目录解析。
+Vite 中使用 `miniappManifest({ platforms: ['windows'] })` 等构建配置；不要在 Vite 配置中复制 Companion 声明。
+构建和本地调试读取同一份声明。构建会检查 ZIP 结构和固定入口，复制到
+`dist/companions/<alias>/<target>.zip`，并生成大小与 SHA-256；Web 文件和 Companion 文件进入同一上传
+session 与同一审核版本。页面不能读取部署后的 `manifest.json`，也不能取得真实 CDN URL 或本机安装路径。
+
+`hb-sdk dev` 的真实 PC 联调可以直接使用这里声明的本地 ZIP，不要求先上传版本，但项目必须已绑定且 COA
+批准 `companion`。dev server 只向 loopback 提供固定 Manifest/ZIP 路由，CLI 用短期票据绑定当前 dev
+进程的 canonical snapshot。ZIP 或配置变化后会校验并切换到新快照，已有 Session 保持原有产物；
+新产物必须重新准备并启动。校验失败时调试台显示阻塞原因，不会悄悄使用旧文件或线上产物。
+单次开发服务最多保留 32 份快照、累计 ZIP 大小 1 GiB；达到上限后停止接纳新快照，
+请先结束调试 Session，再重启开发服务，已有快照不会被自动逐出。
+未配置本地 Companion 时使用 Browser Fake 做状态联调，真实 PC 不会回退到线上 candidate。
+
+构建与 PC 安装都会检查真实二进制格式：Windows 为 AMD64 PE，macOS 为包含 arm64 的 Mach-O；
+脚本即使改名或有执行权限也会被拒绝。授权弹窗展示产物来源与签名状态，本地 ZIP 明确标记
+“本地开发产物，未经过版本审核”。
+`.app` 从 XML 或 binary Info.plist 的 `CFBundleExecutable` 精确选择主入口。
+
+Manifest 只接受固定入口和固定 args。V1 仅支持普通权限启动，`elevation` 只能省略或设为 `none`；
+`required` 会在构建时明确失败，管理员权限启动留待后续版本。公开 API 不接受 executable path、动态 args、
+cwd、environment、shell 或任意命令；不要把 `files.sandbox` 中的普通文件当作可执行对象。
+`displayName` 最多 120 个 Unicode code point；args 最多 64 项，单项最多 1024 UTF-8 bytes、总计最多
+16384 UTF-8 bytes，并拒绝 NUL、CR 和 LF。
+
+## 准备与启动
+
+```ts
+import { companion } from '@heybox/hb-sdk'
+
+// 分别绑定到「准备」与「启动」按钮，不能在一个点击中串联。
+function prepareFromUserAction() {
+  return companion.prepare('runner', {
+    onProgress(progress) {
+      renderProgress(progress)
+    },
+  })
+}
+
+function launchFromUserAction() {
+  return companion.launch('runner')
+}
+```
+
+`prepare()` 和 `launch()` 必须分别由新的可信用户手势触发。每次真正开始新的准备操作前，Runtime 展示一次
+Host 可信授权；已 ready 或加入同一在途准备时不会重复授权。每次真正创建新进程前，`launch()` 再展示独立
+授权，不能复用 prepare 的手势或授权。`launch()` 不会隐式调用 `prepare()`，未准备时稳定失败。
+
+准备操作属于 Host：页面 reload、最小化或进入后台不会取消。新页面可用
+`getPreparationStatus()` 查询状态，并通过相同 alias 加入在途操作；显式取消使用
+`cancelPreparation(alias)` 或 `AbortSignal`。页面 reload 只断开观察者，不会向 Host 发送取消；原子提交已经开始时，最终提交结果优先于取消意图。
+
+## Session 与 stdio
+
+同一小程序 identity 与 alias 同时最多有一个活动 Session。`getActiveSession(alias)` 会取得当前活动 Session
+的控制权；新 Runtime generation 接管后，旧 controller 的写入、关闭 stdin、终止、附件和通知操作都会失败。
+进程退出后 `getActiveSession()` 返回 `undefined`，业务结果应由小程序自行持久化。
+
+stdio 仅在 Manifest 声明 `stdio` 时存在，输入输出都是原始 `Uint8Array`。SDK 不做 UTF-8、换行、NDJSON、
+RPC 或业务状态解析。输出采用 at-least-once 投递，收到 chunk 后 SDK 会确认 sequence；断连与重取控制权可能
+导致重复，因此业务 framing 必须携带可去重标识，并能处理拆包、粘包和重放。
+
+```ts
+const session = await companion.getActiveSession('runner')
+if (session?.stdio) {
+  const stop = session.stdio.onStdout(bytes => decodeBusinessFrame(bytes))
+  await session.stdio.write(encodeBusinessFrame({ type: 'status' }))
+  // 组件销毁时调用 stop()；业务退出协议可先写入，再 closeStdin()。
+}
+```
+
+平台不提供语义跨平台不稳定的 request-close。业务可先通过自身 stdio 协议请求正常退出，或关闭 stdin；
+`terminate()` 是强制结束完整受管进程树。页面隐藏或 reload 不结束 Session，用户真正关闭小程序窗口时由 Host
+处理完整进程树生命周期。
+
+## 可选能力
+
+- `attachments`：`session.attachments.open(id)` 返回只读 `FileHandle`；opaque id 来自桌面程序自身业务协议，页面无法指定物理路径。
+- `notifications`：页面解析业务协议后，可请求 Host 展示固定类别通知；页面完全断开时不承诺业务通知。
+- `stdio`：仅提供原始字节双向流，不提供文本编码或 RPC。
+
+只有 Manifest 声明且 Host 实现的能力才出现在 Session。不要根据操作系统或属性存在性猜测支持情况。
+
+## 调试与验收
+
+调试台分别显示浏览器、手机与 PC Companion 的就绪状态，以及本地 alias、平台和产物摘要短前缀。
+PC 会在页面闲置时继续复核授权；明确撤销权限会结束进程树，临时网络故障只允许有时限的宽限，
+不会让已失去授权的进程无限运行。关闭开发服务前请先停止调试进程。
+
+Browser Dev Host 只提供确定性的 Fake 场景，用于开发准备进度、Session 状态、stdio framing、错误 UI 与恢复逻辑。
+Fake 不选择、不下载、不解压、不启动本机程序，也不经过操作系统安全检查或真实进程组。
+因此 Browser Fake、Mobile 或 Web 的结果不能作为桌面发布证据；发布前必须分别在目标 Windows/macOS 新 PC Host
+完成归档摘要、准备取消、启动、stdio、退出与进程树清理验收。
+
+## 失败处理
+
+- `USER_GESTURE_REQUIRED`：当前 prepare 或 launch 缺少新的可信用户手势。
+- `USER_CANCELLED`：用户拒绝或关闭本次 Host 授权，应正常结束流程。
+- `COMPANION_NOT_PREPARED`：先由新的用户操作显式调用 `prepare()`。
+- `COMPANION_INTEGRITY_FAILED` / `COMPANION_ARCHIVE_INVALID`：停止重试并提交新审核版本，不能绕过摘要或系统安全检查。
+- `COMPANION_SESSION_OWNERSHIP_LOST`：当前 Runtime 已失去 controller；需要时重新调用 `getActiveSession()`。
+- `COMPANION_DESCRIPTOR_UNAVAILABLE`：授权或描述符暂时不可用，可在有界重试策略下重试。
+- `COMPANION_ELEVATION_DENIED`：为未来管理员权限启动保留的兼容错误码；V1 构建不接受 `elevation: 'required'`。
+- `METHOD_FORBIDDEN` / `COMPANION_UNSUPPORTED`：当前 Host 或平台未实现，不要循环重试或用任意执行替代。
+
+完整类型与方法见 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/)。
+
+## 完成检查
+
+- 权限、目标 ZIP、固定入口和固定参数都随同一版本提交审核。
+- prepare 与 launch 使用两次独立可信用户操作和 Host 授权。
+- stdio 业务协议处理了原始字节 framing、at-least-once 去重和断连恢复。
+- 未向页面暴露或传入 URL、物理路径、动态 args、环境变量、shell 或 PID。
+- Browser Fake 只用于开发，目标平台均已完成新 PC 真机验收。
+
 ## Login gate recipe
 
 

package/skill/references/safety-boundaries.md

@@ -18,12 +18,12 @@
 - `auth.login()`、`user.getInfo()` 和 `user.getSteamGameList()` 的可用性不由 `network` 决定；它们分别要求 `userInfo` 或 `steamLibrary`，并继续遵循各自的用户授权和数据规则。
 - `user.revokeAuthorization()` 在两种网络模式下都要求可信用户手势；成功后必须停止使用并清理业务缓存的旧身份、资料和服务端会话。
 - `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
-- 业务网络请求使用 `network.request()`，不要依赖浏览器原生网络出口。
+- 现有业务网络请求仍使用 `network.request()`；该 API 已标记废弃，但目前没有替代调用入口，不要依赖浏览器原生网络出口。
 - 公开 `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`，文件上传请走专用上传能力。
 - 新 PC 开放持久 sandbox、单文件/目录 picker、精确 File 保存与公网 `network.download()`；多选和小黑盒域名流式下载暂不支持。Mobile、Web 与 Browser Dev Host 仍未开放这些 primitive。
-- 新 PC 支持 `network.request`，但会忽略 `withCredentials`；它不改变请求路由或凭据行为。其他平台继续遵循各自的 Host 语义。
+- `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 验收。
 - 新 PC 不支持振动、分享菜单和截图分享；`navigation.openAppPage` 仅支持 `game_detail`，用户/帖子详情会明确失败。调用平台相关能力时应处理 `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。
 - picker 必须来自可信用户手势；取消选择返回 `FILE_PICKER_CANCELLED`。`saveFile()` 只接受 `suggestedName`，不接受 `accept`。
 - `pickFiles()` / `pickDirectory()` 默认只读；`pickFiles()` 仅在显式传入 `multiple: true` 时允许 Host 返回多个文件。要写入或作为下载目标时显式请求 `mode: 'readwrite'`。
@@ -35,7 +35,13 @@
 - 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 前必须保证

package/skill/skill.json

@@ -1,16 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.0+skill.7bb8515ab71e",
+  "skillVersion": "0.8.1-alpha.10+skill.79d09c3b6cad",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.0",
-    "compatibility": "0.8.0"
+    "version": "0.8.1-alpha.10",
+    "compatibility": "0.8.1-alpha.10"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.8.0",
+    "version": "0.8.1-alpha.10",
     "path": "skill"
   },
-  "integrity": "sha256-7bb8515ab71e004724601d7e09d0e5058888b53a7486b7ed15535ba9a8cdb93c"
+  "integrity": "sha256-79d09c3b6cad5fe22962d813b7513e2ef23eda8f6ff5fb9ddc8d6778eb73a81f"
 }

package/types/core/client.d.ts

@@ -1,4 +1,5 @@
 import { type MiniProgramSDKHandshakeState, type MiniProgramSDKHandshakeStateHandler } from './handshake-state';
+import { type MiniProgramEnvironmentInfo, type MiniProgramEnvironmentReader } from '../modules/environment';
 import type { MiniProgramBridgeMethod, MiniProgramCapabilityPayload, MiniProgramCapabilityResult } from '../protocol/capabilities';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 /**
@@ -30,13 +31,15 @@ export interface MiniProgramOperationOptions<TProgress = unknown> {
     signal?: AbortSignal;
     onProgress?: (progress: TProgress) => void;
     createAbortError?: () => unknown;
+    /** Long Host operations can survive observer teardown. */
+    cancelOnAbort?: boolean;
 }
 /** 支持 request-scoped progress/cancel 的 bridge requester。 */
 export interface MiniProgramOperationRequester extends MiniProgramRequester {
     requestOperation<Method extends MiniProgramBridgeMethod, TProgress = unknown>(method: Method, payload: MiniProgramCapabilityPayload<Method>, options?: MiniProgramOperationOptions<TProgress>): Promise<MiniProgramCapabilityResult<Method>>;
 }
 /** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
-export declare class MiniProgramBridgeClient implements MiniProgramOperationRequester {
+export declare class MiniProgramBridgeClient implements MiniProgramOperationRequester, MiniProgramEnvironmentReader {
     private readonly timeout;
     private readonly selfWindow?;
     private readonly targetWindow;
@@ -61,6 +64,7 @@ export declare class MiniProgramBridgeClient implements MiniProgramOperationRequ
     private destroyed;
     private runtimeUnavailable;
     private runtimeUnavailableError?;
+    private environmentInfo?;
     constructor(options?: MiniProgramSDKOptions);
     /** 等待父容器握手完成。 */
     waitForHandshake(): Promise<void>;
@@ -68,6 +72,10 @@ export declare class MiniProgramBridgeClient implements MiniProgramOperationRequ
     getHandshakeState(): MiniProgramSDKHandshakeState;
     /** 订阅握手状态，并立即接收当前状态。 */
     onHandshakeStateChange(handler: MiniProgramSDKHandshakeStateHandler): () => void;
+    /** 等待握手后读取当前实例的环境快照。 */
+    getEnvironmentInfo(): Promise<MiniProgramEnvironmentInfo>;
+    /** 同步读取握手期间缓存的环境快照。 */
+    getEnvironmentInfoSync(): MiniProgramEnvironmentInfo;
     /** 注册小程序事件监听。 */
     on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
     /** 移除小程序事件监听。 */

package/types/core/sdk.d.ts

@@ -1,6 +1,7 @@
 import { type MiniProgramSDKOptions } from './client';
 import { type MiniProgramAuthModule } from '../modules/auth';
 import { type MiniProgramCloudModule } from '../modules/cloud';
+import { type MiniProgramCompanionModule } from '../modules/companion';
 import { type MiniProgramShareModule } from '../modules/share';
 import { type MiniProgramStorageModule } from '../modules/storage';
 import { type MiniProgramNetworkModule } from '../modules/network';
@@ -9,6 +10,7 @@ import { type MiniProgramViewportModule } from '../modules/viewport';
 import { type MiniProgramUserModule } from '../modules/user';
 import { type MiniProgramUiModule } from '../modules/ui';
 import { type MiniProgramDeviceModule } from '../modules/device';
+import { type MiniProgramEnvironmentModule } from '../modules/environment';
 import { type MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
@@ -48,6 +50,10 @@ export declare class MiniProgramSDK {
     readonly navigation: MiniProgramNavigationModule;
     /** 云端数据相关开放能力。 */
     readonly cloud: MiniProgramCloudModule;
+    /** 受管桌面程序能力。 */
+    readonly companion: MiniProgramCompanionModule;
+    /** 当前实例的环境信息。 */
+    readonly environment: MiniProgramEnvironmentModule;
     constructor(options?: MiniProgramSDKOptions);
     /** 获取当前握手状态。 */
     getHandshakeState(): MiniProgramSDKHandshakeState;

package/types/core/singleton.d.ts

@@ -1,5 +1,6 @@
 import type { MiniProgramAuthModule } from '../modules/auth';
 import type { MiniProgramCloudModule } from '../modules/cloud';
+import type { MiniProgramCompanionModule } from '../modules/companion';
 import type { MiniProgramShareModule } from '../modules/share';
 import type { MiniProgramStorageModule } from '../modules/storage';
 import type { MiniProgramNetworkModule } from '../modules/network';
@@ -8,6 +9,7 @@ import type { MiniProgramViewportModule } from '../modules/viewport';
 import type { MiniProgramUserModule } from '../modules/user';
 import type { MiniProgramUiModule } from '../modules/ui';
 import type { MiniProgramDeviceModule } from '../modules/device';
+import type { MiniProgramEnvironmentModule } from '../modules/environment';
 import type { MiniProgramNavigationModule } from '../modules/navigation';
 import type { MiniProgramEventHandler, MiniProgramEventName } from '../protocol/types';
 import type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './handshake-state';
@@ -103,5 +105,9 @@ export declare const device: MiniProgramDeviceModule;
 export declare const navigation: MiniProgramNavigationModule;
 /** 默认 SDK 实例的 cloud 模块。 */
 export declare const cloud: MiniProgramCloudModule;
+/** 默认 SDK 实例的受管桌面程序模块。 */
+export declare const companion: MiniProgramCompanionModule;
+/** 默认 SDK 实例的 environment 模块。 */
+export declare const environment: MiniProgramEnvironmentModule;
 /** 重置默认 SDK 实例，仅用于测试。 */
 export declare function resetDefaultSDKForTest(): void;

package/types/devtools/device-logs.d.ts

@@ -0,0 +1,48 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const DEVICE_LOG_PATH = "/__hb_sdk__/device-logs";
+export declare function registerDeviceLogs(port: number, store: DeviceLogStore): () => void;
+export declare function getDeviceLogs(appUrl: string): any;
+export declare class DeviceLogStore {
+    private sandboxRequests;
+    listSandbox(id: string, path: string): Promise<unknown>;
+    readonly uploadToken: string;
+    readonly epoch: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly expiresAt;
+    private cursor;
+    private logs;
+    private devices;
+    query(params: URLSearchParams): {
+        schemaVersion: number;
+        epoch: `${string}-${string}-${string}-${string}-${string}`;
+        items: {
+            cursor: number;
+            deviceSessionId: string;
+            sequence: number;
+            timestamp: number;
+            receivedAt: number;
+            level: string;
+            source: string;
+            message: string;
+            truncated: boolean;
+            method?: string;
+            callId?: string;
+            outcome?: string;
+            errorCode?: string;
+            durationMs?: number;
+        }[];
+        nextCursor: number;
+        hasMore: boolean;
+        gap: boolean;
+        devices: {
+            id: string;
+            name: string;
+            platform: string;
+            connectedAt: number;
+            lastSeen: number;
+            online: boolean;
+        }[];
+    };
+    upload(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+/** 同源开发页面使用有界批量回传；传输失败不会递归写入 console。 */
+export declare function deviceLogBootstrap(token: string): string;

package/types/index.d.ts

@@ -1,8 +1,9 @@
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
-export { getHandshakeState, onHandshakeStateChange, on, off, auth, user, share, viewport, storage, files, network, ui, device, navigation, cloud, } from './core/singleton';
+export { getHandshakeState, onHandshakeStateChange, on, off, auth, user, share, viewport, storage, files, network, ui, device, environment, navigation, cloud, companion, } from './core/singleton';
 export type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './core/handshake-state';
 export type { MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap } from './protocol/types';
 export type { LoginOptions, LoginPayload, LoginResult, LoginScope, MiniProgramAuthModule } from './modules/auth';
+export type { CompanionAttachments, CompanionCapability, CompanionExit, CompanionExitHandler, CompanionInfo, CompanionNotification, CompanionNotificationCategory, CompanionNotifications, CompanionOutputHandler, CompanionOwnershipLostHandler, CompanionPreparationStatus, CompanionPrepareOptions, CompanionPrepareProgress, CompanionSession, CompanionStdio, CompanionState, CompanionStateChangeHandler, CompanionTarget, MiniProgramCompanionModule, } from './modules/companion';
 export type { DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, LeaderboardEntry, LeaderboardOrder, MiniProgramCloudLeaderboardModule, MiniProgramCloudModule, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, } from './modules/cloud';
 export type { AuthorizedUserInfo, GetUserInfoPayload, GetUserInfoResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, GetSteamGameListOptions, GetSteamGameListPayload, GetSteamGameListResult, MiniProgramUserInfoResult, MiniProgramUserModule, UserInfoAuthorization, UserInfoAuthorizationStatus, SteamGameListData, SteamGameListItem, SteamGamePrice, SteamGameListSort, } from './modules/user';
 export { USER_INFO_AUTHORIZATION_SCOPES } from './modules/user';
@@ -14,6 +15,7 @@ export type { DownloadBaseOptions, DownloadOptions, DownloadProgress, MiniProgra
 export type { CreateOptions, DirectoryHandle, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, ListOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, RemoveOptions, SaveFileOptions, } from './modules/files';
 export type { HideLoadingPayload, HideLoadingResult, MiniProgramToastStatus, MiniProgramUiModule, ShowLoadingPayload, ShowLoadingResult, ShowToastPayload, ShowToastResult, } from './modules/ui';
 export type { MiniProgramDeviceModule, MiniProgramVibrateIntensity, SetClipboardPayload, SetClipboardResult, VibratePayload, VibrateResult, } from './modules/device';
+export type { MiniProgramEnvironmentInfo, MiniProgramEnvironmentModule, MiniProgramOperatingSystemName, MiniProgramRuntimeMode, } from './modules/environment';
 export type { ClosePayload, CloseResult, MiniProgramAppPageTarget, MiniProgramGameDetailGameType, MiniProgramGameDetailPage, MiniProgramNavigationModule, OpenAppPageOptions, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenGameDetailAppPageOptions, OpenPostDetailAppPagePayload, OpenPostDetailAppPageOptions, OpenUserDetailAppPagePayload, OpenUserDetailAppPageOptions, ReloadPayload, ReloadResult, } from './modules/navigation';
 import { getHandshakeState, off, on, onHandshakeStateChange } from './core/singleton';
 declare const hbSDK: {
@@ -30,7 +32,9 @@ declare const hbSDK: {
     network: import(".").MiniProgramNetworkModule;
     ui: import(".").MiniProgramUiModule;
     device: import(".").MiniProgramDeviceModule;
+    environment: import(".").MiniProgramEnvironmentModule;
     navigation: import(".").MiniProgramNavigationModule;
     cloud: import(".").MiniProgramCloudModule;
+    companion: import(".").MiniProgramCompanionModule;
 };
 export default hbSDK;

package/types/miniapp-manifest/companion-directory.d.ts

@@ -0,0 +1,2 @@
+/** 双次读取校验输入稳定性；保留 .app 安全链接以避免破坏签名。 */
+export declare function packCompanionDirectory(root: string, label: string): Buffer;

package/types/miniapp-manifest/companion-executable.d.ts

@@ -0,0 +1,4 @@
+/** 检查原生入口的文件格式与目标架构；文件后缀和执行位不能代替此门禁。 */
+export declare function assertCompanionExecutable(bytes: Buffer, target: 'windows-x64' | 'macos-arm64'): void;
+/** 只解析 bundle 主字典的 CFBundleExecutable，兼容 XML 与 binary plist。 */
+export declare function companionBundleExecutable(plist: Buffer): string;

package/types/miniapp-manifest/companion-types.d.ts

@@ -0,0 +1,38 @@
+export declare const MINIAPP_COMPANION_TARGETS: readonly ["windows-x64", "macos-arm64"];
+export declare const MINIAPP_COMPANION_CAPABILITIES: readonly ["stdio", "attachments", "notifications"];
+export type MiniappCompanionTarget = (typeof MINIAPP_COMPANION_TARGETS)[number];
+export type MiniappCompanionCapability = (typeof MINIAPP_COMPANION_CAPABILITIES)[number];
+export interface MiniappCompanionAuthoringTarget {
+    /** 相对 package.json 所在目录的产物目录；SDK 在调试和构建时自动打包。 */
+    source: string;
+    entrypoint: {
+        kind: 'executable' | 'app-bundle';
+        path: string;
+    };
+    /** V1 仅支持普通权限启动；省略时等同于 `none`。 */
+    elevation?: 'none';
+    args?: readonly string[];
+}
+export interface MiniappCompanionAuthoringDefinition {
+    displayName: string;
+    capabilities?: readonly MiniappCompanionCapability[];
+    targets: Partial<Record<MiniappCompanionTarget, MiniappCompanionAuthoringTarget>>;
+}
+export type MiniappCompanionAuthoringDeclarations = Record<string, MiniappCompanionAuthoringDefinition>;
+export interface MiniappCompanionManifestTarget {
+    path: string;
+    size: number;
+    sha256: string;
+    entrypoint: {
+        kind: 'executable' | 'app-bundle';
+        path: string;
+    };
+    elevation: 'none';
+    args: string[];
+}
+export interface MiniappCompanionManifestDefinition {
+    displayName: string;
+    capabilities: MiniappCompanionCapability[];
+    targets: Partial<Record<MiniappCompanionTarget, MiniappCompanionManifestTarget>>;
+}
+export type MiniappCompanionManifestDeclarations = Record<string, MiniappCompanionManifestDefinition>;

package/types/miniapp-manifest/companions.d.ts

@@ -0,0 +1,17 @@
+import { type MiniappCompanionAuthoringDeclarations, type MiniappCompanionManifestDeclarations, type MiniappCompanionTarget } from './companion-types';
+export * from './companion-types';
+interface PrepareMiniappCompanionsOptions {
+    root: string;
+    outputRoot: string;
+    platforms?: readonly string[];
+    /** 本地调试仅准备当前 PC 目标；构建省略此项，校验全部目标。 */
+    targets?: readonly MiniappCompanionTarget[];
+    copyArtifacts?: boolean;
+    onPreparedArtifact?: (artifact: {
+        archive: Buffer;
+        path: string;
+        size: number;
+        sourcePath: string;
+    }) => void;
+}
+export declare function prepareMiniappCompanions(declarations: MiniappCompanionAuthoringDeclarations | undefined, options: PrepareMiniappCompanionsOptions): MiniappCompanionManifestDeclarations | undefined;

package/types/miniapp-manifest/index.d.ts

@@ -1,3 +1,5 @@
 export * from './schema';
 export * from './node';
 export * from './permissions';
+export * from './companions';
+export * from './companion-types';

package/types/miniapp-manifest/node.d.ts

@@ -1,4 +1,13 @@
 import { type ParsedMiniappPermissions } from './permissions';
+import type { MiniappCompanionAuthoringDeclarations } from './companion-types';
+import type { MiniappPlatform } from './schema';
 export declare function readMiniappVersionFromPackageJson(root: string): string;
+/** Companion source 始终相对声明所在 package.json，而非 Vite 的 HTML root。 */
+export declare function readMiniappCompanionsFromPackageJson(root: string): {
+    declarations: MiniappCompanionAuthoringDeclarations | undefined;
+    projectRoot: string;
+    packageJsonPath: string;
+};
+export declare function readMiniappPlatformsFromPackageJson(root: string): readonly MiniappPlatform[];
 export declare function readMiniappPermissionsFromPackageJson(root: string, sdkVersion: string): ParsedMiniappPermissions;
 export declare function resolveMiniappSdkVersion(): string;

package/types/miniapp-manifest/permissions.d.ts

@@ -1,5 +1,5 @@
 import { type MiniProgramPermissionKey, type MiniProgramRuntimePermissionsSnapshot } from '@heybox/hb-sdk-protocol';
-export declare const MINIAPP_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network"];
+export declare const MINIAPP_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network", "companion"];
 export type MiniappPermissionKey = MiniProgramPermissionKey;
 export interface SimpleMiniappPermissionDeclaration {
     enabled: true;