cursor-guard 4.9.6 → 4.9.8

package/README.md

@@ -21,10 +21,10 @@ When Cursor's AI agent edits your files, there's a risk of accidental overwrites
 - **Secrets filtering** — Sensitive files (`.env`, keys, certificates) are auto-excluded from backups
 - **Auto-backup script** — A cross-platform watcher (Node.js) that periodically snapshots to a dedicated Git branch without disturbing your working tree
 - **MCP tool calls (optional)** — 9 structured tools (diagnostics, snapshot, restore, status, dashboard, alerts, etc.) with JSON responses and lower token cost
-- **Auto-fix diagnostics** — `doctor_fix` automatically patches missing configs, uninitialized Git repos, gitignore gaps, and stale locks
-- **Proactive change-velocity alerts (V4)** — Auto-detects abnormal file change patterns and raises risk warnings
-- **Pre-warning destructive edit guard (V4.9.6)** — Detects risky partial deletions before they quietly stick, with `popup` / `dashboard` / `silent` modes in the IDE
-- **Backup health dashboard (V4)** — One-call comprehensive view: strategy, counts, disk usage, protection scope, health status
+- **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, 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
@@ -124,9 +124,9 @@ After installation, your directory structure should look like this:
     │       ├── backups.js              # Backup listing + retention
     │       ├── restore.js              # Single file / project restore
     │       ├── status.js               # Backup system status
-    │       ├── anomaly.js             # V4: Change-velocity detection
-    │       ├── pre-warning.js         # V4.9.6: destructive edit risk scoring + persistence
-    │       └── dashboard.js           # V4: Health dashboard aggregation
+    │       ├── 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
     │   └── public/                     # Web UI (HTML/CSS/JS)
@@ -201,21 +201,21 @@ npx cursor-guard-backup --path /my/project
 Edit `.cursor-guard.json` to define which files to protect:
 
 ```json
-{
-  "protect": ["src/**", "lib/**", "package.json"],
-  "ignore": ["node_modules/**", "dist/**"],
-  "auto_backup_interval_seconds": 60,
-  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
-  "pre_restore_backup": "always",
-  "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 }
-}
-```
+{
+  "protect": ["src/**", "lib/**", "package.json"],
+  "ignore": ["node_modules/**", "dist/**"],
+  "auto_backup_interval_seconds": 60,
+  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+  "pre_restore_backup": "always",
+  "proactive_alert": true,
+  "alert_thresholds": { "files_per_window": 20, "window_seconds": 10, "cooldown_seconds": 60 },
+  "enable_pre_warning": true,
+  "pre_warning_threshold": 30,
+  "pre_warning_mode": "popup",
+  "pre_warning_exclude_patterns": ["generated/**"],
+  "retention": { "mode": "days", "days": 30 }
+}
+```
 
 #### `pre_restore_backup` — restore behavior control
 
@@ -225,22 +225,22 @@ Edit `.cursor-guard.json` to define which files to protect:
 | `"ask"` | Prompt you each time: "Preserve current version before restore? (Y/n)" — you decide per restore. |
 | `"never"` | Never preserve current version before restore (not recommended). |
 
-Regardless of config, you can always override per-request:
-- Say "don't preserve current version" to skip even when config is `"always"`
-- Say "preserve current first" to force even when config is `"never"`
-
-#### `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.
+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.
 
 ---
 
