yixiong-claude-marketplace/plugins/obsidian/skills/obsidian-history/SKILL.md

name, description

name	description
obsidian-history	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 天）。

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 对比

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（付费功能）

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 做批量写入前，先做快照检查点：

#!/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 · 恢复误删的笔记

# 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 改完文章后，和上一版对比看变化：

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

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

场景 4 · Sync 状态监控

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

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

# 查看云端已删除文件
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 回溯）。

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

# 批量 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，只允许恢复一次