WorkBuddy跨机双写同步设计与Syncthing目录同步实战

2. 跨机双写同步的设计思路与方案选型

2.1 为什么“多机共号”会成为一个真需求

先说说这个需求是怎么来的。我手里有一台台式机放在办公室，一台笔记本随身带，还有一台家里的小主机跑一些定时任务。WorkBuddy 这类工具的核心价值在于它的记忆系统和工作流上下文——技能（Skill）、自定义规则、会话历史、知识库都会沉淀在本地。问题就出在“本地”这两个字上：今天在台式机上调好的一套提示词规则，明天拿到笔记本上打开，发现还是昨天的旧状态；在笔记本上跟 WorkBuddy 聊出来的新上下文，回到家打开小主机，完全没有那部分记忆。

那种割裂感非常难受。我试过几个方向：一是手动导出导入，二是用网盘同步目录，三是干脆在某一台机器上跑服务端、其他机器远程连过去。结果都各有各的坑。手动导出导入最折腾，一次两次还能忍，天天操作根本不现实；网盘同步看着简单，但 WorkBuddy 的存储结构设计得并不适合整目录丢进同步盘，经常出现索引错乱、锁冲突；远程连服务端是最“正统”的方案，但延迟明显，而且断网就没法用，完全违背了本地工具“随时打开就用”的初衷。

所以最后我才确定要走“跨机双写同步”这条路。所谓双写，指的是同一份数据有两台（或多台）机器同时承担读写的职责，然后通过底层的同步机制把各端的改动合并到一起，最终达到逻辑上的单份数据、物理上的多副本。听起来是分布式系统的经典课题，但落地到个人信息工具的层面上，其实比想象中要接地气得多。

2.2 方案选型对比：为什么最终选了底层的目录同步

这里我把比较过的几个方案整理成一张表，方便你对照自己的情况选型。

我最后采用的是“目录同步工具 + 自定义保护脚本”的混合路线。核心原因有两个。第一，WorkBuddy 的数据目录里既有文本类的规则、技能定义（这些文件小、改动频繁、适合做实时双向同步），又有索引/缓存类的文件（这类文件不适合实时同步，需要在特定时刻做快照式备份）。第二，我需要“变更”这件事在两台机器上都实时可见，而不是隔几个小时拉一次，所以必须有一个能监听文件变化的同步引擎在底层跑着。

这里有个很重要的判断标准：如果你对数据安全的容忍度比较低，或者 WorkBuddy 里存了非常重要的知识资产，建议不要省事直接上整目录同步，更不要图省事把 SQLite/LevelDB 之类的数据库文件直接丢进同步盘。数据库文件是二进制大文件，写入时是随机块写入，同步工具在某一瞬间只能看到文件的一部分内容，一旦把半个文件同步到另一台机器，另一台机器上的数据库就废了。我在这上面栽过跟头，后面专门在第 4 节讲解排查思路。

2.3 同步粒度的细化：哪些文件能实时同步，哪些不能

既然选择了目录同步，最核心的工作就变成了“给不同的文件类型划分不同的同步策略”。这一步如果能提前想清楚，后面能省掉 80% 的坑。我的划分原则很简单：按文件的写入方式来区分。

第一类是纯文本类文件，包括 WorkBuddy 的规则文件、技能定义 YAML、角色人设 Prompt、知识库里的 Markdown 文档，这类文件的特点是写入方式为整体覆盖写，不涉及随机写入，同步工具在监管中比较安全。即使两台机器同时改同一个文件，最多也就是互相覆盖成一方的内容，不会把文件弄坏。这一类我放心交给实时双向同步，并且设置冲突策略为“较新版本胜出”。

第二类是数据库与索引类文件，比如 WorkBuddy 自己的会话历史库、向量索引、缓存目录。这类文件就麻烦了。它们看似是一个文件，实际上内部是分页存储的，每次写入都是一系列随机写入，你在任意时刻去抓取文件，抓到的都只是中间态。我曾经亲眼见过一次事故：两台机器同时启动 WorkBuddy，互相把对方机器上处于“写入中”状态的缓存文件同步过来，结果双方同时崩溃，索引全部清空，等于两边丢了一大段记忆。从那以后，数据库类文件被我列入了黑名单，完全不做实时同步，只做定时快照备份。

第三类是配置文件，比如记录当前登录状态的 token 文件、存储本地局域网识别码的文件，这类文件跟具体的机器环境绑定，绝不能同步。你把 A 机器的 token 同步到 B 机器上，B 机器上的 WorkBuddy 会误以为自己是 A，可能直接踢掉 A 的会话，甚至引发鉴权异常。