@@ -329,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 (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`):
 
-# Install the generated .vsix file (or download from GitHub Releases)
-code --install-extension cursor-guard-ide-4.9.6.vsix
+```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`
@@ -356,9 +366,9 @@ 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 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`
+- **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
@@ -435,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: 9 pure-logic modules (doctor / doctor-fix / snapshot / backups / restore / status / anomaly / pre-warning / 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) |
@@ -455,17 +465,31 @@ The skill activates on these signals:
 
 ---
 
-## Changelog
-
-### v4.9.6 — Pre-Warning for Destructive Partial Deletes
-
-- **Feature**: Added configurable `pre_warning` support in `.cursor-guard.json` — `enable_pre_warning`, `pre_warning_threshold`, `pre_warning_mode`, `pre_warning_exclude_patterns`
-- **Feature**: IDE extension now detects risky line/method removals and can react in `popup`, `dashboard`, or `silent` mode
-- **Feature**: `backup_status`, `dashboard`, sidebar, status bar, and browser dashboard surface active delete-risk warnings
-- **Improve**: New `pre-warning.js` core module centralizes deletion-risk scoring, active-warning persistence, and warning history
-- **Docs**: README, skill guide, roadmap, and config references now document the pre-warning flow end-to-end
-
-### v4.9.0–v4.9.1 — Event-Driven Architecture
+## 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)
@@ -600,15 +624,45 @@ 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.
 - **Untracked files**: Files never committed to Git cannot be recovered from Git history. Shadow copy (`backup_strategy: "shadow"` or `"both"`) is the only safety net for untracked files.
 - **Concurrent agents**: If multiple AI agent threads write to the same file simultaneously, snapshots cannot prevent race conditions. Avoid parallel edits to the same file.
 - **External tools modifying the index**: Tools that alter Git's index (e.g. other Git GUIs, IDE Git integrations) while auto-backup is running may conflict. The script uses a temporary index to minimize this, but edge cases exist.
-- **Git worktree**: The auto-backup script supports worktree layouts (`git rev-parse --git-dir`), but has not been tested with all exotic setups (e.g. `--separate-git-dir`).
-- **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**.
+- **Git worktree**: The auto-backup script supports worktree layouts (`git rev-parse --git-dir`), but has not been tested with all exotic setups (e.g. `--separate-git-dir`).
+- **Pre-warning scope**: `pre_warning` is currently an editor/extension-side "last brake", not a universal cross-process write blocker. Headless shell / MCP flows surface it through status and dashboard after detection rather than hard-blocking writes.
+- **Cursor terminal interference**: Cursor's integrated terminal injects `--trailer` flags into `git commit` commands, which breaks plumbing commands like `commit-tree`. Always run auto-backup in a **separate terminal window**.
 - **Large repos**: For very large repositories, `git add -A` in the backup loop may be slow. Use `protect` patterns in `.cursor-guard.json` to narrow scope.
 
 ## Requirements

package/README.zh-CN.md

@@ -22,9 +22,9 @@
 - **自动备份脚本** — 跨平台 (Node.js) 定期快照到独立 Git 分支，不干扰工作区
 - **MCP 工具调用（可选）** — 9 个标准化工具（诊断、快照、恢复、状态、看板、告警等），结构化 JSON 返回，低 token 消耗
 - **自动诊断修复** — `doctor_fix` 一键修补缺失配置、未初始化 Git、gitignore 遗漏等常见问题
-- **主动变更频率告警（V4）** — 自动检测异常文件变更模式并发出风险预警
-- **事先预警删除风险（V4.9.6）** — 在危险的局部删除真正“悄悄生效”前先提醒你，支持 `popup` / `dashboard` / `silent` 三种模式
-- **备份健康看板（V4）** — 一次调用全面查看：策略、数量、磁盘占用、保护范围、健康状态
+- **主动变更频率告警（V4）** — 自动检测异常文件变更模式并发出风险预警
+- **事先预警删除风险（V4.9.7）** — 在危险的局部删除真正“悄悄生效”前先提醒你，支持更柔和的自动继续提示、侧边栏语言同步，以及 `popup` / `dashboard` / `silent` 三种模式
+- **备份健康看板（V4）** — 一次调用全面查看：策略、数量、磁盘占用、保护范围、健康状态
 - **Web 仪表盘（V4.2）** — 本地只读 Web 页面 `http://127.0.0.1:3120`——健康状态、备份、恢复点、诊断、保护范围一目了然。中英双语、自动刷新、支持多项目监控
 - **IDE 扩展（V4.7）** — 完整仪表盘嵌入 VSCode/Cursor/Windsurf，WebView 标签页 + 状态栏告警指示器 + 侧边栏项目树。无需打开浏览器
 - **事件驱动监听（V4.9）** — `fs.watch` + 防抖替代盲轮询。备份延迟 < 500ms，空闲时零 CPU。不支持的平台自动降级为轮询
@@ -124,9 +124,9 @@ git clone https://github.com/zhangqiang8vipp/cursor-guard.git .cursor/skills/cur
     │       ├── backups.js              # 备份列表 + 留存清理
     │       ├── restore.js              # 单文件/全项目恢复
     │       ├── status.js               # 备份系统状态
-    │       ├── anomaly.js             # V4：变更频率检测
-    │       ├── pre-warning.js         # V4.9.6：删除风险评分 + 持久化
-    │       └── dashboard.js           # V4：健康看板聚合
+    │       ├── anomaly.js             # V4：变更频率检测
+│       ├── pre-warning.js         # V4.9.7：删除风险评分 + 持久化
+    │       └── dashboard.js           # V4：健康看板聚合
     ├── dashboard/
     │   ├── server.js                   # 仪表盘 HTTP 服务 + API
     │   └── public/                     # Web UI（HTML/CSS/JS）
@@ -203,19 +203,19 @@ npx cursor-guard-backup --path /my/project
 ```json
 {
   "protect": ["src/**", "lib/**", "package.json"],
-  "ignore": ["node_modules/**", "dist/**"],
-  "auto_backup_interval_seconds": 60,
-  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
-  "pre_restore_backup": "always",
-  "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 }
-}
-```
+  "ignore": ["node_modules/**", "dist/**"],
+  "auto_backup_interval_seconds": 60,
+  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+  "pre_restore_backup": "always",
+  "proactive_alert": true,
+  "alert_thresholds": { "files_per_window": 20, "window_seconds": 10, "cooldown_seconds": 60 },
+  "enable_pre_warning": true,
+  "pre_warning_threshold": 30,
+  "pre_warning_mode": "popup",
+  "pre_warning_exclude_patterns": ["generated/**"],
+  "retention": { "mode": "days", "days": 30 }
+}
+```
 
 #### `pre_restore_backup` — 恢复前保留行为控制
 
@@ -225,22 +225,22 @@ npx cursor-guard-backup --path /my/project
 | `"ask"` | 每次恢复前询问你："恢复前是否保留当前版本？(Y/n)"——由你逐次决定。 |
 | `"never"` | 恢复前不保留当前版本（不推荐）。 |
 
-无论配置如何，你始终可以在单次请求中覆盖：
-- 说"不保留当前版本"可跳过保留（即使配置为 `"always"`）
-- 说"先保留当前版本"可强制保留（即使配置为 `"never"`）
-
-#### `enable_pre_warning` — 局部破坏性删除的事先预警
-
-开启后，IDE 扩展会在“删行很多”或“直接删掉方法/函数”这类高风险编辑发生时，先给出最后一道提醒。
-
-| 字段 | 默认值 | 说明 |
-|------|--------|------|
-| `enable_pre_warning` | `false` | 默认关闭，兼容旧项目 |
-| `pre_warning_threshold` | `30` | 删除风险达到这个百分比时触发预警 |
-| `pre_warning_mode` | `"popup"` | `popup` 弹窗拦一下，`dashboard` 仅高亮看板，`silent` 只记日志/状态 |
-| `pre_warning_exclude_patterns` | `[]` | 跳过生成文件、迁移脚本、第三方代码等 |
-
-如果检测到方法/函数被移除，即使删行比例没到阈值，也会按高风险处理并触发提醒。
+无论配置如何，你始终可以在单次请求中覆盖：
+- 说"不保留当前版本"可跳过保留（即使配置为 `"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` | `[]` | 跳过生成文件、迁移脚本、第三方代码等 |
+
+如果检测到方法/函数被移除，即使删行比例没到阈值，也会按高风险处理并触发提醒。
 
 ---
 
