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

package/skill/references/api-root.md

@@ -9,8 +9,10 @@
 - packages/hb-sdk/src/vite/index.ts
 - packages/hb-sdk/README.md
 - apps/docs/hb-sdk/guide/quick-start.md
+- apps/docs/hb-sdk/guide/environment.md
 - apps/docs/hb-sdk/guide/error-handling.md
 - apps/docs/hb-sdk/guide/lifecycle.md
+- apps/docs/hb-sdk/guide/companion.md
 - apps/docs/hb-sdk/guide/cli.md
 
 ## Contents
@@ -19,12 +21,13 @@
 - [Public root entrypoint](#public-root-entrypoint)
 - [Vite plugin export](#vite-plugin-export)
 - [App-facing concepts](#app-facing-concepts)
+- [Environment info](#environment-info)
 - [Public modules](#public-modules)
 - [Cloud leaderboard](#cloud-leaderboard)
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.8.0`
+- Version at generation time: `0.8.1-alpha.10`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -47,12 +50,35 @@ export {
   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,
@@ -165,6 +191,12 @@ export type {
   VibratePayload,
   VibrateResult,
 } from './modules/device';
+export type {
+  MiniProgramEnvironmentInfo,
+  MiniProgramEnvironmentModule,
+  MiniProgramOperatingSystemName,
+  MiniProgramRuntimeMode,
+} from './modules/environment';
 export type {
   ClosePayload,
   CloseResult,
@@ -188,7 +220,9 @@ export type {
 import {
   auth,
   cloud,
+  companion,
   device,
+  environment,
   getHandshakeState,
   navigation,
   network,
@@ -217,8 +251,10 @@ const hbSDK = {
   network,
   ui,
   device,
+  environment,
   navigation,
   cloud,
+  companion,
 };
 
 export default hbSDK;
@@ -229,227 +265,59 @@ export default hbSDK;
 Use `@heybox/hb-sdk/vite` only in `vite.config.ts`. Do not import it from iframe mini-program business code.
 
 ```ts
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-import { HB_SDK_VERSION } from '../core/version';
-import { MINI_DEV_CONSOLE_EVENT_TYPE, MINI_DEV_IFRAME_WINDOW_NAME, MINI_DEV_CONSOLE_INSTALL_FLAG } from '../core/mini-dev-console';
-import {
-  MINIAPP_PLATFORM_VALUES,
-  renderMiniappManifest,
-  validateMiniappPackageVersionForBuild,
-  validateMiniappPlatforms,
-  type MiniappPlatform,
-} from '../miniapp-manifest/schema';
-import { readMiniappVersionFromPackageJson } from '../miniapp-manifest/node';
-import { readMiniappPermissionsFromPackageJson } from '../miniapp-manifest/node';
-import { getMissingPermissionsWarning } from '../miniapp-manifest/permissions';
-import { enforceMiniappHtmlPolicy } from './html-policy';
-import { shouldSkipMiniappPlatformCspFromEnv } from './runtime-permission-env';
-
 export interface MiniappManifestPlugin {
-  name: string;
-  config: (config: MiniappManifestUserConfig, env?: { command: 'build' | 'serve' }) => MiniappManifestUserConfig | void;
-  configResolved: (resolved: MiniappManifestResolvedConfig) => void;
-  /** Rollup 在构建失败后仍会跑 closeBundle；用 buildEnd 记录真实错误，避免二次校验掩盖原因。 */
-  buildEnd: (error?: Error) => void;
-  transformIndexHtml: (html: string) => string;
-  closeBundle: (this: MiniappManifestPluginContext) => Promise<void>;
+    name: string;
+    config: (config: MiniappManifestUserConfig, env?: {
+        command: 'build' | 'serve';
+    }) => MiniappManifestUserConfig | void;
+    configResolved: (resolved: MiniappManifestResolvedConfig) => void;
+    configureServer: (server: MiniappManifestDevServer) => void;
+    /** Rollup 在构建失败后仍会跑 closeBundle；用 buildEnd 记录真实错误，避免二次校验掩盖原因。 */
+    buildEnd: (error?: Error) => void;
+    transformIndexHtml: (html: string) => string;
+    closeBundle: (this: MiniappManifestPluginContext) => Promise<void>;
+}
+
+export interface MiniappManifestDevServer {
+    httpServer?: Server | null;
+    restart?: (forceOptimize?: boolean) => Promise<void>;
+    middlewares: {
+        use: (handler: (request: IncomingMessage, response: ServerResponse, next: () => void) => void) => void;
+    };
 }
 
 export interface MiniappManifestUserConfig {
-  base?: string;
-  define?: Record<string, string>;
+    base?: string;
+    define?: Record<string, string>;
 }
 
 export interface MiniappManifestPluginContext {
-  warn: (message: string) => void;
+    warn: (message: string) => void;
 }
 
 export interface MiniappManifestResolvedConfig {
-  root: string;
-  command: 'build' | 'serve';
-  build: {
-    outDir: string;
-  };
-  server: {
-    host?: string | boolean;
-    https?: boolean | Record<string, unknown>;
-    port?: number;
-    hmr?:
-      | boolean
-      | {
-          clientPort?: number;
-          host?: string;
-          port?: number;
-          protocol?: 'ws' | 'wss';
+    root: string;
+    command: 'build' | 'serve';
+    build: {
+        outDir: string;
+    };
+    server: {
+        host?: string | boolean;
+        https?: boolean | Record<string, unknown>;
+        port?: number;
+        hmr?: boolean | {
+            clientPort?: number;
+            host?: string;
+            port?: number;
+            protocol?: 'ws' | 'wss';
         };
-  };
-  plugins?: readonly { name?: string }[];
-}
-
-export { MINIAPP_PLATFORM_VALUES };
-export type { MiniappPlatform };
-
-/**
- * dev serve 时在入口 HTML 最早位置注入无依赖 console 捕获 bootstrap。
- *
- * 必须内联完整 patch 逻辑而非等 SDK 模块加载：vite client、业务代码的 console 调用
- * 都可能早于 SDK 单例初始化（如 [vite] connecting）。捕获条件：
- * 1. 构建期只有 vite serve 走到本分支（生产构建无此代码，双保险之 define 常量仍注入给 SDK 侧）；
- * 2. 运行期仅调试 iframe（window.name 标记由调试台 iframe.name 与本 bootstrap 设置）激活。
- * 转发经 window.parent.postMessage（CSP connect-src 不约束 postMessage），失败静默，
- * 严禁回打 console 造成自触发循环。SDK 侧 installMiniDevConsoleForwarding 安装时
- * 检测同款 INSTALL_FLAG，不会重复 patch。
- */
-function injectMiniDevConsoleBootstrap(html: string): string {
-  const bootstrap = `<script>(function(){var LEVELS=['log','debug','info','warn','error'];var FLAG='${MINI_DEV_CONSOLE_INSTALL_FLAG}';var TYPE='${MINI_DEV_CONSOLE_EVENT_TYPE}';if(window.name!=='${MINI_DEV_IFRAME_WINDOW_NAME}')window.name='${MINI_DEV_IFRAME_WINDOW_NAME}';if(window[FLAG])return;var patched=false;for(var i=0;i<LEVELS.length;i++)(function(level){var original=console[level];if(typeof original!=='function')return;console[level]=function(){try{parent.postMessage({type:TYPE,detail:{level:level,args:Array.prototype.slice.call(arguments),timestamp:Date.now()}},'*')}catch(e){}return original.apply(this,arguments)};patched=true})(LEVELS[i]);if(patched)window[FLAG]=true})();</script>`;
-  const headIndex = html.indexOf('<head>');
-  if (headIndex < 0) {
-    return html;
-  }
-  const insertAt = headIndex + '<head>'.length;
-  return `${html.slice(0, insertAt)}${bootstrap}${html.slice(insertAt)}`;
-}
-
-export interface MiniappManifestOptions {
-  platforms: readonly MiniappPlatform[];
+    };
+    plugins?: readonly {
+        name?: string;
+    }[];
 }
 
-const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
-const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
-const miniDevLoggingConstant = ['__HB_SDK_DEV', 'LOGGING__'].join('_');
-
-export function miniappManifest(options: MiniappManifestOptions): MiniappManifestPlugin {
-  const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
-  const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
-  let root = process.cwd();
-  let outDir = 'dist';
-  let command: 'build' | 'serve' = 'build';
-  let hmrWebSocketUrl: string | undefined;
-  /** 构建链路中更早的失败原因；closeBundle 不得再用产物校验覆盖它。 */
-  let priorBuildError: Error | undefined;
-
-  return {
-    name: 'heybox-miniapp-manifest',
-    config(config, env) {
-      assertMiniappViteBase(config.base);
-      // command 在本钩子时序早于 configResolved，必须取自 env 命令而非闭包；
-      // 旧调用方（测试等）未传 env 时按 build 处理。
-      const isServe = env?.command === 'serve';
-      return {
-        ...(config.base === undefined ? { base: './' } : {}),
-        define: {
-          [sdkVersionBuildConstant]: JSON.stringify(resolveSdkVersion()),
-          // 仅 vite serve（hb-sdk dev）注入；vite build / hb-sdk build 永不注入，捕获模块被死代码消除。
-          ...(isServe ? { [miniDevLoggingConstant]: 'true' } : {}),
-        },
-      };
-    },
-    configResolved(resolved) {
-      if (resolved.plugins) {
-        const manifestPluginCount = resolved.plugins.filter((plugin) => plugin.name === 'heybox-miniapp-manifest').length;
-        if (manifestPluginCount !== 1) {
-          throw new Error(`Vite 配置必须且只能包含一个 miniappManifest() 插件，当前数量：${manifestPluginCount}`);
-        }
-      }
-      root = resolved.root;
-      outDir = resolved.build.outDir;
-      command = resolved.command;
-      hmrWebSocketUrl = resolveHmrWebSocketUrl(resolved);
-    },
-    buildEnd(error) {
-      if (error) {
-        priorBuildError = priorBuildError ?? toError(error);
-      }
-    },
-    transformIndexHtml(html) {
-      const enforced = enforceMiniappHtmlPolicy(html, {
-        ...(command === 'serve' ? { hmrWebSocketUrl } : {}),
-        skipPlatformCsp,
-      });
-      return command === 'serve' ? injectMiniDevConsoleBootstrap(enforced) : enforced;
-    },    async closeBundle() {
-      // Rollup 在 buildStart/transform 失败后仍会调用 closeBundle。
-      // 若此时再抛「缺 index.html」等二次错误，会掩盖真实失败原因。
-      if (priorBuildError) {
-        throw priorBuildError;
-      }
-
-      const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
-      const sdkVersion = resolveSdkVersion();
-      const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
-      if (!parsedPermissions.declared) this.warn(getMissingPermissionsWarning());
-      const outputRoot = path.resolve(root, outDir);
-      const htmlFiles = collectHtmlFiles(outputRoot);
-      const unexpectedHtmlFiles = htmlFiles.filter((file) => path.relative(outputRoot, file) !== 'index.html');
-      if (unexpectedHtmlFiles.length > 0) {
-        throw new Error(
-          `工坊小程序只支持单页应用，构建产物不允许额外 HTML：${unexpectedHtmlFiles
-            .map((file) => path.relative(outputRoot, file).split(path.sep).join('/'))
-            .join(', ')}`,
-        );
-      }
-      const indexHtmlPath = path.join(outputRoot, 'index.html');
-      if (!htmlFiles.includes(indexHtmlPath)) {
-        throw new Error('构建产物必须包含入口 dist/index.html');
-      }
-      writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(readFileSync(indexHtmlPath, 'utf8'), { skipPlatformCsp }));
-
-      const manifestPath = path.join(outputRoot, 'manifest.json');
-      mkdirSync(path.dirname(manifestPath), { recursive: true });
-      writeFileSync(
-        manifestPath,
-        renderMiniappManifest({
-          version,
-          sdkVersion,
-          platforms,
-          ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
-        }),
-      );
-    },
-  };
-}
-
-function assertMiniappViteBase(base: string | undefined) {
-  if (base !== undefined && base !== '' && base !== './') {
-    throw new Error(`工坊小程序 Vite base 仅支持空字符串或 "./"，当前值：${base}`);
-  }
-}
-
-function toError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-function collectHtmlFiles(root: string) {
-  const files: string[] = [];
-  if (!existsSync(root)) return files;
-  for (const entry of readdirSync(root, { withFileTypes: true })) {
-    const fullPath = path.join(root, entry.name);
-    if (entry.isDirectory()) files.push(...collectHtmlFiles(fullPath));
-    else if (entry.isFile() && path.extname(entry.name).toLowerCase() === '.html') files.push(fullPath);
-  }
-  return files;
-}
-
-function resolveSdkVersion() {
-  if (HB_SDK_VERSION !== sdkVersionPlaceholder) return HB_SDK_VERSION;
-  const packageJson = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as { version?: unknown };
-  if (typeof packageJson.version !== 'string' || !packageJson.version) {
-    throw new Error('未能读取 @heybox/hb-sdk 当前版本号');
-  }
-  return packageJson.version;
-}
-
-function resolveHmrWebSocketUrl(resolved: MiniappManifestResolvedConfig) {
-  const hmr = resolved.server.hmr;
-  if (hmr === false) return undefined;
-  const options = typeof hmr === 'object' ? hmr : {};
-  const protocol = options.protocol ?? (resolved.server.https ? 'wss' : 'ws');
-  const configuredHost = options.host ?? resolved.server.host;
-  const host = typeof configuredHost === 'string' && configuredHost !== '0.0.0.0' ? configuredHost : '127.0.0.1';
-  const port = options.clientPort ?? options.port ?? resolved.server.port;
-  return `${protocol}://${host}${port ? `:${port}` : ''}`;
-}
+export declare function miniappManifest(): MiniappManifestPlugin;
 ```
 
 ## 生产构建
@@ -458,7 +326,7 @@ function resolveHmrWebSocketUrl(resolved: MiniappManifestResolvedConfig) {
 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 构建检查始终保留。
 
@@ -648,6 +516,96 @@ async function saveFromUserAction(text: string) {
 
 大多数小程序页面都应该使用默认实例。0.6 起不再对业务代码提供独立实例工厂。
 
+## Environment info
+
+
+# 环境信息
+
+`environment` 模块提供当前小程序实例的静态环境快照，包括运行模式、小黑盒 App 版本、canonical 小程序身份、操作系统和 SDK 版本。该能力无需在 `heybox.permissions` 中声明，也不会触发用户授权。
+
+## 推荐用法
+
+优先使用异步方法。SDK 尚未完成握手时，`getInfo()` 会自动等待：
+
+```ts
+import { environment } from '@heybox/hb-sdk'
+
+const info = await environment.getInfo()
+
+console.log(info.runtime.mode)
+console.log(info.host.appVersion)
+console.log(info.miniProgram.id, info.miniProgram.version)
+console.log(info.operatingSystem.name, info.operatingSystem.version)
+console.log(info.sdk.version)
+```
+
+返回对象采用固定结构并深度冻结：
+
+```ts
+interface MiniProgramEnvironmentInfo {
+  readonly runtime: {
+    readonly mode: 'production' | 'preview' | 'development' | 'unknown'
+  }
+  readonly host: {
+    readonly appVersion: string | null
+  }
+  readonly miniProgram: {
+    readonly id: string | null
+    readonly version: string | null
+  }
+  readonly operatingSystem: {
+    readonly name: 'android' | 'ios' | 'ohos' | 'windows' | 'macos' | 'linux' | 'unknown'
+    readonly version: string | null
+  }
+  readonly sdk: {
+    readonly version: string
+  }
+}
+```
+
+## 同步读取
+
+只有已经确认 SDK 为 `ready` 时才能调用 `getInfoSync()`。SDK 会在派发 `ready` 状态前缓存环境快照，因此可以在握手状态订阅中同步读取：
+
+```ts
+import { environment, onHandshakeStateChange } from '@heybox/hb-sdk'
+
+const unsubscribe = onHandshakeStateChange(state => {
+  if (state.status !== 'ready') return
+
+  const info = environment.getInfoSync()
+  console.log(info.operatingSystem.name)
+})
+```
+
+握手完成前调用会抛出 `HbMiniProgramSDKError`，错误码为 `ENVIRONMENT_NOT_READY`。通常不需要自行等待握手；不要求同步执行的代码直接使用 `await environment.getInfo()`。
+
+## 字段语义
+
+| 字段                      | 语义                                                                                                           |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `runtime.mode`            | 当前实例的粗粒度运行模式。正式发布为 `production`，版本预览为 `preview`，本地或 Dev Session 为 `development`。 |
+| `host.appVersion`         | 当前小黑盒 App 版本。它是 Host 提供的不透明字符串。                                                            |
+| `miniProgram.id`          | 平台确认的 canonical `mini_program_id`，不返回数字 ID、用户 ID 或其他旧 ID。                                   |
+| `miniProgram.version`     | 当前加载的小程序版本，是不透明字符串。                                                                         |
+| `operatingSystem.name`    | Host 明确提供的标准系统枚举，不从小程序 iframe 的 UA 推断。                                                    |
+| `operatingSystem.version` | Host 明确提供的系统版本；当前 Host 未提供时为 `null`。                                                         |
+| `sdk.version`             | 当前页面实际运行的 `@heybox/hb-sdk` 版本，遵循 npm SemVer。                                                    |
+
+除 `sdk.version` 外，其他版本字段均不承诺 SemVer 或大小比较语义。需要判断某项能力是否可用时，应依据能力调用结果进行降级，不要仅比较 App 或系统版本。
+
+## 缺失与兼容
+
+旧 Host、匿名本地调试或未提供某个字段的 Host 仍会返回完整结构：缺失字符串为 `null`，未知枚举为 `'unknown'`。非法 Host 字段只会被逐项降级，不会阻断 SDK 握手。
+
+Browser Mock 在 Runtime 启动时使用当前设备预设作为操作系统名称，不读取开发者电脑的 UA。切换设备预设会保留当前 Runtime 和页面状态；需要重新生成环境快照时，使用调试台的重启操作。
+
+## 信任边界
+
+环境信息仅用于界面适配、兼容降级、埋点和诊断，不能用于鉴权、权限控制或风控。小程序提交给服务端的任何环境字段都可能被修改；服务端安全判断必须使用自身认证上下文或平台受信数据。
+
+该 API 不提供设备型号、品牌、UA、CPU、内存、设备唯一标识、账号信息或凭据。屏幕和安全区域继续通过 [`viewport.getWindowInfo()`](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/viewport/getWindowInfo/) 获取。
+
 
 # 错误处理
 
@@ -686,8 +644,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` 和必要的业务上下文，不要上报用户凭据或敏感数据。
@@ -741,6 +704,8 @@ 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)。
+
 ## Public modules
 
 ## 能力概览
@@ -750,6 +715,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | 模块         | 用途                                            |
 | ------------ | ----------------------------------------------- |
 | `auth`       | 获取交给开发者服务端交换的短期授权码            |
+| `environment` | 读取当前实例的冻结环境快照                      |
 | `user`       | 读取 Host 当前用户资料、隔离身份或撤销授权      |
 | `share`      | 打开分享、复制链接或截图分享流程                |
 | `ui`         | 展示 Toast 和 Loading                           |
@@ -760,6 +726,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/)。
 
@@ -818,6 +785,157 @@ 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 重放，业务必须按自身协议去重。
+
+
+# 受管桌面程序
+
+`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 真机验收。
 
 ## 云端排行榜