cursor-guard 4.9.1 → 4.9.6

package/README.md

@@ -21,11 +21,17 @@ When Cursor's AI agent edits your files, there's a risk of accidental overwrites
 - **Secrets filtering** — Sensitive files (`.env`, keys, certificates) are auto-excluded from backups
 - **Auto-backup script** — A cross-platform watcher (Node.js) that periodically snapshots to a dedicated Git branch without disturbing your working tree
 - **MCP tool calls (optional)** — 9 structured tools (diagnostics, snapshot, restore, status, dashboard, alerts, etc.) with JSON responses and lower token cost
-- **Auto-fix diagnostics** — `doctor_fix` automatically patches missing configs, uninitialized Git repos, gitignore gaps, and stale locks
-- **Proactive change-velocity alerts (V4)** — Auto-detects abnormal file change patterns and raises risk warnings
-- **Backup health dashboard (V4)** — One-call comprehensive view: strategy, counts, disk usage, protection scope, health status
-- **Web dashboard (V4.2)** — Local read-only web UI at `http://127.0.0.1:3120` — see health, backups, restore points, diagnostics, protection scope at a glance. Dual-language (zh-CN / en-US), auto-refresh every 15s, multi-project support
+- **Auto-fix diagnostics** — `doctor_fix` automatically patches missing configs, uninitialized Git repos, gitignore gaps, and stale locks
+- **Proactive change-velocity alerts (V4)** — Auto-detects abnormal file change patterns and raises risk warnings
+- **Pre-warning destructive edit guard (V4.9.6)** — Detects risky partial deletions before they quietly stick, with `popup` / `dashboard` / `silent` modes in the IDE
+- **Backup health dashboard (V4)** — One-call comprehensive view: strategy, counts, disk usage, protection scope, health status
+- **Web dashboard (V4.2)** — Local read-only web UI at `http://127.0.0.1:3120` — see health, backups, restore points, diagnostics, protection scope at a glance. Dual-language (zh-CN / en-US), auto-refresh, multi-project support
 - **IDE extension (V4.7)** — Full dashboard embedded in VSCode/Cursor/Windsurf as a WebView tab + status bar alert indicator + sidebar project tree. No browser needed
+- **Event-driven watching (V4.9)** — `fs.watch` + debounce replaces blind polling. Backup latency < 500ms, zero CPU when idle. Automatic fallback to polling on unsupported platforms
+- **Right-click context menus (V4.7.7)** — Add files/folders to `protect` or `ignore` lists via Explorer/Editor right-click menu with pattern picker
+- **Real-time sidebar (V4.9.1)** — "Last backup Xs ago" and alert countdown tick every second in the sidebar dashboard
+- **Smart restore for deleted files (V4.8.4)** — Restore commands auto-point to parent commit (`hash~1`) when file was deleted in the snapshot, preventing "file not found" errors
+- **Self-contained VSIX (V4.8.1)** — MCP server bundled as a single file via esbuild, zero npm dependencies needed for IDE extension
 - **One-click hot restart (V4.5.8)** — Dashboard detects new versions and offers in-place server restart without losing state
 - **Shadow incremental hard links (V4.5.4)** — Unchanged files are hard-linked to save disk space and I/O
 - **Strong protection mode (V4.5.4)** — `always_watch: true` auto-starts watcher with MCP server, ensuring zero protection gaps
@@ -118,8 +124,9 @@ After installation, your directory structure should look like this:
     │       ├── backups.js              # Backup listing + retention
     │       ├── restore.js              # Single file / project restore
     │       ├── status.js               # Backup system status
-    │       ├── anomaly.js             # V4: Change-velocity detection
-    │       └── dashboard.js           # V4: Health dashboard aggregation
+    │       ├── anomaly.js             # V4: Change-velocity detection
+    │       ├── pre-warning.js         # V4.9.6: destructive edit risk scoring + persistence
+    │       └── dashboard.js           # V4: Health dashboard aggregation
     ├── dashboard/
     │   ├── server.js                   # Dashboard HTTP server + API
     │   └── public/                     # Web UI (HTML/CSS/JS)
@@ -194,15 +201,21 @@ npx cursor-guard-backup --path /my/project
 Edit `.cursor-guard.json` to define which files to protect:
 
 ```json
-{
-  "protect": ["src/**", "lib/**", "package.json"],
-  "ignore": ["node_modules/**", "dist/**"],
-  "auto_backup_interval_seconds": 60,
-  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
-  "pre_restore_backup": "always",
-  "retention": { "mode": "days", "days": 30 }
-}
-```
+{
+  "protect": ["src/**", "lib/**", "package.json"],
+  "ignore": ["node_modules/**", "dist/**"],
+  "auto_backup_interval_seconds": 60,
+  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+  "pre_restore_backup": "always",
+  "proactive_alert": true,
+  "alert_thresholds": { "files_per_window": 20, "window_seconds": 10, "cooldown_seconds": 60 },
+  "enable_pre_warning": true,
+  "pre_warning_threshold": 30,
+  "pre_warning_mode": "popup",
+  "pre_warning_exclude_patterns": ["generated/**"],
+  "retention": { "mode": "days", "days": 30 }
+}
+```
 
 #### `pre_restore_backup` — restore behavior control
 
@@ -212,9 +225,22 @@ Edit `.cursor-guard.json` to define which files to protect:
 | `"ask"` | Prompt you each time: "Preserve current version before restore? (Y/n)" — you decide per restore. |
 | `"never"` | Never preserve current version before restore (not recommended). |
 
-Regardless of config, you can always override per-request:
-- Say "don't preserve current version" to skip even when config is `"always"`
-- Say "preserve current first" to force even when config is `"never"`
+Regardless of config, you can always override per-request:
+- Say "don't preserve current version" to skip even when config is `"always"`
+- Say "preserve current first" to force even when config is `"never"`
+
+#### `enable_pre_warning` — destructive partial-delete pre-warning
+
+When enabled, the IDE extension evaluates edits that remove lines or whole methods/functions before they slip by unnoticed.
+
+| Field | Default | Meaning |
+|-------|---------|---------|
+| `enable_pre_warning` | `false` | Turn pre-warning on without affecting existing projects |
+| `pre_warning_threshold` | `30` | Warn when deletion risk reaches this percent |
+| `pre_warning_mode` | `"popup"` | `popup` = interrupt with actions, `dashboard` = highlight only, `silent` = log/status only |
+| `pre_warning_exclude_patterns` | `[]` | Skip generated files, migrations, vendored code, etc. |
+
+Method/function removal is treated as high risk and can still trigger a warning even when the deleted-line percentage is below the threshold.
 
 ---
 
@@ -309,8 +335,8 @@ node build-vsix.js
 cd dist
 npx vsce package
 
-# Install the generated .vsix file
-code --install-extension cursor-guard-ide-4.7.5.vsix
+# Install the generated .vsix file (or download from GitHub Releases)
+code --install-extension cursor-guard-ide-4.9.6.vsix
 ```
 
 On first activation, the extension automatically:
