# Novel Backup

> 自动版本备份 — 每章定稿归档、设定文档快照、增量+全量双轨策略、智能版本号与清理规则

- Skill: `cwjdong-design/novel-backup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cwjdong-design/novel-backup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cwjdong-design/novel-backup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cwjdong-design (https://skillmd.com/u/cwjdong-design)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cwjdong-design/novel-backup

---


# 自动版本备份（v2.0）

## 触发条件

- 由 `novel-main` 步骤 7 触发（每章完成后自动备份）
- 由 `novel-cron` 每日触发（全量打包备份）
- 用户手动说「备份《XXX》」「备份所有小说」

## 输入参数

```json
{
  "final_draft": "<定稿内容>",
  "book_name": "<书名>",
  "chapter_num": <章节号>,
  "word_count": <字数>,
  "mode": "chapter"  // "chapter" | "daily" | "manual"
}
```

---

## 备份体系概览

```
~/novels/books/<书名>/03-版本备份/
├── 备份日志.md                    # 所有备份操作日志
├── 正文历史/                      # 正文增量备份
│   ├── 第X章_v1.md               #   初版
│   ├── 第X章_v2.md               #   修订版
│   └── ...
├── 设定快照_第X章/               # 设定文档快照（按章）
│   ├── 世界观.md
│   ├── 人物库/
│   ├── 伏笔追踪表.md
│   └── 故事线状态.md
├── 设定快照_第Y章/
│   └── ...
└── 归档/                          # 全量打包归档
    ├── <书名>_v1.0.tar.gz
    ├── <书名>_v1.1.tar.gz
    └── ...

~/novels/_shared/backups/          # 跨书全局备份（cron 触发）
├── daily_2026-07-24.tar.gz
└── ...
```

---

## 策略 1：每章增量备份（mode=chapter）

### 1.1 正文版本管理

每次保存正文时，遵循以下版本号规则：

**版本号格式**：`v{N}`，N 从 1 开始递增。

**版本号分配逻辑**：
```
如果 01-正文存稿/第X章.md 不存在
  → 直接保存为 01-正文存稿/第X章.md（即 v1）
  → 同时复制到 03-版本备份/正文历史/第X章_v1.md

如果 01-正文存稿/第X章.md 已存在（重新生成 / 修订）
  → 读取 03-版本备份/正文历史/ 下第X章的最大版本号 M
  → 旧版正文保持为 03-版本备份/正文历史/第X章_v{M}.md（如果尚未归档则先复制）
  → 新版正文归档为 03-版本备份/正文历史/第X章_v{M+1}.md
  → 新正文覆盖 01-正文存稿/第X章.md
```

**示例**：
```
首次生成第 3 章：
  01-正文存稿/第3章.md ← 新正文
  03-版本备份/正文历史/第3章_v1.md ← 副本

修订第 3 章：
  03-版本备份/正文历史/第3章_v1.md ← 旧版（如果不存在则复制）
  03-版本备份/正文历史/第3章_v2.md ← 新版
  01-正文存稿/第3章.md ← 覆盖为新版
```

### 1.2 设定文档快照

每章完成后，将以下文件的当前状态复制到快照目录：

```bash
mkdir -p "03-版本备份/设定快照_第${章节号}章/"
cp 02-设定文档/世界观.md              "03-版本备份/设定快照_第${章节号}章/"
cp -r 02-设定文档/人物库/              "03-版本备份/设定快照_第${章节号}章/"
cp 02-设定文档/伏笔追踪表.md           "03-版本备份/设定快照_第${章节号}章/"
cp 02-设定文档/故事线状态.md           "03-版本备份/设定快照_第${章节号}章/"
```

目的：可以回溯到任意章节完成时的完整设定状态，用于追踪设定演进轨迹。

### 1.3 备份日志记录

追加到 `03-版本备份/备份日志.md`：

```markdown
| <时间> | 第X章 | <字数> | 章备份 | 正文v<N>, 快照v<章节号> |
```

---

## 策略 2：每日全量备份（mode=daily）

由 `novel-cron` 每日触发，按以下逻辑执行：

### 2.1 单书全量打包

对每本书执行：

```bash
# 确保归档目录存在
mkdir -p "$HOME/novels/books/<书名>/03-版本备份/归档/"

# 生成版本号
VERSION=$(cat ~/novels/books/<书名>/03-版本备份/归档/VERSION 2>/dev/null || echo "1.0")

# 打包
tar -czf "$HOME/novels/books/<书名>/03-版本备份/归档/<书名>_v${VERSION}.tar.gz" \
  -C ~/novels/books/<书名>/ \
  01-正文存稿/ 02-设定文档/

# 递增主版本号
echo "$(echo $VERSION | awk -F. '{print $1+1}').0" > ~/novels/books/<书名>/03-版本备份/归档/VERSION
```

### 2.2 全局打包（可选，cron 专用）

```bash
mkdir -p ~/novels/_shared/backups/
tar -czf ~/novels/_shared/backups/daily_$(date +%Y-%m-%d).tar.gz \
  -C ~/novels/ books/
