LLM 知识库，如何统一本地与云端修改

📌 一句话摘要

文章介绍了 NoteDeep Desktop 如何通过本地 Markdown 与云端 ShareDB 统一三类修改的同步方案，实现离线优先与协同编辑。

📝 详细摘要

文章详细阐述了 NoteDeep Desktop 在构建本地优先知识库时的同步架构。它先划分了本地事实源（Markdown 文件和 .notedeep/manifest.json）与云端事实源（ShareDB 的工作区和页面文档），并说明了 .notedeep/state/ 仅用于保存同步基线和待提交操作。接着描述了三类修改来源——本地富文本编辑器、外部 AI 工具直接编辑 Markdown、以及云端编辑器——如何通过文件系统变化和 JSON0 操作汇入统一的 LocalDocState。同步流程包括使用 workspace tree hash 判断页面树变化、通过文件属性筛选真正变化的 Markdown、将 Markdown 转为 JsonML 做 diff、持久化 pending ops、联网拉取云端 ops 并进行 transform 后提交。文章还讨论了页面树单独同步的原因、当前方案的取舍（如 block 级 JsonML diff、依赖 JSON0 transform 处理冲突、缺少人工冲突界面和操作历史压缩策略），并指出了后续改进空间。整体为离线优先、协同编辑场景提供了可参考的架构思路。

💡 主要观点

- 本地事实源与云端事实源的清晰分离。 本地以 Markdown 文件和 .notedeep/manifest.json 中的 manifest.pages 为事实源；云端以 ShareDB 的 workspaces/{workspaceUuid} 和 pages/{pageUuid} 为事实源，state 目录仅保存同步基线和待提交 ops，避免混淆导致同步异常难以裁决。

三类修改的统一汇流机制。 无论是本地富文本编辑器还是外部 AI 工具（Codex、Claude Code、Cursor）对 Markdown 的修改，都表现为文件系统变化，写入 pending ops 中的 source: filesystem；云端编辑器则直接向 ShareDB 提交 JSON0 ops。所有修改最终进入同一个 LocalDocState 进行对齐。

同步流程的关键步骤与顺序。 flushLocalWorkspaceSync 首先用 workspace tree hash 判断页面树是否变化，再通过文件的 path、size、mtime 和 content hash 筛选真正变化的 Markdown；将 Markdown 转为 JsonML 与旧 snapshot 做 diff，持久化产生的 JSON0 ops 到 pendingOps；登录且账号匹配时批量查询 ShareDB 当前版本，云端领先时先拉取远端 ops 并 transform 本地 pending ops，最后提交本地 ops 并将远端页面变化写回 Markdown。

设计取舍及当前局限。 正文 diff 采用 block 级 JsonML 替换而非字符级 Markdown diff，以复用编辑器现有协议并统一处理自定义 block，但导致同一 block 内的并发修改细粒度不足；冲突处理仅依赖 JSON0 transform，缺少人工冲突选择界面；此外，appliedOps 持续增长，压缩策略尚未确定。

💬 文章金句

- 真正困难的不是上传文件，而是三类修改可能同时发生：它们从哪里进入、以谁为准、断网后如何恢复、云端领先时又如何合并？

• 这套设计最终把三类修改收敛成了一个简单原则：本地先可靠地写 Markdown ，再由持久化状态把结构化变化同步到 ShareDB ；云端变化沿相反方向写回本地。

📊 文章信息

AI 初评：82

来源：V2EX

作者：lerongwan1

分类：软件编程

语言：中文

阅读时间：7 分钟

字数：1505

标签： 开发者工具, 系统设计, 云原生 / DevOps, 离线优先, 本地优先

阅读完整文章