Obsidian 微云同步

这是一个 Obsidian 插件，用微云 MCP API 将 Obsidian 仓库同步到微云目录中。它面向个人多端使用，重点是冲突保护、低调用次数、本地增量缓存和较好的大文件表现。

功能

• 支持命令面板、左侧图标和状态栏手动同步。
• 支持启动同步、文件变更后同步和按固定间隔自动同步。
• 自动同步会等待完整安静窗口，持续编辑时不会中途同步。
• 多端同步使用不可变提交和每设备 head，避免争抢单一 latest 指针。
• 普通文件会进入压缩 pack，大文件、视频、压缩包、数据库等可直接作为微云对象上传。
• Markdown、Canvas、Bases 等内容按字节同步，不会被重新序列化。
• 写入本地文件前会再次检查本地是否被修改，避免自动同步覆盖正在编辑的内容。
• 冲突中心常驻在右侧面板，可选择保留本地、保留远端、保留两份、稍后处理或删除。
• 本地缓存记录文件指纹、脏路径、远端目录快照、已知 head 和 GC 计划。
• 内置微云接口限流、重试和两阶段 GC，尽量减少 list/download/upload/delete 调用。

安装

构建产物位于 dist/。自己使用时，将 dist/ 目录中的文件复制到目标 Obsidian 仓库：

<你的仓库>/.obsidian/plugins/obsidian-weiyun-sync/

需要包含：

main.js
manifest.json
styles.css
versions.json

然后在 Obsidian 设置中启用第三方插件和本插件。

配置

在插件设置页填写原始微云 MCP Token。Token 会保存在 Obsidian 插件数据中，只用于调用配置的 MCP 服务；插件不会把 Token 写入通知、状态栏、日志或模拟输出。

默认 MCP 服务地址：

https://www.weiyun.com/api/v3/mcpserver

默认远端文件夹名为 ObsidianVault。如果设置为空，插件会直接使用 Token 绑定的微云目录。少数 Token 需要显式根目录时，可以在高级设置里填写 dir_key 和 pdir_key。

同步策略

每个设备只更新自己的 head 文件。同步时插件会读取各设备 head，基于本地基线做三方合并：

• 只有本地变更：上传本地版本。
• 只有远端变更：下载远端版本。
• 本地和远端都变更且内容不同：记录冲突，交给冲突中心处理。
• 本地文件在同步准备期间又被修改：停止覆盖并记录冲突。

大多数文件会按分块进入 pack；达到直传阈值的大文件会作为 direct object 上传。.canvas 和 .base 文件会按普通文件处理。数据库类文件如果多端同时修改，插件不会做数据库语义合并，而是进入冲突中心保留两边版本。

构建与检查

npm install
npm run typecheck
npm run simulate:local
npm run build

说明：

• simulate:local 使用 fake 微云服务做本地安全和性能模拟，不访问真实微云。
• build 会输出可安装产物到 dist/。

GitHub Actions

仓库包含 CI 工作流，会在推送和 Pull Request 时运行：

• npm ci
• npm run typecheck
• npm run simulate:local
• npm run build
• 检查 dist/ 是否和源码构建结果一致

注意事项

• 首次使用前建议先备份 Obsidian 仓库。
• 请不要把真实 Token、Obsidian 插件数据、.obsidian 目录或本地缓存提交到仓库。
• 不建议手动修改微云目录中的同步元数据文件。