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

package/dist/devtools/browser-dev-host/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f4f5f7" />
     <title>小程序工坊调试台</title>
-    <script type="module" crossorigin src="/assets/index-C5MZZDa5.js"></script>
+    <script type="module" crossorigin src="/assets/index-B-NHlLsr.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/workbench-state-BwV7bm4n.js">
     <link rel="stylesheet" crossorigin href="/assets/index-P-ra4m1y.css">
   </head>

package/dist/index.cjs.js

@@ -799,7 +799,50 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0';
+    : '0.8.1-alpha.2';
+
+const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
+const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
+/** 创建环境信息模块。 */
+function createEnvironmentModule(reader) {
+    return {
+        getInfo: () => reader.getEnvironmentInfo(),
+        getInfoSync: () => reader.getEnvironmentInfoSync(),
+    };
+}
+/** 将不可信 wire 值逐字段降级为固定、深度冻结的公开快照。 */
+function normalizeMiniProgramEnvironmentInfo(value) {
+    const root = readRecord$1(value);
+    const runtime = readRecord$1(root?.runtime);
+    const host = readRecord$1(root?.host);
+    const miniProgram = readRecord$1(root?.miniProgram);
+    const operatingSystem = readRecord$1(root?.operatingSystem);
+    return Object.freeze({
+        runtime: Object.freeze({
+            mode: RUNTIME_MODES.has(runtime?.mode) ? runtime?.mode : 'unknown',
+        }),
+        host: Object.freeze({
+            appVersion: readOptionalString(host?.appVersion),
+        }),
+        miniProgram: Object.freeze({
+            id: readOptionalString(miniProgram?.id),
+            version: readOptionalString(miniProgram?.version),
+        }),
+        operatingSystem: Object.freeze({
+            name: OPERATING_SYSTEM_NAMES.has(operatingSystem?.name)
+                ? operatingSystem?.name
+                : 'unknown',
+            version: readOptionalString(operatingSystem?.version),
+        }),
+        sdk: Object.freeze({ version: HB_SDK_VERSION }),
+    });
+}
+function readOptionalString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function readRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
 
 const DEFAULT_TIMEOUT = 10000;
 const HANDSHAKE_RETRY_INTERVAL = 250;
