确保文件存在并返回同一个代理。
可选options: CreateOptions可选的父目录创建与目标独占创建设置。省略时等同于
{ recursive: false, exclusive: false }；完整语义见 CreateOptions。
当前同一个 FileHandle proxy；成功后 result === file。方法不会读取文件，且默认的
ensure-exists 不会截断或改写已有内容。
HbMiniProgramSDKError options 非对象，或 recursive / exclusive 不是 boolean 时
返回 INVALID_PARAMS；代理不是 readwrite 时在发送 bridge 请求前返回 FILE_ACCESS_DENIED。
HbMiniProgramSDKError 当前运行快照缺少或未启用 filesystem 时返回
PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED；Host 未开放或未协商到 file.create 时返回
METHOD_FORBIDDEN，旧 Runtime 可返回 METHOD_NOT_FOUND。
HbMiniProgramSDKError recursive: false 且父目录缺失时返回
DIRECTORY_NOT_FOUND；目标实际是目录或路径中的祖先实际是文件时返回 FILE_TYPE_MISMATCH；
exclusive: true 且文件已存在时返回 FILE_ALREADY_EXISTS。
HbMiniProgramSDKError 外部 direct handle 已失效或不属于当前 Runtime session 时返回
FILE_ACCESS_REVOKED；Host 创建失败、响应异常或底层平台 I/O 失败时返回相应稳定文件错误码，
无法识别的 Host 错误统一为 FILE_IO_FAILED。
目标缺失时创建空文件。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 协商结果启用。外部精确 File 只有实际获授 readwrite
时才能调用本方法；较早 Android 客户端可能仅授予 read。Web、Browser Dev Host、旧 Host
或 operation 集不完整时 fail closed，不提供 Blob 或内存 fallback。
create() 只创建空目标。父目录已经存在时，FileHandle.writeText /
FileHandle.writeBytes 也可隐式创建文件并写入内容；它们不会自动创建父目录。若需要先确保
目录存在，使用 DirectoryHandle.create；只需探测目标时使用 FileHandle.exists。
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
}
检查当前代理是否仍解析到一个文件。
Host 能取得目标且确认其类型为文件时返回 true。目标文件不存在、任一祖先目录
不存在，或同一逻辑位置实际是目录时返回 false；这些正常的“不存在”结果不会抛出
FILE_NOT_FOUND、DIRECTORY_NOT_FOUND 或 FILE_TYPE_MISMATCH。
HbMiniProgramSDKError 当前运行快照缺少或未启用 filesystem 权限时分别以
PERMISSION_NOT_IN_SNAPSHOT、PERMISSION_DENIED 拒绝；当前 Host 未开放 file.exists 时以
METHOD_FORBIDDEN 拒绝，旧 Runtime 也可能返回 METHOD_NOT_FOUND。
HbMiniProgramSDKError picker / saveFile() 返回的精确外部授权被撤销、句柄
不属于当前 Runtime session 或 registry 已释放时，以 FILE_ACCESS_REVOKED 拒绝，而不是返回
false；SDK 已销毁或 Runtime 已卸载时分别以 SDK_DESTROYED、RUNTIME_UNAVAILABLE 拒绝。
HbMiniProgramSDKError Host 拒绝访问、stat 探测失败、返回非布尔 bridge 结果
或发生其他文件 I/O 失败时，以 FILE_ACCESS_DENIED、FILE_IO_FAILED 或对应 SDK / bridge
错误拒绝。调用方不应把所有异常都解释为“不存在”。
这是只读查询，不创建文件、不读取内容、不修改访问模式，也不要求可信用户手势。
mode: 'read' 与 mode: 'readwrite' 的 FileHandle 均可调用；但成功返回 true 不会
授予写权限，后续 create()、写入或删除仍受当前 mode、来源和 Host operation 限制。
Runtime 使用 Host 的文件状态原语完成检查，但该布尔结果不是 stat()
的缓存或替代品，也不包含大小与时间戳。它只描述本次探测时的状态：目标可能在 resolve 后
被删除、替换或撤销授权，因此后续 readText()、stat() 或写入仍可能失败；不要用
exists() 作为权限检查或消除并发竞态。
对 sandbox lazy proxy，返回 false 后可在 readwrite 模式下调用
create() 显式确保文件存在；缺失父目录时由 create({ recursive: true })
决定是否一并创建。对 picker / saveFile() 的精确外部 FileHandle，授权失效属于错误，不等价于
文件不存在。若要检查目录，应使用 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，不要仅按操作系统推断可用性。
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
}
}
将完整文件读取为新的字节数组。
包含完整文件原始字节的新 Uint8Array。空文件返回长度为 0 的数组。Runtime 会先
复制 Host 字节，SDK 验证 bridge 结果后再创建当前可见区间的副本，因此返回值不与 Host / bridge
响应共享可变存储；修改数组只改变调用方的本地副本，不会写回文件。
HbMiniProgramSDKError 目标或祖先不存在时返回 FILE_NOT_FOUND / DIRECTORY_NOT_FOUND，
目标类型不匹配时返回 FILE_TYPE_MISMATCH。Android / iOS 当前对一次完整读取设 8 MiB
（8 * 1024 * 1024 bytes）上限，超限时返回 FILE_TOO_LARGE。
HbMiniProgramSDKError 使用普通 sandbox / picker / saveFile() 句柄时，运行快照缺少或未启用
filesystem 时返回 PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED；Host 未开放或未协商到
file.readBytes 时返回 METHOD_FORBIDDEN，旧 Runtime 可返回 METHOD_NOT_FOUND。
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 或对应稳定文件错误码。
该方法读取并缓冲整个文件，不提供 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 时使用
readText()；需要把修改后的字节完整覆盖回文件时使用
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 判断。
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
}
}
将完整文件按文本读取。
Runtime 将 Host 返回的完整字节序列按严格 UTF-8 解码后的字符串。空文件返回 ''；
换行、NUL 与其他合法 Unicode 内容保持不变。UTF-8 decoder 会剥离第一个开头 BOM；若解码结果
仍以 U+FEFF 开头，Runtime 再移除一个，因此一到两个连续前导 UTF-8 BOM 都不会出现在结果中。
HbMiniProgramSDKError 文件不是合法 UTF-8 时返回 FILE_ENCODING_INVALID，不会用
replacement character 静默替换坏字节。需要无损读取任意二进制或保留 BOM 时使用
readBytes()。
HbMiniProgramSDKError 目标或祖先不存在时返回 FILE_NOT_FOUND / DIRECTORY_NOT_FOUND，
目标类型不匹配时返回 FILE_TYPE_MISMATCH。Android/iOS 当前对一次完整读取设 8 MiB 上限，
超限时返回 FILE_TOO_LARGE。
HbMiniProgramSDKError 使用普通 sandbox / picker / saveFile() 句柄时，运行快照缺少或未启用
filesystem 时返回 PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED；Host 未开放或未协商到
file.readText 时返回 METHOD_FORBIDDEN，旧 Runtime 可返回 METHOD_NOT_FOUND。
HbMiniProgramSDKError 外部 direct handle 已失效、来自其他或已结束的 Runtime
session 时返回 FILE_ACCESS_REVOKED；SDK / Runtime 已终止、调用超时、Host 返回无效内容或底层
I/O 失败时返回 SDK_DESTROYED、RUNTIME_DESTROYED、REQUEST_TIMEOUT 或 FILE_IO_FAILED 等
对应 SDK 错误。
该方法读取并缓冲整个文件，没有 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 生命周期约束。
writeText() 执行相反方向的完整 UTF-8 编码与覆盖写入；它不会添加 BOM，
且要求 mode === 'readwrite'。若内容可能不是文本，或业务需要区分 BOM 和文件正文，应使用
readBytes() 获取原始字节并自行解析。
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
}
}
删除当前代理指向的 sandbox 文件。
Host 完成删除后以 undefined resolve；当前 FileHandle 代理本身仍可复用，后续可用
exists() 确认目标已不存在，或用 create()
在同一位置重新创建文件。
HbMiniProgramSDKError 代理为只读，或来源是 pickFiles()、saveFile()、外部
Directory 派生项/枚举项时返回 FILE_ACCESS_DENIED；外部授权即使为 readwrite 也不能删除。
HbMiniProgramSDKError 目标或祖先不存在时返回 FILE_NOT_FOUND /
DIRECTORY_NOT_FOUND，目标实际是目录时可返回 FILE_TYPE_MISMATCH；授权失效或 Host 删除失败
时返回 FILE_ACCESS_REVOKED / FILE_IO_FAILED 等稳定文件错误码。
HbMiniProgramSDKError 当前运行快照缺少或未启用 filesystem 时返回
PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED；Host 未开放 file.remove operation 时返回
METHOD_FORBIDDEN，旧 Runtime 不认识该 method 时可返回 METHOD_NOT_FOUND。
该方法只删除一个文件，不接受参数，也不删除目录。可删除对象必须同时来自当前
Mini-program 的 sandbox 且为 readwrite；files.sandbox.file() 和 sandbox 目录的 list()
结果满足来源约束。若目标是目录，使用 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。
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()
读取当前文件的元数据快照。
新建的 FileStat 对象：kind 固定为 'file'，size 是 0 到
Number.MAX_SAFE_INTEGER 的整数；Host 提供时还包含相互独立、非负有限数值的
modifiedAt / createdAt。返回对象不是 FileHandle，也不会包含真实路径、内容或 Host 的额外字段。
HbMiniProgramSDKError 目标文件或任一祖先不存在时返回 FILE_NOT_FOUND /
DIRECTORY_NOT_FOUND；目标实际是目录、direct handle 类型不匹配时返回 FILE_TYPE_MISMATCH。
HbMiniProgramSDKError 外部 direct handle 已撤销、不属于当前 Runtime session 或
registry 已释放时返回 FILE_ACCESS_REVOKED；Host 拒绝读取元数据时返回 FILE_ACCESS_DENIED。
HbMiniProgramSDKError 使用普通 FileHandle 时，运行快照缺少或未启用 filesystem 时返回
PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED；Host 未开放或未协商到 file.stat 时返回
METHOD_FORBIDDEN，旧 Runtime 可返回 METHOD_NOT_FOUND。Companion attachment 是受控例外：
它使用已启用的 companion 授权读取自身元数据，不要求另行声明 filesystem。
HbMiniProgramSDKError Host 返回非对象、错误的 kind，负数/小数/unsafe size，
或负数、非有限数值的时间戳时返回 FILE_IO_FAILED；未知 Host 错误和无法识别的响应同样规范为
FILE_IO_FAILED。SDK 已销毁、Runtime 已卸载或请求超时时还可能返回 SDK_DESTROYED、
RUNTIME_UNAVAILABLE、REQUEST_TIMEOUT。
这是只读操作，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 或不晚于当前时间；用于排序和日期展示前应按业务范围
继续校验。
与 exists() 不同，stat() 不会把缺失祖先、缺失目标或 kind mismatch
归一为 false，而会以对应错误拒绝。与 readText() /
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。
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
}
}
将原始字节完整写入文件。
要写入的 Uint8Array。SDK 在调用时只复制该 view 的当前可见字节区间；不会把
byteOffset 之前或 byteLength 之后的 backing ArrayBuffer 内容一并写入。调用返回 Promise 后
再修改原数组不会改变本次写入。空数组合法，会把目标替换为零字节文件。
SDK 与 Runtime 完成输入复制且 Host 的完整写入请求成功后以 undefined resolve。移动端
会等待最后一个带 EOF 的 chunk 获得 Host 响应；该时点不返回写入字节数、文件元数据或新的
FileHandle，也不承诺操作系统已执行物理 fsync。
HbMiniProgramSDKError content 不是 Uint8Array，或其 backing buffer 是
SharedArrayBuffer 时，在发送 bridge 请求前返回 INVALID_PARAMS；当前代理不是 readwrite
时在输入复制和 Host I/O 前返回 FILE_ACCESS_DENIED。
HbMiniProgramSDKError 当前运行快照缺少或未启用 filesystem 权限时返回
PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED；Host 未开放或未协商到 file.writeBytes 时返回
METHOD_FORBIDDEN，旧 Runtime 可返回 METHOD_NOT_FOUND。
HbMiniProgramSDKError 缺失父目录时返回 DIRECTORY_NOT_FOUND，路径中的祖先或
目标类型不匹配时返回 FILE_TYPE_MISMATCH。Android / iOS 对一次完整写入设 8 MiB 上限；当前
view 的 byteLength 超过 8 * 1024 * 1024 时返回 FILE_TOO_LARGE。
HbMiniProgramSDKError 外部 direct handle 被撤销、不属于当前 Runtime session 或
registry 已释放时返回 FILE_ACCESS_REVOKED；SDK 已销毁、Runtime 已卸载、请求超时、Host 响应
异常或底层 I/O 失败时，返回 SDK_DESTROYED、RUNTIME_UNAVAILABLE、REQUEST_TIMEOUT、
FILE_IO_FAILED 或对应稳定文件错误码。
SDK 会在调用同步阶段执行第一次防御性复制，Runtime 收到 payload 后再复制一次，再把独立的
Uint8Array 交给 Host。因此本次写入只观察调用时 view 中的字节，不与调用方继续共享可变
ArrayBuffer。SharedArrayBuffer backing 会被明确拒绝，不能借此建立跨 bridge 共享内存。
这是完整文件写入，不是 append、range write 或 stream：已有内容会被本次字节序列整体替换， 写入空数组会截断为零字节。若 Host 在写入中途失败，Promise 会拒绝；公开合同不承诺失败时 回滚旧内容或提供跨进程原子替换，需要事务语义时应由业务使用临时文件和自己的提交协议。
目标文件不存在时可以隐式创建，但父目录必须已经存在，writeBytes() 不会递归创建目录。
需要创建父目录时先调用 DirectoryHandle.create()，或对文件调用
create({ recursive: true })。不必先用 exists() 检查文件；该检查也不能消除两次异步调用之间
的状态竞态，实际写入错误仍应处理。
sandbox lazy FileHandle 固定继承 readwrite。pickFiles({ mode: 'readwrite' })、
pickDirectory({ mode: 'readwrite' }) 的派生文件和 saveFile() 返回的精确外部 FileHandle 也可
写入，但 direct handle 只在当前 Runtime session 有效，且授权范围不会扩张。只读 picker 结果
和 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 上限。
readBytes() 返回完整文件的独立字节副本； writeText() 则先把字符串编码成不带 BOM 的 UTF-8，再执行相同的 完整替换语义。需要检查写入后的最终大小或时间戳时，成功后另行调用 stat()。
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()) // 完整替换为空文件。
将字符串按 UTF-8 编码后完整写入文件。
要写入的 JavaScript 字符串。必须确实是 string；SDK 不会对对象调用
String()，也不接受 Uint8Array、Blob、stream 或 encoding 选项。空字符串合法，会把目标
替换为空文件。需要精确控制原始字节时使用 writeBytes()。
Runtime 完成 UTF-8 编码且 Host 的完整写入请求成功后以 undefined resolve。移动端会
等待最后一个带 EOF 的 chunk 获得 Host 响应；该时点不返回写入字节数、文件元数据或新的
FileHandle，也不承诺操作系统已执行物理 fsync。
HbMiniProgramSDKError content 不是字符串时在 Host I/O 前以
INVALID_PARAMS 拒绝；当前代理的 mode 不是 readwrite 时在发送 bridge 请求前以
FILE_ACCESS_DENIED 拒绝。
HbMiniProgramSDKError 当前运行快照缺少或未启用 filesystem 权限时分别以
PERMISSION_NOT_IN_SNAPSHOT、PERMISSION_DENIED 拒绝；Host 未开放 file.writeText 时以
METHOD_FORBIDDEN 拒绝，旧 Runtime 也可能返回 METHOD_NOT_FOUND。
HbMiniProgramSDKError 缺失父目录时返回 DIRECTORY_NOT_FOUND，路径中的祖先
或目标类型不匹配时返回 FILE_TYPE_MISMATCH。Android / iOS 对一次完整写入的 UTF-8 编码结果
设 8 MiB 上限，超过 8 * 1024 * 1024 bytes 时返回 FILE_TOO_LARGE；该限制按字节而不是
JavaScript 字符数计算。
HbMiniProgramSDKError 外部 direct handle 被撤销、不属于当前 Runtime session
或 registry 已释放时返回 FILE_ACCESS_REVOKED；SDK 已销毁、Runtime 已卸载、请求超时、Host
响应异常或底层 I/O 失败时，分别以 SDK_DESTROYED、RUNTIME_UNAVAILABLE、
REQUEST_TIMEOUT、FILE_IO_FAILED 或对应稳定文件错误码拒绝。
Runtime 使用标准 TextEncoder 把完整字符串编码为不带 BOM 的 UTF-8，再调用 Host 的完整文件
写原语。该方法不是 append、range write 或 stream：已有文件内容会被本次编码结果整体替换，
写入 '' 会把文件截断为零字节。若 Host 在写入中途失败，Promise 会拒绝；公开合同不承诺失败
时回滚旧内容或提供跨进程原子替换，需要事务语义时应由业务使用临时文件和自己的提交协议。
目标文件本身不存在时可以隐式创建，因此通常不需要先调用
create()；但父目录必须已经存在，writeText() 不会递归创建目录。
需要创建父目录时先调用 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 结果和 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 上限。
readText() 可按严格 UTF-8 读取完整内容，但会移除前导 BOM；写入后 仍可能因为外部修改、授权撤销或 Session 结束而读取失败。需要检查最终字节数或时间戳时，在 写入成功后另行调用 stat()。
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
}
}
当前 SDK session 中的文件代理。
备注
代理是冻结的能力对象，不是原生
File或文件路径。picker /saveFile()返回的精确授权仅在当前 Runtime session 有效；sandbox 或已授权目录派生的逻辑代理不会在创建时执行 I/O。