cursor-guard 4.3.5 → 4.4.0

package/README.md

@@ -377,6 +377,13 @@ The skill activates on these signals:
 
 ## Changelog
 
+### v4.4.0 — V4 Final
+
+- **Fix**: First snapshot now generates "Added N: file1, file2, ..." summary instead of blank — previously the very first backup had no summary because there was no parent tree to diff against
+- **Feature**: Doctor check "Git retention" — warns when git backup commits exceed 500 and `git_retention.enabled` is `false`, guiding users to enable auto-pruning before refs grow unbounded
+- **Feature**: Doctor check "Backup integrity" — verifies that the latest auto-backup commit's tree object is reachable via `git cat-file -t`, catching silent corruption early
+- **Improve**: `cursor-guard-init` now detects existing `.cursor-guard.json` and displays an upgrade notice instead of silently overwriting
+
 ### v4.3.5
 
 - **Fix**: Backup summary now uses incremental `diff-tree` instead of `git status --porcelain` — previously summary always showed cumulative changes since HEAD, now correctly shows changes since the last auto-backup

package/README.zh-CN.md

@@ -377,6 +377,13 @@ node references\dashboard\server.js --path "D:\MyProject"
 
 ## 更新日志
 
+### v4.4.0 — V4 收官版
+
+- **修复**：首次快照现在会生成 "Added N: file1, file2, ..." 摘要，而不是空白——之前第一次备份因为没有 parent tree 对比所以 summary 始终为空
+- **功能**：Doctor 新增 "Git retention" 检查——当 Git 备份 commit 数超过 500 且 `git_retention.enabled` 为 `false` 时发出 WARN，引导用户开启自动清理防止 ref 无限增长
+- **功能**：Doctor 新增 "Backup integrity" 检查——通过 `git cat-file -t` 验证最近一次 auto-backup commit 的 tree 对象是否可达，尽早发现静默损坏
+- **改进**：`cursor-guard-init` 现在检测已有 `.cursor-guard.json`，显示升级提示而非静默覆盖
+
 ### v4.3.5
 
 - **修复**：备份摘要（Summary）现使用增量 `diff-tree` 替代 `git status --porcelain`——之前 summary 始终显示自 HEAD 以来的累计差异，现在正确显示自上次 auto-backup 以来的增量变化

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.3.3`  
-> **文档状态**：`V2` ~ `V4.3` 已实施（含 V5 intent 基础），`V5` 主体规划中
+> **当前版本**：`V4.4.0`（V4 收官版）  
+> **文档状态**：`V2` ~ `V4.4.0` 已实施（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -20,7 +20,7 @@
 |---|---|---|---|
 | `V2` | 能用 | Skill + Script | "AI 弄丢代码能恢复" |
 | `V3` | 更稳 | + Core 抽取 + 可选 MCP | "恢复操作更标准、更省 token" |
-| `V4` | 更聪明 | + 主动检测 + 可观测 + Web 仪表盘 + Intent 基础 | "cursor-guard 会主动提醒你，还能看到为什么备份" ✅ |
+| `V4` | 更聪明 | + 主动检测 + 可观测 + Web 仪表盘 + Intent + 增量摘要 | "cursor-guard 会主动提醒你，能看到为什么备份、改了什么" ✅ |
 | `V5` | 成闭环 | + 变更控制层 | "AI 代码变更可预防、可追溯、可按事件恢复"（intent 基础已在 V4.3 落地） |
 | `V6` | 成标准 | + 开放协议 + 团队工作流 | "把 AI 代码变更安全做成跨工具标准" |
 | `V7` | 可证明 | + 可验证信任 + 治理层 | "能证明安全流程被执行了" |
@@ -65,7 +65,7 @@ V2-V3 的目标是让用户"离不开"，V6-V7 的目标是让行业"绕不开"
 | `MCP Server` | `V3.1-V4.0` ✅ 已完成 | 9 个工具，Agent 标准调用入口，结构化 JSON 返回 | 否 |
 | `智能提醒 / 可观测` | `V4.0` ✅ 已完成 | 主动发现风险、汇总健康状态（anomaly + dashboard） | 否 |
 | `Web 仪表盘` | `V4.2` ✅ 已完成 | 本地只读 Web UI，备份/恢复点/诊断/保护范围，中英双语 | 否 |
-| `备份上下文 + Intent` | `V4.3` ✅ 已完成 | 结构化 commit trailer（Files-Changed/Summary/Trigger/Intent/Agent/Session），仪表盘可追溯 | 否 |
+| `备份上下文 + Intent` | `V4.3` ✅ 已完成 | 结构化 commit trailer（Files-Changed/Summary/Trigger/Intent/Agent/Session），增量 diff-tree 真实摘要，仪表盘可追溯 | 否 |
 | `变更控制层` | `V5` 规划（intent 基础已在 V4.3 落地） | 覆盖编辑意图、冲突告警、影响半径、审计事件、按事件恢复 | 否 |
 | `开放协议 / 团队工作流` | `V6` 规划 | 把变更控制能力提炼成跨工具协议、适配器和 CI 查询入口 | 否 |
 | `治理 / 可验证层` | `V7` 规划 | 让“是否走过安全流程”变成可以证明、可以审计、可以验证的事实 | 否 |
@@ -454,6 +454,9 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | 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.3.4 | **运维加固**：`backup.log` 日志轮转（1MB / 3 文件）；watcher 单实例保护加固（锁文件时间戳 + 24h 超时）；`previewProjectRestore` 保护路径分组摘要（降低 token 消耗）；SKILL.md 硬规则 #15（升级后提交 skill 文件） | ✅ |
+| V4.3.5 | **Summary 准确性修复 + UI 优化**：备份摘要改用 `diff-tree` 增量对比（修复 porcelain 假摘要 bug）；仪表盘变更列三行堆叠布局；配色全面优化（背景层级 / 状态色 / 文字层级） | ✅ |
+| V4.4.0 | **V4 收官版**：首次快照 summary（无 parent 时生成 Added N: ...）；doctor 新增 Git retention 警告（>500 commits + disabled）和 Backup integrity 校验（`cat-file -t` tree 可达性）；`cursor-guard-init` 升级检测（已有配置提示） | ✅ |
 
 > **注**：V4.2 的 Web 仪表盘最初在 V4.0 规划中标记为"不做"，但用户需求明确后实施。事实证明只读仪表盘投入产出比合理，且不违反安全原则。
 
@@ -511,7 +514,7 @@ V5 不是"三个方向选一个"，而是把下面这条链路做完整：
 
 | 模块 / 能力 | AI 要做什么 | 建议产物 | 完成标准 |
 |---|---|---|---|
-| `intent registry` | 在高风险写入前注册编辑意图，记录 agent、会话、工作区、分支、目标文件、风险级别 | `core/intent.*` 或同等模块 | 能列出活跃会话，能释放会话，能查到谁准备改哪个文件。**基础版已在 V4.3.3 落地**：`snapshot_now` 支持 `intent` / `agent` / `session` 参数，存储为 Git commit trailer，仪表盘可展示 |
+| `intent registry` | 在高风险写入前注册编辑意图，记录 agent、会话、工作区、分支、目标文件、风险级别 | `core/intent.*` 或同等模块 | 能列出活跃会话，能释放会话，能查到谁准备改哪个文件。**基础版已在 V4.3.3 落地**：`snapshot_now` 支持 `intent` / `agent` / `session` 参数，存储为 Git commit trailer，仪表盘可展示。**V4.3.5 修复**：summary 改用 `diff-tree` 增量对比，确保元数据准确 |
 | `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 / 时间 / 风险级别查询。**雏形已在 V4.3.0-V4.3.3 落地**：审计元数据通过 Git commit trailer 持久化，`listBackups` 可按 trigger/intent/agent/session 解析 |