@@ -330,9 +356,13 @@ Features:
 - **WebView Dashboard** — full dashboard embedded as an editor tab, identical to the browser version
 - **Status Bar Indicator** — shows `Guard: OK` (green) or `Guard: 22 files!` (yellow) in real-time
 - **Sidebar TreeView** — activity bar icon with project list, watcher status, backup stats, alerts, health
-- **Visual Sidebar** — graphical dashboard with progress bars, status badges, backup timeline in sidebar
-- **Command Palette** — `Cursor Guard: Open Dashboard`, `Snapshot Now`, `Start Watcher`, `Refresh`
+- **Visual Sidebar** — graphical dashboard with live-ticking backup age, alert countdown, protection scope, quick stats
+- **Pre-warning delete guard** — flags risky partial deletions, removed methods, and suspicious line drops before they quietly stick
+- **Command Palette** — `Open Dashboard`, `Snapshot Now`, `Start/Stop Watcher`, `Quick Restore`, `Doctor`, `Refresh`
+- **Right-click menus** — add files/folders to `protect` or `ignore` via Explorer/Editor context menu
+- **Event-driven refresh** — `FileSystemWatcher` pushes UI updates on file changes (< 1.5s latency), 30s heartbeat fallback
 - **Auto-setup (V4.7.5)** — auto-detects IDE type, installs Skill, registers MCP, creates config on first run
+- **Self-contained (V4.8.1)** — MCP server bundled via esbuild, zero npm dependencies
 - **Multi-project** — hot-loads all workspace folders with `.cursor-guard.json`
 - **Compatible** — works with VSCode ^1.74.0, Cursor, Windsurf, Trae, and all VSCode-based IDEs
 
@@ -405,7 +435,7 @@ The skill activates on these signals:
 |------|---------|
 | `SKILL.md` | Main skill instructions for the AI agent (with MCP dual-path) |
 | `ROADMAP.md` | Version evolution roadmap (V2-V7) |
-| `references/lib/core/` | Core layer: 8 pure-logic modules (doctor / doctor-fix / snapshot / backups / restore / status / anomaly / dashboard) |
+| `references/lib/core/` | Core layer: 9 pure-logic modules (doctor / doctor-fix / snapshot / backups / restore / status / anomaly / pre-warning / dashboard) |
 | `references/mcp/server.js` | MCP Server: 9 structured tools (optional) |
 | `references/lib/auto-backup.js` | Auto-backup watcher (calls Core) |
 | `references/lib/guard-doctor.js` | Health check CLI shell (calls Core) |
@@ -425,7 +455,42 @@ The skill activates on these signals:
 
 ---
 
