cursor-guard 4.8.4 → 4.9.0

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.8.4`  
-> **文档状态**：`V2` ~ `V4.8.4` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.9.0`  
+> **文档状态**：`V2` ~ `V4.9.0` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -734,6 +734,34 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
+### V4.9.0：事件驱动架构 — 从轮询到实时响应 ✅
+
+| 改造 | 说明 |
+|------|------|
+| **Watcher 事件驱动** | `auto-backup.js` 从 `while+sleep(N秒)` 盲轮询重构为 `fs.watch` 事件驱动。文件变化时 500ms 防抖后立即触发备份；无变化时零消耗。30s 心跳兜底负责配置热加载、retention 清理、告警过期 |
+| **轮询降级** | 若 `fs.watch` 不可用（如 Linux 旧内核），自动回退到原始轮询模式，保持向后兼容 |
+| **配置即时响应** | `.cursor-guard.json` 变化时 `fs.watch` 直接触发配置热加载，不再等待 10 个轮询周期 |
+| **IDE 侧 FileSystemWatcher** | 扩展使用 VSCode 内置 `createFileSystemWatcher` 监听文件变化，1.5s 防抖后触发 Poller 即时刷新 |
+| **Poller 心跳模式** | 从 5s 固定轮询改为 30s 心跳。UI 更新由 FileSystemWatcher 事件驱动，心跳仅做兜底健康同步 |
+| **UI 按需刷新** | Sidebar、StatusBar、TreeView 通过 `poller.onChange()` 订阅，只在有数据变化时才重绘，无变化时零消耗 |
+
+**性能对比**：
+
+| 指标 | v4.8.x (轮询) | v4.9.0 (事件驱动) |
+|------|---------------|------------------|
+| 备份响应延迟 | 最差 10s | < 500ms |
+| 无变化时 CPU | 每 10s 执行 git status | 零（idle） |
+| UI 刷新频率 | 每 5s 盲刷新 | 事件触发 + 30s 心跳 |
+| 新增依赖 | — | 零（fs.watch + VSCode 内置） |
+
+### V4.8.5：修复变更摘要中 protect 范围外文件误标为"删除"的 Bug ✅
+
+| 修复 | 说明 |
+|------|------|
+| **diff-tree 结果过滤 protect 范围** | 当 `protect` 配置非空时，`diff-tree` 对比上一次备份和当前备份的 tree 差异后，额外过滤掉不在 `protect` 范围内的文件。之前这些文件会被误标为"删除"（实际只是不在保护范围内） |
+| **根因** | 用户配置 `protect: ["src/**", "pom.xml"]` 后，`.cursor-guard.json`、`.gitignore`、`.cursor/mcp.json` 等文件不在保护范围内，当前 tree 不含这些文件。`diff-tree` 对比时将其报告为 `D`（删除），但代码只过滤了 `cfg.ignore` 未过滤 `cfg.protect` |
+| **影响** | 变更摘要不再出现"幽灵删除"，仅展示 protect 范围内文件的真实变更 |
+
 ### V4.8.4：已删除文件恢复命令自动指向父提交 ✅
 
 | 修复 | 说明 |

package/package.json

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

package/references/lib/auto-backup.js

@@ -171,48 +171,24 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
     console.log(color.cyan(`[guard] Proactive alert: ON  (threshold: ${cfg.alert_thresholds.files_per_window} files / ${cfg.alert_thresholds.window_seconds}s)`));
   }
 
-  // Banner
-  console.log('');
-  console.log(color.cyan(`[guard] Watching '${projectDir}' every ${interval}s  (Ctrl+C to stop)`));
-  console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Ref: ${branchRef}  |  Retention: ${cfg.retention.mode}`));
-  console.log(color.cyan(`[guard] Log: ${logFilePath}`));
+  // ── Extracted cycle functions ──────────────────────────────────
 
-  // Optional embedded dashboard
-  if (opts.dashboardPort) {
+  async function hotReloadConfig() {
     try {
-      const { startDashboardServer } = require('../dashboard/server');
-      const { port } = await startDashboardServer([projectDir], { port: opts.dashboardPort, silent: true });
-      console.log(color.cyan(`[guard] Dashboard: http://127.0.0.1:${port}`));
-    } catch (e) {
-      console.log(color.yellow(`[guard] Dashboard failed to start: ${e.message}`));
-    }
-  }
-
-  console.log('');
-
-  // Main loop
-  let cycle = 0;
-  while (true) {
-    await sleep(interval * 1000);
-    cycle++;
-
-    // Hot-reload config every 10 cycles
-    if (cycle % 10 === 0) {
-      try {
-        const newMtime = fs.statSync(cfgPath).mtimeMs;
-        if (newMtime !== cfgMtime) {
-          const reload = loadConfig(projectDir);
-          if (reload.loaded && !reload.error) {
-            cfg = reload.cfg;
-            cfgMtime = newMtime;
-            tracker = createChangeTracker(cfg);
-            logger.info('Config reloaded (file changed)');
-          }
+      const newMtime = fs.statSync(cfgPath).mtimeMs;
+      if (newMtime !== cfgMtime) {
+        const reload = loadConfig(projectDir);
+        if (reload.loaded && !reload.error) {
+          cfg = reload.cfg;
+          cfgMtime = newMtime;
+          tracker = createChangeTracker(cfg);
+          logger.info('Config reloaded (file changed)');
         }
-      } catch { /* no config file or read error, keep current */ }
-    }
+      }
+    } catch { /* no config file or read error, keep current */ }
+  }
 
