cursor-guard 4.8.2 → 4.8.5

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.8.2`  
-> **文档状态**：`V2` ~ `V4.8.2` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.8.5`  
+> **文档状态**：`V2` ~ `V4.8.5` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -734,6 +734,30 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
+### 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：已删除文件恢复命令自动指向父提交 ✅
+
+| 修复 | 说明 |
+|------|------|
+| **删除文件恢复命令修正** | 当备份记录中文件 action 为 `D`（删除）时，恢复命令的 `source` 自动改为 `commitHash~1`（父提交，即删除前的版本）。之前指向删除后的 commit，导致恢复报错"文件不存在" |
+| **按钮文案区分** | 删除文件的恢复按钮显示"恢复删除前"（橙色边框），非删除文件显示"复制命令"（默认样式）。同时作用于 Modal 文件详情和 Drawer 文件表格 |
+| **i18n** | 新增 `modal.restorePreDelete` key（EN: "Restore pre-delete" / CN: "恢复删除前"） |
+
+### V4.8.3：Doctor MCP 检测修复 + Skill 目录 Junction 补全 ✅
+
+| 修复 | 说明 |
+|------|------|
+| **Doctor MCP 检查误报修复** | 之前只检查 `server.js` 文件存在性和 SDK `require.resolve`（esbuild bundle 后必然失败）。新增 `.cursor/mcp.json` 和 `.windsurf/mcp.json` 配置扫描（项目级 + 全局级），如果 `cursor-guard` 已注册则直接 PASS，显示 `registered in .cursor/mcp.json (bundled mode)` |
+| **Skill 目录 junction 补全** | v4.8.2 的 `autoInstallSkill` 有 `if (SKILL.md exists) return` 早退逻辑，导致已安装的旧目录永远不会创建 junction。重构为独立检查：即使 SKILL.md 已存在，仍检测 `references/` 是否为 junction、是否缺少 `mcp/` 运行时目录，不满足则删除旧纯文档目录并重建 junction |
+| **package.json 安装增强** | 优先从根 `package.json` 复制，fallback 到 `guard-version.json` |
+
 ### V4.8.2：Skill 目录运行时完整安装 ✅
 
 | 修复 | 说明 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.8.2",
+  "version": "4.8.5",
   "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/dashboard/public/app.js

@@ -65,6 +65,7 @@ const I18N = {
     'modal.alertFiles':      'Alert File Details',
     'modal.col.restore':     'Restore',
     'modal.copyRestore':     'Copy cmd',
+    'modal.restorePreDelete':'Restore pre-delete',
     'modal.copied':          'Copied!',
 
     'backups.gitCommits':       'Git Commits',
@@ -292,6 +293,7 @@ const I18N = {
     'modal.alertFiles':      '告警文件详情',
     'modal.col.restore':     '恢复',
     'modal.copyRestore':     '复制命令',
+    'modal.restorePreDelete':'恢复删除前',
     'modal.copied':          '已复制！',
 
     'backups.gitCommits':       'Git 提交数',
@@ -1306,14 +1308,17 @@ function openFileModal(title, files, projectPath, commitHash) {
     else sorted.sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted));
 
     const rows = sorted.map(f => {
-      const restoreCmd = commitHash
-        ? `restore_file({ path: "${projectPath || ''}", file: "${f.path}", source: "${commitHash}" })`
+      const isDeleted = f.action === 'D';
+      const source = isDeleted && commitHash ? `${commitHash}~1` : commitHash;
+      const restoreCmd = source
+        ? `restore_file({ path: "${projectPath || ''}", file: "${f.path}", source: "${source}" })`
         : '';
+      const btnLabel = isDeleted ? t('modal.restorePreDelete') : t('modal.copyRestore');
       return `<tr>
         <td class="text-mono modal-file-path" title="${esc(f.path)}">${esc(f.path)}</td>
         <td>${formatFileActionBadge(f.action)}</td>
         <td class="text-mono modal-file-changes">+${f.added || 0} -${f.deleted || 0}</td>
-        ${commitHash ? `<td><button class="modal-restore-btn" data-restore-cmd="${esc(restoreCmd)}">${t('modal.copyRestore')}</button></td>` : ''}
+        ${commitHash ? `<td><button class="modal-restore-btn${isDeleted ? ' btn-deleted' : ''}" data-restore-cmd="${esc(restoreCmd)}">${btnLabel}</button></td>` : ''}
       </tr>`;
     }).join('');
 
@@ -1339,9 +1344,10 @@ function openFileModal(title, files, projectPath, commitHash) {
     const btn = e.target.closest('[data-restore-cmd]');
     if (btn) {
       copyText(btn.dataset.restoreCmd);
+      const origLabel = btn.classList.contains('btn-deleted') ? t('modal.restorePreDelete') : t('modal.copyRestore');
       btn.textContent = t('modal.copied');
       btn.classList.add('copied');
-      setTimeout(() => { btn.textContent = t('modal.copyRestore'); btn.classList.remove('copied'); }, 1500);
+      setTimeout(() => { btn.textContent = origLabel; btn.classList.remove('copied'); }, 1500);
     }
   });
 
