网页储存接口规范 0.1.0
本包让浏览器里的豫言应用读写当前网页来源（协议、主机、端口）下的键值文字，用于未发送的草稿、界面偏好、展开状态之类只需在本机保存的小数据。它是浏览器 sessionStorage 与 localStorage 的最小公共子集：只有读、写、删三个函数；写入失败是可恢复情形，以返回值表示，不抛事故。应用依赖本包后，全部函数都必须实现。
区域
区域 参数只接受两个固定值：
| 区域 | 对应 | 生命周期 |
| --- | --- | --- |
| 会话 | sessionStorage | 当前标签页（含刷新）；标签页关闭即清除 |
| 本地 | localStorage | 持久，同来源的所有标签页共享 |
区域名不是这两个值之一时抛事故。
函数
读取网页储存 : 字符串(区域) → 字符串(键) → （爻 合 字符串）
键存在时返回（阳，值）；键不存在，或浏览器禁用了储存（隐私模式、被用户或策略封锁）时返回（阴，空字符串）。要区分“键不存在”与“值是空字符串”，看元组的第一项：值是空字符串时返回（阳，空字符串）。
写入网页储存 : 字符串(区域) → 字符串(键) → 字符串(值) → 爻
成功返回阳。配额已满、储存被禁用、隐私模式的零配额等运行时失败返回阴，且不改变原有内容；应用应提示用户（例如“草稿未能保留”）。区域无效、键为空或超长、值超过限额属于违规调用，抛事故。
删除网页储存 : 字符串(区域) → 字符串(键) → 有
删除键；键不存在或储存不可用时什么也不做。
键与值
- 键原样使用，宿主不加前缀。同来源的不同应用共用同一个键空间，应用自己用带项目名的键（例如
yy-cloud-draft:账户:项目:ai）避免冲突；这也使从旧 JS 前端迁来的既有键值继续有效。 - 键至多 512 个 UTF-16 码元，不得为空；值至多 1048576 个 UTF-16 码元（1 Mi 码元），可以为空字符串。
- 值是任意豫言字符串（含 JSON 文字）。含孤立代理项（不能编码为合法 UTF-8 的字符串）不会出现，因为豫言字符串本身是合法 Unicode。
与网页事件的关系
本包不产生事件。其他标签页对同一 localStorage 的修改（storage 事件）本版不提供，应用需要跨标签页同步时应自己轮询或使用后续的广播包。
失败分类
| 情形 | 表现 | | --- | --- | | 区域名无效；键为空或超过 512 码元；值超过限额 | 抛豫言事故（违规调用，中文消息） | | 配额已满、储存被禁用或抛出安全错误 | 写入返回阴；读取返回（阴，空字符串）；删除无事 | | 宿主已关闭 | 抛事故 |
一致性样例
写入网页储存("本地", "偏好", "云端")返回阳；读取网页储存("本地", "偏好")返回（阳，“云端”）；删除网页储存后再读返回（阴，“”）。- 会话与本地互不相通：会话里写入的键在本地里读不到。
读取网页储存("临时", "键")：抛事故（区域无效）。- 值恰为 1048576 个码元时写入成功（或因配额返回阴）；多一个码元抛事故。
- 浏览器储存写入抛出 QuotaExceededError 时，
写入网页储存返回阴，原有键值不变。
边界
本包不规定：键的枚举与清空、storage 跨标签页事件、IndexedDB、Cache API、二进制值、加密储存、同步之外的持久化保证。敏感数据（口令、令牌）不应放入这两种储存。