---
name: obsidian-history
description: Obsidian 版本历史与同步管理：查看/恢复/对比 File Recovery 本地快照（`history:*`）、管理 Obsidian Sync 的暂停与恢复（`sync:*`）、从云端回收站恢复误删文件。触发词：误删、恢复笔记、文件历史、版本恢复、版本对比、diff 笔记、Obsidian Sync、同步暂停。不用于 git 版本控制（直接 Bash git 命令）。Sync 相关命令需付费 Obsidian Sync 订阅。检测到 .obsidian/ 时与核心技能同步激活。
---

# Obsidian History · 版本历史与同步

> Obsidian 的**时间旅行层**：File Recovery（本地版本快照）+ Obsidian Sync（云端版本历史）。AI agent 的大规模写入操作需要这一层作为"后悔药"。

---

## 何时使用

- 查看某文件的**历史版本列表**
- **恢复**某文件的某个版本（误删/误改的救命稻草）
- **对比**两个版本的差异（diff）
- 查看 **Obsidian Sync 状态**（是否同步完成、积压多少）
- **暂停/恢复** Obsidian Sync（批量操作前关掉，避免抖动）
- 查看**已删除**的文件（云端回收站）

## 不用于

- Git 版本控制 → 普通 Bash git 命令
- Obsidian 自带回收站（已删除文件） → `obsidian delete` + 手动恢复
- 云盘历史版本（iCloud / Dropbox） → 云盘客户端

---

## 命令速查

### File Recovery（本地快照，核心插件）

> Obsidian 内置 "File Recovery" 核心插件自动快照本地版本（默认每 5 分钟，保留 7 天）。

```bash
obsidian history file="重要笔记"              # 列出文件的历史版本
obsidian history path="10-Projects/alpha/README.md"
obsidian history:list                          # 列出所有有历史的文件

obsidian history:open file="重要笔记"          # 在 Obsidian UI 中打开恢复界面
obsidian history:read file="重要笔记" version=1       # 读取第 1 个历史版本
obsidian history:read file="重要笔记" version=5       # 读取更早的版本
obsidian history:restore file="重要笔记" version=3    # ⚠ 恢复到第 3 个版本（覆盖当前）
```

### Diff 对比

```bash
obsidian diff file="重要笔记"                          # 列出所有可 diff 的版本
obsidian diff file="重要笔记" from=3 to=1              # 版本 3 到版本 1 的差异
obsidian diff file="重要笔记" filter=local             # 只看本地版本
obsidian diff file="重要笔记" filter=sync              # 只看 Sync 版本
```

### Obsidian Sync（付费功能）

```bash
obsidian sync:status                  # 当前同步状态
obsidian sync on                      # 恢复同步
obsidian sync off                     # 暂停同步（批量操作前）

obsidian sync:deleted                 # 列出已删除的文件（云端回收站）
obsidian sync:deleted total           # 数量

obsidian sync:history file=<name>             # 某文件的 Sync 版本历史
obsidian sync:history file=<name> total       # 版本数
obsidian sync:open file=<name>                # 在 Obsidian 中打开同步历史界面
obsidian sync:read file=<name> version=3      # 读取某 Sync 版本的内容
obsidian sync:restore file=<name> version=3   # ⚠ 恢复到某 Sync 版本
```

---

## AI Agent 最佳实践

### 场景 1 · 危险操作的"后悔药"流程

AI agent 做批量写入前，先做快照检查点：

```bash
#!/bin/bash
# 批量操作前的保险

OP_NAME="refactor-project-alpha"
BEFORE=$(date +%Y%m%d-%H%M%S)

# 1. 暂停 Sync（如果启用），避免抖动
obsidian sync off 2>/dev/null

# 2. 记录受影响的文件列表
obsidian files folder="10-Projects/alpha" format=json > /tmp/${OP_NAME}-${BEFORE}.json

# 3. 提交一个 git 检查点（vault 是 git 仓库的话）
cd "$(obsidian vault info=path)"
git add -A && git commit -m "checkpoint before ${OP_NAME}"

# 4. 执行批量操作
# ... obsidian move / property:set / delete ...

# 5. 恢复 Sync
obsidian sync on

# 6. 如果出错，用 history 或 git 回退
```

### 场景 2 · 恢复误删的笔记

