下面从设计动机 → 浏览器限制 → 使用场景 → 在表格 AI Agent 中的真实取舍四个层次，把 LocalStorage vs IndexedDB 的选型背后逻辑彻底讲清楚。

---

一、本质差异：它们解决的是不同问题

🔹 LocalStorage

简单、同步、字符串 KV —— 为“轻量状态持久化”而生

• 同步 API（getItem / setItem）

• 阻塞主线程（但很快，因为数据小）

• 只能存 string

• 容量 ≈ 5MB / Origin

👉 本质是：“页面级记忆便签”

---

🔸 IndexedDB

异步、事务型、对象存储 —— 为“客户端数据库”而生

• 异步 + 事件 / Promise

• 支持 Blob / ArrayBuffer / Object

• 支持索引、游标、事务

• 容量受磁盘空间限制（通常 50MB～数百 MB，可请求更多）

👉 本质是：“嵌入式 NoSQL 在浏览器里”

---

二、浏览器运行时的硬约束（选型不能忽略）

约束	LocalStorage	IndexedDB
是否阻塞 UI 线程	✅ 是（同步）	❌ 否（异步）
最大容量	~5MB	取决于磁盘
结构化数据	❌	✅
批量写入	❌	✅（事务）
查询/索引	❌	✅
SSR / 框架兼容	✅ 简单	⚠️ 需封装
写入失败影响	易抛异常	可回滚

📌 关键结论​

LocalStorage 同步 API 是它的优势（初始化快），也是它的天花板（不能放大对象）。

---

三、选型判断树（工程实战版）

是否需要存储 > 几百 KB？
   ├─ 是 → IndexedDB
   └─ 否
       ├─ 是否需要索引 / 查询？
       │    ├─ 是 → IndexedDB
       │    └─ 否
       │        ├─ 页面加载必须同步读？
       │        │    ├─ 是 → LocalStorage
       │        │    └─ 否 → IndexedDB（prefer）
       └─ 纯配置 / flag / ID → LocalStorage

---

四、在 SpreadJS AI Agent 中，背后的选型逻辑

✅ 为什么 Session ID / 开关​ 用 LocalStorage？

理由链条：

1. 页面 refresh → 必须立刻知道“上一次打开的是哪个 session”

2. 数据极小（< 200B）

3. 不需要事务

4. 同步读取能让 React useEffect初始化 SpreadContext 更快

localStorage.getItem("spread:activeSessionId")

➡️ 这是 LocalStorage 的黄金场景

---

✅ 为什么 Workbook Snapshot / AI Messages​ 用 IndexedDB？

理由链条：

1. SpreadJS toJSON()通常几十 KB～几 MB

2. 需要按 sessionId + timestamp查询

3. 写入应在后台，不阻塞 Canvas

4. 未来可能保留多个历史版本

{ sessionId, workbookJson, dirtyRanges, savedAt }

➡️ 这是 IndexedDB 的黄金场景

---

❌ 反例（为什么不能反过来）

错误	后果
把 Workbook 存 LocalStorage	主线程卡死、QUOTA_EXCEEDED_ERR
把 Session ID 存 IndexedDB	需 async init → SpreadContext 启动变慢
用 LS 存 AI chat history	Token 多轮 → 爆 5MB、难查询

---

五、更深层的架构逻辑（SpreadContext 视角）

从 Harness / Memory Primitive​ 角度看：

层	存储	类比
Bootstrapping（冷启动）	LocalStorage	BIOS / ENV
Long-term Agent Memory	IndexedDB	File System / DB
Volatile Runtime State	In-Memory (Context)	RAM

✅ 好的 Agent 架构是三层协作，不会让任一层越界。

