cursor-guard 3.4.0 → 4.1.0

package/README.md

@@ -20,47 +20,56 @@ When Cursor's AI agent edits your files, there's a risk of accidental overwrites
 - **Configurable scope** — Protect only what matters via `.cursor-guard.json`
 - **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)** — 7 structured tools (diagnostics, snapshot, restore, status, etc.) with JSON responses and lower token cost
+- **MCP tool calls (optional)** — 9 structured tools (diagnostics, snapshot, restore, status, dashboard, alerts, etc.) with JSON responses and lower token cost
 - **Auto-fix diagnostics** — `doctor_fix` automatically patches missing configs, uninitialized Git repos, gitignore gaps, and stale locks
+- **Proactive change-velocity alerts (V4)** — Auto-detects abnormal file change patterns and raises risk warnings
+- **Backup health dashboard (V4)** — One-call comprehensive view: strategy, counts, disk usage, protection scope, health status
 
 ---
 
 ## Installation
 
-### Method 1: npm
+### Method 1: npm (Recommended)
 
 ```bash
 npm install cursor-guard
+npx cursor-guard-init
 ```
 
-After installation, copy the skill files to your Cursor skills directory:
+The `init` command copies skill files to `.cursor/skills/cursor-guard/`, installs MCP dependencies, and adds `.gitignore` entries — all in one step.
 
-**Windows (PowerShell):**
+Options:
 
-```powershell
-# Global (all projects)
-Copy-Item -Recurse node_modules/cursor-guard "$env:USERPROFILE/.cursor/skills/cursor-guard"
-
-# Per-project (current project only)
-Copy-Item -Recurse node_modules/cursor-guard .cursor/skills/cursor-guard
+```bash
+npx cursor-guard-init              # project-local (default)
+npx cursor-guard-init --global     # global (~/.cursor/skills/)
+npx cursor-guard-init --path /my/project  # specify project root
 ```
 
-**macOS / Linux:**
+After init, the npm package in `node_modules` is no longer needed:
 
 ```bash
-# Global
-cp -r node_modules/cursor-guard ~/.cursor/skills/cursor-guard
-
-# Per-project
-cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+npm uninstall cursor-guard
 ```
 
-After copying, you can remove the npm dependency if you don't need it in `node_modules`:
+<details>
+<summary>Manual installation (without init command)</summary>
+
+If you prefer manual setup, copy files then install dependencies:
 
 ```bash
-npm uninstall cursor-guard
+# Copy
+cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+
+# Install MCP dependencies in the skill directory
+cd .cursor/skills/cursor-guard && npm install --omit=dev && cd -
+
+# Add to .gitignore so node_modules aren't captured by git snapshots
+echo ".cursor/skills/**/node_modules/" >> .gitignore
 ```
 
+</details>
+
 ### Method 2: Git clone
 
 ```bash
@@ -103,9 +112,11 @@ After installation, your directory structure should look like this:
     │       ├── snapshot.js             # Git snapshots + shadow copies
     │       ├── backups.js              # Backup listing + retention
     │       ├── restore.js              # Single file / project restore
-    │       └── status.js               # Backup system status
+    │       ├── status.js               # Backup system status
+    │       ├── anomaly.js             # V4: Change-velocity detection
+    │       └── dashboard.js           # V4: Health dashboard aggregation
     ├── mcp/
-    │   └── server.js                   # MCP Server (7 tools)
+    │   └── server.js                   # MCP Server (9 tools)
     ├── bin/
     │   ├── cursor-guard-backup.js      # CLI: npx cursor-guard-backup
     │   ├── cursor-guard-doctor.js      # CLI: npx cursor-guard-doctor
@@ -154,7 +165,7 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 }
 ```
 
-This gives the AI agent 7 structured tools (diagnostics, snapshot, restore, etc.) with JSON responses — faster, more reliable, and lower token cost. Everything works without MCP too.
+This gives the AI agent 9 structured tools (diagnostics, snapshot, restore, dashboard, alerts, etc.) with JSON responses — faster, more reliable, and lower token cost. Everything works without MCP too.
 
 6. **(Optional) Run auto-backup** in a separate terminal:
 
@@ -296,6 +307,8 @@ The skill activates on these signals:
 - Health check: "guard doctor", "check guard setup", "is MCP working"
 - Auto-fix: "guard fix", "fix config"
 - Backup status: "guard status", "is the watcher running", "last backup time"
+- Dashboard: "dashboard", "health overview", "backup summary"
+- Alerts: "any alerts?", "change velocity warning", "risk status"
 
 ---
 
@@ -305,8 +318,8 @@ 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: 6 pure-logic modules (doctor / doctor-fix / snapshot / backups / restore / status) |
-| `references/mcp/server.js` | MCP Server: 7 structured tools (optional) |
+| `references/lib/core/` | Core layer: 8 pure-logic modules (doctor / doctor-fix / snapshot / backups / restore / status / anomaly / 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) |
 | `references/lib/utils.js` | Shared utilities (config, glob, git, manifest) |

package/README.zh-CN.md

@@ -20,47 +20,56 @@
 - **可配置保护范围** — 通过 `.cursor-guard.json` 配置文件只保护你关心的文件
 - **敏感文件过滤** — `.env`、密钥、证书等敏感文件自动排除备份
 - **自动备份脚本** — 跨平台 (Node.js) 定期快照到独立 Git 分支，不干扰工作区
-- **MCP 工具调用（可选）** — 7 个标准化工具（诊断、快照、恢复、状态等），结构化 JSON 返回，低 token 消耗
+- **MCP 工具调用（可选）** — 9 个标准化工具（诊断、快照、恢复、状态、看板、告警等），结构化 JSON 返回，低 token 消耗
 - **自动诊断修复** — `doctor_fix` 一键修补缺失配置、未初始化 Git、gitignore 遗漏等常见问题
+- **主动变更频率告警（V4）** — 自动检测异常文件变更模式并发出风险预警
+- **备份健康看板（V4）** — 一次调用全面查看：策略、数量、磁盘占用、保护范围、健康状态
 
 ---
 
 ## 安装
 
-### 方式一：npm 安装
+### 方式一：npm 安装（推荐）
 
 ```bash
 npm install cursor-guard
