cursor-guard 4.9.1 → 4.9.8

package/README.md

@@ -23,9 +23,15 @@ When Cursor's AI agent edits your files, there's a risk of accidental overwrites
 - **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
+- **Pre-warning destructive edit guard (V4.9.7)** — Detects risky partial deletions before they quietly stick, with softer auto-continue review, sidebar language sync, and `popup` / `dashboard` / `silent` modes
 - **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
+- **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
@@ -119,6 +125,7 @@ After installation, your directory structure should look like this:
     │       ├── restore.js              # Single file / project restore
     │       ├── status.js               # Backup system status
     │       ├── anomaly.js             # V4: Change-velocity detection
+│       ├── pre-warning.js         # V4.9.7: destructive edit risk scoring + persistence
     │       └── dashboard.js           # V4: Health dashboard aggregation
     ├── dashboard/
     │   ├── server.js                   # Dashboard HTTP server + API
@@ -200,6 +207,12 @@ Edit `.cursor-guard.json` to define which files to protect:
   "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 }
 }
 ```
@@ -216,6 +229,19 @@ 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.
+
 ---
 
 ## Auto-Backup Script
@@ -303,16 +329,26 @@ Embed the full dashboard directly inside your IDE — no browser needed.
 #### Method A: VSIX standalone (recommended, no npm needed)
 
 ```bash
-# Build the self-contained VSIX package
+# Build the self-contained VSIX (version = root package.json "version")
 cd references/vscode-extension
 node build-vsix.js
 cd dist
-npx vsce package
+npx --yes @vscode/vsce package --no-dependencies
 
-# Install the generated .vsix file
-code --install-extension cursor-guard-ide-4.7.5.vsix
+# Install the generated .vsix (VERSION always matches package.json)
+V=$(node -p "require('../../../package.json').version")
+code --install-extension "cursor-guard-ide-${V}.vsix"
 ```
 
+PowerShell (from `references\vscode-extension\dist`):
+
+```powershell
+$V = node -p "require('../../../package.json').version"
+code --install-extension "cursor-guard-ide-$V.vsix"
+```
+
+Print the full release checklist from the repo root: `npm run release:checklist`.
+
 On first activation, the extension automatically:
 - Installs `SKILL.md` to your IDE's skills directory
 - Registers the MCP Server in your IDE's `mcp.json`
@@ -330,9 +366,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 +445,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) |
@@ -427,6 +467,55 @@ The skill activates on these signals:
 
 ## Changelog
 
+### v4.9.8 — Release docs, checklist script, sidebar brand asset
+
+- **Docs**: Bilingual **Release checklist** sections in README / README.zh-CN; steps tied to root `package.json` `version` so VSIX file name, Git tag, and npm stay consistent
+- **Tooling**: `npm run release:checklist` (`scripts/print-release-checklist.js`) prints a ready-to-paste table; `build-vsix.js` logs the expected VSIX file name after build
+- **IDE**: Sidebar header can show packaged brand artwork via `media/brand-placeholder.png` and `asWebviewUri` (fallback gradient if the file is absent)
+
+### v4.9.7 — Softer Pre-Warning UX, Sidebar Locale Sync, and Watcher Singleton Guard
+
+- **Improve**: `popup` mode now uses a softer auto-continue review flow with a 2-second timeout instead of a hard modal stop
+- **Improve**: Pre-warning review text now follows the sidebar language toggle, keeping zh-CN / en-US messaging consistent inside the IDE
+- **Fix**: Sidebar keeps showing watcher / health status even when delete-risk warnings are present, and popup-mode warnings no longer stick forever
+- **Fix**: IDE watcher start/stop logic now uses the real per-project lock path and pending-process guard, preventing repeated clicks from spawning duplicate watchers
+- **Docs**: README, roadmap, and skill notes updated for the 4.9.7 release flow and IDE behavior
+
+### 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
 
 - **Feature**: `build-vsix.js` packages all runtime dependencies into a self-contained VSIX — no npm installation needed
@@ -462,7 +551,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
 
@@ -535,6 +624,36 @@ The skill activates on these signals:
 
 ---
 
+## Release checklist
+
+**Single source of truth**: the `version` field in the **repository root** `package.json`. Running `references/vscode-extension/build-vsix.js` copies that value into the extension `package.json` and `guard-version.json`, so the VSIX and npm tarball stay aligned.
+
+### Generate a filled-in table (recommended)
+
+From the repository root:
+
+```bash
+npm run release:checklist
+```
+
+Copy the terminal output into your own release tracker. It always reflects the current `package.json` version.
+
+### Reference checklist
+
+| Step | What to do |
+|------|------------|
+| **1. Version** | Bump root `package.json` `version`, then rebuild. Do not keep stale numbers (e.g. 4.9.5) in notes while the repo is already newer. |
+| **2. VSIX** | `cd references/vscode-extension && node build-vsix.js && cd dist && npx --yes @vscode/vsce package --no-dependencies` |
+| **3. Artifact** | `cursor-guard-ide-<version>.vsix` in `references/vscode-extension/dist/` (file name matches `version`). |
+| **4. Git** | Commit and push your default branch; create and push tag `v<version>` (example: `git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z`). Record the actual commit hash in your notes. |
+| **5. GitHub Release** | [Create a release](https://github.com/zhangqiang8vipp/cursor-guard/releases/new), select tag `v<version>`, attach the VSIX. |
+| **6. Release branches** | Fast-forward maintenance branches such as `release/v4.8.x` / `release/v4.7.x` to the current `master` when your branching policy requires it. |
+| **7. npm** | From the repo root: `npm publish`. If npm asks for OTP, complete verification in the browser, then run `npm publish` again. |
+
+Skipping the Marketplace is fine; GitHub Release + VSIX is enough for many users.
+
+---
+
 ## 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.
@@ -542,6 +661,7 @@ The skill activates on these signals:
 - **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`).