@@ -831,6 +874,7 @@ class MiniProgramBridgeClient {
     destroyed = false;
     runtimeUnavailable = false;
     runtimeUnavailableError;
+    environmentInfo;
     constructor(options = {}) {
         this.timeout = options.timeout || DEFAULT_TIMEOUT;
         this.selfWindow = options.selfWindow || getGlobalWindow();
@@ -857,6 +901,21 @@ class MiniProgramBridgeClient {
     onHandshakeStateChange(handler) {
         return this.handshakeState.subscribe(handler);
     }
+    /** 等待握手后读取当前实例的环境快照。 */
+    async getEnvironmentInfo() {
+        await this.waitForHandshake();
+        return this.getEnvironmentInfoSync();
+    }
+    /** 同步读取握手期间缓存的环境快照。 */
+    getEnvironmentInfoSync() {
+        const state = this.handshakeState.getState();
+        if (state.status === 'failed')
+            throw state.error;
+        if (state.status !== 'ready' || !this.environmentInfo) {
+            throw createSDKError('ENVIRONMENT_NOT_READY', '环境信息将在 SDK ready 后可用');
+        }
+        return this.environmentInfo;
+    }
     /** 注册小程序事件监听。 */
     on(eventName, handler) {
         return this.eventBus.on(eventName, handler);
@@ -1109,7 +1168,10 @@ class MiniProgramBridgeClient {
         if (eventName === 'unload') {
             this.markRuntimeUnavailable();
         }
-        else if (eventName === 'ready' && !this.runtimeUnavailable) {
+        else if (eventName === 'ready' && !this.runtimeUnavailable && this.handshakeState.getState().status !== 'failed') {
+            if (!this.environmentInfo) {
+                this.environmentInfo = normalizeMiniProgramEnvironmentInfo(undefined);
+            }
             this.resolveHandshakeOnce();
         }
         else if (eventName === 'show' && !this.runtimeUnavailable) {
@@ -1118,6 +1180,12 @@ class MiniProgramBridgeClient {
         this.eventBus.emit(eventName, message.payload);
     }
     handleResponse(message) {
+        if (message.method === SDK_HANDSHAKE_METHOD && message.error === undefined) {
+            if (!this.environmentInfo) {
+                this.environmentInfo = normalizeMiniProgramEnvironmentInfo(readRecord(message.payload)?.environment);
+            }
+            return;
+        }
         if (!message.id) {
             return;
         }
@@ -1237,6 +1305,9 @@ class MiniProgramBridgeClient {
         this.pendingRequests.clear();
     }
 }
+function readRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
 function waitForHandshakeOrAbort(handshake, signal, createAbortError, getTerminalError) {
     if (!signal)
         return handshake;
@@ -3691,6 +3762,8 @@ class MiniProgramSDK {
     navigation;
     /** 云端数据相关开放能力。 */
     cloud;
+    /** 当前实例的环境信息。 */
+    environment;
     constructor(options) {
         const launchHref = (options?.selfWindow ?? getGlobalWindow())?.location.href;
         this.client = new MiniProgramBridgeClient(options);
@@ -3705,6 +3778,7 @@ class MiniProgramSDK {
         this.device = createDeviceModule(this.client);
         this.navigation = createNavigationModule(this.client);
         this.cloud = createCloudModule(this.client);
+        this.environment = createEnvironmentModule(this.client);
     }
     /** 获取当前握手状态。 */
     getHandshakeState() {
@@ -4003,6 +4077,11 @@ const cloud = {
         getInfo: (options) => getDefaultSDK().cloud.leaderboard.getInfo(options),
     },
 };
+/** 默认 SDK 实例的 environment 模块。 */
+const environment = {
+    getInfo: () => getDefaultSDK().environment.getInfo(),
+    getInfoSync: () => getDefaultSDK().environment.getInfoSync(),
+};
 
 const hbSDK = {
     getHandshakeState,
@@ -4018,6 +4097,7 @@ const hbSDK = {
     network,
     ui,
     device,
+    environment,
     navigation,
     cloud,
 };
@@ -4029,6 +4109,7 @@ exports.auth = auth;
 exports.cloud = cloud;
 exports.default = hbSDK;
 exports.device = device;
+exports.environment = environment;
 exports.files = files;
 exports.getHandshakeState = getHandshakeState;
 exports.navigation = navigation;

package/dist/index.esm.js

@@ -795,7 +795,50 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0';
+    : '0.8.1-alpha.2';
+
+const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
+const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
+/** 创建环境信息模块。 */
+function createEnvironmentModule(reader) {
+    return {
+        getInfo: () => reader.getEnvironmentInfo(),
+        getInfoSync: () => reader.getEnvironmentInfoSync(),
+    };
+}
+/** 将不可信 wire 值逐字段降级为固定、深度冻结的公开快照。 */
+function normalizeMiniProgramEnvironmentInfo(value) {
+    const root = readRecord$1(value);
+    const runtime = readRecord$1(root?.runtime);
+    const host = readRecord$1(root?.host);
+    const miniProgram = readRecord$1(root?.miniProgram);
+    const operatingSystem = readRecord$1(root?.operatingSystem);
+    return Object.freeze({
+        runtime: Object.freeze({
+            mode: RUNTIME_MODES.has(runtime?.mode) ? runtime?.mode : 'unknown',
+        }),
+        host: Object.freeze({
+            appVersion: readOptionalString(host?.appVersion),
+        }),
+        miniProgram: Object.freeze({
+            id: readOptionalString(miniProgram?.id),
+            version: readOptionalString(miniProgram?.version),
+        }),
+        operatingSystem: Object.freeze({
+            name: OPERATING_SYSTEM_NAMES.has(operatingSystem?.name)
+                ? operatingSystem?.name
+                : 'unknown',
+            version: readOptionalString(operatingSystem?.version),
+        }),
+        sdk: Object.freeze({ version: HB_SDK_VERSION }),
+    });
+}
+function readOptionalString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function readRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
 
 const DEFAULT_TIMEOUT = 10000;
 const HANDSHAKE_RETRY_INTERVAL = 250;
@@ -827,6 +870,7 @@ class MiniProgramBridgeClient {
     destroyed = false;
     runtimeUnavailable = false;
     runtimeUnavailableError;
+    environmentInfo;
     constructor(options = {}) {
         this.timeout = options.timeout || DEFAULT_TIMEOUT;
         this.selfWindow = options.selfWindow || getGlobalWindow();
@@ -853,6 +897,21 @@ class MiniProgramBridgeClient {
     onHandshakeStateChange(handler) {
         return this.handshakeState.subscribe(handler);
     }
+    /** 等待握手后读取当前实例的环境快照。 */
+    async getEnvironmentInfo() {
+        await this.waitForHandshake();
+        return this.getEnvironmentInfoSync();
+    }
+    /** 同步读取握手期间缓存的环境快照。 */
+    getEnvironmentInfoSync() {
+        const state = this.handshakeState.getState();
+        if (state.status === 'failed')
+            throw state.error;
+        if (state.status !== 'ready' || !this.environmentInfo) {
+            throw createSDKError('ENVIRONMENT_NOT_READY', '环境信息将在 SDK ready 后可用');
+        }
+        return this.environmentInfo;
+    }
     /** 注册小程序事件监听。 */
     on(eventName, handler) {
         return this.eventBus.on(eventName, handler);
@@ -1105,7 +1164,10 @@ class MiniProgramBridgeClient {
         if (eventName === 'unload') {
             this.markRuntimeUnavailable();
         }
-        else if (eventName === 'ready' && !this.runtimeUnavailable) {
+        else if (eventName === 'ready' && !this.runtimeUnavailable && this.handshakeState.getState().status !== 'failed') {
+            if (!this.environmentInfo) {
+                this.environmentInfo = normalizeMiniProgramEnvironmentInfo(undefined);
+            }
             this.resolveHandshakeOnce();
         }
         else if (eventName === 'show' && !this.runtimeUnavailable) {
@@ -1114,6 +1176,12 @@ class MiniProgramBridgeClient {
         this.eventBus.emit(eventName, message.payload);
     }
     handleResponse(message) {
+        if (message.method === SDK_HANDSHAKE_METHOD && message.error === undefined) {
+            if (!this.environmentInfo) {
+                this.environmentInfo = normalizeMiniProgramEnvironmentInfo(readRecord(message.payload)?.environment);
+            }
+            return;
+        }
         if (!message.id) {
             return;
         }
@@ -1233,6 +1301,9 @@ class MiniProgramBridgeClient {
         this.pendingRequests.clear();
     }
 }
+function readRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
 function waitForHandshakeOrAbort(handshake, signal, createAbortError, getTerminalError) {
     if (!signal)
         return handshake;
@@ -3687,6 +3758,8 @@ class MiniProgramSDK {
     navigation;
     /** 云端数据相关开放能力。 */
     cloud;
+    /** 当前实例的环境信息。 */
+    environment;
     constructor(options) {
         const launchHref = (options?.selfWindow ?? getGlobalWindow())?.location.href;
         this.client = new MiniProgramBridgeClient(options);
@@ -3701,6 +3774,7 @@ class MiniProgramSDK {
         this.device = createDeviceModule(this.client);
         this.navigation = createNavigationModule(this.client);
         this.cloud = createCloudModule(this.client);
+        this.environment = createEnvironmentModule(this.client);
     }
     /** 获取当前握手状态。 */
     getHandshakeState() {
@@ -3999,6 +4073,11 @@ const cloud = {
         getInfo: (options) => getDefaultSDK().cloud.leaderboard.getInfo(options),
     },
 };
+/** 默认 SDK 实例的 environment 模块。 */
+const environment = {
+    getInfo: () => getDefaultSDK().environment.getInfo(),
+    getInfoSync: () => getDefaultSDK().environment.getInfoSync(),
+};
 
 const hbSDK = {
     getHandshakeState,
@@ -4014,8 +4093,9 @@ const hbSDK = {
     network,
     ui,
     device,
+    environment,
     navigation,
     cloud,
 };
 
-export { HbMiniProgramNetworkError, HbMiniProgramSDKError, USER_INFO_AUTHORIZATION_SCOPES, auth, cloud, hbSDK as default, device, files, getHandshakeState, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport };
+export { HbMiniProgramNetworkError, HbMiniProgramSDKError, USER_INFO_AUTHORIZATION_SCOPES, auth, cloud, hbSDK as default, device, environment, files, getHandshakeState, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport };

package/dist/vite.cjs.js

@@ -8,7 +8,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0';
+    : '0.8.1-alpha.2';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/dist/vite.esm.js

@@ -5,7 +5,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0';
+    : '0.8.1-alpha.2';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.0",
+  "version": "0.8.1-alpha.2",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -62,7 +62,7 @@
     "skills": "1.5.23",
     "undici": "^7.28.0",
     "ws": "^8.18.0",
-    "@heybox/hb-sdk-protocol": "0.8.0"
+    "@heybox/hb-sdk-protocol": "0.8.1-alpha.2"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -113,13 +113,13 @@
     "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox/hb-api": "~1.28.2",
-    "@heybox/hb-sdk-runtime": "~0.8.0",
-    "@heybox/runtime": "~0.2.0",
+    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.2",
     "@heybox/runtime-policy": "~0.2.0",
-    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox/runtime-transport-fetch": "~0.2.0"
+    "@heybox/runtime-transport-fetch": "~0.2.0",
+    "@heybox/runtime": "~0.2.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -183,14 +183,12 @@
     "changelog:draft": "node scripts/changelog-draft.cjs",
     "check:changelog": "node scripts/check-changelog.cjs",
     "release:verify-tarball": "node scripts/skill/verify-tarball-install.mjs",
-    "test:release": "node --test scripts/public-changelog.test.mjs scripts/public-changelog-workflow.test.cjs scripts/release-family.test.cjs ../../ops/jobs/publish-changed-packages/publish.test.cjs ../../ops/jobs/release-hb-sdk/docs-release-contract.test.cjs ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.test.cjs",
+    "test:release": "node --test scripts/public-changelog.test.mjs scripts/public-changelog-workflow.test.cjs scripts/release-family.test.cjs ../../ops/jobs/publish-changed-packages/publish.test.cjs",
     "test:compatibility-evidence": "node --test scripts/validate-compatibility-evidence.test.mjs",
     "release:prepare": "node scripts/release-prepare.cjs",
     "release:tag": "node scripts/release-tag.cjs",
     "release:family:dry-run": "node ../../ops/jobs/publish-changed-packages/publish.cjs --dry-run",
     "release:family:promote": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action promote",
-    "release:family:rollback": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action rollback",
-    "release:stable:promote": "node ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.cjs --action promote",
-    "release:stable:rollback": "node ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.cjs --action rollback"
+    "release:family:rollback": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action rollback"
   }
 }

package/skill/SKILL.md

@@ -52,6 +52,8 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 12. Use `share.showShareMenu({ extra })` to open the share menu or `share.copyLink({ extra })` to copy and return the mini-program share link. `share.showShareMenu()` always uses the platform `common_share` landing page and does not accept a custom `url`. Read the JSON-compatible page state synchronously with `share.getExtra()` after launch, validate the developer-defined fields, and fall back to the default page when it returns `undefined`.
 13. New PC enables the retained `files` and `network.download()` contract with persistent sandbox storage, single-file/directory pickers, exact File saving, and public-network streaming downloads. Mobile, Web, Browser Dev Host, and legacy PC return `METHOD_FORBIDDEN` and provide no memory/Blob fallback. Call `files.pickFiles()` / `pickDirectory()` / `saveFile()` only from trusted user actions; `saveFile()` accepts only `suggestedName`, `remove()` only deletes sandbox objects, and non-empty directories require `remove({ recursive: true })`.
 14. Use `network.download()` only with an SDK-created File/Directory target. It is GET-only, does not follow redirects, and exposes local `AbortSignal` / progress callbacks without sending functions over the bridge. Abort is a cancellation intent; a Host commit that already won still resolves successfully.
+15. Use `environment.getInfo()` for the immutable runtime, Host App, canonical Mini-program, operating-system, and SDK version snapshot. It waits for the handshake automatically. Use `environment.getInfoSync()` only after `getHandshakeState().status === 'ready'` or inside a ready-state subscription; before that it throws `ENVIRONMENT_NOT_READY`.
+16. Treat missing environment strings as `null` and unknown enum values as `unknown`. Only `sdk.version` is SemVer; do not compare the other opaque version strings or use any environment field for authentication, authorization, or risk control.
 
 ## Step 5: Use CLI workflows
 
@@ -88,6 +90,7 @@ For workshop mini-program business code:
 7. Do not use `network.request()` to reach platform-reserved runtime auth or OpenAPI internal paths.
 8. Do not expose credentials or describe internal Host authorization state machines and routes in app-facing guidance.
 9. Do not invent string paths, File System Access API handles, Blob downloads, uploads, Range/resume, external deletion, move, append, or persistent external grants. Public file operations use only SDK-created handles; deletion is limited to SDK sandbox handles.
+10. Do not treat `environment.*` as a device-fingerprint or trusted backend signal. It intentionally excludes account data, device identifiers, model, UA, CPU, and memory; use `viewport.getWindowInfo()` for screen geometry.
 
 For CLI and local development:
 

package/skill/references/api-protocol.md

@@ -176,7 +176,10 @@ export type {
   MiniProgramNetworkMethod,
   MiniProgramNetworkParams,
   MiniProgramNetworkRequestMethod,
+  MiniProgramOperatingSystemName,
   MiniProgramRuntimePermissionEntry,
+  MiniProgramRuntimeEnvironmentInfo,
+  MiniProgramRuntimeMode,
   MiniProgramRuntimePermissionsSnapshot,
   MiniProgramRuntimePermissionStatus,
   MiniProgramSafeArea,
@@ -215,6 +218,7 @@ export type {
   SaveFilePayload,
   SaveFileResult,
   SDKHandshakePayload,
+  SDKHandshakeResult,
   SetClipboardPayload,
   SetClipboardResult,
   SetNavigationBarStylePayload,
@@ -295,12 +299,12 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 4 | 65 | 60 | 1 |
-| Protocol API | 0 | 13 | 56 | 90 | 47 |
+| Root API | 2 | 4 | 67 | 62 | 2 |
+| Protocol API | 0 | 13 | 58 | 90 | 47 |
 | Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
 | Vite API | 0 | 1 | 5 | 1 | 1 |
 
-<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=3; fingerprint=660a21ad77c32f30dbc7ebb02b053ebce2a7c6e7301cc805a5cdd1a75572fbb2 -->
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=4; fingerprint=1b6c6a8f921122d588700ac1323b6c46a2ee6d331c585078527612b218546757 -->
 
 ## SDK API
 

package/skill/references/api-root.md

@@ -9,6 +9,7 @@
 - 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/cli.md
@@ -19,12 +20,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.2`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -47,6 +49,7 @@ export {
   network,
   ui,
   device,
+  environment,
   navigation,
   cloud,
 } from './core/singleton';
@@ -165,6 +168,12 @@ export type {
   VibratePayload,
   VibrateResult,
 } from './modules/device';
+export type {
+  MiniProgramEnvironmentInfo,
+  MiniProgramEnvironmentModule,
+  MiniProgramOperatingSystemName,
+  MiniProgramRuntimeMode,
+} from './modules/environment';
 export type {
   ClosePayload,
   CloseResult,
@@ -189,6 +198,7 @@ import {
   auth,
   cloud,
   device,
+  environment,
   getHandshakeState,
   navigation,
   network,
@@ -217,6 +227,7 @@ const hbSDK = {
   network,
   ui,
   device,
+  environment,
   navigation,
   cloud,
 };
@@ -648,6 +659,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,6 +787,7 @@ 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` 表示网络空闲超时，失败不会改动原目标。
 - `DOWNLOAD_HTTP_STATUS` 的 `data` 只包含脱敏后的 `status`、可选 `statusText` 和安全响应头。
@@ -750,6 +852,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | 模块         | 用途                                            |
 | ------------ | ----------------------------------------------- |
 | `auth`       | 获取交给开发者服务端交换的短期授权码            |
+| `environment` | 读取当前实例的冻结环境快照                      |
 | `user`       | 读取 Host 当前用户资料、隔离身份或撤销授权      |
 | `share`      | 打开分享、复制链接或截图分享流程                |
 | `ui`         | 展示 Toast 和 Loading                           |

package/skill/references/recipes.md

@@ -413,6 +413,7 @@ 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` 表示网络空闲超时，失败不会改动原目标。
 - `DOWNLOAD_HTTP_STATUS` 的 `data` 只包含脱敏后的 `status`、可选 `statusText` 和安全响应头。

package/skill/skill.json

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