OpenWrite 场景结构管理:长篇章节组织、稳定场景ID与跨章迁移完整教程

原创2026-10-25 19:57:081,602 阅读
文章标签:AI 应用AI 写作AI 技能AI 插件dsh-plugin

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 的场景结构管理可以浓缩成三句话:

  1. 稳定场景 ID 让重排、拆分、跨章移动不再牵一发动全身;
  2. 阅读顺序 / 故事时间双序让倒叙多线长篇的组织问题可视化;
  3. revision 保护 + 只读预览 + 可回滚迁移确保每一步结构操作都可核对、可撤销。

配合「资料 → 大纲」面板和 7 个 novel_scene_* 工具,你可以在写作中途随时重构长篇结构,而不必担心正文和既有评审被破坏。更多工作台细节见 packages/studio-panel/README.md,完整创作流程见 docs/WORKFLOWS.md。

登录后查看全文
Openwrite