gitee.com/xiwnx23/ikybgo/blob/master/88289750.md
gitee.com/xiwnx23/jqjdjm/blob/master/27783897.md
gitee.com/xiwnx23/hiuqse/blob/master/00835703.md
gitee.com/xiwnx23/ebhzrr/blob/master/37387952.md
gitee.com/xiwnx23/meomvn/blob/master/73788182.md
gitee.com/xiwnx23/cnuyej/blob/master/15482131.md
gitee.com/xiwnx23/uucyks/blob/master/33964270.md
gitee.com/xiwnx23/vefhqs/blob/master/41418919.md
gitee.com/xiwnx23/tzebot/blob/master/11160363.md
gitee.com/xiwnx23/adjcjr/blob/master/00941908.md
gitee.com/xiwnx23/mamfed/blob/master/27188391.md
gitee.com/xiwnx23/dojiex/blob/master/51855263.md
gitee.com/xiwnx23/cfnjqj/blob/master/33365721.md
gitee.com/xiwnx23/fhxwjq/blob/master/74302135.md
gitee.com/xiwnx23/rtxzhv/blob/master/43224773.md
gitee.com/xiwnx23/qkpgpw/blob/master/41299034.md
gitee.com/xiwnx23/kqrpsu/blob/master/77315752.md
gitee.com/xiwnx23/lrzoro/blob/master/80267622.md
gitee.com/xiwnx23/xqhqpv/blob/master/23762030.md
gitee.com/xiwnx23/qagexz/blob/master/24224750.md
gitee.com/xiwnx23/jqsfph/blob/master/47012672.md
gitee.com/xiwnx23/falljn/blob/master/65233867.md
gitee.com/xiwnx23/tyfoql/blob/master/89245818.md
gitee.com/xiwnx23/rwxqyk/blob/master/82200693.md
gitee.com/xiwnx23/damrwd/blob/master/77665306.md
gitee.com/xiwnx23/sprwex/blob/master/52413177.md
gitee.com/xiwnx23/zrjtow/blob/master/39818897.md
gitee.com/xiwnx23/vvurwz/blob/master/43247866.md
gitee.com/xiwnx23/eemdjx/blob/master/22425300.md
gitee.com/xiwnx23/vyunuj/blob/master/77487272.md
gitee.com/xiwnx23/kfkxag/blob/master/40678710.md
gitee.com/xiwnx23/ptkjbw/blob/master/13180997.md
gitee.com/xiwnx23/maykwr/blob/master/00080571.md
gitee.com/xiwnx23/qvcvyt/blob/master/82976638.md
gitee.com/xiwnx23/awgjvu/blob/master/66093700.md
gitee.com/xiwnx23/bacgma/blob/master/93830735.md
gitee.com/xiwnx23/nyrqji/blob/master/59207951.md
gitee.com/xiwnx23/dobdfi/blob/master/52601533.md
gitee.com/xiwnx23/dinhpq/blob/master/51878553.md
gitee.com/xiwnx23/qxpmgl/blob/master/69515456.md
gitee.com/xiwnx23/dgjkge/blob/master/70698094.md
gitee.com/xiwnx23/ptatmn/blob/master/02050344.md
gitee.com/xiwnx23/pqpkdc/blob/master/52658771.md
gitee.com/xiwnx23/xkroji/blob/master/07156903.md
gitee.com/xiwnx23/plqeid/blob/master/82752878.md
gitee.com/xiwnx23/mubodv/blob/master/00418716.md
gitee.com/xiwnx23/ngnetk/blob/master/51415098.md
gitee.com/xiwnx23/yoozuk/blob/master/26363722.md
gitee.com/xiwnx23/bgugpu/blob/master/69389359.md
gitee.com/xiwnx23/azueqw/blob/master/51508025.md
gitee.com/xiwnx23/jevusu/blob/master/62125319.md
gitee.com/xiwnx23/bidqjr/blob/master/48212619.md
gitee.com/xiwnx23/ombkdn/blob/master/97597217.md
gitee.com/xiwnx23/afuadc/blob/master/70093100.md
gitee.com/xiwnx23/ciwmpx/blob/master/85823227.md
gitee.com/xiwnx23/xbbhqa/blob/master/77756790.md
gitee.com/xiwnx23/fysscr/blob/master/50375548.md
gitee.com/xiwnx23/xzuteb/blob/master/76359485.md
gitee.com/xiwnx23/lconps/blob/master/29977883.md
gitee.com/xiwnx23/mwcupu/blob/master/55648823.md
gitee.com/xiwnx23/jphqfn/blob/master/66968879.md
gitee.com/xiwnx23/xspyik/blob/master/70678291.md
gitee.com/xiwnx23/kiyeha/blob/master/58039786.md
gitee.com/xiwnx23/kuxaqd/blob/master/46586925.md
gitee.com/xiwnx23/ebgtfa/blob/master/52974533.md
gitee.com/xiwnx23/vtucuq/blob/master/86794703.md
gitee.com/xiwnx23/hcejsw/blob/master/14461001.md
gitee.com/xiwnx23/trbgsn/blob/master/99608379.md
gitee.com/xiwnx23/igzcjt/blob/master/41577952.md
gitee.com/xiwnx23/ovjcln/blob/master/65212781.md
gitee.com/xiwnx23/jpugfe/blob/master/49496099.md
gitee.com/xiwnx23/euusyx/blob/master/07013786.md
gitee.com/xiwnx23/xgvgeg/blob/master/15519154.md
gitee.com/xiwnx23/nfnzhm/blob/master/72646544.md
gitee.com/xiwnx23/mrrdib/blob/master/23377682.md
gitee.com/xiwnx23/vwcvwy/blob/master/99271637.md
gitee.com/xiwnx23/kwxwiu/blob/master/25155698.md
gitee.com/xiwnx23/wsybae/blob/master/84875053.md
gitee.com/xiwnx23/ufztxc/blob/master/27119079.md
gitee.com/xiwnx23/ypngjn/blob/master/01306951.md
gitee.com/xiwnx23/iifebk/blob/master/70941510.md
gitee.com/xiwnx23/bmwqyv/blob/master/18583875.md
gitee.com/xiwnx23/tspidm/blob/master/00908492.md
gitee.com/xiwnx23/nwecjl/blob/master/33299019.md
gitee.com/xiwnx23/owxagw/blob/master/59911888.md
gitee.com/xiwnx23/ebjzup/blob/master/79046323.md
gitee.com/xiwnx23/ewxsrs/blob/master/47853637.md
gitee.com/xiwnx23/xmqapd/blob/master/25604920.md
gitee.com/xiwnx23/kklhgp/blob/master/48010597.md
gitee.com/xiwnx23/nxykji/blob/master/88566531.md
gitee.com/xiwnx23/ibtjvj/blob/master/59060298.md
gitee.com/xiwnx23/jtoynt/blob/master/33367254.md
gitee.com/xiwnx23/pgavfp/blob/master/32566772.md
gitee.com/xiwnx23/etelhj/blob/master/44093085.md
gitee.com/xiwnx23/gpmety/blob/master/11764231.md
gitee.com/xiwnx23/fbiugu/blob/master/26297575.md
gitee.com/xiwnx23/qjiyik/blob/master/59042853.md
gitee.com/xiwnx23/xqyemr/blob/master/18226109.md
gitee.com/xiwnx23/ebcsps/blob/master/47534355.md
gitee.com/xiwnx23/wtspoh/blob/master/82918426.md
gitee.com/xiwnx23/hdpbde/blob/master/52532970.md
gitee.com/xiwnx23/vlpyqg/blob/master/71066014.md
gitee.com/xiwnx23/shrkpe/blob/master/47640937.md
gitee.com/xiwnx23/sxzeyj/blob/master/11890659.md
gitee.com/xiwnx23/gsgjrd/blob/master/67852192.md
gitee.com/xiwnx23/hdyaqv/blob/master/40089259.md
gitee.com/xiwnx23/iasedj/blob/master/57063798.md
gitee.com/xiwnx23/vuchjy/blob/master/25331925.md
gitee.com/xiwnx23/ithmyn/blob/master/82153408.md
gitee.com/xiwnx23/fdaqfx/blob/master/99450911.md
gitee.com/xiwnx23/iceksn/blob/master/00734831.md
gitee.com/xiwnx23/hukuou/blob/master/78538204.md
gitee.com/xiwnx23/cvvcou/blob/master/22265669.md
gitee.com/xiwnx23/tpkwci/blob/master/01423279.md
gitee.com/xiwnx23/qzjjmj/blob/master/92098288.md
gitee.com/xiwnx23/jlzsrq/blob/master/15237509.md
gitee.com/xiwnx23/kykjij/blob/master/74711539.md
gitee.com/xiwnx23/wjsedy/blob/master/27350436.md
gitee.com/xiwnx23/ltseyk/blob/master/02853184.md
gitee.com/xiwnx23/dwxfhz/blob/master/07278023.md
gitee.com/xiwnx23/sepdzv/blob/master/23367860.md
gitee.com/xiwnx23/gojrwl/blob/master/15448948.md
gitee.com/xiwnx23/auydii/blob/master/18477512.md
gitee.com/xiwnx23/guoltf/blob/master/91710880.md
gitee.com/xiwnx23/jkevag/blob/master/58418361.md
gitee.com/xiwnx23/jhrxtv/blob/master/85501979.md
gitee.com/xiwnx23/abdzdz/blob/master/55713342.md
gitee.com/xiwnx23/mejpfc/blob/master/40304974.md
gitee.com/xiwnx23/aybarq/blob/master/58715445.md
gitee.com/xiwnx23/yeerqg/blob/master/45743453.md
gitee.com/xiwnx23/bvtbhc/blob/master/67518533.md
gitee.com/xiwnx23/resfss/blob/master/70287268.md
gitee.com/xiwnx23/jcvdlf/blob/master/55233615.md
gitee.com/xiwnx23/xmufrg/blob/master/27454802.md
gitee.com/xiwnx23/qabtla/blob/master/69525231.md
gitee.com/xiwnx23/kzrrhg/blob/master/17983620.md
gitee.com/xiwnx23/mbmcdq/blob/master/06348535.md
gitee.com/xiwnx23/fcqvkc/blob/master/20856979.md
gitee.com/xiwnx23/lmihsd/blob/master/99094907.md
gitee.com/xiwnx23/oxqfxq/blob/master/38143345.md
gitee.com/xiwnx23/awkjvu/blob/master/77879094.md
gitee.com/xiwnx23/mjcoeo/blob/master/53348445.md
gitee.com/xiwnx23/feyaew/blob/master/25574399.md
gitee.com/xiwnx23/maexqz/blob/master/88072637.md
gitee.com/xiwnx23/mzumft/blob/master/36414271.md
gitee.com/xiwnx23/arvuiq/blob/master/87076716.md
gitee.com/xiwnx23/bukjms/blob/master/60900256.md
gitee.com/xiwnx23/bregpf/blob/master/48797677.md
gitee.com/xiwnx23/bkbtfu/blob/master/88598591.md
gitee.com/xiwnx23/gmnkjv/blob/master/00882050.md
gitee.com/xiwnx23/hhwckn/blob/master/31195357.md
gitee.com/xiwnx23/cipyni/blob/master/36672609.md
gitee.com/xiwnx23/vntrok/blob/master/06853504.md
gitee.com/xiwnx23/fixdow/blob/master/16658639.md
gitee.com/xiwnx23/tepoch/blob/master/81789329.md
gitee.com/xiwnx23/ivmoqz/blob/master/10042026.md
gitee.com/xiwnx23/wqjtrh/blob/master/65208880.md
gitee.com/xiwnx23/wustmg/blob/master/47078900.md
gitee.com/xiwnx23/grmkyt/blob/master/68504942.md
gitee.com/xiwnx23/ausoez/blob/master/56614304.md
gitee.com/xiwnx23/hxuzgr/blob/master/41011738.md
gitee.com/xiwnx23/mccplh/blob/master/47355618.md
gitee.com/xiwnx23/nmiudw/blob/master/22871610.md
gitee.com/xiwnx23/dbcdem/blob/master/59687465.md
gitee.com/xiwnx23/qiwmnk/blob/master/40701095.md
gitee.com/xiwnx23/ruidyj/blob/master/92648522.md
gitee.com/xiwnx23/xzkydw/blob/master/36380296.md
gitee.com/xiwnx23/nsnpfr/blob/master/60946587.md
gitee.com/xiwnx23/ftzjay/blob/master/40617360.md
gitee.com/xiwnx23/rsxxnv/blob/master/54080329.md
gitee.com/xiwnx23/psbkiz/blob/master/32263456.md
gitee.com/xiwnx23/bfhmcx/blob/master/07322372.md
gitee.com/xiwnx23/ayirii/blob/master/52482557.md
gitee.com/xiwnx23/sidchq/blob/master/61556201.md
gitee.com/xiwnx23/pjvsvl/blob/master/66742346.md
gitee.com/xiwnx23/tlyasa/blob/master/43653129.md
gitee.com/xiwnx23/sedieg/blob/master/39794304.md
gitee.com/xiwnx23/xkokjh/blob/master/88082640.md
gitee.com/xiwnx23/zndnfs/blob/master/60767341.md
gitee.com/xiwnx23/sjllkt/blob/master/57995070.md
gitee.com/xiwnx23/tpnqac/blob/master/93117048.md
gitee.com/xiwnx23/pbsfut/blob/master/30938315.md
gitee.com/xiwnx23/aiccnc/blob/master/99756031.md
gitee.com/xiwnx23/ehidwm/blob/master/44060649.md
gitee.com/xiwnx23/ffebyf/blob/master/80114360.md
gitee.com/xiwnx23/ephbbx/blob/master/40608726.md
gitee.com/xiwnx23/cinqjp/blob/master/52163839.md
gitee.com/xiwnx23/tykdjo/blob/master/63677914.md
gitee.com/xiwnx23/fychmp/blob/master/18206820.md
gitee.com/xiwnx23/hiakwi/blob/master/03057659.md
gitee.com/xiwnx23/pjfyrs/blob/master/74793381.md
gitee.com/xiwnx23/vupmpo/blob/master/96357244.md
gitee.com/xiwnx23/ncqpir/blob/master/07475900.md
gitee.com/xiwnx23/qplsnp/blob/master/38460215.md
gitee.com/xiwnx23/xeiflo/blob/master/52142139.md
gitee.com/xiwnx23/cmgvdl/blob/master/66333148.md
gitee.com/xiwnx23/byziur/blob/master/99825194.md
gitee.com/xiwnx23/icluna/blob/master/79967964.md
gitee.com/xiwnx23/pnhazw/blob/master/39661884.md
gitee.com/xiwnx23/jdebgp/blob/master/88259389.md
gitee.com/xiwnx23/pwrtvo/blob/master/48206653.md
gitee.com/xiwnx23/kyvbvu/blob/master/88386511.md
gitee.com/xiwnx23/ovpxqp/blob/master/63999080.md
gitee.com/xiwnx23/twgwej/blob/master/76201616.md
gitee.com/xiwnx23/fehdnj/blob/master/11574764.md
gitee.com/xiwnx23/kghtln/blob/master/99371385.md
gitee.com/xiwnx23/ektpbd/blob/master/18482285.md
gitee.com/xiwnx23/fgameg/blob/master/06636225.md
gitee.com/xiwnx23/ciaxch/blob/master/98641464.md
gitee.com/xiwnx23/udhtfp/blob/master/63217440.md
gitee.com/xiwnx23/sisesv/blob/master/41043157.md
gitee.com/xiwnx23/dstuab/blob/master/06693558.md
gitee.com/xiwnx23/wcdpfy/blob/master/70783781.md
gitee.com/xiwnx23/mjzpon/blob/master/60081723.md
gitee.com/xiwnx23/qsfrut/blob/master/09682086.md
gitee.com/xiwnx23/mldpeq/blob/master/64275080.md
gitee.com/xiwnx23/arwyvi/blob/master/15426764.md
gitee.com/xiwnx23/gpcvhm/blob/master/09678253.md