如果你准备参考我的做法，建议先花点时间把 WorkBuddy 的数据目录完整浏览一遍，把所有文件按“文本/数据库/环境相关”分好类，再动同步工具。这一步比任何技巧都重要。

3. 核心细节解析与实操要点

3.1 读懂 WorkBuddy 的数据目录结构

先直接说结论：WorkBuddy 的数据目录一般在用户主目录下的隐藏文件夹里，具体路径会因为操作系统和安装方式略有差异。在 Linux 上常见的位置是~/.workbuddy/，Windows 上大概是%USERPROFILE%\.workbuddy\，macOS 同理。但不同版本有自定义缓存目录的选项，后面我会讲怎么改。

我见过很多人上来就找config.yaml或者settings.json，其实 WorkBuddy 的目录里，核心价值最高的是这几个子目录：

• rules/：存放用户自定的规则文件，通常是一堆文本文件或 Markdown，对应“给 WorkBuddy 定几条规则”这类需求。
• skills/：存放技能定义，每个技能可能是一个子目录，里面有描述文件、参数定义和触发逻辑。
• memories/或memory/：核心记忆库，存放长期记忆、用户画像、偏好等，这部分是很多人最看重的资产。
• sessions/或conversations/：会话历史，按会话 ID 组织，可能是文本文件、JSON 或数据库。
• knowledge/或kb/：本地知识库内容，一般是文档、文本块，或者是向量化的索引。
• cache/：缓存目录，这里面内容不推荐备份也不需要同步。

建议你先把自己的目录结构打出来看一遍。不同版本的 WorkBuddy 结构名称可能有出入，但大方向一致。按我前面说的三类划分，把上述目录分类标记好，同步策略就能确定下来。

3.2 双写同步的同步工具配置实战

我选择了用 Syncthing 作为底层的文件同步引擎，再结合自研的脚本做保护。为什么选 Syncthing 而不选网盘？因为它是点对点同步，不经过中转服务器，数据不出网，安全；而且它支持监听文件变化后实时推送，两端几乎无感知同步；最关键的是对文件夹的“类型”有区分，可以设置“仅发送”“仅接收”“发送和接收”三种模式，这正好对得上我前面说的三类文件分别对待的需求。

配置的核心逻辑是：把 WorkBuddy 数据目录拆成三个独立的同步文件夹。

第一个是“实时同步文件夹”，包含 rules、skills、memories 里的文本文件、knowledge 里的 Markdown 文档等纯文本内容，两台机器都设为“发送和接收”模式。这个文件夹上的同步策略是最宽松的，因为文件类型决定了它不容易损坏。

第二个是“快照备份文件夹”，包含 sessions 数据库中生成的导出快照，或者定期从 WorkBuddy 自带的导出功能生成的归档文件。这个文件夹里不直接同步原始数据库，只同步我定时生成的快照，总能保证有一份新鲜度可接受的完整备份。

第三个是“禁止同步列表”，包括 cache 目录、token 文件、socket 临时文件，直接在 Syncthing 的忽略规则里写死，任何情况下都不进同步。

具体的忽略规则我写在这份配置里，供你参考，Syncthing 用的是类 gitignore 语法。实际操作中，我把整份忽略规则放在每个同步文件夹的.stignore文件里，比如：

// 忽略缓存目录 tmp/ cache/ /**/*.tmp // 忽略环境相关的鉴权文件 **/token* **/*.credential **/auth_*.json // 忽略锁文件 **/*.lock **/LOCK* // 忽略数据库本体只留快照 **/*.db **/*.sqlite **/index*

这里有个关键心得：忽略规则要写得宽一点，宁多勿少。因为一旦漏掉某个环境绑定文件，它被错误同步到另一台机器带来的问题，比完全不同步十来个可重建的文件要严重得多。

3.3 双写同步的冲突处理：防呆设计怎么做

跨机双写，最怕的就是同一份文件在两台机器上被同时修改。文本类倒是好办，大不了最后一次保存的赢；但如果是记忆库的归档文件，冲突处理不当就会丢内容。所以需要设计一个简单的“防呆”机制。

