novel-backup

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

自动版本备份（v2.0）

触发条件

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

输入参数

{
  "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 设定文档快照

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

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

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

1.3 备份日志记录

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

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

---

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

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

2.1 单书全量打包

对每本书执行：

# 确保归档目录存在
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 专用）

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

2.3 备份日志

| <时间> | — | — | 日备份 | <书名>_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）

✅ 备份完成 — 第 X 章

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

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

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

每日备份后（mode=daily）

✅ 每日备份完成 — 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 工具执行：确保权限和路径正确
• 备份操作幂等：重复执行不会产生重复文件或数据不一致
• 跨书备份独立：每本书的备份互不影响
• 清理策略保守：宁愿多保留，避免误删