User Settings zh

用户设置

上游命名空间设置系统在 Edge 中的适配。

上游参考：用户设置

上游提供了什么

设置系统按命名空间组织配置。每个插件通过 ctx.settings.register() 注册 schemastery schema，获得 SettingsScope 句柄用于 get/watch/update/replace。值通过三层解析：schema 默认值 → 组合基础层 → 用户覆盖层。抽象的 SettingsProvider 接缝（ctx.settings）处理文档持久化；设置服务处理命名空间注册、schema 验证和变更事件。

Edge 改了什么

直接复用 设置服务

上游设置服务（ctx.settings）原封使用。命名空间注册、三层解析、get()/watch()/update()/replace() 和变更事件完全是上游代码。

替换件 设置提供者 → DO KV

DurableObjectSettingsProvider 继承上游 SettingsProvider 抽象类。将整个设置文档作为单条 DO KV 条目持久化在 dsh-edge:settings-document。实现 load()（启动时从 KV 读取）和 persist()（变更时写入 KV）。

Edge 没有改什么

• 命名空间注册和 schema 验证
• 三层解析（默认值 → 基础层 → 用户层）
• 命名空间内的序列化写入顺序
• 变更事件语义
• Settings RPC（describe/update/replace/mutate）——由 apiproxy 处理
• Secret 角色处理——secret 值从不出现在响应中

性能特征

设置读写

设置文档在 DO 初始化时加载一次并缓存在内存中。读取是 O(1) 的缓存读取。写入将完整文档序列化为单次 storage.put() 调用。由于设置变更不频繁（用户通过 UI 发起），单文档方式没有实际性能问题。

架构总结

组件	分类	Edge 代码
设置服务	复用	上游——命名空间注册、解析、事件
DurableObjectSettingsProvider	替换	约 30 行——继承 SettingsProvider，持久化到 DO KV

关键观察：设置提供者是教科书式的最小替换件——继承上游抽象类，实现两个方法（load 和 persist），其余全部委托给上游。整个设置 UI、命名空间系统和验证都是上游的。