---
name: lightclaw-backup
description: >-
  LightClaw 备份与版本管理。当用户需要创建备份、恢复备份、查看备份列表、
  清理旧备份或管理备份轮转时使用。触发词包括：backup, restore, snapshot,
  备份, 恢复, 回滚, 快照, 版本管理, 导出配置, 导入配置, save state.
metadata:
  lightclaw:
    emoji: "💾"
---

# LightClaw 备份与版本管理 💾

你是一个可靠的备份助手。你的任务是帮助用户创建、查看、恢复和轮转 LightClaw
工作区数据的备份。

## 快速参考

| 操作 | 命令 |
|------|------|
| 创建备份 | `python <skill-scripts-dir>/backup.py create` |
| 创建带标签的备份 | `python <skill-scripts-dir>/backup.py create --label "升级前"` |
| 查看备份列表 | `python <skill-scripts-dir>/backup.py list` |
| 恢复最近的备份 | `python <skill-scripts-dir>/backup.py restore` |
| 恢复指定备份 | `python <skill-scripts-dir>/backup.py restore --id <backup_id>` |
| 对比差异 | `python <skill-scripts-dir>/backup.py diff --id <backup_id>` |
| 清理旧备份 | `python <skill-scripts-dir>/backup.py clean --keep 7` |

## 备份内容

备份**仅涵盖工作区目录** `~/.lightclaw/workspace/` 下的内容。
归档内路径以 workspace 为根，恢复时会精准放回 workspace 目录。

### 工作区（WORKING_DIR: `~/.lightclaw/workspace/`）

| 项目 | 说明 |
|------|------|
| `*.md` | 所有 Markdown 文件（SOUL.md、HEARTBEAT.md、IDENTITY.md、USER.md 等） |
| `skills/` | 已安装的和自定义的 Skill |
| `memory/` | Agent 记忆文件 |
| `custom_channels/` | 用户安装的自定义 Channel 模块 |

### 不备份的内容

以下内容体积大、属于临时数据或可自动重建，不在备份范围内：

| 排除项 | 原因 |
|--------|------|
| `models/` | 本地 LLM 模型文件（体积极大，可重新下载） |
| `sessions/` | 运行时会话数据（临时性） |
| `uploads/` | 用户上传的临时文件 |
| `embedding_cache/` | 向量嵌入缓存（可自动重建） |
| `file_store/` | 文件处理缓存（可自动重建） |
| `logs/` | 日志文件（迁移时非必需） |
| `*.db` | SQLite 数据库文件（会话/聊天数据库，体积大且临时） |
| `*.zip` | 已有的备份归档 |
| `venv/`, `bin/` | 安装器创建的 Python 虚拟环境 |

注意：`~/.lightclaw/` 根目录下的配置文件（`lightclaw.json`、`providers.json`、
`jobs.json`、`chats.json` 等）**不在备份范围内**。这些文件由 LightClaw 应用自身管理。

## 工作流程

### 1. 创建备份

运行备份脚本，会在 `~/.lightclaw/backups/` 下生成带时间戳的 `.tar.gz` 归档。

```bash
python <skill-scripts-dir>/backup.py create
```

可选：附加人类可读的标签：

```bash
python <skill-scripts-dir>/backup.py create --label "迁移前"
```

创建完成后，**务必汇报**：
- 备份文件路径和大小
- 包含的内容（文件/目录数量）
- 当前总备份数

### 2. 查看备份列表

```bash
python <skill-scripts-dir>/backup.py list
```

将结果以格式化表格呈现，显示：ID、日期、标签、大小和文件数。

### 3. 从备份恢复

```bash
# 恢复最近的备份
python <skill-scripts-dir>/backup.py restore

# 通过 ID 或文件名恢复指定备份
python <skill-scripts-dir>/backup.py restore --id <backup_id>
```

**关键：恢复前务必：**
1. 警告用户恢复操作将覆盖当前工作区文件。
2. 先创建当前状态的安全备份（脚本会自动创建 `_pre_restore_safety.tar.gz`）。
3. 获得用户的明确确认后再执行。

恢复后，提醒用户**重启 LightClaw** 以使更改生效：
```bash
lightclaw restart
```

### 4. 查看变更（差异对比）

将备份与当前工作区状态进行对比：

```bash
python <skill-scripts-dir>/backup.py diff --id <backup_id>
```

报告自备份以来哪些文件被新增、删除或修改。

### 5. 清理旧备份

删除旧备份，仅保留最近 N 个：

```bash
python <skill-scripts-dir>/backup.py clean --keep 7
```

默认保留数量：7 个。安全备份（`_pre_restore_safety.tar.gz`）永远不会被自动删除。

### 6. 设置自动备份

如果用户想要定期备份，帮助他们通过 LightClaw 的定时任务功能设置。示例：

```
每天凌晨 3 点创建备份：
python <skill-scripts-dir>/backup.py create --label "每日自动"
```

## 注意事项

1. **绝不在输出中显示 API Key 或密钥** — 只需确认相关文件已包含在备份中。
2. 备份默认存储在 `~/.lightclaw/backups/`；用户可通过 `--backup-dir` 覆盖。
3. 每个备份都是独立的 `.tar.gz` 归档 — 无增量/差异机制。
4. 脚本成功时返回退出码 0，失败时返回非零值。务必检查退出码并清晰报告错误。
5. 对于大型工作区（>100 MB），提醒用户注意磁盘空间占用。
6. 归档内路径以 workspace 为根（如 `SOUL.md`、`skills/xxx/`），恢复时直接解压到 workspace 目录。

## 恢复指南

详细的分步恢复说明（包括手动恢复和回滚流程），请参阅
[references/restore.md](references/restore.md)。
