@heybox/hb-sdk 0.9.1-alpha.8 → 0.9.1

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

@@ -5,9 +5,9 @@
     <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-BZBZfB4t.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-BU-vzcs0.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-BRxbUJVN.css">
+    <script type="module" crossorigin src="/assets/index-Bpxbe1lP.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-sH2a_jbj.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-7Cq8iNcD.css">
   </head>
   <body>
     <div id="app"></div>

package/dist/index.cjs.js

@@ -282,10 +282,12 @@ function isPlainObject$2(value) {
  * `data` 仅作为可选调试信息，不保证结构稳定。错误码是跨 Host 的分支契约；
  * `message` 只用于日志和开发者提示，不应作为机器判断条件。
  *
- * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_DECLARED`
- * 或 `PERMISSION_DENIED`（检查 Manifest/平台批准）、`USER_GESTURE_REQUIRED`
+ * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_IN_SNAPSHOT`
+ *（当前运行快照缺少权限，需发布含声明的新版本或重新打开调试）、
+ * `PERMISSION_DENIED`（检查权限启用状态与平台批准）、`USER_GESTURE_REQUIRED`
  *（改为用户点击后重试）、`AUTHORIZATION_CANCELLED`（结束当前流程），以及
  * `METHOD_FORBIDDEN`（当前 Host 不支持该能力）。具体能力还可能返回模块专属错误码。
+ * 旧 Runtime 仍可能返回 `PERMISSION_NOT_DECLARED`；SDK 会保留 Host 返回的错误码。
  * 不要把所有错误都当作可重试错误，也不要把 `data` 当成稳定的序列化协议。
  *
    * @example
@@ -7278,7 +7280,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.8';
+    : '0.9.1';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -7324,8 +7326,8 @@ function readRecord$1(value) {
 }
 
 const DEFAULT_TIMEOUT = 10000;
-// 选择器等待由用户决定，使用长操作的生命周期清理，不设固定总时长。
-const FILE_PICKER_METHODS = new Set([FILES_PICK_FILES_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_SAVE_FILE_METHOD]);
+// 选择器等待、截图延迟与排队由 Host 管理，使用长操作生命周期，不设固定总时长。
+const HOST_MANAGED_TIMEOUT_METHODS = new Set([FILES_PICK_FILES_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_SAVE_FILE_METHOD, SHARE_SCREENSHOT_METHOD]);
 const HANDSHAKE_RETRY_INTERVAL = 250;
 /** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
 class MiniProgramBridgeClient {
@@ -7407,7 +7409,7 @@ class MiniProgramBridgeClient {
     }
     /** 调用父容器开放能力。 */
     async request(method, ...args) {
-        return this.performRequest(method, args[0], !FILE_PICKER_METHODS.has(method));
+        return this.performRequest(method, args[0], !HOST_MANAGED_TIMEOUT_METHODS.has(method));
     }
     /** 发起不使用固定总时长 timer 的长操作。 */
     async requestOperation(method, payload, options = {}) {
@@ -8509,8 +8511,8 @@ function createCompanionModule(requester) {
  * `options.extra` 时生成不带扩展数据的链接。
  * @returns Host 完成剪贴板写入后 resolve 的完整分享链接；返回字符串与剪贴板内容一致。
  * @throws {@link HbMiniProgramSDKError} 参数、`extra` 编码或小程序身份不合法时返回
- * `INVALID_PARAMS`；未声明或未启用 `share` 权限时分别返回
- * `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`；当前 Host 未开放剪贴板能力时可返回
+ * `INVALID_PARAMS`；当前运行快照缺少或未启用 `share` 权限时分别返回
+ * `PERMISSION_NOT_IN_SNAPSHOT` 或 `PERMISSION_DENIED`；当前 Host 未开放剪贴板能力时可返回
  * `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。握手、bridge 超时和其他 Host 写入失败会保留
  * 对应错误码。
  *
@@ -10270,6 +10272,12 @@ function decodeBase64Url(value) {
  * @see {@link MiniProgramScreenshotOptions}
  */
 function screenshot(requester, options) {
+    try {
+        console.warn('[hb-sdk] share.screenshot 行为变更提醒：正式版 SDK 0.9.1 及以上默认添加小程序品牌水印；低于 0.9.1（含预发布版本）的 SDK 保持无水印截图。升级前请在目标截图区域底部预留至少 57 个逻辑像素，避免遮挡重要内容；watermarkTheme 的 light 为黑色水印，dark 为白色水印且是默认值，不自动跟随系统主题。系统按键截图不在此能力范围内。');
+    }
+    catch {
+        // 日志输出失败不能阻断截图调用。
+    }
     return requester.request(SHARE_SCREENSHOT_METHOD, options);
 }
 

package/dist/index.esm.js

@@ -278,10 +278,12 @@ function isPlainObject$2(value) {
  * `data` 仅作为可选调试信息，不保证结构稳定。错误码是跨 Host 的分支契约；
  * `message` 只用于日志和开发者提示，不应作为机器判断条件。
  *
- * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_DECLARED`
- * 或 `PERMISSION_DENIED`（检查 Manifest/平台批准）、`USER_GESTURE_REQUIRED`
+ * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_IN_SNAPSHOT`
+ *（当前运行快照缺少权限，需发布含声明的新版本或重新打开调试）、
+ * `PERMISSION_DENIED`（检查权限启用状态与平台批准）、`USER_GESTURE_REQUIRED`
  *（改为用户点击后重试）、`AUTHORIZATION_CANCELLED`（结束当前流程），以及
  * `METHOD_FORBIDDEN`（当前 Host 不支持该能力）。具体能力还可能返回模块专属错误码。
+ * 旧 Runtime 仍可能返回 `PERMISSION_NOT_DECLARED`；SDK 会保留 Host 返回的错误码。
  * 不要把所有错误都当作可重试错误，也不要把 `data` 当成稳定的序列化协议。
  *
    * @example
@@ -7274,7 +7276,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.8';
+    : '0.9.1';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -7320,8 +7322,8 @@ function readRecord$1(value) {
 }
 
 const DEFAULT_TIMEOUT = 10000;
-// 选择器等待由用户决定，使用长操作的生命周期清理，不设固定总时长。
-const FILE_PICKER_METHODS = new Set([FILES_PICK_FILES_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_SAVE_FILE_METHOD]);
+// 选择器等待、截图延迟与排队由 Host 管理，使用长操作生命周期，不设固定总时长。
+const HOST_MANAGED_TIMEOUT_METHODS = new Set([FILES_PICK_FILES_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_SAVE_FILE_METHOD, SHARE_SCREENSHOT_METHOD]);
 const HANDSHAKE_RETRY_INTERVAL = 250;
 /** 底层 bridge client，负责握手、请求响应、事件分发与超时清理。 */
 class MiniProgramBridgeClient {
@@ -7403,7 +7405,7 @@ class MiniProgramBridgeClient {
     }
     /** 调用父容器开放能力。 */
     async request(method, ...args) {
-        return this.performRequest(method, args[0], !FILE_PICKER_METHODS.has(method));
+        return this.performRequest(method, args[0], !HOST_MANAGED_TIMEOUT_METHODS.has(method));
     }
     /** 发起不使用固定总时长 timer 的长操作。 */
     async requestOperation(method, payload, options = {}) {
@@ -8505,8 +8507,8 @@ function createCompanionModule(requester) {
  * `options.extra` 时生成不带扩展数据的链接。
  * @returns Host 完成剪贴板写入后 resolve 的完整分享链接；返回字符串与剪贴板内容一致。
  * @throws {@link HbMiniProgramSDKError} 参数、`extra` 编码或小程序身份不合法时返回
- * `INVALID_PARAMS`；未声明或未启用 `share` 权限时分别返回
- * `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`；当前 Host 未开放剪贴板能力时可返回
+ * `INVALID_PARAMS`；当前运行快照缺少或未启用 `share` 权限时分别返回
+ * `PERMISSION_NOT_IN_SNAPSHOT` 或 `PERMISSION_DENIED`；当前 Host 未开放剪贴板能力时可返回
  * `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。握手、bridge 超时和其他 Host 写入失败会保留
  * 对应错误码。
  *
@@ -10266,6 +10268,12 @@ function decodeBase64Url(value) {
  * @see {@link MiniProgramScreenshotOptions}
  */
 function screenshot(requester, options) {
+    try {
+        console.warn('[hb-sdk] share.screenshot 行为变更提醒：正式版 SDK 0.9.1 及以上默认添加小程序品牌水印；低于 0.9.1（含预发布版本）的 SDK 保持无水印截图。升级前请在目标截图区域底部预留至少 57 个逻辑像素，避免遮挡重要内容；watermarkTheme 的 light 为黑色水印，dark 为白色水印且是默认值，不自动跟随系统主题。系统按键截图不在此能力范围内。');
+    }
+    catch {
+        // 日志输出失败不能阻断截图调用。
+    }
     return requester.request(SHARE_SCREENSHOT_METHOD, options);
 }
 

package/dist/miniapp-publish.cjs.js

@@ -9531,6 +9531,31 @@ function parseMiniappBindAppIds(value, options = {}) {
     return Object.freeze(appIds);
 }
 
+/** 小程序简介最大长度（Unicode code point），与服务端截断口径一致。 */
+const MINIAPP_DESC_MAX_LENGTH = 200;
+/**
+ * 校验并规范化 `package.json#heybox.desc` / `manifest.desc`。
+ *
+ * @param value - 原始声明；未声明时为 `undefined`。
+ * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.desc`。
+ * @returns 去除首尾空白后的简介；未声明或为空串时返回 `undefined`。
+ * @throws `Error` 非字符串、超过 200 个字符，或包含除换行外的控制字符时抛出。
+ */
+function parseMiniappDesc(value, sourceLabel = 'package.json#heybox.desc') {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`${sourceLabel} 必须是字符串`);
+    const desc = value.replace(/^\p{White_Space}+|\p{White_Space}+$/gu, '');
+    if (!desc)
+        return undefined;
+    if (Array.from(desc).length > MINIAPP_DESC_MAX_LENGTH)
+        throw new Error(`${sourceLabel} 不能超过 ${MINIAPP_DESC_MAX_LENGTH} 个字符`);
+    if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(desc.replace(/\n/g, '')))
+        throw new Error(`${sourceLabel} 不能包含控制字符`);
+    return desc;
+}
+
 const MINIAPP_PERMISSION_KEYS = MINI_PROGRAM_PERMISSION_KEYS;
 function parseMiniappPermissions(value, options) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.permissions';
@@ -9703,6 +9728,7 @@ function validateMiniappManifestForDeploy(manifest) {
         throw new Error('manifest.category 缺失，请在 package.json#heybox.category 声明 tool、game 或 other 后重新构建');
     }
     const bindAppIds = parseMiniappBindAppIds(manifest.bindAppIds, { sourceLabel: 'manifest.bindAppIds' });
+    const desc = parseMiniappDesc(manifest.desc, 'manifest.desc');
     return {
         version,
         sdkVersion,
@@ -9714,6 +9740,7 @@ function validateMiniappManifestForDeploy(manifest) {
         ...(window === undefined ? {} : { window }),
         ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
         ...(category === undefined ? {} : { category }),
+        ...(desc === undefined ? {} : { desc }),
     };
 }
 function validateGeneratedCompanions(value) {

package/dist/miniapp-publish.esm.js

@@ -9529,6 +9529,31 @@ function parseMiniappBindAppIds(value, options = {}) {
     return Object.freeze(appIds);
 }
 
+/** 小程序简介最大长度（Unicode code point），与服务端截断口径一致。 */
+const MINIAPP_DESC_MAX_LENGTH = 200;
+/**
+ * 校验并规范化 `package.json#heybox.desc` / `manifest.desc`。
+ *
+ * @param value - 原始声明；未声明时为 `undefined`。
+ * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.desc`。
+ * @returns 去除首尾空白后的简介；未声明或为空串时返回 `undefined`。
+ * @throws `Error` 非字符串、超过 200 个字符，或包含除换行外的控制字符时抛出。
+ */
+function parseMiniappDesc(value, sourceLabel = 'package.json#heybox.desc') {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`${sourceLabel} 必须是字符串`);
+    const desc = value.replace(/^\p{White_Space}+|\p{White_Space}+$/gu, '');
+    if (!desc)
+        return undefined;
+    if (Array.from(desc).length > MINIAPP_DESC_MAX_LENGTH)
+        throw new Error(`${sourceLabel} 不能超过 ${MINIAPP_DESC_MAX_LENGTH} 个字符`);
+    if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(desc.replace(/\n/g, '')))
+        throw new Error(`${sourceLabel} 不能包含控制字符`);
+    return desc;
+}
+
 const MINIAPP_PERMISSION_KEYS = MINI_PROGRAM_PERMISSION_KEYS;
 function parseMiniappPermissions(value, options) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.permissions';
@@ -9701,6 +9726,7 @@ function validateMiniappManifestForDeploy(manifest) {
         throw new Error('manifest.category 缺失，请在 package.json#heybox.category 声明 tool、game 或 other 后重新构建');
     }
     const bindAppIds = parseMiniappBindAppIds(manifest.bindAppIds, { sourceLabel: 'manifest.bindAppIds' });
+    const desc = parseMiniappDesc(manifest.desc, 'manifest.desc');
     return {
         version,
         sdkVersion,
@@ -9712,6 +9738,7 @@ function validateMiniappManifestForDeploy(manifest) {
         ...(window === undefined ? {} : { window }),
         ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
         ...(category === undefined ? {} : { category }),
+        ...(desc === undefined ? {} : { desc }),
     };
 }
 function validateGeneratedCompanions(value) {

package/dist/protocol.cjs.js

@@ -1299,7 +1299,7 @@ function isManagedMiniProgramRuntimePermissionKey(key) {
  * `requirement`：`kind: 'none'` 不读取权限；`kind: 'all'` 要求列出的每个 canonical entry 都存在
  * 且 `status === 'enabled'`。之后仍需通过 Host capability、可信手势、用户授权、参数和业务
  * policy。当前 Runtime 对 `valid: false` 按空权限表 fail closed，受保护 method 会得到
- * `PERMISSION_NOT_DECLARED`，而不是沿用输入中的部分 enabled entry。
+ * `PERMISSION_NOT_IN_SNAPSHOT`，而不是沿用输入中的部分 enabled entry。
  *
  * @example
  * ```ts

package/dist/protocol.esm.js

@@ -1297,7 +1297,7 @@ function isManagedMiniProgramRuntimePermissionKey(key) {
  * `requirement`：`kind: 'none'` 不读取权限；`kind: 'all'` 要求列出的每个 canonical entry 都存在
  * 且 `status === 'enabled'`。之后仍需通过 Host capability、可信手势、用户授权、参数和业务
  * policy。当前 Runtime 对 `valid: false` 按空权限表 fail closed，受保护 method 会得到
- * `PERMISSION_NOT_DECLARED`，而不是沿用输入中的部分 enabled entry。
+ * `PERMISSION_NOT_IN_SNAPSHOT`，而不是沿用输入中的部分 enabled entry。
  *
  * @example
  * ```ts

package/dist/vite.cjs.js

@@ -10282,7 +10282,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.8';
+    : '0.9.1';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -10700,6 +10700,31 @@ function parseMiniappCategory(value, sourceLabel = 'package.json#heybox.category
     throw new Error(`${sourceLabel} 必须是 tool、game 或 other`);
 }
 
+/** 小程序简介最大长度（Unicode code point），与服务端截断口径一致。 */
+const MINIAPP_DESC_MAX_LENGTH = 200;
+/**
+ * 校验并规范化 `package.json#heybox.desc` / `manifest.desc`。
+ *
+ * @param value - 原始声明；未声明时为 `undefined`。
+ * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.desc`。
+ * @returns 去除首尾空白后的简介；未声明或为空串时返回 `undefined`。
+ * @throws `Error` 非字符串、超过 200 个字符，或包含除换行外的控制字符时抛出。
+ */
+function parseMiniappDesc(value, sourceLabel = 'package.json#heybox.desc') {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`${sourceLabel} 必须是字符串`);
+    const desc = value.replace(/^\p{White_Space}+|\p{White_Space}+$/gu, '');
+    if (!desc)
+        return undefined;
+    if (Array.from(desc).length > MINIAPP_DESC_MAX_LENGTH)
+        throw new Error(`${sourceLabel} 不能超过 ${MINIAPP_DESC_MAX_LENGTH} 个字符`);
+    if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(desc.replace(/\n/g, '')))
+        throw new Error(`${sourceLabel} 不能包含控制字符`);
+    return desc;
+}
+
 const MINIAPP_PERMISSION_KEYS = MINI_PROGRAM_PERMISSION_KEYS;
 function parseMiniappPermissions(value, options) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.permissions';
@@ -10811,6 +10836,7 @@ function renderMiniappManifest(manifest) {
     const window = validateMiniappWindow(manifest.window, 'manifest.window');
     const category = parseMiniappCategory(manifest.category, 'manifest.category');
     const bindAppIds = parseMiniappBindAppIds(manifest.bindAppIds, { sourceLabel: 'manifest.bindAppIds' });
+    const desc = parseMiniappDesc(manifest.desc, 'manifest.desc');
     const output = {
         version: manifest.version,
         sdkVersion: manifest.sdkVersion,
@@ -10822,6 +10848,7 @@ function renderMiniappManifest(manifest) {
         ...(window === undefined ? {} : { window }),
         ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
         ...(category === undefined ? {} : { category }),
+        ...(desc === undefined ? {} : { desc }),
     };
     return `${JSON.stringify(output, null, 2)}\n`;
 }
@@ -10992,6 +11019,11 @@ function readMiniappCategoryFromPackageJson(root) {
     const { packageJson } = readMiniappPackageJson(root, false);
     return parseMiniappCategory(readMiniappHeyboxConfig(packageJson)?.category);
 }
+/** 读取并校验 `package.json#heybox.desc`；未声明或为空时返回 `undefined`。 */
+function readMiniappDescFromPackageJson(root) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    return parseMiniappDesc(readMiniappHeyboxConfig(packageJson)?.desc);
+}
 function readMiniappPackageJson(root, requireVersion) {
     const packageJsonPath = findNearestPackageJsonPath(root);
     let content;
@@ -20529,6 +20561,7 @@ const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
  *   图片源路径相对项目目录；icon 为 200×200，封面 1–5 张，每张不超过 10 MiB / 4000 万像素。
  *   build 会复制图片到输出目录 `_hb/basic-info/`，并将 Manifest 路径改为生成路径，不改写源图片；
  * - `heybox.category`：`tool`、`game` 或 `other`；构建时允许缺省，发布预检要求提供；
+ * - `heybox.desc`：可选简介，最多 200 个字符，写入 manifest 后在小程序简介页展示；
  * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序。
  *   声明仍停留在旧模板移动端默认（`android`、`ios`、`ohos`）时，`serve` 与 `build` 都只输出
  *   一条非阻断提示，不影响构建结果；
@@ -20983,6 +21016,7 @@ function miniappManifest() {
             const companionDeclarations = includeCompanions ? companionConfig.declarations : undefined;
             const bindAppIds = readMiniappBindAppIdsFromPackageJson(root);
             const category = readMiniappCategoryFromPackageJson(root);
+            const desc = readMiniappDescFromPackageJson(root);
             if (companionDeclarations && !parsedPermissions.permissions?.companion) {
                 throw new Error('配置 companions 时必须声明 package.json#heybox.permissions.companion.enabled=true');
             }
@@ -21020,6 +21054,7 @@ function miniappManifest() {
             const companions = prepareMiniappCompanions(companionDeclarations, { root: companionConfig.projectRoot, outputRoot, platforms });
             node_fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
             const manifestText = renderMiniappManifest({
+                ...(desc === undefined ? {} : { desc }),
                 version,
                 sdkVersion,
                 platforms,

package/dist/vite.esm.js

@@ -10279,7 +10279,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.8';
+    : '0.9.1';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -10697,6 +10697,31 @@ function parseMiniappCategory(value, sourceLabel = 'package.json#heybox.category
     throw new Error(`${sourceLabel} 必须是 tool、game 或 other`);
 }
 
+/** 小程序简介最大长度（Unicode code point），与服务端截断口径一致。 */
+const MINIAPP_DESC_MAX_LENGTH = 200;
+/**
+ * 校验并规范化 `package.json#heybox.desc` / `manifest.desc`。
+ *
+ * @param value - 原始声明；未声明时为 `undefined`。
+ * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.desc`。
+ * @returns 去除首尾空白后的简介；未声明或为空串时返回 `undefined`。
+ * @throws `Error` 非字符串、超过 200 个字符，或包含除换行外的控制字符时抛出。
+ */
+function parseMiniappDesc(value, sourceLabel = 'package.json#heybox.desc') {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`${sourceLabel} 必须是字符串`);
+    const desc = value.replace(/^\p{White_Space}+|\p{White_Space}+$/gu, '');
+    if (!desc)
+        return undefined;
+    if (Array.from(desc).length > MINIAPP_DESC_MAX_LENGTH)
+        throw new Error(`${sourceLabel} 不能超过 ${MINIAPP_DESC_MAX_LENGTH} 个字符`);
+    if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(desc.replace(/\n/g, '')))
+        throw new Error(`${sourceLabel} 不能包含控制字符`);
+    return desc;
+}
+
 const MINIAPP_PERMISSION_KEYS = MINI_PROGRAM_PERMISSION_KEYS;
 function parseMiniappPermissions(value, options) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.permissions';
@@ -10808,6 +10833,7 @@ function renderMiniappManifest(manifest) {
     const window = validateMiniappWindow(manifest.window, 'manifest.window');
     const category = parseMiniappCategory(manifest.category, 'manifest.category');
     const bindAppIds = parseMiniappBindAppIds(manifest.bindAppIds, { sourceLabel: 'manifest.bindAppIds' });
+    const desc = parseMiniappDesc(manifest.desc, 'manifest.desc');
     const output = {
         version: manifest.version,
         sdkVersion: manifest.sdkVersion,
@@ -10819,6 +10845,7 @@ function renderMiniappManifest(manifest) {
         ...(window === undefined ? {} : { window }),
         ...(bindAppIds.length === 0 ? {} : { bindAppIds }),
         ...(category === undefined ? {} : { category }),
+        ...(desc === undefined ? {} : { desc }),
     };
     return `${JSON.stringify(output, null, 2)}\n`;
 }
@@ -10989,6 +11016,11 @@ function readMiniappCategoryFromPackageJson(root) {
     const { packageJson } = readMiniappPackageJson(root, false);
     return parseMiniappCategory(readMiniappHeyboxConfig(packageJson)?.category);
 }
+/** 读取并校验 `package.json#heybox.desc`；未声明或为空时返回 `undefined`。 */
+function readMiniappDescFromPackageJson(root) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    return parseMiniappDesc(readMiniappHeyboxConfig(packageJson)?.desc);
+}
 function readMiniappPackageJson(root, requireVersion) {
     const packageJsonPath = findNearestPackageJsonPath(root);
     let content;
@@ -20526,6 +20558,7 @@ const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
  *   图片源路径相对项目目录；icon 为 200×200，封面 1–5 张，每张不超过 10 MiB / 4000 万像素。
  *   build 会复制图片到输出目录 `_hb/basic-info/`，并将 Manifest 路径改为生成路径，不改写源图片；
  * - `heybox.category`：`tool`、`game` 或 `other`；构建时允许缺省，发布预检要求提供；
+ * - `heybox.desc`：可选简介，最多 200 个字符，写入 manifest 后在小程序简介页展示；
  * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序。
  *   声明仍停留在旧模板移动端默认（`android`、`ios`、`ohos`）时，`serve` 与 `build` 都只输出
  *   一条非阻断提示，不影响构建结果；
@@ -20980,6 +21013,7 @@ function miniappManifest() {
             const companionDeclarations = includeCompanions ? companionConfig.declarations : undefined;
             const bindAppIds = readMiniappBindAppIdsFromPackageJson(root);
             const category = readMiniappCategoryFromPackageJson(root);
+            const desc = readMiniappDescFromPackageJson(root);
             if (companionDeclarations && !parsedPermissions.permissions?.companion) {
                 throw new Error('配置 companions 时必须声明 package.json#heybox.permissions.companion.enabled=true');
             }
@@ -21017,6 +21051,7 @@ function miniappManifest() {
             const companions = prepareMiniappCompanions(companionDeclarations, { root: companionConfig.projectRoot, outputRoot, platforms });
             mkdirSync(path.dirname(manifestPath), { recursive: true });
             const manifestText = renderMiniappManifest({
+                ...(desc === undefined ? {} : { desc }),
                 version,
                 sdkVersion,
                 platforms,

package/docs/runtime-host-migration.md

@@ -89,7 +89,9 @@ Storage 面板只通过 `runtime.diagnostics.storage?.getSnapshot()` 读取 Runt
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
 | Browser Dev Host       | 私有 WebSocket channel 优先，HTTP/SSE 保留为兼容路径。账号 identity 的 canonical 读取仍由 HTTP session status 完成；channel 只发 revision hint，收到 hint 后重新读取 HTTP 状态。                                                                                                                                          | WebSocket 握手、重连或消息失败不阻断 Browser Mock；回退 HTTP/SSE 并继续有界轮询。                  |
 | Mobile Release         | 当前稳定客户端继续把原生 `mini_url` launch 交给详情 H5/Native Host；二维码保持 HTTPS `open_inapp` 与 `heybox://` `openWindow`，但短链这一跳是普通 H5。跳转页打开完整 sandbox query（`mini_url`、身份、启动票和 LAN Dev Context）后延迟 `closeWindow`。真机 WebView 基址是 `http://127.0.0.1` 详情页且 HTML 来自线上缓存。 | 生成真机二维码前仍需 CLI 登录、项目绑定和有效 Dev Context；这些条件不阻断 Browser 调试台启动。     |
-| Mobile Debug/Ad-Hoc H5 | `dev_context_url` 是可选的 Dev Session 输入；读取成功后采用本地 network proxy，代理不参与 Runtime 权限判断。 | Dev Context 缺失、过期、不可达或校验失败时记录脱敏诊断，继续使用原生 Host 的账号、网络与远端权限。 |
+| Mobile Debug/Ad-Hoc H5 | `dev_context_url` 是可选的 Dev Session 输入；读取成功后采用本地 network proxy，代理不参与 Runtime 权限判断。 | 历史协议 Dev Context 不可用时保留原生适配；新开发协议缺少有效描述时阻断并提示重试或更新 CLI。 |
+
+开发快照与凭据续期的权威约定见[开发会话](./development-session.md)。
 
 `DevSession` 同时携带本地声明、独立的 `local_dev_grant` 与 context revision，不会反向修改线上配置。真实 H5 必须先以启动票取得 canonical identity，再将可信线上基线与声明及严格解析的 grant 合成普通 Runtime 快照；没有有效票据或非法 grant 时不临时放权。临时授权仅允许 `network` / `companion`，不包含 `useOfficialDomain`，且每次启动由用户确认。
 
@@ -101,7 +103,7 @@ Node 负责 CLI-owned stable context endpoint、短跳转 registry 和 Launch Re
 
 ## Mobile 短跳转安全边界
 
-默认 Mobile 二维码编码现有 `https://api.xiaoheihe.cn/open_inapp/#heybox://...` 启动契约，但短链这一跳是普通 H5 `openWindow`（不带 `mini_program`），`webview.url` 只放局域网短链 `http://<lan-ip>:<port>/l/<token>`。短链返回 HTML 跳转页：先 `location.href` 打开完整 `heybox-mini-dev://sandbox` 协议，约 500ms 后再发 `closeWindow` 关掉中间页。不要对自定义协议做 HTTP 302，WebView 会把它当成相对路径。真机 WebView 基址是 `http://127.0.0.1/tools/user_miniprogram/detail`，HTML 来自线上详情页缓存，因此最终协议携带 `mini_url`、`mini_program_id`、`local_dev_launch_token`、`sdk_version` 和稳定 CLI-owned `dev_context_url`；二维码短期 token 轮换不会让已打开页面失效。`launch.json` 仍可作为同分支详情 Host 的补充发现。Dev Context 过期或校验失败时记录脱敏诊断，继续使用原生网络与已发现的权限。
+默认 Mobile 二维码编码现有 `https://api.xiaoheihe.cn/open_inapp/#heybox://...` 启动契约，但短链这一跳是普通 H5 `openWindow`（不带 `mini_program`），`webview.url` 只放局域网短链 `http://<lan-ip>:<port>/l/<token>`。短链返回 HTML 跳转页：先 `location.href` 打开完整 `heybox-mini-dev://sandbox` 协议，约 500ms 后再发 `closeWindow` 关掉中间页。不要对自定义协议做 HTTP 302，WebView 会把它当成相对路径。真机 WebView 基址是 `http://127.0.0.1/tools/user_miniprogram/detail`，HTML 来自线上详情页缓存，因此最终协议携带 `mini_url`、`mini_program_id`、`local_dev_launch_token`、`sdk_version` 和稳定 CLI-owned `dev_context_url`；二维码短期 token 轮换不会让已打开页面失效。`launch.json` 仍可作为同分支详情 Host 的补充发现。新开发协议的 Dev Context 过期或校验失败时不能生成新运行快照；历史适配边界见开发会话文档。
 
 `launch.json` 和短链都只减少二维码编码长度，不是认证、加密、签名或 HMAC：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.9.1-alpha.8",
+  "version": "0.9.1",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -68,6 +68,7 @@
   "dependencies": {
     "@jitl/quickjs-wasmfile-release-sync": "0.31.0",
     "@msgpack/msgpack": "2.8.0",
+    "fflate": "0.8.3",
     "parse5": "^7.3.0",
     "quickjs-emscripten-core": "0.31.0",
     "skills": "1.5.23",
@@ -75,7 +76,7 @@
     "undici": "^7.28.0",
     "ws": "^8.18.0",
     "sharp": "^0.34.5",
-    "@heybox/hb-sdk-protocol": "0.9.1-alpha.8"
+    "@heybox/hb-sdk-protocol": "0.9.1"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -128,11 +129,11 @@
     "@ai-desktop/view-contract": "file:../hb-sdk-protocol/vendor/view-contract-2.2.2-6ac49bbf6410.tgz",
     "rollup-plugin-dts": "6.4.0",
     "@heybox-domain/heybox-theme": "~0.1.0",
-    "@heybox/hb-sdk-runtime": "~0.9.1-alpha.8",
-    "@heybox/runtime": "~0.2.1",
-    "@heybox/runtime-policy": "~0.2.1",
+    "@heybox/hb-sdk-runtime": "~0.9.1",
     "@heybox/hb-api": "~1.28.14",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
+    "@heybox/runtime": "~0.2.1",
+    "@heybox/runtime-policy": "~0.2.1",
     "@heybox/runtime-transport-fetch": "~0.2.1"
   },
   "publishConfig": {

package/skill/SKILL.md

@@ -7,6 +7,16 @@ description: Uses @heybox/hb-sdk and the hb-sdk CLI to build, debug, review, and
 
 Use this Skill for workshop mini-program application code, project declarations, public SDK APIs, CLI workflows, Host/Runtime protocol maintenance, and publishing review.
 
+## Screenshot API Changes: Mandatory Upgrade Checks
+
+Before implementing screenshot flows or upgrading the SDK, use the canonical documentation index to read the screenshot Reference, community-sharing Recipe, and upgrade notes. Explicitly explain these changes to the developer:
+
+- Check the installed SDK against the watermark version cutoff, including prerelease ordering. Explain the warning emitted by the SDK screenshot entry and the Runtime's compatibility behavior for legacy screenshots versus the default watermark behavior for newer SDKs.
+- Check the required reserved area at the bottom of the capture region, the content that must remain unobstructed, and the corresponding rules for custom capture rectangles.
+- Check the light/dark theme option, default colors, system-theme behavior, and the support boundary between SDK screenshots and physical-button screenshots.
+
+Before upgrading, verify both the page layout and the captured image. Do not only update the dependency or invocation without explaining screenshot behavior changes. Read exact version cutoffs, dimensions, parameters, and Host support from the canonical documentation fetched for this task; never substitute an older installed Skill snapshot.
+
 ## Canonical Documentation
 
 The only maintained hb-sdk guidance source is:

package/skill/skill.json

@@ -1,16 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.9.1-alpha.8+skill.3260e7d71ada",
+  "skillVersion": "0.9.1+skill.c3a240ca503a",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.9.1-alpha.8",
-    "compatibility": "0.9.1-alpha.8"
+    "version": "0.9.1",
+    "compatibility": "0.9.1"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.9.1-alpha.8",
+    "version": "0.9.1",
     "path": "skill"
   },
-  "integrity": "sha256-3260e7d71ada646d5d8b269490e3de4b5ecd3fe824b18cdb73fe64247738ffea"
+  "integrity": "sha256-c3a240ca503a1e5f3b15033e091f1fa79a8b70585aa0d8d8fa0b332daec60ac5"
 }