我的做法分为三层。第一层是时间戳阈值：在同步配置里把冲突解决策略改为“较新版本胜出”，同时把同步周期设为接近实时，这样大多数情况下两台机器的修改不会真的在毫秒级撞上。第二层是保存前置快照：每次 WorkBuddy 正常退出时，由脚本自动把记忆和会话历史打一个带时间戳的压缩包扔到快照文件夹里，这个包会通过同步工具传到另一台机器；万一发生冲突导致数据异常，可以用快照做恢复点回滚。第三层是启动前检查：脚本在 WorkBuddy 启动前先检查有没有“冲突副本文件”（Syncthing 会把冲突文件命名为类似filename.sync-conflict-20240517-134512-XXXXX），如果发现，就先弹出提醒，让我决定是保留哪个版本或先恢复快照。

这个三层机制看似简单，但实际效果很好。我用这套机制连续跑了一个多月，再也没有出现过一次因为同步导致的记忆丢失。如果你不想自己写脚本，也可以让 Syncthing 默认处理冲突，但那意味着你对冲突结果完全失控，不推荐。

3.4 让同步与 WorkBuddy 的运行节奏解耦

这个知识点我觉得是最容易被忽略的，所以单独拿出来说。很多人做跨机同步，都会陷入一个思维定式：同步要实时，越快越好。但 WorkBuddy 这类工具在运行期间对数据目录是持续有读写的，如果你让同步工具在进程运行期间高频扫描目录，很容易把进程刚刚写入一半的文件拿走同步，造成对端读到半个文件。

我采用的策略是“运行期间只同步文本类，退出时统一做快照同步”。换句话说，实时同步的文件夹已经限定了只放文本类内容，数据库类内容全部交给退出钩子来处理。退出钩子是一个脚本，在 WorkBuddy 关闭后触发，它做三件事：把会话历史数据库复制一份到快照目录；调用 WorkBuddy 自带的导出命令生成归档；把归档压缩并同步。这套机制保证了数据库类内容的每次同步看起来都是一个完整的文件，而不是半个。

为了保证退出钩子真的能跑，我用的是系统级的进程监控服务，比如 systemd 用户级服务或 Windows 计划任务，监听 WorkBuddy 主进程的退出事件，而不是在 WorkBuddy 内部做集成。因为 WorkBuddy 本身并没有提供退出时执行外部命令的标准接口，外部监控是更通用的做法。

4. 实操过程与核心环节实现

4.1 跨机双写同步的最小闭环搭建步骤

走到这一步，我把整套环境的搭建过程逐条列出来。假设你已经安装好了 WorkBuddy 并确认两台机器上的数据目录结构一致。

第一步，先在一台机器上把 WorkBuddy 的配置、规则、技能整理到标准目录下，保证它是干净可复制的状态。如果你是从旧机器搬迁项目过来的，可以先参考“WorkBuddy 搬迁项目到新机器”的方法做一次完整导出，我后面会专门讲这个细节。

第二步，在两台机器上安装 Syncthing。Linux 下可以用发行版自带的包管理器装，macOS 可以直接 brew 装，Windows 下直接下载官方带 GUI 的安装包。装好后，在两台机器上分别启动 Syncthing 服务，并记录每一台的设备 ID。

第三步，在 A 机器上创建“实时同步文件夹”，指向其 WorkBuddy 的 rules/skills/memories 文本目录，共享给 B 机器的设备 ID。接着创建“快照文件夹”，指向一个专门放备份归档的目录，也共享给 B。然后在 B 机器上把这两个共享文件夹接受下来，并配置好各自的路径。

第四步，在两端都写好.stignore忽略规则。实时同步文件夹的忽略规则按第 3.2 节那份来写，快照文件夹则无所谓因为里面已经只有归档文件了。

第五步，编写退出钩子脚本。Linux 下的脚本可以做得很简洁，核心逻辑如下示例，Windows 下用 PowerShell 思路一致，这里以 bash 版本为例，供参考。

#!/usr/bin/env bash # 在 WorkBuddy 退出后，导出当前配置与记忆到快照目录 SNAPSHOT_DIR="$HOME/workbuddy-snapshots" TIMESTAMP=$(date +%Y%m%d-%H%M%S) mkdir -p "$SNAPSHOT_DIR" # 停止向实时目录写入，导出内存中的记忆 workbuddy export --format archive --output "$SNAPSHOT_DIR/wb-memory-$TIMESTAMP.tar.gz" # 备份会话历史数据库为快照 cp "$HOME/.workbuddy/sessions/sessions.db" "$SNAPSHOT_DIR/sessions-$TIMESTAMP.db"

第六步，配置 systemd 用户服务或计划任务监听 WorkBuddy 主进程退出事件。systemd 用户服务配置的要点是ExecStopPost字段会在服务停止后执行你指定的脚本：