-    // Detect changes
+  async function backupCycle() {
     let hasChanges = false;
     let pendingManifest = null;
     let lastManifest = null;
@@ -230,11 +206,10 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
       }
     } catch (e) {
       logger.error(`Change detection failed: ${e.message}`);
-      continue;
+      return;
     }
-    if (!hasChanges) continue;
+    if (!hasChanges) return;
 
-    // Shadow: pre-compute changed file count from manifest diff (already accurate)
     let changedFileCount = 0;
     if (!repo && pendingManifest) {
       if (!lastManifest) {
@@ -253,7 +228,6 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
       }
     }
 
-    // Git snapshot via Core — changedFileCount comes from diff-tree (accurate incremental)
     let changedFiles;
     if ((cfg.backup_strategy === 'git' || cfg.backup_strategy === 'both') && repo) {
       const context = { trigger: 'auto' };
@@ -273,7 +247,6 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
       }
     }
 
-    // V4: Record change event and check for anomalies (after snapshot, using accurate count)
     recordChange(tracker, changedFileCount, changedFiles);
     const anomalyResult = checkAnomaly(tracker);
     if (anomalyResult.anomaly && anomalyResult.alert && !anomalyResult.suppressed) {
@@ -281,7 +254,6 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
       logger.warn(`ALERT: ${anomalyResult.alert.fileCount} files changed in ${anomalyResult.alert.windowSeconds}s (threshold: ${anomalyResult.alert.threshold})`);
     }
 
-    // Shadow copy via Core
     if (cfg.backup_strategy === 'shadow' || cfg.backup_strategy === 'both') {
       const shadowResult = createShadowCopy(projectDir, cfg, { backupDir });
       if (shadowResult.status === 'created') {
@@ -295,28 +267,125 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
         logger.error(`Shadow copy failed: ${shadowResult.error}`);
       }
     }
+  }
 
