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

package/types/modules/files/types.d.ts

@@ -1,34 +1,188 @@
-/** File/Directory 访问模式。 */
+/**
+ * File/Directory 访问模式。
+ *
+ * `read` 允许读取、查询状态和枚举目录；`readwrite` 在此基础上允许创建和写入。
+ * 删除操作仍只对 sandbox 对象开放，外部授权即使为 `readwrite` 也不能删除。
+ */
 export type FileMode = 'read' | 'readwrite';
+/**
+ * 用户选择文件时的筛选和授权选项。
+ *
+ * @remarks
+ * 省略 options 或传 `{}` 等同于 `{ mode: 'read', multiple: false }`，且不设置扩展名筛选。
+ * Host 返回的整批文件会先校验数量、结构、名称、mode 和 session 配额，再一次性注册；任一项
+ * 失败都不会保留部分授权。
+ */
 export interface PickFilesOptions {
+    /**
+     * 请求的访问模式，默认 `read`。Host 即使授予更高权限也会被 Runtime 收窄为 `read`；请求
+     * `readwrite` 但平台/选择器只能授予只读时返回 `FILE_ACCESS_DENIED`，不会静默降级。外部
+     * File 即使为 `readwrite` 也不能调用 `remove()`。
+     */
     mode?: FileMode;
+    /**
+     * 传给系统选择器的文件扩展名筛选，例如 `['.json', '.txt', '.tar.gz']`。
+     *
+     * @remarks
+     * 必须是数组；每项匹配 `/^\.[a-z0-9][a-z0-9._-]*$/i`，即以 `.` 和 ASCII 字母/数字开头，
+     * 后续只允许 ASCII 字母、数字、点、下划线或连字符。空串、缺少前导点、路径、通配符、空格
+     * 或 MIME type 会以 `INVALID_PARAMS` 拒绝。重复项在进入 Host 前按首次出现顺序去重。
+     * 该字段只影响系统选择器筛选，不读取或转换文件内容；不需要筛选时应省略。
+     */
     accept?: string[];
+    /**
+     * 是否允许选择多个文件，默认 `false`。`false` 时成功结果恰好一个；只有显式为 `true` 时
+     * 才接受多个结果，实际数量由系统选择器决定，但成功结果仍至少一个。
+     */
     multiple?: boolean;
 }
+/**
+ * 用户选择目录时的授权选项。
+ *
+ * @remarks
+ * V1 只接受 `mode`，不支持文件扩展名筛选、多选或建议名称。省略 options、传 `{}` 或省略
+ * `mode` 都请求 `read`。Host 即使返回更高权限也会被 Runtime 收窄到请求模式；请求
+ * `readwrite` 但平台/选择器只授予只读时返回 `FILE_ACCESS_DENIED`，不会静默降级。
+ */
 export interface PickDirectoryOptions {
+    /**
+     * 请求的访问模式，默认 `read`。`read` 允许枚举、读取和查询派生目标；`readwrite` 还允许
+     * 创建/写入派生文件与目录，并可把所选目录作为 `network.download()` target。外部授权即使
+     * 为 `readwrite` 也不能调用 `remove()`。
+     */
     mode?: FileMode;
 }
+/**
+ * 用户选择精确保存目标时的选项。
+ *
+ * @remarks
+ * V1 只接受 `suggestedName`，不支持 `accept`、扩展名筛选、访问模式或 overwrite；返回授权固定
+ * 为 `readwrite`。该名称是提供给 Host 系统保存界面的建议值，跨平台最终文件名以返回
+ * {@link FileHandle.name} 为准。
+ */
 export interface SaveFileOptions {
+    /**
+     * 提供给系统选择器的建议文件名。
+     *
+     * @remarks
+     * 必须是非空的单个规范 basename：不能以 `/` 开头或结尾，不能包含 `/`、`\\`、NUL、
+     * U+0000-U+001F / U+007F 控制字符或空 path segment，也不能等于 `.` 或 `..`。例如
+     * `report.json` 合法，`reports/report.json`、`../report.json` 与 `report\\latest.json` 非法并返回
+     * `INVALID_PARAMS`。SDK 不会自动添加或修改扩展名。
+     */
     suggestedName: string;
 }
+/**
+ * {@link FileHandle.create} / {@link DirectoryHandle.create} 的创建选项。
+ *
+ * @remarks
+ * 两个字段都只接受 boolean，省略 options、传 `{}` 或省略单个字段时均使用 `false`。这些选项只影响
+ * 当前代理所指向的目标：不会把外部 File 授权扩张到父目录或兄弟项，也不会绕过当前代理的 `mode`、
+ * Runtime session、Mini-program identity、`filesystem` 权限或 Host capability 检查。
+ */
 export interface CreateOptions {
+    /**
+     * 是否同时创建目标路径中缺失的父目录，默认 `false`。
+     *
+     * `false` 时任一父目录缺失会失败；`true` 时 Host 在当前 sandbox 或已授权目录范围内创建缺失父目录。
+     * 它不改变目标已存在时的处理方式，也不能跨出当前逻辑 root。
+     */
     recursive?: boolean;
+    /**
+     * 目标已存在时是否失败，默认 `false`。
+     *
+     * `false` 是不破坏内容的 ensure-exists：同类型目标已存在时成功，不清空已有文件。`true` 要求本次
+     * 新建目标，文件或目录已存在时分别返回 `FILE_ALREADY_EXISTS` / `DIRECTORY_ALREADY_EXISTS`。
+     * 该字段只约束最终目标，不要求 `recursive` 创建的父目录也必须全新。
+     */
     exclusive?: boolean;
 }
+/** 删除目录时的选项。 */
 export interface RemoveOptions {
     /** 是否递归删除目录内容，默认 `false`。 */
     recursive?: boolean;
 }
+/** 枚举目录直接子项时的选项。 */
 export interface ListOptions {
+    /**
+     * 本次最多返回的直接子项数量，默认 `1000`。
+     *
+     * 必须是 `1` 到 `1000`（含）之间的 safe integer。`0`、负数、小数、`NaN`、无穷大或 unsafe
+     * integer 返回 `INVALID_PARAMS`；大于 `1000` 返回 `DIRECTORY_LIST_LIMIT_EXCEEDED`。该字段只是
+     * 单次结果上限，不是 offset、cursor 或递归深度，也没有配套的总数或截断标记。
+     */
     limit?: number;
 }
-/** 可同步派生 lazy File/Directory proxy 的逻辑根。 */
+/**
+ * 可同步派生 lazy File/Directory proxy 的逻辑根。
+ *
+ * @remarks
+ * 派生只创建当前 SDK session 内的冻结代理，不执行 I/O，也不暴露宿主真实路径。
+ * 路径在调用时同步校验，后续读写才通过 Host 访问目标。
+ */
 export interface PathRoot {
     /**
      * 按规范相对路径派生文件代理。
      *
-     * @param relativePath - 使用 `/` 分隔的规范相对路径。
-     * @returns 延迟访问对应文件的代理。
+     * @param relativePath - 相对于当前逻辑根、使用 `/` 分隔的规范路径。必须是非空字符串，不能以
+     * `/` 开头或结尾，不能包含空 segment、反斜杠、NUL 或其他控制字符；任一 segment 恰为 `.` 或
+     * `..` 都会拒绝，包括整个参数 `'.'`。`.env`、`report..json` 等不等于点段的普通名称可以使用。
+     * @returns 当前 SDK session 内延迟访问目标文件的冻结
+     * [FileHandle](/reference/symbols/root/interfaces/FileHandle)。其 `kind` 固定为 `'file'`，`name` 是
+     * `relativePath` 的末段 basename，`mode` 继承当前逻辑根；因此 `files.sandbox.file()` 返回
+     * `readwrite`，从用户选择目录继续派生时则继承所选目录的 `read` 或 `readwrite`，不能通过子路径
+     * 提升权限。
+     * @throws [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)
+     * `relativePath` 不是字符串、为空、以 `/` 开头或结尾，包含连续 `/`、任一 `.` / `..` 点段、
+     * 反斜杠或控制字符时，同步抛出 `INVALID_PARAMS`。
+     *
+     * @remarks
+     * 该方法同步校验路径并创建 lazy proxy，不检查文件是否存在或创建文件，不读取内容或元数据，不发送
+     * bridge 请求，也不会打开系统选择器。调用本身因此不需要用户手势，不会触发 Host operation，
+     * 不会占用 `pickFiles()` / `saveFile()` 的 direct handle 配额，也不会暴露宿主真实路径。
+     *
+     * 后续 I/O 才要求在 `package.json#heybox.permissions` 中声明并启用 `filesystem`，并由 Host 开放
+     * 对应 operation：[FileHandle](/reference/symbols/root/interfaces/FileHandle) 的 `create()`、`remove()`、
+     * `exists()`、`readText()`、`readBytes()`、`writeText()`、`writeBytes()`、`stat()` 分别使用
+     * `file.create`、`file.remove`、`file.exists`、`file.readText`、`file.readBytes`、`file.writeText`、
+     * `file.writeBytes`、`file.stat`。未声明或未启用权限时分别返回 `PERMISSION_NOT_DECLARED` 或
+     * `PERMISSION_DENIED`，Host 未开放具体 operation 时返回 `METHOD_FORBIDDEN`；这些错误在调用异步
+     * 方法时发生，不由本方法抛出。
+     *
+     * 代理只表达目标位置。`exists()` 可区分文件缺失或目标实际为目录；`create()` 可显式确保文件存在，
+     * `writeText()` / `writeBytes()` 也可隐式创建目标文件，但不会自动创建缺失的父目录。只读父目录派生
+     * 的文件可以读取与查询，调用 `create()`、写入或删除会返回 `FILE_ACCESS_DENIED`；外部目录派生的
+     * 文件即使是 `readwrite` 也不能删除。
+     *
+     * 若目标是目录或需要先创建父目录，使用
+     * [files.sandbox.directory()](/reference/sdk/files/sandbox/directory)。若要让用户选择现有的精确外部
+     * 文件，使用 [files.pickFiles()](/reference/sdk/files/pickFiles)；若要让用户指定新的精确可写目标，
+     * 使用 [files.saveFile()](/reference/sdk/files/saveFile)。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * // 构造代理时没有 I/O，且不会隐式创建 reports 目录。
+     * const report = hbSDK.files.sandbox.file('reports/latest.json')
+     * console.log(report.kind, report.name, report.mode)
+     * // file, latest.json, readwrite
+     *
+     * await hbSDK.files.sandbox.directory('reports').create({ recursive: true })
+     * await report.writeText(JSON.stringify({ generatedAt: Date.now() }))
+     *
+     * if (await report.exists()) {
+     *   console.log(await report.readText())
+     *   console.log((await report.stat()).size)
+     * }
+     * ```
+     *
+     * @see [files.sandbox.directory()](/reference/sdk/files/sandbox/directory) 派生或创建沙箱目录。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 通过可信用户操作取得现有外部文件授权。
+     * @see [files.saveFile()](/reference/sdk/files/saveFile) 通过可信用户操作取得精确可写目标。
+     * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 查看创建、读写、状态与删除方法。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 路径、权限、Host operation 与配额说明。
+     *
      * @since 0.8.0-alpha.2
      * @hbPlatform android
      * @hbPlatform ios
@@ -45,8 +199,59 @@ export interface PathRoot {
     /**
      * 按规范相对路径派生目录代理。
      *
-     * @param relativePath - 使用 `/` 分隔的规范相对路径。
-     * @returns 延迟访问对应目录的代理。
+     * @param relativePath - 相对于当前逻辑根、使用 `/` 分隔的规范路径。必须是非空字符串，不能以
+     * `/` 开头或结尾，不能包含空 segment、反斜杠、NUL 或其他控制字符。`.` 是仅有的特例：只有
+     * 整个参数等于 `'.'` 时才表示当前逻辑根；`./cache`、`cache/.`、`cache/../secret` 等含点段路径
+     * 不会被折叠或解析，而会直接拒绝。
+     * @returns 当前 SDK session 内延迟访问目标目录的冻结
+     * [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle)。其 `kind` 固定为
+     * `'directory'`，`name` 是末段 basename（传 `'.'` 时为 `'.'`），`mode` 继承当前逻辑根；因此
+     * `files.sandbox.directory()` 返回 `readwrite`，从用户选择目录继续派生时则继承所选目录的
+     * `read` 或 `readwrite`，不能通过子路径提升权限。
+     * @throws [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)
+     * `relativePath` 不是字符串、为空、以 `/` 开头或结尾，包含连续 `/`、任何 `.` / `..` 点段、
+     * 反斜杠或控制字符时，同步抛出 `INVALID_PARAMS`；完整参数 `'.'` 除外。
+     *
+     * @remarks
+     * 该方法同步校验路径并创建 lazy proxy，不检查目录是否存在或创建目录，不执行文件 I/O，不发送
+     * bridge 请求，也不会打开系统选择器。调用本身因此不需要用户手势，不会触发 Host operation，
+     * 不会占用 picker / `saveFile()` 的 direct handle 配额，也不会暴露宿主真实路径。
+     *
+     * 后续 I/O 才要求在 `package.json#heybox.permissions` 中声明并启用 `filesystem`，并由 Host 开放
+     * 对应 operation：[DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 的 `create()`、
+     * `exists()`、`list()`、`remove()` 分别使用 `directory.create`、`directory.exists`、
+     * `directory.list`、`directory.remove`。未声明或未启用权限时分别返回
+     * `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`，Host 未开放具体 operation 时返回
+     * `METHOD_FORBIDDEN`；这些错误在调用异步方法时发生，不由本方法抛出。
+     *
+     * `files.sandbox.directory('.')` 是沙箱根目录的逻辑代理，可用于 `exists()` 或 `list()`，但不能删除；
+     * 对它调用 `remove()` 会返回 `FILE_ACCESS_DENIED`。普通子目录代理只表达目标位置：需要确保目录
+     * 存在时调用 `create()`，需要观察直接子项时调用 `list()`。若目标是文件，使用
+     * [files.sandbox.file()](/reference/sdk/files/sandbox/file)；若要访问用户选择的外部目录，使用
+     * [files.pickDirectory()](/reference/sdk/files/pickDirectory)。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * // 构造代理时没有 I/O；父目录也不会被隐式创建。
+     * const reports = hbSDK.files.sandbox.directory('reports/2026')
+     * console.log(reports.kind, reports.name, reports.mode)
+     * // directory, 2026, readwrite
+     *
+     * await reports.create({ recursive: true })
+     *
+     * // `.` 只作为完整参数表示沙箱根；它不是可嵌入路径的点段。
+     * const root = hbSDK.files.sandbox.directory('.')
+     * const entries = await root.list({ limit: 100 })
+     * console.log(entries.map(entry => entry.name))
+     * ```
+     *
+     * @see [files.sandbox.file()](/reference/sdk/files/sandbox/file) 派生沙箱文件代理。
+     * @see [files.pickDirectory()](/reference/sdk/files/pickDirectory) 通过可信用户操作取得外部目录授权。
+     * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 查看 `create()`、`exists()`、`list()` 与 `remove()`。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 路径、权限、Host operation 与配额说明。
+     *
      * @since 0.8.0-alpha.2
      * @hbPlatform android
      * @hbPlatform ios
@@ -61,53 +266,1099 @@ export interface PathRoot {
      */
     directory(relativePath: string): DirectoryHandle;
 }
