cursor-guard 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +154 -41
- package/package.json +28 -28
package/README.md
CHANGED
|
@@ -2,45 +2,136 @@
|
|
|
2
2
|
|
|
3
3
|
Protects your code from accidental AI overwrite or deletion in [Cursor](https://cursor.com).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
保护你的代码免受 [Cursor](https://cursor.com) AI 代理意外覆写或删除。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## What It Does / 功能介绍
|
|
6
10
|
|
|
7
11
|
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:
|
|
8
12
|
|
|
9
|
-
|
|
10
|
-
- **Read before Write** — The agent must read a file before overwriting it
|
|
11
|
-
- **Review before apply** — Diff previews and explicit confirmation for dangerous ops
|
|
12
|
-
- **Deterministic recovery** — Clear priority-ordered recovery paths (Git → shadow copies → conversation context → editor history)
|
|
13
|
-
- **Configurable scope** — Protect only what matters via `.cursor-guard.json`
|
|
14
|
-
- **Secrets filtering** — Sensitive files (`.env`, keys, certificates) are auto-excluded from backups
|
|
15
|
-
- **Auto-backup script** — A PowerShell watcher that periodically snapshots to a dedicated Git branch without disturbing your working tree
|
|
13
|
+
当 Cursor 的 AI 代理编辑你的文件时，可能会意外覆盖、删除或丢失代码。**Cursor Guard** 强制执行一套安全协议：
|
|
16
14
|
|
|
17
|
-
|
|
15
|
+
- **Mandatory pre-write snapshots / 强制写前快照** — Git commit or shadow copy before any destructive operation / 在任何破坏性操作前自动 Git 提交或影子拷贝
|
|
16
|
+
- **Read before Write / 先读后写** — The agent must read a file before overwriting it / 代理必须先读取文件内容，才能覆写
|
|
17
|
+
- **Review before apply / 预览再执行** — Diff previews and explicit confirmation for dangerous ops / 危险操作前展示 diff 预览并要求确认
|
|
18
|
+
- **Deterministic recovery / 确定性恢复** — Clear priority-ordered recovery paths (Git → shadow copies → conversation context → editor history) / 按优先级的恢复路径（Git → 影子拷贝 → 对话上下文 → 编辑器历史）
|
|
19
|
+
- **Configurable scope / 可配置保护范围** — Protect only what matters via `.cursor-guard.json` / 通过配置文件只保护你关心的文件
|
|
20
|
+
- **Secrets filtering / 敏感文件过滤** — Sensitive files (`.env`, keys, certificates) are auto-excluded from backups / `.env`、密钥、证书等敏感文件自动排除
|
|
21
|
+
- **Auto-backup script / 自动备份脚本** — A PowerShell watcher that periodically snapshots to a dedicated Git branch without disturbing your working tree / 定期快照到独立 Git 分支，不干扰工作区
|
|
18
22
|
|
|
19
|
-
|
|
23
|
+
---
|
|
20
24
|
|
|
21
|
-
|
|
25
|
+
## Installation / 安装
|
|
22
26
|
|
|
27
|
+
### Method 1: npm install / 方式一：npm 安装
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install cursor-guard
|
|
23
31
|
```
|
|
24
|
-
|
|
32
|
+
|
|
33
|
+
After installation, copy the skill files to your Cursor skills directory:
|
|
34
|
+
|
|
35
|
+
安装后，将技能文件复制到 Cursor 技能目录：
|
|
36
|
+
|
|
37
|
+
**Windows (PowerShell):**
|
|
38
|
+
|
|
39
|
+
```powershell
|
|
40
|
+
# Global installation (all projects) / 全局安装（所有项目生效）
|
|
41
|
+
Copy-Item -Recurse node_modules/cursor-guard "$env:USERPROFILE/.cursor/skills/cursor-guard"
|
|
42
|
+
|
|
43
|
+
# Per-project installation / 项目级安装（仅当前项目生效）
|
|
44
|
+
Copy-Item -Recurse node_modules/cursor-guard .cursor/skills/cursor-guard
|
|
25
45
|
```
|
|
26
46
|
|
|
27
|
-
|
|
47
|
+
**macOS / Linux:**
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
# Global installation / 全局安装
|
|
51
|
+
cp -r node_modules/cursor-guard ~/.cursor/skills/cursor-guard
|
|
52
|
+
|
|
53
|
+
# Per-project installation / 项目级安装
|
|
54
|
+
cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
After copying, you can remove the npm dependency if you don't need it in `node_modules`:
|
|
58
|
+
|
|
59
|
+
复制完成后，如果不需要保留在 `node_modules` 中，可以卸载：
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npm uninstall cursor-guard
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Method 2: Git clone / 方式二：Git 克隆
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
# Global installation / 全局安装
|
|
69
|
+
git clone https://github.com/zhangqiang8vipp/cursor-guard.git ~/.cursor/skills/cursor-guard
|
|
70
|
+
|
|
71
|
+
# Per-project installation / 项目级安装
|
|
72
|
+
git clone https://github.com/zhangqiang8vipp/cursor-guard.git .cursor/skills/cursor-guard
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Method 3: Manual download / 方式三：手动下载
|
|
76
|
+
|
|
77
|
+
Download from [GitHub Releases](https://github.com/zhangqiang8vipp/cursor-guard/releases) and extract to:
|
|
78
|
+
|
|
79
|
+
从 [GitHub Releases](https://github.com/zhangqiang8vipp/cursor-guard/releases) 下载并解压到：
|
|
28
80
|
|
|
29
81
|
```
|
|
30
|
-
|
|
82
|
+
~/.cursor/skills/cursor-guard/ # Global / 全局
|
|
83
|
+
<project-root>/.cursor/skills/cursor-guard/ # Per-project / 项目级
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Verify Installation / 验证安装
|
|
87
|
+
|
|
88
|
+
After installation, your directory structure should look like this / 安装后目录结构应如下所示：
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
.cursor/skills/cursor-guard/
|
|
92
|
+
├── SKILL.md # AI agent instructions / AI 代理指令
|
|
93
|
+
├── README.md
|
|
94
|
+
├── LICENSE
|
|
95
|
+
└── references/
|
|
96
|
+
├── auto-backup.ps1 # Auto-backup script / 自动备份脚本
|
|
97
|
+
├── recovery.md # Recovery commands / 恢复命令
|
|
98
|
+
├── cursor-guard.example.json # Example config / 示例配置
|
|
99
|
+
└── cursor-guard.schema.json # Config schema / 配置 Schema
|
|
31
100
|
```
|
|
32
101
|
|
|
33
102
|
The skill activates automatically when the AI agent detects risky operations (file edits, deletes, renames) or when you mention recovery-related terms.
|
|
34
103
|
|
|
35
|
-
|
|
104
|
+
技能会在 AI 代理检测到高风险操作（文件编辑、删除、重命名）或你提到恢复相关词汇时自动激活。无需其他设置，安装即生效。
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## Quick Start / 快速上手
|
|
36
109
|
|
|
37
|
-
|
|
110
|
+
1. **Install the skill** using any method above / 用以上任意方式安装技能
|
|
111
|
+
|
|
112
|
+
2. **Open Cursor** and start an Agent conversation / 打开 Cursor，开始一个 Agent 对话
|
|
113
|
+
|
|
114
|
+
3. **The skill works automatically** — when the AI agent tries to edit files, it will: / 技能自动生效——当 AI 代理尝试编辑文件时，会自动：
|
|
115
|
+
- Create a Git snapshot before writing / 写入前创建 Git 快照
|
|
116
|
+
- Read files before overwriting / 覆写前先读取文件
|
|
117
|
+
- Show diff previews for dangerous operations / 危险操作前展示 diff 预览
|
|
118
|
+
- Report a status block after each protected operation / 每次受保护操作后报告状态
|
|
119
|
+
|
|
120
|
+
4. **(Optional) Add project config** to customize protection scope / （可选）添加项目配置自定义保护范围：
|
|
38
121
|
|
|
39
122
|
```bash
|
|
40
123
|
cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guard.json
|
|
41
124
|
```
|
|
42
125
|
|
|
43
|
-
|
|
126
|
+
5. **(Optional) Run auto-backup** in a separate terminal / （可选）在独立终端运行自动备份：
|
|
127
|
+
|
|
128
|
+
```powershell
|
|
129
|
+
.\auto-backup.ps1 -Path "D:\MyProject"
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Project Configuration / 项目配置
|
|
133
|
+
|
|
134
|
+
Edit `.cursor-guard.json` to define which files to protect / 编辑 `.cursor-guard.json` 定义保护哪些文件：
|
|
44
135
|
|
|
45
136
|
```json
|
|
46
137
|
{
|
|
@@ -52,54 +143,76 @@ Edit `.cursor-guard.json` to define which files to protect:
|
|
|
52
143
|
}
|
|
53
144
|
```
|
|
54
145
|
|
|
55
|
-
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Auto-Backup Script / 自动备份脚本
|
|
56
149
|
|
|
57
150
|
Run in a separate terminal while working in Cursor:
|
|
58
151
|
|
|
152
|
+
在使用 Cursor 时，在**单独的终端窗口**中运行：
|
|
153
|
+
|
|
59
154
|
```powershell
|
|
60
155
|
.\auto-backup.ps1 -Path "D:\MyProject"
|
|
61
156
|
|
|
62
|
-
# Custom interval (default 60s)
|
|
157
|
+
# Custom interval (default 60s) / 自定义间隔（默认 60 秒）：
|
|
63
158
|
.\auto-backup.ps1 -Path "D:\MyProject" -IntervalSeconds 30
|
|
64
159
|
```
|
|
65
160
|
|
|
66
161
|
The script uses Git plumbing commands to snapshot to `cursor-guard/auto-backup` branch — it never switches branches or touches your working index.
|
|
67
162
|
|
|
68
|
-
|
|
163
|
+
脚本使用 Git 底层命令快照到 `cursor-guard/auto-backup` 分支——不会切换分支，也不会影响你的工作索引。
|
|
164
|
+
|
|
165
|
+
> **Note / 注意**: Run this script in a separate PowerShell window, NOT inside Cursor's integrated terminal. Cursor's terminal may interfere with Git plumbing commands.
|
|
166
|
+
>
|
|
167
|
+
> 请在独立的 PowerShell 窗口中运行此脚本，不要在 Cursor 的集成终端中运行，因为 Cursor 终端可能干扰 Git 底层命令。
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Recovery / 恢复
|
|
69
172
|
|
|
70
173
|
If something goes wrong, recovery follows this priority:
|
|
71
174
|
|
|
175
|
+
出问题时，按以下优先级恢复：
|
|
176
|
+
|
|
72
177
|
1. **Git** — `git restore`, `git reset`, `git reflog`
|
|
73
|
-
2. **Shadow copies
|
|
74
|
-
3. **Conversation context
|
|
75
|
-
4. **Editor history
|
|
178
|
+
2. **Shadow copies / 影子拷贝** — `.cursor-guard-backup/<timestamp>/`
|
|
179
|
+
3. **Conversation context / 对话上下文** — Original file content captured by agent Read calls / 代理 Read 调用捕获的原始内容
|
|
180
|
+
4. **Editor history / 编辑器历史** — VS Code/Cursor Timeline (auxiliary / 辅助)
|
|
181
|
+
|
|
182
|
+
See [references/recovery.md](references/recovery.md) for detailed commands / 详细命令见恢复文档。
|
|
76
183
|
|
|
77
|
-
|
|
184
|
+
---
|
|
78
185
|
|
|
79
|
-
## Trigger Keywords
|
|
186
|
+
## Trigger Keywords / 触发关键词
|
|
80
187
|
|
|
81
|
-
The skill activates on these signals
|
|
188
|
+
The skill activates on these signals / 技能在以下信号时激活：
|
|
82
189
|
|
|
83
|
-
- File edits, deletes, renames by the AI agent
|
|
84
|
-
- Recovery requests
|
|
85
|
-
- History issues
|
|
190
|
+
- File edits, deletes, renames by the AI agent / AI 代理的文件编辑、删除、重命名
|
|
191
|
+
- Recovery requests / 恢复请求："回滚"、"误删"、"丢版本"、"rollback"、"undo"、"recover"
|
|
192
|
+
- History issues / 历史问题：checkpoints missing、Timeline not working、save failures
|
|
86
193
|
|
|
87
|
-
|
|
194
|
+
---
|
|
88
195
|
|
|
89
|
-
|
|
196
|
+
## Files / 文件说明
|
|
197
|
+
|
|
198
|
+
| File / 文件 | Purpose / 用途 |
|
|
90
199
|
|------|---------|
|
|
91
|
-
| `SKILL.md` | Main skill instructions for the AI agent |
|
|
92
|
-
| `references/auto-backup.ps1` | PowerShell auto-backup watcher script |
|
|
93
|
-
| `references/recovery.md` | Recovery command templates |
|
|
94
|
-
| `references/cursor-guard.example.json` | Example project configuration |
|
|
95
|
-
| `references/cursor-guard.schema.json` | JSON Schema for config validation |
|
|
200
|
+
| `SKILL.md` | Main skill instructions for the AI agent / AI 代理的主要技能指令 |
|
|
201
|
+
| `references/auto-backup.ps1` | PowerShell auto-backup watcher script / PowerShell 自动备份监控脚本 |
|
|
202
|
+
| `references/recovery.md` | Recovery command templates / 恢复命令模板 |
|
|
203
|
+
| `references/cursor-guard.example.json` | Example project configuration / 示例项目配置 |
|
|
204
|
+
| `references/cursor-guard.schema.json` | JSON Schema for config validation / 配置文件的 JSON Schema |
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## Requirements / 环境要求
|
|
96
209
|
|
|
97
|
-
|
|
210
|
+
- **Git** — for primary backup strategy / 主要备份策略
|
|
211
|
+
- **PowerShell 5.1+** — for auto-backup script (Windows built-in) / 自动备份脚本（Windows 自带）
|
|
212
|
+
- **Cursor IDE** — with Agent mode enabled / 需启用 Agent 模式
|
|
98
213
|
|
|
99
|
-
|
|
100
|
-
- **PowerShell 5.1+** (for auto-backup script; Windows built-in)
|
|
101
|
-
- **Cursor IDE** with Agent mode enabled
|
|
214
|
+
---
|
|
102
215
|
|
|
103
|
-
## License
|
|
216
|
+
## License / 许可证
|
|
104
217
|
|
|
105
218
|
MIT
|
package/package.json
CHANGED
|
@@ -1,29 +1,29 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "cursor-guard",
|
|
3
|
+
"version": "1.0.1",
|
|
4
|
+
"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 安全网、确定性恢复。",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"cursor",
|
|
7
|
+
"cursor-ide",
|
|
8
|
+
"ai-safety",
|
|
9
|
+
"code-protection",
|
|
10
|
+
"git-backup",
|
|
11
|
+
"snapshot",
|
|
12
|
+
"recovery",
|
|
13
|
+
"agent-skill"
|
|
14
|
+
],
|
|
15
|
+
"author": "zhangqiang8vipp",
|
|
16
|
+
"license": "MIT",
|
|
17
|
+
"repository": {
|
|
18
|
+
"type": "git",
|
|
19
|
+
"url": "https://github.com/zhangqiang8vipp/cursor-guard.git"
|
|
20
|
+
},
|
|
21
|
+
"homepage": "https://github.com/zhangqiang8vipp/cursor-guard",
|
|
22
|
+
"files": [
|
|
23
|
+
"SKILL.md",
|
|
24
|
+
"README.md",
|
|
25
|
+
"LICENSE",
|
|
26
|
+
"references/"
|
|
27
|
+
],
|
|
28
|
+
"main": "SKILL.md"
|
|
29
29
|
}
|