writing-agent/docs/run-snapshot.md

Book 快照

用户手动保存、多档位；与自动续作 session.json 分离。

编辑 / 重 roll 的统一做法：恢复到之前的快照，再从该点继续。
创作（design）与运行（play）共用此语义。

存快照 → 继续生成 → 不满意 → 加载 earlier 快照 → 重跑后续 worker / 重出展示

三种 kind（更新语义）

kind	名称	何时存	存什么
instance	创作定稿截面	Worker 集 accept；可选含 锁定开局	设计.worker集、静态设定 tag、运行.初始变量、输出.开场白；不含后续轮次、事件流
opening	开局锁定（可选单独存）	创作末尾 swipe 选定开场后	与 instance 中开局部分相同；便于「同 Worker 集、换开局再开 play 线」
run	游玩存档	play 任意时刻	instance/opening 层 + 运行.*、轮次、变量当前值、对话

Worker 集 accept     → 可存 instance（规格截面）
可选开局赋初值       → 可存 instance / opening（非进 play 强制门槛）
play 任意时刻        → 可存 多条 run
改 Worker 集         → load 旧 instance 再改
改某轮输出           → load 该轮前的 run → 重 roll / 重跑

instance = Worker 集（+ 可选开局截面）。进 play 由用户手动决定。见 book-storage.md、design-orchestrator-guide.md。

同一开局 · 多条存档

opening-generator 锁定 checkpoint  =  共用起点
  ├─ run 存档 A（第 5 轮）
  ├─ run 存档 B（第 12 轮，另一分支）
  └─ 「从同一开局新开一条线」= 清空 run 层、保留 opening/instance 层（见 session-manager startNewPlayLine）

多条 run 快照共享同一 opening（或含 opening 的 instance），无需为每条 play 线复制 Worker 集。

Swipe 与快照

创作末尾 开局 产出时，可用 message branch / swipe 多版本对比（可选）。
play 对终稿可用 重 roll；用户新输入 = 认可上轮终稿。见 design-orchestrator-guide.md。

与三种存储需求

需求	用什么
创作过程	Book designTrace + messages
实例规格 + 锁定开局	instance / opening 快照
游玩过程	PlayBook playTrace + run 快照（同一开局可多条）
改设定 / 重 roll	加载对应 kind 的 earlier 快照

与自动续作

	session.json	run-snapshots/
触发	自动	用户手动（关键节点建议提示存档）
数量	每 Book 1 份	多档、可命名
打开作品	默认恢复	选档 加载
编辑	—	load = 恢复到该档状态

API

GET    /api/books/:bookId/saves
POST   /api/books/:bookId/saves     { label, kind: "instance"|"opening"|"run", note?, sessionId? }
POST   /api/books/:bookId/saves/:id/load
DELETE /api/books/:bookId/saves/:id

（opening kind 可在实现中与 instance 合并存储，文档层区分语义即可。）

实现

src/types/run-snapshot.ts
src/book/run-snapshot-store.ts
src/book/snapshot-filters.ts
src/server/session-manager.ts
src/server/message-branch.ts          swipe / branch checkpoint

存储：books/{bookId}/run-snapshots/{id}.json

相关

文档	关系
skill-design-guide.md §0.4	Worker 集与快照
creation-playbook.md	创作流中的开局与存档
context-assembly.md	恢复后 worker prompt 仍含 preset + static + dynamic