@@ -329,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（VERSION 与 package.json 一致；勿手写旧版本号）
+V=$(node -p "require('../../../package.json').version")
+code --install-extension "cursor-guard-ide-${V}.vsix"
+```
 
-# 安装生成的 .vsix 文件（或从 GitHub Releases 下载）
-code --install-extension cursor-guard-ide-4.9.6.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`
@@ -356,9 +366,9 @@ code --install-extension .
 - **WebView 仪表盘** — 完整仪表盘作为编辑器标签页嵌入，与浏览器版本完全一致
 - **状态栏指示器** — 实时显示 `Guard: OK`（绿色）或 `Guard: 22 files!`（黄色告警）
 - **侧边栏 TreeView** — Activity Bar 图标，树形展示项目列表、Watcher 状态、备份统计、告警、健康评估
-- **可视化图表侧边栏** — 备份时间实时跳动、告警倒计时、保护范围、Quick Stats
-- **事先预警删除保护** — 在局部删代码、删方法、可疑大段删行时提前亮警报
-- **命令面板** — `Open Dashboard`、`Snapshot Now`、`Start/Stop Watcher`、`Quick Restore`、`Doctor`、`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、创建配置
@@ -435,7 +445,7 @@ code --install-extension .
 |------|------|
 | `SKILL.md` | AI 代理的主要技能指令（含 MCP 双路径逻辑） |
 | `ROADMAP.md` | 版本演进规划书（V2-V7） |
-| `references/lib/core/` | Core 层：9 个纯逻辑模块（doctor / doctor-fix / snapshot / backups / restore / status / anomaly / pre-warning / 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） |
@@ -455,17 +465,31 @@ code --install-extension .
 
 ---
 
-## 更新日志
-
-### v4.9.6 — 事先预警局部破坏性删除
-
-- **新功能**：`.cursor-guard.json` 新增 `enable_pre_warning`、`pre_warning_threshold`、`pre_warning_mode`、`pre_warning_exclude_patterns`
-- **新功能**：IDE 扩展现在会检测高风险删行 / 删方法，并支持 `popup`、`dashboard`、`silent` 三种预警模式
-- **新功能**：`backup_status`、`dashboard`、侧边栏、状态栏、浏览器仪表盘都会展示活跃的删除风险预警
-- **增强**：新增 `pre-warning.js` Core 模块，统一负责删除风险评分、活跃预警持久化和历史记录
-- **文档**：README、SKILL、ROADMAP 与配置说明已补齐预警功能说明
-
-### v4.9.0–v4.9.1 — 事件驱动架构
+## 更新日志
+
+### 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` 不可用时自动回退到轮询模式
@@ -599,15 +623,45 @@ 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 或部分恢复。
 - **未跟踪文件**：从未提交到 Git 的文件无法从 Git 历史恢复。影子拷贝（`backup_strategy: "shadow"` 或 `"both"`）是未跟踪文件的唯一安全网。
 - **并发 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 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` 模式缩小范围。
 
 ## 环境要求

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.9.6`
-> **文档状态**：`V2` ~ `V4.9.6` 已完成交付（含 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（基础能力起点）
 
 | 项目 | 内容 |
 |---|---|