-## Changelog
+## Changelog
+
+### v4.9.6 — Pre-Warning for Destructive Partial Deletes
+
+- **Feature**: Added configurable `pre_warning` support in `.cursor-guard.json` — `enable_pre_warning`, `pre_warning_threshold`, `pre_warning_mode`, `pre_warning_exclude_patterns`
+- **Feature**: IDE extension now detects risky line/method removals and can react in `popup`, `dashboard`, or `silent` mode
+- **Feature**: `backup_status`, `dashboard`, sidebar, status bar, and browser dashboard surface active delete-risk warnings
+- **Improve**: New `pre-warning.js` core module centralizes deletion-risk scoring, active-warning persistence, and warning history
+- **Docs**: README, skill guide, roadmap, and config references now document the pre-warning flow end-to-end
+
+### v4.9.0–v4.9.1 — Event-Driven Architecture
+
+- **Architecture**: Watcher (`auto-backup.js`) rewritten from `while+sleep` polling to `fs.watch` event-driven with 500ms debounce. Zero CPU when idle, backup latency < 500ms
+- **Fallback**: Automatic degradation to polling mode if `fs.watch` is unavailable (e.g. older Linux kernels)
+- **Config hot-reload**: `.cursor-guard.json` changes trigger instant config reload via `fs.watch` event (no more waiting 10 polling cycles)
+- **IDE FileSystemWatcher**: Extension uses VSCode built-in `createFileSystemWatcher` to push UI updates on file changes (1.5s debounce)
+- **Poller heartbeat**: Reduced from 5s fixed interval to 30s heartbeat; UI updates are now event-driven
+- **Live sidebar counters**: "Last backup Xs ago" ticks every second in real-time (v4.9.1)
+
+### v4.8.0–v4.8.5 — Bundling, Doctor Fixes, Restore UX
+
+- **Fix**: MCP server bundled as single self-contained file via esbuild — eliminates all transitive dependency issues (`zod-to-json-schema`, `ajv`, etc.) (v4.8.1)
+- **Fix**: `doctor` MCP check no longer false-warns when cursor-guard is configured in `.cursor/mcp.json` (v4.8.2)
+- **Fix**: Skill directory `references/` now auto-creates junction link to extension runtime files on every activation (v4.8.2)
+- **Fix**: Deleted file restore commands auto-point to parent commit (`hash~1`), preventing "file not found" errors. Button shows "Restore pre-delete" with orange styling (v4.8.4)
+- **Fix**: Files outside `protect` scope no longer appear as phantom "deleted" in change summaries (v4.8.5)
+- **Improve**: VSIX package reduced from 3.18 MB to 1.27 MB thanks to esbuild bundling
+
+### v4.7.6–v4.7.9 — Sidebar Redesign, Context Menus, Protection Scope
+
+- **Feature**: Right-click context menus — add files/folders to `protect` or `ignore` via Explorer/Editor menus with pattern picker (v4.7.7)
+- **Feature**: Protection scope card in sidebar — shows protected/excluded file counts, actual protect/ignore patterns (v4.7.8)
+- **Feature**: Alert countdown ticks live every second in sidebar (v4.7.8)
+- **Fix**: Open Dashboard CORS/CSP issues — added `Access-Control-Allow-Origin`, relaxed CSP, fallback to browser on WebView failure (v4.7.8)
+- **Fix**: `protect` patterns now use strict matching (full path only, no basename fallback) for consistency (v4.7.8)
+- **Redesign**: Sidebar dashboard simplified — single status indicator, 2x2 action button grid, streamlined Quick Stats, removed clutter (v4.7.6)
 
 ### v4.7.5 — VSIX Self-Contained Build + Auto-Setup
 
@@ -462,7 +527,7 @@ The skill activates on these signals:
 - **Feature**: Dashboard version detection + one-click hot restart (`/api/restart` endpoint)
 - **Feature**: File detail modal with per-file restore command copy buttons
 - **Feature**: `cursor-guard-init` auto-creates `.cursor-guard.json`; `backup_interval_seconds` alias supported
-- **License**: Changed from MIT to BSL 1.1 (source available, commercial use requires author authorization)
+- **License**: Changed to BSL 1.1
 
 ### v4.4.0 — V4 Final
 
@@ -541,8 +606,9 @@ The skill activates on these signals:
 - **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 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 in a **separate terminal window**.
+- **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`).
+- **Pre-warning scope**: `pre_warning` is currently an editor/extension-side "last brake", not a universal cross-process write blocker. Headless shell / MCP flows surface it through status and dashboard after detection rather than hard-blocking writes.
+- **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 in a **separate terminal 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
@@ -565,4 +631,4 @@ This is an independent open-source project maintained by a solo developer. If Cu
 
 ## License
 
-[BSL 1.1 (Business Source License)](LICENSE) — Source code is freely available for viewing, modification, and non-commercial use. Commercial use requires authorization from the author. Auto-converts to Apache 2.0 on 2056-03-22.
+[BSL 1.1](LICENSE)

package/README.zh-CN.md

@@ -22,10 +22,16 @@
 - **自动备份脚本** — 跨平台 (Node.js) 定期快照到独立 Git 分支，不干扰工作区
 - **MCP 工具调用（可选）** — 9 个标准化工具（诊断、快照、恢复、状态、看板、告警等），结构化 JSON 返回，低 token 消耗
 - **自动诊断修复** — `doctor_fix` 一键修补缺失配置、未初始化 Git、gitignore 遗漏等常见问题
-- **主动变更频率告警（V4）** — 自动检测异常文件变更模式并发出风险预警
-- **备份健康看板（V4）** — 一次调用全面查看：策略、数量、磁盘占用、保护范围、健康状态
-- **Web 仪表盘（V4.2）** — 本地只读 Web 页面 `http://127.0.0.1:3120`——健康状态、备份、恢复点、诊断、保护范围一目了然。中英双语、每 15 秒自动刷新、支持多项目监控
+- **主动变更频率告警（V4）** — 自动检测异常文件变更模式并发出风险预警
+- **事先预警删除风险（V4.9.6）** — 在危险的局部删除真正“悄悄生效”前先提醒你，支持 `popup` / `dashboard` / `silent` 三种模式
+- **备份健康看板（V4）** — 一次调用全面查看：策略、数量、磁盘占用、保护范围、健康状态
+- **Web 仪表盘（V4.2）** — 本地只读 Web 页面 `http://127.0.0.1:3120`——健康状态、备份、恢复点、诊断、保护范围一目了然。中英双语、自动刷新、支持多项目监控
 - **IDE 扩展（V4.7）** — 完整仪表盘嵌入 VSCode/Cursor/Windsurf，WebView 标签页 + 状态栏告警指示器 + 侧边栏项目树。无需打开浏览器
+- **事件驱动监听（V4.9）** — `fs.watch` + 防抖替代盲轮询。备份延迟 < 500ms，空闲时零 CPU。不支持的平台自动降级为轮询
+- **右键上下文菜单（V4.7.7）** — 在资源管理器/编辑器右键菜单中将文件或文件夹添加到 `protect` 或 `ignore` 列表
+- **实时侧边栏（V4.9.1）** — "上次备份 Xs 前"和告警倒计时每秒跳动更新
+- **删除文件智能恢复（V4.8.4）** — 恢复命令自动指向父提交（`hash~1`），避免"文件不存在"错误
+- **自包含 VSIX（V4.8.1）** — MCP server 通过 esbuild 打包为单文件，IDE 扩展零 npm 依赖
 - **一键热重启（V4.5.8）** — 仪表盘检测到新版本时可原地重启服务，不丢失状态
 - **Shadow 增量硬链接（V4.5.4）** — 未变更文件硬链接到上次快照，节省磁盘空间和 I/O
 - **强保护模式（V4.5.4）** — `always_watch: true` 让 watcher 随 MCP server 自动启动，确保零保护缺口
