检查点与版本管理
检查点创建、历史记录、回滚策略、Git集成
引言
AI 修改代码时，最大的风险是什么？改坏了却回不去。
CodeBuddy 的检查点系统正是为解决这个问题——每次 AI 修改代码前自动创建快照，让你随时可以回退到任意历史状态。
核心价值：让 AI 大胆改，你放心看。改错了？一键回退。
一、检查点 vs Git
1.1 详细对比
| 特性 | 检查点 | Git |
|---|---|---|
| 创建方式 | 自动（AI 修改前） | 手动（开发者 commit） |
| 粒度 | 每次 AI 操作 | 每次有意义的变更 |
| 回退速度 | 即时（内部快照） | 需要 checkout/merge |
| 存储位置 | 本地（CodeBuddy 管理） | 仓库（.git 目录） |
| 适用场景 | AI 修改回退 | 版本管理、团队协作 |
| 保留时间 | 当前会话 | 永久 |
| 可视化 | IDE 中直接查看 | 需要 git log |
1.2 什么时候用什么？
场景 1：AI 重构了 10 个文件，你发现方向不对
→ 检查点回退（即时）
→ 给 AI 新指令重新开始
场景 2：功能开发完成，需要提交代码
→ Git commit（永久保存）
→ 写清楚的 commit message
场景 3：AI 修改了 3 个文件，你想保留其中 2 个
→ 检查点回退到修改前
→ 手动保留想要的修改
→ 让 AI 只修改第 3 个文件
二、使用方式详解
2.1 通过 UI 操作（官方推荐）
CodeBuddy IDE 的检查点功能通过 UI 操作，不支持命令行方式：
查看检查点：
- 在 IDE 侧栏找到「历史」标签页
- 查看检查点列表，包含时间戳和描述
回退到检查点：
- 在历史标签页中选择目标检查点
- 点击「回退」按钮
- 确认回退操作
创建检查点：
- 检查点由 AI Agent 自动创建
- 每次有意义的代码变更后自动保存
- 也可以手动触发创建
2.2 检查点 vs Git
| 维度 | 检查点 | Git |
|---|---|---|
| 粒度 | 每次 AI 操作 | 每次有意义的变更 |
| 自动化 | AI 自动创建 | 手动 commit |
| 回退速度 | 秒级 | 需要 checkout |
| 适用场景 | AI 操作回退 | 版本管理 |
2.3 最佳实践
- 大胆尝试：有了检查点，可以放心让 AI 做激进改动
- 及时回退：发现问题立即回退，不要积累
- 结合 Git：检查点用于短期回退，Git 用于长期版本管理
2.1 查看检查点列表
通过 UI 查看
# 输出示例：
# checkpoint-003 2026-06-18 14:32 "重构 auth 模块"
# checkpoint-002 2026-06-18 14:28 "添加登录接口"
# checkpoint-001 2026-06-18 14:25 "创建 User 模型"
2.2 查看检查点详情
通过 UI 查看 checkpoint-002
# 输出：
# 创建时间：2026-06-18 14:28
# 触发操作：write_file
# 影响文件：
# - src/auth/login.ts (新增)
# - src/auth/index.ts (修改)
# - package.json (修改)
2.3 回退到指定检查点
通过 UI 回退 checkpoint-001
# 输出：
# ✅ 已回退到 checkpoint-001
# 恢复文件：3 个
# 当前状态：创建 User 模型之后
2.4 手动创建检查点
AI 自动创建 "重要功能完成前的备份"
# 输出：
# ✅ 已创建 checkpoint-004
三、安全的 AI 修改工作流
3.1 推荐工作流
步骤 1：确保代码已提交
git add . && git commit -m "before AI refactoring"
步骤 2：让 AI 开始修改
AI 自动创建 checkpoint-001
步骤 3：审查 AI 的修改
如果满意 → 继续
如果不满意 → 通过 UI 回退 checkpoint-001
步骤 4：AI 继续修改
AI 自动创建 checkpoint-002
步骤 5：全部完成后，提交到 Git
git add . && git commit -m "AI refactoring complete"
3.2 实战案例
你：帮我重构 src/utils/ 目录，把重复代码合并
AI：好的，我先分析一下...
（自动创建 checkpoint-001）
发现 12 个重复函数，我将合并为 4 个工具模块
你：等一下，我想保留 date-utils.ts 的原始实现
AI：好的，回退到 checkpoint-001
通过 UI 回退 checkpoint-001
现在我只重构其他 3 个模块
AI：开始重构...
（自动创建 checkpoint-002）
✅ 合并 string-utils.ts
✅ 合并 array-utils.ts
✅ 合并 validation-utils.ts
四、Git 集成
4.1 智能提交
CodeBuddy 的 /commit 命令会自动分析代码变更，生成有意义的 commit message：
/commit
# AI 分析变更：
# - 新增 src/auth/login.ts → feat
# - 修改 src/api/users.ts → feat (添加登录相关接口)
# - 新增 tests/auth/login.test.ts → test
# 自动生成：
# git commit -m "feat: add user authentication with JWT"
4.2 提交规范
CodeBuddy 遵循 Conventional Commits 规范：
| 变更类型 | 前缀 | 示例 |
|---|---|---|
| 新功能 | feat: | feat: add user login |
| Bug 修复 | fix: | fix: resolve auth token expiry |
| 重构 | refactor: | refactor: extract auth middleware |
| 测试 | test: | test: add login unit tests |
| 文档 | docs: | docs: update API documentation |
| 样式 | style: | style: format code with prettier |
五、常见陷阱
陷阱 1：检查点不替代 Git
❌ 只用检查点管理版本，从不 commit
✅ 重要里程碑必须 commit，检查点只用于 AI 修改的临时回退
陷阱 2：检查点会占用磁盘
❌ 让 AI 运行 1000 次操作，创建 1000 个检查点
✅ 定期清理不需要的检查点
陷阱 3：回退后 AI 记忆仍在
❌ 回退检查点后，AI 还记得之前的修改
✅ 回退后开新会话，避免 AI 基于过时信息继续工作
六、总结
| 问题 | 答案 |
|---|---|
| 检查点是什么？ | AI 修改前的自动快照 |
| 和 Git 的区别？ | 检查点自动+临时，Git 手动+永久 |
| 如何回退？ | 通过 UI 回退 <id> |
| 最佳实践？ | Git 管版本，检查点管 AI 修改 |