可选options: PickDirectoryOptions可选目录授权模式；省略时等同于 { mode: 'read' }，完整规则见
PickDirectoryOptions。
用户选中的冻结 DirectoryHandle direct proxy。kind 固定为
'directory'，name 是安全 basename，mode 与请求模式一致；不包含真实路径。取消会抛错，
不返回 undefined。
HbMiniProgramSDKError options 或 mode 非法时返回 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 结果非法/mode 不匹配或其他 picker/I/O 失败时
返回 FILE_ACCESS_REVOKED 或 FILE_IO_FAILED 等稳定文件错误码。
必须直接从按钮点击等可信用户操作调用。不要先 await 握手或其他异步任务；应提前通过
getHandshakeState() / onHandshakeStateChange() 控制按钮只在 ready 时可用，再在点击回调
中立即调用 picker。取消是正常用户结果，应按 FILE_PICKER_CANCELLED 结束当前流程。
选择器等待不设固定超时；用户确认、取消或当前 SDK / Runtime 会话结束后才结束操作。
默认授权模式为 read。返回的是用户选择范围的精确外部目录授权，只在当前 Runtime
session 有效；session 结束或授权撤销后不能恢复或持久化复用。其 file() / directory()
派生项及 list() 结果继承 mode、不能提升权限，也不会继续占用 direct handle 配额。
readwrite 允许在授权目录内创建/写入以及作为 network.download() target，但外部目录及
其后代仍不能删除。
单个 Runtime session 最多保留 1024 个 picker / saveFile() direct handles；每次成功的
pickDirectory() 占用一个。它与 sandbox 的逻辑代理不同：
files.sandbox.directory 不打开选择器、无需用户手势、持久按
Mini-program 隔离，也不占用该 direct-handle 配额。
鸿蒙手机和平板的单目录选择需要系统 API 26.0.0 或以上；较早系统需具备
SystemCapability.FileManagement.UserFileService.FolderSelection 能力。
同时要求当前客户端已适配并开放目录选择，不支持时抛出 METHOD_FORBIDDEN。
不具备上述能力的 API 24 鸿蒙手机无法选择外部目录，声明 filesystem 或升级编译 SDK
不会解除限制。单文件读写或导出可分别使用 pickFiles()、saveFile()，不授予父目录权限。
新 PC Host 支持目录选择；Android/iOS 需要 1.3.396+，移动端继续以 system.describe
实际声明的 operation 为准；OHOS 同样按 Host 宣告能力启用。Web、Browser Dev Host、旧 Host
或 operation 集不完整时 fail closed，不提供 Blob/内存 fallback。页面代码不应按操作系统
猜测可用性，应处理 METHOD_FORBIDDEN。
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
}
})
让用户选择目录并返回当前 session 的授权代理。