对话上下文的本地持久化与增量同步方案-开发者社区

对话上下文的本地持久化与增量同步方案

在长会话场景下，如果每次前端建立连接都要全量拉取几百条甚至上千条历史消息，网络耗时和内存压力会迅速击穿首屏体验。尤其是移动端或弱网环境下，等待完整会话树下载并完成 Markdown 渲染，白屏时间往往超过两秒。更棘手的是，当用户在多个标签页同时与大模型互动，或者在断网重连后产生分支会话时，全量覆盖策略会导致脏写与游标错乱。我们团队在重构 AI 知识库对话中台时，彻底废弃了原先的内存全量同步，设计了一套基于 IndexedDB 与版本向量（Version Vector）的增量持久化同步方案。

存储底座：IndexedDB 的树状会话结构选型

浏览器的localStorage容量上限通常只有 5MB，且属于同步阻塞 API，频繁序列化大体积 JSON 会直接导致主线程掉帧。因此本地存储底座必须选用 IndexedDB。

在设计存储模型时，大模型对话不能简单地按线性数组存储。因为用户随时可能在某条回答后点击“重新生成”或“编辑提问”，产生分支对话（Tree-structured turns）。我们设计了两个核心 Object Store：sessions与messages。

sessions记录会话元数据与当前激活的分支叶子节点：

