cursor-guard 4.5.4 → 4.5.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/ROADMAP.md +45 -27
  2. package/package.json +1 -1
package/ROADMAP.md CHANGED
@@ -3,8 +3,8 @@
3
3
  > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
4
4
  > 每一代向下兼容，低版本功能永远不废弃。
5
5
  >
6
- > **当前版本**：`V4.5.4`（V4 最终版）
7
- > **文档状态**：`V2` ~ `V4.5.4` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
6
+ > **当前版本**：`V4.5.5`（V4 最终版）
7
+ > **文档状态**：`V2` ~ `V4.5.5` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
8
8
 
9
9
  ## 阅读导航
10
10
 
@@ -663,8 +663,9 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
663
663
 
664
664
  ### 进入 V5 的衡量标准
665
665
 
666
- - V4 的主动提醒功能误报率 < 10%
667
- - 健康看板的信息准确度经用户验证
666
+ - ✅ V4 的主动提醒功能误报率 < 10% — V4.5.0 修复了计数数据源（`diff-tree` 替代 `porcelain`）
667
+ - ✅ 健康看板的信息准确度经用户验证 — V4.5.2-V4.5.3 增加结构化文件列表，数据来源一致
668
+ - ✅ `always_watch` 基础能力可用 — V4.5.4 已实现（spawn 独立进程版）
668
669
  - 多 Agent 并发编辑已成为用户的真实场景（不是假设）
669
670
  - MCP 协议的 notification / resource subscription 机制已相对成熟
670
671
 
@@ -674,10 +675,12 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
674
675
 
675
676
  | 项目 | 内容 |
676
677
  |---|---|
677
- | 状态 | 中期主线 🚀 |
678
+ | 状态 | 中期主线 🚀（V4.5.x 已完成基础设施前置） |
678
679
  | 定位 | 从保护"一次 AI 写操作"升级为管理"整条 AI 代码变更链路"：事前预防、事中判断、事后追溯、按事件恢复。 |
679
680
  | 产品定义 | `AI Code Change Control Layer` |
680
681
  | 关键词 | `intent` / `impact` / `audit` / `restore-by-event` |
682
+ | V4 前置 | `always_watch`（V4.5.4）、结构化文件数据（V4.5.2-V4.5.3）、intent 基础（V4.3.3）、审计 trailer（V4.3.0）、Shadow 硬链接（V4.5.4）、Web 仪表盘（V4.2-V4.5.3） |
683
+ | V5 核心差异 | **embedded watcher（同进程）** + **begin_edit 意图-变更原子绑定** — 这两项是 V4 无法做到的，需要架构升级 |
681
684
 
682
685
  ### 为什么需要这一步
683
686
 
@@ -698,29 +701,35 @@ V2-V4 已经证明，cursor-guard 的价值不只是"多留一个备份点"，
698
701
 
699
702
  V5 不是"三个方向选一个"，而是把下面这条链路做完整：
700
703
 
701
- 1. **Intent**：谁正准备改这里？
702
- 2. **Impact**：这次改动会波及哪里？
703
- 3. **Audit**：这段代码何时、被谁、因何改的？
704
- 4. **Restore**：出事后该回退哪次操作？
704
+ | 步骤 | 核心问题 | V4 已有基础 | V5 新增 |
705
+ |------|---------|------------|---------|
706
+ | **Intent** | 谁正准备改这里？ | ✅ `snapshot_now` intent/agent/session 参数 | `begin_edit` 实时注册 + 文件路径绑定 |
707
+ | **Impact** | 这次改动波及哪里？ | ✅ 结构化 `changedFiles` + `getBackupFiles` | 符号级分析（导出/引用/测试波及） |
708
+ | **Audit** | 何时、被谁、因何改的？ | ✅ Git trailer 审计元数据 + 仪表盘展示 | 独立 JSONL 审计存储 + 结构化事件查询 |
709
+ | **Restore** | 出事回退哪次操作？ | ✅ `restore_file` / `restore_project` + pre-restore 快照 | `restore_from_event`（按事件 ID 直接恢复） |
705
710
 
