版本管理规范

自动备份触发条件

以下任一条件满足时，AI 必须在操作前执行备份：

1. 本次指令涉及写入/修改 ≥5 个文件
2. 修改 核心文件（index.html / protagonists.html / characters.html / 规范类页面 / style.css / toolbar 结构）
3. 会话结束前 做最终备份

备份命令（CMD，可靠执行）

cmd /c "robocopy d:\u7f51\u6587\u5267\u672c\bloodbound d:\u7f51\u6587\u5267\u672c\bloodbound-backups\bak_%date:~0,4%%date:~5,2%%date:~8,2%_%time:~0,2%%time:~3,2% /E /XD .git node_modules .codebuddy bloodbound-backups"

备份仓库结构

d:\网文剧本\bloodbound-backups\
├── bak_20260627_0928\    ← 时间戳命名
├── bak_20260627_1500\    ← 每次备份独立目录
└── ...                   ← 建议保留最近 20 个版本

备份使用 robocopy 镜像模式，每次全量复制，确保完整性。单次备份约 1.6 MB，20 个版本约 32 MB。

首页资料版本号

首页 Hero 区域的「资料版本」标签跟随 设定与规范体系 的整体版本。当 ≥3 个规范文件发生 vX.2 以上变更时，整体版本号递增。

当前: 资料版本 v4.2（对应 CodeBuddy 深度定制版本）

路径一：自动脚本恢复（推荐）

项目已配备 rollback.py 自动恢复脚本，位于 canvas/ 目录。

恢复前脚本会自动创建 bak_safety_时间戳 安全备份，确保恢复操作本身不会导致数据丢失。

路径二：手动 robocopy 恢复

1. 检查 d:\网文剧本\bloodbound(CodeBuddy版本)\canvas\ — 同步副本是否完好
2. 检查 d:\网文剧本\bloodbound-backups\ — 最新备份目录
3. 如有 references/*.md 源文件 → 可重新生成 HTML
4. 从备份恢复：cmd /c robocopy 备份目录 canvas /E

路径三：Git 版本回退

当本地备份不可用时，可从 Git 仓库恢复到指定提交状态。

Git 回退前务必先备份当前文件。使用 python backup.py 创建安全快照后再操作。

恢复优先级

备份完整性验证

恢复前建议先验证备份完整性：

首页「版本记录」表需在每次重大变更后更新。更新规则：

• 文件列：以 code 格式标注文件名
• 版本列：当前版本号（如 v4.2）
• 更新内容列：一句话概括变更，≤30 字
• 仅记录 vX.1 以上变更。纯修正（排版调整、标点修复）不单列
• 新文件首次写入 == v1.0

每一次会话结束前，AI 必须将本次工作内容记录到 session-log.json。是保存与审计的强制环节。

7.1 日志字段规范

7.2 记录规则

7.3 示例条目

{"date":"06-27","time":"13:38","source":"CodeBuddy","model":"DeepSeek-V4","work":"主角图谱重写+星座生肖+性格优缺点","tokens":3.2}

与首页「会话日志」表联动。日志 JSON 的新增顺序 = 首页表格的渲染顺序（最新在上）。

首页 Hero 区的「✦ 保留版本」标签是一个肉眼可见的备份状态指示器，告诉你当前版本是否已被备份保护。

8.1 它是什么

8.2 什么时候出现

8.3 它不是什么

是本地备份标签。Git 上传是另一条通道（见第九节）。两者的关系：本地备份 = 你的安全网；Git 上传 = 线上的副本。两个都做才算"完全保留"。

8.4 与版本号的关系

版本号（如 v5.0）是"内容到了什么阶段"。保留版本标签是"这个阶段有没有被存下来"。同一版本号可能在备份前和备份后都出现，区别在于有没有 ✦。

首页「↑ Git」按钮将当前所有文件推送到 Gitee 远程仓库。是备份之后必须走的一步，确保线上与本地一致。

9.1 按钮状态流转

9.2 服务端执行流程（serve.py）

9.3 VERSION 文件 — 上传验证戳

用途：每次上传时自动更新，包含推送时间和文件统计。打开 Gitee 仓库 → 查看根目录 VERSION 文件 → 对比推送时间与你的本地操作时间 → 若一致=上传成功，若不一致=上传未生效。

血契之书 · 版本戳
───────────────
版本号   : v5.1
推送时间 : 2026-06-27 14:50:30
HTML页   : 37+ 份
仓库地址 : https://gitee.com/beijing-zangdai_0/the-book-of-blood-covenant
───────────────
若线上此文件时间戳与你本机不同 → 上传未生效

9.4 与本地备份的关系

推荐顺序：修改 → 本地备份（✦ 保留版本出现）→ 点击 ↑ Git 上传 → 打开 Gitee 仓库验证 VERSION 时间戳。

• — §零 步骤6（调用前备份）、§九 第11条（退出前备份）
• — §一 文件体系总览
• canvas/backup.py — 自动备份脚本（见第四节·路径一）
• canvas/rollback.py — 自动恢复脚本（见第四节·路径一）
• canvas/update-version.js — 版本号自动更新工具
• serve.py — 本地开发服务器，含 Git Push 端点（见第九节）
• VERSION — 版本戳文件，每次上传时自动更新（见第九节）
• .git/hooks/pre-commit — 提交前自动检查（破折号/双井号/文件大小/版本戳）