interface SessionRecord { id: string; title: string; activeLeafId: string; updatedAt: number; syncedCursor: number; // 客户端与服务端同步的水位游标 localVersion: number; }

messages存储单个消息节点，通过parentId和childrenIds组成多叉树：

interface MessageRecord { id: string; sessionId: string; parentId: string | null; childrenIds: string[]; role: 'user' | 'assistant' | 'system'; content: string; tokensUsage?: number; createdAt: number; serverSynced: boolean; // 是否已确认同步到远端 patchVersion: number; // 增量变动版本号 }

使用原生 IndexedDB API 较为繁琐，我们在底层封装了一层轻量级事务管理。在打开数据库时，建立以sessionId和patchVersion为复合索引的查询通道，以便快速检索未同步节点：

const DB_NAME = 'ai_chat_matrix'; const DB_VERSION = 2; export function openChatDatabase(): Promise<IDBDatabase> { return new Promise((resolve, reject) => { const request = indexedDB.open(DB_NAME, DB_VERSION); request.onupgradeneeded = (event) => { const db = (event.target as IDBOpenDBRequest).result; if (!db.objectStoreNames.contains('sessions')) { const sessionStore = db.createObjectStore('sessions', { keyPath: 'id' }); sessionStore.createIndex('updatedAt', 'updatedAt', { unique: false }); } if (!db.objectStoreNames.contains('messages')) { const msgStore = db.createObjectStore('messages', { keyPath: 'id' }); msgStore.createIndex('sessionId', 'sessionId', { unique: false }); msgStore.createIndex('session_patch', ['sessionId', 'patchVersion'], { unique: false }); } }; request.onsuccess = () => resolve(request.result); request.onerror = () => reject(request.error); }); }

增量同步协议：双向游标与变动补丁集

同步机制的核心目标有两个：第一，用户打开页面时只拉取本地未持久化的增量差集（Delta）；第二，用户离线或流式输出中断时，本地产生的新消息能在网络恢复后有序合并到服务端。

我们放弃了传统的全局时间戳对齐，因为客户端本地时钟与服务端集群时钟存在不可控的毫秒级漂移。我们采用基于递增逻辑时钟的游标对齐：

每次会话发生变更（追加消息、分支切换、内容修改），本地自增localVersion。
客户端同步请求携带syncedCursor（即上一次服务端确认的最高游标）。
服务端返回cursor > syncedCursor的变动集合，以及服务端分配的全局最新游标nextCursor。

interface SyncPullRequest { sessionId: string; lastKnownCursor: number; pendingLocalChanges: LocalPatch[]; } interface LocalPatch { type: 'upsert' | 'delete' | 'switch_branch'; messageId: string; payload?: Partial<MessageRecord>; clientTimestamp: number; } interface SyncPullResponse { serverCursor: number; serverPatches: RemotePatch[]; conflicts: ConflictResolution[]; }

在前端的同步调度器中，我们使用 Web Worker 隔离增量计算，避免反序列化大补丁包阻塞 UI 渲染：

export class ChatSyncManager { private db: IDBDatabase; private syncTimer: number | null = null; private isSyncing = false; constructor(db: IDBDatabase) { this.db = db; } public triggerSync(sessionId: string) { if (this.syncTimer) { window.clearTimeout(this.syncTimer); } // 采用防抖策略合并短时间内的流式输出落地 this.syncTimer = window.setTimeout(() => { this.executeSync(sessionId); }, 400); } private async executeSync(sessionId: string) { if (this.isSyncing) return; this.isSyncing = true; try { const session = await this.getSession(sessionId); if (!session) return; const unsyncedMessages = await this.getUnsyncedMessages(sessionId, session.syncedCursor); const patches: LocalPatch[] = unsyncedMessages.map((msg) => ({ type: 'upsert', messageId: msg.id, payload: msg, clientTimestamp: msg.createdAt, })); const res = await fetch('/api/chat/sync', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId, lastKnownCursor: session.syncedCursor, pendingLocalChanges: patches, }), }); const data: SyncPullResponse = await res.json(); await this.applyServerPatches(sessionId, data.serverPatches, data.serverCursor); } finally { this.isSyncing = false; } } private getSession(sessionId: string): Promise<SessionRecord | null> { return new Promise((resolve) => { const tx = this.db.transaction('sessions', 'readonly'); const store = tx.objectStore('sessions'); const req = store.get(sessionId); req.onsuccess = () => resolve(req.result || null); req.onerror = () => resolve(null); }); } private getUnsyncedMessages(sessionId: string, cursor: number): Promise<MessageRecord[]> { return new Promise((resolve) => { const tx = this.db.transaction('messages', 'readonly'); const store = tx.objectStore('messages'); const index = store.index('session_patch'); const range = IDBKeyRange.bound([sessionId, cursor + 1], [sessionId, Infinity]); const req = index.getAll(range); req.onsuccess = () => resolve(req.result || []); req.onerror = () => resolve([]); }); } private applyServerPatches(sessionId: string, patches: RemotePatch[], newCursor: number): Promise<void> { return new Promise((resolve, reject) => { const tx = this.db.transaction(['sessions', 'messages'], 'readwrite'); const msgStore = tx.objectStore('messages'); const sessionStore = tx.objectStore('sessions'); for (const patch of patches) { if (patch.type === 'upsert' && patch.data) { msgStore.put({ ...patch.data, serverSynced: true }); } else if (patch.type === 'delete') { msgStore.delete(patch.messageId); } } const sessionReq = sessionStore.get(sessionId); sessionReq.onsuccess = () => { const session: SessionRecord = sessionReq.result; if (session) { session.syncedCursor = newCursor; sessionStore.put(session); } }; tx.oncomplete = () => resolve(); tx.onerror = () => reject(tx.error); }); } }

脏数据与并发冲突消解策略

多端或多标签页操作同一对话时，最常见的冲突是服务端已经因另一端的指令重置了分支，而当前标签页仍在继续推送旧分支上的追问。

针对这种场景，我们制订了两条确定性合并规则：

LWW（Last-Write-Wins）与因果溯源结合：对于同一messageId的文本内容修改，以服务端最后写入时间戳为准；但如果服务端判定该节点已被祖先节点修剪（Pruned），则不会静默丢弃客户端输入，而是将客户端的新输入转换为一个独立的分支挂载点，并在客户端 IndexedDB 中重新修正其parentId。
乐观更新与状态回滚：UI 层在用户输入后立即写入本地 IndexedDB 并渲染到界面，消息标记为serverSynced: false。当网络请求返回 409 冲突或网络断开时，UI 上呈现“离线等待重试”状态指示器，而不是粗暴地清空输入框，保证了离线可用性与上下文完整性。

通过将持久化层与通信层解耦，前端不仅在首屏加载时将渲染性能拉升到了亚毫秒级（直接从本地读取活跃分支装载到 Zustand 状态树），更让长文本对话系统在不稳定的网络环境中拥有了高可靠的持久化保障。

对话上下文的本地持久化与增量同步方案