-    // Periodic retention every 10 cycles via Core
-    if (cycle % 10 === 0) {
-      const retResult = cleanShadowRetention(backupDir, cfg);
-      if (retResult.removed > 0) {
-        logger.log(`Retention (${retResult.mode}): cleaned ${retResult.removed} old snapshot(s)`, 'gray');
-      }
-      if (retResult.diskWarning === 'critically low') {
-        logger.error(`WARNING: disk critically low — ${retResult.diskFreeGB} GB free`);
-      } else if (retResult.diskWarning === 'low') {
-        logger.warn(`Disk note: ${retResult.diskFreeGB} GB free`);
-      }
+  async function maintenanceCycle() {
+    const retResult = cleanShadowRetention(backupDir, cfg);
+    if (retResult.removed > 0) {
+      logger.log(`Retention (${retResult.mode}): cleaned ${retResult.removed} old snapshot(s)`, 'gray');
+    }
+    if (retResult.diskWarning === 'critically low') {
+      logger.error(`WARNING: disk critically low — ${retResult.diskFreeGB} GB free`);
+    } else if (retResult.diskWarning === 'low') {
+      logger.warn(`Disk note: ${retResult.diskFreeGB} GB free`);
+    }
 
-      if (repo) {
-        const gitRetResult = cleanGitRetention(branchRef, gDir, cfg, projectDir);
-        if (gitRetResult.rebuilt) {
-          logger.log(`Git retention (${gitRetResult.mode}): rebuilt branch with ${gitRetResult.kept} newest snapshots, pruned ${gitRetResult.pruned}. Run 'git gc' to reclaim space.`, 'gray');
-        }
+    if (repo) {
+      const gitRetResult = cleanGitRetention(branchRef, gDir, cfg, projectDir);
+      if (gitRetResult.rebuilt) {
+        logger.log(`Git retention (${gitRetResult.mode}): rebuilt branch with ${gitRetResult.kept} newest snapshots, pruned ${gitRetResult.pruned}. Run 'git gc' to reclaim space.`, 'gray');
       }
+    }
+
+    clearExpiredAlert(projectDir);
+  }
+
+  // ── Optional embedded dashboard ────────────────────────────────
+
+  if (opts.dashboardPort) {
+    try {
+      const { startDashboardServer } = require('../dashboard/server');
+      const { port } = await startDashboardServer([projectDir], { port: opts.dashboardPort, silent: true });
+      console.log(color.cyan(`[guard] Dashboard: http://127.0.0.1:${port}`));
+    } catch (e) {
+      console.log(color.yellow(`[guard] Dashboard failed to start: ${e.message}`));
+    }
+  }
+
+  // ── Try event-driven mode (fs.watch) ───────────────────────────
+
+  let eventDriven = false;
+
+  try {
+    const watcher = fs.watch(projectDir, { recursive: true });
+    let debounceTimer = null;
+    let backupRunning = false;
+
+    function scheduleBackup() {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(async () => {
+        if (backupRunning) return;
+        backupRunning = true;
+        try { await backupCycle(); } catch (e) { logger.error(`Backup cycle error: ${e.message}`); }
+        backupRunning = false;
+      }, 500);
+    }
 
+    watcher.on('change', (_eventType, filename) => {
+      if (!filename) return;
+      const f = filename.replace(/\\/g, '/');
+      if (f.startsWith('.git/') || f.startsWith('.git\\')) return;
+      if (f.startsWith('.cursor-guard-backup')) return;
+      if (f === '.cursor-guard.json') {
+        hotReloadConfig();
+        return;
+      }
+      scheduleBackup();
+    });
+
+    watcher.on('error', (e) => {
+      logger.error(`fs.watch error: ${e.message}`);
+    });
+
+    const origCleanup = cleanup;
+    cleanup = function() { try { watcher.close(); } catch {} origCleanup(); };
+
+    eventDriven = true;
+
+    console.log('');
+    console.log(color.cyan(`[guard] Watching '${projectDir}' — event-driven (fs.watch + 30s heartbeat)`));
+    console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Ref: ${branchRef}  |  Retention: ${cfg.retention.mode}`));
+    console.log(color.cyan(`[guard] Log: ${logFilePath}`));
+    console.log('');
+
+    let hbCycle = 0;
+    while (true) {
+      await sleep(30000);
+      hbCycle++;
+      if (hbCycle % 2 === 0) await hotReloadConfig();
+      if (hbCycle % 4 === 0) {
+        try { await maintenanceCycle(); } catch (e) { logger.error(`Maintenance error: ${e.message}`); }
+      }
       clearExpiredAlert(projectDir);
     }
+  } catch (watchErr) {
+    if (!eventDriven) {
+      console.log(color.yellow(`[guard] fs.watch not available (${watchErr.message}), using ${interval}s polling fallback`));
+    }
+  }
+
+  // ── Polling fallback ───────────────────────────────────────────
+
+  if (!eventDriven) {
+    console.log('');
+    console.log(color.cyan(`[guard] Watching '${projectDir}' every ${interval}s  (Ctrl+C to stop)`));
+    console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Ref: ${branchRef}  |  Retention: ${cfg.retention.mode}`));
+    console.log(color.cyan(`[guard] Log: ${logFilePath}`));
+    console.log('');
+
+    let cycle = 0;
+    while (true) {
+      await sleep(interval * 1000);
+      cycle++;
+
+      if (cycle % 10 === 0) await hotReloadConfig();
+
+      try { await backupCycle(); } catch (e) { logger.error(`Backup cycle error: ${e.message}`); }
+
+      if (cycle % 10 === 0) {
+        try { await maintenanceCycle(); } catch (e) { logger.error(`Maintenance error: ${e.message}`); }
+      }
+    }
   }
 }
 

package/references/lib/core/snapshot.js

@@ -156,6 +156,7 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
             : 'M';
           const fileName = filePart.split('\t').pop();
           if (matchesAny(cfg.ignore, fileName) || matchesAny(cfg.ignore, path.basename(fileName))) continue;
+          if (cfg.protect.length > 0 && !matchesAny(cfg.protect, fileName, { strict: true })) continue;
           groups[key].push(fileName);
         }
         changedCount = Object.values(groups).reduce((sum, arr) => sum + arr.length, 0);
