知识库同步引擎

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

同步方案选型

选型规则：

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

Vault 模型与同步边界

Git 同步方案（推荐）

初始化

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

多设备克隆

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

日常同步工作流

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

# 编辑笔记...

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

自动同步脚本

# 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/ 分设备策略

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

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

插件配置治理

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

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

冲突检测与自愈

冲突识别

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

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

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

三路合并自愈

# 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，等用户手动处理
• 永不静默丢弃任何一方

同步健康看板

scripts/vault-health

输出示例：

=== 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 同步

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

场景2：iCloud 冲突副本清理

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

场景3：插件配置漂移

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

场景4：选择性同步附件

用户：附件太多，手机不想全同步
执行：
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 可找回。

故障排查

依赖说明

运行环境

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

第三方依赖

API Key 配置

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

可用性分类

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