# 从备份恢复 LightClaw 工作区

## 自动恢复（推荐）

使用备份脚本进行安全恢复，会自动创建安全备份：

```bash
# 恢复最近的备份
python backup.py restore

# 恢复指定备份（通过 'list' 获取的 ID 或文件名片段）
python backup.py restore --id "20260315_030000"
```

脚本会依次执行：
1. 创建当前工作区的安全备份（`_pre_restore_safety.tar.gz`）
2. 解压选定的备份
3. 将恢复的文件合并到 `~/.lightclaw/workspace/`（覆盖匹配路径）

**恢复后请重启 LightClaw：**

```bash
lightclaw restart
```

## 手动恢复

如果备份脚本不可用，可手动恢复：

```bash
# 1. 停止 LightClaw
lightclaw stop

# 2. 安全复制当前工作区
cp -r ~/.lightclaw/workspace ~/.lightclaw/workspace-old

# 3. 解压备份到工作区目录（归档内路径以 workspace 为根）
cd ~/.lightclaw/workspace
tar -xzf ~/.lightclaw/backups/lightclaw-backup-YYYYMMDD_HHMMSS.tar.gz

# 4. 启动 LightClaw
lightclaw start

# 5. 验证一切正常
lightclaw status
```

## 恢复失败时的回滚

如果恢复后出现问题：

### 从安全备份回滚（脚本自动创建的）

```bash
lightclaw stop
cd ~/.lightclaw/workspace
tar -xzf ~/.lightclaw/backups/_pre_restore_safety.tar.gz
lightclaw start
```

### 从手动备份回滚

```bash
lightclaw stop
rm -rf ~/.lightclaw/workspace
mv ~/.lightclaw/workspace-old ~/.lightclaw/workspace
lightclaw start
```

## 备份归档结构

归档内所有路径以 workspace 为根，恢复时直接解压到 `~/.lightclaw/workspace/`：

```
（归档根目录 → 对应 ~/.lightclaw/workspace/）
├── SOUL.md                  # Agent 灵魂设定
├── HEARTBEAT.md             # Heartbeat 提示词
├── IDENTITY.md              # Agent 身份
├── USER.md                  # 用户信息
├── MEMORY.md                # 长期记忆
├── AGENTS.md                # Agent 配置文档
├── BOOTSTRAP.md             # 启动引导
├── skills/                  # 已安装的和自定义的 Skill
│   ├── health-check/
│   ├── lightclaw-backup/
│   └── ...
├── memory/                  # Agent 记忆文件
│   ├── 2026-03-14_*.md
│   └── ...
├── custom_channels/         # 用户安装的自定义 Channel 模块
└── _backup_manifest.json    # 备份元数据（文件列表、校验和）
```

## 不备份的内容

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

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

## 部分恢复

如果只需要恢复备份中的特定文件：

```bash
# 查看备份内容
tar -tzf ~/.lightclaw/backups/lightclaw-backup-YYYYMMDD_HHMMSS.tar.gz

# 只恢复 SOUL.md（注意：解压目标是 workspace 目录）
tar -xzf ~/.lightclaw/backups/lightclaw-backup-YYYYMMDD_HHMMSS.tar.gz \
    -C ~/.lightclaw/workspace SOUL.md

# 只恢复所有 Markdown 文件
tar -xzf ~/.lightclaw/backups/lightclaw-backup-YYYYMMDD_HHMMSS.tar.gz \
    -C ~/.lightclaw/workspace --include='*.md'

# 只恢复 Skill
tar -xzf ~/.lightclaw/backups/lightclaw-backup-YYYYMMDD_HHMMSS.tar.gz \
    -C ~/.lightclaw/workspace --include='skills/*'
```

部分恢复后，请重启 LightClaw：

```bash
lightclaw restart
```