@@ -199,7 +200,8 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
       const lsInitial = git(['ls-tree', '--name-only', '-r', newTree], { cwd, allowFail: true });
       if (lsInitial) {
         const files = lsInitial.split('\n').filter(Boolean)
-          .filter(f => !matchesAny(cfg.ignore, f) && !matchesAny(cfg.ignore, path.basename(f)));
+          .filter(f => !matchesAny(cfg.ignore, f) && !matchesAny(cfg.ignore, path.basename(f)))
+          .filter(f => cfg.protect.length === 0 || matchesAny(cfg.protect, f, { strict: true }));
         changedCount = files.length;
         const sample = files.slice(0, 5).join(', ');
         incrementalSummary = `Added ${files.length}: ${sample}${files.length > 5 ? ', ...' : ''}`;

package/references/vscode-extension/dist/extension.js

@@ -189,6 +189,18 @@ async function activate(context) {
     vscode.window.showInformationMessage(`Cursor Guard: dashboard started on port ${dashMgr.port}`);
   }
 
+  // Event-driven UI refresh: FileSystemWatcher triggers immediate poller refresh
+  let _fsRefreshTimer = null;
+  const _scheduleRefresh = () => {
+    if (_fsRefreshTimer) clearTimeout(_fsRefreshTimer);
+    _fsRefreshTimer = setTimeout(() => poller.forceRefresh(), 1500);
+  };
+  const fileWatcher = vscode.workspace.createFileSystemWatcher('**/*', false, false, false);
+  fileWatcher.onDidChange(_scheduleRefresh);
+  fileWatcher.onDidCreate(_scheduleRefresh);
+  fileWatcher.onDidDelete(_scheduleRefresh);
+  context.subscriptions.push(fileWatcher);
+
   context.subscriptions.push(
     vscode.workspace.onDidChangeWorkspaceFolders(async () => {
       const restarted = await dashMgr.autoStart(vscode.workspace.workspaceFolders);

package/references/vscode-extension/dist/guard-version.json

@@ -1 +1 @@
-{"version":"4.8.4"}
+{"version":"4.9.0"}

package/references/vscode-extension/dist/lib/auto-backup.js

@@ -171,48 +171,24 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
     console.log(color.cyan(`[guard] Proactive alert: ON  (threshold: ${cfg.alert_thresholds.files_per_window} files / ${cfg.alert_thresholds.window_seconds}s)`));
   }
 
-  // Banner
-  console.log('');
-  console.log(color.cyan(`[guard] Watching '${projectDir}' every ${interval}s  (Ctrl+C to stop)`));
-  console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Ref: ${branchRef}  |  Retention: ${cfg.retention.mode}`));
-  console.log(color.cyan(`[guard] Log: ${logFilePath}`));
+  // ── Extracted cycle functions ──────────────────────────────────
 
-  // Optional embedded dashboard
-  if (opts.dashboardPort) {
+  async function hotReloadConfig() {
     try {
-      const { startDashboardServer } = require('../dashboard/server');
-      const { port } = await startDashboardServer([projectDir], { port: opts.dashboardPort, silent: true });
-      console.log(color.cyan(`[guard] Dashboard: http://127.0.0.1:${port}`));
-    } catch (e) {
-      console.log(color.yellow(`[guard] Dashboard failed to start: ${e.message}`));
-    }
-  }
-
-  console.log('');
-
-  // Main loop
-  let cycle = 0;
-  while (true) {
-    await sleep(interval * 1000);
-    cycle++;
-
-    // Hot-reload config every 10 cycles
-    if (cycle % 10 === 0) {
-      try {
-        const newMtime = fs.statSync(cfgPath).mtimeMs;
-        if (newMtime !== cfgMtime) {
-          const reload = loadConfig(projectDir);
-          if (reload.loaded && !reload.error) {
-            cfg = reload.cfg;
-            cfgMtime = newMtime;
-            tracker = createChangeTracker(cfg);
-            logger.info('Config reloaded (file changed)');
-          }
+      const newMtime = fs.statSync(cfgPath).mtimeMs;
+      if (newMtime !== cfgMtime) {
+        const reload = loadConfig(projectDir);
+        if (reload.loaded && !reload.error) {
+          cfg = reload.cfg;
+          cfgMtime = newMtime;
+          tracker = createChangeTracker(cfg);
+          logger.info('Config reloaded (file changed)');
         }
-      } catch { /* no config file or read error, keep current */ }
-    }
+      }
+    } catch { /* no config file or read error, keep current */ }
+  }
 
-    // Detect changes
+  async function backupCycle() {
     let hasChanges = false;
     let pendingManifest = null;
     let lastManifest = null;
@@ -230,11 +206,10 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
       }
     } catch (e) {
       logger.error(`Change detection failed: ${e.message}`);
-      continue;
+      return;
     }
-    if (!hasChanges) continue;
+    if (!hasChanges) return;
 
-    // Shadow: pre-compute changed file count from manifest diff (already accurate)
     let changedFileCount = 0;
     if (!repo && pendingManifest) {
       if (!lastManifest) {
@@ -253,7 +228,6 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
       }
     }
 
