oh-my-muse/design-docs/前端-02-编辑器与影子层交互.md

前端-02：编辑器与影子层交互

• 版本：v4
• 更新日期：2026-05-10
• 目标读者：前端 / 后端 / 架构 / 产品
• 阅读时间：25-40 分钟
• 边界说明：这里只讲作品写作台的前端状态拥有、交互结构、候选反馈和恢复策略；本文件描述目标前端形态，不代表当前代码都已实现。精确接口看 后端-05，精确状态机看 架构-04。

1. 作品写作台概览

前端的任务不是只渲染正文编辑器和 Shadow Panel(待审面板)，而是把作品写作台(Writing Desk)做成普通用户进入单个作品后的默认创作空间。

建议的写作台结构：

区域	用户看到什么	前端职责
左侧	章节、章节摘要、情节节拍、作品设定锚点	帮用户理解当前章节位置，并提供到作品规划台(Planning Desk)的跳转
中间	当前章节正文编辑器	承载文本块(Block)级编辑、保存、修订号(revision)冲突处理和候选合并
右侧	AI 候选、待确认知识、生成历史、任务反馈、参考来源摘要	承载候选卡流、待确认知识提醒、历史抽屉和失败反馈
下方或抽屉	已确认设定、作品知识、上下文命中、风险说明	展示解释信息和可跳转定位，不替用户自动确认

普通用户默认看到的是“AI 候选 / 待确认知识 / 已确认设定 / 生成历史”，不直接看到待审层(Shadow)、提案(Proposal)、规范数据(Canonical)这些系统术语。系统术语可留在代码、调试视图或架构文档里。

2. 写作台与作品规划台互跳

写作台(Writing Desk)和作品规划台(Planning Desk)是同一作品工作台(Work Workspace)里的两个工作区，前端必须提供清楚的互相跳转。

• 从写作台到作品规划台：用户可以从章节、情节节拍、角色设定、世界设定、文风检查或一致性问题跳转到对应规划入口。
• 从作品规划台回写作台：用户保存或确认规划后，可以回到相关章节、文本块或候选上下文继续写作。
• 跳转必须携带用户能理解的定位信息，例如章节、角色、设定项、风险问题或待确认知识；不要把 schemaId、proposalId、pipeline 作为普通用户默认可见线索。
• 作品规划台产生的 AI 方案仍然先进入待确认内容；用户确认后才能成为后续生成上下文的一部分。

3. 文本块编辑与修订号保护

3.1 Block 级编辑

• 每个文本块(Block)都必须携带 id 与修订号(revision)，这是正文写入、候选合并和冲突恢复的锚点。
• 用户在写作台里编辑的是正式正文，不是待审草稿。
• 导入产生的文本块和手动创建的文本块在前端是一套规则，不允许出现“导入块走特殊编辑路径”。

3.2 标注与提示

• 命名实体识别(NER)预览、待确认知识、风险标记(Risk Markers)和参考来源摘要都属于解释能力。
• 这些提示不能伪装成正式事实；视觉上必须区分“待确认”和“已确认”。
• 已确认设定来自规范数据(Canonical)或用户可见投影；待确认知识来自待审层(Shadow)。

4. 状态拥有

4.1 Query Cache 与本地状态分工

• Query Cache 持有服务器事实与服务器列表：正文文本块、章节、已确认设定、用户可见投影、待确认内容列表、生成历史和用量记录。
• Zustand(状态库)或等价本地状态持有当前 UI 状态：当前候选卡、右侧面板、历史抽屉、冲突解决弹窗、乐观更新快照和跳转定位。
• 历史记录不属于当前待确认区；已接受、已丢弃、已过期或失败对象必须走独立查询和独立视图。

4.2 待确认对象的前端分组

前端至少要区分四类用户可见对象：