@@ -118,8 +124,9 @@ git clone https://github.com/zhangqiang8vipp/cursor-guard.git .cursor/skills/cur
     │       ├── backups.js              # 备份列表 + 留存清理
     │       ├── restore.js              # 单文件/全项目恢复
     │       ├── status.js               # 备份系统状态
-    │       ├── anomaly.js             # V4：变更频率检测
-    │       └── dashboard.js           # V4：健康看板聚合
+    │       ├── anomaly.js             # V4：变更频率检测
+    │       ├── pre-warning.js         # V4.9.6：删除风险评分 + 持久化
+    │       └── dashboard.js           # V4：健康看板聚合
     ├── dashboard/
     │   ├── server.js                   # 仪表盘 HTTP 服务 + API
     │   └── public/                     # Web UI（HTML/CSS/JS）
@@ -196,13 +203,19 @@ npx cursor-guard-backup --path /my/project
 ```json
 {
   "protect": ["src/**", "lib/**", "package.json"],
-  "ignore": ["node_modules/**", "dist/**"],
-  "auto_backup_interval_seconds": 60,
-  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
-  "pre_restore_backup": "always",
-  "retention": { "mode": "days", "days": 30 }
-}
-```
+  "ignore": ["node_modules/**", "dist/**"],
+  "auto_backup_interval_seconds": 60,
+  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+  "pre_restore_backup": "always",
+  "proactive_alert": true,
+  "alert_thresholds": { "files_per_window": 20, "window_seconds": 10, "cooldown_seconds": 60 },
+  "enable_pre_warning": true,
+  "pre_warning_threshold": 30,
+  "pre_warning_mode": "popup",
+  "pre_warning_exclude_patterns": ["generated/**"],
+  "retention": { "mode": "days", "days": 30 }
+}
+```
 
 #### `pre_restore_backup` — 恢复前保留行为控制
 
@@ -212,9 +225,22 @@ npx cursor-guard-backup --path /my/project
 | `"ask"` | 每次恢复前询问你："恢复前是否保留当前版本？(Y/n)"——由你逐次决定。 |
 | `"never"` | 恢复前不保留当前版本（不推荐）。 |
 
-无论配置如何，你始终可以在单次请求中覆盖：
-- 说"不保留当前版本"可跳过保留（即使配置为 `"always"`）
-- 说"先保留当前版本"可强制保留（即使配置为 `"never"`）
+无论配置如何，你始终可以在单次请求中覆盖：
+- 说"不保留当前版本"可跳过保留（即使配置为 `"always"`）
+- 说"先保留当前版本"可强制保留（即使配置为 `"never"`）
+
+#### `enable_pre_warning` — 局部破坏性删除的事先预警
+
+开启后，IDE 扩展会在“删行很多”或“直接删掉方法/函数”这类高风险编辑发生时，先给出最后一道提醒。
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `enable_pre_warning` | `false` | 默认关闭，兼容旧项目 |
+| `pre_warning_threshold` | `30` | 删除风险达到这个百分比时触发预警 |
+| `pre_warning_mode` | `"popup"` | `popup` 弹窗拦一下，`dashboard` 仅高亮看板，`silent` 只记日志/状态 |
+| `pre_warning_exclude_patterns` | `[]` | 跳过生成文件、迁移脚本、第三方代码等 |
+
+如果检测到方法/函数被移除，即使删行比例没到阈值，也会按高风险处理并触发提醒。
 
 ---
 
@@ -309,8 +335,8 @@ node build-vsix.js
 cd dist
 npx vsce package
 
-# 安装生成的 .vsix 文件
-code --install-extension cursor-guard-ide-4.7.5.vsix
+# 安装生成的 .vsix 文件（或从 GitHub Releases 下载）
+code --install-extension cursor-guard-ide-4.9.6.vsix
 ```
 
 首次激活时，扩展自动：
@@ -330,9 +356,13 @@ code --install-extension .
 - **WebView 仪表盘** — 完整仪表盘作为编辑器标签页嵌入，与浏览器版本完全一致
 - **状态栏指示器** — 实时显示 `Guard: OK`（绿色）或 `Guard: 22 files!`（黄色告警）
 - **侧边栏 TreeView** — Activity Bar 图标，树形展示项目列表、Watcher 状态、备份统计、告警、健康评估
-- **可视化图表侧边栏** — 进度条、状态徽章、备份时间线等图形化展示
-- **命令面板** — `Cursor Guard: Open Dashboard`、`Snapshot Now`、`Start Watcher`、`Refresh`
+- **可视化图表侧边栏** — 备份时间实时跳动、告警倒计时、保护范围、Quick Stats
+- **事先预警删除保护** — 在局部删代码、删方法、可疑大段删行时提前亮警报
+- **命令面板** — `Open Dashboard`、`Snapshot Now`、`Start/Stop Watcher`、`Quick Restore`、`Doctor`、`Refresh`
+- **右键菜单** — 在资源管理器/编辑器右键菜单中将文件或文件夹添加到 `protect` 或 `ignore`
+- **事件驱动刷新** — `FileSystemWatcher` 监听文件变化推送 UI 更新（< 1.5s 延迟），30s 心跳兜底
 - **自动配置（V4.7.5）** — 首次运行自动检测 IDE 类型、安装 Skill、注册 MCP、创建配置