[Unit] Description=WorkBuddy Sync Hook [Service] Type=oneshot RemainAfterExit=yes ExecStart=/bin/true ExecStopPost=/home/you/bin/workbuddy-sync-hook.sh

Windows 下也可以用“任务计划程序”绑到 WorkBuddy 的进程退出事件上，效果一样。

到这里，最小闭环就算搭好了。剩下的就是观察和调优。

4.2 更换 WorkBuddy 缓存目录的必要性

我在实操里发现，WorkBuddy 默认的缓存目录经常跟数据目录放在一起，结果缓存文件也被同步工具纳入监视范围，白增加大量 I/O，还容易触发同步风暴。手动更改缓存目录是值得做的。WorkBuddy 支持通过配置文件或命令行参数调整缓存目录，具体写法我用的是环境变量加启动参数双保险，建议按你所用版本手册调整。

更换缓存目录后，把缓存指向系统临时目录或一个独立的本地磁盘分区，这样缓存数据彻底脱离同步范围，从源头上阻断了缓存文件被错误同步的可能。改完之后，前面第 2.3 节里说的“第二类数据库与索引文件”的范围又会缩小一块，同步维护成本进一步降低。

4.3 多机共用一个账号时身份与令牌的处理

这是最容易让人想当然的地方。很多人以为多机共用账号就是简单地在一台机器上登录，然后把登录状态文件复制到另一台机器即可。实际上一旦同步工具把 auth/token 文件从 A 推到 B，B 上会因为令牌的机器指纹或会话上下文不一致而无法正常鉴权，轻则要求重新登录，重则导致账号被判定为异常登录。WorkBuddy 的账号体系在本地写入的令牌通常会绑定设备信息，直接跨机复制是行不通的。

我的做法是：token 文件进忽略名单，多机共号时直接在每台机器上分别登录账号。登录后的线上数据通过 WorkBuddy 官方账号体系自动拉取到本地，本地新增的规则、技能文本再通过我前面搭好的中间栏同步。这样“账号层”走官方通道，“文件层”走自建同步，两边各司其职，是最贴近 WorkBuddy 设计意图的做法。

顺带说一句，很多人搜“WorkBuddy 换账号如何获得原来账号的记忆”，其实答案就在这个语境里：如果你在本地的记忆库文件还保留着，换账号后且落盘规则不变，那么新账号离线时也能读到旧账号期间同步下来的记忆文件；但这只是文件层的数据残留，不代表官方账号体系认可这种跨账号操作。因此建议换号前先把记忆目录整体备份，不要赌任何“账号切换自动继承记忆”的功能存在。

4.4 从旧机器搬迁 WorkBuddy 项目到新机器

如果你不是从零开始搭建，而是有一台旧机器上已经积累了大量 WorkBuddy 项目数据，想搬迁到新机器上，那需要单独处理。搬迁和实时同步是两码事：搬迁是一次性的动作，不需要实时；但搬迁做不好，后续同步也会跟着出问题。

我推荐的搬迁顺序是：先在旧机器上用 WorkBuddy 自带的导出命令生成一个全量归档，包含规则、技能、记忆、会话历史。然后把归档文件拷贝到新机器，在新机器上导入。导入完成后再把新机器加入之前搭好的 Syncthing 对等网络，这样新机器启动后的初始状态和旧机器完全一致，后续增量同步的基准点也对得上。

如果你有一堆旧项目目录散落在各个地方，记得先把它们统一归拢成 WorkBuddy 数据目录下的规范结构，再走导出导入流程。直接把散落目录拷进数据目录会导致索引识别不到，导入时经常提示“缺少技能上下文”之类的错误，原因就是项目文件不在数据目录的规范位置上。

5. 常见问题与排查技巧实录

5.1 同步后 WorkBuddy 无法启动或直接崩溃

这类问题九成出在数据库类文件被错误同步。表现是启动时或初始化期间直接就闪退。排查思路很简单：先停掉同步工具，把 WorkBuddy 的数据目录重置为最近一次稳定的快照，看能不能正常启动。如果能，基本可以确认是同步把损坏的中间态文件写进来了。

此时去.stignore里把数据库扩展名全部加进黑名单，同时对已被同步损坏的文件做一次全量扫描清理。这里有一个细节：清理之后，最好在对端也做一次“完全重扫”并删除多余的“冲突副本”，不然过一会儿同步工具又会把淘汰的旧文件推回来。