@@ -1378,12 +1384,15 @@ function renderDrawerFilesTable(files, sortKey, commitHash, projectPath) {
   else sorted.sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted));
   const hasRestore = !!commitHash;
   const rows = sorted.map(f => {
-    const cmd = hasRestore ? `restore_file({ path: "${projectPath || ''}", file: "${f.path}", source: "${commitHash}" })` : '';
+    const isDeleted = f.action === 'D';
+    const source = isDeleted && commitHash ? `${commitHash}~1` : commitHash;
+    const cmd = hasRestore ? `restore_file({ path: "${projectPath || ''}", file: "${f.path}", source: "${source}" })` : '';
+    const btnLabel = isDeleted ? t('modal.restorePreDelete') : t('modal.copyRestore');
     return `<tr>
       <td class="text-mono drawer-file-path">${esc(f.path)}</td>
       <td>${formatFileActionBadge(f.action)}</td>
       <td class="text-mono drawer-file-changes">+${f.added} -${f.deleted}</td>
-      ${hasRestore ? `<td><button class="modal-restore-btn" data-restore-cmd="${esc(cmd)}">${t('modal.copyRestore')}</button></td>` : ''}
+      ${hasRestore ? `<td><button class="modal-restore-btn${isDeleted ? ' btn-deleted' : ''}" data-restore-cmd="${esc(cmd)}">${btnLabel}</button></td>` : ''}
     </tr>`;
   }).join('');
   return `<table class="drawer-files-table">
@@ -1490,9 +1499,10 @@ function openRestoreDrawer(backup) {
         const restoreBtn = e.target.closest('[data-restore-cmd]');
         if (restoreBtn) {
           copyText(restoreBtn.dataset.restoreCmd);
+          const origLabel = restoreBtn.classList.contains('btn-deleted') ? t('modal.restorePreDelete') : t('modal.copyRestore');
           restoreBtn.textContent = t('modal.copied');
           restoreBtn.classList.add('copied');
-          setTimeout(() => { restoreBtn.textContent = t('modal.copyRestore'); restoreBtn.classList.remove('copied'); }, 1500);
+          setTimeout(() => { restoreBtn.textContent = origLabel; restoreBtn.classList.remove('copied'); }, 1500);
         }
       });
     };

package/references/dashboard/public/style.css

@@ -1443,6 +1443,15 @@ main {
   color: #fff;
   border-color: var(--green);
 }
+.modal-restore-btn.btn-deleted {
+  border-color: var(--orange, #f0ad4e);
+  color: var(--orange, #f0ad4e);
+}
+.modal-restore-btn.btn-deleted:hover {
+  background: var(--orange, #f0ad4e);
+  color: #fff;
+  border-color: var(--orange, #f0ad4e);
+}
 
 /* ── Responsive ───────────────────────────────────────────── */
 

package/references/lib/core/doctor.js

@@ -253,49 +253,69 @@ function runDiagnostics(projectDir) {
   }
 
   // 14. MCP server status
+  // Strategy: check multiple sources — mcp.json config, local server.js, SDK availability
   const mcpServerPath = path.resolve(__dirname, '../../mcp/server.js');
   const mcpServerExists = fs.existsSync(mcpServerPath);
 
+  // Check if cursor-guard is registered in any mcp.json (project or global)
+  let mcpConfigured = false;
+  let mcpConfigSource = '';
+  const home = process.env.USERPROFILE || process.env.HOME || '';
+  const mcpJsonCandidates = [
+    projectDir ? path.join(projectDir, '.cursor', 'mcp.json') : null,
+    projectDir ? path.join(projectDir, '.windsurf', 'mcp.json') : null,
+    path.join(home, '.cursor', 'mcp.json'),
+    path.join(home, '.windsurf', 'mcp.json'),
+  ].filter(Boolean);
+  for (const mcpJsonPath of mcpJsonCandidates) {
+    try {
+      if (!fs.existsSync(mcpJsonPath)) continue;
+      const mcpJson = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8'));
+      if (mcpJson.mcpServers?.['cursor-guard']) {
+        mcpConfigured = true;
+        mcpConfigSource = path.relative(projectDir || home, mcpJsonPath);
+        break;
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Check SDK availability (for non-bundled installations)
   let mcpSdkAvailable = false;
   let mcpSdkVersion = null;
   const skillRoot = path.resolve(__dirname, '../../..');
-  // Search multiple candidate locations for SDK package.json
   const sdkCandidates = [
     path.join(skillRoot, 'node_modules', '@modelcontextprotocol', 'sdk', 'package.json'),
   ];
   for (const candidate of sdkCandidates) {
     try {
-      const resolved = path.resolve(candidate);
-      if (fs.existsSync(resolved)) {
-        const mcpPkg = JSON.parse(fs.readFileSync(resolved, 'utf-8'));
+      if (fs.existsSync(candidate)) {
+        mcpSdkVersion = JSON.parse(fs.readFileSync(candidate, 'utf-8')).version;
         mcpSdkAvailable = true;
-        mcpSdkVersion = mcpPkg.version;
         break;
       }
     } catch { /* ignore */ }
   }
   if (!mcpSdkAvailable) {
-    // Fallback: try require.resolve from Node's module paths.
-    // Some SDK versions restrict subpath access via exports, so try
-    // the main entry first and derive the package.json from it.
     try {
       const mainPath = require.resolve('@modelcontextprotocol/sdk');
       const sdkDir = mainPath.replace(/[/\\]dist[/\\].*$/, '').replace(/[/\\]src[/\\].*$/, '');
       const pkgPath = path.join(sdkDir, 'package.json');
       if (fs.existsSync(pkgPath)) {
-        const mcpPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        mcpSdkVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
         mcpSdkAvailable = true;
-        mcpSdkVersion = mcpPkg.version;
       }
     } catch { /* not installed */ }
   }
 
-  if (mcpServerExists && mcpSdkAvailable) {
+  if (mcpConfigured) {
+    const detail = mcpSdkAvailable
+      ? `registered in ${mcpConfigSource}, SDK ${mcpSdkVersion}`
+      : `registered in ${mcpConfigSource} (bundled mode)`;
+    check('MCP server', 'PASS', detail);
+  } else if (mcpServerExists && mcpSdkAvailable) {
     check('MCP server', 'PASS', `server.js found, SDK ${mcpSdkVersion}`);
   } else if (mcpServerExists && !mcpSdkAvailable) {
     check('MCP server', 'WARN', 'server.js found but @modelcontextprotocol/sdk not installed — run: cd <skill-dir> && npm install');
-  } else if (!mcpServerExists && mcpSdkAvailable) {
-    check('MCP server', 'WARN', `SDK installed (${mcpSdkVersion}) but server.js not found at expected path`);
   } else {
     check('MCP server', 'WARN', 'MCP not configured (optional — cursor-guard works without it)');
   }

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/dashboard/public/app.js

@@ -65,6 +65,7 @@ const I18N = {
     'modal.alertFiles':      'Alert File Details',
     'modal.col.restore':     'Restore',
     'modal.copyRestore':     'Copy cmd',
+    'modal.restorePreDelete':'Restore pre-delete',
     'modal.copied':          'Copied!',
 
     'backups.gitCommits':       'Git Commits',
@@ -292,6 +293,7 @@ const I18N = {
     'modal.alertFiles':      '告警文件详情',
     'modal.col.restore':     '恢复',
     'modal.copyRestore':     '复制命令',
+    'modal.restorePreDelete':'恢复删除前',
     'modal.copied':          '已复制！',
 
     'backups.gitCommits':       'Git 提交数',
@@ -1306,14 +1308,17 @@ function openFileModal(title, files, projectPath, commitHash) {
     else sorted.sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted));
 
     const rows = sorted.map(f => {
-      const restoreCmd = commitHash
-        ? `restore_file({ path: "${projectPath || ''}", file: "${f.path}", source: "${commitHash}" })`
+      const isDeleted = f.action === 'D';
+      const source = isDeleted && commitHash ? `${commitHash}~1` : commitHash;
+      const restoreCmd = source
+        ? `restore_file({ path: "${projectPath || ''}", file: "${f.path}", source: "${source}" })`
         : '';
+      const btnLabel = isDeleted ? t('modal.restorePreDelete') : t('modal.copyRestore');
       return `<tr>
         <td class="text-mono modal-file-path" title="${esc(f.path)}">${esc(f.path)}</td>
         <td>${formatFileActionBadge(f.action)}</td>
         <td class="text-mono modal-file-changes">+${f.added || 0} -${f.deleted || 0}</td>
