checkpoint-manager

Checkpoint Manager 是一个面向自主编码（autonomous coding）场景的状态快照与回滚工具，核心目标是在进行有风险的改动前保存项目状态，并在操作失败时安全回滚。

用途该工具用于创建和管理状态检查点，以便在自主编码过程中安全地进行实验。当需要创建检查点、回滚更改、管理恢复点或实现安全实验流程时，可以使用它。

主要能力

创建检查点：通过 CheckpointManager 类调用 create_checkpoint 方法，可指定名称和描述，例如在重大重构前保存状态。
回滚：支持回滚到指定检查点（rollback(checkpoint.id)）或回滚到最新检查点（rollback_to_latest()）。
状态捕获：检查点会捕获 Git 状态（提交哈希、分支、未提交文件）、功能列表快照、进度文件状态以及上下文信息（会话编号、token 使用量），并存储检查点元数据。
检查点类型：包括自动（在风险操作前触发，保留最近 5 个）、手动（用户或智能体请求，保留至删除）、功能（功能完成后触发，永久保留）、会话（会话开始时触发，保留最近 3 个）。
集成点：可与 error-recoverer（失败时触发回滚）、coding-agent（更改前创建检查点）、autonomous-loop（管理检查点生命周期）、context-state-tracker（提供状态给检查点）等组件配合使用。

使用方式通过 Python 导入并使用：

from scripts.checkpoint_manager import CheckpointManager

manager = CheckpointManager(project_dir) checkpoint = await manager.create_checkpoint( name="before-refactor", description="State before major refactoring" )

回滚示例：

await manager.rollback(checkpoint.id)

或回滚到最新

await manager.rollback_to_latest()

检查点结构示例（JSON）： { "id": "checkpoint-20250115-103000", "name": "before-refactor", "description": "State before major refactoring", "timestamp": "2025-01-15T10:30:00", "git_state": { "commit_hash": "abc1234", "branch": "main", "dirty_files": ["src/app.ts"] }, "feature_state": { "current": "auth-003", "completed": ["auth-001", "auth-002"], "snapshot_path": ".claude/checkpoints/checkpoint-xxx/feature_list.json" }, "context": { "session_number": 5, "token_usage": 45000 } }

工作流程

创建检查点：捕获 Git 状态、快照功能列表、保存进度文件状态、记录上下文、存储检查点元数据。
执行风险操作：尝试操作，成功则继续，失败则回滚到检查点。
回滚：加载检查点数据、Git 重置到检查点提交、恢复功能列表、恢复进度文件、清理临时文件。

技能介绍

或回滚到最新