@heybox/hb-sdk 0.9.0-alpha.3 → 0.9.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.9.0-alpha.3",
+  "version": "0.9.0-alpha.5",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -65,7 +65,7 @@
     "undici": "^7.28.0",
     "ws": "^8.18.0",
     "sharp": "^0.34.5",
-    "@heybox/hb-sdk-protocol": "0.9.0-alpha.3"
+    "@heybox/hb-sdk-protocol": "0.9.0-alpha.5"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -119,10 +119,10 @@
     "@heybox-domain/heybox-theme": "~0.1.0",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox/hb-api": "~1.28.10",
-    "@heybox/hb-sdk-runtime": "~0.9.0-alpha.3",
+    "@heybox/hb-sdk-runtime": "~0.9.0-alpha.5",
     "@heybox/runtime": "~0.2.0",
-    "@heybox/runtime-policy": "~0.2.0",
-    "@heybox/runtime-transport-fetch": "~0.2.0"
+    "@heybox/runtime-transport-fetch": "~0.2.0",
+    "@heybox/runtime-policy": "~0.2.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/skill.json

@@ -1,15 +1,15 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.9.0-alpha.3+skill.aa24d6656331",
+  "skillVersion": "0.9.0-alpha.5+skill.aa24d6656331",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.9.0-alpha.3",
-    "compatibility": "0.9.0-alpha.3"
+    "version": "0.9.0-alpha.5",
+    "compatibility": "0.9.0-alpha.5"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.9.0-alpha.3",
+    "version": "0.9.0-alpha.5",
     "path": "skill"
   },
   "integrity": "sha256-aa24d6656331cbad8f6aae7735258a49d7f1a82f6e900415de53a1b93a30ddb8"

package/types/core/singleton.d.ts