-        ${commitHash ? `<td><button class="modal-restore-btn" data-restore-cmd="${esc(restoreCmd)}">${t('modal.copyRestore')}</button></td>` : ''}
+        ${commitHash ? `<td><button class="modal-restore-btn${isDeleted ? ' btn-deleted' : ''}" data-restore-cmd="${esc(restoreCmd)}">${btnLabel}</button></td>` : ''}
       </tr>`;
     }).join('');
 
@@ -1339,9 +1344,10 @@ function openFileModal(title, files, projectPath, commitHash) {
     const btn = e.target.closest('[data-restore-cmd]');
     if (btn) {
       copyText(btn.dataset.restoreCmd);
+      const origLabel = btn.classList.contains('btn-deleted') ? t('modal.restorePreDelete') : t('modal.copyRestore');
       btn.textContent = t('modal.copied');
       btn.classList.add('copied');
-      setTimeout(() => { btn.textContent = t('modal.copyRestore'); btn.classList.remove('copied'); }, 1500);
+      setTimeout(() => { btn.textContent = origLabel; btn.classList.remove('copied'); }, 1500);
     }
   });
 
@@ -1378,12 +1384,15 @@ function renderDrawerFilesTable(files, sortKey, commitHash, projectPath) {
   else sorted.sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted));
   const hasRestore = !!commitHash;
   const rows = sorted.map(f => {
-    const cmd = hasRestore ? `restore_file({ path: "${projectPath || ''}", file: "${f.path}", source: "${commitHash}" })` : '';
+    const isDeleted = f.action === 'D';
+    const source = isDeleted && commitHash ? `${commitHash}~1` : commitHash;
+    const cmd = hasRestore ? `restore_file({ path: "${projectPath || ''}", file: "${f.path}", source: "${source}" })` : '';
+    const btnLabel = isDeleted ? t('modal.restorePreDelete') : t('modal.copyRestore');
     return `<tr>
       <td class="text-mono drawer-file-path">${esc(f.path)}</td>
       <td>${formatFileActionBadge(f.action)}</td>
       <td class="text-mono drawer-file-changes">+${f.added} -${f.deleted}</td>
