必填的保存目标建议 basename；完整校验见 SaveFileOptions。
用户确认后的冻结 FileHandle direct proxy。kind 固定为 'file'，name
是 Host 最终文件 basename，mode 固定为 'readwrite'；不包含真实路径，也不授予父目录或
兄弟文件访问权。
HbMiniProgramSDKError options 缺失/非对象、suggestedName 非字符串或不是规范
basename、或传入 V1 不支持的 accept 时返回 INVALID_PARAMS；缺少当前可信用户手势时
返回 USER_GESTURE_REQUIRED；用户取消系统保存界面时返回 FILE_PICKER_CANCELLED。
HbMiniProgramSDKError 当前运行快照缺少或未启用 filesystem 时返回
PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED；Host 未开放/未协商到保存 operation 时返回
METHOD_FORBIDDEN，旧 Runtime 可返回 METHOD_NOT_FOUND。目标已存在且 Host 不能独占创建
时返回 FILE_ALREADY_EXISTS，不会静默覆盖。
HbMiniProgramSDKError 当前 session 的外部 direct handle 达到 1024 上限时返回
FILE_QUOTA_EXCEEDED；授权在完成前失效、Host 返回非精确 File、非 readwrite mode、非法
descriptor 或其他 picker/I/O 失败时返回 FILE_ACCESS_REVOKED / FILE_IO_FAILED 等稳定
文件错误码。
必须直接从按钮点击等可信用户操作调用。不要先 await 握手或其他异步任务；应提前通过
getHandshakeState() / onHandshakeStateChange() 控制按钮只在 ready 时可用，再在点击回调
中立即调用。取消是正常用户结果，应按 FILE_PICKER_CANCELLED 结束当前流程。
选择器等待不设固定超时；用户确认、取消或当前 SDK / Runtime 会话结束后才结束操作。
返回的是当前 Runtime session 内一个精确外部 File 授权，不会额外保留或暴露父 Directory
handle。它占用 picker / saveFile() 共享的 1024 direct-handle 配额中的一个；session 结束
或授权撤销后不能恢复或持久化复用。代理固定 readwrite，可调用 writeText() /
writeBytes()，或作为 network.download 的 File
target；外部授权仍不能调用 remove()。
V1 没有 overwrite 选项。当前新 PC Host 先让用户选择保存目录，再以 suggestedName 独占
创建空文件；同名目标返回 FILE_ALREADY_EXISTS。其他 Host 可以展示平台原生保存界面，
但成功结果仍只授权最终精确 File，且不能通过该 API 请求静默覆盖。
Android 已适配客户端支持 files.saveFile，系统保存器返回精确 SAF 文件授权，不授予
父目录权限。writeText() / writeBytes() 先暂存完整内容，再写入该目标；最终 Provider
写入不是原子替换，失败时目标可能为空或部分写入，原内容不保证保留。该授权不支持
network.download() 的原子替换，导出请调用文件代理的写入方法。
新 PC、Android 与 iOS Host 支持该能力。OHOS 按 Host 实际宣告的
operation 启用。Web、Browser Dev Host、旧 Host 或 operation 集不完整时 fail closed，不
提供 Blob/内存 fallback。页面代码不应仅按操作系统判断，应处理 METHOD_FORBIDDEN。
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
}
})
让用户选择一个精确的文件保存目标。