706
- 只有这四步连起来，cursor-guard 才不是"备份工具"，而是"变更控制层"。
711
+ 只有这四步连起来，cursor-guard 才不是"备份工具"，而是"变更控制层"。V4 已铺好每一步的基础设施，V5 的核心价值是把它们**原子化串联**——通过同进程 embedded watcher + 文件路径意图绑定，让 Intent → Impact → Audit → Restore 在一个事件链里自动完成。
707
712
 
708
713
  ### V5.0 可执行功能清单
709
714
 
710
- | 模块 / 能力 | AI 要做什么 | 建议产物 | 完成标准 |
715
+ > **注**：部分 V5 规划能力已在 V4.5.x 提前落地，下表用 ✅ 标注。V5 的核心差异化在于 **embedded watcher（同进程）** 和 **begin_edit 意图-变更原子绑定**。
716
+
717
+ | 模块 / 能力 | 说明 | V4 已落地 | V5 新增 |
711
718
  |---|---|---|---|
712
- | `intent registry` | 在高风险写入前注册编辑意图，记录 agent、会话、工作区、分支、目标文件、风险级别 | `core/intent.*` 或同等模块 | 能列出活跃会话，能释放会话，能查到谁准备改哪个文件。**基础版已在 V4.3.3 落地**：`snapshot_now` 支持 `intent` / `agent` / `session` 参数，存储为 Git commit trailer，仪表盘可展示。**V4.3.5 修复**：summary 改用 `diff-tree` 增量对比，确保元数据准确 |
713
- | `pre-edit snapshot` | 在每次高风险 AI 写入前创建 `refs/guard/pre-edit/*` 恢复点 | `refs/guard/pre-edit/<session>/<seq>` | 任意一条 AI 编辑事件都能关联到写前快照 |
714
- | `conflict detection` | 先做文件路径级冲突检测，再预留符号级增强位 | `detectConflicts()` / `listConflicts()` | 两个会话同时改重叠文件时能给出 advisory warning |
715
- | `audit store` | 以 append-only 方式保存 AI 编辑事件 | 默认本地 `JSONL`；后续可升级 `SQLite` | 能按文件 / 会话 / agent / 时间 / 风险级别查询。**雏形已在 V4.3.0-V4.3.3 落地**：审计元数据通过 Git commit trailer 持久化，`listBackups` 可按 trigger/intent/agent/session 解析 |
716
- | `restore by event` | 允许从一条审计事件直接跳转并执行恢复 | `restore_from_event` | 给定 `event_id` 可以定位 `before_ref` 或 `restore_ref` |
717
- | `impact set` | 为高风险编辑记录受影响文件 / 符号 / 测试集合 | `impact_set` 字段 | 查询事件时能看到"这次改动可能波及哪里" |
718
- | `MCP / CLI surface` | 暴露最小可用接口给 Agent 和终端 | `register_intent` / `list_active_intents` / `audit_query` / `get_event` / `restore_from_event` | AI 不需要拼复杂 shell，就能完成查询与恢复 |
719
- | `dashboard / doctor` | 把活跃会话、冲突告警、最近 AI 事件纳入诊断和看板 | `dashboard` / `doctor` 扩展字段 | 用户能看见"现在谁在改、最近改了什么、哪里有冲突" |
720
- | `always_watch` | 配置项 `"always_watch": true`，MCP server 启动时自动内嵌 watcher 循环；用户可选两种保护模式：**轻量模式**（默认，AI 手动 `snapshot_now`）vs **强保护模式**（watcher 始终在后台，所有变更自动备份） | `.cursor-guard.json` 配置 + MCP server 启动逻辑 | MCP server 启动后，`always_watch: true` 的项目自动有 watcher 保护，无需额外命令；选择权在用户 |
721
- | `embedded watcher` | **消灭进程边界**：不再是独立后台进程，而是 MCP server 同进程内的 watcher 循环。同进程 = 无 IPC、无文件桥接、无并发竞争。检测到文件变更时自动创建 snapshot，不依赖 AI 手动调用 | MCP server 内部模块 | watcher 停止 = 裸奔的保护缺口彻底消除；AI 忘记 snapshot 也有兜底 |
722
- | `begin_edit` / `end_edit` | **意图-变更原子绑定**：AI 编辑前调 `begin_edit({ intent, files[], agent, session })`，在内存 `Map<session, EditScope>` 注册编辑意图和目标文件。embedded watcher 检测到变更时按**文件路径**匹配 intent，自动备份带完整上下文。`end_edit(session)` 或 TTL（默认 5 分钟）自动清除 | `begin_edit` / `end_edit` MCP 工具 + 内存 `activeEdits` Map | auto-backup 也能带 intent/agent/session；并发多 Agent 按文件路径消歧，不按时间顺序 |
723
- | `tests / docs` | 为事件链路补齐单测、集成测试和文档 | tests + schema docs | V5.0 的所有核心事件和恢复路径都有测试覆盖 |
719
+ | `intent registry` | 注册编辑意图（agent、会话、目标文件、风险级别） | ✅ V4.3.3：`snapshot_now` 支持 `intent/agent/session`，Git trailer 存储，仪表盘展示 | 升级为 `begin_edit` MCP 工具，内存 Map 管理活跃会话，支持文件路径级冲突检测 |
720
+ | `pre-edit snapshot` | 每次高风险写入前创建恢复点 | ✅ V4：`restore_file` / `restore_project` 自动创建 `refs/guard/pre-restore/*` | 新增 `refs/guard/pre-edit/<session>/<seq>`，按会话隔离 |
721
+ | `conflict detection` | 并发编辑冲突告警 | — | 新增：`begin_edit` 时检测文件路径重叠，advisory warning |
722
+ | `audit store` | 审计事件存储与查询 | ✅ V4.3.0-V4.3.3：Git commit trailer 持久化（trigger/intent/agent/session），`listBackups` 可解析 | 升级为独立 JSONL 审计存储，支持按事件 ID / 文件 / 会话 / 风险级别查询 |
723
+ | `restore by event` | 从审计事件直接恢复 | — | 新增：`restore_from_event(event_id)` → 定位 `before_ref` → 执行恢复 |
724
+ | `impact set` | 记录变更波及范围 | ✅ V4.5.2：告警携带结构化文件列表 `[{path, action, added, deleted}]` | 升级：增加符号级分析（导出/引用变更检测） |
725
+ | `MCP / CLI surface` | 变更控制接口 | ✅ V4：9 个 MCP 工具（doctor / list_backups / snapshot_now / restore_file / restore_project / doctor_fix / backup_status / dashboard / alert_status） | 新增：`begin_edit` / `end_edit` / `audit_query` / `get_event` / `restore_from_event` |
726
+ | `dashboard / doctor` | 看板和诊断 | ✅ V4.2-V4.5.3：完整 Web 仪表盘，告警卡片+历史、备份表格+抽屉、诊断面板、结构化文件表格 | 扩展：活跃会话面板、冲突告警卡片、AI 事件时间线 |
727
+ | `always_watch` | 强保护模式 | ✅ **V4.5.4 已完整实现**：`always_watch: true` → MCP server 首次 tool 调用自动 spawn watcher 进程，`ensureWatcher()` + `watchedProjects` Map + 锁文件互斥兼容 | V5 进一步升级为 embedded watcher（同进程内嵌，非独立进程） |
728
+ | `embedded watcher` | 同进程 watcher 循环 | 部分：V4.5.4 `always_watch` 通过 spawn 独立子进程实现（解决了"裸奔"问题，但仍是跨进程） | **核心差异**：MCP server 内嵌 watcher 循环，同进程=无 IPC、无竞争。检测变更时按文件路径匹配 `begin_edit` 中的 intent |
729
+ | `begin_edit` / `end_edit` | 意图-变更原子绑定 | — | **核心新增**：`begin_edit({ intent, files[], agent, session })` → 内存 `Map<session, EditScope>` → watcher 按文件路径匹配 → auto-backup 带完整上下文。`end_edit` 或 TTL 5min 自动清除 |
730
+ | `Shadow 增量优化` | 节省磁盘 I/O | ✅ **V4.5.4 已完整实现**：硬链接未变文件（mtime+size 比较），mtime 保留，跨卷容错，日志显示 linkedCount | — |
731
+ | `备份结构化文件数据` | 结构化 files 数组 | ✅ **V4.5.2-V4.5.3 已完整实现**：snapshot changedFiles、anomaly alert files、`getBackupFiles` API、前端 mini 表格+抽屉可排序表格 | — |
732
+ | `tests / docs` | 测试和文档 | ✅ V4：138 测试全过（utils 39 + core 78 + MCP 21） | 为 V5 新增事件链路补齐测试 |
724
733
 
