EvolStore MCP

EvolStore 是为任务工作空间设计的版本控制文件管理系统，提供自动版本归档和快照管理功能。通过 MCP 服务器暴露接口，可供 AI Agent 集成使用。

功能概述

功能模块	描述
自动版本管理	每次文件变更自动创建历史版本
快照系统	语义化版本管理，支持回滚
文件操作	读写、删除、恢复文件
版本对比	查看不同版本间的差异
全量扫描	导入现有文件、捕获手动修改

核心特性

1. 自动版本管理

• 自动归档 - 每次文件变更都会自动创建历史版本
• 全局版本号 - 所有文件变更使用统一的递增版本号（1, 2, 3...）
• 版本分离 - 当前文件存放在工作空间，历史版本统一保存在 .esdata/vermgr/ 目录

2. 快照系统

• 语义化版本 - 快照使用 MAJOR.MINOR.PATCH 格式（如 1.2.0）
• 指针式快照 - 快照只存储"文件路径→版本号"的映射，不复制文件，节省空间
• 版本升级策略：
  • 仅内容变更：PATCH +1
  • 增删文件：MINOR +1
  • 强制升级：MAJOR +1
• 快照回滚 - 可一键回滚到任意快照状态
• 快照导入导出 - 支持跨环境迁移和备份

3. 文件操作功能

• 写入文件 - 自动检测变化并归档历史版本
• 读取文件 - 支持读取当前版本或任意历史版本
• 删除文件 - 删除当前版本，历史版本受快照保护
• 恢复文件 - 用历史版本覆盖当前文件
• 文件对比 - 查看同一文件不同版本间的差异
• 目录浏览 - 支持分页和递归浏览工作空间目录
• 历史查询 - 查看文件的所有历史版本信息

4. 全量扫描模式

• 首次导入 - 可全量扫描工作空间，将所有现有文件纳入版本管理
• 捕获手动修改 - 扫描发现未通过 API 操作的文件并自动备份
• 完整备份 - 创建包含工作空间所有文件的完整快照

MCP 工具接口

EvolStore 通过 MCP Server 提供以下工具：

工具名称	功能
write_file	写入文件并自动归档历史
read_file	读取当前或历史版本
delete_file	删除文件
restore_file	恢复到历史版本
create_snapshot	创建快照
list_snapshots	获取快照列表
rollback_snapshot	回滚到指定快照
get_file_versions	查看文件历史版本
compare_versions	对比文件版本
list_directory	浏览目录
get_statistics	获取统计信息
scan_workspace	全量扫描工作空间

使用场景

1. AI Agent 工作空间

为 AI Agent 提供可靠的文件版本管理，防止误操作导致数据丢失。

2. 项目开发协作

记录项目文件的完整演化历史，支持版本回溯和对比。

3. 定期备份

创建项目快照，在重要节点保存完整状态。

4. 数据恢复

误删除或误修改文件后，可快速恢复到历史版本。

核心优势

优势	说明
自动化	无需手动创建备份，所有变更自动归档
轻量级	快照采用指针式设计，不重复存储文件
安全性	事务保护、原子操作、路径安全校验
灵活性	支持部分快照和全量快照两种模式
可追溯	完整的操作日志和审计记录
易集成	通过 MCP 协议与 AI Agent 无缝集成

审计与统计

• 操作日志 - 记录所有文件操作和快照操作的详细日志
• 统计信息 - 提供文件数量、版本数、存储空间等统计数据
• 清理功能：
  • 清理旧快照（保留最新 N 个）
  • 清理未被快照引用的历史版本

提示

EvolStore 服务随 Evol 应用自动启动，无需手动配置。