cursor-guard 1.0.1 → 1.2.0

package/README.md

@@ -1,30 +1,31 @@
 # Cursor Guard
 
+[![npm version](https://img.shields.io/npm/v/cursor-guard)](https://www.npmjs.com/package/cursor-guard)
+[![license](https://img.shields.io/github/license/zhangqiang8vipp/cursor-guard)](LICENSE)
+
 Protects your code from accidental AI overwrite or deletion in [Cursor](https://cursor.com).
 
-保护你的代码免受 [Cursor](https://cursor.com) AI 代理意外覆写或删除。
+**[中文文档](README.zh-CN.md)**
 
 ---
 
-## What It Does / 功能介绍
+## What It Does
 
 When Cursor's AI agent edits your files, there's a risk of accidental overwrites, deletions, or loss of work. **Cursor Guard** enforces a safety protocol:
 
-当 Cursor 的 AI 代理编辑你的文件时，可能会意外覆盖、删除或丢失代码。**Cursor Guard** 强制执行一套安全协议：
-
-- **Mandatory pre-write snapshots / 强制写前快照** — Git commit or shadow copy before any destructive operation / 在任何破坏性操作前自动 Git 提交或影子拷贝
-- **Read before Write / 先读后写** — The agent must read a file before overwriting it / 代理必须先读取文件内容，才能覆写
-- **Review before apply / 预览再执行** — Diff previews and explicit confirmation for dangerous ops / 危险操作前展示 diff 预览并要求确认
-- **Deterministic recovery / 确定性恢复** — Clear priority-ordered recovery paths (Git → shadow copies → conversation context → editor history) / 按优先级的恢复路径（Git → 影子拷贝 → 对话上下文 → 编辑器历史）
-- **Configurable scope / 可配置保护范围** — Protect only what matters via `.cursor-guard.json` / 通过配置文件只保护你关心的文件
-- **Secrets filtering / 敏感文件过滤** — Sensitive files (`.env`, keys, certificates) are auto-excluded from backups / `.env`、密钥、证书等敏感文件自动排除
-- **Auto-backup script / 自动备份脚本** — A PowerShell watcher that periodically snapshots to a dedicated Git branch without disturbing your working tree / 定期快照到独立 Git 分支，不干扰工作区
+- **Mandatory pre-write snapshots** — Git commit or shadow copy before any destructive operation
+- **Read before Write** — The agent must read a file before overwriting it
+- **Review before apply** — Diff previews and explicit confirmation for dangerous ops
+- **Deterministic recovery** — Clear priority-ordered recovery paths (Git → shadow copies → conversation context → editor history)
+- **Configurable scope** — Protect only what matters via `.cursor-guard.json`
+- **Secrets filtering** — Sensitive files (`.env`, keys, certificates) are auto-excluded from backups
+- **Auto-backup script** — A PowerShell watcher that periodically snapshots to a dedicated Git branch without disturbing your working tree
 
 ---
 
-## Installation / 安装
+## Installation
 
-### Method 1: npm install / 方式一：npm 安装
+### Method 1: npm
 
 ```bash
 npm install cursor-guard
@@ -32,106 +33,98 @@ npm install cursor-guard
 
 After installation, copy the skill files to your Cursor skills directory:
 
-安装后，将技能文件复制到 Cursor 技能目录：
-
 **Windows (PowerShell):**
 
 ```powershell
-# Global installation (all projects) / 全局安装（所有项目生效）
+# Global (all projects)
 Copy-Item -Recurse node_modules/cursor-guard "$env:USERPROFILE/.cursor/skills/cursor-guard"
 
-# Per-project installation / 项目级安装（仅当前项目生效）
+# Per-project (current project only)
 Copy-Item -Recurse node_modules/cursor-guard .cursor/skills/cursor-guard
 ```
 
 **macOS / Linux:**
 
 ```bash
-# Global installation / 全局安装
+# Global
 cp -r node_modules/cursor-guard ~/.cursor/skills/cursor-guard
 
-# Per-project installation / 项目级安装
+# Per-project
 cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
 ```
 
 After copying, you can remove the npm dependency if you don't need it in `node_modules`:
 
-复制完成后，如果不需要保留在 `node_modules` 中，可以卸载：
-
 ```bash
 npm uninstall cursor-guard
 ```
 
-### Method 2: Git clone / 方式二：Git 克隆
+### Method 2: Git clone
 
 ```bash
-# Global installation / 全局安装
+# Global
 git clone https://github.com/zhangqiang8vipp/cursor-guard.git ~/.cursor/skills/cursor-guard
 
-# Per-project installation / 项目级安装
+# Per-project
 git clone https://github.com/zhangqiang8vipp/cursor-guard.git .cursor/skills/cursor-guard
 ```
 
-### Method 3: Manual download / 方式三：手动下载
+### Method 3: Manual download
 
 Download from [GitHub Releases](https://github.com/zhangqiang8vipp/cursor-guard/releases) and extract to:
 
-从 [GitHub Releases](https://github.com/zhangqiang8vipp/cursor-guard/releases) 下载并解压到：
-
 ```
-~/.cursor/skills/cursor-guard/          # Global / 全局
-<project-root>/.cursor/skills/cursor-guard/  # Per-project / 项目级
+~/.cursor/skills/cursor-guard/               # Global
+<project-root>/.cursor/skills/cursor-guard/   # Per-project
 ```
 
-### Verify Installation / 验证安装
+### Verify Installation
 
-After installation, your directory structure should look like this / 安装后目录结构应如下所示：
+After installation, your directory structure should look like this:
 
 ```
 .cursor/skills/cursor-guard/
-├── SKILL.md                          # AI agent instructions / AI 代理指令
+├── SKILL.md                          # AI agent instructions
 ├── README.md
 ├── LICENSE
 └── references/
-    ├── auto-backup.ps1               # Auto-backup script / 自动备份脚本
-    ├── recovery.md                   # Recovery commands / 恢复命令
-    ├── cursor-guard.example.json     # Example config / 示例配置
-    └── cursor-guard.schema.json      # Config schema / 配置 Schema
+    ├── auto-backup.ps1               # Auto-backup script
+    ├── recovery.md                   # Recovery commands
+    ├── cursor-guard.example.json     # Example config
+    └── cursor-guard.schema.json      # Config schema
 ```
 
-The skill activates automatically when the AI agent detects risky operations (file edits, deletes, renames) or when you mention recovery-related terms.
-
-技能会在 AI 代理检测到高风险操作（文件编辑、删除、重命名）或你提到恢复相关词汇时自动激活。无需其他设置，安装即生效。
+The skill activates automatically when the AI agent detects risky operations or when you mention recovery-related terms. No extra setup needed.
 
 ---
 
-## Quick Start / 快速上手
+## Quick Start
 
-1. **Install the skill** using any method above / 用以上任意方式安装技能
+1. **Install the skill** using any method above
 
-2. **Open Cursor** and start an Agent conversation / 打开 Cursor，开始一个 Agent 对话
+2. **Open Cursor** and start an Agent conversation
 
-3. **The skill works automatically** — when the AI agent tries to edit files, it will: / 技能自动生效——当 AI 代理尝试编辑文件时，会自动：
-   - Create a Git snapshot before writing / 写入前创建 Git 快照
-   - Read files before overwriting / 覆写前先读取文件
-   - Show diff previews for dangerous operations / 危险操作前展示 diff 预览
-   - Report a status block after each protected operation / 每次受保护操作后报告状态
+3. **The skill works automatically** — when the AI agent tries to edit files, it will:
+   - Create a Git snapshot before writing
+   - Read files before overwriting
+   - Show diff previews for dangerous operations
+   - Report a status block after each protected operation
 
-4. **(Optional) Add project config** to customize protection scope / （可选）添加项目配置自定义保护范围：
+4. **(Optional) Add project config** to customize protection scope:
 
 ```bash
 cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guard.json
 ```
 
-5. **(Optional) Run auto-backup** in a separate terminal / （可选）在独立终端运行自动备份：
+5. **(Optional) Run auto-backup** in a separate terminal:
 
 ```powershell
 .\auto-backup.ps1 -Path "D:\MyProject"
 ```
 
-### Project Configuration / 项目配置
+### Project Configuration
 
-Edit `.cursor-guard.json` to define which files to protect / 编辑 `.cursor-guard.json` 定义保护哪些文件：
+Edit `.cursor-guard.json` to define which files to protect:
 
 ```json
 {
@@ -145,74 +138,100 @@ Edit `.cursor-guard.json` to define which files to protect / 编辑 `.cursor-gua
 
 ---
 
-## Auto-Backup Script / 自动备份脚本
+## Auto-Backup Script
 
 Run in a separate terminal while working in Cursor:
 
-在使用 Cursor 时，在**单独的终端窗口**中运行：
-
 ```powershell
 .\auto-backup.ps1 -Path "D:\MyProject"
 
-# Custom interval (default 60s) / 自定义间隔（默认 60 秒）：
+# Custom interval (default 60s):
 .\auto-backup.ps1 -Path "D:\MyProject" -IntervalSeconds 30
 ```
 
 The script uses Git plumbing commands to snapshot to `cursor-guard/auto-backup` branch — it never switches branches or touches your working index.
 
-脚本使用 Git 底层命令快照到 `cursor-guard/auto-backup` 分支——不会切换分支，也不会影响你的工作索引。
-
-> **Note / 注意**: Run this script in a separate PowerShell window, NOT inside Cursor's integrated terminal. Cursor's terminal may interfere with Git plumbing commands.
->
-> 请在独立的 PowerShell 窗口中运行此脚本，不要在 Cursor 的集成终端中运行，因为 Cursor 终端可能干扰 Git 底层命令。
+> **Note**: Run this script in a separate PowerShell window, NOT inside Cursor's integrated terminal. Cursor's terminal may interfere with Git plumbing commands.
 
 ---
 
-## Recovery / 恢复
+## Recovery
+
+If something goes wrong, just tell the AI agent in natural language:
 
-If something goes wrong, recovery follows this priority:
+### By time
 
-出问题时，按以下优先级恢复：
+> "restore to 5 minutes ago"
+> "go back to yesterday's version"
+> "restore to 3pm today"
+
+### By version
+
+> "undo the last change"
+> "go back 3 versions"
+> "restore to the previous version"
+
+### By file
+
+> "restore src/app.py to 10 minutes ago"
+> "restore src/app.py to the previous version"
+
+The agent will automatically search Git history and auto-backup snapshots, show you matching versions to choose from, and restore after your confirmation.
+
+### Recovery priority
 
 1. **Git** — `git restore`, `git reset`, `git reflog`
-2. **Shadow copies / 影子拷贝** — `.cursor-guard-backup/<timestamp>/`
-3. **Conversation context / 对话上下文** — Original file content captured by agent Read calls / 代理 Read 调用捕获的原始内容
-4. **Editor history / 编辑器历史** — VS Code/Cursor Timeline (auxiliary / 辅助)
+2. **Auto-backup branch** — `cursor-guard/auto-backup`
+3. **Shadow copies** — `.cursor-guard-backup/<timestamp>/`
+4. **Conversation context** — Original file content captured by agent Read calls
+5. **Editor history** — VS Code/Cursor Timeline (auxiliary)
 
-See [references/recovery.md](references/recovery.md) for detailed commands / 详细命令见恢复文档。
+See [references/recovery.md](references/recovery.md) for detailed commands.
 
 ---
 
-## Trigger Keywords / 触发关键词
+## Trigger Keywords
 
-The skill activates on these signals / 技能在以下信号时激活：
+The skill activates on these signals:
 
-- File edits, deletes, renames by the AI agent / AI 代理的文件编辑、删除、重命名
-- Recovery requests / 恢复请求："回滚"、"误删"、"丢版本"、"rollback"、"undo"、"recover"
-- History issues / 历史问题：checkpoints missing、Timeline not working、save failures
+- File edits, deletes, renames by the AI agent
+- Recovery requests: "rollback", "undo", "recover", "restore"
+- Time-based recovery: "restore to N minutes ago", "go back to yesterday"
+- Version-based recovery: "previous version", "go back N versions"
+- History issues: checkpoints missing, Timeline not working, save failures
 
 ---
 
-## Files / 文件说明
+## Files
 
-| File / 文件 | Purpose / 用途 |
+| File | Purpose |
 |------|---------|
-| `SKILL.md` | Main skill instructions for the AI agent / AI 代理的主要技能指令 |
-| `references/auto-backup.ps1` | PowerShell auto-backup watcher script / PowerShell 自动备份监控脚本 |
-| `references/recovery.md` | Recovery command templates / 恢复命令模板 |
-| `references/cursor-guard.example.json` | Example project configuration / 示例项目配置 |
-| `references/cursor-guard.schema.json` | JSON Schema for config validation / 配置文件的 JSON Schema |
+| `SKILL.md` | Main skill instructions for the AI agent |
+| `references/auto-backup.ps1` | PowerShell auto-backup watcher script |
+| `references/recovery.md` | Recovery command templates |
+| `references/cursor-guard.example.json` | Example project configuration |
+| `references/cursor-guard.schema.json` | JSON Schema for config validation |
 
 ---
 
-## Requirements / 环境要求
+## Known Limitations
+
+- **Binary files**: Git diffs and snapshots work on text files. Binary files (images, compiled assets) are stored but cannot be meaningfully diffed or partially restored.
+- **Untracked files**: Files never committed to Git cannot be recovered from Git history. Shadow copy (`backup_strategy: "shadow"` or `"both"`) is the only safety net for untracked files.
+- **Concurrent agents**: If multiple AI agent threads write to the same file simultaneously, snapshots cannot prevent race conditions. Avoid parallel edits to the same file.
+- **External tools modifying the index**: Tools that alter Git's index (e.g. other Git GUIs, IDE Git integrations) while `auto-backup.ps1` is running may conflict. The script uses a temporary index to minimize this, but edge cases exist.
+- **Git worktree**: The auto-backup script supports worktree layouts (`git rev-parse --git-dir`), but has not been tested with all exotic setups (e.g. `--separate-git-dir`).
+- **Cursor terminal interference**: Cursor's integrated terminal injects `--trailer` flags into `git commit` commands, which breaks plumbing commands like `commit-tree`. Always run `auto-backup.ps1` in a **separate PowerShell window**.
+- **Large repos**: For very large repositories, `git add -A` in the backup loop may be slow. Use `protect` patterns in `.cursor-guard.json` to narrow scope.
+
+## Requirements
 
-- **Git** — for primary backup strategy / 主要备份策略
-- **PowerShell 5.1+** — for auto-backup script (Windows built-in) / 自动备份脚本（Windows 自带）
-- **Cursor IDE** — with Agent mode enabled / 需启用 Agent 模式
+- **Git** — for primary backup strategy
+- **PowerShell 5.1+** — for auto-backup script (Windows built-in)
+- **Cursor IDE** — with Agent mode enabled
 
 ---
 
-## License / 许可证
+## License
 
 MIT

package/README.zh-CN.md

@@ -0,0 +1,237 @@
+# Cursor Guard
+
+[![npm version](https://img.shields.io/npm/v/cursor-guard)](https://www.npmjs.com/package/cursor-guard)
+[![license](https://img.shields.io/github/license/zhangqiang8vipp/cursor-guard)](LICENSE)
+
+保护你的代码免受 [Cursor](https://cursor.com) AI 代理意外覆写或删除。
+
+**[English](README.md)**
+
+---
+
+## 功能介绍
+
+当 Cursor 的 AI 代理编辑你的文件时，可能会意外覆盖、删除或丢失代码。**Cursor Guard** 强制执行一套安全协议：
+
+- **强制写前快照** — 在任何破坏性操作前自动 Git 提交或影子拷贝
+- **先读后写** — 代理必须先读取文件内容，才能覆写
+- **预览再执行** — 危险操作前展示 diff 预览并要求确认
+- **确定性恢复** — 按优先级的恢复路径（Git → 影子拷贝 → 对话上下文 → 编辑器历史）
+- **可配置保护范围** — 通过 `.cursor-guard.json` 配置文件只保护你关心的文件
+- **敏感文件过滤** — `.env`、密钥、证书等敏感文件自动排除备份
+- **自动备份脚本** — 定期快照到独立 Git 分支，不干扰工作区
+
+---
+
+## 安装
+
+### 方式一：npm 安装
+
+```bash
+npm install cursor-guard
+```
+
+安装后，将技能文件复制到 Cursor 技能目录：
+
+**Windows (PowerShell):**
+
+```powershell
+# 全局安装（所有项目生效）
+Copy-Item -Recurse node_modules/cursor-guard "$env:USERPROFILE/.cursor/skills/cursor-guard"
+
+# 项目级安装（仅当前项目生效）
+Copy-Item -Recurse node_modules/cursor-guard .cursor/skills/cursor-guard
+```
+
+**macOS / Linux:**
+
+```bash
+# 全局安装
+cp -r node_modules/cursor-guard ~/.cursor/skills/cursor-guard
+
+# 项目级安装
+cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+```
+
+复制完成后，如果不需要保留在 `node_modules` 中，可以卸载：
+
+```bash
+npm uninstall cursor-guard
+```
+
+### 方式二：Git 克隆
+
+```bash
+# 全局安装
+git clone https://github.com/zhangqiang8vipp/cursor-guard.git ~/.cursor/skills/cursor-guard
+
+# 项目级安装
+git clone https://github.com/zhangqiang8vipp/cursor-guard.git .cursor/skills/cursor-guard
+```
+
+### 方式三：手动下载
+
+从 [GitHub Releases](https://github.com/zhangqiang8vipp/cursor-guard/releases) 下载并解压到：
+
+```
+~/.cursor/skills/cursor-guard/               # 全局
+<项目根目录>/.cursor/skills/cursor-guard/      # 项目级
+```
+
+### 验证安装
+
+安装后目录结构应如下所示：
+
+```
+.cursor/skills/cursor-guard/
+├── SKILL.md                          # AI 代理指令
+├── README.md
+├── LICENSE
+└── references/
+    ├── auto-backup.ps1               # 自动备份脚本
+    ├── recovery.md                   # 恢复命令模板
+    ├── cursor-guard.example.json     # 示例配置
+    └── cursor-guard.schema.json      # 配置 Schema
+```
+
+技能会在 AI 代理检测到高风险操作（文件编辑、删除、重命名）或你提到恢复相关词汇时自动激活。无需其他设置，安装即生效。
+
+---
+
+## 快速上手
+
+1. **安装技能** — 用以上任意方式安装
+
+2. **打开 Cursor** — 开始一个 Agent 对话
+
+3. **技能自动生效** — 当 AI 代理尝试编辑文件时，会自动：
+   - 写入前创建 Git 快照
+   - 覆写前先读取文件
+   - 危险操作前展示 diff 预览
+   - 每次受保护操作后报告状态
+
+4. **（可选）添加项目配置** — 自定义保护范围：
+
+```bash
+cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guard.json
+```
+
+5. **（可选）运行自动备份** — 在独立终端运行：
+
+```powershell
+.\auto-backup.ps1 -Path "D:\MyProject"
+```
+
+### 项目配置
+
+编辑 `.cursor-guard.json` 定义保护哪些文件：
+
+```json
+{
+  "protect": ["src/**", "lib/**", "package.json"],
+  "ignore": ["node_modules/**", "dist/**"],
+  "auto_backup_interval_seconds": 60,
+  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+  "retention": { "mode": "days", "days": 30 }
+}
+```
+
+---
+
+## 自动备份脚本
+
+在使用 Cursor 时，在**单独的终端窗口**中运行：
+
+```powershell
+.\auto-backup.ps1 -Path "D:\MyProject"
+
+# 自定义间隔（默认 60 秒）：
+.\auto-backup.ps1 -Path "D:\MyProject" -IntervalSeconds 30
+```
+
+脚本使用 Git 底层命令快照到 `cursor-guard/auto-backup` 分支——不会切换分支，也不会影响你的工作索引。
+
+> **注意**：请在独立的 PowerShell 窗口中运行此脚本，不要在 Cursor 的集成终端中运行，因为 Cursor 终端可能干扰 Git 底层命令。
+
+---
+
+## 恢复
+
+出问题时，直接用自然语言告诉 AI 代理即可：
+
+### 按时间恢复
+
+> "帮我恢复到5分钟前"
+> "恢复到今天下午3点的状态"
+> "回到昨天的版本"
+
+### 按版本恢复
+
+> "恢复到上一个版本"
+> "回到前3个版本"
+> "撤销最近两次修改"
+
+### 指定文件恢复
+
+> "把 src/app.py 恢复到10分钟前"
+> "把 src/app.py 恢复到上一个版本"
+
+代理会自动搜索 Git 历史和自动备份快照，列出匹配版本供你选择，确认后执行恢复。
+
+### 恢复优先级
+
+1. **Git** — `git restore`, `git reset`, `git reflog`
+2. **自动备份分支** — `cursor-guard/auto-backup`
+3. **影子拷贝** — `.cursor-guard-backup/<时间戳>/`
+4. **对话上下文** — 代理 Read 调用捕获的原始文件内容
+5. **编辑器历史** — VS Code/Cursor Timeline（辅助）
+
+详细恢复命令见 [references/recovery.md](references/recovery.md)。
+
+---
+
+## 触发关键词
+
+技能在以下信号时激活：
+
+- AI 代理的文件编辑、删除、重命名
+- 恢复请求："回滚"、"误删"、"丢版本"、"改不回来"
+- 按时间恢复："恢复到N分钟前"、"恢复到下午3点"、"回到昨天"
+- 按版本恢复："恢复到上一个版本"、"前N个版本"、"撤销最近N次修改"
+- 历史问题：Checkpoint 丢失、Timeline 不工作、保存失败
+
+---
+
+## 文件说明
+
+| 文件 | 用途 |
+|------|------|
+| `SKILL.md` | AI 代理的主要技能指令 |
+| `references/auto-backup.ps1` | PowerShell 自动备份监控脚本 |
+| `references/recovery.md` | 恢复命令模板 |
+| `references/cursor-guard.example.json` | 示例项目配置 |
+| `references/cursor-guard.schema.json` | 配置文件的 JSON Schema |
+
+---
+
+## 已知限制
+
+- **二进制文件**：Git 快照可以存储二进制文件（图片、编译产物），但无法进行有意义的 diff 或部分恢复。
+- **未跟踪文件**：从未提交到 Git 的文件无法从 Git 历史恢复。影子拷贝（`backup_strategy: "shadow"` 或 `"both"`）是未跟踪文件的唯一安全网。
+- **并发 Agent**：如果多个 AI 代理线程同时写入同一文件，快照无法防止竞态条件。请避免并行编辑同一文件。
+- **外部工具修改索引**：在 `auto-backup.ps1` 运行期间，其他修改 Git 索引的工具（如 Git GUI、IDE Git 集成）可能冲突。脚本使用临时索引来最小化风险，但边缘情况仍存在。
+- **Git worktree**：自动备份脚本支持 worktree 布局（`git rev-parse --git-dir`），但未在所有特殊配置下测试（如 `--separate-git-dir`）。
+- **Cursor 终端干扰**：Cursor 集成终端会向 `git commit` 命令注入 `--trailer` 标志，导致 `commit-tree` 等底层命令异常。请始终在**独立的 PowerShell 窗口**中运行 `auto-backup.ps1`。
+- **大型仓库**：对于非常大的仓库，备份循环中的 `git add -A` 可能较慢。使用 `.cursor-guard.json` 中的 `protect` 模式缩小范围。
+
+## 环境要求
+
+- **Git** — 主要备份策略
+- **PowerShell 5.1+** — 自动备份脚本（Windows 自带）
+- **Cursor IDE** — 需启用 Agent 模式
+
+---
+
+## 许可证
+
+MIT

package/SKILL.md

@@ -19,6 +19,7 @@ Use this skill when any of the following appear:
 - **History confusion**: Checkpoints missing, Timeline/local history not rolling back, "save failed" after external writes.
 - **Parallel context**: Multiple repos or branches; unclear which folder is the workspace root.
 - **Recovery asks**: e.g. "改不回来", "丢版本", "回滚", "reflog", "误删", or English equivalents.
+- **Time/version recovery**: e.g. "恢复到5分钟前", "恢复到前3个版本", "回到上一个版本", "restore to 10 minutes ago", "go back 2 versions", "恢复到下午3点的状态".
 
 If none of the above, do not expand scope; answer normally.
 
@@ -33,6 +34,9 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
   "protect": ["src/**", "lib/**", "package.json"],
   "ignore": ["node_modules/**", "dist/**", "*.log"],
 
+  // "git": auto-backup to a dedicated branch (default)
+  // "shadow": file copies to .cursor-guard-backup/<timestamp>/
+  // "both": git branch snapshot + shadow copies
   "backup_strategy": "git",
   "auto_backup_interval_seconds": 60,
 
@@ -87,15 +91,46 @@ When the target file of an edit **falls outside the protected scope**, the agent
 
 **Before any High-risk operation on a protected file:**
 
+Use a **temporary index and dedicated ref** so the user's staged/unstaged state is never touched:
+
+```bash
+# 1. Create temp index from HEAD
+GIT_INDEX_FILE=.git/guard-snapshot-index git read-tree HEAD
+
+# 2. Stage working-tree files into temp index
+GIT_INDEX_FILE=.git/guard-snapshot-index git add -A
+
+# 3. Write tree and create commit on a guard ref (not on the user's branch)
+TREE=$(GIT_INDEX_FILE=.git/guard-snapshot-index git write-tree)
+COMMIT=$(git commit-tree $TREE -p HEAD -m "guard: snapshot before ai edit")
+git update-ref refs/guard/snapshot $COMMIT
+
+# 4. Cleanup
+rm .git/guard-snapshot-index
 ```
-git add -A && git commit -m "guard: snapshot before ai edit" --no-verify
+
+**PowerShell equivalent** (for agent Shell calls):
+
+```powershell
+$guardIdx = Join-Path (git rev-parse --git-dir) "guard-snapshot-index"
+$env:GIT_INDEX_FILE = $guardIdx
+git read-tree HEAD
+git add -A
+$tree = git write-tree
+$env:GIT_INDEX_FILE = $null
+Remove-Item $guardIdx -Force -ErrorAction SilentlyContinue
+$commit = git commit-tree $tree -p HEAD -m "guard: snapshot before ai edit"
+git update-ref refs/guard/snapshot $commit
 ```
 
 - Run this via Shell tool BEFORE the first Write / StrReplace / Delete call.
-- If `.cursor-guard.json` exists with `protect` patterns, the agent may scope the commit: `git add <protected-paths>` instead of `-A` to keep the snapshot focused.
-- If `git status` shows nothing to commit, that's fine — the existing HEAD is the rollback point.
+- The user's index (staged files) and current branch are **never modified**.
+- If `.cursor-guard.json` exists with `protect` patterns, scope `git add` to those paths instead of `-A`.
 - Record the commit hash (short) and report it to the user.
-- Before committing, check staged files against `secrets_patterns` (§0). Exclude any matches and warn the user.
+- To restore: `git restore --source=refs/guard/snapshot -- <file>`.
+- Before writing the tree, check staged files against `secrets_patterns` (§0). Exclude any matches and warn the user.
+
+**Simplified fallback**: If the plumbing approach fails (e.g. `commit-tree` not available), the agent MAY fall back to `git stash push -m "guard: snapshot" --keep-index` + `git stash pop` to shelter and restore the user's state. Report which method was used in the status block.
 
 **Before any Medium-risk operation:**
 
@@ -151,14 +186,26 @@ When editing 3+ files in one task:
 
 ## 4. Backup Strategy (Priority)
 
-1. **Git local commits** — primary safety net. Short WIP commits before risky AI runs.
-2. **Shadow copy** (`.cursor-guard-backup/`) — fallback for non-git or when user wants extra insurance.
-3. **Auto-backup script** — see [references/auto-backup.ps1](references/auto-backup.ps1) for a PowerShell watcher that auto-commits on file change.
+There are two distinct backup mechanisms. Do not confuse them:
+
+| | **Git branch snapshot** | **Shadow copy** |
+|---|---|---|
+| **What** | Commits to `cursor-guard/auto-backup` branch via plumbing | File copies to `.cursor-guard-backup/<timestamp>/` |
+| **Who creates** | `auto-backup.ps1` (when `backup_strategy` = `git` or `both`) | `auto-backup.ps1` (when `backup_strategy` = `shadow` or `both`); or the agent manually (§2b) |
+| **Who cleans up** | Manual: `git branch -D cursor-guard/auto-backup` | `auto-backup.ps1` per `retention` config; or manual |
+| **Restore** | `git restore --source=cursor-guard/auto-backup -- <file>` | `Copy-Item ".cursor-guard-backup/<ts>/<file>" "<path>"` |
+| **Requires Git** | Yes | No (fallback for non-git repos) |
+
+**Priority order for the agent:**
+
+1. **Guard ref snapshot** (`refs/guard/snapshot`) — agent creates before each high-risk edit using temp index (§2a). Does not pollute user's branch or staging area.
+2. **Git branch auto-backup** (`cursor-guard/auto-backup`) — periodic snapshots by `auto-backup.ps1`.
+3. **Shadow copy** (`.cursor-guard-backup/`) — fallback for non-git repos, or as extra insurance when `backup_strategy = "both"`.
 4. **Editor habits** — Ctrl+S frequently; optional extensions are user-configured, mention only if asked.
 
 **Hard default:** Do NOT `git push` unless the user explicitly asks. Scope = **local only**.
 
-**Retention:** Shadow copies are auto-cleaned by `auto-backup.ps1` per the `retention` config (default: keep 30 days). For manual cleanup of the backup branch, see [references/recovery.md](references/recovery.md).
+**Retention:** The `retention` config in `.cursor-guard.json` controls cleanup of **shadow copy directories** only. Git branch snapshots are not subject to retention; clean them manually (see [references/recovery.md](references/recovery.md)).
 
 ---
 
@@ -172,6 +219,126 @@ When editing 3+ files in one task:
 
 ---
 
+## 5a. Time-Based & Version-Based Recovery
+
+When the user requests recovery using time or version references, follow this workflow:
+
+### Trigger Phrases (Chinese & English)
+
+| Pattern | Type | Example |
+|---------|------|---------|
+| "恢复到 N 分钟/小时前", "N minutes/hours ago" | Time-based | "恢复到5分钟前", "restore to 10 minutes ago" |
+| "恢复到前 N 个版本", "go back N versions" | Version-based | "恢复到前3个版本", "go back 2 versions" |
+| "恢复到上一个版本", "previous version" | Version-based (N=1) | "回到上一个版本", "undo last change" |
+| "恢复到今天下午3点", "restore to 3pm" | Time-based (absolute) | "恢复到下午3点的状态" |
+| "恢复到昨天的版本", "yesterday's version" | Time-based | "恢复到昨天" |
+
+### Step 1: Parse the Request
+
+Extract two things from the user's request:
+- **Target scope**: specific file(s) or entire project?
+- **Reference point**: a time expression or a version count?
+
+If unclear, ask: "你想恢复哪个文件？还是整个项目？" / "Which file(s) do you want to restore?"
+
+### Step 2: Find Matching Commits
+
+**For time-based requests**, the goal is to find the **latest commit AT or BEFORE the target time** — not commits after it.
+
+```bash
+# "恢复到5分钟前" → find the most recent commit BEFORE that point
+git log --oneline --before="5 minutes ago" -5 -- <file>
+
+# Auto-backup branch (if exists)
+git log cursor-guard/auto-backup --oneline --before="5 minutes ago" -5 -- <file>
+
+# Reflog as fallback (shows all HEAD movements)
+git reflog --before="5 minutes ago" -5
+```
+
+Time expression mapping (always use `--before` to find the state AT that point):
+- "5分钟前" / "5 minutes ago" → `--before="5 minutes ago"`
+- "1小时前" / "1 hour ago" → `--before="1 hour ago"`
+- "今天下午3点" → `--before="today 15:00"`
+- "昨天" / "yesterday" → `--before="yesterday 23:59"`
+
+**Key rule**: the first result from `--before` is the closest commit at or before the target time — that is the correct restore point.
+
+**For version-based requests**, use commit offset:
+
+```bash
+# N versions ago on current branch
+git log --oneline -<N+5> -- <file>
+
+# Or use HEAD~N directly
+git show HEAD~<N>:<file>
+
+# Auto-backup branch
+git log cursor-guard/auto-backup --oneline -<N+5> -- <file>
+```
+
+### Step 3: Present Candidates to User
+
+**Selection rule**: prefer the **latest commit AT or BEFORE the target time**. This is always candidate #1 in the `--before` results. Only if no commit exists before the target time, inform the user and offer the closest commit after it as an approximation.
+
+Show a numbered list of matching commits with timestamps:
+
+```
+Found these snapshots / 找到以下快照:
+
+→ 1. [abc1234] 2026-03-21 16:05:32 — guard: snapshot before ai edit  ← closest before target
+  2. [def5678] 2026-03-21 16:02:15 — guard: auto-backup 2026-03-21 16:02:15
+  3. [ghi9012] 2026-03-21 15:58:40 — feat: add login page
+
+Recommended: #1 (closest to target time). Restore this one? / 推荐 #1（最接近目标时间）。恢复这个？
+```
+
+**Rules**:
+- If only ONE candidate is found, confirm with the user before restoring.
+- If MULTIPLE candidates, pre-select #1 (closest before target) but let the user pick another.
+- If NO candidates before the target time:
+  - Check auto-backup branch: `git rev-parse --verify cursor-guard/auto-backup`
+  - Check shadow copies: `Get-ChildItem .cursor-guard-backup/ -Directory | Sort-Object Name -Descending`
+  - If still nothing, report clearly: "No snapshot found before that time. The earliest available is [hash] at [time]. Do you want to use it?"
+- **Never silently pick a version.** Always show and confirm.
+
+### Step 4: Execute Recovery
+
+**Single file recovery:**
+
+```bash
+git restore --source=<commit-hash> -- <path/to/file>
+```
+
+**Entire project recovery** (destructive — require explicit confirmation):
+
+```bash
+# Show what will change first
+git diff <commit-hash> -- .
+
+# After user confirms:
+git restore --source=<commit-hash> -- .
+```
+
+**From shadow copy:**
+
+```powershell
+# Find the closest timestamp directory
+Get-ChildItem .cursor-guard-backup/ -Directory | Sort-Object Name -Descending
+
+# Restore
+Copy-Item ".cursor-guard-backup/<timestamp>/<file>" "<original-path>"
+```
+
+### Step 5: Verify & Report
+
+After restoring, always:
+1. Show the restored file content (or diff) so the user can verify
+2. Report the recovery in the status block (§6)
+3. Suggest creating a new snapshot of the current (restored) state
+
+---
+
 ## 6. Output to User (When This Skill Was Used)
 
 When you followed this skill's workflow, end with a short **status block**:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Protects code from accidental AI overwrite or deletion in Cursor IDE — mandatory pre-write snapshots, review-before-apply, local Git safety net, and deterministic recovery. | 保护代码免受 Cursor AI 代理意外覆写或删除——强制写前快照、预览再执行、本地 Git 安全网、确定性恢复。",
   "keywords": [
     "cursor",
@@ -22,6 +22,7 @@
   "files": [
     "SKILL.md",
     "README.md",
+    "README.zh-CN.md",
     "LICENSE",
     "references/"
   ],

package/references/auto-backup.ps1

@@ -37,10 +37,16 @@ $ErrorActionPreference = "Stop"
 $resolved = (Resolve-Path $Path).Path
 Set-Location $resolved
 
-# ── Paths ──────────────────────────────────────────────────────────
-$gitDir      = Join-Path $resolved ".git"
-$lockFile    = Join-Path $gitDir   "cursor-guard.lock"
-$guardIndex  = Join-Path $gitDir   "cursor-guard-index"
+# ── Paths (worktree-safe: uses git rev-parse instead of hard-coding .git) ──
+$gitDir      = (git rev-parse --git-dir 2>$null)
+if (-not $gitDir) {
+    $gitDir = Join-Path $resolved ".git"
+} else {
+    $gitDir = (Resolve-Path $gitDir -ErrorAction SilentlyContinue).Path
+    if (-not $gitDir) { $gitDir = Join-Path $resolved ".git" }
+}
+$lockFile    = Join-Path $gitDir "cursor-guard.lock"
+$guardIndex  = Join-Path $gitDir "cursor-guard-index"
 $backupDir   = Join-Path $resolved ".cursor-guard-backup"
 $logFilePath = Join-Path $backupDir "backup.log"
 
@@ -56,6 +62,7 @@ trap { Invoke-Cleanup; break }
 $protectPatterns  = @()
 $ignorePatterns   = @()
 $secretsPatterns  = @(".env", ".env.*", "*.key", "*.pem", "*.p12", "*.pfx", "credentials*")
+$backupStrategy   = "git"
 $retentionMode    = "days"
 $retentionDays    = 30
 $retentionMaxCnt  = 100
@@ -69,6 +76,7 @@ if (Test-Path $cfgPath) {
         if ($cfg.protect)                       { $protectPatterns = @($cfg.protect) }
         if ($cfg.ignore)                        { $ignorePatterns  = @($cfg.ignore) }
         if ($cfg.secrets_patterns)              { $secretsPatterns = @($cfg.secrets_patterns) }
+        if ($cfg.backup_strategy)              { $backupStrategy  = $cfg.backup_strategy }
         if ($cfg.auto_backup_interval_seconds -and $IntervalSeconds -eq 0) {
             $IntervalSeconds = $cfg.auto_backup_interval_seconds
         }
@@ -88,7 +96,8 @@ if (Test-Path $cfgPath) {
 if ($IntervalSeconds -eq 0) { $IntervalSeconds = 60 }
 
 # ── Git repo check ───────────────────────────────────────────────
-if (-not (Test-Path $gitDir)) {
+$isRepo = git rev-parse --is-inside-work-tree 2>$null
+if ($isRepo -ne "true") {
     $ans = Read-Host "Directory is not a Git repo. Initialize? (y/n)"
     if ($ans -eq 'y') {
         git init
@@ -126,6 +135,20 @@ if (-not (git rev-parse --verify $branchRef 2>$null)) {
     Write-Host "[guard] Created branch: $branch" -ForegroundColor Green
 }
 
+# ── Ensure .cursor-guard-backup/ is git-ignored ─────────────────
+$excludeFile = Join-Path $gitDir "info/exclude"
+$excludeDir  = Split-Path $excludeFile
+if (-not (Test-Path $excludeDir)) { New-Item -ItemType Directory -Force $excludeDir | Out-Null }
+$excludeEntry = ".cursor-guard-backup/"
+if (Test-Path $excludeFile) {
+    $content = Get-Content $excludeFile -Raw -ErrorAction SilentlyContinue
+    if (-not $content -or $content -notmatch [regex]::Escape($excludeEntry)) {
+        Add-Content $excludeFile "`n$excludeEntry"
+    }
+} else {
+    Set-Content $excludeFile $excludeEntry
+}
+
 # ── Log directory & helpers ──────────────────────────────────────
 if (-not (Test-Path $backupDir)) { New-Item -ItemType Directory -Force $backupDir | Out-Null }
 
@@ -209,10 +232,50 @@ function Invoke-RetentionCleanup {
     } catch {}
 }
 
+# ── Shadow copy helper ────────────────────────────────────────────
+function Invoke-ShadowCopy {
+    $ts = Get-Date -Format 'yyyyMMdd_HHmmss'
+    $snapDir = Join-Path $backupDir $ts
+    New-Item -ItemType Directory -Force $snapDir | Out-Null
+
+    $files = if ($protectPatterns.Count -gt 0) {
+        $protectPatterns | ForEach-Object { Get-ChildItem $resolved -Recurse -File -Filter $_ -ErrorAction SilentlyContinue }
+    } else {
+        Get-ChildItem $resolved -Recurse -File -ErrorAction SilentlyContinue |
+            Where-Object { $_.FullName -notmatch '[\\/](\.git|\.cursor-guard-backup|node_modules)[\\/]' }
+    }
+
+    $copied = 0
+    foreach ($f in $files) {
+        $rel = $f.FullName.Substring($resolved.Length + 1)
+        $skip = $false
+        foreach ($ig in $ignorePatterns) {
+            $re = '^' + [regex]::Escape($ig).Replace('\*\*','.*').Replace('\*','[^/\\]*').Replace('\?','.') + '$'
+            if ($rel -match $re) { $skip = $true; break }
+        }
+        foreach ($pat in $secretsPatterns) {
+            $re = '^' + [regex]::Escape($pat).Replace('\*','.*').Replace('\?','.') + '$'
+            if ($rel -match $re -or $f.Name -match $re) { $skip = $true; break }
+        }
+        if ($skip) { continue }
+        $dest = Join-Path $snapDir $rel
+        $destDir = Split-Path $dest
+        if (-not (Test-Path $destDir)) { New-Item -ItemType Directory -Force $destDir | Out-Null }
+        Copy-Item $f.FullName $dest -Force
+        $copied++
+    }
+    if ($copied -gt 0) {
+        Write-Log "Shadow copy $ts ($copied files)"
+    } else {
+        Remove-Item $snapDir -Recurse -Force -ErrorAction SilentlyContinue
+    }
+    return $copied
+}
+
 # ── Banner ───────────────────────────────────────────────────────
 Write-Host ""
 Write-Host "[guard] Watching '$resolved' every ${IntervalSeconds}s  (Ctrl+C to stop)" -ForegroundColor Cyan
-Write-Host "[guard] Branch: $branch  |  Retention: $retentionMode ($retentionDays days / $retentionMaxCnt count / ${retentionMaxMB} MB)" -ForegroundColor Cyan
+Write-Host "[guard] Strategy: $backupStrategy  |  Branch: $branch  |  Retention: $retentionMode ($retentionDays days / $retentionMaxCnt count / ${retentionMaxMB} MB)" -ForegroundColor Cyan
 Write-Host "[guard] Log: $logFilePath" -ForegroundColor Cyan
 Write-Host ""
 
@@ -226,63 +289,64 @@ try {
         $dirty = git status --porcelain 2>$null
         if (-not $dirty) { continue }
 
-        try {
-            # Use a temporary index file — the main index and branch are never touched
-            $env:GIT_INDEX_FILE = $guardIndex
-
-            # Seed temp index from the current backup-branch tree
-            $parentHash = git rev-parse --verify $branchRef 2>$null
-            if ($parentHash) { git read-tree $branchRef 2>$null }
-
-            # Stage protected files from the working tree into temp index
-            if ($protectPatterns.Count -gt 0) {
-                foreach ($p in $protectPatterns) { git add -- $p 2>$null }
-            } else {
-                git add -A 2>$null
-            }
-            foreach ($ig in $ignorePatterns) {
-                git rm --cached --ignore-unmatch -rq -- $ig 2>$null
-            }
+        # ── Git branch snapshot ──────────────────────────────────
+        if ($backupStrategy -eq "git" -or $backupStrategy -eq "both") {
+            try {
+                $env:GIT_INDEX_FILE = $guardIndex
 
-            Remove-SecretsFromIndex
+                $parentHash = git rev-parse --verify $branchRef 2>$null
+                if ($parentHash) { git read-tree $branchRef 2>$null }
 
-            # Build tree object and compare with parent
-            $newTree    = git write-tree
-            $parentTree = if ($parentHash) { git rev-parse "${branchRef}^{tree}" 2>$null } else { $null }
-
-            if ($newTree -eq $parentTree) {
-                Write-Host "[guard] $(Get-Date -Format 'HH:mm:ss') tree unchanged, skipped." -ForegroundColor DarkGray
-                continue
-            }
-
-            # Create commit via plumbing — no checkout, no hooks, no branch switch
-            $ts  = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
-            $msg = "guard: auto-backup $ts"
-            $commitHash = if ($parentHash) {
-                git commit-tree $newTree -p $parentHash -m $msg
-            } else {
-                git commit-tree $newTree -m $msg
-            }
-            git update-ref $branchRef $commitHash
+                if ($protectPatterns.Count -gt 0) {
+                    foreach ($p in $protectPatterns) { git add -- $p 2>$null }
+                } else {
+                    git add -A 2>$null
+                }
+                foreach ($ig in $ignorePatterns) {
+                    git rm --cached --ignore-unmatch -rq -- $ig 2>$null
+                }
 
-            if (-not $commitHash) {
-                Write-Log "ERROR: commit-tree failed, snapshot skipped" Red
-                continue
+                Remove-SecretsFromIndex
+
+                $newTree    = git write-tree
+                $parentTree = if ($parentHash) { git rev-parse "${branchRef}^{tree}" 2>$null } else { $null }
+
+                if ($newTree -eq $parentTree) {
+                    Write-Host "[guard] $(Get-Date -Format 'HH:mm:ss') tree unchanged, skipped." -ForegroundColor DarkGray
+                } else {
+                    $ts  = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+                    $msg = "guard: auto-backup $ts"
+                    $commitHash = if ($parentHash) {
+                        git commit-tree $newTree -p $parentHash -m $msg
+                    } else {
+                        git commit-tree $newTree -m $msg
+                    }
+
+                    if (-not $commitHash) {
+                        Write-Log "ERROR: commit-tree failed, snapshot skipped" Red
+                    } else {
+                        git update-ref $branchRef $commitHash
+                        $short = $commitHash.Substring(0, 7)
+                        if ($parentTree) {
+                            $diff  = git diff-tree --no-commit-id --name-only -r $parentTree $newTree 2>$null
+                            $count = if ($diff) { @($diff).Count } else { 0 }
+                        } else {
+                            $all   = git ls-tree --name-only -r $newTree 2>$null
+                            $count = if ($all) { @($all).Count } else { 0 }
+                        }
+                        Write-Log "Git snapshot $short ($count files)"
+                    }
+                }
             }
-
-            $short = $commitHash.Substring(0, 7)
-            if ($parentTree) {
-                $diff  = git diff-tree --no-commit-id --name-only -r $parentTree $newTree 2>$null
-                $count = if ($diff) { @($diff).Count } else { 0 }
-            } else {
-                $all   = git ls-tree --name-only -r $newTree 2>$null
-                $count = if ($all) { @($all).Count } else { 0 }
+            finally {
+                $env:GIT_INDEX_FILE = $null
+                Remove-Item $guardIndex -Force -ErrorAction SilentlyContinue
             }
-            Write-Log "Snapshot $short ($count files)"
         }
-        finally {
-            $env:GIT_INDEX_FILE = $null
-            Remove-Item $guardIndex -Force -ErrorAction SilentlyContinue
+
+        # ── Shadow copy ──────────────────────────────────────────
+        if ($backupStrategy -eq "shadow" -or $backupStrategy -eq "both") {
+            Invoke-ShadowCopy | Out-Null
         }
 
         # Periodic retention cleanup every 10 cycles

package/references/recovery.md

@@ -34,21 +34,40 @@ git restore --source=<commit> -- <path/to/file>
 
 ## Undo uncommitted changes (entire repo) — **destructive**
 
+**Always preview first / 务必先预览：**
+
 ```bash
+# Step 1: Preview what will be reverted / 预览将要还原的内容
+git diff
+
+# Step 2: Preview what untracked files would be removed / 预览将被删除的未跟踪文件
+git clean -fdn   # dry-run: shows what WOULD be deleted
+
+# Step 3: Only after user confirms / 用户确认后再执行
 git restore .
-git clean -fd   # removes untracked files/dirs — DANGEROUS
 ```
 
-Only suggest `git clean -fd` if the user explicitly wants untracked removal; warn about data loss.
+Only suggest `git clean -fd` if the user explicitly wants untracked removal; warn about data loss:
+
+```bash
+# DANGEROUS: removes untracked files — only after explicit confirmation
+# 危险：删除未跟踪文件——仅在用户明确确认后执行
+git clean -fd
+```
 
 ## Recover "lost" commits / after reset
 
 ```bash
+# Step 1: Find the lost commit / 找到丢失的提交
 git reflog
-# find the commit hash, then:
+
+# Step 2: Create a recovery branch (safe, non-destructive) / 创建恢复分支（安全）
 git branch recover-branch <hash>
-# or (destructive — discards uncommitted work):
-git reset --hard <hash>
+
+# Step 3 (alternative): Hard reset — DESTRUCTIVE, preview first
+# 硬重置——破坏性操作，先预览
+git diff HEAD <hash> --stat   # preview what changes
+git reset --hard <hash>       # only after confirmation
 ```
 
 ## Restore deleted file from HEAD (if it was committed)
@@ -65,6 +84,98 @@ git stash list
 git stash pop
 ```
 
+## Restore to N minutes/hours ago / 恢复到 N 分钟/小时前
+
+The goal is to find the **latest commit AT or BEFORE** the target time.
+
+目标是找到目标时间点**之前（含）最近的一次提交**。
+
+```bash
+# Find the most recent commit BEFORE N minutes ago
+# 查找 N 分钟前之前最近的提交
+git log --oneline --before="5 minutes ago" -5 -- <file>
+
+# Find the most recent commit BEFORE N hours ago
+# 查找 N 小时前之前最近的提交
+git log --oneline --before="2 hours ago" -5 -- <file>
+
+# Reflog as fallback (captures resets, amends, etc.)
+# Reflog 作为兜底（能捕获 reset、amend 等操作）
+git reflog --before="5 minutes ago" -5
+
+# Restore file to the first (closest) commit found above
+# 恢复到上面找到的第一个（最近的）提交
+git restore --source=<commit-hash> -- <file>
+```
+
+## Restore to a specific time / 恢复到指定时间点
+
+```bash
+# Find the closest commit before a specific time
+# 查找指定时间点之前最近的提交
+git log --oneline --before="2026-03-21 15:00" -5 -- <file>
+git log --oneline --before="today 15:00" -5 -- <file>
+
+# Yesterday / 昨天
+git log --oneline --after="yesterday 00:00" --before="yesterday 23:59" -- <file>
+
+# Restore
+git restore --source=<commit-hash> -- <file>
+```
+
+## Restore to N versions ago / 恢复到前 N 个版本
+
+```bash
+# Show recent N commits for a file
+# 查看某文件最近 N 个提交
+git log --oneline -10 -- <file>
+
+# Restore to previous version (1 version ago)
+# 恢复到上一个版本
+git restore --source=HEAD~1 -- <file>
+
+# Restore to 3 versions ago
+# 恢复到前 3 个版本
+git restore --source=HEAD~3 -- <file>
+
+# Preview what the file looked like N versions ago (without restoring)
+# 预览 N 个版本前的文件内容（不实际恢复）
+git show HEAD~3:<file>
+
+# Diff current vs N versions ago
+# 对比当前和 N 个版本前的差异
+git diff HEAD~3 -- <file>
+```
+
+> **Note / 注意**: `HEAD~N` counts commits on the current branch. If you want the Nth commit that *changed this specific file*, use:
+>
+> `HEAD~N` 是按分支提交计数。如果想找第 N 次**修改该文件**的提交，用：
+>
+> ```bash
+> # Find the 3rd most recent commit that touched this file
+> git log --oneline -3 -- <file>
+> # Then use the hash from the output
+> git restore --source=<hash> -- <file>
+> ```
+
+## Restore entire project to a point in time / 恢复整个项目到某个时间点
+
+```bash
+# CAUTION: This affects ALL files. Review carefully!
+# 注意：这会影响所有文件，请仔细检查！
+
+# Step 1: Find the target commit / 第一步：找到目标提交
+git log --oneline --before="10 minutes ago" -5
+
+# Step 2: Preview what will change / 第二步：预览变更
+git diff <commit-hash> -- .
+
+# Step 3: Restore (after confirmation) / 第三步：恢复（确认后）
+git restore --source=<commit-hash> -- .
+```
+
+---
+
 ## Recover from auto-backup branch
 
 The `auto-backup.ps1` script stores periodic snapshots on a dedicated branch via plumbing commands:
@@ -81,6 +192,14 @@ git restore --source=<commit-hash> -- <path/to/file>
 
 # Diff your working copy against the auto-backup version
 git diff cursor-guard/auto-backup -- <path/to/file>
+
+# Time-based: find auto-backup snapshot from before N minutes ago
+# 按时间查找：N 分钟前之前最近的自动备份快照
+git log cursor-guard/auto-backup --oneline --before="5 minutes ago" -5 -- <path/to/file>
+
+# Version-based: list recent N auto-backup snapshots
+# 按版本查找：最近 N 个自动备份快照
+git log cursor-guard/auto-backup --oneline -10 -- <path/to/file>
 ```
 
 ## If not a Git repo yet
@@ -100,11 +219,20 @@ This does **not** recover past work from before `init`.
 If `.cursor-guard-backup/` exists, find snapshots:
 
 ```powershell
-# List all backup timestamps
+# List all backup timestamps / 列出所有备份时间戳
 Get-ChildItem .cursor-guard-backup/ -Directory | Sort-Object Name -Descending
 
-# Restore a specific file from a timestamp
+# Restore a specific file from a timestamp / 从某个时间戳恢复文件
 Copy-Item ".cursor-guard-backup/<timestamp>/<filename>" "<original-path>"
+
+# Find the closest shadow copy to N minutes ago / 查找 N 分钟前最近的影子拷贝
+$target = (Get-Date).AddMinutes(-5)
+Get-ChildItem .cursor-guard-backup/ -Directory |
+    Where-Object { $_.Name -match '^\d{8}_\d{6}$' } |
+    ForEach-Object {
+        $dt = [datetime]::ParseExact($_.Name, "yyyyMMdd_HHmmss", $null)
+        [PSCustomObject]@{ Name = $_.Name; Time = $dt; Diff = [math]::Abs(($dt - $target).TotalSeconds) }
+    } | Sort-Object Diff | Select-Object -First 3
 ```
 
 ---