@@ -952,8 +955,8 @@ V7.2  完整 attestation（安全操作证明链）
 
 | | V2 | V3 | V4 | V5 | V6 | V7 |
 |---|---|---|---|---|---|---|
-| **一句话** | 能恢复 | 更稳更省 | 主动提醒 + 可观测 + Intent | 变更闭环 | 跨工具标准 | 可证明 |
-| **核心架构** | Skill + Script | + Core + MCP | + 智能检测 + Web 仪表盘 + Intent 基础 | + 变更控制层 | + 开放协议 + 适配器 | + 治理层 |
+| **一句话** | 能恢复 | 更稳更省 | 主动提醒 + 可观测 + 可追溯 | 变更闭环 | 跨工具标准 | 可证明 |
+| **核心架构** | Skill + Script | + Core + MCP | + 智能检测 + Web 仪表盘 + Intent + 增量摘要 | + 变更控制层 | + 开放协议 + 适配器 | + 治理层 |
 | **Agent 调用** | 拼 shell | 优先 MCP | MCP + 主动建议 | MCP + 意图 / 审计 / 恢复 | 标准接口 + 适配器 | 标准接口 + 审计 |
 | **安装门槛** | 最低 | 不变 | 不变 | 略增 | 看具体实现 | 看具体实现 |
 | **适合谁** | 所有人 | 所有人 | 所有人 | 重度 AI 用户 + 团队试点 | 工具开发者 + 团队 | 企业 + 合规场景 |
