cursor-guard 1.0.1 → 1.3.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,109 @@ 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.
+
+**Default behavior**: Before any restore, the agent automatically preserves your current version so you can undo the restore if needed. You don't need to ask for this — it happens by default. To skip, explicitly say "don't preserve current version" or "skip backup before restore".
 
-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:
+1. **Preserve your current version** first (unless you opt out)
+2. Search Git history and auto-backup snapshots
+3. Show matching versions for you to choose
+4. Restore after your confirmation
+5. Report both the pre-restore backup ref and the restore result
+
+If the pre-restore backup fails, the agent will **not** proceed — it will wait for your explicit confirmation before restoring without a safety net.
+
+### 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,246 @@
+# 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 恢复到上一个版本"
+
+代理会：
+1. **先保留你的当前版本**（除非你明确选择跳过）
+2. 搜索 Git 历史和自动备份快照
+3. 列出匹配版本供你选择
+4. 确认后执行恢复
+5. 报告恢复前备份引用和恢复结果
+
+如果保留当前版本失败，代理**不会**继续恢复——会等你明确确认后才会在没有安全网的情况下恢复。
+
+### 恢复优先级
+
+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