cursor-guard 4.3.3 → 4.3.4

package/README.md

@@ -377,6 +377,13 @@ The skill activates on these signals:
 
 ## Changelog
 
+### v4.3.4
+
+- **Improve**: Log rotation — `backup.log` now rotates at 1MB, keeping up to 3 old files (`backup.log.1`, `.2`, `.3`). Rotation runs on watcher startup and every 100 writes
+- **Improve**: Watcher single-instance protection — lock file now includes startup timestamp; locks older than 24h are auto-cleaned even if PID check is unreliable on Windows
+- **Improve**: `previewProjectRestore` output grouped — protected paths (`.cursor/`, `.gitignore`, `.cursor-guard.json`) summarized as `protectedPaths: { count: N }` instead of listing thousands of individual files, drastically reducing token cost
+- **Improve**: SKILL.md Hard Rule #15 — agents must commit skill files after upgrade to ensure `restore_project` HEAD protection works correctly
+
 ### v4.3.3
 
 - **Feature**: Intent context for snapshots — `snapshot_now` now accepts `intent`, `agent`, and `session` parameters, stored as Git commit trailers to form an audit trail per operation

package/README.zh-CN.md

@@ -377,6 +377,13 @@ node references\dashboard\server.js --path "D:\MyProject"
 
 ## 更新日志
 
