版本管理规范

自动备份触发条件

以下任一条件满足时，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。

版本号	含义	示例场景
v1.0	首次完整创建	survival.html 从零构建
vX.1	小幅修订（修正错误、增补1-2段）	修正译名、补充一个关系条目
vX.2	中等修订（新增1个完整小节）	角色卡新增三观板块
vX.5	中度重构（CSS 重构、样式系统升级）	style.css 统计卡片新增
v2.0	结构性改写（新增章节、逻辑重排）	AI规范从v3.0→v4.0（预检+成本表+自检）
v3.0	重大重构（合并/拆分文件、架构调整）	通讯规范+角色习惯合并为通讯规范说明v3.0

首页资料版本号

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

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

步	操作	验证
1	备份：执行 robocopy 全量备份	确认目标目录存在且文件数 >= 源目录
2	写入：workspace 临时文件 → del + copy 到 canvas	确认目标文件大小 > 0 字节
3	同步：canvas → bloodbound(CodeBuddy版本)\canvas	确认两份文件大小一致
4	预览：preview_url 打开验证渲染	页面正常显示，无404/乱码/白屏
5	清理：删除 workspace 临时文件	.html/.ps1 临时文件已清除
6	记录：更新首页版本记录表	文件、版本号、更新内容三列完整

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

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

命令	作用
python rollback.py	列出所有可用备份及时间戳
python rollback.py --latest	从最近一次备份恢复（自动创建安全备份）
python rollback.py --backup bak_20260707_1430	从指定备份恢复
python rollback.py --dry-run --latest	预览模式，列出将被恢复的文件但不执行

恢复前脚本会自动创建 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 log --oneline -20	查看最近 20 次提交，找到目标版本
git show 提交哈希:canvas/文件名 > 临时文件	提取特定提交中的单个文件
git checkout 提交哈希 -- canvas/	恢复整个 canvas 目录到指定提交

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

恢复优先级

优先级	来源	工具	说明
1	rollback.py 自动恢复	python rollback.py --latest	最安全，自动创建安全备份
2	bloodbound(CodeBuddy版本)	robocopy	同步副本，通常与主目录一致
3	bloodbound-backups	robocopy / rollback.py	最新时间戳目录
4	Git 仓库	git checkout	线上副本，按提交历史恢复
5	references/*.md	手动重建	可重新生成 HTML 的源文件

备份完整性验证

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

命令	作用
python backup.py --verify	验证最新备份的文件数是否与源目录一致
python backup.py --list	列出所有备份及其文件数

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

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

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

7.1 日志字段规范

字段	格式	说明	示例
date	MM-DD	会话日期，不写年份	"06-27"
time	HH:MM	会话开始时间（可选，同日多条必填）	"13:38"
source	英文全称	软件来源：CodeBuddy / DeepSeek Web / Claude / GPT / Cursor	"CodeBuddy"
model	具体版本号	模型版本，不可省略	"DeepSeek-V4" / "Claude-4"
work	≤25字	一句话概括工作内容，精炼不罗列	"主角图谱重写+星座生肖+性格优缺点"
tokens	数字，单位万	本次消耗的 token 估算值	3.2

7.2 记录规则

#	规则
1	新条目插在数组最前面 — 首页按编写顺序渲染，无需再次排序
2	同日多条合并 — 同一日内的多次对话合并为一条，work 字段用分号分隔
3	每次写入后检查 JSON 合法性 — 逗号、引号、数组括号不可缺失
4	备份前追加 — 执行备份命令前，确保本次会话内容已写入日志

7.3 示例条目

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

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

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

8.1 它是什么

状态	首页显示	含义
已备份	✦ 保留版本	当前所有文件已通过 robocopy 完整复制到 bloodbound-backups\bak_时间戳\。如果后续修改出错，可以从这个备份恢复
未备份	标签不出现	当前修改尚未备份，一旦文件被覆盖或丢失，无法恢复

8.2 什么时候出现

#	触发条件
1	执行了 robocopy 全量备份 → 标签写入首页 HTML
2	备份目标路径确认文件数 ≥ 源目录文件数 → 标签保留
3	本次会话结束前执行最终备份 → 标签伴随最新备份时间戳

8.3 它不是什么

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

8.4 与版本号的关系

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

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

9.1 按钮状态流转

阶段	按钮显示	说明
待命	↑ Git	空闲，可点击
上传中	⏳ 上传中	服务器正在执行 git 操作，按钮锁定、禁止再次点击
成功	✓ 已推送	绿色背景，3 秒后自动恢复为 ↑ Git
失败	✗ 错误信息	红色背景，弹窗提示具体失败原因

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

步	操作	作用
1	获取锁	防止并发上传。若已被占用则返回 HTTP 423，前端显示"上传进行中"
2	写入 VERSION 戳	在 canvas 根目录生成/更新 VERSION 文件，含版本号+推送时间+文件数+仓库地址
3	git pull	先拉取远程最新，避免冲突
4	git add -A	暂存所有变更
5	git commit	提交信息格式：Canvas Update | MM-DD HH:MM
6	git push origin master	推送到 https://gitee.com/beijing-zangdai_0/the-book-of-blood-covenant
7	释放锁	无论成功或失败，锁都会在 finally 中释放

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 与本地备份的关系

维度	本地备份（robocopy）	Git上传（↑ Git）
位置	bloodbound-backups\bak_时间戳\	gitee.com/beijing-zangdai_0/...
触发方式	AI 检测到备份条件时自动执行	人工点击 ↑ Git 按钮
恢复方式	robocopy 从备份目录回拷	git clone / git pull
首页指示器	✦ 保留版本	VERSION 文件时间戳
目的	防止本地误改无法恢复	线上副本 + 外链展示

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

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