Author（创作与后台）

Author 承载创作与后台能力。当前只实现 editor:doc 草稿模型；完整编辑器界面、运营后台与埋点尚未实现。本插件只进入 editor 构建目标的根插件名单，游戏运行时产物不含它。

顶部信息表

项	内容
契约版本	author@1
当前状态	实现中
源码目录	src/core/author
页面定位	说明草稿模型的编辑语义、显式校验边界与后续编辑器接口的登记状态

职责

负责：

• 以内部剧本 IR 为文档的草稿模型；
• 节点、边与入口的编辑操作；
• 由调用方显式发起的 IR v1 校验；
• 草稿保存与正式输出的区分；
• 声明编辑器视图与埋点实现位。

不负责：

• 游戏运行时的播放、存档与演出；
• 完整编辑器界面、编辑预览与「尝试完整播放」；这些随后续阶段实现；
• 资源管理与本地化工作台；
• 运营后台与在线服务，见 规划中的大插件 中的 Online。

对外接口

名称与 policy 以 src/core/author/contract.ts 为准。

名称	类别	policy	说明
editor:doc	服务	trusted	草稿模型与编辑操作
ops:console	服务	trusted	只声明，当前不提供
telemetry:sink	服务	trusted	只声明，当前不提供
editor:resolve-node	机制插槽	trusted	只声明，当前不提供
editor:on-doc-change	通知	—	载入或修改成功后发出 { graphId }
editor:view@1	实现位（single）	public	当前空缺
telemetry:sink-impl@1	实现位（single）	public	当前空缺

editor:doc 方法

• load(草稿)：接受任意 JSON 对象，不校验。
• snapshot()：返回草稿的结构化克隆副本；尚未载入时返回 undefined。
• setEntry(nodeId)：设置入口节点，节点 ID 须为非空字符串。
• putNode(id, node)：写入或替换节点。
• removeNode(id)：删除节点，返回是否实际删除。
• addEdge(edge)：追加一条边。
• removeEdge(index)：按序号删除边。
• validate()：按 IR v1 校验，返回 { ok: true } 或 { ok: false, code, detail }。
• saveDraft()：原样输出草稿文本。
• exportFormal()：先校验，通过后输出规范化文本。

关键语义

草稿优先，校验显式

• 编辑操作本身不触发校验，草稿可以暂时不完整。
• 删除仍被引用的节点是允许的；引用完整性只在 validate() 或 exportFormal() 时暴露。
• 只拒绝非 JSON 数据等形状错误，例如不可结构化克隆的值、非对象草稿、非对象节点或边。
• validate() 由调用方显式发起；编辑预览不会自动触发。
• 校验失败时返回错误码与详情；正式输出失败时抛出带错误码的异常。

草稿保存与正式输出

方法	是否校验	输出	用途
saveDraft()	否	当前草稿的 JSON 文本	编辑中的临时保存
exportFormal()	是	通过 IR v1 校验后的规范化 JSON	交给运行时的正式产物

两者是不同行为，不能互相替代。exportFormal() 不通过校验就不输出任何正式文本。

边序号

removeEdge(index) 按当前数组序号删除。删除后其后的序号前移，调用方应重新取 snapshot() 再决定下一次删除，不能沿用旧序号。

变更通知

editor:on-doc-change 在草稿载入与每次修改成功后发出，载荷为 { graphId }。草稿没有字符串 id 时，graphId 为 undefined。

构建目标

• 本插件只进入 editor 构建目标的根插件名单：npm run build:editor 输出 dist-editor/。
• 游戏运行时产物 dist/ 不含 Author。
• 开发时 npm run dev:editor 启动编辑器目标。
• 编辑器直接复用运行时的 IR 与 VM，不另建文档模型；完整编辑器界面随后续阶段实现。

当前实现范围

• 已完成：editor:doc 的载入、快照、编辑操作、显式校验、草稿保存与正式输出；契约用例在 Node 与系统 Edge 中通过，editor 目标可经开发服务器启动到就绪。
• 未实现：完整编辑器界面、编辑预览、资源管理、本地化工作台、运营后台、埋点与分析。
• 未实现：editor:view@1 与 telemetry:sink-impl@1 实现位空缺；ops:console、telemetry:sink 与 editor:resolve-node 仅在契约中声明，当前不提供。
• 注意：编辑操作不校验是设计行为，不是遗漏；需要完整性时由调用方显式调用 validate()。

相关链接

• 插槽与实现位：editor:view@1 等 single 实现位的空缺语义。
• policy 与写边：trusted 服务与 public 实现位的差别。
• 装载管线与 guard：editor 构建目标如何只装载 Author 而不影响运行时。
• 剧本 IR：editor:doc 直接使用的文档格式。
• 剧本 IR v1 Schema：validate() 与 exportFormal() 的校验依据。