+### v4.3.4
+
+- **改进**：日志轮转——`backup.log` 超过 1MB 自动轮转，保留最近 3 个旧文件。watcher 启动时和每 100 次写入时检查
+- **改进**：Watcher 单实例保护——锁文件新增启动时间戳；超过 24 小时的锁即使 PID 检查不可靠（Windows）也自动清理
+- **改进**：`previewProjectRestore` 分组输出——受保护路径（`.cursor/`、`.gitignore`、`.cursor-guard.json`）汇总为 `protectedPaths: { count: N }`，不再逐一列出数千个文件，大幅降低 token 消耗
+- **改进**：SKILL.md 硬规则 #15——升级后 Agent 必须提交 skill 文件，确保 `restore_project` 的 HEAD 保护机制生效
+
 ### v4.3.3
 
 - **功能**：快照意图上下文——`snapshot_now` 新增 `intent`（操作意图）、`agent`（AI 模型）、`session`（会话 ID）参数，作为 Git commit trailer 存储，形成按操作事件的审计链

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.0.0`  
-> **文档状态**：`V2` ~ `V4.0` 已实施，`V5+` 规划中
+> **当前版本**：`V4.3.3`  
+> **文档状态**：`V2` ~ `V4.3` 已实施（含 V5 intent 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -20,8 +20,8 @@
 |---|---|---|---|
 | `V2` | 能用 | Skill + Script | "AI 弄丢代码能恢复" |
 | `V3` | 更稳 | + Core 抽取 + 可选 MCP | "恢复操作更标准、更省 token" |
-| `V4` | 更聪明 | + 主动检测 + 可观测 | "cursor-guard 会主动提醒你" ✅ |
-| `V5` | 成闭环 | + 变更控制层 | "AI 代码变更可预防、可追溯、可按事件恢复" |
+| `V4` | 更聪明 | + 主动检测 + 可观测 + Web 仪表盘 + Intent 基础 | "cursor-guard 会主动提醒你，还能看到为什么备份" ✅ |
+| `V5` | 成闭环 | + 变更控制层 | "AI 代码变更可预防、可追溯、可按事件恢复"（intent 基础已在 V4.3 落地） |
 | `V6` | 成标准 | + 开放协议 + 团队工作流 | "把 AI 代码变更安全做成跨工具标准" |
 | `V7` | 可证明 | + 可验证信任 + 治理层 | "能证明安全流程被执行了" |
 
@@ -64,7 +64,9 @@ V2-V3 的目标是让用户"离不开"，V6-V7 的目标是让行业"绕不开"
 | `Node Core` | `V3.0` ✅ 已完成 | 6 个模块：doctor / doctor-fix / snapshot / backups / restore / status | 否 |
 | `MCP Server` | `V3.1-V4.0` ✅ 已完成 | 9 个工具，Agent 标准调用入口，结构化 JSON 返回 | 否 |
 | `智能提醒 / 可观测` | `V4.0` ✅ 已完成 | 主动发现风险、汇总健康状态（anomaly + dashboard） | 否 |
-| `变更控制层` | `V5` 规划 | 覆盖编辑意图、冲突告警、影响半径、审计事件、按事件恢复 | 否 |
+| `Web 仪表盘` | `V4.2` ✅ 已完成 | 本地只读 Web UI，备份/恢复点/诊断/保护范围，中英双语 | 否 |
+| `备份上下文 + Intent` | `V4.3` ✅ 已完成 | 结构化 commit trailer（Files-Changed/Summary/Trigger/Intent/Agent/Session），仪表盘可追溯 | 否 |
+| `变更控制层` | `V5` 规划（intent 基础已在 V4.3 落地） | 覆盖编辑意图、冲突告警、影响半径、审计事件、按事件恢复 | 否 |
 | `开放协议 / 团队工作流` | `V6` 规划 | 把变更控制能力提炼成跨工具协议、适配器和 CI 查询入口 | 否 |
 | `治理 / 可验证层` | `V7` 规划 | 让“是否走过安全流程”变成可以证明、可以审计、可以验证的事实 | 否 |
 
@@ -440,10 +442,25 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | 三审 | 4 项 | `doctor-fix.js` stale-lock PID 正则修正（`pid=` 格式）；Git pre-restore ref 加毫秒防碰撞；非 Git pre-restore shadow 同步加碰撞检测；`doctor.js` shadow 目录正则支持毫秒后缀 |
 | 四审 | 3+2 项 | `createGitSnapshot` protect basename 语义对齐（`git add -A` + `matchesAny` 裁剪替代 `git add -- <pattern>`）；`unquoteGitPath()` 反解 C-quoted 路径（支持 UTF-8 octal）；pre-restore ref / shadow snapshot 碰撞重试循环（最多 1000 次）；`previewProjectRestore` 正确解析 rename/copy 条目 |
 
+### V4.x 增量（全部已完成 ✅）
+
+| 版本 | 新增 | 状态 |
+|---|---|---|
+| V4.1 | 用户反馈修复：fileCount 精度、安装流程、doctor MCP 检测、PowerShell 兼容 | ✅ |
+| V4.2.0 | **Web 仪表盘**：本地只读 Web UI，健康总览、备份表格、恢复点抽屉、诊断、保护范围。中英双语、自动刷新、多项目支持 | ✅ |
+| V4.2.1 | 代码审查修复：`t()` replaceAll、未用导入清理、过滤栏补全、跨平台 shell 兼容、去重 | ✅ |
+| V4.2.2 | `restore_project` 保护 `.cursor-guard.json`；init 提示 `git commit` | ✅ |
+| V4.3.0 | **备份上下文元数据**：Git commit 结构化 trailer（Files-Changed / Summary / Trigger），仪表盘"变更"列 | ✅ |
+| V4.3.1 | `restore_project` 保护 `.gitignore`；`cursor-guard-index.lock` 清理；summary 按 protect/ignore 过滤 + 分类格式 | ✅ |
+| V4.3.2 | `cursor-guard-init` 自动添加根目录 `node_modules/` 到 `.gitignore`；doctor MCP 版本提示含重载快捷键 | ✅ |
+| V4.3.3 | **Intent 上下文**（V5 基础前置）：`snapshot_now` 支持 `intent` / `agent` / `session` 参数，Git trailer 存储，仪表盘展示意图徽章和完整审计字段 | ✅ |
+
+> **注**：V4.2 的 Web 仪表盘最初在 V4.0 规划中标记为"不做"，但用户需求明确后实施。事实证明只读仪表盘投入产出比合理，且不违反安全原则。
+
 ### V4 不做的事
 
 - 不做自动恢复（恢复永远需要人确认，这是产品底线）
-- 不做 Web 仪表盘
+- ~~不做 Web 仪表盘~~ → V4.2 已实施（只读、本地、零依赖）
 - 不做云端同步
 
 ### 进入 V5 的衡量标准
@@ -494,10 +511,10 @@ V5 不是"三个方向选一个"，而是把下面这条链路做完整：
 
 | 模块 / 能力 | AI 要做什么 | 建议产物 | 完成标准 |
 |---|---|---|---|
-| `intent registry` | 在高风险写入前注册编辑意图，记录 agent、会话、工作区、分支、目标文件、风险级别 | `core/intent.*` 或同等模块 | 能列出活跃会话，能释放会话，能查到谁准备改哪个文件 |
+| `intent registry` | 在高风险写入前注册编辑意图，记录 agent、会话、工作区、分支、目标文件、风险级别 | `core/intent.*` 或同等模块 | 能列出活跃会话，能释放会话，能查到谁准备改哪个文件。**基础版已在 V4.3.3 落地**：`snapshot_now` 支持 `intent` / `agent` / `session` 参数，存储为 Git commit trailer，仪表盘可展示 |
 | `pre-edit snapshot` | 在每次高风险 AI 写入前创建 `refs/guard/pre-edit/*` 恢复点 | `refs/guard/pre-edit/<session>/<seq>` | 任意一条 AI 编辑事件都能关联到写前快照 |
 | `conflict detection` | 先做文件路径级冲突检测，再预留符号级增强位 | `detectConflicts()` / `listConflicts()` | 两个会话同时改重叠文件时能给出 advisory warning |
-| `audit store` | 以 append-only 方式保存 AI 编辑事件 | 默认本地 `JSONL`；后续可升级 `SQLite` | 能按文件 / 会话 / agent / 时间 / 风险级别查询 |
+| `audit store` | 以 append-only 方式保存 AI 编辑事件 | 默认本地 `JSONL`；后续可升级 `SQLite` | 能按文件 / 会话 / agent / 时间 / 风险级别查询。**雏形已在 V4.3.0-V4.3.3 落地**：审计元数据通过 Git commit trailer 持久化，`listBackups` 可按 trigger/intent/agent/session 解析 |
 | `restore by event` | 允许从一条审计事件直接跳转并执行恢复 | `restore_from_event` | 给定 `event_id` 可以定位 `before_ref` 或 `restore_ref` |
 | `impact set` | 为高风险编辑记录受影响文件 / 符号 / 测试集合 | `impact_set` 字段 | 查询事件时能看到"这次改动可能波及哪里" |
 | `MCP / CLI surface` | 暴露最小可用接口给 Agent 和终端 | `register_intent` / `list_active_intents` / `audit_query` / `get_event` / `restore_from_event` | AI 不需要拼复杂 shell，就能完成查询与恢复 |
@@ -935,8 +952,8 @@ V7.2  完整 attestation（安全操作证明链）
 
 | | V2 | V3 | V4 | V5 | V6 | V7 |
 |---|---|---|---|---|---|---|
-| **一句话** | 能恢复 | 更稳更省 | 主动提醒 | 变更闭环 | 跨工具标准 | 可证明 |
-| **核心架构** | Skill + Script | + Core + MCP | + 智能检测 | + 变更控制层 | + 开放协议 + 适配器 | + 治理层 |
+| **一句话** | 能恢复 | 更稳更省 | 主动提醒 + 可观测 + Intent | 变更闭环 | 跨工具标准 | 可证明 |
+| **核心架构** | Skill + Script | + Core + MCP | + 智能检测 + Web 仪表盘 + Intent 基础 | + 变更控制层 | + 开放协议 + 适配器 | + 治理层 |
 | **Agent 调用** | 拼 shell | 优先 MCP | MCP + 主动建议 | MCP + 意图 / 审计 / 恢复 | 标准接口 + 适配器 | 标准接口 + 审计 |
 | **安装门槛** | 最低 | 不变 | 不变 | 略增 | 看具体实现 | 看具体实现 |
 | **适合谁** | 所有人 | 所有人 | 所有人 | 重度 AI 用户 + 团队试点 | 工具开发者 + 团队 | 企业 + 合规场景 |
@@ -957,8 +974,11 @@ V3.4  ──────  ✅ MCP 自检
                │
                │  前提：MCP 调用成功率 > 95%，token 消耗可观测下降
                ▼
-V4.0  ──────  ✅ 智能恢复建议 + 备份健康看板 + 4 轮代码审查加固（138 测试）  ← 当前版本
-V4.x  ──────  候选支线（完整性校验 / 多项目概览）
+V4.0  ──────  ✅ 智能恢复建议 + 备份健康看板 + 4 轮代码审查加固（138 测试）
+V4.1  ──────  ✅ 用户反馈修复
+V4.2  ──────  ✅ Web 仪表盘（只读、双语、多项目）+ 代码审查修复
+V4.3  ──────  ✅ 备份上下文元数据 + Intent 上下文 + restore 安全加固  ← 当前版本
+V4.x  ──────  候选支线（完整性校验 / 更丰富的审计查询）
                │
                │  前提：AI 编辑需要更强的追溯 / 恢复 / 查询闭环
                │  前提：多 Agent / 多工具协作成为真实场景
@@ -1002,13 +1022,15 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 
 ## 给用户说的话
 
-### 现在（V4）
+### 现在（V4.3）
 
 > cursor-guard 已经能保护你的代码，而且越来越聪明。
 > 自动备份、写前快照、确定性恢复——开箱即用。
 > V3 新增：MCP 工具调用（可选）让 AI 操作更稳、更快、更省 token。
-> V4 新增：系统会主动监测异常变更并提醒你，一个 `dashboard` 就能看全局健康状态。
-> 经过 4 轮代码审查，138 个测试覆盖所有核心路径。
+> V4.0 新增：系统会主动监测异常变更并提醒你，一个 `dashboard` 就能看全局健康状态。
+> V4.2 新增：本地 Web 仪表盘——健康、备份、恢复点、诊断一页可见，中英双语自动刷新。
+> V4.3 新增：每次备份带上下文（改了什么、为什么备份、哪个 AI 在操作），在仪表盘可追溯。
+> 经过 4 轮代码审查，138+ 个测试覆盖所有核心路径。
 
 ### 未来
 
@@ -1027,7 +1049,7 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 | 自动恢复（无人确认） | 恢复操作必须有人确认，这是产品底线 |
 | 自动 push 到远程 | 本地优先，push 需用户明确指令 |
 | 云端备份服务 | cursor-guard 的定位是本地安全网 |
-| Web 仪表盘 | 投入产出比不合理 |
+| ~~Web 仪表盘~~ | ~~投入产出比不合理~~ → V4.2 已实施只读仪表盘（本地、零依赖、不执行写操作） |
 | 取代 Git | cursor-guard 是 Git 的增强，不是替代 |
 | AI 行为限制 | cursor-guard 是安全网，不是笼子 |
 | 多 IDE 全面适配 | 聚焦 Cursor，其他 IDE 由社区或 V6 协议解决 |
@@ -1036,5 +1058,5 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 
 ---
 
-*最后更新：2026-03-21*
-*版本：v1.2（V4.0 最终交付，含 4 轮代码审查加固）*
+*最后更新：2026-03-22*
+*版本：v1.3（V4.3.3 交付，含 Web 仪表盘、备份上下文元数据、Intent 基础）*

package/SKILL.md

@@ -583,6 +583,7 @@ Skip the block for unrelated turns.
 12. **Concurrent agents**: if multiple Agent threads are active, warn the user to avoid simultaneous writes to the same file. Snapshots cannot prevent race conditions between parallel agents.
 13. **Preservation must not pollute** — all pre-restore backups use temp index + dedicated ref (`refs/guard/pre-restore`). The user's staging area, working tree, and commit history on their branch are never modified by the preservation process.
 14. **Do not restore `.cursor/` directory** — `.cursor/skills/`, `.cursor/rules/`, and `.cursor/mcp.json` are tool infrastructure, not project code. `restore_project` automatically protects this directory. Never include `.cursor/` in manual restore commands unless the user explicitly requests it. Restoring `.cursor/skills/cursor-guard/` would downgrade the protection tool itself.
+15. **Commit skill files after upgrade** — after running `cursor-guard-init` or upgrading the skill, immediately commit `.cursor/skills/cursor-guard/` and `.cursor-guard.json` to HEAD (`git add .cursor/ .cursor-guard.json && git commit -m "chore: upgrade cursor-guard"`). This ensures `restore_project`'s HEAD protection mechanism can preserve the current skill version. Without this commit, a restore could revert the skill to an older version.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.3.3",
+  "version": "4.3.4",
   "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

@@ -72,24 +72,39 @@ async function runBackup(projectDir, intervalOverride) {
   // Ensure backup dir
   fs.mkdirSync(backupDir, { recursive: true });
 
-  // Lock file with stale detection
+  // Lock file with stale detection (PID + age)
+  const LOCK_MAX_AGE_MS = 24 * 60 * 60 * 1000;
   if (fs.existsSync(lockFile)) {
     let stale = false;
+    let reason = '';
     try {
       const content = fs.readFileSync(lockFile, 'utf-8');
       const pidMatch = content.match(/pid=(\d+)/);
-      if (pidMatch) {
-        const oldPid = parseInt(pidMatch[1], 10);
-        if (!isProcessAlive(oldPid)) {
+      const startedMatch = content.match(/started=(.+)/);
+      const oldPid = pidMatch ? parseInt(pidMatch[1], 10) : null;
+      const startedAt = startedMatch ? Date.parse(startedMatch[1]) : NaN;
+
+      if (oldPid && !isProcessAlive(oldPid)) {
+        stale = true;
+        reason = `pid ${oldPid} not running`;
+      } else if (!isNaN(startedAt) && Date.now() - startedAt > LOCK_MAX_AGE_MS) {
+        stale = true;
+        reason = `lock age > 24h (started ${startedMatch[1]})`;
+      } else if (!oldPid) {
+        const stat = fs.statSync(lockFile);
+        if (Date.now() - stat.mtimeMs > LOCK_MAX_AGE_MS) {
           stale = true;
-          console.log(color.yellow(`[guard] Stale lock detected (pid ${oldPid} not running). Cleaning up.`));
-          fs.unlinkSync(lockFile);
+          reason = 'lock file too old (no PID, mtime > 24h)';
         }
       }
     } catch { /* ignore */ }
