LLM 知识库如何统一本地与云端修改立即体验 NoteDeep做 NoteDeep Desktop 时我希望本地知识库不只是云端数据的缓存用户可以离线编辑 MarkdownCodex、Claude Code 或 Cursor 可以直接改文件云端仍然保留富文本编辑、历史版本与协作能力。真正困难的不是上传文件而是三类修改可能同时发生它们从哪里进入、以谁为准、断网后如何恢复、云端领先时又如何合并最后我把它们收敛到同一套本地状态和 JSON0 同步链路中。背景与目标这个方案先确定了两个产品边界本地目录必须在没有网络、甚至没有登录时正常工作Markdown 必须是人和 AI 工具都能直接读写的开放文件而不是某种只能由 NoteDeep 解析的缓存格式。因此本地与云端分别拥有自己的事实源页面正文的本地事实源是 Markdown 文件。页面树的本地事实源是.notedeep/manifest.json中的manifest.pages。云端事实源是 ShareDB 的workspaces/{workspaceUuid}与pages/{pageUuid}。.notedeep/state/保存同步基线和待提交 ops不冒充业务事实源。sync-index.json只用于跳过未变化文件丢失后可以重建。这层区分很重要。如果把 snapshot、文件索引和业务数据混在一起同步异常后很难判断应该相信谁。三类修改如何汇流产品视角下有三类输入但当前实现没有为它们各写一套同步器。本地编辑器产生的是 JsonML但保存前先转换为 MarkdownCodex 等外部工具直接修改 Markdown。两者到了同步层都表现为文件变化并以source: filesystem写入 pending ops。这是一个刻意的收敛无论内容来自富文本编辑器还是外部工具磁盘上的 Markdown 都是本地正文事实。同步引擎不需要猜测修改来自哪个 UI也不会形成两条互相竞争的本地写入链路。云端编辑器则直接向 ShareDB 提交 JSON0 ops。本地同步时发现云端版本领先拉取远端 ops更新本地 snapshot再把 JsonML 转回 Markdown。这样三类修改最终都经过同一个LocalDocState对齐。一轮同步做了什么统一入口是flushLocalWorkspaceSync。它会合并同一 workspace 的并发同步请求避免保存、watcher 和定时任务同时跑多轮同步。一轮同步的主链路是用 workspace tree hash 判断页面树是否变化。用文件的 path、size、mtime 和 content hash 筛出真正变化的 Markdown。将 Markdown 转成 JsonML与旧 snapshot 做 diff。stageSnapshot先把 JSON0 ops 持久化到pendingOps。登录且账号匹配时批量查询 ShareDB 当前版本。云端领先时先拉取远端 ops并 transform 本地 pending ops。提交本地 ops远端页面变化再写回 Markdown。这里最重要的顺序是“先 stage再联网”。未登录、离线或请求失败只会让同步暂停不会阻塞 Markdown 保存。下次打开、保存、文件变化、手动同步或 60 秒定时任务触发时继续消费本地 pending ops。页面树为什么单独同步正文变化和页面树变化不是一回事。正文进入pages/{pageUuid}页面路径、标题、父子关系、排序和删除状态进入workspaces/{workspaceUuid}。本地页面树由manifest.pages构造为 WorkspaceDoc再通过字段级 JSON0 ops 上行。远端新增页面下行时先把 WorkspaceDoc 投影回 manifest为新pageUuid生成本地路径再拉取对应 page doc 并写成 Markdown。这让“云端新建一页”不只是多出一份远端正文而是能够完整落到本地目录结构中。这套方案的取舍当前正文 diff 是 block 粒度的 JsonML 替换不做字符级 Markdown diff。好处是复用编辑器现有的 JsonML 与 JSON0 协议也能统一处理自定义 block代价是同一 block 内的并发修改不够细。目前并发冲突依赖 JSON0 transform没有人工冲突选择界面。Markdown 与 JsonML 的往返也会执行格式规范化因此它不是保留每个空格和排版细节的文本同步工具。此外appliedOps目前会持续增长压缩策略仍待确定。这些都是当前实现边界而不是已经解决的问题。结果与后续这套设计最终把三类修改收敛成了一个简单原则本地先可靠地写 Markdown再由持久化状态把结构化变化同步到 ShareDB云端变化沿相反方向写回本地。它没有消灭同步系统的复杂度但把复杂度集中在LocalDocState和flushDocState没有扩散到编辑器、文件 watcher 和每一种外部工具中。对一个需要同时服务人、AI coding tools 和云端协作的知识库来说这个边界比“实时上传文件”更重要。如果你也在设计离线优先或本地优先应用希望这套取舍能提供一些参考。使用 NoteDeep 开始整理你的本地知识库#架构设计 #离线优先 #本地优先 #协同编辑 #NoteDeep