Storage zh

存储

Edge 用 Durable Object KV 替换了上游基于文件的存储后端。

上游参考：存储

上游提供了什么

存储子系统通过能力接缝模式持久化 session 事件日志之外的所有数据，分三层：

• Storage Hub（ctx.storage）— 协调后端和数据形式。自身不做 I/O。
• Storage Backend — 提供者实现（JSON 文件、SQLite），暴露 kv 方面供键值操作。每个后端拥有一个介质。
• Storage Domain（ctx.storageDomain）— 类型化、schema 验证的消费层，支持原子读-改-写、版本化单元和持久确认后的 domain/changed 事件。

读取从内存同步返回。写入按领域排队，先持久化、再更新内存、最后发出变更事件。

Edge 改了什么

直接复用 Hub 和 Domain

Storage（hub）和 StorageDomain 原封安装。领域声明、schema 验证、原子写入、变更事件和生命周期管理完全是上游代码。

替换件 Backend → DO KV

DurableObjectStorageBackend 使用 Durable Object 的 storage.get() / storage.put() / storage.list() 实现上游 StorageBackend 接口。所有键以 dsh-kv: 为前缀，与其他 DO 存储用途共存。

后端通过 ctx.storage.backend.register('durable-object', backend) 注册，并配合 ctx.provide('storage.backend.durable-object', true) 满足下游插件的 inject 解析。

Edge 没有改什么

• Storage Hub 和 Domain 插件
• 领域声明、schema 验证、版本化单元
• 原子写入语义和变更事件排序
• 消费者 API（storageDomain.open() / .get() / .update()）

性能特征

读路径

读取从内存中的领域状态同步返回——零 I/O。后端的 loadUnit() 在打开时通过 storage.list({ prefix }) 一次性填充内存，后续读取命中缓存 Map。

写路径

写入通过 storage.put(key, value)——单次 DO 存储操作。DO 存储保证每请求原子性。写后读一致性即时生效，因为 put resolve 后内存状态同步更新。

键空间

所有领域数据共享 dsh-kv: 前缀命名空间。当前消费者：WorkspaceRegistry（workspace 列表和排序）、SessionProjectionCache（投影快照）以及任何上游领域插件。键碰撞由键路径中的单元名防止：dsh-kv:{unit}:{table}:{key}。

DO KV 键映射

dsh-kv:{unit}:__version__              → schema 版本
dsh-kv:{unit}:__global__               → 全局领域状态
dsh-kv:{unit}:{table}:{key}            → 领域记录

存储领域外的其他 DO KV 键（凭据、设置、模型选择）使用 dsh-edge: 前缀——完整键映射见会话持久化文档。

架构总结

组件	分类	上游对应
Storage Hub	复用	—
Storage Domain	复用	—
DurableObjectStorageBackend	替换	JSON / SQLite 文件后端

关键观察：存储子系统是一个干净的能力接缝替换。Edge 换了一个后端实现，而整个 Hub + Domain 层运行的是未修改的上游代码。业务逻辑从不直接接触 DO 存储——它通过上游的领域 API。