-    if (!stale) {
+    if (stale) {
+      console.log(color.yellow(`[guard] Stale lock detected (${reason}). Cleaning up.`));
+      try { fs.unlinkSync(lockFile); } catch { /* ignore */ }
+    } else {
       console.log(color.red(`[guard] ERROR: Lock file exists (${lockFile}).`));
-      console.log(color.red('  If no other instance is running, delete it and retry.'));
+      console.log(color.red('  Another watcher instance may be running.'));
+      console.log(color.red('  If no other instance is running, delete the lock file and retry.'));
       process.exit(1);
     }
   }

package/references/lib/core/restore.js

@@ -170,7 +170,7 @@ function restoreFile(projectDir, file, source, opts = {}) {
  *
  * @param {string} projectDir
  * @param {string} source - Commit hash or ref
- * @returns {{ status: 'ok'|'error', files?: Array<{path: string, change: 'modified'|'added'|'deleted'}>, totalChanged?: number, error?: string }}
+ * @returns {{ status: 'ok'|'error', files?: Array<{path: string, change: string}>, protectedPaths?: {count: number, note?: string}, totalChanged?: number, error?: string }}
  */
 function previewProjectRestore(projectDir, source) {
   if (!isGitRepo(projectDir)) {
@@ -218,13 +218,27 @@ function previewProjectRestore(projectDir, source) {
       }
     }
 
+    const protectedFiles = [];
+    const projectFiles = [];
     for (const f of files) {
       if (isToolPath(f.path)) {
-        f.warning = 'protected path — will be preserved from HEAD to prevent tool/config downgrade';
+        protectedFiles.push(f);
+      } else {
+        projectFiles.push(f);
       }
     }
 
-    return { status: 'ok', files, totalChanged: files.length };
+    return {
+      status: 'ok',
+      files: projectFiles,
+      protectedPaths: {
+        count: protectedFiles.length,
+        note: protectedFiles.length > 0
+          ? 'these paths (.cursor/, .cursor-guard.json, .gitignore) will be preserved from HEAD'
+          : undefined,
+      },
+      totalChanged: files.length,
+    };
   } catch (e) {
     return { status: 'error', error: e.message };
   }

package/references/lib/utils.js

@@ -354,19 +354,31 @@ function timestamp() {
   return new Date().toISOString().replace('T', ' ').substring(0, 19);
 }
 
-function createLogger(logFilePath, maxSizeMB = 10) {
+function createLogger(logFilePath, { maxSizeMB = 1, maxFiles = 3 } = {}) {
   let writeCount = 0;
-  function rotateIfNeeded() {
-    if (++writeCount % 100 !== 0) return;
+  const maxBytes = maxSizeMB * 1024 * 1024;
+
+  function rotate() {
     try {
       const stat = fs.statSync(logFilePath);
-      if (stat.size > maxSizeMB * 1024 * 1024) {
-        const old = logFilePath + '.old';
-        try { fs.unlinkSync(old); } catch { /* ignore */ }
-        fs.renameSync(logFilePath, old);
-      }
-    } catch { /* ignore */ }
+      if (stat.size <= maxBytes) return;
+    } catch { return; }
+    for (let i = maxFiles - 1; i >= 1; i--) {
+      const from = i === 1 ? logFilePath + '.1' : logFilePath + '.' + i;
+      const to = logFilePath + '.' + (i + 1);
+      try { fs.renameSync(from, to); } catch { /* ignore */ }
+    }
+    try { fs.renameSync(logFilePath, logFilePath + '.1'); } catch { /* ignore */ }
+    try { fs.unlinkSync(logFilePath + '.' + (maxFiles + 1)); } catch { /* ignore */ }
   }
+
+  rotate();
+
+  function rotateIfNeeded() {
+    if (++writeCount % 100 !== 0) return;
+    rotate();
+  }
+
   return {
     log(msg, c = 'green') {
       const line = `${timestamp()}  ${msg}`;