-      ${hasRestore ? `<td><button class="modal-restore-btn" data-restore-cmd="${esc(cmd)}">${t('modal.copyRestore')}</button></td>` : ''}
+      ${hasRestore ? `<td><button class="modal-restore-btn${isDeleted ? ' btn-deleted' : ''}" data-restore-cmd="${esc(cmd)}">${btnLabel}</button></td>` : ''}
     </tr>`;
   }).join('');
   return `<table class="drawer-files-table">
@@ -1490,9 +1499,10 @@ function openRestoreDrawer(backup) {
         const restoreBtn = e.target.closest('[data-restore-cmd]');
         if (restoreBtn) {
           copyText(restoreBtn.dataset.restoreCmd);
+          const origLabel = restoreBtn.classList.contains('btn-deleted') ? t('modal.restorePreDelete') : t('modal.copyRestore');
           restoreBtn.textContent = t('modal.copied');
           restoreBtn.classList.add('copied');
-          setTimeout(() => { restoreBtn.textContent = t('modal.copyRestore'); restoreBtn.classList.remove('copied'); }, 1500);
+          setTimeout(() => { restoreBtn.textContent = origLabel; restoreBtn.classList.remove('copied'); }, 1500);
         }
       });
     };

package/references/vscode-extension/dist/dashboard/public/style.css

@@ -1443,6 +1443,15 @@ main {
   color: #fff;
   border-color: var(--green);
 }