```

### 2.3 备份日志

```markdown
| <时间> | — | — | 日备份 | <书名>_vX.Y.tar.gz, daily_YYYY-MM-DD.tar.gz |
```

---

## 策略 3：手动全量备份（mode=manual）

用户主动触发时：

1. 确认备份范围：当前书 / 所有书
2. 执行全量打包（同策略 2.1）
3. 可选：同步到外部路径 / iCloud / 网盘

---

## 版本号规则

### 正文单章版本号

格式：`v{N}`，N 为整数（1, 2, 3, ...）

- 首次生成 → `v1`
- 每次重新生成 / 手动修订 → `v{N+1}`
- 版本号无上限，不自动覆盖

### 归档版本号（全量打包）

格式：`v{M}.{m}`

- **主版本号 M**：每次日备份自动递增（1.0 → 2.0 → 3.0）
- **次版本号 m**：同一天内多次全量备份时递增（2.0 → 2.1 → 2.2）

**递增规则**：
```
同一天内：M 不变，m 递增
新的一天：M 递增，m 归零 → M+1.0
```

### 设定快照版本号

格式：以章节号标识（`设定快照_第X章/`），不做额外版本号。
每章的设定快照是该章完成时的唯一状态快照。

---

## 清理策略

### 正文历史清理

| 规则 | 阈值 | 行为 |
|------|------|------|
| 每章保留最近版本 | 最近 5 个版本 | 超出部分删除 |
| 保留首版 | v1 永久保留 | 不删除 |
| 保留末版 | 最新版永久保留 | 不删除 |

**删例**：
```
第3章_v1  ← 永久保留
第3章_v2
第3章_v3
...      ← 中间版本过多时删除
第3章_v8  ← 最新版，保留
```

### 设定快照清理

| 规则 | 阈值 | 行为 |
|------|------|------|
| 保留最近快照 | 最近 20 个 | 超出部分删除 |
| 保留里程碑 | 每 10 章 | 第 10、20、30... 章快照永久保留 |
| 保留首章 | 第 1 章快照永久保留 | — |

**删例**：
```
设定快照_第1章/   ← 永久保留
设定快照_第2章/   ← 过旧，可删
...
设定快照_第9章/   ← 过旧，可删
设定快照_第10章/  ← 里程碑，保留
...
设定快照_第19章/  ← 可删
设定快照_第20章/  ← 里程碑，保留
...
设定快照_第27章/  ← 保留（最近 20 个）
...
设定快照_第47章/  ← 当前，保留
```

### 归档清理

| 规则 | 阈值 | 行为 |
|------|------|------|
| 保留最近日备份 | 最近 7 天 | 超出删除 |
| 保留周备份 | 每周日的那份 | 永久保留 |
| 保留里程碑 | 每 50 章的归档 | 永久保留 |

### 全局备份清理

`~/novels/_shared/backups/` 下保留最近 7 天的 `daily_*.tar.gz`，超出自动删除。

---

## 清理执行时机

- **每章备份后**：执行正文历史清理 + 设定快照清理
- **每日 cron 后**：执行归档清理 + 全局备份清理
- **不阻塞写作流程**：清理失败不影响正常备份

---

## 输出格式

### 每章备份后（mode=chapter）

```markdown
✅ 备份完成 — 第 X 章

📄 正文：
  → 01-正文存稿/第X章.md
  → 03-版本备份/正文历史/第X章_v{N}.md

📸 设定快照：
  → 03-版本备份/设定快照_第X章/

🧹 清理：删除了 M 个过期快照
```

### 每日备份后（mode=daily）

```markdown
✅ 每日备份完成 — YYYY-MM-DD

📦 归档：
  → <书名>_v{M}.{m}.tar.gz（N 本书，共 X MB）
  → daily_YYYY-MM-DD.tar.gz（全局，X MB）

🧹 清理：删除了 M 个过期归档
```

---

## 恢复操作

当用户需要恢复到某一章的状态时：

### 恢复正文
- 从 `03-版本备份/正文历史/第X章_v{N}.md` 复制到 `01-正文存稿/第X章.md`

### 恢复设定
- 从 `03-版本备份/设定快照_第X章/` 复制全部文件回 `02-设定文档/`

### 恢复全书
- 解压 `03-版本备份/归档/<书名>_v{M}.{m}.tar.gz` 到临时目录
- 询问用户确认后覆盖

---

## 注意事项

- **正文 v1 永不删除**：首版是宝贵的创作记录
- **快照不以时间命名**：以章节号命名，便于语义回溯
- **tar.gz 创建通过 terminal 工具执行**：确保权限和路径正确
- **备份操作幂等**：重复执行不会产生重复文件或数据不一致
- **跨书备份独立**：每本书的备份互不影响
- **清理策略保守**：宁愿多保留，避免误删