+- **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.
 
@@ -565,4 +685,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

@@ -23,9 +23,15 @@
 - **MCP 工具调用（可选）** — 9 个标准化工具（诊断、快照、恢复、状态、看板、告警等），结构化 JSON 返回，低 token 消耗
 - **自动诊断修复** — `doctor_fix` 一键修补缺失配置、未初始化 Git、gitignore 遗漏等常见问题
 - **主动变更频率告警（V4）** — 自动检测异常文件变更模式并发出风险预警
+- **事先预警删除风险（V4.9.7）** — 在危险的局部删除真正“悄悄生效”前先提醒你，支持更柔和的自动继续提示、侧边栏语言同步，以及 `popup` / `dashboard` / `silent` 三种模式
 - **备份健康看板（V4）** — 一次调用全面查看：策略、数量、磁盘占用、保护范围、健康状态
-- **Web 仪表盘（V4.2）** — 本地只读 Web 页面 `http://127.0.0.1:3120`——健康状态、备份、恢复点、诊断、保护范围一目了然。中英双语、每 15 秒自动刷新、支持多项目监控
+- **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 自动启动，确保零保护缺口
@@ -119,6 +125,7 @@ git clone https://github.com/zhangqiang8vipp/cursor-guard.git .cursor/skills/cur
     │       ├── restore.js              # 单文件/全项目恢复
     │       ├── status.js               # 备份系统状态
     │       ├── anomaly.js             # V4：变更频率检测
+│       ├── pre-warning.js         # V4.9.7：删除风险评分 + 持久化
     │       └── dashboard.js           # V4：健康看板聚合
     ├── dashboard/
     │   ├── server.js                   # 仪表盘 HTTP 服务 + API
@@ -200,6 +207,12 @@ npx cursor-guard-backup --path /my/project
   "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 }
 }
 ```
@@ -216,6 +229,19 @@ npx cursor-guard-backup --path /my/project
 - 说"不保留当前版本"可跳过保留（即使配置为 `"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` | `[]` | 跳过生成文件、迁移脚本、第三方代码等 |
+
+如果检测到方法/函数被移除，即使删行比例没到阈值，也会按高风险处理并触发提醒。
+
 ---
 
 ## 自动备份脚本
@@ -303,16 +329,26 @@ node references\dashboard\server.js --path "D:\MyProject"
 #### 方式 A：VSIX 独立安装（推荐，无需 npm）
 
 ```bash
-# 构建独立 VSIX 包
+# 构建独立 VSIX 包（版本号 = 仓库根目录 package.json 的 version）
 cd references/vscode-extension
 node build-vsix.js
 cd dist
-npx vsce package
+npx --yes @vscode/vsce package --no-dependencies
 
-# 安装生成的 .vsix 文件
-code --install-extension cursor-guard-ide-4.7.5.vsix
+# 安装生成的 .vsix（VERSION 与 package.json 一致；勿手写旧版本号）
+V=$(node -p "require('../../../package.json').version")
+code --install-extension "cursor-guard-ide-${V}.vsix"
 ```
 