按我的经验，宁可牺牲一点实时性，也绝不把数据库类文件放进实时同步的文件夹。你要实时性，就请用快照 + 定时同步来代替。

5.2 同步源不断报错“文件被占用”或“权限不足”

Windows 上最容易踩这个坑。WorkBuddy 进程还在运行时，数据目录里的某些文件会被独占，Syncthing 尝试读取时就会报权限不足或占用。如果只是偶尔报，倒也不用太慌。但如果报错越来越频繁，优先检查是不是你的同步周期太短导致进程还没释放文件就被扫描了。

我的解决办法是把同步周期调慢一点，同时设置 Syncthing 的“扫描间隔”为一个带随机抖动的值，比如 60 秒到 120 秒之间随机，而不是固定 30 秒。这样能显著减少抓取到进程正在写入的中间态的概率。Linux 下权限问题多半出在数据目录属主不一致，用chown把目录归一到当前用户即可。

5.3 多机同时在线时出现“会话错乱”或“记忆互相覆盖”

双写同步做到实时之后，会遇到一个分布式系统固有的问题：并发冲突。想象一下，你在台式机上让 WorkBuddy 记住一个设定，同时笔记本上的 WorkBuddy 正在把另一个修改写入记忆库，两边文件级别的时间戳几乎相同，最后同步合并时，总有一方的写入被覆盖掉。

这一类问题的根源是文件级同步不提供事务隔离，所以要从 WorkBuddy 的机制上绕开。我实际验证有效的做法是：尽量避免两台机器同时打开 WorkBuddy 并编辑同一个记忆条目。可以通过规则把不同机器的职责分开，台式机负责知识库整理，笔记本负责对话交互，人为降低冲突概率。冲突机制作为兜底存在，而不要把兜底当作常态。

如果确实需要同时编辑，那就靠前面第 3.3 节里的快照机制做保险。每次启动前看到冲突提醒时，不要慌着点掉，先看一眼冲突文件的时间戳，结合两台机器上的工作进度判断保留哪一份。

5.4 修改 WorkBuddy 缓存目录后同步失效

这类问题是我自己的亲身经历。改完缓存目录后，WorkBuddy 正常读写新路径，但旧路径下的缓存残留文件还在被同步工具监听，导致同步状态一直显示“有更新”，实际却什么都没有拿到。看起来是同步失效，其实是你的同步源和实际数据源不一致。

排查思路是查看 Syncthing 监视的路径是否指向了旧目录，如果是，就把旧的同步文件夹从 Syncthing 中移除，再新建指向新目录的同步任务。做这类调整之前，记得先把两端的 WorkBuddy 完全退出，避免在搬迁路径的过程中写入新数据造成路径记录混乱。

5.5 常见问题速查表

5.6 几个常规文档里不会写的经验心得

最后分享几个我实践中觉得很值钱的体会。

第一，给 WorkBuddy 定规则这件事，天然适合跨机同步。你把规则文件放在 rules 目录里，用文本格式组织，同步工具帮你带到每台机器。但是要注意，规则文件设计时要尽量做成分离的、自描述的，不要在一个文件里堆几千行，不然两边稍微改一点点就冲突。尽量把每条规则拆成独立的文件或按主题分模块，文本同步的冲突率会大幅度下降。

第二，如果你觉得 WorkBuddy 生成的内容“AI 味太重”，我在实践中发现通过同步一致的人设与行为规范文件，能明显改善这个问题的体验一致性。规则文件同步到位后，无论你在哪台机器调用 WorkBuddy，它输出的语气、节奏、用词偏好都会保持一致，因为底层读取的是同一份规则定义。这算是多机同步带来的额外收益。

第三，不要低估导出归档文件的体积。WorkBuddy 用久了以后，会话历史、知识库、向量索引可能膨胀得很快。我建议快照目录里做一个保留策略，只保留最近 7 天的归档，更早的转移到冷备盘。否则快照文件夹越滚越大，Syncthing 的扫描和同步性能都会受影响，而这种性能退化往往是自己悄悄发生的，等发现时已经拖慢整体速度。

按照这套思路搭建完成后，我自己最直观的感受是：不管手边是哪台机器，打开 WorkBuddy 就像回到同一个状态，规则还是那些规则，记忆还是那些记忆，不需要每次切换机器都重新熟悉一遍。如果你也在多设备环境里被这个问题困扰，可以先从最小闭环搭起，把文本类文件先同步起来，再逐步加入快照机制，最后根据使用节奏调整同步策略。这个过程不需要一次做到完美，边用边调，慢慢就会找到一个适合你的平衡点。