-/** Mini-program 私有 sandbox 的逻辑根。 */
+/**
+ * Mini-program 私有 sandbox 的逻辑根。
+ *
+ * @remarks
+ * sandbox 按 Mini-program identity 隔离并由 Host 持久保存；它是逻辑根，不是本机路径。
+ * sandbox 派生对象固定为 `readwrite`，但每次 I/O 仍需已声明 `filesystem` 权限且 Host 支持对应 operation。
+ */
 export interface FileSystem extends PathRoot {
 }
-/** 当前 SDK session 中的文件代理。 */
+/**
+ * 当前 SDK session 中的文件代理。
+ *
+ * @remarks
+ * 代理是冻结的能力对象，不是原生 `File` 或文件路径。picker / `saveFile()` 返回的精确授权仅在当前
+ * Runtime session 有效；sandbox 或已授权目录派生的逻辑代理不会在创建时执行 I/O。
+ */
 export interface FileHandle {
+    /** 可用于区分文件与目录的固定标记。 */
     readonly kind: 'file';
+    /** 文件 basename，不包含父目录或真实路径。 */
     readonly name: string;
+    /** 当前代理被授予的访问模式。 */
     readonly mode: FileMode;
+    /**
+     * 确保文件存在并返回同一个代理。
+     *
+     * @param options - 可选的父目录创建与目标独占创建设置。省略时等同于
+     * `{ recursive: false, exclusive: false }`；完整语义见 {@link CreateOptions}。
+     * @returns 当前同一个 `FileHandle` proxy；成功后 `result === file`。方法不会读取文件，且默认的
+     * ensure-exists 不会截断或改写已有内容。
+     * @throws {@link HbMiniProgramSDKError} options 非对象，或 `recursive` / `exclusive` 不是 boolean 时
+     * 返回 `INVALID_PARAMS`；代理不是 `readwrite` 时在发送 bridge 请求前返回 `FILE_ACCESS_DENIED`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `file.create` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} `recursive: false` 且父目录缺失时返回
+     * `DIRECTORY_NOT_FOUND`；目标实际是目录或路径中的祖先实际是文件时返回 `FILE_TYPE_MISMATCH`；
+     * `exclusive: true` 且文件已存在时返回 `FILE_ALREADY_EXISTS`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 已失效或不属于当前 Runtime session 时返回
+     * `FILE_ACCESS_REVOKED`；Host 创建失败、响应异常或底层平台 I/O 失败时返回相应稳定文件错误码，
+     * 无法识别的 Host 错误统一为 `FILE_IO_FAILED`。
+     *
+     * @remarks
+     * 目标缺失时创建空文件。`recursive: true` 会在当前逻辑 root 内同时创建缺失父目录；它不会允许
+     * `..`、绝对路径或跨越用户授权边界。目标已是文件时，默认调用作为幂等的 ensure-exists 成功，
+     * 保留原内容；需要检测冲突时传 `exclusive: true`。若目标实际为目录，不会把目录替换为文件。
+     *
+     * 调用要求当前代理的 `mode === 'readwrite'`。sandbox 文件固定继承 `readwrite`；从用户选择的目录
+     * 派生时继承该目录的 `mode`，因此只读目录的后代不能创建。用户选择或 `saveFile()` 返回的精确
+     * 外部 File 也只能在获授 `readwrite` 时调用；操作仍局限于该精确文件，不能取得父目录或兄弟文件。
+     * Runtime 会重新校验 direct handle 的 session/provenance，Host 还会绑定当前 Mini-program identity。
+     * 该方法不需要可信用户手势，也不会创建新的 direct handle、消耗 1024 个外部授权句柄配额或暴露真实路径。
+     *
+     * 新 PC Host 支持该 operation；Android/iOS 需要 `1.3.396+` 并以 `system.describe` 实际宣告的
+     * operation 为准，OHOS 同样按 Host 协商结果启用。Android 的精确 SAF File 仅授予 `read`，因此
+     * 不能调用本方法；sandbox 或可写目录派生文件不受该精确 File 限制。Web、Browser Dev Host、旧 Host
+     * 或 operation 集不完整时 fail closed，不提供 Blob 或内存 fallback。
+     *
+     * `create()` 只创建空目标。父目录已经存在时，{@link FileHandle.writeText} /
+     * {@link FileHandle.writeBytes} 也可隐式创建文件并写入内容；它们不会自动创建父目录。若需要先确保
+     * 目录存在，使用 {@link DirectoryHandle.create}；只需探测目标时使用 {@link FileHandle.exists}。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const report = hbSDK.files.sandbox.file('reports/2026/summary.json')
+     * const sameReport = await report.create({ recursive: true })
+     * console.assert(sameReport === report)
+     *
+     * await report.writeText('{"ready":true}')
+     * await report.create() // 已存在时成功，原内容不变
+     * console.log(await report.readText())
+     *
+     * try {
+     *   await report.create({ exclusive: true })
+     * } catch (error) {
+     *   if (!(error instanceof HbMiniProgramSDKError) || error.code !== 'FILE_ALREADY_EXISTS') throw error
+     * }
+     * ```
+     *
+     * @see {@link CreateOptions}
+     * @see {@link FileHandle.exists}
+     * @see {@link FileHandle.writeText}
+     * @see {@link FileHandle.writeBytes}
+     * @see {@link DirectoryHandle.create}
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     create(options?: CreateOptions): Promise<FileHandle>;
-    /** 删除 sandbox 文件；外部授权文件不允许删除。 */
+    /**
+     * 删除当前代理指向的 sandbox 文件。
+     *
+     * @returns Host 完成删除后以 `undefined` resolve；当前 `FileHandle` 代理本身仍可复用，后续可用
+     * {@link FileHandle.exists | exists()} 确认目标已不存在，或用 {@link FileHandle.create | create()}
+     * 在同一位置重新创建文件。
+     * @throws {@link HbMiniProgramSDKError} 代理为只读，或来源是 `pickFiles()`、`saveFile()`、外部
+     * Directory 派生项/枚举项时返回 `FILE_ACCESS_DENIED`；外部授权即使为 `readwrite` 也不能删除。
+     * @throws {@link HbMiniProgramSDKError} 目标或祖先不存在时返回 `FILE_NOT_FOUND` /
+     * `DIRECTORY_NOT_FOUND`，目标实际是目录时可返回 `FILE_TYPE_MISMATCH`；授权失效或 Host 删除失败
+     * 时返回 `FILE_ACCESS_REVOKED` / `FILE_IO_FAILED` 等稳定文件错误码。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放 `file.remove` operation 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 不认识该 method 时可返回 `METHOD_NOT_FOUND`。
+     *
+     * @remarks
+     * 该方法只删除一个文件，不接受参数，也不删除目录。可删除对象必须同时来自当前
+     * Mini-program 的 sandbox 且为 `readwrite`；`files.sandbox.file()` 和 sandbox 目录的 `list()`
+     * 结果满足来源约束。若目标是目录，使用 {@link DirectoryHandle.remove}；删除非空目录还需显式
+     * 传入 `{ recursive: true }`。
+     *
+     * `remove()` 不会先调用 `exists()`，也不是幂等的“确保不存在”操作：lazy sandbox 代理可以在
+     * 文件尚不存在时构造，此时调用删除会按 Host 结果抛出缺失错误。即使先由 `exists()` 返回
+     * `true`，目标仍可能在两次异步调用之间变化，因此仍应处理 `FILE_NOT_FOUND` /
+     * `DIRECTORY_NOT_FOUND`。调用不要求可信用户手势，也不占用外部 direct-handle 配额。
+     *
+     * 新 PC Host 支持该操作；Android/iOS `1.3.396+` 和 OHOS 仍以启动时
+     * `system.describe` 宣告的 `files.remove` operation 为准。Web、Browser Dev Host、旧 Host 或
+     * operation 缺失时 fail closed，不提供浏览器文件系统或内存 fallback。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const draft = hbSDK.files.sandbox.file('draft.txt')
+     * await draft.writeText('temporary')
+     *
+     * if (await draft.exists()) {
+     *   await draft.remove()
+     * }
+     * console.log(await draft.exists()) // false
+     *
+     * // 代理仍表示同一个 sandbox 位置，可以重新创建。
+     * await draft.create()
+     * ```
+     *
+     * @see {@link FileHandle.create}
+     * @see {@link FileHandle.exists}
+     * @see {@link DirectoryHandle.remove}
+     * @see [files.sandbox.file()](/reference/sdk/files/sandbox/file) 创建 sandbox 文件代理。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看来源、平台与错误码边界。
+     */
     remove(): Promise<void>;
+    /**
+     * 检查当前代理是否仍解析到一个文件。
+     *
+     * @returns Host 能取得目标且确认其类型为文件时返回 `true`。目标文件不存在、任一祖先目录
+     * 不存在，或同一逻辑位置实际是目录时返回 `false`；这些正常的“不存在”结果不会抛出
+     * `FILE_NOT_FOUND`、`DIRECTORY_NOT_FOUND` 或 `FILE_TYPE_MISMATCH`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 权限时分别以
+     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；当前 Host 未开放 `file.exists` 时以
+     * `METHOD_FORBIDDEN` 拒绝，旧 Runtime 也可能返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} picker / `saveFile()` 返回的精确外部授权被撤销、句柄
+     * 不属于当前 Runtime session 或 registry 已释放时，以 `FILE_ACCESS_REVOKED` 拒绝，而不是返回
+     * `false`；SDK 已销毁或 Runtime 已卸载时分别以 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE` 拒绝。
+     * @throws {@link HbMiniProgramSDKError} Host 拒绝访问、`stat` 探测失败、返回非布尔 bridge 结果
+     * 或发生其他文件 I/O 失败时，以 `FILE_ACCESS_DENIED`、`FILE_IO_FAILED` 或对应 SDK / bridge
+     * 错误拒绝。调用方不应把所有异常都解释为“不存在”。
+     *
+     * @remarks
+     * 这是只读查询，不创建文件、不读取内容、不修改访问模式，也不要求可信用户手势。
+     * `mode: 'read'` 与 `mode: 'readwrite'` 的 {@link FileHandle} 均可调用；但成功返回 `true` 不会
+     * 授予写权限，后续 `create()`、写入或删除仍受当前 mode、来源和 Host operation 限制。
+     *
+     * Runtime 使用 Host 的文件状态原语完成检查，但该布尔结果不是 {@link FileHandle.stat | stat()}
+     * 的缓存或替代品，也不包含大小与时间戳。它只描述本次探测时的状态：目标可能在 resolve 后
+     * 被删除、替换或撤销授权，因此后续 `readText()`、`stat()` 或写入仍可能失败；不要用
+     * `exists()` 作为权限检查或消除并发竞态。
+     *
+     * 对 sandbox lazy proxy，返回 `false` 后可在 `readwrite` 模式下调用
+     * {@link FileHandle.create | create()} 显式确保文件存在；缺失父目录时由 `create({ recursive: true })`
+     * 决定是否一并创建。对 picker / `saveFile()` 的精确外部 FileHandle，授权失效属于错误，不等价于
+     * 文件不存在。若要检查目录，应使用 {@link DirectoryHandle.exists | DirectoryHandle.exists()}，
+     * 目录位于当前文件代理对应位置时本方法返回 `false`。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 宣告
+     * `files.stat` 时逐项启用，OHOS 同样以 Host 实际协商结果为准。Web、Browser Dev Host、旧 Host
+     * 或缺少该 operation 的环境会 fail closed，不提供浏览器 File / Blob 或内存 fallback；页面应
+     * 处理 `METHOD_FORBIDDEN`，不要仅按操作系统推断可用性。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const report = hbSDK.files.sandbox.file('reports/latest.json')
+     *
+     * try {
+     *   if (!(await report.exists())) {
+     *     await report.create({ recursive: true })
+     *     await report.writeText('{}')
+     *   }
+     *
+     *   // exists() 之后状态仍可能变化，实际读取错误仍需处理。
+     *   console.log(await report.readText())
+     * } catch (error) {
+     *   if (error instanceof HbMiniProgramSDKError && error.code === 'METHOD_FORBIDDEN') {
+     *     showFilesUnsupported()
+     *   } else {
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileHandle.create | FileHandle.create()} 确保 sandbox 文件存在。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 读取文件大小与 Host 可提供的时间戳。
+     * @see {@link DirectoryHandle.exists | DirectoryHandle.exists()} 检查目录类型的目标。
+     * @see [files.sandbox.file()](/reference/sdk/files/sandbox/file) 创建 sandbox lazy FileHandle。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得当前 session 的精确外部文件授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看权限、平台与 Host operation 说明。
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     exists(): Promise<boolean>;
+    /**
+     * 将完整文件按文本读取。
+     *
+     * @returns Runtime 将 Host 返回的完整字节序列按严格 UTF-8 解码后的字符串。空文件返回 `''`；
+     * 换行、NUL 与其他合法 Unicode 内容保持不变。UTF-8 decoder 会剥离第一个开头 BOM；若解码结果
+     * 仍以 `U+FEFF` 开头，Runtime 再移除一个，因此一到两个连续前导 UTF-8 BOM 都不会出现在结果中。
+     * @throws {@link HbMiniProgramSDKError} 文件不是合法 UTF-8 时返回 `FILE_ENCODING_INVALID`，不会用
+     * replacement character 静默替换坏字节。需要无损读取任意二进制或保留 BOM 时使用
+     * {@link FileHandle.readBytes | readBytes()}。
+     * @throws {@link HbMiniProgramSDKError} 目标或祖先不存在时返回 `FILE_NOT_FOUND` / `DIRECTORY_NOT_FOUND`，
+     * 目标类型不匹配时返回 `FILE_TYPE_MISMATCH`。Android/iOS 当前对一次完整读取设 8 MiB 上限，
+     * 超限时返回 `FILE_TOO_LARGE`。
+     * @throws {@link HbMiniProgramSDKError} 普通 sandbox / picker / `saveFile()` 句柄未声明或未启用
+     * `filesystem` 时返回 `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到
+     * `file.readText` 时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 已失效、来自其他或已结束的 Runtime
+     * session 时返回 `FILE_ACCESS_REVOKED`；SDK / Runtime 已终止、调用超时、Host 返回无效内容或底层
+     * I/O 失败时返回 `SDK_DESTROYED`、`RUNTIME_DESTROYED`、`REQUEST_TIMEOUT` 或 `FILE_IO_FAILED` 等
+     * 对应 SDK 错误。
+     *
+     * @remarks
+     * 该方法读取并缓冲整个文件，没有 offset、range、stream、encoding 或 `AbortSignal` 参数。移动端
+     * Host 可以在内部按 chunk 读取，但公开 Promise 只在全部字节读取、复制和 UTF-8 解码完成后 resolve；
+     * 读取失败不会返回部分文本。8 MiB 是 Android/iOS 当前 Host 的原始文件字节上限，不是 JavaScript
+     * 字符串长度限制；新 PC Host 的限制由实际 Host I/O 合同决定。
+     *
+     * `mode: 'read'` 与 `mode: 'readwrite'` 句柄都可以读取，调用不需要可信用户手势，也不会弹出 picker、
+     * 创建文件、修改内容或延长外部授权寿命。picker / `saveFile()` 返回的 direct handle 只在当前
+     * Runtime session 有效；sandbox lazy ref 会在每次调用时按当前 Mini-program identity 解析。
+     * Companion `attachments.open()` 返回的只读 FileHandle 是受控例外：其 `readText()` 由 `companion`
+     * provenance 授权，不额外要求 `filesystem`，但仍受当前 Companion / Runtime session 生命周期约束。
+     *
+     * {@link FileHandle.writeText | writeText()} 执行相反方向的完整 UTF-8 编码与覆盖写入；它不会添加 BOM，
+     * 且要求 `mode === 'readwrite'`。若内容可能不是文本，或业务需要区分 BOM 和文件正文，应使用
+     * {@link FileHandle.readBytes | readBytes()} 获取原始字节并自行解析。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const settings = hbSDK.files.sandbox.file('settings.json')
+     *
+     * try {
+     *   const text = await settings.readText()
+     *   const value = JSON.parse(text)
+     *   console.log(value)
+     * } catch (error) {
+     *   if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_ENCODING_INVALID') {
+     *     // readBytes() 保留原始字节和 BOM，可交给业务自己的格式解析器。
+     *     const bytes = await settings.readBytes()
+     *     console.warn('settings.json 不是 UTF-8', bytes)
+     *   } else if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_NOT_FOUND') {
+     *     await settings.writeText('{}')
+     *   } else {
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileHandle.readBytes | FileHandle.readBytes()} 无损读取原始字节并保留 BOM。
+     * @see {@link FileHandle.writeText | FileHandle.writeText()} 以 UTF-8 覆盖写入完整字符串。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 在读取前查看文件字节数。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得当前 session 的外部文件授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看权限、平台限制与错误码。
+     */
     readText(): Promise<string>;
+    /**
+     * 将字符串按 UTF-8 编码后完整写入文件。
+     *
+     * @param content - 要写入的 JavaScript 字符串。必须确实是 `string`；SDK 不会对对象调用
+     * `String()`，也不接受 `Uint8Array`、`Blob`、stream 或 encoding 选项。空字符串合法，会把目标
+     * 替换为空文件。需要精确控制原始字节时使用 {@link FileHandle.writeBytes | writeBytes()}。
+     * @returns Runtime 完成 UTF-8 编码且 Host 的完整写入请求成功后以 `undefined` resolve。移动端会
+     * 等待最后一个带 EOF 的 chunk 获得 Host 响应；该时点不返回写入字节数、文件元数据或新的
+     * `FileHandle`，也不承诺操作系统已执行物理 `fsync`。
+     * @throws {@link HbMiniProgramSDKError} `content` 不是字符串时在 Host I/O 前以
+     * `INVALID_PARAMS` 拒绝；当前代理的 `mode` 不是 `readwrite` 时在发送 bridge 请求前以
+     * `FILE_ACCESS_DENIED` 拒绝。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 权限时分别以
+     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；Host 未开放 `file.writeText` 时以
+     * `METHOD_FORBIDDEN` 拒绝，旧 Runtime 也可能返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 缺失父目录时返回 `DIRECTORY_NOT_FOUND`，路径中的祖先
+     * 或目标类型不匹配时返回 `FILE_TYPE_MISMATCH`。Android / iOS 对一次完整写入的 UTF-8 编码结果
+     * 设 `8 MiB` 上限，超过 `8 * 1024 * 1024` bytes 时返回 `FILE_TOO_LARGE`；该限制按字节而不是
+     * JavaScript 字符数计算。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 被撤销、不属于当前 Runtime session
+     * 或 registry 已释放时返回 `FILE_ACCESS_REVOKED`；SDK 已销毁、Runtime 已卸载、请求超时、Host
+     * 响应异常或底层 I/O 失败时，分别以 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、
+     * `REQUEST_TIMEOUT`、`FILE_IO_FAILED` 或对应稳定文件错误码拒绝。
+     *
+     * @remarks
+     * Runtime 使用标准 `TextEncoder` 把完整字符串编码为不带 BOM 的 UTF-8，再调用 Host 的完整文件
+     * 写原语。该方法不是 append、range write 或 stream：已有文件内容会被本次编码结果整体替换，
+     * 写入 `''` 会把文件截断为零字节。若 Host 在写入中途失败，Promise 会拒绝；公开合同不承诺失败
+     * 时回滚旧内容或提供跨进程原子替换，需要事务语义时应由业务使用临时文件和自己的提交协议。
+     *
+     * 目标文件本身不存在时可以隐式创建，因此通常不需要先调用
+     * {@link FileHandle.create | create()}；但父目录必须已经存在，`writeText()` 不会递归创建目录。
+     * 需要创建父目录时先调用 {@link DirectoryHandle.create | DirectoryHandle.create()}，或对文件调用
+     * `create({ recursive: true })`。不要用 `exists()` 后再写来消除竞态：目标可能在两次异步调用之间
+     * 变化，实际写入错误仍应处理。
+     *
+     * sandbox lazy FileHandle 固定继承 `readwrite`，并在每次调用时按当前 Mini-program identity 解析。
+     * `pickFiles({ mode: 'readwrite' })`、`pickDirectory({ mode: 'readwrite' })` 的派生文件和
+     * `saveFile()` 返回的精确外部 FileHandle 也可以写入，但授权范围不会因此扩张；direct handle 只在
+     * 当前 Runtime session 有效。只读 picker 结果、Android 的精确 SAF File 和 Companion attachment
+     * 会在本地 mode 检查时以 `FILE_ACCESS_DENIED` 拒绝。该方法不需要新的可信用户手势；只有最初
+     * 获取外部授权的 picker / `saveFile()` 需要手势。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 同时宣告
+     * `files.openWrite`、`files.write`、`files.release` 时逐项启用，OHOS 同样以 Host 实际协商结果为准。
+     * Web、Browser Dev Host、旧 Host 或 operation 集不完整时 fail closed，不提供浏览器 File / Blob
+     * 或内存 fallback。新 PC Host 的大小限制由实际 Host 合同决定，不应套用移动端 8 MiB 上限。
+     *
+     * {@link FileHandle.readText | readText()} 可按严格 UTF-8 读取完整内容，但会移除前导 BOM；写入后
+     * 仍可能因为外部修改、授权撤销或 Session 结束而读取失败。需要检查最终字节数或时间戳时，在
+     * 写入成功后另行调用 {@link FileHandle.stat | stat()}。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const reports = hbSDK.files.sandbox.directory('reports')
+     * await reports.create({ recursive: true })
+     *
+     * const report = reports.file('latest.txt')
+     * await report.writeText('第一版\n') // 文件不存在时隐式创建。
+     *
+     * try {
+     *   await report.writeText('第二版\n') // 完整替换，不会追加到第一版后面。
+     *   console.log(await report.readText()) // 第二版
+     * } catch (error) {
+     *   if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_TOO_LARGE') {
+     *     console.warn('文本的 UTF-8 编码结果超过当前平台上限')
+     *   } else {
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileHandle.readText | FileHandle.readText()} 按严格 UTF-8 读取完整文件。
+     * @see {@link FileHandle.writeBytes | FileHandle.writeBytes()} 写入调用方提供的原始字节。
+     * @see {@link FileHandle.create | FileHandle.create()} 显式确保文件和可选父目录存在。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 在写入后读取文件大小与时间戳。
+     * @see {@link DirectoryHandle.create | DirectoryHandle.create()} 先创建缺失父目录。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得可选的精确外部文件写授权。
+     * @see [files.saveFile()](/reference/sdk/files/saveFile) 让用户指定新的精确可写目标。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看路径、权限、平台与配额边界。
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     writeText(content: string): Promise<void>;
+    /**
+     * 将完整文件读取为新的字节数组。
+     *
+     * @returns 包含完整文件原始字节的新 `Uint8Array`。空文件返回长度为 `0` 的数组。Runtime 会先
+     * 复制 Host 字节，SDK 验证 bridge 结果后再创建当前可见区间的副本，因此返回值不与 Host / bridge
+     * 响应共享可变存储；修改数组只改变调用方的本地副本，不会写回文件。
+     * @throws {@link HbMiniProgramSDKError} 目标或祖先不存在时返回 `FILE_NOT_FOUND` / `DIRECTORY_NOT_FOUND`，
+     * 目标类型不匹配时返回 `FILE_TYPE_MISMATCH`。Android / iOS 当前对一次完整读取设 `8 MiB`
+     * （`8 * 1024 * 1024` bytes）上限，超限时返回 `FILE_TOO_LARGE`。
+     * @throws {@link HbMiniProgramSDKError} 普通 sandbox / picker / `saveFile()` 句柄未声明或未启用
+     * `filesystem` 时返回 `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到
+     * `file.readBytes` 时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 被撤销、不属于当前或已结束的 Runtime
+     * session 时返回 `FILE_ACCESS_REVOKED`；Host 拒绝底层授权时也可能返回 `FILE_ACCESS_DENIED`。
+     * 握手失败、SDK / Runtime 已终止或不可用、调用超时、Host 返回非字节结果或底层 I/O 失败时，返回
+     * `HANDSHAKE_FAILED`、`SDK_DESTROYED`、`RUNTIME_DESTROYED`、`RUNTIME_UNAVAILABLE`、
+     * `REQUEST_TIMEOUT`、`FILE_IO_FAILED` 或对应稳定文件错误码。
+     *
+     * @remarks
+     * 该方法读取并缓冲整个文件，不提供 offset、range、stream、encoding、进度回调或 `AbortSignal`
+     * 参数。移动端 Host 可以在内部按 chunk 拉取，但公开 Promise 只在全部字节读取并复制完成后 resolve；
+     * 失败不会返回部分数组。8 MiB 是 Android / iOS 当前 Host 的原始文件字节上限，恰好等于上限允许；
+     * 新 PC Host 的限制由实际 Host I/O 合同决定。
+     *
+     * `readBytes()` 不解释内容格式：UTF-8 BOM、无效 UTF-8、NUL、压缩数据和图片头都会原样保留，也不会
+     * 因文本编码返回 `FILE_ENCODING_INVALID`。需要严格 UTF-8 字符串并移除前导 BOM 时使用
+     * {@link FileHandle.readText | readText()}；需要把修改后的字节完整覆盖回文件时使用
+     * {@link FileHandle.writeBytes | writeBytes()}。
+     *
+     * `mode: 'read'` 与 `mode: 'readwrite'` 句柄都可以读取，调用不需要可信用户手势，也不会弹出 picker、
+     * 创建文件、修改内容或延长外部授权寿命。picker / `saveFile()` 返回的 direct handle 只在当前
+     * Runtime session 有效；sandbox lazy ref 会在每次调用时按当前 Mini-program identity 解析。
+     * Companion `attachments.open()` 返回的只读 FileHandle 是受控例外：其 `readBytes()` 由 `companion`
+     * provenance 授权，不额外要求 `filesystem`，但仍受当前 Companion / Runtime session 生命周期约束。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 同时宣告
+     * `files.openRead`、`files.read`、`files.release` 时逐项启用，OHOS 同样以 Host 实际协商结果为准。
+     * Web、Browser Dev Host 的普通 sandbox / picker 路径、旧 Host 或 operation 集不完整时 fail closed，
+     * 不提供浏览器 File / Blob、内存 fallback 或自动分段的公开 API；前述 Companion attachment 仍按
+     * 自身受控 provenance 判断。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const avatar = hbSDK.files.sandbox.file('avatar.png')
+     *
+     * try {
+     *   const bytes = await avatar.readBytes()
+     *   const isPng =
+     *     bytes.length >= 4 &&
+     *     bytes[0] === 0x89 &&
+     *     bytes[1] === 0x50 &&
+     *     bytes[2] === 0x4e &&
+     *     bytes[3] === 0x47
+     *
+     *   console.log({ isPng, size: bytes.byteLength })
+     *   bytes[0] = 0 // 只修改本地副本，不会写回 avatar.png
+     * } catch (error) {
+     *   if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_TOO_LARGE') {
+     *     console.warn('请改用业务分片格式，或避免把大文件一次读入内存')
+     *   } else {
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileHandle.readText | FileHandle.readText()} 严格按 UTF-8 解码并处理前导 BOM。
+     * @see {@link FileHandle.writeBytes | FileHandle.writeBytes()} 完整覆盖写入原始字节。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 在完整读取前查看文件字节数。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得当前 session 的外部文件授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看权限、平台限制与错误码。
+     */
     readBytes(): Promise<Uint8Array>;
+    /**
+     * 将原始字节完整写入文件。
+     *
+     * @param content - 要写入的 `Uint8Array`。SDK 在调用时只复制该 view 的当前可见字节区间；不会把
+     * `byteOffset` 之前或 `byteLength` 之后的 backing `ArrayBuffer` 内容一并写入。调用返回 Promise 后
+     * 再修改原数组不会改变本次写入。空数组合法，会把目标替换为零字节文件。
+     * @returns SDK 与 Runtime 完成输入复制且 Host 的完整写入请求成功后以 `undefined` resolve。移动端
+     * 会等待最后一个带 EOF 的 chunk 获得 Host 响应；该时点不返回写入字节数、文件元数据或新的
+     * `FileHandle`，也不承诺操作系统已执行物理 `fsync`。
+     * @throws {@link HbMiniProgramSDKError} `content` 不是 `Uint8Array`，或其 backing buffer 是
+     * `SharedArrayBuffer` 时，在发送 bridge 请求前返回 `INVALID_PARAMS`；当前代理不是 `readwrite`
+     * 时在输入复制和 Host I/O 前返回 `FILE_ACCESS_DENIED`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 权限时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `file.writeBytes` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 缺失父目录时返回 `DIRECTORY_NOT_FOUND`，路径中的祖先或
+     * 目标类型不匹配时返回 `FILE_TYPE_MISMATCH`。Android / iOS 对一次完整写入设 8 MiB 上限；当前
+     * view 的 `byteLength` 超过 `8 * 1024 * 1024` 时返回 `FILE_TOO_LARGE`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 被撤销、不属于当前 Runtime session 或
+     * registry 已释放时返回 `FILE_ACCESS_REVOKED`；SDK 已销毁、Runtime 已卸载、请求超时、Host 响应
+     * 异常或底层 I/O 失败时，返回 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`、
+     * `FILE_IO_FAILED` 或对应稳定文件错误码。
+     *
+     * @remarks
+     * SDK 会在调用同步阶段执行第一次防御性复制，Runtime 收到 payload 后再复制一次，再把独立的
+     * `Uint8Array` 交给 Host。因此本次写入只观察调用时 view 中的字节，不与调用方继续共享可变
+     * `ArrayBuffer`。`SharedArrayBuffer` backing 会被明确拒绝，不能借此建立跨 bridge 共享内存。
+     *
+     * 这是完整文件写入，不是 append、range write 或 stream：已有内容会被本次字节序列整体替换，
+     * 写入空数组会截断为零字节。若 Host 在写入中途失败，Promise 会拒绝；公开合同不承诺失败时
+     * 回滚旧内容或提供跨进程原子替换，需要事务语义时应由业务使用临时文件和自己的提交协议。
+     *
+     * 目标文件不存在时可以隐式创建，但父目录必须已经存在，`writeBytes()` 不会递归创建目录。
+     * 需要创建父目录时先调用 {@link DirectoryHandle.create | DirectoryHandle.create()}，或对文件调用
+     * `create({ recursive: true })`。不必先用 `exists()` 检查文件；该检查也不能消除两次异步调用之间
+     * 的状态竞态，实际写入错误仍应处理。
+     *
+     * sandbox lazy FileHandle 固定继承 `readwrite`。`pickFiles({ mode: 'readwrite' })`、
+     * `pickDirectory({ mode: 'readwrite' })` 的派生文件和 `saveFile()` 返回的精确外部 FileHandle 也可
+     * 写入，但 direct handle 只在当前 Runtime session 有效，且授权范围不会扩张。只读 picker 结果、
+     * Android 的精确 SAF File 和 Companion attachment 返回 `FILE_ACCESS_DENIED`。该方法不需要新的
+     * 可信用户手势；只有最初取得外部授权的 picker / `saveFile()` 需要手势。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 同时宣告
+     * `files.openWrite`、`files.write`、`files.release` 时逐项启用，OHOS 同样以 Host 实际协商结果
+     * 为准。Web、Browser Dev Host、旧 Host 或 operation 集不完整时 fail closed，不提供浏览器
+     * File / Blob 或内存 fallback。新 PC Host 的大小限制由实际 Host 合同决定，不应套用移动端
+     * 8 MiB 上限。
+     *
+     * {@link FileHandle.readBytes | readBytes()} 返回完整文件的独立字节副本；
+     * {@link FileHandle.writeText | writeText()} 则先把字符串编码成不带 BOM 的 UTF-8，再执行相同的
+     * 完整替换语义。需要检查写入后的最终大小或时间戳时，成功后另行调用
+     * {@link FileHandle.stat | stat()}。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const file = hbSDK.files.sandbox.file('header.bin')
+     * const backing = new Uint8Array([0xff, 0x89, 0x50, 0x4e, 0x47, 0xff])
+     * const visible = backing.subarray(1, 5)
+     *
+     * const writing = file.writeBytes(visible)
+     * visible.fill(0) // 不影响 writeBytes() 已取得的快照。
+     * await writing
+     *
+     * console.log([...await file.readBytes()]) // [137, 80, 78, 71]
+     * await file.writeBytes(new Uint8Array()) // 完整替换为空文件。
+     * ```
+     *
+     * @see {@link FileHandle.readBytes | FileHandle.readBytes()} 读取独立的原始字节副本。
+     * @see {@link FileHandle.writeText | FileHandle.writeText()} 以 UTF-8 写入完整字符串。
+     * @see {@link FileHandle.create | FileHandle.create()} 显式确保文件和可选父目录存在。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 在写入后读取文件大小与时间戳。
+     * @see {@link DirectoryHandle.create | DirectoryHandle.create()} 先创建缺失父目录。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得可选的精确外部文件写授权。
+     * @see [files.saveFile()](/reference/sdk/files/saveFile) 让用户指定新的精确可写目标。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看路径、权限、平台与错误码边界。
+     */
     writeBytes(content: Uint8Array): Promise<void>;
+    /**
+     * 读取当前文件的元数据快照。
+     *
+     * @returns 新建的 {@link FileStat} 对象：`kind` 固定为 `'file'`，`size` 是 `0` 到
+     * `Number.MAX_SAFE_INTEGER` 的整数；Host 提供时还包含相互独立、非负有限数值的
+     * `modifiedAt` / `createdAt`。返回对象不是 `FileHandle`，也不会包含真实路径、内容或 Host 的额外字段。
+     * @throws {@link HbMiniProgramSDKError} 目标文件或任一祖先不存在时返回 `FILE_NOT_FOUND` /
+     * `DIRECTORY_NOT_FOUND`；目标实际是目录、direct handle 类型不匹配时返回 `FILE_TYPE_MISMATCH`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 已撤销、不属于当前 Runtime session 或
+     * registry 已释放时返回 `FILE_ACCESS_REVOKED`；Host 拒绝读取元数据时返回 `FILE_ACCESS_DENIED`。
+     * @throws {@link HbMiniProgramSDKError} 普通 FileHandle 未声明或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `file.stat` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。Companion attachment 是受控例外：
+     * 它使用已启用的 `companion` 授权读取自身元数据，不要求另行声明 `filesystem`。
+     * @throws {@link HbMiniProgramSDKError} Host 返回非对象、错误的 `kind`，负数/小数/unsafe `size`，
+     * 或负数、非有限数值的时间戳时返回 `FILE_IO_FAILED`；未知 Host 错误和无法识别的响应同样规范为
+     * `FILE_IO_FAILED`。SDK 已销毁、Runtime 已卸载或请求超时时还可能返回 `SDK_DESTROYED`、
+     * `RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * 这是只读操作，`mode: 'read'` 与 `mode: 'readwrite'` 均可调用，不要求可信用户手势，也不会读取
+     * 文件内容、创建文件、更新时间戳或占用新的 direct-handle 配额。Runtime 会重新校验 ref 的类型、
+     * 当前 session/provenance 与 Mini-program identity；通过结构校验不等于可以跨 session 复用句柄。
+     *
+     * 每次调用都会发送新的 `file.stat` 请求，并返回与 Host 响应分离的新对象；SDK 不缓存、冻结或持续
+     * 更新该对象。修改返回对象不会影响文件或后续结果，文件也可能在 Promise resolve 后立即被外部进程
+     * 修改、替换或删除。因此它只描述本次 Host 查询的快照，不能与之前的 `exists()` 或之后的
+     * `readText()` / `readBytes()` 组成原子检查。
+     *
+     * `size` 的公开约定单位是 byte，`modifiedAt` / `createdAt` 的公开约定单位是 Unix epoch
+     * milliseconds；但 Runtime 只能验证数值结构，不能证明 Host 使用了正确单位、时间来自文件系统或
+     * `size` 与稍后读取的内容仍一致。时间戳可分别缺失，也不要求为整数/safe integer、落在 JavaScript
+     * `Date` 可表示范围内、`createdAt <= modifiedAt` 或不晚于当前时间；用于排序和日期展示前应按业务范围
+     * 继续校验。
+     *
+     * 与 {@link FileHandle.exists | exists()} 不同，`stat()` 不会把缺失祖先、缺失目标或 kind mismatch
+     * 归一为 `false`，而会以对应错误拒绝。与 {@link FileHandle.readText | readText()} /
+     * {@link FileHandle.readBytes | readBytes()} 不同，它只读取元数据，不传输文件 body；Android/iOS 的
+     * 8 MiB 单次完整内容读写上限不限制可报告的 `size`，但 `size` 仍不能超过
+     * `Number.MAX_SAFE_INTEGER`。
+     *
+     * 新 PC Host 支持该 operation；Android/iOS `1.3.396+` 仅在 `system.describe` 宣告
+     * `files.stat` 时逐项启用，OHOS 同样以 Host 实际协商结果为准。Web、Browser Dev Host、旧 Host
+     * 或缺少该 operation 的环境会 fail closed，不提供浏览器 File / Blob 或内存 fallback。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const report = hbSDK.files.sandbox.file('reports/latest.json')
+     *
+     * // exists() 只用于快速分支；文件仍可能在下一次异步调用前变化。
+     * if (await report.exists()) {
+     *   try {
+     *     const stat = await report.stat()
+     *     console.log(`${stat.size} bytes`)
+     *
+     *     if (stat.modifiedAt !== undefined) {
+     *       const modifiedAt = new Date(stat.modifiedAt)
+     *       if (!Number.isNaN(modifiedAt.getTime())) console.log(modifiedAt.toISOString())
+     *     }
+     *   } catch (error) {
+     *     if (!(error instanceof HbMiniProgramSDKError) || error.code !== 'FILE_NOT_FOUND') throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileStat}
+     * @see {@link FileHandle.exists}
+     * @see {@link FileHandle.readText}
+     * @see {@link FileHandle.readBytes}
+     * @see [files.sandbox.file()](/reference/sdk/files/sandbox/file) 创建 sandbox lazy FileHandle。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得当前 session 的精确外部文件授权。
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     stat(): Promise<FileStat>;
 }
-/** 当前 SDK session 中的目录代理。 */
+/**
+ * 当前 SDK session 中的目录代理。
+ *
+ * @remarks
+ * 目录既能执行目录操作，也是派生子 File/Directory 逻辑代理的根。派生代理继承目录的 `mode`，
+ * 不能通过子路径提升授权范围。
+ */
 export interface DirectoryHandle extends PathRoot {
+    /** 可用于区分文件与目录的固定标记。 */
     readonly kind: 'directory';
+    /** 目录 basename，不包含父目录或真实路径。 */
     readonly name: string;
+    /** 当前代理及其派生项被授予的访问模式。 */
     readonly mode: FileMode;
+    /**
+     * 确保目录存在并返回同一个代理。
+     *
+     * @param options - 可选的父目录创建与目标独占创建设置。省略时等同于
+     * `{ recursive: false, exclusive: false }`；完整语义见 {@link CreateOptions}。
+     * @returns Host 确认目录存在后返回当前同一个 `DirectoryHandle` proxy；成功后
+     * `result === directory`。不会创建新的授权 handle，也不会刷新或改变代理的 `name`、`mode`。
+     * @throws {@link HbMiniProgramSDKError} options 非对象，或 `recursive` / `exclusive` 不是 boolean 时
+     * 返回 `INVALID_PARAMS`；代理不是 `readwrite` 时在发送 bridge 请求前返回 `FILE_ACCESS_DENIED`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `directory.create` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} `recursive: false` 且任一父目录缺失时返回
+     * `DIRECTORY_NOT_FOUND`；目标实际是文件或路径中的祖先实际是文件时返回 `FILE_TYPE_MISMATCH`；
+     * `exclusive: true` 且目录已存在时返回 `DIRECTORY_ALREADY_EXISTS`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 已失效、伪造或不属于当前 Runtime session
+     * 时返回 `FILE_ACCESS_REVOKED`；Host 创建失败或底层平台 I/O 失败时返回相应稳定文件错误码，
+     * 无法识别的 Host 错误统一为 `FILE_IO_FAILED`。SDK / Runtime 终止或请求超时还可能返回
+     * `SDK_DESTROYED`、`RUNTIME_DESTROYED`、`RUNTIME_UNAVAILABLE` 或 `REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * 目标缺失时创建空目录。`recursive: true` 会在当前逻辑 root 内同时创建缺失父目录；它不会允许
+     * `..`、绝对路径或越过 sandbox / 用户选择目录的授权边界。目标已是目录时，默认调用作为幂等的
+     * ensure-exists 成功，不删除、清空或重新创建其中内容；需要检测最终目标冲突时传
+     * `exclusive: true`。`exclusive` 只约束最终目录，`recursive` 创建的父目录可以已经存在。
+     * 若同一位置实际是文件，则不会把文件替换为目录。
+     *
+     * 调用要求当前代理的 `mode === 'readwrite'`。sandbox 目录固定继承 `readwrite`；从
+     * `files.pickDirectory({ mode: 'readwrite' })` 返回的外部目录派生后代时也可在该授权范围内创建，
+     * 但默认 `read` 的选择结果及其后代会在本地 mode 检查时拒绝。创建不会扩大授权到所选目录之外，
+     * 也不会让外部目录获得 `remove()` 权限；外部 direct handle 及其后代仍只在当前 Runtime session
+     * 有效。Runtime 会重新校验 direct handle 的 provenance，Host 还会绑定当前 Mini-program identity。
+     *
+     * 该方法要求 `package.json#heybox.permissions` 已声明并启用 `filesystem`，但不要求新的可信用户
+     * 手势；只有最初调用 `pickDirectory()` 取得外部授权时需要用户操作。它不占用新的外部 direct-handle
+     * 配额，也不暴露 Host 真实路径。
+     *
+     * 新 PC Host 支持该 operation；Android / iOS 需要 `1.3.396+` 并以 `system.describe` 实际宣告的
+     * operation 集为准，OHOS 同样按 Host 协商结果启用。Web、Browser Dev Host、旧 Host 或 operation
+     * 集不完整时 fail closed，不提供浏览器文件系统、OPFS 或内存 fallback。
+     *
+     * 创建目录后，可用当前代理的 {@link PathRoot.file | file()} / {@link PathRoot.directory | directory()}
+     * 同步派生后代代理，并用 {@link DirectoryHandle.list | list()} 枚举直接子项；派生与枚举结果继承
+     * 当前目录的 mode。若最终目标应是文件，使用 {@link FileHandle.create}；它复用同一组
+     * `recursive` / `exclusive` 选项，但独占冲突返回 `FILE_ALREADY_EXISTS`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const reports = hbSDK.files.sandbox.directory('exports/2026')
+     * const sameReports = await reports.create({ recursive: true })
+     * console.assert(sameReports === reports)
+     *
+     * const summary = reports.file('summary.json')
+     * await summary.create()
+     * await summary.writeText('{"ready":true}')
+     * console.log((await reports.list()).map(entry => entry.name))
+     *
+     * try {
+     *   await reports.create({ exclusive: true })
+     * } catch (error) {
+     *   if (!(error instanceof HbMiniProgramSDKError) || error.code !== 'DIRECTORY_ALREADY_EXISTS') throw error
+     * }
+     * ```
+     *
+     * @see {@link CreateOptions}
+     * @see {@link FileHandle.create}
+     * @see {@link DirectoryHandle.exists}
+     * @see {@link DirectoryHandle.list}
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     */
     create(options?: CreateOptions): Promise<DirectoryHandle>;
-    /** 删除 sandbox 目录；非空目录需要显式设置 `recursive`，外部授权目录不允许删除。 */
+    /**
+     * 删除当前代理指向的 sandbox 目录。
+     *
+     * @param options - 可选删除配置。省略 options、传 `{}` 或省略 `recursive` 都等同于
+     * `{ recursive: false }`；此时只允许删除空目录。`recursive` 必须是 boolean，非对象 options、
+     * 数组或其他类型会以 `INVALID_PARAMS` 拒绝。
+     * @returns Host 报告目标目录删除完成后以 `undefined` resolve。不返回删除的子项数量、原目录
+     * 内容或新的 handle；当前 `DirectoryHandle` 仍是同一逻辑位置的代理，可继续调用
+     * {@link DirectoryHandle.exists | exists()} 或 {@link DirectoryHandle.create | create()}。
+     * @throws {@link HbMiniProgramSDKError} 当前代理不是 `readwrite`，来源是 `pickDirectory()` 返回的
+     * 外部目录，或从外部目录派生/枚举得到时，在发送 bridge 请求前以 `FILE_ACCESS_DENIED` 拒绝。
+     * 外部目录授权即使为 `readwrite` 也不能删除其自身或任何后代。
+     * @throws {@link HbMiniProgramSDKError} 删除 `files.sandbox.directory('.')` 表示的 sandbox 根目录时
+     * 以 `FILE_ACCESS_DENIED` 拒绝；`recursive: true` 也不能绕过该边界。目标目录非空且
+     * `recursive` 为默认的 `false` 时返回 `DIRECTORY_NOT_EMPTY`。
+     * @throws {@link HbMiniProgramSDKError} 目标或任一祖先不存在时返回 `DIRECTORY_NOT_FOUND`，目标
+     * 实际是文件或路径中的祖先类型不匹配时返回 `FILE_TYPE_MISMATCH`。删除已经不存在的目录不会
+     * 当作幂等成功；需要“确保不存在”语义时应先接受缺失错误或在操作后调用 `exists()` 对账。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 权限时分别以
+     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；Host 未开放 `directory.remove` 时以
+     * `METHOD_FORBIDDEN` 拒绝，旧 Runtime 也可能返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} SDK 已销毁、Runtime 已卸载、请求超时、Host 拒绝删除或
+     * 发生底层 I/O 失败时，以 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`、
+     * `FILE_ACCESS_DENIED`、`FILE_IO_FAILED` 或 Host 保留的对应稳定文件错误码拒绝。
+     *
+     * @remarks
+     * 该方法只对当前 Mini-program identity 的 sandbox 子目录开放，并要求代理的
+     * `mode === 'readwrite'`。它不需要可信用户手势、不打开系统选择器、不暴露真实路径，也不会因为
+     * 传入 `recursive: true` 而跨出当前逻辑目录。picker 只负责授予外部访问，不能授予删除外部目录
+     * 树的能力；这一来源限制独立于 mode 和 Host 原生权限。
+     *
+     * `recursive: false` 是保护性默认值：空目录会删除，存在任意直接或间接子项时应返回
+     * `DIRECTORY_NOT_EMPTY`，且不应由 Runtime 自动重试为递归删除。`recursive: true` 明确授权 Host
+     * 删除该目录及其整个后代，包括文件、空目录和非空目录。Promise 只反映 Host 对本次请求的最终
+     * 结果；公开合同不承诺多对象删除具备事务原子性或失败后自动恢复已删除子项。
+     *
+     * 删除成功后，当前代理对象不会失效或自动改变 `name` / `mode`。随后
+     * {@link DirectoryHandle.exists | exists()} 应在目标仍不存在时返回 `false`，也可以调用
+     * {@link DirectoryHandle.create | create()} 在同一 sandbox 位置重新创建。两次调用之间仍存在
+     * 并发变化窗口，因此删除前的 `exists()` 或 `list()` 不能保证后续删除成功。
+     *
+     * 若只需删除单个 sandbox 文件，使用 {@link FileHandle.remove | FileHandle.remove()}；它没有
+     * `recursive` 选项。若希望保留目录并清理部分内容，应先通过 `list()` 取得直接子项，再按业务规则
+     * 删除 sandbox 项；不要对外部授权项调用 remove。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 宣告
+     * `files.remove` 时逐项启用，OHOS 同样以 Host 实际协商结果为准。Web、Browser Dev Host、旧 Host
+     * 或缺少该 operation 的环境会 fail closed，不提供浏览器文件系统或内存 fallback；页面应处理
+     * `METHOD_FORBIDDEN`，不要仅按操作系统推断可用性。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const cache = hbSDK.files.sandbox.directory('cache')
+     * await cache.create({ recursive: true })
+     * await cache.file('index.json').writeText('{}')
+     *
+     * try {
+     *   await cache.remove() // 默认 recursive: false，非空目录会拒绝。
+     * } catch (error) {
+     *   if (!(error instanceof HbMiniProgramSDKError) || error.code !== 'DIRECTORY_NOT_EMPTY') {
+     *     throw error
+     *   }
+     * }
+     *
+     * await cache.remove({ recursive: true })
+     * console.log(await cache.exists()) // false
+     *
+     * // 代理仍表示同一个 sandbox 位置。
+     * await cache.create()
+     * ```
+     *
+     * @see {@link DirectoryHandle.create | DirectoryHandle.create()} 显式确保目录和可选父目录存在。
+     * @see {@link DirectoryHandle.exists | DirectoryHandle.exists()} 删除后确认当前目录是否仍存在。
+     * @see {@link DirectoryHandle.list | DirectoryHandle.list()} 删除前枚举直接子项。
+     * @see {@link FileHandle.remove | FileHandle.remove()} 删除单个 sandbox 文件。
+     * @see [files.sandbox.directory()](/reference/sdk/files/sandbox/directory) 创建 sandbox 目录代理。
+     * @see [files.pickDirectory()](/reference/sdk/files/pickDirectory) 取得不可删除的外部目录授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看来源、权限、平台和错误码边界。
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     remove(options?: RemoveOptions): Promise<void>;
+    /**
+     * 检查目录是否存在。
+     *
+     * @returns Runtime 对当前目录引用执行一次 Host `stat` 后得到的 boolean 快照。目标目录存在且 Host
+     * 确认为目录时返回 `true`；目标或任一祖先不存在，目标实际是文件，或 Host 以
+     * `FILE_NOT_FOUND`、`DIRECTORY_NOT_FOUND`、`FILE_TYPE_MISMATCH` 报告同类状态时返回 `false`；Host
+     * stat 响应不是对象或 `kind` 不是 `'directory'` 时也按类型不匹配返回 `false`。不返回目录元数据、
+     * 句柄或缺失原因。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `directory.exists`
+     * （底层要求 `files.stat`）时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct directory handle 被撤销、不属于当前或已结束的
+     * Runtime session 时返回 `FILE_ACCESS_REVOKED`；Host 拒绝当前目录授权时返回 `FILE_ACCESS_DENIED`。
+     * 这些授权错误不会被转换为 `false`。
+     * @throws {@link HbMiniProgramSDKError} Host 返回未归类的错误、公开 bridge 返回非 boolean 结果或底层
+     * I/O 失败时返回 `FILE_IO_FAILED` 或对应稳定文件错误码。握手失败、SDK / Runtime 已终止或不可用、
+     * 调用超时时还可能返回 `HANDSHAKE_FAILED`、`SDK_DESTROYED`、`RUNTIME_DESTROYED`、
+     * `RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * `exists()` 是只读探测，`mode: 'read'` 与 `mode: 'readwrite'` 均可调用；它不要求可信用户手势，
+     * 不会创建目录、枚举子项、读取文件内容、延长外部授权寿命或占用新的 direct-handle 配额。sandbox
+     * lazy ref 会在每次调用时按当前 Mini-program identity 解析；picker 返回的外部目录授权只在当前
+     * Runtime session 有效。
+     *
+     * 每次调用都会发送新的 `directory.exists` 请求并重新查询 Host，不读取或更新 SDK 本地缓存。
+     * 返回值只描述该次查询完成时的状态：目录可能在 Promise resolve 后立即被其他代码创建、删除或
+     * 替换，因此先 `exists()` 再 `create()` / `list()` 存在 TOCTOU 竞态。必须继续处理后续操作自身的
+     * `DIRECTORY_NOT_FOUND`、`FILE_TYPE_MISMATCH`、授权和 I/O 错误；需要确保目录存在时，直接调用
+     * {@link DirectoryHandle.create | create()} 的幂等默认模式通常更合适。
+     *
+     * Runtime 内部通过 Host directory `stat` 判断 kind，但公开 `DirectoryHandle` 没有 `stat()` 方法，
+     * `exists()` 也不会暴露 size、时间戳或其他目录元数据。{@link FileHandle.stat | FileHandle.stat()}
+     * 只适用于文件；不要把它当作目录元数据入口。需要直接子项时调用
+     * {@link DirectoryHandle.list | list()}，它会重新访问 Host，不复用本次存在性结果。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 宣告 `files.stat` 时启用，
+     * OHOS 同样以 Host 实际协商结果为准。Web、Browser Dev Host、旧 Host 或缺少该 operation 的环境
+     * fail closed，返回 `METHOD_FORBIDDEN` / `METHOD_NOT_FOUND`，不会用浏览器 File / Blob 或内存目录
+     * 伪造 `false`。该操作只读取元数据，不受移动端 8 MiB 完整文件内容读写上限影响。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const cache = hbSDK.files.sandbox.directory('cache/images')
+     *
+     * try {
+     *   if (!(await cache.exists())) {
+     *     // 默认 create 是幂等的；recursive 同时确保父目录存在。
+     *     await cache.create({ recursive: true })
+     *   }
+     *
+     *   // exists() 与 list() 不是原子操作，list() 的错误仍需处理。
+     *   const entries = await cache.list({ limit: 100 })
+     *   console.log(entries.map(entry => entry.name))
+     * } catch (error) {
+     *   if (error instanceof HbMiniProgramSDKError && error.code === 'DIRECTORY_NOT_FOUND') {
+     *     console.warn('目录在检查后被删除，请刷新状态后重试')
+     *   } else {
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link DirectoryHandle.create | DirectoryHandle.create()} 幂等确保目录及可选父目录存在。
+     * @see {@link DirectoryHandle.list | DirectoryHandle.list()} 重新访问 Host 并枚举直接子项。
+     * @see {@link FileHandle.exists | FileHandle.exists()} 对文件目标执行相同的存在性归一化。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 文件专属的公开元数据快照。
+     * @see [files.sandbox.directory()](/reference/sdk/files/sandbox/directory) 创建 sandbox lazy DirectoryHandle。
+     * @see [files.pickDirectory()](/reference/sdk/files/pickDirectory) 取得当前 session 的外部目录授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看权限、平台和错误边界。
+     */
     exists(): Promise<boolean>;
+    /**
+     * 枚举当前目录的直接子项。
+     *
+     * @param options - 可选的单次结果数量上限。省略 options、传 `{}` 或省略 `limit` 时使用
+     * `1000`；完整范围见 {@link ListOptions}。
+     * @returns 当前目录直接子项的冻结 {@link FileHandle} / {@link DirectoryHandle} 代理数组；空目录
+     * 返回 `[]`。数组与每个代理都是本次调用的新结果，条目 `mode` 与当前目录严格一致，`name` 只含
+     * basename，不包含父路径或 Host 真实路径。不会递归返回后代。
+     * @throws {@link HbMiniProgramSDKError} options 不是对象，或 `limit` 不是正的 safe integer 时返回
+     * `INVALID_PARAMS`；`limit > 1000`，或 Host 返回项目数超过有效 `limit` 时返回
+     * `DIRECTORY_LIST_LIMIT_EXCEEDED`。
+     * @throws {@link HbMiniProgramSDKError} 当前目录或任一祖先不存在时返回 `DIRECTORY_NOT_FOUND`，目标
+     * 实际是文件时返回 `FILE_TYPE_MISMATCH`；外部 direct Directory 授权失效、来自其他或已结束的
+     * Runtime session 时返回 `FILE_ACCESS_REVOKED`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `directory.list` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} Host 返回非数组、稀疏数组、非法 kind/name/mode/handle，或
+     * 子项不能安全派生为当前目录的直接后代时返回 `FILE_IO_FAILED`；其他 Host 枚举或底层 I/O 失败
+     * 返回对应稳定文件错误码，无法识别的 Host 错误统一为 `FILE_IO_FAILED`。
+     *
+     * @remarks
+     * `list()` 只枚举一层，不排序、不去重，也不补齐分页。结果顺序以及达到 `limit` 时选择哪些条目
+     * 由 Host 文件系统决定；调用方不能依赖字母序、创建时间序或跨调用稳定顺序。需要稳定展示时应按
+     * `name` 等业务规则自行排序。公开结果没有 `total`、`hasMore` 或 continuation cursor，因此
+     * `limit` 不应被当作可完整遍历超大目录的分页协议。
+     *
+     * Runtime 逐槽读取 Host 数组，拒绝稀疏或越界结果，并把每个 Host 文件/目录转换成当前目录的直接
+     * 子逻辑引用；SDK 再验证所有 descriptor 都继承父目录 `mode`。从 `read` 目录列出的代理仍只读，
+     * 从 `readwrite` 目录列出的代理可在原授权范围内写入，但枚举不会提升权限或扩大到父目录之外。
+     *
+     * 返回项不会作为新的 external direct handles 注册，因此不消耗 picker / `saveFile()` 共享的 1024
+     * direct-handle 配额。它们仍依赖原目录的来源和生命周期：sandbox 子项按当前 Mini-program identity
+     * 解析；外部目录的子项只在原 direct Directory 所属的当前 Runtime session 内有效，session 结束或
+     * 授权撤销后后续操作会失败。列表只是本次枚举快照，返回后文件系统可以继续变化。
+     *
+     * `mode: 'read'` 与 `mode: 'readwrite'` 目录都能调用。该方法不要求可信用户手势，不创建、读取或
+     * 修改文件内容；外部目录只有最初调用 `pickDirectory()` 时需要手势。新 PC Host 支持该操作；
+     * Android / iOS `1.3.396+` 仅在 `system.describe` 宣告 `files.list` 时逐项启用，OHOS 同样以 Host
+     * 实际协商结果为准。Web、Browser Dev Host、旧 Host 或 operation 缺失时 fail closed，不提供
+     * 浏览器文件系统、File / Blob 或内存 fallback。
+     *
+     * 若只需判断目录本身是否存在，使用 {@link DirectoryHandle.exists | exists()}。已知子项名称时，
+     * 可直接通过当前目录的 {@link PathRoot.file | file()} 或 {@link PathRoot.directory | directory()}
+     * 构造 lazy proxy，无需先枚举；这两个方法同样不会执行 I/O 或占用 direct-handle 配额。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const reports = hbSDK.files.sandbox.directory('reports')
+     * await reports.create({ recursive: true })
+     * await reports.file('summary.json').writeText('{}')
+     * await reports.directory('archive').create()
+     *
+     * const entries = await reports.list({ limit: 100 })
+     * const sorted = [...entries].sort((left, right) => left.name.localeCompare(right.name))
+     * for (const entry of sorted) {
+     *   if (entry.kind === 'file') console.log('file', entry.name, await entry.stat())
+     *   else console.log('directory', entry.name, await entry.exists())
+     * }
+     * ```
+     *
+     * @see {@link ListOptions}
+     * @see {@link FileSystemEntity}
+     * @see {@link PathRoot.file | DirectoryHandle.file()} 构造已知名称的直接或嵌套文件代理。
+     * @see {@link PathRoot.directory | DirectoryHandle.directory()} 构造已知名称的直接或嵌套目录代理。
+     * @see {@link DirectoryHandle.exists | DirectoryHandle.exists()} 检查当前目录是否存在。
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory} 取得当前 session 的外部目录授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看权限、路径、平台与配额边界。
+     */
     list(options?: ListOptions): Promise<FileSystemEntity[]>;
 }
+/** 目录枚举返回的文件或目录代理。 */
 export type FileSystemEntity = FileHandle | DirectoryHandle;
+/**
+ * {@link FileHandle.stat} 返回的文件元数据快照。
+ *
+ * @remarks
+ * Runtime 与 SDK 会把 Host 结果规范为这四个公开字段；Host 的额外字段不会进入结果。每次 `stat()`
+ * 返回新对象，它不是缓存或 live view，也不冻结；调用方修改字段不会改变文件或后续快照。
+ *
+ * 单位是公开合同而不是可从 number 结构证明的事实：`size` 按 byte 解释，时间字段按 Unix epoch
+ * milliseconds 解释。SDK 无法验证 Host 实际单位、时间来源、字段之间的顺序关系或快照 resolve 后是否仍
+ * 与磁盘一致。
+ */
 export interface FileStat {
+    /** 固定为 `'file'`，用于和 Host 的目录状态区分。 */
     kind: 'file';
+    /**
+     * 本次快照中的文件大小，公开约定单位为 byte。必须是 `0` 到 `Number.MAX_SAFE_INTEGER` 的整数；
+     * `0` 表示空文件。负数、小数、`NaN`、Infinity、unsafe integer 或数字字符串会使 `stat()` 以
+     * `FILE_IO_FAILED` 拒绝。
+     */
     size: number;
-    /** Unix epoch milliseconds。 */
+    /**
+     * Host 可提供的最后修改时间，公开约定为 Unix epoch milliseconds。可独立省略；存在时只保证为
+     * 非负有限 number，允许小数和超过 `Number.MAX_SAFE_INTEGER` 的值，不保证可构造有效 `Date`。
+     */
     modifiedAt?: number;
-    /** Unix epoch milliseconds。 */
+    /**
+     * Host 可提供的创建时间，公开约定为 Unix epoch milliseconds。可独立省略；范围规则与
+     * {@link FileStat.modifiedAt} 相同，也不保证早于或等于 `modifiedAt`。
+     */
     createdAt?: number;
 }
-/** Mini-program 对外文件能力。 */
+/**
+ * Mini-program 对外文件能力。
+ *
+ * @remarks
+ * `sandbox` 提供隔离持久存储；picker 与 `saveFile()` 通过可信用户操作授予当前 Runtime session
+ * 最小化的外部访问范围。所有能力要求声明 `filesystem`，具体 operation 还需由 Host 宣告支持。
+ */
 export interface FilesModule {
+    /** 当前 Mini-program 的私有 sandbox 逻辑根。 */
     readonly sandbox: FileSystem;
     /**
      * 让用户选择一个或多个文件并返回当前 session 的授权代理。
      *
-     * @param options - 访问模式、扩展名筛选与多选设置。
-     * @returns 用户选择的文件代理。
-     * @remarks Android `1.3.396` 的精确 SAF 文件仅支持只读选择；请求 `readwrite` 会返回 `FILE_ACCESS_DENIED`。
+     * @param options - 可选访问模式、扩展名筛选与多选设置；完整默认值和校验见
+     * {@link PickFilesOptions}。
+     * @returns 非空的冻结 {@link FileHandle} 数组。默认单选时恰好一项；每项 `kind` 固定为
+     * `'file'`，`name` 是安全 basename，`mode` 与请求模式一致，且不包含真实路径。用户取消会
+     * 抛错，不返回空数组或 `undefined`。
+     * @throws {@link HbMiniProgramSDKError} options、`mode`、`accept` 或 `multiple` 非法时返回
+     * `INVALID_PARAMS`；缺少当前可信用户手势时返回 `USER_GESTURE_REQUIRED`；用户取消系统选择器
+     * 时返回 `FILE_PICKER_CANCELLED`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放/未协商到 `files.external` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`；请求的 `readwrite` 未获 Host
+     * 授予时返回 `FILE_ACCESS_DENIED`。
+     * @throws {@link HbMiniProgramSDKError} 整批结果会让当前 session 的外部 direct handle 超过
+     * 1024 时返回 `FILE_QUOTA_EXCEEDED`，且不保留部分结果；授权在完成前失效、Host 返回空数组、
+     * 单选返回多项、结果结构/name/mode 非法或其他 picker/I/O 失败时返回
+     * `FILE_ACCESS_REVOKED` / `FILE_IO_FAILED` 等稳定文件错误码。
+     *
+     * @remarks
+     * 必须直接从按钮点击等可信用户操作调用。不要先 `await` 握手或其他异步任务；应提前通过
+     * `getHandshakeState()` / `onHandshakeStateChange()` 控制按钮只在 ready 时可用，再在点击回调
+     * 中立即调用 picker。取消是正常用户结果，应按 `FILE_PICKER_CANCELLED` 结束当前流程。
+     *
+     * 默认 `mode: 'read'`、`multiple: false` 且无 `accept`。返回的是用户选择范围内的精确外部
+     * File direct handles，不是浏览器原生 `File`，不能扩张到父目录或兄弟文件；每项授权只在
+     * 当前 Runtime session 有效，session 结束或授权撤销后不能恢复或持久化复用。单个 session
+     * 的 picker / `saveFile()` direct handle 共享 1024 上限，每个返回文件占用一个。
+     *
+     * `read` File 可调用 `readText()`、`readBytes()`、`exists()` 与 `stat()`；写入、创建及作为
+     * 下载替换目标需要 `readwrite`。外部精确 File 无论 mode 都不能删除。Android `1.3.396+`
+     * 的精确 SAF 文件只支持只读选择，请求 `readwrite` 会返回 `FILE_ACCESS_DENIED`；其他平台也
+     * 以 Host 实际授予结果为准。
+     *
+     * 新 PC Host 支持文件选择；Android/iOS 需要 `1.3.396+`，移动端继续以 `system.describe`
+     * 实际声明的 operation 为准；OHOS 同样按 Host 宣告能力启用。Web、Browser Dev Host、旧 Host
+     * 或 operation 集不完整时 fail closed，不提供浏览器 File/Blob 或内存 fallback。页面代码不应
+     * 按操作系统猜测可用性，应处理 `METHOD_FORBIDDEN`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const chooseFilesButton = document.querySelector<HTMLButtonElement>('#choose-files')!
+     *
+     * chooseFilesButton.addEventListener('click', async () => {
+     *   try {
+     *     const files = await hbSDK.files.pickFiles({
+     *       mode: 'read',
+     *       accept: ['.json', '.txt'],
+     *       multiple: true,
+     *     })
+     *
+     *     for (const file of files) {
+     *       console.log(file.kind, file.name, file.mode, await file.readText())
+     *     }
+     *   } catch (error) {
+     *     if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_PICKER_CANCELLED') return
+     *     throw error
+     *   }
+     * })
+     * ```
+     *
+     * @see {@link PickFilesOptions}
+     * @see {@link FileHandle}
+     * @see {@link FileHandle.readText}
+     * @see {@link FileHandle.readBytes}
+     * @see {@link FileHandle.stat}
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory}
+     * @see {@link FilesModule.saveFile | files.saveFile}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.8.0-alpha.2
      * @hbPlatform android
      * @hbPlatform ios
@@ -124,8 +1375,70 @@ export interface FilesModule {
     /**
      * 让用户选择目录并返回当前 session 的授权代理。
      *
-     * @param options - 目录访问模式。
-     * @returns 用户选择的目录代理。
+     * @param options - 可选目录授权模式；省略时等同于 `{ mode: 'read' }`，完整规则见
+     * {@link PickDirectoryOptions}。
+     * @returns 用户选中的冻结 {@link DirectoryHandle} direct proxy。`kind` 固定为
+     * `'directory'`，`name` 是安全 basename，`mode` 与请求模式一致；不包含真实路径。取消会抛错，
+     * 不返回 `undefined`。
+     * @throws {@link HbMiniProgramSDKError} options 或 `mode` 非法时返回 `INVALID_PARAMS`；缺少当前
+     * 可信用户手势时返回 `USER_GESTURE_REQUIRED`；用户取消系统选择器时返回
+     * `FILE_PICKER_CANCELLED`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放/未协商到 `files.external` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`；请求的 `readwrite` 未获 Host
+     * 授予时返回 `FILE_ACCESS_DENIED`。
+     * @throws {@link HbMiniProgramSDKError} 当前 session 的外部 direct handle 达到 1024 上限时返回
+     * `FILE_QUOTA_EXCEEDED`；授权在完成前失效、Host 结果非法/mode 不匹配或其他 picker/I/O 失败时
+     * 返回 `FILE_ACCESS_REVOKED` 或 `FILE_IO_FAILED` 等稳定文件错误码。
+     *
+     * @remarks
+     * 必须直接从按钮点击等可信用户操作调用。不要先 `await` 握手或其他异步任务；应提前通过
+     * `getHandshakeState()` / `onHandshakeStateChange()` 控制按钮只在 ready 时可用，再在点击回调
+     * 中立即调用 picker。取消是正常用户结果，应按 `FILE_PICKER_CANCELLED` 结束当前流程。
+     *
+     * 默认授权模式为 `read`。返回的是用户选择范围的精确外部目录授权，只在当前 Runtime
+     * session 有效；session 结束或授权撤销后不能恢复或持久化复用。其 `file()` / `directory()`
+     * 派生项及 `list()` 结果继承 mode、不能提升权限，也不会继续占用 direct handle 配额。
+     * `readwrite` 允许在授权目录内创建/写入以及作为 `network.download()` target，但外部目录及
+     * 其后代仍不能删除。
+     *
+     * 单个 Runtime session 最多保留 1024 个 picker / `saveFile()` direct handles；每次成功的
+     * `pickDirectory()` 占用一个。它与 sandbox 的逻辑代理不同：
+     * {@link FileSystem.directory | files.sandbox.directory} 不打开选择器、无需用户手势、持久按
+     * Mini-program 隔离，也不占用该 direct-handle 配额。
+     *
+     * 新 PC Host 支持目录选择；Android/iOS 需要 `1.3.396+`，移动端继续以 `system.describe`
+     * 实际声明的 operation 为准；OHOS 同样按 Host 宣告能力启用。Web、Browser Dev Host、旧 Host
+     * 或 operation 集不完整时 fail closed，不提供 Blob/内存 fallback。页面代码不应按操作系统
+     * 猜测可用性，应处理 `METHOD_FORBIDDEN`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const chooseDirectoryButton = document.querySelector<HTMLButtonElement>('#choose-directory')!
+     *
+     * chooseDirectoryButton.addEventListener('click', async () => {
+     *   try {
+     *     const directory = await hbSDK.files.pickDirectory({ mode: 'readwrite' })
+     *     console.log(directory.kind, directory.name, directory.mode)
+     *     await directory.file('report.txt').writeText('done')
+     *   } catch (error) {
+     *     if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_PICKER_CANCELLED') return
+     *     throw error
+     *   }
+     * })
+     * ```
+     *
+     * @see {@link PickDirectoryOptions}
+     * @see {@link DirectoryHandle}
+     * @see {@link FileSystem.directory | files.sandbox.directory}
+     * @see {@link FilesModule.saveFile | files.saveFile}
+     * @see {@link MiniProgramNetworkModule.download | network.download}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.8.0-alpha.2
      * @hbPlatform android
      * @hbPlatform ios
@@ -142,8 +1455,70 @@ export interface FilesModule {
     /**
      * 让用户选择一个精确的文件保存目标。
      *
-     * @param options - 建议文件名。
-     * @returns 具备读写权限的目标文件代理。
+     * @param options - 必填的保存目标建议 basename；完整校验见 {@link SaveFileOptions}。
+     * @returns 用户确认后的冻结 {@link FileHandle} direct proxy。`kind` 固定为 `'file'`，`name`
+     * 是 Host 最终文件 basename，`mode` 固定为 `'readwrite'`；不包含真实路径，也不授予父目录或
+     * 兄弟文件访问权。
+     * @throws {@link HbMiniProgramSDKError} options 缺失/非对象、`suggestedName` 非字符串或不是规范
+     * basename、或传入 V1 不支持的 `accept` 时返回 `INVALID_PARAMS`；缺少当前可信用户手势时
+     * 返回 `USER_GESTURE_REQUIRED`；用户取消系统保存界面时返回 `FILE_PICKER_CANCELLED`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放/未协商到保存 operation 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。目标已存在且 Host 不能独占创建
+     * 时返回 `FILE_ALREADY_EXISTS`，不会静默覆盖。
+     * @throws {@link HbMiniProgramSDKError} 当前 session 的外部 direct handle 达到 1024 上限时返回
+     * `FILE_QUOTA_EXCEEDED`；授权在完成前失效、Host 返回非精确 File、非 `readwrite` mode、非法
+     * descriptor 或其他 picker/I/O 失败时返回 `FILE_ACCESS_REVOKED` / `FILE_IO_FAILED` 等稳定
+     * 文件错误码。
+     *
+     * @remarks
+     * 必须直接从按钮点击等可信用户操作调用。不要先 `await` 握手或其他异步任务；应提前通过
+     * `getHandshakeState()` / `onHandshakeStateChange()` 控制按钮只在 ready 时可用，再在点击回调
+     * 中立即调用。取消是正常用户结果，应按 `FILE_PICKER_CANCELLED` 结束当前流程。
+     *
+     * 返回的是当前 Runtime session 内一个精确外部 File 授权，不会额外保留或暴露父 Directory
+     * handle。它占用 picker / `saveFile()` 共享的 1024 direct-handle 配额中的一个；session 结束
+     * 或授权撤销后不能恢复或持久化复用。代理固定 `readwrite`，可调用 `writeText()` /
+     * `writeBytes()`，或作为 {@link MiniProgramNetworkModule.download | network.download} 的 File
+     * target；外部授权仍不能调用 `remove()`。
+     *
+     * V1 没有 overwrite 选项。当前新 PC Host 先让用户选择保存目录，再以 `suggestedName` 独占
+     * 创建空文件；同名目标返回 `FILE_ALREADY_EXISTS`。其他 Host 可以展示平台原生保存界面，
+     * 但成功结果仍只授权最终精确 File，且不能通过该 API 请求静默覆盖。
+     *
+     * 新 PC 与 iOS Host 支持该能力；Android 不提供 `files.saveFile`。OHOS 按 Host 实际宣告的
+     * operation 启用。Web、Browser Dev Host、旧 Host 或 operation 集不完整时 fail closed，不
+     * 提供 Blob/内存 fallback。页面代码不应仅按操作系统判断，应处理 `METHOD_FORBIDDEN`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const saveButton = document.querySelector<HTMLButtonElement>('#save-report')!
+     *
+     * saveButton.addEventListener('click', async () => {
+     *   try {
+     *     const file = await hbSDK.files.saveFile({ suggestedName: 'report.json' })
+     *     await file.writeText(JSON.stringify({ ok: true }))
+     *     console.log(file.kind, file.name, file.mode)
+     *   } catch (error) {
+     *     if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_PICKER_CANCELLED') return
+     *     throw error
+     *   }
+     * })
+     * ```
+     *
+     * @see {@link SaveFileOptions}
+     * @see {@link FileHandle}
+     * @see {@link FileHandle.writeText}
+     * @see {@link FileHandle.writeBytes}
+     * @see {@link FilesModule.pickFiles | files.pickFiles}
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory}
+     * @see {@link MiniProgramNetworkModule.download | network.download}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.8.0-alpha.2
      * @hbPlatform ios
      * @hbPlatform ohos