-    // Git snapshot via Core — changedFileCount comes from diff-tree (accurate incremental)
     let changedFiles;
     if ((cfg.backup_strategy === 'git' || cfg.backup_strategy === 'both') && repo) {
       const context = { trigger: 'auto' };
@@ -273,7 +247,6 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
       }
     }
 
-    // V4: Record change event and check for anomalies (after snapshot, using accurate count)
     recordChange(tracker, changedFileCount, changedFiles);
     const anomalyResult = checkAnomaly(tracker);
     if (anomalyResult.anomaly && anomalyResult.alert && !anomalyResult.suppressed) {
@@ -281,7 +254,6 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
       logger.warn(`ALERT: ${anomalyResult.alert.fileCount} files changed in ${anomalyResult.alert.windowSeconds}s (threshold: ${anomalyResult.alert.threshold})`);
     }
 
-    // Shadow copy via Core
     if (cfg.backup_strategy === 'shadow' || cfg.backup_strategy === 'both') {
       const shadowResult = createShadowCopy(projectDir, cfg, { backupDir });
       if (shadowResult.status === 'created') {
@@ -295,28 +267,125 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
         logger.error(`Shadow copy failed: ${shadowResult.error}`);
       }
     }
+  }
 
-    // Periodic retention every 10 cycles via Core
-    if (cycle % 10 === 0) {
-      const retResult = cleanShadowRetention(backupDir, cfg);
-      if (retResult.removed > 0) {
-        logger.log(`Retention (${retResult.mode}): cleaned ${retResult.removed} old snapshot(s)`, 'gray');
-      }
-      if (retResult.diskWarning === 'critically low') {
-        logger.error(`WARNING: disk critically low — ${retResult.diskFreeGB} GB free`);
-      } else if (retResult.diskWarning === 'low') {
-        logger.warn(`Disk note: ${retResult.diskFreeGB} GB free`);
-      }
+  async function maintenanceCycle() {
+    const retResult = cleanShadowRetention(backupDir, cfg);
+    if (retResult.removed > 0) {
+      logger.log(`Retention (${retResult.mode}): cleaned ${retResult.removed} old snapshot(s)`, 'gray');
+    }
+    if (retResult.diskWarning === 'critically low') {
+      logger.error(`WARNING: disk critically low — ${retResult.diskFreeGB} GB free`);
+    } else if (retResult.diskWarning === 'low') {
+      logger.warn(`Disk note: ${retResult.diskFreeGB} GB free`);
+    }
 
-      if (repo) {
-        const gitRetResult = cleanGitRetention(branchRef, gDir, cfg, projectDir);
-        if (gitRetResult.rebuilt) {
-          logger.log(`Git retention (${gitRetResult.mode}): rebuilt branch with ${gitRetResult.kept} newest snapshots, pruned ${gitRetResult.pruned}. Run 'git gc' to reclaim space.`, 'gray');
-        }
+    if (repo) {
+      const gitRetResult = cleanGitRetention(branchRef, gDir, cfg, projectDir);
+      if (gitRetResult.rebuilt) {
+        logger.log(`Git retention (${gitRetResult.mode}): rebuilt branch with ${gitRetResult.kept} newest snapshots, pruned ${gitRetResult.pruned}. Run 'git gc' to reclaim space.`, 'gray');
       }
+    }
+
+    clearExpiredAlert(projectDir);
+  }
+
+  // ── Optional embedded dashboard ────────────────────────────────
+
+  if (opts.dashboardPort) {
+    try {
+      const { startDashboardServer } = require('../dashboard/server');
+      const { port } = await startDashboardServer([projectDir], { port: opts.dashboardPort, silent: true });
+      console.log(color.cyan(`[guard] Dashboard: http://127.0.0.1:${port}`));
+    } catch (e) {
+      console.log(color.yellow(`[guard] Dashboard failed to start: ${e.message}`));
+    }
+  }
+
+  // ── Try event-driven mode (fs.watch) ───────────────────────────
+
+  let eventDriven = false;
+
+  try {
+    const watcher = fs.watch(projectDir, { recursive: true });
+    let debounceTimer = null;
+    let backupRunning = false;
+
+    function scheduleBackup() {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(async () => {
+        if (backupRunning) return;
+        backupRunning = true;
+        try { await backupCycle(); } catch (e) { logger.error(`Backup cycle error: ${e.message}`); }
+        backupRunning = false;
+      }, 500);
+    }
 
+    watcher.on('change', (_eventType, filename) => {
+      if (!filename) return;
+      const f = filename.replace(/\\/g, '/');
+      if (f.startsWith('.git/') || f.startsWith('.git\\')) return;
+      if (f.startsWith('.cursor-guard-backup')) return;
+      if (f === '.cursor-guard.json') {
+        hotReloadConfig();
+        return;
+      }
+      scheduleBackup();
+    });
+
+    watcher.on('error', (e) => {
+      logger.error(`fs.watch error: ${e.message}`);
+    });
+
+    const origCleanup = cleanup;
+    cleanup = function() { try { watcher.close(); } catch {} origCleanup(); };
+
+    eventDriven = true;
+
+    console.log('');
+    console.log(color.cyan(`[guard] Watching '${projectDir}' — event-driven (fs.watch + 30s heartbeat)`));
+    console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Ref: ${branchRef}  |  Retention: ${cfg.retention.mode}`));
+    console.log(color.cyan(`[guard] Log: ${logFilePath}`));
+    console.log('');
+
+    let hbCycle = 0;
+    while (true) {
+      await sleep(30000);
+      hbCycle++;
+      if (hbCycle % 2 === 0) await hotReloadConfig();
+      if (hbCycle % 4 === 0) {
+        try { await maintenanceCycle(); } catch (e) { logger.error(`Maintenance error: ${e.message}`); }
+      }
       clearExpiredAlert(projectDir);
     }
+  } catch (watchErr) {
+    if (!eventDriven) {
+      console.log(color.yellow(`[guard] fs.watch not available (${watchErr.message}), using ${interval}s polling fallback`));
+    }
+  }
+
+  // ── Polling fallback ───────────────────────────────────────────
+
+  if (!eventDriven) {
+    console.log('');
+    console.log(color.cyan(`[guard] Watching '${projectDir}' every ${interval}s  (Ctrl+C to stop)`));
+    console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Ref: ${branchRef}  |  Retention: ${cfg.retention.mode}`));
+    console.log(color.cyan(`[guard] Log: ${logFilePath}`));
+    console.log('');
+
+    let cycle = 0;
+    while (true) {
+      await sleep(interval * 1000);
+      cycle++;
+
+      if (cycle % 10 === 0) await hotReloadConfig();
+
+      try { await backupCycle(); } catch (e) { logger.error(`Backup cycle error: ${e.message}`); }
+
+      if (cycle % 10 === 0) {
+        try { await maintenanceCycle(); } catch (e) { logger.error(`Maintenance error: ${e.message}`); }
+      }
+    }
   }
 }
 