+- **自包含（V4.8.1）** — MCP server 通过 esbuild 打包，零 npm 依赖
 - **多项目** — 热加载所有包含 `.cursor-guard.json` 的工作区文件夹
 - **兼容性** — 支持 VSCode ^1.74.0、Cursor、Windsurf、Trae 及所有基于 VSCode 的 IDE
 
@@ -405,7 +435,7 @@ code --install-extension .
 |------|------|
 | `SKILL.md` | AI 代理的主要技能指令（含 MCP 双路径逻辑） |
 | `ROADMAP.md` | 版本演进规划书（V2-V7） |
-| `references/lib/core/` | Core 层：8 个纯逻辑模块（doctor / doctor-fix / snapshot / backups / restore / status / anomaly / dashboard） |
+| `references/lib/core/` | Core 层：9 个纯逻辑模块（doctor / doctor-fix / snapshot / backups / restore / status / anomaly / pre-warning / dashboard） |
 | `references/mcp/server.js` | MCP Server：9 个标准化工具（可选） |
 | `references/lib/auto-backup.js` | 自动备份 watcher（调用 Core） |
 | `references/lib/guard-doctor.js` | 健康检查 CLI 壳（调用 Core） |
@@ -425,7 +455,42 @@ code --install-extension .
 
 ---
 
-## 更新日志
+## 更新日志
+
+### v4.9.6 — 事先预警局部破坏性删除
+
+- **新功能**：`.cursor-guard.json` 新增 `enable_pre_warning`、`pre_warning_threshold`、`pre_warning_mode`、`pre_warning_exclude_patterns`
+- **新功能**：IDE 扩展现在会检测高风险删行 / 删方法，并支持 `popup`、`dashboard`、`silent` 三种预警模式
+- **新功能**：`backup_status`、`dashboard`、侧边栏、状态栏、浏览器仪表盘都会展示活跃的删除风险预警
+- **增强**：新增 `pre-warning.js` Core 模块，统一负责删除风险评分、活跃预警持久化和历史记录
+- **文档**：README、SKILL、ROADMAP 与配置说明已补齐预警功能说明
+
+### v4.9.0–v4.9.1 — 事件驱动架构
+
+- **架构重构**：Watcher（`auto-backup.js`）从 `while+sleep` 轮询重写为 `fs.watch` 事件驱动 + 500ms 防抖。空闲时零 CPU，备份延迟 < 500ms
+- **自动降级**：`fs.watch` 不可用时自动回退到轮询模式
+- **配置即时响应**：`.cursor-guard.json` 变化通过 `fs.watch` 事件直接触发热加载（不再等待 10 个轮询周期）
+- **IDE FileSystemWatcher**：扩展使用 VSCode 内置 `createFileSystemWatcher` 推送文件变化事件（1.5s 防抖）
+- **Poller 心跳**：从 5s 固定轮询改为 30s 心跳；UI 更新由事件驱动
+- **实时侧边栏计时**："上次备份 Xs 前"每秒跳动更新（v4.9.1）
+
+### v4.8.0–v4.8.5 — 打包修复、Doctor 优化、恢复 UX
+
+- **修复**：MCP server 通过 esbuild 打包为单个自包含文件——彻底解决传递依赖缺失问题（`zod-to-json-schema`、`ajv` 等）（v4.8.1）
+- **修复**：`doctor` MCP 检查不再在 `.cursor/mcp.json` 已配置 cursor-guard 时误报 WARN（v4.8.2）
+- **修复**：Skill 目录 `references/` 每次激活时自动创建 junction 链接到扩展运行时文件（v4.8.2）
+- **修复**：删除文件的恢复命令自动指向父提交（`hash~1`），避免"文件不存在"错误。按钮显示"恢复删除前"橙色样式（v4.8.4）
+- **修复**：`protect` 范围外的文件不再在变更摘要中被误标为"删除"（v4.8.5）
+- **优化**：VSIX 包从 3.18 MB 缩减至 1.27 MB
+
+### v4.7.6–v4.7.9 — 侧边栏重设计、右键菜单、保护范围
+
+- **新功能**：右键上下文菜单——在资源管理器/编辑器右键添加文件到 `protect` 或 `ignore`，含模式选择器（v4.7.7）
+- **新功能**：侧边栏保护范围卡片——显示受保护/排除文件数、protect/ignore 模式列表（v4.7.8）
+- **新功能**：告警倒计时每秒实时跳动（v4.7.8）
+- **修复**：Open Dashboard CORS/CSP 问题——添加 CORS 头、放宽 CSP、WebView 失败时回退到浏览器（v4.7.8）
+- **修复**：`protect` 模式改为严格匹配（仅完整路径，不回退到 basename）（v4.7.8）
+- **重设计**：侧边栏仪表盘简化——单一状态指示器、2×2 操作按钮网格、精简 Quick Stats（v4.7.6）
 
 ### v4.7.5 — VSIX 独立打包 + 自动配置
 
@@ -461,7 +526,7 @@ code --install-extension .
 - **功能**：Dashboard 版本检测 + 一键热重启（`/api/restart` 端点）
 - **功能**：文件详情弹窗 + 每文件恢复命令复制按钮
 - **功能**：`cursor-guard-init` 自动创建 `.cursor-guard.json`；支持 `backup_interval_seconds` 别名
-- **许可证**：从 MIT 变更为 BSL 1.1（源码可见，商业使用需作者授权）
+- **许可证**：变更为 BSL 1.1
 
 ### v4.4.0 — V4 收官版
 