```bash
# 1. 列出所有有历史的文件
obsidian history:list

# 2. 如果误删了"项目 Alpha"，先查是否还能找到历史
obsidian history file="项目Alpha"

# 3. 读取最近的版本内容
obsidian history:read file="项目Alpha" version=1

# 4. 确认无误后恢复
obsidian history:restore file="项目Alpha" version=1
```

### 场景 3 · AI 改写对比

AI agent 改完文章后，和上一版对比看变化：

```bash
# AI 修改完一篇文章
obsidian create path="drafts/article.md" content="新版本..."

# 对比与上一版的差异
obsidian diff file="article" from=2 to=1
```

### 场景 4 · Sync 状态监控

```bash
# 在脚本中检查同步是否完成再继续
while true; do
  STATUS=$(obsidian sync:status)
  if echo "$STATUS" | grep -q "synced"; then
    echo "Sync 完成"
    break
  fi
  sleep 5
done
```

### 场景 5 · 从云端回收站恢复

```bash
# 查看云端已删除文件
obsidian sync:deleted

# 对某个误删的文件恢复到某版本
obsidian sync:history file="重要笔记"
obsidian sync:read file="重要笔记" version=1   # 先确认内容
obsidian sync:restore file="重要笔记" version=1
```

---

## File Recovery vs Obsidian Sync 版本历史

| 特性 | File Recovery（本地） | Obsidian Sync（云端） |
|-----|---------------------|---------------------|
| 成本 | 免费（核心插件） | 付费订阅 |
| 触发 | 每 5 分钟自动（可配置） | 每次修改实时 |
| 保留 | 默认 7 天 | 默认 1 年 |
| 位置 | 本地 `.obsidian/` 内 | 云端服务器 |
| 跨设备 | ❌ | ✅ |
| 命令前缀 | `history:*` / `diff filter=local` | `sync:*` / `diff filter=sync` |
| 已删除文件恢复 | ❌ | ✅ `sync:deleted` |

**策略建议**：
- 个人单设备 → File Recovery 已够用
- 多设备 / 重度 AI 写入 → 强烈推荐 Sync（订阅值回票价）
- 强烈推荐同时把 vault 纳入 **git 仓库**，作为第三道保险

---

## 与 Git 协作的混合策略

Obsidian 的 history/sync 对**误操作**友好（分钟级粒度），git 对**语义变更**友好（按 commit message 回溯）。

```bash
# .gitignore（放在 vault 根目录）
.obsidian/workspace*
.obsidian/cache
.trash/
.DS_Store
```

```bash
# 批量 AI 操作的 git 惯例
cd $(obsidian vault info=path)

# 操作前：干净状态
git status --porcelain  # 应为空
git commit --allow-empty -m "checkpoint: before AI refactor"

# 操作：agent 执行
# ...

# 操作后：按语义提交
git add -A
git commit -m "ai: refactor zettel links in 50-Zettel/

- 更新了 42 篇笔记的反链
- 重命名了 3 个文件
- 自动添加 created 字段到 15 篇旧笔记"
```

---

## 与其他技能的协作

| 场景 | 链路 |
|-----|------|
| 大批量写入前 | **obsidian-history**（checkpoint）→ 其他写入技能 |
| Agent 审计回溯 | **obsidian-daily**（审计日志）+ obsidian-history（版本对比） |
| 项目归档前 | obsidian-history（sync:status 确认）→ **obsidian**（move） |
| 回滚 AI 改写 | **obsidian-search** 找出受影响文件 → obsidian-history:restore |

---

## 常见陷阱

| 现象 | 原因 | 对策 |
|------|------|------|
| `history` 命令返回空 | File Recovery 未启用 | `plugin:enable id=file-recovery` |
| `sync:*` 命令全部失败 | 未订阅 Obsidian Sync | 用 File Recovery + git 替代 |
| `history:restore` 后新改动丢失 | restore 是覆盖 | restore 前先 `read` 保存当前 |
| Sync 卡住不同步 | 网络或冲突 | `sync:status` 查看；必要时 `sync off; sync on` |
| 批量操作中途失败 | 没做检查点 | 永远先 git commit 或 sync off |
| version 编号混乱 | 不同来源混用 | 用 `diff filter=local` 或 `filter=sync` 区分 |
| AI 反复 restore 导致循环 | 无终止条件 | agent 写入前记录 baseline，只允许恢复一次 |