@@ -975,10 +978,17 @@ V3.4  ──────  ✅ MCP 自检
                │  前提：MCP 调用成功率 > 95%，token 消耗可观测下降
                ▼
 V4.0  ──────  ✅ 智能恢复建议 + 备份健康看板 + 4 轮代码审查加固（138 测试）
-V4.1  ──────  ✅ 用户反馈修复
-V4.2  ──────  ✅ Web 仪表盘（只读、双语、多项目）+ 代码审查修复
-V4.3  ──────  ✅ 备份上下文元数据 + Intent 上下文 + restore 安全加固  ← 当前版本
-V4.x  ──────  候选支线（完整性校验 / 更丰富的审计查询）
+V4.1  ──────  ✅ 用户反馈修复（fileCount 精度、安装流程、PowerShell 兼容）
+V4.2.0 ─────  ✅ Web 仪表盘（只读、双语、多项目、聚合 API）
+V4.2.1 ─────  ✅ 代码审查修复（t() replaceAll、未用导入、过滤栏补全）
+V4.2.2 ─────  ✅ restore 保护 .cursor-guard.json + init 提示 git commit
+V4.3.0 ─────  ✅ 备份上下文元数据（Git trailer: Files-Changed / Summary / Trigger）
+V4.3.1 ─────  ✅ restore 保护 .gitignore + lock 清理 + summary 过滤/分类
+V4.3.2 ─────  ✅ init 自动添加 node_modules/ 到 .gitignore + doctor 重载提示
+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 升级检测  ← 当前版本
                │
                │  前提：AI 编辑需要更强的追溯 / 恢复 / 查询闭环
                │  前提：多 Agent / 多工具协作成为真实场景
@@ -1022,14 +1032,18 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 
 ## 给用户说的话
 
-### 现在（V4.3）
+### 现在（V4.3.5）
 
 > cursor-guard 已经能保护你的代码，而且越来越聪明。
 > 自动备份、写前快照、确定性恢复——开箱即用。
-> V3 新增：MCP 工具调用（可选）让 AI 操作更稳、更快、更省 token。
-> V4.0 新增：系统会主动监测异常变更并提醒你，一个 `dashboard` 就能看全局健康状态。
-> V4.2 新增：本地 Web 仪表盘——健康、备份、恢复点、诊断一页可见，中英双语自动刷新。
-> V4.3 新增：每次备份带上下文（改了什么、为什么备份、哪个 AI 在操作），在仪表盘可追溯。
+>
+> **V3**：MCP 工具调用（可选）让 AI 操作更稳、更快、更省 token。
+> **V4.0**：系统会主动监测异常变更并提醒你，一个 `dashboard` 就能看全局健康状态。
+> **V4.2**：本地 Web 仪表盘——健康、备份、恢复点、诊断一页可见，中英双语自动刷新。
+> **V4.3.0-4.3.3**：每次备份带上下文（改了什么、为什么备份、哪个 AI 在操作），Intent 意图可追溯。
+> **V4.3.4**：运维加固——日志轮转、锁文件保护、restore 预览分组降低 token 消耗。
+> **V4.3.5**：修复了备份摘要准确性（增量 diff-tree）；仪表盘变更列分层展示，配色全面优化。
+>
 > 经过 4 轮代码审查，138+ 个测试覆盖所有核心路径。
 
 ### 未来