@@ -540,8 +605,9 @@ code --install-extension .
 - **未跟踪文件**：从未提交到 Git 的文件无法从 Git 历史恢复。影子拷贝（`backup_strategy: "shadow"` 或 `"both"`）是未跟踪文件的唯一安全网。
 - **并发 Agent**：如果多个 AI 代理线程同时写入同一文件，快照无法防止竞态条件。请避免并行编辑同一文件。
 - **外部工具修改索引**：在自动备份运行期间，其他修改 Git 索引的工具（如 Git GUI、IDE Git 集成）可能冲突。脚本使用临时索引来最小化风险，但边缘情况仍存在。
-- **Git worktree**：自动备份脚本支持 worktree 布局（`git rev-parse --git-dir`），但未在所有特殊配置下测试（如 `--separate-git-dir`）。
-- **Cursor 终端干扰**：Cursor 集成终端会向 `git commit` 命令注入 `--trailer` 标志，导致 `commit-tree` 等底层命令异常。请始终在**独立的终端窗口**中运行自动备份脚本。
+- **Git worktree**：自动备份脚本支持 worktree 布局（`git rev-parse --git-dir`），但未在所有特殊配置下测试（如 `--separate-git-dir`）。
+- **预警边界**：`pre_warning` 目前属于编辑器/扩展侧的“最后一道刹车”，还不是跨进程、全场景的硬拦截。纯 shell / 纯 MCP 无界面场景下，主要通过状态和看板暴露风险。
+- **Cursor 终端干扰**：Cursor 集成终端会向 `git commit` 命令注入 `--trailer` 标志，导致 `commit-tree` 等底层命令异常。请始终在**独立的终端窗口**中运行自动备份脚本。
 - **大型仓库**：对于非常大的仓库，备份循环中的 `git add -A` 可能较慢。使用 `.cursor-guard.json` 中的 `protect` 模式缩小范围。
 
 ## 环境要求
@@ -564,4 +630,4 @@ code --install-extension .
 
 ## 许可证
 
-[BSL 1.1（商业源代码许可证）](LICENSE) — 源代码自由查看、修改和非商业使用。商业使用需获得作者授权。2056-03-22 之后自动转为 Apache 2.0。
+[BSL 1.1](LICENSE)

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.9.1`  
-> **文档状态**：`V2` ~ `V4.9.1` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.9.6`
+> **文档状态**：`V2` ~ `V4.9.6` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -193,7 +193,7 @@ cursor-guard 的安全，不靠“模型自己小心一点”，而是靠**规
 
 ---
 
-## V2 — Skill + Script（当前版本）
+## V2 — Skill + Script（基础能力起点）
 
 | 项目 | 内容 |
 |---|---|
@@ -560,7 +560,7 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 
 | 层 | 改动 | 说明 |
 |----|------|------|
-| Core | `backups.js` 新增 `getBackupFiles(projectDir, commitHash)` | 对指定 commit 运行 `diff-tree --numstat + --name-status`，返回 `[{path, action, added, deleted}]`，按变化量降序。支持 rename 解析（`R` 前缀→取 tab 分割的最后一段）。无 parent 时退化为 `ls-tree` 列出全部文件 |
+| Core | `backups.js` 新增 `getBackupFiles(projectDir, commitHash)` | 对指定 commit 运行 `git diff --numstat` + `git diff --name-status`（与终端一致；V4.9.3+）。无 parent 时对 Git 空树 `4b825dc…`。返回 `[{path, action, added, deleted}]`，按变化量降序；`R`/`C` 前缀解析 rename/copy |
 | Server | `GET /api/backup-files?id=<project>&hash=<commit>` | 懒加载端点，不在 `list_backups` 中批量计算（50 条备份×`diff-tree` 会很慢）。400 校验 `hash` 必填 |
 | Dashboard | `parseSummaryToFiles(summary)` | 解析 summary 文本格式 `"Modified 3: a.js (+2 -1), b.js (+0 -5), ...; Added 2: c.js (+10 -0)"` → `[{path, action, added, deleted}]`。正则匹配 `(Modified|Added|Deleted|Renamed) N:` 段头，逐文件解析 `filename (+N -M)`，自动跳过 `...` 截断标记 |
 | Dashboard | `fetchBackupFiles(hash)` | 调用 `/api/backup-files` 端点，返回完整文件数组。网络失败静默降级（返回空数组） |
