知识库同步引擎

Obsidian 多端同步引擎，解决 iCloud/Dropbox 同步冲突、插件配置漂移、.obsidian/ 目录混乱、 移动端笔记丢失四大痛点。支持 Git 同步、选择性同步、冲突自愈与配置版本化。 核心能力: - 同步方案选型：Git（推荐）/ iCloud / Dropbox / Syncthing / Obsidian Sync - 选择性同步：笔记同步、.obsidian/ 不同步或分设备同步 - 冲突检测与自愈：自动识别冲突文件、三路合并、保留冲突副本 - 插件配置治理：按设备类型分配置、敏感配置排除同步 - 同步健康看板：上次同步时间、冲突数、未推送提交数 适用场景: - 桌面+手机+平板多端使用 Obsidian - 团队/家庭共享部分笔记但保留各自配置 - 把 Obsidian 当 Git 仓库做版本化知识管理 - iCloud/Dropbox 同步频繁出问题的用户 差异化: - 同步方案决策表（含免费/付费/自建），原版未提同步 - 选择性同步规则（.obsidian/ 分设备），原版无此概念 - 冲突自愈流程（三路合并 + 副本保留），原版无冲突处理 - 同步健康看板，原版无监控 触发关键词: obsidian, sync, 同步, 多端, icloud, dropbox, git, 冲突, conflict, 移动端

让 Obsidian vault 在多设备间稳定同步。聚焦"不丢笔记、不乱配置、冲突可解"，把同步从黑盒变成可监控的引擎。

同步方案选型

方案	免费	冲突处理	选择性同步	移动端友好	推荐场景
Git	是	强（三路合并）	强（.gitignore）	需配合（Working Copy）	技术用户首选
iCloud	是	弱（生成副本文件）	无	强（iOS）	Apple 全家桶
Dropbox	限免费额度	中（生成副本）	无	中	跨平台普通用户
Syncthing	是	中	弱	中（需后台）	自建同步、隐私敏感
Obsidian Sync	付费	强	强	强	不想折腾、付费用户

选型规则：

• 技术用户 + 想要版本历史 → Git
• Apple 全家桶 + 不想配 Git → iCloud（接受偶发冲突）
• 跨平台 + 不想付费 → Syncthing
• 不想折腾 + 接受付费 → Obsidian Sync

Vault 模型与同步边界

路径	内容	是否同步	说明
*.md	笔记	是	核心内容
<attachments>/	附件	是	笔记引用的资源
.obsidian/app.json	全局设置	按设备	字体/主题等可分设备
.obsidian/workspace.json	工作区状态	否	每设备独立
.obsidian/plugins/	插件配置	选择性	部分插件配置可共享
.obsidian/community-plugins.json	插件清单	是	保持插件一致
.trash/	回收站	否	每设备独立

Git 同步方案（推荐）

初始化

bash

cd <vault-path>
git init
cat > .gitignore <<'EOF'
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/cache
.trash/
*.tmp
.DS_Store
EOF
git add .
git commit -m "chore: init vault"
git remote add origin <repo-url>
git push -u origin main

多设备克隆

bash

# 新设备
git clone <repo-url> <vault-path>
# 用 Obsidian 打开该文件夹

日常同步工作流

bash

# 拉取（开始编辑前）
git pull --rebase

# 编辑笔记...

# 推送（结束编辑后）
git add .
git commit -m "docs: update <note>"
git push

自动同步脚本

bash

# scripts/vault-sync.sh
#!/usr/bin/env bash
set -e
cd "$(obsidian-cli print-default --path-only)"
git pull --rebase --autostash || {
  echo "冲突需手动解决"
  exit 1
}
git add .
git commit -m "auto: sync $(date +%FT%T)" || echo "无变更"
git push

加入 cron/Task Scheduler：

• macOS/Linux：每 30 分钟跑一次
• 编辑前手动 git pull --rebase

选择性同步规则

.obsidian/ 分设备策略

bash

# .gitignore 排除设备相关配置
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/graph.json
.obsidian/cache

# 保留共享配置
# .obsidian/app.json（主题/字体可共享或分设备）
# .obsidian/community-plugins.json（插件清单共享）
# .obsidian/plugins/*/data.json（按需）

插件配置治理

bash

# 某些插件配置含设备特定路径，需排除
.obsidian/plugins/obsidian-git/data.json
.obsidian/plugins/local-rest-api/data.json

# 共享插件配置（如 Dataview 查询）
# .obsidian/plugins/dataview/data.json → 保留同步

冲突检测与自愈

冲突识别

bash

# Git 同步时检测冲突
scripts/vault-sync.sh --check-conflicts
# 输出冲突文件列表

iCloud/Dropbox 同步会生成"冲突副本"文件（如 note (1).md、note (conflicted copy).md）：

bash

# 扫描冲突副本
scripts/conflict-scan --vault "<vault-path>"
# 识别模式：* (1).md、* (conflicted copy).md、*. conflicted

三路合并自愈

bash

# Git 冲突 → 用 merge tool 解决
scripts/conflict-resolve --strategy merge --vault "<vault-path>"

