TimeVault - 代码时光保险库

让代码回滚像 Ctrl+Z 一样简单

一个基于 Node.js 的本地代码自动追踪系统，采用集中式存储，自动监控文件变化并创建 checkpoint，支持通过交互式 CLI 进行版本回滚和查询。

✨ 核心特性

🔒 集中式存储: 所有项目的备份统一存储在程序目录，不会污染项目代码
💬 交互式 CLI: 友好的命令行界面，自动打开，无需记忆 API
🚀 智能启动: 自动管理项目启用状态，优化性能
📦 多项目管理: 同时监控多个项目，统一管理
💾 混合存储: 完整快照 + 增量差异，节省 80-90% 空间
⏮️ 完整回滚: 基于快照对比的精确回滚，支持任意跳转
🏷️ 标签快照: 手动创建带名称的重要节点快照
🔍 分页查看: 支持查看任意时期的 checkpoint 历史
⏸️ 智能暂停: 回滚时自动暂停监控，避免创建重复 checkpoint

🚀 快速开始

# 1. 安装依赖
npm install

# 2. 启动服务（自动打开 CLI 管理界面）
npm start

就这么简单！ 服务启动后会自动打开交互式管理界面。

📋 CLI 管理界面

============================================================
TimeVault - 交互式管理界面
============================================================

1. 查看所有项目
2. 添加项目
3. 启用项目
4. 禁用项目
5. 删除项目
6. 查看项目详情
7. 查看 Checkpoint 列表
8. 回滚到 Checkpoint
9. 创建标签快照
10. 查看系统状态
0. 退出

📖 使用流程

首次使用

运行 npm start
CLI 自动打开，选择 2. 添加项目
输入项目路径: D:\projects\my-app
输入项目名称（可选）: 我的应用
✅ 系统自动创建初始完整快照并开始监控！

日常使用

npm start  # 启动服务，自动打开 CLI

已启用的项目自动开始监控
每次保存文件自动创建 checkpoint
通过 CLI 查看历史和回滚

创建重要节点快照

在 CLI 中选择 9. 创建标签快照
选择项目
输入标签名称: v1.0.0 或 重要功能完成
✅ 创建完整快照，方便日后快速定位

误删代码恢复

打开 CLI（如已关闭: npm run cli）
选择 8. 回滚到 Checkpoint
选择项目
输入显示数量和偏移量（查看更早的 checkpoint）
选择删除前的 checkpoint
确认回滚
✅ 代码完整恢复！

查看历史记录

选择 7. 查看 Checkpoint 列表
选择项目
输入显示数量: 20
输入跳过数量: 0（查看最新 20 个）或 20（查看第 21-40 个）
查看详细的文件变化列表

💡 核心概念

Checkpoint 类型

📸 SNAPSHOT（快照）: 完整快照，保存所有文件的完整内容
- 系统默认每 10 个 checkpoint 创建一次
- 添加项目时自动创建初始快照
- 手动创建标签快照
📝 DIFF（差异）: 增量差异，只保存变化部分
- 节省 80-90% 存储空间
- 基于最近的快照生成
🏷️ 标签快照: 带自定义名称的完整快照
- 用于标记重要节点
- 方便快速定位和回滚

回滚机制

TimeVault 使用完整快照对比的回滚机制：

重建目标状态: 遍历 checkpoint 链，重建目标时间点的完整文件状态
扫描当前目录: 获取当前所有文件列表
对比差异:
- 当前有但目标没有 → 删除（包括新增的文件）
- 目标有但当前没有 → 创建
- 都有但内容不同 → 覆盖
应用变化: 执行删除、创建、覆盖操作

优势：

✅ 支持任意方向跳转（早期 ↔ 中期 ↔ 后期）
✅ 精确恢复到目标时间点的完整状态
✅ 自动删除目标时间点之后新增的文件
✅ 保留未被追踪的文件

智能监控暂停