@@ -734,6 +734,39 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
+### V4.9.6：新增可开关的 `pre_warning` 事先预警 MVP ✅
+
+| 能力 | 说明 |
+|------|------|
+| **配置开关** | `.cursor-guard.json` 新增 `enable_pre_warning`、`pre_warning_threshold`、`pre_warning_mode`、`pre_warning_exclude_patterns`，默认关闭，兼容旧项目 |
+| **风险模型** | 基于删行比例 + 方法/函数移除检测进行评分；删方法/函数即使未达到删行阈值，也会按高风险处理 |
+| **IDE 交互** | VSCode / Cursor / Windsurf 扩展支持 `popup` / `dashboard` / `silent` 三种模式；`popup` 提供 `Undo Change` 与 `View Diff` 作为最后一道刹车 |
+| **状态面整合** | `backup_status`、`dashboard`、状态栏、侧边栏、浏览器仪表盘统一展示活跃 pre-warning；风险摘要进入 health issues |
+| **架构定位** | 这是 V5「变更控制层」前的一步 MVP：先做编辑器侧的“最后一道提醒”，不是跨进程硬拦截；后续仍由 V5 的 `begin_edit` / embedded watcher 承接更强的事前控制 |
+
+### V4.9.5 / V4.9.4：修复事件驱动 Watcher 因 `.git` 写入导致的疯狂自触发备份 ✅
+
+| 修复 | 说明 |
+|------|------|
+| **根因** | v4.9.0 起 `fs.watch(recursive)` 监听整个仓库。每次快照会写 `.git/objects`、`refs/guard/…` 等，触发 watch → debounce 后又跑备份。Windows 下 `filename` 常为 `HEAD`、`objects/…` 等**不带** `.git/` 前缀 → **反馈环路** |
+| **完全避免（不靠延时）** | `shouldIgnoreFsWatchEvent`：凡可判定为「落在 Git 目录内」的事件一律不触发备份。**不用**快照后冷却计时；路径语义正确即可从根上断开环路 |
+| **真实 Git 目录** | 传入 `git rev-parse --git-dir` 解析后的路径（worktree / 子模块等下 `.git` 可能是文件），避免误用 `项目/.git` 字符串 |
+| **路径规则** | `.git/` 前缀、`.cursor-guard-backup`、多段路径在 `git-dir` 下存在、`path.relative(gitDir, resolve(项目,filename))` 落在仓库内 → 忽略 |
+| **V4.9.5** | 移除曾加入的 **3.5s 冷却**（用户要求：应全量避免，而非靠时间窗口兜底） |
+
+### V4.9.3：备份文件 +/- 与终端 `git diff` 完全一致 ✅
+
+| 变更 | 说明 |
+|------|------|
+| **唯一数据源** | `getBackupFiles` 只使用 `git diff --numstat <parent> <commit>` + `git diff --name-status <parent> <commit>`，与你在终端执行的 diff 统计一致（含 rename 检测、CRLF、二进制 `- -` 等） |
+| **根/orphan 提交** | 无父提交时 `parent` 使用 Git 标准空树 `4b825dc642cb6eb9a060e54bf8d69288fbee4904`，不再用 `ls-tree` + 手工行数 |
+| **移除** | 去掉 `diff-tree --numstat`、`--text` 及 `git show` 行数回退，避免与 CLI 语义分叉 |
+| **拷贝** | `git diff --name-status` 的 `C`（copy）映射为 `action: copied` |
+
+### V4.9.2：（已由 V4.9.3 替代）备份详情行数修复尝试
+
+> V4.9.2 的 `--text` + `git show` 回退已废弃；以 V4.9.3「纯 git diff」为准。
+
 ### V4.9.1：侧边栏"Last backup"实时计时 ✅
 
 | 优化 | 说明 |
@@ -1381,7 +1414,7 @@ PR Review 中展示 AI 编辑报告
 
 ### V6 不做的事
 
-- **不做商业化平台** —— cursor-guard 保持开源，协议保持开放
+- **不做平台化** —— cursor-guard 专注代码安全工具
 - **不做强依赖云端的服务** —— 核心能力永远是本地优先
 - **不做 IDE 本体** —— 只做安全层，不越界
 - **不做通用工程观测平台** —— 只围绕 AI 代码变更安全
@@ -1568,7 +1601,10 @@ V4.3.2 ─────  ✅ init 自动添加 node_modules/ 到 .gitignore + doc
 V4.3.3 ─────  ✅ Intent 上下文（intent / agent / session trailer + 仪表盘展示）
 V4.3.4 ─────  ✅ 运维加固（日志轮转 / 锁文件时间戳 / preview 分组 / SKILL 规则）
 V4.3.5 ─────  ✅ Summary 增量 diff-tree 修复 + 变更列堆叠布局 + 配色优化
-V4.4.0 ─────  ✅ V4 收官：首次快照 summary + doctor 完整性/retention 检查 + init 升级检测  ← 当前版本
+V4.4.0 ─────  ✅ V4 收官：首次快照 summary + doctor 完整性/retention 检查 + init 升级检测
+V4.9.0 ─────  ✅ 事件驱动 watcher + 实时侧边栏计时
+V4.9.5 ─────  ✅ 修复 `.git` 写入导致的疯狂自触发备份
+V4.9.6 ─────  ✅ `pre_warning` 事先预警 MVP（局部删代码风险提示）  ← 当前版本
                │
                │  前提：AI 编辑需要更强的追溯 / 恢复 / 查询闭环
                │  前提：多 Agent / 多工具协作成为真实场景
@@ -1647,10 +1683,10 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 | 取代 Git | cursor-guard 是 Git 的增强，不是替代 |
 | AI 行为限制 | cursor-guard 是安全网，不是笼子 |
 | 多 IDE 全面适配 | 聚焦 Cursor，其他 IDE 由社区或 V6 协议解决 |
-| 商业化封闭 | 保持开源，协议保持开放 |
+| 封闭化 | 保持开源，协议保持开放 |
 | 中心化认证服务 | 签名和验证基于本地，不引入外部依赖 |
 
 ---
 
-*最后更新：2026-03-22*
-*版本：v1.5（V4.4.0 收官版，含 Web 仪表盘、备份上下文元数据、Intent 基础、增量 summary、doctor 完整性校验、运维加固、UI 优化）*
+*最后更新：2026-03-22*
+*版本：v1.6（V4.9.6，含事件驱动 watcher、自触发备份反馈环修复、`pre_warning` 事先预警 MVP）*

package/SKILL.md

@@ -62,17 +62,24 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
   // "count": keep N newest commits. "days": keep commits from last N days.
   "git_retention": { "enabled": false, "mode": "count", "max_count": 200 },
 