@@ -734,17 +734,33 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
-### V4.9.6：新增可开关的 `pre_warning` 事先预警 MVP ✅
-
-| 能力 | 说明 |
-|------|------|
-| **配置开关** | `.cursor-guard.json` 新增 `enable_pre_warning`、`pre_warning_threshold`、`pre_warning_mode`、`pre_warning_exclude_patterns`，默认关闭，兼容旧项目 |
-| **风险模型** | 基于删行比例 + 方法/函数移除检测进行评分；删方法/函数即使未达到删行阈值，也会按高风险处理 |
-| **IDE 交互** | VSCode / Cursor / Windsurf 扩展支持 `popup` / `dashboard` / `silent` 三种模式；`popup` 提供 `Undo Change` 与 `View Diff` 作为最后一道刹车 |
-| **状态面整合** | `backup_status`、`dashboard`、状态栏、侧边栏、浏览器仪表盘统一展示活跃 pre-warning；风险摘要进入 health issues |
-| **架构定位** | 这是 V5「变更控制层」前的一步 MVP：先做编辑器侧的“最后一道提醒”，不是跨进程硬拦截；后续仍由 V5 的 `begin_edit` / embedded watcher 承接更强的事前控制 |
-
-### V4.9.5 / V4.9.4：修复事件驱动 Watcher 因 `.git` 写入导致的疯狂自触发备份 ✅
+### V4.9.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` 写入导致的疯狂自触发备份 ✅
 
 | 修复 | 说明 |
 |------|------|
@@ -1601,10 +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.9.0 ─────  ✅ 事件驱动 watcher + 实时侧边栏计时
-V4.9.5 ─────  ✅ 修复 `.git` 写入导致的疯狂自触发备份
-V4.9.6 ─────  ✅ `pre_warning` 事先预警 MVP（局部删代码风险提示）  ← 当前版本
+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 / 多工具协作成为真实场景
@@ -1688,5 +1709,5 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 
 ---
 
-*最后更新：2026-03-22*
-*版本：v1.6（V4.9.6，含事件驱动 watcher、自触发备份反馈环修复、`pre_warning` 事先预警 MVP）*
+*最后更新：2026-03-22*
+*版本：v1.8（V4.9.8，在 V4.9.7 基础上增加发版流程文档与侧边栏品牌资源；历史能力含事件驱动 watcher、自触发备份反馈环修复、`pre_warning` 事先预警 MVP）*

package/SKILL.md

@@ -72,7 +72,7 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
     "cooldown_seconds": 60   // min gap between alerts
   },
 
-  // V4.9.6: destructive partial-delete pre-warning (default: off).
+  // V4.9.7: destructive partial-delete pre-warning (default: off).
   // Triggered when deletion risk is high or whole methods/functions disappear.
   "enable_pre_warning": false,
   "pre_warning_threshold": 30,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.9.6",
+  "version": "4.9.8",
   "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",
@@ -24,7 +24,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node references/lib/utils.test.js && node references/lib/core/core.test.js && node references/mcp/mcp.test.js"
+    "test": "node references/lib/utils.test.js && node references/lib/core/core.test.js && node references/mcp/mcp.test.js",
+    "release:checklist": "node scripts/print-release-checklist.js"
   },
   "bin": {
     "cursor-guard-init": "references/bin/cursor-guard-init.js",