可选options: PickFilesOptions可选访问模式、扩展名筛选与多选设置；完整默认值和校验见 PickFilesOptions。
非空的冻结 FileHandle 数组。默认单选时恰好一项；每项 kind 固定为
'file'，name 是安全 basename，mode 与请求模式一致，且不包含真实路径。用户取消会
抛错，不返回空数组或 undefined。
HbMiniProgramSDKError options、mode、accept 或 multiple 非法时返回
INVALID_PARAMS；缺少当前可信用户手势时返回 USER_GESTURE_REQUIRED；用户取消系统选择器
时返回 FILE_PICKER_CANCELLED。
HbMiniProgramSDKError 当前运行快照缺少或未启用 filesystem 时返回
PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED；Host 未开放/未协商到 files.external 时返回
METHOD_FORBIDDEN，旧 Runtime 可返回 METHOD_NOT_FOUND；请求的 readwrite 未获 Host
授予时返回 FILE_ACCESS_DENIED。
HbMiniProgramSDKError 整批结果会让当前 session 的外部 direct handle 超过
1024 时返回 FILE_QUOTA_EXCEEDED，且不保留部分结果；授权在完成前失效、Host 返回空数组、
单选返回多项、结果结构/name/mode 非法或其他 picker/I/O 失败时返回
FILE_ACCESS_REVOKED / FILE_IO_FAILED 等稳定文件错误码。
必须直接从按钮点击等可信用户操作调用。不要先 await 握手或其他异步任务；应提前通过
getHandshakeState() / onHandshakeStateChange() 控制按钮只在 ready 时可用，再在点击回调
中立即调用 picker。取消是正常用户结果，应按 FILE_PICKER_CANCELLED 结束当前流程。
选择器等待不设固定超时；用户确认、取消或当前 SDK / Runtime 会话结束后才结束操作。
默认 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 已适配客户端
支持精确 SAF 文件的 readwrite 选择，需系统返回写入授权；较早客户端仍会拒绝该模式。
writeText() / writeBytes() 先暂存完整内容再写入，最终 Provider 写入不是原子替换，
失败时原文件可能为空或只写入部分内容。该授权不支持 network.download() 的原子替换。
未指定模式时仍为只读；用户或 Provider 未授予写入权限时返回 FILE_ACCESS_DENIED。
新 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。
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
}
})
让用户选择一个或多个文件并返回当前 session 的授权代理。