-  // V4: Proactive change-velocity detection (default: on).
-  // When enabled, the watcher monitors file change frequency and raises
-  // alerts when abnormal patterns are detected (e.g. 20+ files in 10s).
-  "proactive_alert": true,
-  "alert_thresholds": {
-    "files_per_window": 20,  // trigger threshold
-    "window_seconds": 10,    // sliding window
-    "cooldown_seconds": 60   // min gap between alerts
-  }
-}
-```
+  // V4: Proactive change-velocity detection (default: on).
+  // When enabled, the watcher monitors file change frequency and raises
+  // alerts when abnormal patterns are detected (e.g. 20+ files in 10s).
+  "proactive_alert": true,
+  "alert_thresholds": {
+    "files_per_window": 20,  // trigger threshold
+    "window_seconds": 10,    // sliding window
+    "cooldown_seconds": 60   // min gap between alerts
+  },
+
+  // V4.9.6: destructive partial-delete pre-warning (default: off).
+  // Triggered when deletion risk is high or whole methods/functions disappear.
+  "enable_pre_warning": false,
+  "pre_warning_threshold": 30,
+  "pre_warning_mode": "popup",
+  "pre_warning_exclude_patterns": []
+}
+```
 
 **Resolution rules:**
 - `protect` set + `ignore` set → file must match a `protect` pattern AND not match any `ignore` pattern.
@@ -82,10 +89,12 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
 
 **`secrets_patterns`**: Glob patterns for sensitive files (`.env`, keys, certificates). Matching files are **auto-excluded** from backup commits, even within `protect` scope. Built-in defaults: `.env`, `.env.*`, `*.key`, `*.pem`, `*.p12`, `*.pfx`, `credentials*`. Set this field to override.
 
-**`retention`**: Controls automatic cleanup of old shadow-copy snapshots in `.cursor-guard-backup/`:
-- `"days"` (default): keep snapshots from the last N days (default **30**).
-- `"count"`: keep the N most recent snapshots (default 100).
-- `"size"`: keep total shadow-copy folder under N MB (default 500).
+**`retention`**: Controls automatic cleanup of old shadow-copy snapshots in `.cursor-guard-backup/`:
+- `"days"` (default): keep snapshots from the last N days (default **30**).
+- `"count"`: keep the N most recent snapshots (default 100).
+- `"size"`: keep total shadow-copy folder under N MB (default 500).
+
+**`enable_pre_warning` / `pre_warning_*`**: Optional IDE-side "last brake" for destructive partial deletions. When enabled, the extension scores deletion-heavy edits, removed methods/functions, and suspicious line drops. `popup` interrupts with quick actions, `dashboard` only surfaces the warning in UI/status, and `silent` only records it. Active warnings are exposed through `backup_status` / `dashboard` as `_activePreWarning`.
 
 **If no config file exists**, the agent operates in "protect everything" mode (backward compatible). Mention to the user that they can create `.cursor-guard.json` to narrow scope — see [references/cursor-guard.example.json](references/cursor-guard.example.json).
 
@@ -111,12 +120,13 @@ cursor-guard provides an **MCP server** (`cursor-guard-mcp`) as an optional enha
 | Change-velocity alerts | `alert_status` | manual: check alert file in .git/ or .cursor-guard-backup/ |
 
 **Rules**:
-- MCP results are JSON — parse `status`, `error`, and data fields; do not re-run shell to verify.
-- If an MCP call returns an `error` field, report it to the user and fall back to the shell path for that operation.
-- All Hard Rules (§Hard Rules) still apply regardless of execution path. MCP tools enforce them internally (e.g. `restore_file` creates a pre-restore snapshot by default).
-- If MCP is not configured, the skill works exactly as before — **no degradation**.
-- `doctor_fix` is safe to call — each fix is idempotent. Use `dry_run: true` to preview changes before applying. Typical fixes: create missing config, init git repo, gitignore backup dir, remove stale lock file.
-- `restore_project` with `preview: false` executes a full restore including pre-restore snapshot. Always call with `preview: true` first, show the result to the user, and only execute after explicit confirmation.
+- MCP results are JSON — parse `status`, `error`, and data fields; do not re-run shell to verify.
+- If an MCP call returns an `error` field, report it to the user and fall back to the shell path for that operation.
+- All Hard Rules (§Hard Rules) still apply regardless of execution path. MCP tools enforce them internally (e.g. `restore_file` creates a pre-restore snapshot by default).
+- If MCP is not configured, the skill works exactly as before — **no degradation**.
+- `backup_status` and `dashboard` may include `_activePreWarning`; when present, surface it as an active delete-risk warning before giving the rest of the health summary.
+- `doctor_fix` is safe to call — each fix is idempotent. Use `dry_run: true` to preview changes before applying. Typical fixes: create missing config, init git repo, gitignore backup dir, remove stale lock file.
+- `restore_project` with `preview: false` executes a full restore including pre-restore snapshot. Always call with `preview: true` first, show the result to the user, and only execute after explicit confirmation.
 
 When the target file of an edit **falls outside the protected scope**, the agent:
 - Still applies "Read before Write" (Hard Rule §2).
@@ -603,7 +613,7 @@ Skip the block for unrelated turns.
 - Recovery commands: [references/recovery.md](references/recovery.md)
 - Auto-backup (Node.js core): [references/lib/auto-backup.js](references/lib/auto-backup.js)
 - Guard doctor (Node.js core): [references/lib/guard-doctor.js](references/lib/guard-doctor.js)
-- Core modules: [references/lib/core/](references/lib/core/) (doctor, doctor-fix, snapshot, backups, restore, status, anomaly, dashboard)
+- Core modules: [references/lib/core/](references/lib/core/) (doctor, doctor-fix, snapshot, backups, restore, status, anomaly, pre-warning, dashboard)
 - MCP server: [references/mcp/server.js](references/mcp/server.js) (9 tools: doctor, doctor_fix, backup_status, list_backups, snapshot_now, restore_file, restore_project, dashboard, alert_status)
 - Web dashboard: [references/dashboard/](references/dashboard/) (local read-only web UI — `node references/dashboard/server.js --path <project>`)
 - Shared utilities: [references/lib/utils.js](references/lib/utils.js)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.9.1",
+  "version": "4.9.6",
   "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",