跳到主要内容

多设备同步

多设备同步属于核心插件。它协调文件系统内容、活动中的角色扮演会话、DSH 对话和外部 rclone 进程；它不会给 state 包增加存储后端。

边界​

host/sync/units.ts 定义唯一允许同步的路径：每个世界和会话各自成为一个单元，另有 prompts、presets、lorebooks、avatars 和 ui。点号开头的目录会被排除。kindOf() 是单元名称的校验边界；绝不能把未经检查的请求路径直接交给 rclone。

会话按整个文件夹传输，因为数据库、时间线、快照和媒体共同描述同一份状态。其他单元使用 rclone bisync --conflict-resolve none，两边都修改过的文件可以保留为 .conflict1 和 .conflict2。界面要求用户选择，不会猜测哪一份更新。

本机与远端状态​

<root>/.sync/state.json 保存设备 ID、上次远端修订、本机指纹、忽略的单元和未解决状态；它只留在本机。远端在 .revisions/ 下保存上传修订，在 .tombstones/ 下保存删除标记。会话上传完成前，其修订会标记为未完成，因此其他设备不会下载一半的文件夹。

SyncService 负责比较、传输、冲突处理和传播删除；UnitGate 负责进程内锁。HTTP 路由拒绝读写锁定中的单元，角色扮演回合则等待自己的会话单元解锁。替换会话前，服务会停止并卸载其智能体工作、关闭状态；文件到达后，再根据 opening.json 和 timeline.json 重建 DSH 对话。

rclone 配置密码通过 DSH 凭据存储解析，并以 RCLONE_CONFIG_PASS 环境变量传递，而不是放进命令行参数。配置文件必须是角色扮演根目录之外的绝对路径。rclone 命令失败时会向界面返回经过截短的错误，但绝不会当作成功处理。

修改与测试​

修改同步功能时，应同时保持以下部分一致：

  • shared/sync.ts 与浏览器 API、控制器；
  • host/sync/、HTTP 门控和会话生命周期钩子；
  • “存档”页面中的删除范围选择；
  • 面向用户的同步指南、配置参考和文件系统参考；
  • tests/host/sync 下的单元测试，以及路由与会话重建测试。

运行常规测试后，还应让两个独立的 DSH 主目录和角色扮演根目录连接到一个 rclone 本地远端。检查首次上传和下载、两台设备同时修改、拉取会话、仅本机删除、所有设备删除，以及传输中断后的恢复。