@heybox/hb-sdk 0.9.1-alpha.10 → 0.9.1-alpha.12

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

@@ -5,8 +5,8 @@
     <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-CVZ3CdPt.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-DXmUwcoE.js">
+    <script type="module" crossorigin src="/assets/index-BdfQ_aP4.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-F0wNWGvm.js">
     <link rel="stylesheet" crossorigin href="/assets/index-BRxbUJVN.css">
   </head>
   <body>

package/dist/index.cjs.js

@@ -7278,7 +7278,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.10';
+    : '0.9.1-alpha.12';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -10270,6 +10270,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

@@ -7274,7 +7274,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.10';
+    : '0.9.1-alpha.12';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -10266,6 +10266,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/vite.cjs.js

@@ -10282,7 +10282,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.10';
+    : '0.9.1-alpha.12';
 
 /**
  * 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.10';
+    : '0.9.1-alpha.12';
 
 /**
  * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.9.1-alpha.10",
+  "version": "0.9.1-alpha.12",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -76,7 +76,7 @@
     "undici": "^7.28.0",
     "ws": "^8.18.0",
     "sharp": "^0.34.5",
-    "@heybox/hb-sdk-protocol": "0.9.1-alpha.10"
+    "@heybox/hb-sdk-protocol": "0.9.1-alpha.12"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -130,11 +130,11 @@
     "rollup-plugin-dts": "6.4.0",
     "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox/hb-api": "~1.28.14",
+    "@heybox/hb-sdk-runtime": "~0.9.1-alpha.12",
     "@heybox/runtime": "~0.2.1",
-    "@heybox/hb-sdk-runtime": "~0.9.1-alpha.10",
-    "@heybox/runtime-transport-fetch": "~0.2.1",
-    "@heybox/runtime-policy": "~0.2.1"
+    "@heybox/runtime-policy": "~0.2.1",
+    "@heybox/hb-api": "~1.28.14",
+    "@heybox/runtime-transport-fetch": "~0.2.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

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.10+skill.3260e7d71ada",
+  "skillVersion": "0.9.1-alpha.12+skill.c3a240ca503a",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.9.1-alpha.10",
-    "compatibility": "0.9.1-alpha.10"
+    "version": "0.9.1-alpha.12",
+    "compatibility": "0.9.1-alpha.12"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.9.1-alpha.10",
+    "version": "0.9.1-alpha.12",
     "path": "skill"
   },
-  "integrity": "sha256-3260e7d71ada646d5d8b269490e3de4b5ecd3fe824b18cdb73fe64247738ffea"
+  "integrity": "sha256-c3a240ca503a1e5f3b15033e091f1fa79a8b70585aa0d8d8fa0b332daec60ac5"
 }

package/types/index.d.ts

@@ -3451,7 +3451,12 @@ interface MiniProgramShareModule {
      * `pixelRatio` 换算，也不把越界矩形夹取到窗口内。JavaScript 的 coercible 非 number 值可能被
      * 当前 Runtime 接受，但这不是 TypeScript 公共合同，不应依赖。
      *
-     * Runtime 会在截图区域底部居中叠加「小黑盒 + 搜索图标 + 当前小程序名称」胶囊，
+     * SDK 每次调用都会输出 warning，提醒水印行为变化及布局、配色要求；日志失败不阻断截图。
+     * 新 Runtime 按 Version record 中已校验的 SDK 版本启用水印：低于正式版 `0.9.1`
+     * （包括 `0.9.1-alpha.*`）或兼容模式下版本缺失时，静默保持无水印截图；
+     * `0.9.1` 及以上默认添加水印。升级 SDK 前应同步调整截图布局。
+     *
+     * 启用水印时，Runtime 会在截图区域底部居中叠加「小黑盒 + 搜索图标 + 当前小程序名称」胶囊，
      * 下方显示灰色「小黑盒工坊小程序」。开发者应在目标截图区域底部预留至少 57 个逻辑
      * 像素的空白背景，不放置成绩、正文、按钮等重要内容，并保证背景与所选水印配色
      * 有足够对比度；自定义 `rect` 也按该区域的底部预留。水印不增加图片尺寸，只在本次
@@ -6261,7 +6266,7 @@ interface MiniProgramStorageModule {
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options`、key 或 JSON 数据非法，
      * 包括顶层 `undefined`、`BigInt`、循环引用或序列化过程抛错。
      * @throws {@link HbMiniProgramSDKError} `STORAGE_QUOTA_EXCEEDED`：完整 JSON 字符串的 UTF-8
-     * 字节数超过当前 Host 配额。
+     * 字节数超过当前 Host 配额，或写入新 key 后当前小程序的不同 key 数量将超过 1000 个。
      * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
      * 版本未声明或未启用 `storage`；`INVALID_STATE`：canonical 小程序身份尚未就绪。
      * @throws {@link HbMiniProgramSDKError} `METHOD_NOT_FOUND` / `METHOD_FORBIDDEN`：当前 Host

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

@@ -155,6 +155,8 @@ interface MiniappManifest {
     bindAppIds?: readonly string[];
     /** 发布类别；历史读取可缺省，发布校验必须提供。 */
     category?: MiniappCategory;
+    /** 简介，最多 200 个字符；未声明时简介页不展示。 */
+    desc?: string;
 }
 /**
  * 判断小程序版本是否符合公开 Manifest 版本规则。
@@ -211,6 +213,7 @@ declare function isValidMiniappManifestVersion(version: string): boolean;
  * 成功仅表示 Manifest 字段通过校验，不能替代文件检查与服务端发布预检。
  */
 declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
+    desc?: string | undefined;
     category?: MiniappCategory | undefined;
     bindAppIds?: readonly string[] | undefined;
     window?: MiniappWindowDeclaration | undefined;

package/types/vite/index.d.ts

@@ -149,6 +149,7 @@ declare const HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = "HB_SDK_MINI_PROGR
  *   图片源路径相对项目目录；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` 都只输出
  *   一条非阻断提示，不影响构建结果；