@@ -205,7 +205,7 @@ export declare function onHandshakeStateChange(handler: MiniProgramSDKHandshakeS
  * - `heybox_app_login_change`：`{ isHeyboxAppLoggedIn }`；
  * - `user_info_authorization_change`：
  *   [UserInfoAuthorization](/reference/symbols/root/interfaces/UserInfoAuthorization)，包含 `identity` 与
- *   `profile` 两项授权状态；
+ *   `profile` 两项授权状态，支持 Steam 账号能力时还可能包含 `steam_account`；
  * - `companion.session.output`：`{ sessionId, controllerGeneration, stream, sequence, data }`；
  * - `companion.session.exit`：`{ sessionId, exit }`；
  * - `companion.session.ownershipLost`：`{ sessionId, controllerGeneration }`。

package/types/miniapp-manifest/basic-info-browser.d.ts

@@ -1,4 +1,32 @@
-/** 只消费构建目录中的字节，不生成或回写 Manifest。返回 URL 的释放由页面负责。 */
+/**
+ * 在浏览器中校验构建产物的展示资料图片，并创建预览 URL。
+ *
+ * @param manifest - 构建产物 Manifest，必须包含合法的 `sdkVersion`。
+ * @param files - 构建文件列表；`relativePath` 必须精确匹配 Manifest 中的图片路径。
+ * @returns 名称、图标 `icon_url` 和按原顺序排列的 `cover_image_urls`；允许缺失资料的历史产物返回 `undefined`。
+ * @throws `Error` 资料非法、图片缺失/为空/超过 10 MiB、格式与扩展名不符、超过 4000 万像素、
+ * icon 不是 200×200，或仍使用脚手架占位图片时拒绝；浏览器解码和摘要计算失败也会拒绝。
+ * @remarks
+ * 需要浏览器提供 `crypto.subtle`、`createImageBitmap` 和 object URL API；不生成或回写 Manifest。
+ * 失败时会释放本次已创建的 URL；成功后所有 URL 由调用方在预览结束或替换时释放。
+ * @example
+ * ```ts
+ * import { previewMiniappBasicInfo } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * const preview = await previewMiniappBasicInfo(manifest, files);
+ * if (preview) {
+ *   try {
+ *     const image = new Image();
+ *     image.src = preview.icon_url;
+ *     await image.decode();
+ *     document.body.append(image);
+ *   } finally {
+ *     // 已加载的图像可继续显示；不再需要从这些 URL 加载时释放。
+ *     [preview.icon_url, ...preview.cover_image_urls].forEach(URL.revokeObjectURL);
+ *   }
+ * }
+ * ```
+ */
 export declare function previewMiniappBasicInfo(manifest: Record<string, unknown>, files: readonly {
     relativePath: string;
     file: Blob;

package/types/miniapp-manifest/basic-info.d.ts

@@ -1,12 +1,33 @@
 export declare const BASIC_INFO_MAX_BYTES: number;
 export declare const BASIC_INFO_MAX_PIXELS = 40000000;
+/** 小程序展示资料；项目声明和构建产物使用相同字段，图片路径的根目录不同。 */
 export interface MiniappBasicInfo {
+    /** NFKC 规范化并移除首尾 Unicode 空白后的名称，长度为 1–40 个 Unicode code point。 */
     name: string;
+    /** 图标的规范相对路径；项目声明相对项目目录，Manifest 相对构建目录。 */
     icon: string;
+    /** 1–5 个互不重复的封面相对路径，按展示顺序排列。 */
     coverImages: string[];
 }
-/** 按 NFKC 和 Unicode 空白规范化名称，并校验 1–40 个字符及禁用字符。 */
+/**
+ * 规范化并校验小程序展示名称。
+ *
+ * @param raw - 原始名称，必须是字符串。
+ * @returns NFKC 规范化、去除首尾 Unicode White_Space 后的名称；不折叠规范化后的内部空白。
+ * @throws `Error` 输入不是字符串，或规范化后不是 1–40 个 Unicode code point、不含文字或数字，或包含控制字符、
+ * 格式字符、行/段分隔符以及 HTML 特殊字符 `<`、`>`、`&`、双引号或单引号时抛出。
+ */
 export declare function normalizeBasicInfoName(raw: unknown): string;
 export declare function validateBasicInfoPath(raw: unknown): string;
-/** 解析项目或构建资料；仅早于 0.8.2 且三项全部缺失时返回 undefined。 */
+/**
+ * 校验项目声明或 Manifest 中的小程序展示资料。
+ *
+ * @param value - `package.json#heybox` 或 Manifest 对象，读取 `name`、`icon`、`coverImages`。
+ * @param sdkVersion - 产物 SDK 版本，默认 `0.8.2`；用于判断历史产物是否允许缺失全部资料。
+ * @returns 名称规范化后的新资料对象；仅版本早于 `0.8.2` 且三项均无自有属性时返回 `undefined`。
+ * @throws `Error` SDK 版本非法、资料字段不齐、名称/图片路径非法，或封面不是 1–5 个互不重复的路径时抛出。
+ * @remarks
+ * 图片路径必须使用 `/` 分隔的非空相对路径，扩展名为 JPEG、PNG、GIF 或 WebP；拒绝 URL、点段、
+ * 控制字符和构建/缓存等保留目录。此函数只校验声明，不读取文件，也不验证图片字节、尺寸或存在性。
+ */
 export declare function parseMiniappBasicInfo(value: Record<string, unknown>, sdkVersion?: string): MiniappBasicInfo | undefined;

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

@@ -1,4 +1,11 @@
-/** 小程序发布类别；新上传版本必须声明，历史产物读取允许缺省。 */
+/** 小程序发布类别：`tool` 为工具、`game` 为游戏、`other` 为其他；新上传版本必须声明，历史读取可缺省。 */
 export type MiniappCategory = 'tool' | 'game' | 'other';
-/** 校验配置或产物中的类别，省略与显式非法值严格区分。 */
+/**
+ * 校验项目配置或产物中的小程序类别。
+ *
+ * @param value - 待校验值，只接受 `tool`、`game`、`other` 或 `undefined`；不做 trim 或大小写转换。
+ * @param sourceLabel - 错误消息中的字段来源，默认 `package.json#heybox.category`。
+ * @returns 合法类别原值；输入 `undefined` 时返回 `undefined`，由发布流程另行检查是否必填。
+ * @throws `Error` 输入为其他值（包括 null 或空字符串）时抛出带字段来源的错误。
+ */
 export declare function parseMiniappCategory(value: unknown, sourceLabel?: string): MiniappCategory | undefined;

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

@@ -1,6 +1,11 @@
 export declare const MINIAPP_COMPANION_TARGETS: readonly ["windows-x64", "macos-arm64"];
 export declare const MINIAPP_COMPANION_CAPABILITIES: readonly ["stdio", "attachments", "notifications"];
+/** Companion 二进制目标：Windows x64 或 macOS arm64；不是小程序的通用平台列表。 */
 export type MiniappCompanionTarget = (typeof MINIAPP_COMPANION_TARGETS)[number];
+/**
+ * Companion 声明的能力标识：`stdio` 为标准输入输出、`attachments` 为受管附件、`notifications` 为通知。
+ * 声明不代表当前宿主可用；实际能力以启动后 Session 返回的 capability 集合为准。
+ */
 export type MiniappCompanionCapability = (typeof MINIAPP_COMPANION_CAPABILITIES)[number];
 export interface MiniappCompanionAuthoringTarget {
     /** 相对 package.json 所在目录的产物目录；SDK 在调试和构建时自动打包。 */
@@ -19,20 +24,40 @@ export interface MiniappCompanionAuthoringDefinition {
     targets: Partial<Record<MiniappCompanionTarget, MiniappCompanionAuthoringTarget>>;
 }
 export type MiniappCompanionAuthoringDeclarations = Record<string, MiniappCompanionAuthoringDefinition>;
+/** 构建生成的单个 Companion ZIP 归档描述；不使用项目声明中的 source 目录。 */
 export interface MiniappCompanionManifestTarget {
+    /** 相对构建目录的 ZIP 路径，固定为 `companions/{alias}/{target}.zip`。 */
     path: string;
+    /** ZIP 文件完整字节数，必须为正安全整数；不是解压后的大小。 */
     size: number;
+    /** ZIP 完整字节的 SHA-256，使用 64 位小写十六进制字符串。 */
     sha256: string;
+    /** 解压归档中的启动入口，由构建时从项目声明校验并保留。 */
     entrypoint: {
+        /** 普通可执行文件或 macOS `.app` bundle；Windows 仅支持 executable。 */
         kind: 'executable' | 'app-bundle';
+        /** 相对归档根目录的入口路径，使用 `/` 分隔；不是 ZIP 路径或项目 source 路径。 */
         path: string;
     };
+    /** V1 固定为普通权限启动，不支持请求管理员权限。 */
     elevation: 'none';
+    /** 启动参数列表；最多 64 项，每项 1024 UTF-8 bytes，总计 16 KiB，不允许 NUL、CR 或 LF。 */
     args: string[];
 }
+/** 一个 Companion alias 对应的展示信息、声明能力与平台归档。 */
 export interface MiniappCompanionManifestDefinition {
+    /** 非空展示名称，最多 120 个 Unicode code point。 */
     displayName: string;
+    /** 无重复的声明能力列表，可为空；不表示平台批准或宿主已提供这些能力。 */
     capabilities: MiniappCompanionCapability[];
+    /** 按二进制目标索引的已生成归档，至少提供一个目标。 */
     targets: Partial<Record<MiniappCompanionTarget, MiniappCompanionManifestTarget>>;
 }
+/**
+ * 发布 Manifest 的 Companion 声明，键为以小写字母开头、长度 1–32 的小写字母/数字/连字符 alias。
+ *
+ * @remarks
+ * 声明时对象必须非空，所有 alias 合计最多 64 个 target 描述符。归档由构建插件生成，
+ * 不应把含 source 目录的项目配置直接当作此类型；运行时还需声明 companion 权限并获得平台批准。
+ */
 export type MiniappCompanionManifestDeclarations = Record<string, MiniappCompanionManifestDefinition>;

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

@@ -1,12 +1,24 @@
 import { type MiniProgramPermissionKey, type MiniProgramRuntimePermissionsSnapshot } from '@heybox/hb-sdk-protocol';
 export declare const MINIAPP_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network", "companion"];
 export type MiniappPermissionKey = MiniProgramPermissionKey;
+/** 构建产物中一个已启用的权限声明；未启用的项目配置项会在构建时被省略。 */
 export interface SimpleMiniappPermissionDeclaration {
+    /** 固定为 true，表示应用请求使用该权限；不等同于平台已经批准。 */
     enabled: true;
 }
+/** 构建产物中的网络权限声明，附带是否请求小黑盒官方域名访问的配置。 */
 export interface NetworkMiniappPermissionDeclaration extends SimpleMiniappPermissionDeclaration {
+    /** 是否申请官方域名访问，项目省略时规范化为 false；实际启用还需远端批准该配置。 */
     useOfficialDomain: boolean;
 }
+/**
+ * 构建规范化后写入 Manifest 的权限对象；仅包含请求启用的权限，空对象表示无权限需求。
+ *
+ * @remarks
+ * 这是本地声明，不是运行时授权结果。仅需声明的权限按声明生效；要求平台批准的权限还需与远端批准
+ * 求交，network 的 useOfficialDomain 配置也需同时获批。显式声明中缺失某权限表示不请求该权限；
+ * SDK 0.9 系列起必须提供对象，0.8 历史产物未声明时另按迁移规则处理。
+ */
 export type MiniappPermissionDeclarations = Partial<Record<Exclude<MiniappPermissionKey, 'network'>, SimpleMiniappPermissionDeclaration> & {
     network: NetworkMiniappPermissionDeclaration;
 }>;

package/types/miniapp-manifest/runtime-gate.d.ts

@@ -1,5 +1,12 @@
 import { type DefaultTreeAdapterMap } from 'parse5';
 type HtmlDocument = DefaultTreeAdapterMap['document'];
 export declare function injectMiniappRuntimeGate(document: HtmlDocument): void;
+/**
+ * 检查 HTML 是否包含 Runtime Gate 的三个结构标记。
+ *
+ * @param html - 待检查的完整 HTML 文本，使用 HTML parser 解析。
+ * @returns Gate、隐藏样式及 bootstrap 标记均出现时返回 `true`，否则返回 `false`。
+ * @remarks 只识别标记，不验证脚本内容、标记所在节点或宿主握手；不能据此判断页面安全或实际可运行。
+ */
 export declare function hasMiniappRuntimeGate(html: string): boolean;
 export {};

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

@@ -72,18 +72,31 @@ export declare function isLegacyMobileTemplatePlatforms(platforms: readonly Mini
  * @returns 面向开发者的单行提示；调用方负责经 Vite 插件 `warn` 或等价日志通道输出，不得据此阻断构建。
  */
 export declare function getLegacyMobileTemplatePlatformsNotice(sourceLabel?: string): string;
+/** 构建生成的小程序发布 Manifest；可选字段用于兼容历史产物，发布前仍需完整校验。 */
 export interface MiniappManifest {
+    /** 原始产物可带额外元数据；发布校验返回值只保留已知字段。 */
     [key: string]: unknown;
+    /** 展示名称；SDK `0.8.2` 起需与图标、封面一起提供。 */
     name?: string;
+    /** 相对构建目录的图标路径。 */
     icon?: string;
+    /** 相对构建目录的封面路径，1–5 张，按展示顺序排列。 */
     coverImages?: string[];
+    /** 生成产物时实际安装的 hb-sdk 版本，不是小程序发布版本。 */
     sdkVersion: string;
+    /** 小程序发布版本：完整 SemVer，可含 prerelease，不允许 build metadata 或 core `0.0.0`。 */
     version: string;
+    /** 小程序承诺适配的非空、无重复目标平台列表。 */
     platforms: readonly MiniappPlatform[];
+    /** 产物权限声明；SDK `0.9` 系列起必须显式提供，无权限需求时使用空对象。 */
     permissions?: MiniappPermissionDeclarations;
+    /** 构建生成的 Companion 归档声明，不是含 source 目录的项目 authoring 配置。 */
     companions?: MiniappCompanionManifestDeclarations;
+    /** 桌面窗口的可选初值、最小尺寸及是否可缩放。 */
     window?: MiniappWindowDeclaration;
+    /** 关联游戏 App ID 字符串，最多 20 个；空列表在发布校验结果中省略。 */
     bindAppIds?: readonly string[];
+    /** 发布类别；历史读取可缺省，发布校验必须提供。 */
     category?: MiniappCategory;
 }
 export interface ParseMiniappManifestResult {
@@ -138,6 +151,16 @@ export declare function validateMiniappPackageVersionForBuild(version: string):
 export declare function validateMiniappManifestVersion(version: unknown, sourceLabel?: string): string;
 export declare function renderMiniappManifest(manifest: MiniappManifest): string;
 export declare function parseMiniappManifestJson(raw: string, sourceLabel?: string): ParseMiniappManifestResult;
+/**
+ * 校验发布 Manifest 并返回规范化后的已知字段。
+ *
+ * @param manifest - 从构建产物读取的 Manifest，图片和 Companion 路径相对构建目录。
+ * @returns 新对象：规范化版本、名称、平台与游戏绑定，省略空绑定及未声明的可选字段；不保留未知字段。
+ * @throws `Error` 版本、平台、资料、权限、窗口、游戏绑定或生成的 Companion 声明非法，以及类别缺失时抛出。
+ * @remarks
+ * 不修改输入对象，不执行文件 I/O；不会验证图片/归档是否存在、内容摘要是否匹配，也不查询远端发布资格。
+ * 成功仅表示 Manifest 字段通过校验，不能替代文件检查与服务端发布预检。
+ */
 export declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
     category?: MiniappCategory | undefined;
     bindAppIds?: readonly string[] | undefined;

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

@@ -59,30 +59,13 @@ export { parseMiniappBindAppIds, type ParseMiniappBindAppIdsOptions } from '../m
 /**
  * 将扫描到的相对路径转换为统一的 `/` 分隔形式。
  *
- * @param relativePath - 待整理的构建产物路径。TypeScript 入口声明为字符串；JavaScript 运行时会
- * 先计算 `relativePath || ''`，再通过 `String(...)` 强制转换。
- * @returns 仅统一分隔符形态的新字符串：所有 `\\` 转为 `/`，所有前导 `/` 被删除，其余连续
- * `/` 合并为一个。空字符串以及运行时传入的 `undefined`、`null`、`false`、`0`、`NaN` 等
- * falsy 值返回 `''`；truthy 非字符串按标准 `String(value)` 结果继续整理。
+ * @param relativePath - 待整理的构建产物路径。
+ * @returns 反斜杠转为 `/`、删除前导 `/`、合并连续 `/` 后的新字符串；空输入返回空字符串。
  *
  * @remarks
- * 这是面向 build/deploy 文件扫描结果的**格式 helper**，不是路径安全校验或 canonical path
- * parser。它不会 trim、URL decode、Unicode normalize、解析盘符，也不会拒绝或消解 `.` / `..`
- * segment、控制字符、Windows drive prefix 或尾随 `/`。例如 `/etc/passwd` 会变成
- * `etc/passwd`，`C:\\temp\\app.js` 会变成 `C:/temp/app.js`，`assets/../secret/` 仍保留点段
- * 和尾随 slash；调用方不能根据返回值推断原输入是安全相对路径。
- *
- * SDK 的 build/deploy 流程会把扫描路径先用本函数统一分隔符，再分别使用
- * {@link relativePathContainsNodeModulesSegment} 排除完整 `node_modules` 目录段、用
- * {@link shouldUploadDistFile} 过滤根 `manifest.json` / `.DS_Store` / source map。`hb-sdk build`
- * 随后校验大小预算；`hb-sdk remote deploy` 还会在签名和上传前通过
- * `validateUploadPaths()`、`prepareMiniappArtifactFiles()` 或
- * `validateMiniappUploadPathLengths()` 执行真正的空路径、点段、控制字符、重复和长度校验。
- * 这些步骤不能由本函数单独替代；`shouldUploadDistFile()` 也不会自行检查 `node_modules`。
- *
- * 不要把本函数与 `@heybox/hb-sdk/protocol` 的 `isMiniProgramRelativePath()` 混用：协议 guard
- * 不做转换，只接受已经规范的非空字符串，并拒绝前导/尾随 `/`、反斜杠、空 segment、`.`、
- * `..` 与控制字符；本函数则会改写部分非法形态并保留其余不安全内容。
+ * 仅整理文本格式，不做路径安全校验：保留点段、控制字符、盘符和尾随 `/`，不 trim 或 URL decode。
+ * 上传前仍需校验路径安全、唯一性与长度。协议 `isMiniProgramRelativePath()` 则只校验、不改写输入。
+ * JavaScript 非字符串输入按 `String(relativePath || '')` 转换，falsy 值回退为空串。
  *
  * @example
  * ```ts
@@ -90,8 +73,6 @@ export { parseMiniappBindAppIds, type ParseMiniappBindAppIdsOptions } from '../m
  *
  * normalizeRelativePath('///dist\\assets//app.js'); // 'dist/assets/app.js'
  * normalizeRelativePath('assets/../secret///'); // 'assets/../secret/'，仍需安全校验
- * normalizeRelativePath(123 as unknown as string); // '123'，JavaScript 运行时强制转换
- * normalizeRelativePath(0 as unknown as string); // ''，falsy 值先回退为空串
  * ```
  *
  * @see {@link relativePathContainsNodeModulesSegment}
@@ -102,40 +83,21 @@ export declare function normalizeRelativePath(relativePath: string): string;
 /**
  * 判断路径中是否包含大小写不敏感的完整 `node_modules` 目录段。
  *
- * @param relativePath - 待检查的构建产物路径。函数先通过 {@link normalizeRelativePath} 把
- * 反斜杠改为 `/`、删除前导 `/` 并合并连续 `/`，再按 `/` 分段。
- * @returns 至少一个非空段大小写不敏感地等于完整 `node_modules` 时返回 `true`；空路径、
- * 空段及 `node_modules.txt`、`node_modules-old`、`@node_modules` 等相似名称返回 `false`。
+ * @param relativePath - 构建产物路径，先按 {@link normalizeRelativePath} 整理分隔符再分段比较。
+ * @returns 任意目录段大小写不敏感地等于 `node_modules` 时返回 `true`；空路径和相似名称返回 `false`。
  *
  * @remarks
- * 比较使用每个非空 segment 的 `toLowerCase() === 'node_modules'`，因此根目录或任意深度的
- * `node_modules`、`NODE_MODULES`、`Node_Modules` 都会命中。前导和重复 slash 会先被
- * `normalizeRelativePath` 整理；尾随 slash 产生的空段会被忽略。
- *
- * 这是同步、无副作用的**单一 predicate**，只回答“规范化后的文本是否包含该完整段”。它
- * 不 trim segment、不进行 URL/percent decode、Unicode normalize 或文件系统解析。例如
- * `node_modules%2Fpkg/index.js`、`%6eode_modules/pkg.js` 和 `node_modules.txt` 都不会命中；调用方
- * 不应传 URL，也不能把未命中解释为路径安全。
- *
- * 本函数不会拒绝或消解 `.` / `..`、绝对路径、Windows drive prefix、控制字符、空路径、
- * symlink、重复路径或超长路径。`assets/../node_modules/pkg.js` 仍会命中，因为点段保持原样；
- * 不含 `node_modules` 的危险路径则仍可能返回 `false`。签名或上传前必须继续执行对应的上传
- * 路径规范、唯一性和长度校验。
- *
- * SDK build/deploy 会在文件扫描后用本函数拒绝整个 `node_modules` 树，再用
- * {@link shouldUploadDistFile} 排除根 `manifest.json`、`.DS_Store` 和 source map。build 随后
- * 校验大小预算；deploy 还会执行上传路径安全、唯一性、长度与签名校验。这些步骤互不替代：`shouldUploadDistFile()` 本身不检查
- * `node_modules`，本函数也不决定普通文件是否应该上传。
+ * 只检查目录段文本，不 trim、URL decode 或解析文件系统。未命中不表示路径安全；点段仍保留。
+ * SDK 用它排除 `node_modules` 树，再用 {@link shouldUploadDistFile} 过滤其他不上传的文件；
+ * 路径安全、唯一性、长度与上传大小需分别校验。
  *
  * @example
  * ```ts
  * import { relativePathContainsNodeModulesSegment } from '@heybox/hb-sdk/miniapp-publish';
  *
  * relativePathContainsNodeModulesSegment('dist\\NODE_MODULES/pkg/index.js'); // true
- * relativePathContainsNodeModulesSegment('dist//vendor///node_modules/'); // true
  * relativePathContainsNodeModulesSegment('dist/node_modules.txt'); // false
  * relativePathContainsNodeModulesSegment('dist/node_modules%2Fpkg.js'); // false，不做 URL decode
- * relativePathContainsNodeModulesSegment('assets/../secret.js'); // false，但这不代表路径安全
  * ```
  *
  * @see [normalizeRelativePath](/reference/symbols/miniapp-publish/functions/normalizeRelativePath)

package/types/modules/auth/index.d.ts

@@ -9,6 +9,9 @@ export { AUTH_LOGIN_METHOD } from '../../protocol/capabilities';
  *   `app_user_id`。它不是黑盒用户 ID，也不能跨小程序关联用户。
  * - `profile`：允许开发者服务端读取当前用户的昵称和头像。用户可以只同意
  *   `identity`，因此请求 `profile` 不代表最终一定获得该 scope。
+ * - `steam_account`：申请当前用户主绑定 Steam 账号资料。授权成功不代表已绑定 Steam；
+ *   {@link AuthorizedUserInfo.steam_id} 存在才表示取得了主绑定 SteamID64，不包含游戏库。
+ *   旧版或未启用 Steam 账号能力的 Host 会以 `INVALID_PARAMS` 拒绝该 scope。
  *
  * `identity` 是登录流程的必选 scope：调用方可以不传它，平台仍会把它加入实际授权
  * 结果。scope 只描述授权码和后续 OpenAPI token 可访问的资料，不是 token、客户端权限
@@ -39,6 +42,7 @@ export interface LoginOptions {
      * 匿名授权，成功结果仍包含 `identity`。数组中的值必须属于 {@link LoginScope} 且不能
      * 重复；JavaScript 调用传入未知值、重复值、`null` 或非数组值时，Promise 以
      * `HbMiniProgramSDKError.code === 'INVALID_PARAMS'` 拒绝。
+     * `steam_account` 虽属于公开类型，仍要求 Host 支持并启用 Steam 账号能力。
      *
      * @defaultValue `undefined`，即只申请隐式的 `identity`。
      * @see {@link LoginResult.scopes}
@@ -96,7 +100,7 @@ export interface MiniProgramAuthModule {
      * @returns Promise 成功时返回 {@link LoginResult}。它只包含一次性 code、code 有效期和
      * 实际授权 scope，不包含用户资料、`app_user_id`、access token、cookie 或应用密钥。
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`scopes` 不是数组、包含未知值或
-     * 重复值。
+     * 重复值，或当前 Host 尚未启用请求的 `steam_account` scope。
      * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`：
      * 当前版本未声明或不可使用 `userInfo` 权限。
      * @throws {@link HbMiniProgramSDKError} `USER_GESTURE_REQUIRED`：本次需要展示黑盒登录或

package/types/modules/companion/index.d.ts

@@ -345,14 +345,11 @@ export interface CompanionStdio {
      * 自行处理拆包、粘包和 framing。handler 每次收到独立的新 `Uint8Array` 副本，同一事件的其他
      * handler 也收到各自副本，因此一个 handler 修改 bytes 不会污染另一个 handler。
      *
-     * Host 输出按 at-least-once 语义投递。Runtime 先拒绝非法 Session ID、stream、generation、
-     * sequence 或 bytes；SDK 再在当前 controller generation 内分别为 stdout/stderr 记录最后一个
-     * sequence。已见或倒退的 stdout sequence 不会再次调用 handler，但有效 replay 仍会 best-effort
-     * 发送内部 `companion.session.ackOutput`；ack 失败不会转交给业务，也不会让本方法抛错。controller
-     * 转移、重新取得控制、页面 reload 或业务重连会形成新的去重边界，业务 frame 仍应携带自己的
-     * 幂等 ID，不能把 SDK 的 generation 内去重当作端到端 exactly-once 保证。
-     *
-     * handler 的同步异常会被隔离：其他 stdout handler 仍会收到同一 chunk，内部 ack 也仍会尝试。
+     * Host 输出按 at-least-once 语义投递。SDK 会在当前 controller 内抑制同一流已见或倒退的输出，
+     * 但重新取得控制、页面 reload 或业务重连后仍可能收到重放。业务 frame 应携带自己的幂等 ID，
+     * 不能把 SDK 的局部去重当作端到端 exactly-once 保证。
+     *
+     * handler 的同步异常会被隔离：其他 stdout handler 仍会收到同一 chunk。
      * SDK 忽略 handler 返回值且不会 await Promise；若传入 async 函数，需在函数内部处理 rejected
      * Promise。取消函数仅影响未来本地分发，已经开始执行的回调不会被中断。
      *
@@ -367,13 +364,11 @@ export interface CompanionStdio {
      * stdout/stderr sequence 去重状态；业务仍需处理 Host 重放。若不希望恢复后继续接收，应在
      * `onOwnershipLost()` 中调用本方法返回的取消函数。
      *
-     * Host 集成还必须提供 `HostCompanionPort.onSessionEvent()` 事件源。当前该 Host Port 成员是可选的：
-     * 若 Host 返回含 `stdio` 的 Session，却没有接入事件源，本方法仍会成功注册，但 stdout、exit 与
-     * ownership 事件都不会到达 SDK，且没有轮询或 WebSocket fallback。Mini-program 无法通过本方法
-     * 检测该集成缺口；Host/Runtime 集成方应把 Session event source 作为可用 stdio 输出的必要条件。
+     * 自定义 Host 若未提供 Session 事件源，本方法仍可注册，但不会收到输出、退出或 ownership
+     * 事件，也没有轮询 fallback。Mini-program 不能把注册成功当作事件源可用的保证。
      *
      * V1 真实 Companion stdio 仅支持新 PC Host 的 Windows x64 与 macOS arm64；Browser Dev Host
-     * 提供确定性 Fake 以验证 bytes、ack、framing 和错误 UI，不执行真实程序。其他平台、旧 Host 或
+     * 提供确定性 Fake 以验证字节流、framing 和错误 UI，不执行真实程序。其他平台、旧 Host 或
      * 未开放 Companion 的环境不会提供可用 Session stdio。
      *
      * @example
@@ -438,22 +433,17 @@ export interface CompanionStdio {
      * 即使返回了 `stdio`，订阅也只是成功注册本地 handler，之后不会收到输出事件；它不会轮询、报错或
      * 从 `write()` 响应中推导 stderr。
      *
-     * stderr 与 {@link CompanionStdio.onStdout | onStdout()} 使用相同的原始字节、sequence、去重和确认
-     * 合同，但两条流相互独立：各自维护最近 sequence 和 handler 集合，相同 sequence 数字可以分别在
-     * stdout 与 stderr 出现。字节不会自动按 UTF-8、换行、JSON 或消息边界解码；一个逻辑诊断可能被
-     * 拆到多个 chunk，一个 chunk 也可能含多条诊断。stderr 只是 Companion 进程选择的第二输出流，
+     * stderr 与 {@link CompanionStdio.onStdout | onStdout()} 使用相同的原始字节与去重合同，
+     * 但两条流的订阅和去重相互独立。字节不会自动按 UTF-8、换行、JSON 或消息边界解码；一个逻辑
+     * 诊断可能被拆到多个 chunk，一个 chunk 也可能含多条诊断。stderr 是 Companion 进程的第二输出流，
      * 收到数据不等于进程失败，退出结果应通过 {@link CompanionSession.waitForExit} 或
      * {@link CompanionSession.onExit} 判断。
      *
-     * 对当前 controller generation，每条格式合法且 sequence 大于本流已见水位的事件最多向业务
-     * handler 投递一次。较旧或重复的 sequence 不会再次投递，但 SDK 仍会发送 best-effort
-     * `companion.session.ackOutput`；即使没有 stderr handler 或某个 handler 抛错，也会继续确认。
-     * ack 是 SDK 内部 fire-and-forget 请求，失败会被吞掉，不会回调 handler，也不表示 Host 一定停止
-     * 重放。因此 Host 输出是 at-least-once，业务跨 controller 转移、页面 reload 或重连仍应按自己的
-     * framing / 消息 ID 处理重放和去重。
+     * SDK 会在当前 controller 内抑制本流已见或倒退的输出，但 Host 输出仍是 at-least-once。
+     * 业务跨 controller 转移、页面 reload 或重连后，应按自己的 framing / 消息 ID 处理重放和去重。
      *
      * handler 按注册集合顺序同步执行，返回值会被忽略，Promise 不会被等待。每个 handler 的同步异常
-     * 都被 SDK 单独捕获，不会阻断同一 chunk 的其他 handler 或 ack；异步 handler 的 rejected Promise
+     * 都被 SDK 单独捕获，不会阻断同一 chunk 的其他 handler；异步 handler 的 rejected Promise
      * 不会被 SDK 捕获，应在 handler 内显式处理。订阅不会重放注册前的 stderr，也不能读取历史缓冲区。
      *
      * Session 退出后，SDK 会清空 stdout/stderr handler；已有取消函数仍可安全调用。controller ownership
@@ -792,8 +782,8 @@ export interface CompanionSession {
      * `terminate()` resolve 不会直接把本地 `session.state` 改成 `'exited'`。SDK 只在收到合法的
      * `companion.session.exit` 事件后更新状态、resolve `waitForExit()` 并调用 `onExit()`；Host 通常会把
      * 强制终止报告为 `{ reason: 'terminated' }`，但调用方应以实际 {@link CompanionExit} 为准。若 Host
-     * 没有接入 `HostCompanionPort.onSessionEvent()`，terminate 请求仍可能成功，而 `state` 不更新、
-     * `waitForExit()` 一直 pending；Mini-program 没有轮询 fallback，Host/Runtime 集成方必须提供事件源。
+     * 没有提供 Session 事件源，terminate 请求仍可能成功，而 `state` 不更新、`waitForExit()` 一直
+     * pending；Mini-program 没有轮询 fallback。
      *
      * V1 真实 Companion Session 仅支持新 PC Host 的 Windows x64 与 macOS arm64；Browser Dev Host
      * Fake 会立即发出 `reason: 'terminated'` 的确定性 exit 事件，仅用于 UI 与状态机联调，不代表真实
@@ -970,16 +960,20 @@ export interface CompanionSession {
      * const session = await hbSDK.companion.getActiveSession('runner')
      * if (session) {
      *   // 先读取当前值，再订阅未来的 running -> exited 迁移。
-     *   renderState(session.state)
+     *   console.log(session.state)
      *
      *   const stopState = session.onStateChange(state => {
-     *     renderState(state)
+     *     console.log(state)
      *   })
      *   const stopExit = session.onExit(exit => {
-     *     renderExit(exit)
+     *     console.log(exit)
      *     stopState()
-     *     stopExit()
      *   })
+     *
+     *   window.addEventListener('pagehide', () => {
+     *     stopState()
+     *     stopExit()
+     *   }, { once: true })
      * }
      * ```
      *
@@ -1089,10 +1083,9 @@ export interface CompanionSession {
      * sequence 水位，并保留已注册的 handler；之后新的 ownership-lost 事件仍可再次触发同一订阅。
      * 页面 reload 会创建新的 SDK/proxy，旧订阅不会跨页面保留。
      *
-     * Host 的 `HostCompanionPort.onSessionEvent()` 是可选集成 Port。若 Host 返回活动 Session 却不提供
-     * event source，本方法仍会成功注册，但不会收到 ownership-lost、output 或 exit 事件，且没有轮询或
-     * WebSocket fallback；控制请求仍可能直接失败为 `COMPANION_SESSION_OWNERSHIP_LOST`。Host/Runtime
-     * 集成方必须提供事件源，业务不能把“尚未收到通知”当作仍拥有控制权。
+     * 自定义 Host 若未提供 Session 事件源，本方法仍可注册，但不会收到 ownership、输出或退出
+     * 事件，也没有轮询 fallback；控制请求仍可能以 `COMPANION_SESSION_OWNERSHIP_LOST` 失败。
+     * 业务不能把“尚未收到通知”当作仍拥有控制权。
      *
      * 不要求新的可信用户手势，也不改变权限或 Session 生命周期。它适用于在 ownership 丢失后立即
      * 禁用按钮、停止发送新命令并显示恢复入口；不要在回调中自动抢占 controller 或无条件重发可能已

package/types/modules/network/index.d.ts

@@ -80,7 +80,8 @@ export interface MiniProgramNetworkRequestConfig {
     headers?: MiniProgramNetworkHeaders;
     /**
      * Host 请求超时，单位毫秒；必须是 `0` 至 `30000` 的有限数字。省略或 `0` 时的具体默认
-     * 行为由 Host 决定；业务需要明确超时时应传正数。
+     * 行为由 Host 决定；业务需要明确超时时应传正数。该字段不改变 SDK 等待 bridge 响应的
+     * 独立超时；默认 SDK 实例的等待上限为 10 秒，详见 {@link MiniProgramNetworkModule.request}。
      */
     timeout?: number;
     /** SDK 侧状态校验；默认只接受 2xx，函数本身不会跨 bridge，详见 {@link MiniProgramNetworkValidateStatus}。 */
@@ -126,11 +127,15 @@ export interface DownloadBaseOptions {
      * 短期签名 URL。
      */
     headers?: MiniProgramNetworkHeaders;
-    /** 网络与响应 body 的空闲超时，单位毫秒；必须是有限正数，不是整个下载的总时长。 */
+    /**
+     * 网络与响应 body 的空闲超时，单位毫秒；必须是有限正数，不是整个下载的总时长。
+     * 省略时 SDK 与 Runtime 不设置统一默认值，由 Host 采用自身策略；需要确定超时预算时显式传入。
+     */
     timeout?: number;
     /**
      * 单次下载可提交的最大字节数；必须是正的 safe integer。可信 `Content-Length` 已超限时
      * 会在写入前返回 `FILE_TOO_LARGE`，流式传输过程中超限也不会提交部分文件。
+     * 省略时 SDK 与 Runtime 不附加该字节上限，但仍受 Host 文件与传输限制；不能视为无限容量。
      */
     maxBytes?: number;
     /**
@@ -271,6 +276,11 @@ export interface MiniProgramNetworkModule {
      * Browser Dev Host 与真实 App Host 都拒绝 multipart，并执行相同的 no-follow、官方域名和
      * 敏感路径策略；本地代理另有 5 MiB 响应体上限，真机 Host 仍可能有不同的响应限制。
      *
+     * Host 的 `config.timeout` 与 SDK 等待 bridge 响应的超时彼此独立；默认 SDK 实例从请求
+     * 发出后最多等待 10 秒。因此即使传 `timeout: 30000`，也可能先以 `REQUEST_TIMEOUT` 拒绝。
+     * SDK 等待超时不会主动取消 Host 请求，也不能证明服务端未处理请求；写请求重试应使用
+     * 幂等键或先核实业务结果，避免重复执行。
+     *
      * @example
      * ```ts
      * import hbSDK from '@heybox/hb-sdk'

package/types/modules/user/index.d.ts

@@ -16,6 +16,8 @@ export interface MiniProgramUserModule {
      * - `false`：当前未登录，`authorization` 和 `userInfo` 固定为 `null`。
      * - `true`：`authorization` 固定包含 `identity`、`profile` 两项状态；兼容 Host 的
      *   `userInfo` 仍可能为 `null`，非空时包含隔离 `app_user_id` 与可空 `profile`。
+     *   支持 Steam 账号能力的 Host 还可能返回 `authorization.steam_account` 与
+     *   `userInfo.steam_id`；授权与绑定状态应分别判断。
      *
      * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED` 表示
      * `userInfo` Manifest 权限不可用；`INVALID_STATE` 表示缺少 canonical 小程序身份；
@@ -39,6 +41,8 @@ export interface MiniProgramUserModule {
      * 会静默建立或读取本小程序隔离身份，并授予 `identity` 与 `profile`。`app_user_id` 只在
      * 当前小程序与当前授权有效期内作为稳定、不透明的关联键；它不是黑盒用户 ID、授权码或
      * 登录凭据。`profile.nickname` / `avatar` 只用于展示，可能为空字符串，不应用于鉴权。
+     * Steam 账号能力启用时，该读取还会静默授予 `steam_account`；只有当前账号存在主绑定
+     * 时才返回 string 类型的 `steam_id`。该字段缺失不能单独证明用户拒绝了授权。
      *
      * 该方法不返回 code、token 或 cookie，也不会创建开发者服务端会话。需要服务端身份时，
      * 在可信用户操作中调用 [auth.login](/reference/sdk/auth/login) 获取一次性 code；需要停止
@@ -112,7 +116,8 @@ export interface MiniProgramUserModule {
      *
      * 只有服务端确认成功且请求期间账号未变化时，Runtime 才清空缓存的隔离身份和授权 scope，
      * 并通过 [on](/reference/sdk/lifecycle/on) 发布 `user_info_authorization_change`，payload 为
-     * `{ identity: 'denied', profile: 'denied' }`。失败或过期的撤销结果不会发布该成功事件。
+     * `{ identity: 'denied', profile: 'denied' }`；启用 Steam 账号能力时还包含
+     * `steam_account: 'denied'`。失败或过期的撤销结果不会发布该成功事件。
      *
      * 成功后必须立即停止使用旧 `app_user_id` 和资料，并由业务自行清理 localStorage、SDK
      * `storage` 中的业务值、cookie、数据库以及开发者服务端 session；SDK 不会代为删除这些
@@ -183,6 +188,12 @@ export interface MiniProgramUserModule {
      * unit。`limit` 必须为正整数并在大于 100 时收窄为 100。继续分页时把返回的
      * `data.nextOffset` 原样传给下一次调用。
      *
+     * Host Runtime 默认将相同查询的成功游戏页缓存 24 小时，游戏新增、游玩时长、隐藏状态和
+     * 价格可能延迟更新。支持 sandbox 文件操作的宿主可以跨小程序关闭复用；其他宿主仅在当前
+     * Runtime 内复用。缓存仍检查当前账号和绑定上下文，首次全量读取仍需逐页请求。
+     * 缓存行为与有效期由 Host Runtime 策略决定，小程序不能通过本方法指定强制刷新。
+     * 系统或用户清理缓存目录后会重新请求；24 小时是有效期上限，不保证文件保留时长。
+     *
      * 先检查 `isLogin` 和 `isBound`，再读取 `data`。需要单独读取小黑盒登录态和当前小程序
      * 隔离身份时使用 [user.getInfo](/reference/sdk/user/getInfo)；需要为开发者服务端建立会话时，
      * 在可信用户操作中使用 [auth.login](/reference/sdk/auth/login)。这两个 API 都要求

package/types/modules/user/steam-game-list.d.ts

@@ -82,9 +82,9 @@ export interface SteamGameListItem {
     image?: string;
     /** 非空的 Steam 图标 URL 字符串；优先读取服务端 `appicon`。 */
     icon?: string;
-    /** 服务端原始累计游玩时长数值；`0` 是有效值，当前公开合同不承诺单位。 */
+    /** 当前接口返回的累计游玩时长，单位为秒；`0` 是有效值。该单位只适用于本接口响应。 */
     playtimeForever?: number;
-    /** 服务端原始最近游玩时长数值；`0` 是有效值，当前公开合同不承诺单位。 */
+    /** 当前接口返回的最近两周游玩时长，单位为秒；`0` 是有效值。该单位只适用于本接口响应。 */
     playtime2Weeks?: number;
     /** trim 后的非空游戏标签；没有有效标签时整个字段省略。 */
     tags?: string[];