my.oschina.net/u/3841072/blog/19680989
my.oschina.net/u/3841072/blog/19680988
my.oschina.net/u/3841072/blog/19680985
my.oschina.net/u/3841072/blog/19680984
my.oschina.net/u/3841072/blog/19680983
my.oschina.net/u/3841072/blog/19680982
my.oschina.net/u/3841072/blog/19680981
my.oschina.net/u/3841072/blog/19680980
my.oschina.net/u/3841072/blog/19680978
my.oschina.net/u/3841072/blog/19680979
my.oschina.net/u/3841072/blog/19680974
my.oschina.net/u/3841072/blog/19680973
my.oschina.net/u/3841072/blog/19680972
my.oschina.net/u/3841072/blog/19680967
my.oschina.net/u/3841072/blog/19680966
my.oschina.net/u/3841072/blog/19680965
my.oschina.net/u/3841072/blog/19680961
my.oschina.net/u/3841072/blog/19680958
my.oschina.net/u/3841072/blog/19680957
my.oschina.net/u/3841072/blog/19680956
my.oschina.net/u/3841072/blog/19680955
my.oschina.net/u/3841072/blog/19680954
my.oschina.net/u/3841072/blog/19680953
my.oschina.net/u/3841072/blog/19680951
my.oschina.net/u/3165323/blog/19680910
my.oschina.net/u/3165323/blog/19680909
my.oschina.net/u/3165323/blog/19680907
my.oschina.net/u/3165323/blog/19680904
my.oschina.net/u/3165323/blog/19680903
my.oschina.net/u/3165323/blog/19680902
my.oschina.net/u/3165323/blog/19680901
my.oschina.net/u/3165323/blog/19680900
my.oschina.net/u/3165323/blog/19680899
my.oschina.net/u/3165323/blog/19680898
my.oschina.net/u/3165323/blog/19680896
my.oschina.net/u/3165323/blog/19680895
my.oschina.net/u/3165323/blog/19680894
my.oschina.net/u/3165323/blog/19680883
my.oschina.net/u/3165323/blog/19680882
my.oschina.net/u/3165323/blog/19680881
 

---

六、团队级决策原则（可直接写进 Wiki）

LocalStorage：配置、指针、开关、轻标识（<5KB）​

IndexedDB：业务数据、快照、日志、历史、大对象​

内存（SpreadContext）：运行时真理源

---

七、一句话总结

**LocalStorage vs IndexedDB 的选型，不是性能偏好，而是：

数据大小 × 读写时机 × 查询需求 × 页面生命周期 共同决定的架构决策。**​

在表格 AI Agent 中，二者不是二选一，而是各司其职。

如果你接下来想要：

• ✅ IndexedDB 封装为 Promise + 事务工具类

• ✅ SpreadJS Autosave 写频与存储配额平衡

• ✅ Session 清理 / 回滚 / 多版本快照策略

可以直接告诉我 👍