+PowerShell（在 `references\vscode-extension\dist` 下）：
+
+```powershell
+$V = node -p "require('../../../package.json').version"
+code --install-extension "cursor-guard-ide-$V.vsix"
+```
+
+发版前打印完整检查清单：`npm run release:checklist`（在仓库根目录）。
+
 首次激活时，扩展自动：
 - 将 `SKILL.md` 安装到 IDE 的 skills 目录
 - 将 MCP Server 注册到 IDE 的 `mcp.json`
@@ -330,9 +366,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 +445,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） |
@@ -427,6 +467,55 @@ code --install-extension .
 
 ## 更新日志
 
+### v4.9.8 — 发版文档、清单脚本、侧边栏品牌资源
+
+- **文档**：在 README / README.zh-CN 增加双语**发版检查清单**，步骤与根目录 `package.json` 的 `version` 绑定，避免 VSIX 名、Git 标签、npm 版本各写各的
+- **工具**：`npm run release:checklist`（`scripts/print-release-checklist.js`）一键输出可粘贴的表格；`build-vsix.js` 构建结束后提示对应 VSIX 文件名
+- **IDE**：侧边栏顶栏可通过扩展内 `media/brand-placeholder.png` + webview `asWebviewUri` 展示品牌图（无文件时仍用渐变占位）
+
+### v4.9.7 — 更柔和的事先预警、侧边栏语言同步与 Watcher 单例保护
+
+- **改进**：`popup` 模式改为 2 秒自动继续的柔性提示，不再用硬阻塞弹窗打断连续编辑
+- **改进**：事先预警提示文案会跟随侧边栏语言切换，IDE 内中英文保持一致
+- **修复**：即使存在删除风险提示，侧边栏也会持续展示 watcher / health 状态；`popup` 模式的预警不会一直挂住不消失
+- **修复**：IDE 启停 watcher 时改为读取真实项目锁路径，并增加启动中的单例保护，避免重复点击拉起多个 watcher
+- **文档**：README、ROADMAP、SKILL 一并更新到 4.9.7 发版说明
+
+### 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 独立打包 + 自动配置
 
 - **功能**：`build-vsix.js` 将所有运行时依赖打包为独立 VSIX —— 无需 npm 安装
@@ -461,7 +550,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 收官版
 
@@ -534,6 +623,36 @@ code --install-extension .
 
 ---
 
