两种存储
ctx.storage（权限 storage） |
ctx.deviceStorage（权限 storage.device） |
|
|---|---|---|
| 在哪 | 云端，跟账号走，所有设备同步 | 这台电脑，按账号隔离，不上传 |
| 放什么 | 用户的学习数据（卡组、计划、记录） | 凭据性质的东西（订阅地址、API 令牌）、只在本机有意义的缓存 |
| 配额 | 每插件每用户 ≤ 5000 条；每用户所有插件合计 ≤ 10000 条、≤ 20 MB | 每插件 ≤ 512 KB |
规则
- 集合名：
^[a-z][a-z0-9_-]{0,47}$；文档 id：^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$；单个文档 JSON ≤ 64 KB。 - 超出配额抛
Plugin storage is full for this plugin：在describe里就按剩余空间拦截（官方闪卡插件的cardRoom）， 别让用户确认之后才失败。 - 每个插件的存储彼此隔离；插件被移除时数据保留（用户再添加回来接着用）。
- 所有写入都会让面板收到一次
data事件。
数据设计建议
- 一个实体一个文档，别把一千张卡塞进一个文档（64 KB 上限、每次整份重写、并发时互相覆盖）。
- 列表的「数量」等派生值当缓存看（官方闪卡的
cardCount），以真实数据为准。 - 软删除：删除只记
deletedAt，保留 7 天可恢复，之后再真清 —— 撤销不依赖内存快照、断网也不丢数据。 - 按对象串行读改写（见命令 · 并发）；跨设备仍是后写的赢，关键字段要能合并。
数据迁移（插件升级）
插件包不能带数据库迁移，数据格式由你自己演进：
- 新字段一律可选，读旧数据时给默认值；
- 需要改结构时在文档里写版本号
v，读取时按版本升级、写回新版本； - 绝不改集合名、文档 id 规则与插件 id：用户的数据按它们存着。