725
734
  ### V5 核心设计：Embedded Watcher + 文件路径意图绑定
726
735
 
@@ -789,8 +798,15 @@ MCP Server 进程（知道 intent） ←——×——→ Watcher 进程（知
789
798
  #### 实现分期
790
799
 
791
800
  ```
792
- Phase 1 (V5.0):
793
- ├── always_watch: true → MCP server 内嵌 watcher 循环
801
+ Phase 0 (V4.5.x — ✅ 已完成):
802
+ ├── always_watch: true → MCP server 自动 spawn watcher 子进程（V4.5.4）
803
+ ├── 结构化文件数据：snapshot changedFiles + alert files + getBackupFiles API（V4.5.2-V4.5.3）
804
+ ├── Shadow 硬链接增量优化（V4.5.4）
805
+ ├── 告警历史 UX + 备份文件表格化（V4.5.3）
806
+ └── intent/agent/session 基础支持（V4.3.3）
807
+
808
+ Phase 1 (V5.0 — 核心差异化):
809
+ ├── always_watch 升级：从 spawn 独立进程 → MCP server 内嵌 watcher 循环（同进程）
794
810
  ├── 新增 begin_edit / end_edit MCP 工具
795
811
  ├── 内存 Map<session, EditScope> 管理活跃编辑意图
796
812
  └── watcher 变更检测时查 Map，按文件路径匹配 intent → 写入 commit trailer
@@ -938,7 +954,8 @@ V5 的关键不是"多打一行日志"，而是建立完整证据链：
938
954
 
939
955
  ### V5 完成标志（Definition of Done）
940
956
 
941
- - `always_watch: true` 配置生效后，MCP server 启动自动内嵌 watcher 循环，用户无需额外命令
957
+ - ~~`always_watch: true` 配置生效后，用户无需额外命令~~ → ✅ **V4.5.4 已完成**（spawn 子进程方式）
958
+ - V5 升级：`always_watch` 从 spawn 子进程升级为 MCP server 内嵌 watcher 循环（同进程，无 IPC）
942
959
  - `begin_edit` / `end_edit` MCP 工具可用，AI 能声明编辑意图和目标文件
943
960
  - embedded watcher 的自动备份能通过文件路径匹配关联 `begin_edit` 中的 intent/agent/session
944
961
  - 无 `begin_edit` 时自动备份行为与 V4 一致（无退化）
@@ -946,7 +963,8 @@ V5 的关键不是"多打一行日志"，而是建立完整证据链：
946
963
  - 用户能查询最近一次 AI 编辑的完整上下文
947
964
  - 给定 `event_id` 能找到对应快照并执行恢复
948
965
  - 两个活跃会话改同一文件时，系统能稳定给出冲突告警
949
- - dashboard / doctor 能展示最近 AI 事件、活跃会话和未解决冲突
966
+ - ~~dashboard / doctor 展示告警、备份详情~~ → ✅ **V4.2-V4.5.3 已完成**（Web 仪表盘、告警卡片+历史、结构化文件表格、可排序抽屉）
967
+ - V5 扩展：dashboard 增加活跃会话面板、冲突告警卡片、AI 事件时间线
950
968
 
951
969
  ### 进入 V6 的衡量标准
952
970
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cursor-guard",
3
- "version": "4.5.4",
3
+ "version": "4.5.5",
4
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 安全网、确定性恢复。",
5
5
  "keywords": [
6
6
  "cursor",