@@ -1059,4 +1073,4 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 ---
 
 *最后更新：2026-03-22*
-*版本：v1.3（V4.3.3 交付，含 Web 仪表盘、备份上下文元数据、Intent 基础）*
+*版本：v1.5（V4.4.0 收官版，含 Web 仪表盘、备份上下文元数据、Intent 基础、增量 summary、doctor 完整性校验、运维加固、UI 优化）*

package/package.json

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

package/references/bin/cursor-guard-init.js

@@ -56,6 +56,13 @@ console.log(`  Source:  ${skillSource}`);
 console.log(`  Target:  ${skillTarget}`);
 console.log(`  Mode:    ${isGlobal ? 'global (~/.cursor/skills/)' : 'project-local (.cursor/skills/)'}\n`);
 
+// Pre-check: warn if .cursor-guard.json already exists (upgrade scenario)
+const configPath = path.join(projectDir, '.cursor-guard.json');
+if (fs.existsSync(configPath)) {
+  console.log('  NOTE: .cursor-guard.json already exists — your config will be preserved.');
+  console.log('        Only skill files will be updated (upgrade mode).\n');
+}
+
 // Step 1: Copy skill files (excluding node_modules and .git)
 console.log('  [1/4] Copying skill files...');
 if (fs.existsSync(skillTarget)) {

package/references/lib/core/doctor.js

@@ -92,6 +92,33 @@ function runDiagnostics(projectDir) {
     }
   }
 
+  // 5b. Git retention warning
+  if (repo) {
+    const guardRef = 'refs/guard/auto-backup';
+    const countStr = git(['rev-list', '--count', guardRef], { cwd: projectDir, allowFail: true });
+    const commitCount = countStr ? parseInt(countStr, 10) : 0;
+    if (commitCount > 500 && !cfg.git_retention.enabled) {
+      check('Git retention', 'WARN',
+        `${commitCount} backup commits and git_retention is disabled — set git_retention.enabled=true in .cursor-guard.json to auto-prune old snapshots`);
+    } else if (commitCount > 0 && cfg.git_retention.enabled) {
+      check('Git retention', 'PASS', `${commitCount} commits, auto-prune enabled (${cfg.git_retention.mode}: ${cfg.git_retention.mode === 'days' ? cfg.git_retention.days + 'd' : cfg.git_retention.max_count})`);
+    }
+  }
+
+  // 5c. Backup integrity — verify latest auto-backup tree is reachable
+  if (repo) {
+    const guardRef = 'refs/guard/auto-backup';
+    const latestHash = git(['rev-parse', '--verify', guardRef], { cwd: projectDir, allowFail: true });
+    if (latestHash) {
+      const treeType = git(['cat-file', '-t', `${latestHash}^{tree}`], { cwd: projectDir, allowFail: true });
+      if (treeType === 'tree') {
+        check('Backup integrity', 'PASS', `latest auto-backup commit ${latestHash.substring(0, 7)} tree is valid`);
+      } else {
+        check('Backup integrity', 'FAIL', `latest auto-backup commit ${latestHash.substring(0, 7)} tree is corrupted or unreachable`);
+      }
+    }
+  }
+
   // 6. Guard refs
   if (repo) {
     const refs = git(['for-each-ref', 'refs/guard/', '--format=%(refname)'], { cwd: projectDir, allowFail: true });

package/references/lib/core/snapshot.js

@@ -166,6 +166,14 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
         if (groups.R.length) parts.push(`Renamed ${groups.R.length}: ${groups.R.slice(0, 5).join(', ')}`);
         if (parts.length) incrementalSummary = parts.join('; ');
       }
+    } else {
+      const lsInitial = git(['ls-tree', '--name-only', '-r', newTree], { cwd, allowFail: true });
+      if (lsInitial) {
+        const files = lsInitial.split('\n').filter(Boolean);
+        changedCount = files.length;
+        const sample = files.slice(0, 5).join(', ');
+        incrementalSummary = `Added ${files.length}: ${sample}${files.length > 5 ? ', ...' : ''}`;
+      }
     }
 
     // Override context summary with the accurate incremental one