OpenWrite 场景结构管理:长篇章节组织、稳定场景ID与跨章迁移完整教程
OpenWrite 场景结构管理:长篇章节组织、稳定场景ID与跨章迁移完整教程
OpenWrite 是运行在 DeepSeek Harness(dsh)中的小说创作插件,内置原生场景结构管理能力:它用稳定场景 ID 把长篇正文拆成可引用的场景实体,支持阅读顺序与故事时间双序查看,并在跨章迁移时以三重 revision 保护数据安全。本教程面向新手,带你完成从旧稿分场预览、元数据维护到跨章移动场景的完整流程。
💡 如果你还没安装 OpenWrite,执行
dsh plugin --profile web add -w dsh-openwrite@latest,再运行dsh web进入工作台即可,无需克隆仓库。
1️⃣ 为什么长篇写作需要「场景」这一层
很多写作工具里,章(chapter)是最小组织节点,章内的 beat 只是一段段文本列表——无法被持久引用。当你需要重排、拆分或跨章移动一段情节时,只能整章操作,风险很高。
OpenWrite 在审计文档中明确了这一缺口(P2 级问题),并给出了解法:让场景成为一等公民,每个场景拥有:
- 稳定 ID(不随章节变化而漂移)
- 所属章与章内阅读序号
- 故事时间排序键与标签
- 在场人物、地点、事件引用
- 正定位锚与新鲜度状态
📖 设计依据见 docs/OPEN_SOURCE_NOVEL_AUDIT.md,其中还定义了验收标准:重排、跨章移动后正文与引用完整,导出遵循阅读顺序,时间线遵循故事时间。
2️⃣ 找到入口:资料 → 大纲 → 原生场景结构
在 dsh 工作台点击侧栏 OpenWrite,打开创作会话后进入「资料」页签,导航到「大纲 → 原生场景结构」。工作台面板由 SceneWorkbench.tsx 实现,副标题写得很直白:
按稳定场景 ID 管理元数据与章内、跨章顺序。
面板顶部是状态行,共有 4 种状态(定义见 SceneWorkbench.tsx):
| 状态 | 含义 | 你能做什么 |
|---|---|---|
absent 尚未迁移 |
项目还没有原生场景结构 | 审阅下方只读迁移预览 |
current 当前 |
结构与当前章节一致 | ✅ 可编辑元数据和顺序、移动场景 |
stale 已过期 |
章节已变化 | 元数据与移动停用,需重新预览迁移 |
ambiguous 有歧义 |
存在无法自动判定的场景 | 逐项解决结构问题 |
只有 current 状态下编辑按钮才可用——这是防止误改的核心设计。
3️⃣ 读懂场景卡片:一个场景、两套顺序
迁移完成后,每个场景显示为一张卡片,包含:场景 ID、所属章、标题、故事时间(标签 + 排序键)、人物、地点、事件。数据模型见 SceneWorkbench.tsx。
阅读顺序 vs 故事时间
面板工具栏提供两种显示顺序切换:
- 阅读顺序:读者实际读到的先后(正文物理顺序)
- 故事时间:按
story_time_sort_key排序(适合回忆杀、倒叙、多线叙事)
📌 实践建议:给每个场景填写故事时间标签(如「第 3 天·夜」)和可比较的排序键(如 D3-night),之后切到故事时间视图,倒叙结构是否自洽一眼可见。排序逻辑实现在 SceneWorkbench.tsx。
编辑场景元数据
点击场景卡片的「编辑」按钮,可修改标题、故事时间排序键/标签、人物、地点、事件(逗号分隔多个)。保存走 CAS 乐观锁:请求必须携带当前场景结构的 expected_revision,若期间结构已被他人/后台任务修改,工作台会提示「修订冲突」并自动刷新到最新版本让你重试(冲突处理见 SceneWorkbench.tsx)。
✅ 关键保障:元数据编辑绝不改动正文一个字——它只写场景侧车数据(sidecar),正文 SHA 保持不变,既有评审不会因此失效。
4️⃣ 跨章迁移场景:预览 → 应用 → 回滚三步走
第 1 步:只读预览,逐项核对
旧正文首次接入,或结构过期(stale)时,面板底部会出现「迁移预览(只读)」区块。预览本身不写入项目,只列出将要发生的分场/迁移项。你核对无误后,勾选「我已核对只读预览,确认应用迁移」,「应用迁移」按钮才会解锁(UI 逻辑见 SceneWorkbench.tsx)。
第 2 步:应用迁移需要精确 revision
应用迁移必须携带预览生成时的 expected_preview_revision 与显式确认标志——预览过期(期间章节变了)时服务端会拒绝,你必须重新生成预览。成功后会返回 migration_id,工作台记录本会话最近一次迁移。
第 3 步:一键回滚到迁移前
如果迁移结果不符合预期,点击「回滚最近迁移」,OpenWrite 会恢复迁移前字节级一致的场景侧车(rollback 由当前结构 revision 做 CAS 保护)。对应工具说明见 tools.ts。
移动场景到另一章
编辑面板里还有「移动场景」区域:选择目标章 + 目标位置(从 0 开始),点击移动。跨章移动需要三重 revision 同时匹配:场景自身 revision、源章 revision、目标章 revision,缺一不可(请求体构造见 SceneWorkbench.tsx)。
⚠️ 跨章移动正文时,OpenWrite 会触发既有的正文接纳流程(manuscript acceptance flow):移动后正文变化会使旧评审立即 stale,按写作→评审→修订的闭环重新交付,而不是静默改写。
5️⃣ stale/ambiguous 如何保护你的稿件
场景结构的生命周期规则定义在 docs/WORKFLOWS.md:
- 章节正文变化后,旧结构进入
stale,元数据编辑与移动自动停用; - 你重新预览并确认迁移后,结构重新锚定为
current; - 交付(导出成稿)会阻断 stale/ambiguous 状态,避免把过期结构写进成品;
- 完整备份导出始终回退到完整正文,场景结构只是增强层,删掉它稿件也完好。
这套「宁可停下、不可错改」的语义,是长篇项目中避免连锁损坏的关键。
6️⃣ 进阶:Agent 可用的 7 个场景工具
除了面板操作,你还可以直接在 OpenWrite 创作会话里用自然语言指挥 Agent 操作场景。桥接层提供了 7 个 novel_scene_* 工具(清单见 DESIGN.md,实现见 tools.ts):
| 工具 | 作用 |
|---|---|
novel_scene_structure |
读取全量场景结构:稳定 ID、双序、章 revision、引用与问题 |
novel_chapter_scenes |
读取单章的场景切片 |
novel_scene_migration_preview |
生成只读、精确 revision 的分场预览 |
novel_scene_migration_apply |
应用一份新鲜预览(需精确 revision + 显式确认) |
novel_scene_migration_rollback |
字节级回滚到迁移前 |
novel_scene_update |
CAS 更新场景标题/故事时间/人物地点事件引用 |
novel_scene_move |
章内/跨章移动场景(三重 revision 保护) |
📝 示例对话:「用 novel_scene_structure 检查当前结构状态,如果有 stale 就先重新生成迁移预览给我核对,再应用。」Agent 会按预览→确认→应用的安全顺序执行,而不是直接写盘。
7️⃣ 常见问题 FAQ
Q1:大纲里规划了但还没写的章节会出现在场景列表吗?
不会。planned_missing 章节保留在项目计划中,不会作为可编辑场景显示,面板只会提示「N 个规划章节尚无稿件」(逻辑见 SceneWorkbench.tsx)。
Q2:修改场景元数据会影响正文字数或导出吗? 不会。元数据存于场景侧车,有效标记不计入可读字数,也不进入默认导出。
Q3:导出和续写分别遵循哪个顺序? 导出遵循阅读顺序;连续性时间线遵循故事时间。这正是双序设计的价值。
Q4:迁移后想彻底放弃场景结构怎么办? 结构数据是独立 sidecar,备份导出永远包含完整正文;按 docs/WORKFLOWS.md 的规则,正文不会因结构过期而损坏。
8️⃣ 小结:稳定 ID + 双序 + 三重保护
OpenWrite 的场景结构管理可以浓缩成三句话:
- 稳定场景 ID 让重排、拆分、跨章移动不再牵一发动全身;
- 阅读顺序 / 故事时间双序让倒叙多线长篇的组织问题可视化;
- revision 保护 + 只读预览 + 可回滚迁移确保每一步结构操作都可核对、可撤销。
配合「资料 → 大纲」面板和 7 个 novel_scene_* 工具,你可以在写作中途随时重构长篇结构,而不必担心正文和既有评审被破坏。更多工作台细节见 packages/studio-panel/README.md,完整创作流程见 docs/WORKFLOWS.md。