回滚操作会自动暂停文件监控，避免创建重复的 checkpoint：

回滚前：暂停监控
执行回滚：修改文件不触发 checkpoint
回滚后：延迟 1 秒恢复监控

集中式存储

TimeVault/
└── .tracker-data/              # 集中式数据目录
    ├── projects.json           # 项目列表
    └── projects/
        ├── 48e9d204/           # 项目 1 的备份
        │   ├── index.json      # Checkpoint 元数据
        │   ├── config.json     # 项目配置
        │   └── checkpoints/
        │       ├── snapshots/  # 完整快照
        │       └── diffs/      # 增量差异
        └── a1b2c3d4/           # 项目 2 的备份

优势：

✅ 删除项目代码不会删除备份
✅ 不污染项目目录
✅ 统一管理所有备份
✅ 无需配置 .gitignore
✅ 方便整体备份和迁移

🎯 使用场景

场景 1: 日常开发保护

# 早上启动
npm start

# 开发中
# 每次保存文件，自动创建 checkpoint
# 完全不需要手动操作

# 晚上关闭
# 在 CLI 中选择 0. 退出

场景 2: 实验性修改

# 创建标签快照
CLI → 9. 创建标签快照 → "实验前的稳定版本"

# 大胆修改代码
# 系统自动记录每一步

# 实验失败？
CLI → 8. 回滚 → 选择 "实验前的稳定版本"
# ✅ 一键恢复！

场景 3: 版本发布

# 发布前创建标签
CLI → 9. 创建标签快照 → "v1.0.0 发布版本"

# 发布后出现问题
CLI → 8. 回滚 → 选择 "v1.0.0 发布版本"
# ✅ 快速回退到发布版本

场景 4: 多次回滚

# 当前在最新版本
CLI → 8. 回滚 → 选择中期 checkpoint
# 回滚到中期

# 发现还不够早
CLI → 8. 回滚 → 输入偏移量查看更早的记录 → 选择早期 checkpoint
# 回滚到早期

# 想回到中期
CLI → 8. 回滚 → 选择中期 checkpoint
# 回滚到中期

# ✅ 任意跳转，每次都准确！

场景 5: 管理多个项目

# 添加 10 个项目
CLI → 2. 添加项目（重复 10 次）

# 禁用不常用的 7 个
CLI → 4. 禁用项目（重复 7 次）

# 下次启动只监控 3 个常用项目
# 内存占用: ~15MB（vs ~50MB）

📊 性能特性

场景	内存	CPU	启动时间	回滚速度
10 个项目全启用	~50MB	<1%	<1 秒	1-3 秒
100 个项目全启用	~500MB	<10%	~10 秒	1-3 秒
100 个项目，90 个禁用	~50MB	<1%	<1 秒	1-3 秒
1000 个文件的项目回滚	-	-	-	10-30 秒

建议：

只启用常用项目（3-10 个）
不常用的项目禁用以节省资源
需要时再启用

🔧 高级功能

API 使用

如果你更喜欢用 API 而不是 CLI：

# 添加项目
curl -X POST http://localhost:3000/api/projects/add \
  -H "Content-Type: application/json" \
  -d '{"targetDir": "D:\\path\\to\\project", "name": "项目名称"}'

# 查看所有项目
curl http://localhost:3000/api/projects

# 查看 checkpoint（支持分页）
curl "http://localhost:3000/api/projects/:id/checkpoints?limit=20&offset=0"

# 创建标签快照
curl -X POST http://localhost:3000/api/projects/:id/checkpoints/tag \
  -H "Content-Type: application/json" \
  -d '{"tagName": "v1.0.0"}'

# 回滚
curl -X POST http://localhost:3000/api/projects/:id/rollback/:checkpointId

# 启用/禁用项目
curl -X POST http://localhost:3000/api/projects/:id/enable
curl -X POST http://localhost:3000/api/projects/:id/disable

重新打开 CLI

如果关闭了 CLI 但服务还在运行：