+## 发版检查清单
+
+**唯一版本源**：仓库**根目录** `package.json` 里的 **`version`**。执行 `references/vscode-extension/build-vsix.js` 时，会把同一版本写入扩展内的 `package.json` 与 `guard-version.json`，因此 VSIX 与 npm 包版本一致。
+
+### 生成已填好版本号的表格（推荐）
+
+在仓库根目录执行：
+
+```bash
+npm run release:checklist
+```
+
+将终端完整输出复制到你的发版记录即可；其中版本号始终与当前 `package.json` 一致。
+
+### 步骤对照表
+
+| 步骤 | 内容 |
+|------|------|
+| **1. 版本号** | 先修改根目录 `package.json` 的 `version`，再执行构建。记录表里不要写已过期的版本号（例如仓库已是 4.9.8 却仍写 4.9.5）。 |
+| **2. VSIX** | `cd references/vscode-extension && node build-vsix.js && cd dist && npx --yes @vscode/vsce package --no-dependencies` |
+| **3. 产物** | `references/vscode-extension/dist/cursor-guard-ide-<version>.vsix`（文件名与 `version` 一致） |
+| **4. Git** | 提交并推送默认分支；打标签 **`v<version>`** 并推送（示例：`git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z`）。提交 hash 以实际为准记入你的表格。 |
+| **5. GitHub Release** | 在 [Releases](https://github.com/zhangqiang8vipp/cursor-guard/releases/new) 新建 Release，选择对应 **`v<version>`** 标签，上传上述 VSIX。 |
+| **6. release 分支** | 按分支策略将 **`release/v4.8.x`**、**`release/v4.7.x`** 等维护分支快进到当前 **`master`**（如需）。 |
+| **7. npm** | 在仓库根目录执行 **`npm publish`**；若提示 OTP，先在浏览器完成 npm 的二次验证，再重新执行一次 **`npm publish`**。 |
+
+暂不发布 VS Code Marketplace 也可以；仅靠 GitHub Release + VSIX 已能满足很多安装场景。
+
+---
+
 ## 已知限制
 
 - **二进制文件**：Git 快照可以存储二进制文件（图片、编译产物），但无法进行有意义的 diff 或部分恢复。
@@ -541,6 +660,7 @@ code --install-extension .
 - **并发 Agent**：如果多个 AI 代理线程同时写入同一文件，快照无法防止竞态条件。请避免并行编辑同一文件。
 - **外部工具修改索引**：在自动备份运行期间，其他修改 Git 索引的工具（如 Git GUI、IDE Git 集成）可能冲突。脚本使用临时索引来最小化风险，但边缘情况仍存在。
 - **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 +684,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.8`
+> **文档状态**：`V2` ~ `V4.9.8` 已完成交付（含 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,55 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
+### V4.9.8：发版流程文档化 + 侧边栏品牌占位 ✅
+| 能力 | 说明 |
+|------|------|
+| **发版清单** | 根目录 `npm run release:checklist` 输出带当前 `package.json` 版本的步骤表；README / README.zh-CN 双语「发版检查清单」与之一致，避免 VSIX 名、tag、npm 版本手写漂移 |
+| **构建提示** | `build-vsix.js` 结束行打印预期 `cursor-guard-ide-<version>.vsix` 文件名 |
+| **侧边栏品牌** | 扩展包内 `media/brand-placeholder.png`，webview 通过 `asWebviewUri` 加载；缺失时回退渐变占位 |
+
+### V4.9.7：预警体验打磨、语言同步与 Watcher 单例保护 ✅
+| 能力 | 说明 |
+|------|------|
+| **柔性预警** | `popup` 模式改为 2 秒自动继续的软提示，保留 `Undo Change`、`View Diff`、`Keep Changes`，但不再把连续 AI 编辑卡死在硬模态弹窗里 |
+| **语言同步** | 侧边栏语言切换会同步到预警提示，zh-CN / en-US 的按钮、摘要、倒计时文案保持一致 |
+| **侧边栏状态恢复** | `popup` 模式的预警不再长期占据侧边栏主卡片；Watcher / Health 状态重新固定可见，系统是否正常运行能持续看到 |
+| **Watcher 单例** | IDE 侧统一读取真实 watcher 锁文件路径，并增加 pending-process 保护；同一个项目重复点 `Start Watcher` 不会再拉起多个 watcher |
+| **发布目标** | 这是对 V4.9.6 MVP 的 UX/稳定性收口版，让预警真正适合长时间挂在 Agent 模式下使用 |
+
+### 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 +1430,7 @@ PR Review 中展示 AI 编辑报告
 
 ### V6 不做的事
 
-- **不做商业化平台** —— cursor-guard 保持开源，协议保持开放
+- **不做平台化** —— cursor-guard 专注代码安全工具
 - **不做强依赖云端的服务** —— 核心能力永远是本地优先
 - **不做 IDE 本体** —— 只做安全层，不越界
 - **不做通用工程观测平台** —— 只围绕 AI 代码变更安全
@@ -1568,7 +1617,15 @@ 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.8 ─────  ✅ 发版清单（README 双语 + checklist 脚本）+ 侧边栏品牌图  ← 当前版本
+V4.9.7 ─────  ✅ 预警体验打磨 + 语言同步 + watcher 单例保护
+               │
+               │  前提：MVP 已跑通，需要把提示从“能用”打磨到“适合常开”
+               ▼
+V4.9.6 ─────  ✅ `pre_warning` 事先预警 MVP（局部删代码风险提示）
                │
                │  前提：AI 编辑需要更强的追溯 / 恢复 / 查询闭环
                │  前提：多 Agent / 多工具协作成为真实场景
@@ -1647,10 +1704,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 优化）*
+*版本：v1.8（V4.9.8，在 V4.9.7 基础上增加发版流程文档与侧边栏品牌资源；历史能力含事件驱动 watcher、自触发备份反馈环修复、`pre_warning` 事先预警 MVP）*