+.modal-restore-btn.btn-deleted {
+  border-color: var(--orange, #f0ad4e);
+  color: var(--orange, #f0ad4e);
+}
+.modal-restore-btn.btn-deleted:hover {
+  background: var(--orange, #f0ad4e);
+  color: #fff;
+  border-color: var(--orange, #f0ad4e);
+}
 
 /* ── Responsive ───────────────────────────────────────────── */
 

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

@@ -1 +1 @@
-{"version":"4.8.2"}
+{"version":"4.8.5"}

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

@@ -67,47 +67,64 @@ function autoInstallSkill(extRoot, homePath, dirName) {
   if (!skillSrc) return actions;
 
   const skillTarget = path.join(homePath, 'skills', 'cursor-guard');
-  const skillMdTarget = path.join(skillTarget, 'SKILL.md');
-
-  if (fs.existsSync(skillMdTarget)) return actions;
-
   fs.mkdirSync(skillTarget, { recursive: true });
 
+  // ── Install/update SKILL.md and ROADMAP.md ──
   const skillMdSrc = path.join(skillSrc, 'SKILL.md');
-  if (fs.existsSync(skillMdSrc)) {
+  const skillMdTarget = path.join(skillTarget, 'SKILL.md');
+  if (fs.existsSync(skillMdSrc) && !fs.existsSync(skillMdTarget)) {
     fs.copyFileSync(skillMdSrc, skillMdTarget);
     actions.push('SKILL.md installed');
   }
 
   const roadmapSrc = path.join(skillSrc, 'ROADMAP.md');
-  if (fs.existsSync(roadmapSrc)) {
-    fs.copyFileSync(roadmapSrc, path.join(skillTarget, 'ROADMAP.md'));
+  const roadmapDst = path.join(skillTarget, 'ROADMAP.md');
+  if (fs.existsSync(roadmapSrc) && !fs.existsSync(roadmapDst)) {
+    fs.copyFileSync(roadmapSrc, roadmapDst);
   }
 
-  // Link references/ → extension directory so SKILL.md paths resolve correctly
-  // (mcp/server.js, lib/core/*, dashboard/, bin/ etc.)
+  // ── Ensure references/ junction exists (runs even for existing installations) ──
   const refsTarget = path.join(skillTarget, 'references');
-  if (!fs.existsSync(refsTarget)) {
+  const refsIsJunction = _isSymlinkOrJunction(refsTarget);
+  const refsIsPlainDir = !refsIsJunction && fs.existsSync(refsTarget);
+  const refsMissingRuntime = refsIsPlainDir && !fs.existsSync(path.join(refsTarget, 'mcp'));
+
+  if (!fs.existsSync(refsTarget) || refsMissingRuntime) {
+    // Remove old plain directory if it only has docs (no runtime)
+    if (refsMissingRuntime) {
+      try { fs.rmSync(refsTarget, { recursive: true, force: true }); } catch { /* ok */ }
+    }
     try {
       fs.symlinkSync(extRoot, refsTarget, 'junction');
       actions.push('references/ linked');
     } catch {
-      // junction failed (rare) — fall back to copying essential docs only
       fs.mkdirSync(refsTarget, { recursive: true });
       _copyDocFiles(skillSrc, refsTarget);
     }
   }
 
-  // Copy package.json so `require('../../package.json')` in source mode works
-  const pkgSrc = path.join(extRoot, '..', '..', 'package.json');
+  // ── Ensure package.json exists ──
   const pkgDst = path.join(skillTarget, 'package.json');
-  if (fs.existsSync(pkgSrc) && !fs.existsSync(pkgDst)) {
-    fs.copyFileSync(pkgSrc, pkgDst);
+  if (!fs.existsSync(pkgDst)) {
+    const pkgSrc = path.join(extRoot, '..', '..', 'package.json');
+    const guardVer = path.join(extRoot, 'guard-version.json');
+    if (fs.existsSync(pkgSrc)) {
+      fs.copyFileSync(pkgSrc, pkgDst);
+    } else if (fs.existsSync(guardVer)) {
+      fs.copyFileSync(guardVer, pkgDst);
+    }
   }
 
   return actions;
 }
 
+function _isSymlinkOrJunction(p) {
+  try {
+    const stat = fs.lstatSync(p);
+    return stat.isSymbolicLink();
+  } catch { return false; }
+}
+
 function _copyDocFiles(skillSrc, refsTarget) {
   const docs = [
     'config-reference.md', 'config-reference.zh-CN.md',

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

@@ -253,49 +253,69 @@ function runDiagnostics(projectDir) {
   }
 
   // 14. MCP server status
+  // Strategy: check multiple sources — mcp.json config, local server.js, SDK availability
   const mcpServerPath = path.resolve(__dirname, '../../mcp/server.js');
   const mcpServerExists = fs.existsSync(mcpServerPath);
 
+  // Check if cursor-guard is registered in any mcp.json (project or global)
+  let mcpConfigured = false;
+  let mcpConfigSource = '';
+  const home = process.env.USERPROFILE || process.env.HOME || '';
+  const mcpJsonCandidates = [
+    projectDir ? path.join(projectDir, '.cursor', 'mcp.json') : null,
+    projectDir ? path.join(projectDir, '.windsurf', 'mcp.json') : null,
+    path.join(home, '.cursor', 'mcp.json'),
+    path.join(home, '.windsurf', 'mcp.json'),
+  ].filter(Boolean);
+  for (const mcpJsonPath of mcpJsonCandidates) {
+    try {
+      if (!fs.existsSync(mcpJsonPath)) continue;
+      const mcpJson = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8'));
+      if (mcpJson.mcpServers?.['cursor-guard']) {
+        mcpConfigured = true;
+        mcpConfigSource = path.relative(projectDir || home, mcpJsonPath);
+        break;
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Check SDK availability (for non-bundled installations)
   let mcpSdkAvailable = false;
   let mcpSdkVersion = null;
   const skillRoot = path.resolve(__dirname, '../../..');
-  // Search multiple candidate locations for SDK package.json
   const sdkCandidates = [
     path.join(skillRoot, 'node_modules', '@modelcontextprotocol', 'sdk', 'package.json'),
   ];
   for (const candidate of sdkCandidates) {
     try {
-      const resolved = path.resolve(candidate);
-      if (fs.existsSync(resolved)) {
-        const mcpPkg = JSON.parse(fs.readFileSync(resolved, 'utf-8'));
+      if (fs.existsSync(candidate)) {
+        mcpSdkVersion = JSON.parse(fs.readFileSync(candidate, 'utf-8')).version;
         mcpSdkAvailable = true;
-        mcpSdkVersion = mcpPkg.version;
         break;
       }
     } catch { /* ignore */ }
   }
   if (!mcpSdkAvailable) {
-    // Fallback: try require.resolve from Node's module paths.
-    // Some SDK versions restrict subpath access via exports, so try
-    // the main entry first and derive the package.json from it.
     try {
       const mainPath = require.resolve('@modelcontextprotocol/sdk');
       const sdkDir = mainPath.replace(/[/\\]dist[/\\].*$/, '').replace(/[/\\]src[/\\].*$/, '');
       const pkgPath = path.join(sdkDir, 'package.json');
       if (fs.existsSync(pkgPath)) {
-        const mcpPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        mcpSdkVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
         mcpSdkAvailable = true;
-        mcpSdkVersion = mcpPkg.version;
       }
     } catch { /* not installed */ }
   }
 
-  if (mcpServerExists && mcpSdkAvailable) {
+  if (mcpConfigured) {
+    const detail = mcpSdkAvailable
+      ? `registered in ${mcpConfigSource}, SDK ${mcpSdkVersion}`
+      : `registered in ${mcpConfigSource} (bundled mode)`;
+    check('MCP server', 'PASS', detail);
+  } else if (mcpServerExists && mcpSdkAvailable) {
     check('MCP server', 'PASS', `server.js found, SDK ${mcpSdkVersion}`);
   } else if (mcpServerExists && !mcpSdkAvailable) {
     check('MCP server', 'WARN', 'server.js found but @modelcontextprotocol/sdk not installed — run: cd <skill-dir> && npm install');
-  } else if (!mcpServerExists && mcpSdkAvailable) {
-    check('MCP server', 'WARN', `SDK installed (${mcpSdkVersion}) but server.js not found at expected path`);
   } else {
     check('MCP server', 'WARN', 'MCP not configured (optional — cursor-guard works without it)');
   }

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/mcp/server.js

@@ -35568,7 +35568,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "cursor-guard",
-      version: "4.8.2",
+      version: "4.8.5",
       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",
@@ -35875,6 +35875,27 @@ var require_doctor = __commonJS({
       }
       const mcpServerPath = path2.resolve(__dirname, "../../mcp/server.js");
       const mcpServerExists = fs.existsSync(mcpServerPath);
+      let mcpConfigured = false;
+      let mcpConfigSource = "";
+      const home = process.env.USERPROFILE || process.env.HOME || "";
+      const mcpJsonCandidates = [
+        projectDir ? path2.join(projectDir, ".cursor", "mcp.json") : null,
+        projectDir ? path2.join(projectDir, ".windsurf", "mcp.json") : null,
+        path2.join(home, ".cursor", "mcp.json"),
+        path2.join(home, ".windsurf", "mcp.json")
+      ].filter(Boolean);
+      for (const mcpJsonPath of mcpJsonCandidates) {
+        try {
+          if (!fs.existsSync(mcpJsonPath)) continue;
+          const mcpJson = JSON.parse(fs.readFileSync(mcpJsonPath, "utf-8"));
+          if (mcpJson.mcpServers?.["cursor-guard"]) {
+            mcpConfigured = true;
+            mcpConfigSource = path2.relative(projectDir || home, mcpJsonPath);
+            break;
+          }
+        } catch {
+        }
+      }
       let mcpSdkAvailable = false;
       let mcpSdkVersion = null;
       const skillRoot = path2.resolve(__dirname, "../../..");
@@ -35883,11 +35904,9 @@ var require_doctor = __commonJS({
       ];
       for (const candidate of sdkCandidates) {
         try {
-          const resolved = path2.resolve(candidate);
-          if (fs.existsSync(resolved)) {
-            const mcpPkg = JSON.parse(fs.readFileSync(resolved, "utf-8"));
+          if (fs.existsSync(candidate)) {
+            mcpSdkVersion = JSON.parse(fs.readFileSync(candidate, "utf-8")).version;
             mcpSdkAvailable = true;
-            mcpSdkVersion = mcpPkg.version;
             break;
           }
         } catch {
@@ -35899,19 +35918,19 @@ var require_doctor = __commonJS({
           const sdkDir = mainPath.replace(/[/\\]dist[/\\].*$/, "").replace(/[/\\]src[/\\].*$/, "");
           const pkgPath = path2.join(sdkDir, "package.json");
           if (fs.existsSync(pkgPath)) {
-            const mcpPkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            mcpSdkVersion = JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version;
             mcpSdkAvailable = true;
-            mcpSdkVersion = mcpPkg.version;
           }
         } catch {
         }
       }
-      if (mcpServerExists && mcpSdkAvailable) {
+      if (mcpConfigured) {
+        const detail = mcpSdkAvailable ? `registered in ${mcpConfigSource}, SDK ${mcpSdkVersion}` : `registered in ${mcpConfigSource} (bundled mode)`;
+        check("MCP server", "PASS", detail);
+      } else if (mcpServerExists && mcpSdkAvailable) {
         check("MCP server", "PASS", `server.js found, SDK ${mcpSdkVersion}`);
       } else if (mcpServerExists && !mcpSdkAvailable) {
         check("MCP server", "WARN", "server.js found but @modelcontextprotocol/sdk not installed \u2014 run: cd <skill-dir> && npm install");
-      } else if (!mcpServerExists && mcpSdkAvailable) {
-        check("MCP server", "WARN", `SDK installed (${mcpSdkVersion}) but server.js not found at expected path`);
       } else {
         check("MCP server", "WARN", "MCP not configured (optional \u2014 cursor-guard works without it)");
       }
@@ -36077,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);
@@ -36108,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.2",
+  "version": "4.8.5",
   "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.2`  
-> **文档状态**：`V2` ~ `V4.8.2` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.8.5`  
+> **文档状态**：`V2` ~ `V4.8.5` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -734,6 +734,30 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
+### 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：已删除文件恢复命令自动指向父提交 ✅
+
+| 修复 | 说明 |
+|------|------|
+| **删除文件恢复命令修正** | 当备份记录中文件 action 为 `D`（删除）时，恢复命令的 `source` 自动改为 `commitHash~1`（父提交，即删除前的版本）。之前指向删除后的 commit，导致恢复报错"文件不存在" |
+| **按钮文案区分** | 删除文件的恢复按钮显示"恢复删除前"（橙色边框），非删除文件显示"复制命令"（默认样式）。同时作用于 Modal 文件详情和 Drawer 文件表格 |
+| **i18n** | 新增 `modal.restorePreDelete` key（EN: "Restore pre-delete" / CN: "恢复删除前"） |
+
+### V4.8.3：Doctor MCP 检测修复 + Skill 目录 Junction 补全 ✅
+
+| 修复 | 说明 |
+|------|------|
+| **Doctor MCP 检查误报修复** | 之前只检查 `server.js` 文件存在性和 SDK `require.resolve`（esbuild bundle 后必然失败）。新增 `.cursor/mcp.json` 和 `.windsurf/mcp.json` 配置扫描（项目级 + 全局级），如果 `cursor-guard` 已注册则直接 PASS，显示 `registered in .cursor/mcp.json (bundled mode)` |
+| **Skill 目录 junction 补全** | v4.8.2 的 `autoInstallSkill` 有 `if (SKILL.md exists) return` 早退逻辑，导致已安装的旧目录永远不会创建 junction。重构为独立检查：即使 SKILL.md 已存在，仍检测 `references/` 是否为 junction、是否缺少 `mcp/` 运行时目录，不满足则删除旧纯文档目录并重建 junction |
+| **package.json 安装增强** | 优先从根 `package.json` 复制，fallback 到 `guard-version.json` |
+
 ### V4.8.2：Skill 目录运行时完整安装 ✅
 
 | 修复 | 说明 |

package/references/vscode-extension/lib/auto-setup.js

@@ -67,47 +67,64 @@ function autoInstallSkill(extRoot, homePath, dirName) {
   if (!skillSrc) return actions;
 
   const skillTarget = path.join(homePath, 'skills', 'cursor-guard');
-  const skillMdTarget = path.join(skillTarget, 'SKILL.md');
-
-  if (fs.existsSync(skillMdTarget)) return actions;
-
   fs.mkdirSync(skillTarget, { recursive: true });
 
+  // ── Install/update SKILL.md and ROADMAP.md ──
   const skillMdSrc = path.join(skillSrc, 'SKILL.md');
-  if (fs.existsSync(skillMdSrc)) {
+  const skillMdTarget = path.join(skillTarget, 'SKILL.md');
+  if (fs.existsSync(skillMdSrc) && !fs.existsSync(skillMdTarget)) {
     fs.copyFileSync(skillMdSrc, skillMdTarget);
     actions.push('SKILL.md installed');
   }
 
   const roadmapSrc = path.join(skillSrc, 'ROADMAP.md');
-  if (fs.existsSync(roadmapSrc)) {
-    fs.copyFileSync(roadmapSrc, path.join(skillTarget, 'ROADMAP.md'));
+  const roadmapDst = path.join(skillTarget, 'ROADMAP.md');
+  if (fs.existsSync(roadmapSrc) && !fs.existsSync(roadmapDst)) {
+    fs.copyFileSync(roadmapSrc, roadmapDst);
   }
 
-  // Link references/ → extension directory so SKILL.md paths resolve correctly
-  // (mcp/server.js, lib/core/*, dashboard/, bin/ etc.)
+  // ── Ensure references/ junction exists (runs even for existing installations) ──
   const refsTarget = path.join(skillTarget, 'references');
-  if (!fs.existsSync(refsTarget)) {
+  const refsIsJunction = _isSymlinkOrJunction(refsTarget);
+  const refsIsPlainDir = !refsIsJunction && fs.existsSync(refsTarget);
+  const refsMissingRuntime = refsIsPlainDir && !fs.existsSync(path.join(refsTarget, 'mcp'));
+
+  if (!fs.existsSync(refsTarget) || refsMissingRuntime) {
+    // Remove old plain directory if it only has docs (no runtime)
+    if (refsMissingRuntime) {
+      try { fs.rmSync(refsTarget, { recursive: true, force: true }); } catch { /* ok */ }
+    }
     try {
       fs.symlinkSync(extRoot, refsTarget, 'junction');
       actions.push('references/ linked');
     } catch {
-      // junction failed (rare) — fall back to copying essential docs only
       fs.mkdirSync(refsTarget, { recursive: true });
       _copyDocFiles(skillSrc, refsTarget);
     }
   }
 
-  // Copy package.json so `require('../../package.json')` in source mode works
-  const pkgSrc = path.join(extRoot, '..', '..', 'package.json');
+  // ── Ensure package.json exists ──
   const pkgDst = path.join(skillTarget, 'package.json');
-  if (fs.existsSync(pkgSrc) && !fs.existsSync(pkgDst)) {
-    fs.copyFileSync(pkgSrc, pkgDst);
+  if (!fs.existsSync(pkgDst)) {
+    const pkgSrc = path.join(extRoot, '..', '..', 'package.json');
+    const guardVer = path.join(extRoot, 'guard-version.json');
+    if (fs.existsSync(pkgSrc)) {
+      fs.copyFileSync(pkgSrc, pkgDst);
+    } else if (fs.existsSync(guardVer)) {
+      fs.copyFileSync(guardVer, pkgDst);
+    }
   }
 
   return actions;
 }
 
+function _isSymlinkOrJunction(p) {
+  try {
+    const stat = fs.lstatSync(p);
+    return stat.isSymbolicLink();
+  } catch { return false; }
+}
+
 function _copyDocFiles(skillSrc, refsTarget) {
   const docs = [
     'config-reference.md', 'config-reference.zh-CN.md',

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.2",
+  "version": "4.8.5",
   "publisher": "zhangqiang8vipp",
   "license": "BUSL-1.1",
   "engines": {