npm run cli

配置文件

默认配置位于 .tracker-data/config.json：

{
  "port": 3000,
  "debounceDelay": 300,
  "snapshotInterval": 10,
  "maxCheckpoints": 100,
  "ignore": [
    "node_modules/**",
    ".git/**",
    ".tracker-data/**",
    "*.log",
    "*.tmp",
    ".DS_Store"
  ]
}

❓ 常见问题

Q: 会影响我的项目代码吗？

A: 完全不会。所有备份数据都存储在 TimeVault 程序目录的 .tracker-data 文件夹中，与项目代码完全隔离。

Q: 删除项目代码会删除备份吗？

A: 不会。备份数据独立存储，删除项目代码不会影响备份。你可以随时恢复。

Q: 重复添加同一项目会怎样？

A: 系统会拒绝添加，返回 "Project already exists" 错误，原有数据完全不受影响。

Q: 第二天启动会自动监控吗？

A: 是的。只要项目是启用状态（enabled: true），启动服务时会自动开始监控。

Q: 回滚会创建新的 checkpoint 吗？

A: 不会。回滚时系统会自动暂停文件监控，回滚完成后才恢复，避免创建重复的 checkpoint。

Q: 可以回滚到更新的版本吗？

A: 可以！TimeVault 使用完整快照对比机制，支持任意方向跳转（早期 ↔ 中期 ↔ 后期）。

Q: 监控很多项目会有性能问题吗？

A: 会有一定影响。建议：

只启用常用项目（3-10 个）
不常用的项目禁用
需要时再启用

Q: 如何备份 TimeVault 的数据？

A: 直接备份 .tracker-data 文件夹即可，包含所有项目的完整备份数据。

Q: 标签快照和普通快照有什么区别？

A: 标签快照是带自定义名称的完整快照，方便标记重要节点（如版本发布、功能完成）。普通快照是系统自动创建的。

Q: 如何查看很早以前的 checkpoint？

A: 在查看或回滚时，输入"跳过前 N 个"参数。例如跳过 100 个，就能查看第 101-120 个 checkpoint。

🆚 与 Git 的区别

特性	TimeVault	Git
触发方式	自动被动	手动 commit
粒度	文件保存级别	逻辑提交级别
元数据	时间戳 + 可选标签	commit message
协作	单机使用	多人协作
存储位置	集中式（程序目录）	分散式（.git）
回滚方式	完整快照对比	基于 commit 链
适用场景	实时备份、误操作恢复、实验性修改	版本管理、团队协作、代码审查

建议：TimeVault 和 Git 配合使用

TimeVault：本地的"无限撤销"，自动保护每一次修改
Git：正式的版本管理，团队协作和代码审查

📝 更新日志

v3.0.0 (2025-12-29)

重大改进：

✅ 完整快照对比回滚机制（支持任意方向跳转）
✅ 标签快照功能（手动创建带名称的重要节点）
✅ 分页查看 checkpoint（支持查看任意时期的历史）
✅ 智能监控暂停（回滚时自动暂停，避免重复 checkpoint）
✅ 初始完整快照（添加项目时自动创建）
✅ 修复新增文件回滚后不删除的 bug
✅ 修复连续回滚状态不准确的 bug

v2.0.0 (2025-12-29)

重大改进：

✅ 集中式存储架构
✅ 交互式 CLI 界面
✅ 自动打开 CLI
✅ 智能启动策略
✅ 多项目管理支持
✅ 项目启用/禁用功能
✅ 性能优化

Breaking Changes：

API 路径变更: /api/checkpoints → /api/projects/:id/checkpoints
存储位置变更: 项目目录 .tracker/ → 程序目录 .tracker-data/projects/

📄 许可证

MIT

🎉 开始使用

npm start

TimeVault v3.0 - 代码时光保险库，让每一次修改都有迹可循

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

kbykb/timevault

Folders and files

Latest commit

History

Repository files navigation