设置与状态

先明确状态属于插件、某个视图，还是一份文档。不同所有权决定持久化和同步方式。

声明原生设置

API 3 的 contributes.settings 包含 modules、groups 和 items。模块和分组可属于插件，也可连接宿主公开的稳定设置位置；不能插入其他插件的设置。

设置项支持 boolean、string、number、select 和 model，必须提供符合类型的默认值。宿主渲染并保存，后台通过 configuration.get() 读取。

需要配置保存后立即生效时，注册 configuration.onChange 并返回应用完成的 Promise。普通 configuration:changed 事件仅观察保存事实。没有热应用处理器、处理失败或超时时，宿主可以重启插件来应用已保存配置。

私有业务数据

后台 storage.get/set 保存插件自己的 JSON 业务数据。多个视图通过自己的命令读写，后台广播变化，视图首次进入仍读取快照。

不要同时把原生设置保存一份到 storage。更改持久数据结构时递增 dataVersion 并导出 migrate(previous,from,to)，处理旧版本；失败时保留旧数据。

二进制文件放在 resources 或 documents 中。JSON 只保存名称、资源 ID 和版本等元数据，避免把大文件编码进普通状态。

实例状态

资源标签和普通挂载面板可用 state/setState 保存阅读位置、筛选条件等。导航页、装饰、插槽和替换控件不使用此持久化通道。

升级时比较 stateVersion 与 expectedStateVersion，转换后保存新状态。实例布局与业务状态分别处理；两个文件的阅读位置不应共享同一个全局字段。

条件与事件

UI 的 when 使用公开页面上下文控制呈现。需要依赖设置草稿、模型或任务状态的判断时，声明条件函数及其输入，通过 conditions.register 注册；条件不增加数据权限。

events.on 支持当前作用域的精确事件与命名空间匹配。先读取快照再订阅变化；普通事件不会重放历史，也不会等候异步监听器完成。完整事件表和类型见 API 参考。

检查恢复

验证设置即时生效、离开页面再返回、重新启用和应用重启。旧配置不符合新范围时应保留修复入口；不要因为一个字段错误清空其他设置或用户内容。