# Checkpoint 导入/导出指南

本指南说明如何在 GNS3 Copilot 侧边栏中使用导入和导出会话功能。

## 功能概述

GNS3 Copilot 现在支持在侧边栏中直接导出和导入会话，方便您：

- 📤 **导出会话**：保存当前会话到本地文件作为备份
- 📥 **导入会话**：从本地文件恢复之前导出的会话
- 🔄 **会话迁移**：在不同实例或设备之间迁移会话

## 使用导出功能

### 步骤 1：选择会话

在侧边栏的"会话历史"下拉框中选择要导出的会话。

### 步骤 2：点击导出按钮

在"当前会话"信息下方，点击 **:material/download: Export** 按钮。

### 步骤 3：下载文件

导出成功后，会显示一个下载按钮 **:material/download_file: Download File**，点击即可下载文件。

### 文件命名

导出的文件名格式为：`{会话标题}_{时间戳}.json`

例如：`Network_Configuration_20260108_234012.json`

### 文件内容

导出的文件包含：
- ✅ 完整的 checkpoint 数据
- ✅ 所有消息（包括 tool_calls）
- ✅ 对话标题
- ✅ 选中的 GNS3 项目
- ✅ 会话元数据

## 使用导入功能

### 步骤 1：上传文件

在侧边栏的"**导入会话**"区域，点击"**Browse files**"按钮选择文件。

### 支持的文件格式

- `.json` - 推荐格式
- `.txt` - 兼容格式

### 步骤 2：自动导入

选择文件后，系统会自动：
1. 验证文件格式
2. 导入会话数据
3. 创建新的线程
4. 刷新会话列表

### 步骤 3：查看导入的会话

导入成功后，会显示成功消息，包括新的 thread ID。您可以从会话历史下拉框中选择新导入的会话。

## 使用场景

### 场景 1：备份重要会话

```text
1. 选择重要会话
2. 点击"导出"按钮
3. 下载并保存文件到安全位置
```

### 场景 2：在不同设备间迁移

```text
设备 A:
1. 导出会话 → 下载文件 → 传输文件

设备 B:
2. 上传文件 → 导入会话 → 开始使用
```

### 场景 3：恢复误删的会话

```text
1. 从备份文件选择导出的会话
2. 导入到新的线程
3. 继续使用恢复的会话
```

## 常见问题

### Q: 导出的文件包含哪些数据？

A: 导出的文件包含完整的会话状态，包括：
- 所有对话消息（用户、AI、工具调用）
- 对话标题
- 选中的 GNS3 项目
- 会话元数据和配置

### Q: 导入的会话会覆盖现有会话吗？

A: 不会。导入功能会创建一个新的线程，不会影响现有会话。

### Q: 导入后需要重新选择会话吗？

A: 是的。导入成功后，您需要在会话历史下拉框中选择新导入的会话才能查看和使用。

### Q: 支持导入其他版本的导出文件吗？

A: 支持导入任何通过 GNS3 Copilot 导出的会话文件。只要文件格式正确，都可以成功导入。

### Q: 导入失败怎么办？

A: 如果导入失败，系统会显示详细的错误信息。常见原因包括：
- 文件格式不正确（必须是有效的 JSON）
- 文件不是由 GNS3 Copilot 导出的
- 文件已损坏

### Q: 中文内容会乱码吗？

A: 不会。导出和导入都使用 UTF-8 编码，正确处理中文等多语言内容。

## 最佳实践

1. **定期备份**：定期导出重要会话作为备份
2. **命名规范**：保持会话标题清晰，便于识别导出的文件
3. **安全存储**：将导出的文件存储在安全的位置
4. **验证导入**：导入后检查会话内容是否完整
5. **版本兼容**：确保使用相同版本的 GNS3 Copilot 导入和导出

## 技术细节

### 文件格式

导出的文件是 JSON 格式，结构如下：

```json
{
  "checkpoint": {
    "v": 3,
    "ts": "2026-01-08T23:40:12.123456",
    "id": "checkpoint-id",
    "channel_values": {
      "messages": [...],
      "conversation_title": "...",
      "selected_project": (...)
    },
    "channel_versions": {...},
    "versions_seen": {...},
    "next": null
  },
  "config": {...},
  "metadata": {...}
}
```

### 消息序列化

所有消息都经过序列化处理，确保：
- JSON 兼容性
- 跨实例迁移
- UI 兼容性

### 数据验证

导入时会验证：
- 文件格式有效性
- 数据结构完整性
- 消息 UI 兼容性

## 相关文档

- [Checkpoint 使用指南](../CHECKPOINT_USAGE_GUIDE.md)
- [Checkpoint 调试指南](../development/checkpoint-debugging-guide.md)
- [用户常见问题](FAQ_ZH.md)