+npx cursor-guard-init
 ```
 
-安装后，将技能文件复制到 Cursor 技能目录：
+`init` 命令一键完成：复制技能文件到 `.cursor/skills/cursor-guard/`、安装 MCP 依赖、添加 `.gitignore` 条目。
 
-**Windows (PowerShell):**
+可选参数：
 
-```powershell
-# 全局安装（所有项目生效）
-Copy-Item -Recurse node_modules/cursor-guard "$env:USERPROFILE/.cursor/skills/cursor-guard"
-
-# 项目级安装（仅当前项目生效）
-Copy-Item -Recurse node_modules/cursor-guard .cursor/skills/cursor-guard
+```bash
+npx cursor-guard-init              # 项目级安装（默认）
+npx cursor-guard-init --global     # 全局安装（~/.cursor/skills/）
+npx cursor-guard-init --path /my/project  # 指定项目根目录
 ```
 
-**macOS / Linux:**
+初始化完成后，`node_modules` 中的 npm 包已不再需要：
 
 ```bash
-# 全局安装
-cp -r node_modules/cursor-guard ~/.cursor/skills/cursor-guard
-
-# 项目级安装
-cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+npm uninstall cursor-guard
 ```
 
-复制完成后，如果不需要保留在 `node_modules` 中，可以卸载：
+<details>
+<summary>手动安装（不使用 init 命令）</summary>
+
+如果你更喜欢手动操作，复制文件后需要手动安装依赖：
 
 ```bash
-npm uninstall cursor-guard
+# 复制
+cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+
+# 在 skill 目录中安装 MCP 依赖
+cd .cursor/skills/cursor-guard && npm install --omit=dev && cd -
+
+# 添加到 .gitignore，防止 node_modules 被 git 快照捕获
+echo ".cursor/skills/**/node_modules/" >> .gitignore
 ```
 
+</details>
+
 ### 方式二：Git 克隆
 
 ```bash
@@ -103,9 +112,11 @@ git clone https://github.com/zhangqiang8vipp/cursor-guard.git .cursor/skills/cur
     │       ├── snapshot.js             # Git 快照 + 影子拷贝
     │       ├── backups.js              # 备份列表 + 留存清理
     │       ├── restore.js              # 单文件/全项目恢复
-    │       └── status.js               # 备份系统状态
+    │       ├── status.js               # 备份系统状态
+    │       ├── anomaly.js             # V4：变更频率检测
+    │       └── dashboard.js           # V4：健康看板聚合
     ├── mcp/
-    │   └── server.js                   # MCP Server（7 个工具）
+    │   └── server.js                   # MCP Server（9 个工具）
     ├── bin/
     │   ├── cursor-guard-backup.js      # CLI：npx cursor-guard-backup
     │   ├── cursor-guard-doctor.js      # CLI：npx cursor-guard-doctor
@@ -154,7 +165,7 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 }
 ```
 
-启用后 AI 代理可直接调用 7 个结构化工具（诊断、快照、恢复等），无需拼接 shell 命令，更快更省 token。不启用也完全不影响使用。
+启用后 AI 代理可直接调用 9 个结构化工具（诊断、快照、恢复、看板、告警等），无需拼接 shell 命令，更快更省 token。不启用也完全不影响使用。
 
 6. **（可选）运行自动备份** — 在独立终端运行：
 
@@ -296,6 +307,8 @@ npx cursor-guard-doctor --path /my/project
 - 健康检查："guard doctor"、"自检"、"诊断guard"、"MCP 能用吗"
 - 自动修复："guard fix"、"修复配置"、"自动修复"
 - 备份状态："备份状态"、"guard status"、"watcher 在跑吗"
+- 健康看板："看板"、"dashboard"、"备份总览"、"健康状态"
+- 告警检查："有告警吗"、"变更异常"、"风险提示"
 
 ---
 
@@ -305,8 +318,8 @@ npx cursor-guard-doctor --path /my/project
 |------|------|
 | `SKILL.md` | AI 代理的主要技能指令（含 MCP 双路径逻辑） |
 | `ROADMAP.md` | 版本演进规划书（V2-V7） |
-| `references/lib/core/` | Core 层：6 个纯逻辑模块（doctor / doctor-fix / snapshot / backups / restore / status） |
-| `references/mcp/server.js` | MCP Server：7 个标准化工具（可选） |
+| `references/lib/core/` | Core 层：8 个纯逻辑模块（doctor / doctor-fix / snapshot / backups / restore / status / anomaly / dashboard） |
+| `references/mcp/server.js` | MCP Server：9 个标准化工具（可选） |
 | `references/lib/auto-backup.js` | 自动备份 watcher（调用 Core） |
 | `references/lib/guard-doctor.js` | 健康检查 CLI 壳（调用 Core） |
 | `references/lib/utils.js` | 共享工具库（配置、glob、git、manifest） |