LLM 知识库，如何统一本地与云端修改
[立即体验 NoteDeep](https://www.notedeep.com/)
做 NoteDeep Desktop 时，我希望本地知识库不只是云端数据的缓存：用户可以离线编辑 Markdown，Codex、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，但保存前先转换为 Markdown；Codex 等外部工具直接修改 Markdown。两者到了同步层都表现为文件变化，并以 `source: filesystem` 写入 pending ops。
这是一个刻意的收敛：无论内容来自富文本编辑器还是外部工具，磁盘上的 Markdown 都是本地正文事实。同步引擎不需要猜测修改来自哪个 UI，也不会形成两条互相竞争的本地写入链路。
云端编辑器则直接向 ShareDB 提交 JSON0 ops。本地同步时发现云端版本领先，拉取远端 ops，更新本地 snapshot，再把 JsonML 转回 Markdown。这样三类修改最终都经过同一个 `LocalDocState` 对齐。
## 一轮同步做了什么
统一入口是 `flushLocalWorkspaceSync`。它会合并同一 workspace 的并发同步请求，避免保存、watcher 和定时任务同时跑多轮同步。
一轮同步的主链路是：
1. 用 workspace tree hash 判断页面树是否变化。
2. 用文件的 path、size、mtime 和 content hash 筛出真正变化的 Markdown。
3. 将 Markdown 转成 JsonML，与旧 snapshot 做 diff。
4. `stageSnapshot` 先把 JSON0 ops 持久化到 `pendingOps`。
5. 登录且账号匹配时，批量查询 ShareDB 当前版本。
6. 云端领先时先拉取远端 ops，并 transform 本地 pending ops。
7. 提交本地 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 开始整理你的本地知识库](https://www.notedeep.com/)
#架构设计 #离线优先 #本地优先 #协同编辑 #NoteDeep
---
原文链接：[点击查看](https://www.v2ex.com/t/1226749)
[立即体验 NoteDeep](https://www.notedeep.com/)
做 NoteDeep Desktop 时，我希望本地知识库不只是云端数据的缓存：用户可以离线编辑 Markdown，Codex、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，但保存前先转换为 Markdown；Codex 等外部工具直接修改 Markdown。两者到了同步层都表现为文件变化，并以 `source: filesystem` 写入 pending ops。
这是一个刻意的收敛：无论内容来自富文本编辑器还是外部工具，磁盘上的 Markdown 都是本地正文事实。同步引擎不需要猜测修改来自哪个 UI，也不会形成两条互相竞争的本地写入链路。
云端编辑器则直接向 ShareDB 提交 JSON0 ops。本地同步时发现云端版本领先，拉取远端 ops，更新本地 snapshot，再把 JsonML 转回 Markdown。这样三类修改最终都经过同一个 `LocalDocState` 对齐。
## 一轮同步做了什么
统一入口是 `flushLocalWorkspaceSync`。它会合并同一 workspace 的并发同步请求，避免保存、watcher 和定时任务同时跑多轮同步。
一轮同步的主链路是：
1. 用 workspace tree hash 判断页面树是否变化。
2. 用文件的 path、size、mtime 和 content hash 筛出真正变化的 Markdown。
3. 将 Markdown 转成 JsonML，与旧 snapshot 做 diff。
4. `stageSnapshot` 先把 JSON0 ops 持久化到 `pendingOps`。
5. 登录且账号匹配时，批量查询 ShareDB 当前版本。
6. 云端领先时先拉取远端 ops，并 transform 本地 pending ops。
7. 提交本地 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 开始整理你的本地知识库](https://www.notedeep.com/)
#架构设计 #离线优先 #本地优先 #协同编辑 #NoteDeep
---
原文链接：[点击查看](https://www.v2ex.com/t/1226749)
· 0 个赞