用户语言	底层来源	前端提交语义
AI 候选	Suggestion / Shadow	原样接受、修改后合并、丢弃当前建议
待确认知识	Knowledge Draft / Proposal / Shadow	确认、忽略、来源失效时重新提取
解析章节待确认结果	Full Parse 章节聚合草稿 / Shadow	整章确认、整章驳回、批量选择、一键确认全部可确认章节
生成历史	Archive / Job History / Usage	只读回看、定位来源、解释失败，不参与当前待确认提交

它们可以共用卡片视觉风格，但不能共用错误的提交语义。

5. 右侧候选卡流

右侧候选卡流是写作台的关键交互面，不是后台审核列表。

候选卡应至少表达：

• 候选文本或候选方案。
• 关联待确认知识。
• 风险标记(Risk Markers)。
• 来源快照(Source Snapshot)状态。
• 本次参考了哪些作品知识、规划项或授权全局资料的摘要。
• 可执行动作：原样接受、修改后合并、丢弃当前建议。

交互约束：

• 未接受的 AI 候选不能进入正文、已确认设定、正式检索或下一次生成事实。
• 原样接受时，前端可以展示“已合并，关联知识草稿已确认”，前提是后端返回的结果确实表示关联草稿已确认。
• 修改后合并时，前端必须清掉旧待确认知识并提示“已合并，旧知识草稿已失效，正在重新提取”。
• 丢弃当前建议只结束当前建议和关联草稿的待审生命周期，不改正文、不改已确认设定。

6. 同步与恢复策略

6.1 乐观更新

• 对正文接受可以做乐观更新，但必须以修订号(revision)为锚点。
• 失败后要么回滚到上一个稳定状态，要么进入显式冲突态；不能静默吞错。
• 如果用户在乐观更新后继续编辑了当前文本块，失败恢复时禁止直接覆盖新输入。

6.2 冲突处理

前端需要明确区分两类冲突：

• 内容冲突：修订号(revision)不匹配，用户要看见“我的版本”和“服务器版本”的差异，并选择保留、合并或重试。
• 知识冲突：风险标记、来源失效或属性冲突，用户在待确认知识层处理，而不是当成正文冲突。

6.3 来源快照拦截

• 待确认知识必须带来源快照(Source Snapshot)或等价来源校验结果。
• 来源已失效时，前端必须拦截确认动作，并用用户语言说明“这条待确认内容已经和当前来源不匹配，需要重新提取”。
• 拦截后不能让用户绕过校验强行写入已确认设定。

6.4 修改后合并

修改后合并的前端语义是：

1. 用户先编辑最终要进入正文的内容。
2. 正文按修订号(revision)合并。
3. 旧待确认知识立即失效并从当前待确认区移除。
4. 系统重新提取新的待确认知识。
5. 用户稍后再确认或忽略新的待确认知识。

这条链路不能被简化成“接受后继续沿用旧知识草稿”。

7. 导入与全书解析 UI

• “开始解析”入口由导入状态和解析状态驱动，但前端不在本文件定义状态机细节。
• 解析进行中，前端要展示章节级进度与失败反馈，而不是只有一个全局加载态。
• 章节汇总页是主工作台；详情页是解释面板。
• 详情页不提供逐条接受；全书解析场景的提交动作只能在章节边界完成。
• 批量选择和“一键确认全部可确认章节”只是操作效率优化；前端文案必须避免暗示系统会做跨章节不可解释写入。

8. 用户可见反馈规范

• 待确认对象必须显式标识“待确认”。
• 已确认设定必须和待确认知识分区展示。
• 历史记录必须在独立区域展示，不和当前待确认内容混放。
• 成功提示要说真话：
  • 原样接受：已合并，关联知识草稿已确认
  • 修改后合并：已合并，旧知识草稿已失效，正在重新提取
• 不要伪造“已发现 N 条提案待审核”这类没有一致性保证的即时数字。

9. 关联阅读

• 产品边界：产品-02-核心功能与交互边界.md
• 用户流程：流程-01-产品操作流程(用户视角).md
• 系统流程：流程-02-系统处理流程(系统视角).md
• 状态机与约束：架构-04-状态机与约束清单.md
• Accept 收束专题：专题-01-正文建议接受(Accept Suggestion)实现规范.md