package/references/vscode-extension/dist/lib/core/snapshot.js

@@ -156,6 +156,7 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
             : 'M';
           const fileName = filePart.split('\t').pop();
           if (matchesAny(cfg.ignore, fileName) || matchesAny(cfg.ignore, path.basename(fileName))) continue;
+          if (cfg.protect.length > 0 && !matchesAny(cfg.protect, fileName, { strict: true })) continue;
           groups[key].push(fileName);
         }
         changedCount = Object.values(groups).reduce((sum, arr) => sum + arr.length, 0);
@@ -199,7 +200,8 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
       const lsInitial = git(['ls-tree', '--name-only', '-r', newTree], { cwd, allowFail: true });
       if (lsInitial) {
         const files = lsInitial.split('\n').filter(Boolean)
-          .filter(f => !matchesAny(cfg.ignore, f) && !matchesAny(cfg.ignore, path.basename(f)));
+          .filter(f => !matchesAny(cfg.ignore, f) && !matchesAny(cfg.ignore, path.basename(f)))
+          .filter(f => cfg.protect.length === 0 || matchesAny(cfg.protect, f, { strict: true }));
         changedCount = files.length;
         const sample = files.slice(0, 5).join(', ');
         incrementalSummary = `Added ${files.length}: ${sample}${files.length > 5 ? ', ...' : ''}`;

package/references/vscode-extension/dist/lib/poller.js

@@ -2,7 +2,7 @@
 
 const vscode = require('vscode');
 
-const POLL_INTERVAL = 5000;
+const HEARTBEAT_INTERVAL = 30000;
 
 class Poller {
   constructor(dashMgr) {
@@ -10,6 +10,7 @@ class Poller {
     this._timer = null;
     this._listeners = [];
     this._data = new Map();
+    this._pollRunning = false;
   }
 
   get data() { return this._data; }
@@ -28,7 +29,7 @@ class Poller {
   start() {
     if (this._timer) return;
     this._poll();
-    this._timer = setInterval(() => this._poll(), POLL_INTERVAL);
+    this._timer = setInterval(() => this._poll(), HEARTBEAT_INTERVAL);
   }
 
   stop() {
@@ -36,8 +37,10 @@ class Poller {
   }
 
   async _poll() {
-    if (!this._dashMgr.running) return;
+    if (this._pollRunning) return;
+    this._pollRunning = true;
     try {
+      if (!this._dashMgr.running) return;
       const projects = await this._dashMgr.getProjects();
       if (!Array.isArray(projects)) return;
       for (const p of projects) {
@@ -52,6 +55,7 @@ class Poller {
       }
       this._emit();
     } catch { /* non-critical */ }
+    finally { this._pollRunning = false; }
   }
 
   async forceRefresh() {

package/references/vscode-extension/dist/mcp/server.js

@@ -35568,7 +35568,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "cursor-guard",
-      version: "4.8.4",
+      version: "4.9.0",
       description: "Protects code from accidental AI overwrite or deletion in Cursor IDE \u2014 mandatory pre-write snapshots, review-before-apply, local Git safety net, and deterministic recovery. | \u4FDD\u62A4\u4EE3\u7801\u514D\u53D7 Cursor AI \u4EE3\u7406\u610F\u5916\u8986\u5199\u6216\u5220\u9664\u2014\u2014\u5F3A\u5236\u5199\u524D\u5FEB\u7167\u3001\u9884\u89C8\u518D\u6267\u884C\u3001\u672C\u5730 Git \u5B89\u5168\u7F51\u3001\u786E\u5B9A\u6027\u6062\u590D\u3002",
       keywords: [
         "cursor",
@@ -36096,6 +36096,7 @@ var require_snapshot = __commonJS({
               const key = code.startsWith("R") ? "R" : code === "D" ? "D" : code === "A" ? "A" : "M";
               const fileName = filePart.split("	").pop();
               if (matchesAny(cfg.ignore, fileName) || matchesAny(cfg.ignore, path2.basename(fileName))) continue;
+              if (cfg.protect.length > 0 && !matchesAny(cfg.protect, fileName, { strict: true })) continue;
               groups[key].push(fileName);
             }
             changedCount = Object.values(groups).reduce((sum, arr) => sum + arr.length, 0);
@@ -36127,7 +36128,7 @@ var require_snapshot = __commonJS({
         } else {
           const lsInitial = git(["ls-tree", "--name-only", "-r", newTree], { cwd, allowFail: true });
           if (lsInitial) {
-            const files = lsInitial.split("\n").filter(Boolean).filter((f) => !matchesAny(cfg.ignore, f) && !matchesAny(cfg.ignore, path2.basename(f)));
+            const files = lsInitial.split("\n").filter(Boolean).filter((f) => !matchesAny(cfg.ignore, f) && !matchesAny(cfg.ignore, path2.basename(f))).filter((f) => cfg.protect.length === 0 || matchesAny(cfg.protect, f, { strict: true }));
             changedCount = files.length;
             const sample = files.slice(0, 5).join(", ");
             incrementalSummary = `Added ${files.length}: ${sample}${files.length > 5 ? ", ..." : ""}`;

package/references/vscode-extension/dist/package.json

@@ -2,7 +2,7 @@
   "name": "cursor-guard-ide",
   "displayName": "Cursor Guard",
   "description": "AI code protection dashboard embedded in your IDE — real-time alerts, backup history, one-click snapshots",
-  "version": "4.8.4",
+  "version": "4.9.0",
   "publisher": "zhangqiang8vipp",
   "license": "BUSL-1.1",
   "engines": {

package/references/vscode-extension/dist/skill/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.8.4`  
-> **文档状态**：`V2` ~ `V4.8.4` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.9.0`  
+> **文档状态**：`V2` ~ `V4.9.0` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -734,6 +734,34 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
+### V4.9.0：事件驱动架构 — 从轮询到实时响应 ✅
+
+| 改造 | 说明 |
+|------|------|
+| **Watcher 事件驱动** | `auto-backup.js` 从 `while+sleep(N秒)` 盲轮询重构为 `fs.watch` 事件驱动。文件变化时 500ms 防抖后立即触发备份；无变化时零消耗。30s 心跳兜底负责配置热加载、retention 清理、告警过期 |
+| **轮询降级** | 若 `fs.watch` 不可用（如 Linux 旧内核），自动回退到原始轮询模式，保持向后兼容 |
+| **配置即时响应** | `.cursor-guard.json` 变化时 `fs.watch` 直接触发配置热加载，不再等待 10 个轮询周期 |
+| **IDE 侧 FileSystemWatcher** | 扩展使用 VSCode 内置 `createFileSystemWatcher` 监听文件变化，1.5s 防抖后触发 Poller 即时刷新 |
+| **Poller 心跳模式** | 从 5s 固定轮询改为 30s 心跳。UI 更新由 FileSystemWatcher 事件驱动，心跳仅做兜底健康同步 |
+| **UI 按需刷新** | Sidebar、StatusBar、TreeView 通过 `poller.onChange()` 订阅，只在有数据变化时才重绘，无变化时零消耗 |
+
+**性能对比**：
+
+| 指标 | v4.8.x (轮询) | v4.9.0 (事件驱动) |
+|------|---------------|------------------|
+| 备份响应延迟 | 最差 10s | < 500ms |
+| 无变化时 CPU | 每 10s 执行 git status | 零（idle） |
+| UI 刷新频率 | 每 5s 盲刷新 | 事件触发 + 30s 心跳 |
+| 新增依赖 | — | 零（fs.watch + VSCode 内置） |
+
+### V4.8.5：修复变更摘要中 protect 范围外文件误标为"删除"的 Bug ✅
+
+| 修复 | 说明 |
+|------|------|
+| **diff-tree 结果过滤 protect 范围** | 当 `protect` 配置非空时，`diff-tree` 对比上一次备份和当前备份的 tree 差异后，额外过滤掉不在 `protect` 范围内的文件。之前这些文件会被误标为"删除"（实际只是不在保护范围内） |
+| **根因** | 用户配置 `protect: ["src/**", "pom.xml"]` 后，`.cursor-guard.json`、`.gitignore`、`.cursor/mcp.json` 等文件不在保护范围内，当前 tree 不含这些文件。`diff-tree` 对比时将其报告为 `D`（删除），但代码只过滤了 `cfg.ignore` 未过滤 `cfg.protect` |
+| **影响** | 变更摘要不再出现"幽灵删除"，仅展示 protect 范围内文件的真实变更 |
+
 ### V4.8.4：已删除文件恢复命令自动指向父提交 ✅
 
 | 修复 | 说明 |

package/references/vscode-extension/extension.js

@@ -189,6 +189,18 @@ async function activate(context) {
     vscode.window.showInformationMessage(`Cursor Guard: dashboard started on port ${dashMgr.port}`);
   }
 
+  // Event-driven UI refresh: FileSystemWatcher triggers immediate poller refresh
+  let _fsRefreshTimer = null;
+  const _scheduleRefresh = () => {
+    if (_fsRefreshTimer) clearTimeout(_fsRefreshTimer);
+    _fsRefreshTimer = setTimeout(() => poller.forceRefresh(), 1500);
+  };
+  const fileWatcher = vscode.workspace.createFileSystemWatcher('**/*', false, false, false);
+  fileWatcher.onDidChange(_scheduleRefresh);
+  fileWatcher.onDidCreate(_scheduleRefresh);
+  fileWatcher.onDidDelete(_scheduleRefresh);
+  context.subscriptions.push(fileWatcher);
+
   context.subscriptions.push(
     vscode.workspace.onDidChangeWorkspaceFolders(async () => {
       const restarted = await dashMgr.autoStart(vscode.workspace.workspaceFolders);

package/references/vscode-extension/lib/poller.js

@@ -2,7 +2,7 @@
 
 const vscode = require('vscode');
 
-const POLL_INTERVAL = 5000;
+const HEARTBEAT_INTERVAL = 30000;
 
 class Poller {
   constructor(dashMgr) {
@@ -10,6 +10,7 @@ class Poller {
     this._timer = null;
     this._listeners = [];
     this._data = new Map();
+    this._pollRunning = false;
   }
 
   get data() { return this._data; }
@@ -28,7 +29,7 @@ class Poller {
   start() {
     if (this._timer) return;
     this._poll();
-    this._timer = setInterval(() => this._poll(), POLL_INTERVAL);
+    this._timer = setInterval(() => this._poll(), HEARTBEAT_INTERVAL);
   }
 
   stop() {
@@ -36,8 +37,10 @@ class Poller {
   }
 
   async _poll() {
-    if (!this._dashMgr.running) return;
+    if (this._pollRunning) return;
+    this._pollRunning = true;
     try {
+      if (!this._dashMgr.running) return;
       const projects = await this._dashMgr.getProjects();
       if (!Array.isArray(projects)) return;
       for (const p of projects) {
@@ -52,6 +55,7 @@ class Poller {
       }
       this._emit();
     } catch { /* non-critical */ }
+    finally { this._pollRunning = false; }
   }
 
   async forceRefresh() {

package/references/vscode-extension/package.json

@@ -2,7 +2,7 @@
   "name": "cursor-guard-ide",
   "displayName": "Cursor Guard",
   "description": "AI code protection dashboard embedded in your IDE — real-time alerts, backup history, one-click snapshots",
-  "version": "4.8.4",
+  "version": "4.9.0",
   "publisher": "zhangqiang8vipp",
   "license": "BUSL-1.1",
   "engines": {