# iCloud/Dropbox 冲突副本 → 三路合并
scripts/conflict-resolve --strategy three-way \
  --base "<vault-path>/note.md" \
  --mine "<vault-path>/note (1).md" \
  --strategy keep-both-on-fail

保留策略：

• 合并成功：删除冲突副本，保留合并结果
• 合并失败：保留双方，生成 note (merged-failed).md，等用户手动处理
• 永不静默丢弃任何一方

同步健康看板

bash

scripts/vault-health

输出示例：

text

=== Vault 同步健康看板 ===
上次同步：2026-07-18 14:30 (8 分钟前)
未推送提交：2
未拉取提交：0
冲突文件：0
游离附件：12
插件配置漂移：1（obsidian-git/data.json）
同步方案：Git (origin: github.com/me/vault)
分支：main

建议：
- 推送 2 个未推送提交
- 检查 obsidian-git 插件配置是否需要排除

真实场景示例

场景1：桌面+手机 Git 同步

text

用户：在手机上用 Working Copy 改了笔记，桌面要拉
执行：
1. 桌面 git pull --rebase --autostash
2. 健康看板确认无冲突
3. 继续编辑

场景2：iCloud 冲突副本清理

text

用户：iCloud 同步生成了 5 个冲突副本
执行：
1. conflict-scan → 列出 5 个冲突文件
2. conflict-resolve --strategy three-way 逐个合并
3. 3 个合并成功，2 个保留双方等手动处理
4. 报告：清理 3 个冲突，2 个待处理

场景3：插件配置漂移

text

用户：桌面装了新插件，手机没装
执行：
1. vault-health → 检测到 community-plugins.json 漂移
2. 提示：桌面有 dataview，手机无
3. 用户选择：手机也装（同步配置）或桌面禁用（保持一致）

场景4：选择性同步附件

text

用户：附件太多，手机不想全同步
执行：
1. 配置 .gitignore 排除大附件目录
2. 用 Git LFS 管理大文件
3. 或切到 Obsidian Sync（支持选择性同步）

FAQ

Q1: Git 同步在手机上怎么搞？ A: iOS 用 Working Copy（付费）或 Obsidian Git 插件；Android 用 Termux + git 或 Obsidian Git 插件。Obsidian Git 插件可在 Obsidian 内自动同步。

Q2: iCloud 经常生成冲突副本怎么办？ A: 三步：① 用 conflict-scan 定期扫描；② 用 conflict-resolve 三路合并；③ 考虑切到 Git 或 Obsidian Sync 彻底解决。

Q3: .obsidian/workspace.json 要同步吗？ A: 不要。每设备的工作区状态独立。同步会导致打开 Obsidian 时窗口布局乱跳。已在 .gitignore 排除。

Q4: 插件配置要不要同步？ A: 分情况。community-plugins.json（插件清单）同步；插件 data.json 看是否含设备特定路径。obsidian-git 等含路径的配置建议排除。

Q5: 冲突合并丢内容了怎么办？ A: 不会。冲突解决脚本永远保留双方副本。若合并成功也会在 .trash/ 留一份原文件。Git 还有 git reflog 可找回。

故障排查

现象	排查路径
Git push 被拒	git pull --rebase 先拉 → 解决冲突 → 重试
iCloud 不同步	检查 iCloud Drive 是否启用 → 检查网络 → 重启 iCloud 进程
手机看不到新笔记	检查 Git 是否 push → 手机端 pull → 检查 .gitignore 是否误排除
插件配置丢失	检查是否被 .gitignore 排除 → 从 Git 历史恢复 git checkout HEAD -- path
冲突副本爆炸	用 conflict-resolve 批量处理 → 评估是否换同步方案
同步慢	检查附件大小 → 用 Git LFS → 或排除大附件目录

依赖说明

运行环境

• Agent 平台: 任意支持 SKILL.md 的 AI Agent
• 操作系统: Windows / macOS / Linux（移动端需配合同步工具）
• Obsidian: 桌面版 + 移动版（多端场景）

第三方依赖

依赖项	类型	是否必需	获取方式
git	版本控制	必需（Git 方案）	系统自带或 git-scm.com
Git 远程仓库	托管	必需（Git 方案）	GitHub/GitLab/Gitea
obsidian-cli	命令行工具	推荐	npm / 官方仓库
iCloud Drive	同步服务	可选（iCloud 方案）	Apple 内置
Dropbox	同步服务	可选（Dropbox 方案）	dropbox.com
Syncthing	同步服务	可选（自建方案）	syncthing.net
Obsidian Sync	同步服务	可选（付费方案）	obsidian.md 订阅
Working Copy（iOS）	Git 客户端	可选（iOS Git）	App Store
LLM API	API	必需	由 Agent 内置 LLM 提供

API Key 配置

• Git 远程仓库认证（SSH key 或 Personal Access Token）
• Obsidian Sync 订阅账号（若使用付费方案）
• 无需第三方 API Key

可用性分类

• 分类: MD+EXEC（Markdown 指令 + 必须通过 exec 执行 git 与同步脚本）
• 说明: 基于自然语言指令驱动 Agent 配置并运维多端同步，含冲突自愈与健康监控