oh-my-muse/design-docs/架构-02-核心数据结构与双轨模型.md

架构-02：核心数据结构与双轨模型

• 版本：v5
• 更新日期：2026-05-10
• 目标读者：架构/后端/前端/产品
• 阅读时间：30-45 分钟
• 边界说明：这里只定义模型层概念、不变式和归属边界；本文件描述目标模型，不代表当前代码都已实现。精确表结构以 后端-04-统一数据库Schema-v1.md 为准，精确接口(API)以 后端-05-统一API契约-v1.md 为准，精确状态机以 架构-04-状态机与约束清单.md 为准。

1. 双轨模型：规范数据(Canonical) / 待审层(Shadow) / 归档层(Archive)

1.1 定义

• 规范数据(Canonical)：用户认可的真实数据。正文、已确认作品知识、已确认规划项和叙事状态都必须能追溯来源。
• 待审层(Shadow)：系统或人工智能(AI)产出的候选、知识草稿、解析结果和风险标记。它是临时层，默认不可信。
• 归档层(Archive)：已接受、已拒绝、已过期、被替代或失败的历史对象。它用于审计和回看，不再作为当前待审对象。

一句话：AI 只能写待审层(Shadow)；只有用户确认、用户保存正文或章节级确认，才能让内容进入规范数据(Canonical)。

1.2 必须保留的硬边界

• 所有 AI 生成、提取、规划、检查结果都先进待审层(Shadow)。
• 待审对象不能进入正式检索、正式图查询或下一次生成事实。
• 修改后合并必须让旧知识草稿失效，并基于最终正文重新提取。
• 全书解析(Full Parse)的批量确认边界固定为 parse_job_id + chapter_id，同章节内 all-or-nothing，不做跨章节一次性写入。
• 待审层(Shadow)活跃区只保存待审对象；终态对象进入归档层(Archive)或审计记录。

2. 模型层分区

产品入口增加后，模型层不能按 UI 面板膨胀。Muse 的核心模型分为五类：

模型分区	归属	负责什么	不负责什么
系统级模板与配置	管理员(Admin) / Admin BC	元结构定义(MetaSchema)、字段定义、Prompt 版本、Agent 配置、上下文策略、全局知识库访问策略、评测集和 New-API 同步配置	不保存某个普通用户作品的正文或创作取舍
用户级作品数据	普通用户(User) / Content BC	作品(Work)、章节(Chapter)、文本块(Block)、导入状态、正文版本、作品级绑定	不保存系统级 Prompt、Agent 和全局授权规则
作品级知识数据	单个作品 / Knowledge BC	世界状态(World State)、叙事状态(Narrative State)、实体、关系、事件、属性变化、来源追溯	不跨作品共享正式事实，不直接替代全局知识库
全局知识库与访问策略	管理员(Admin) / Admin BC + Knowledge BC	全局知识库(Global Knowledge Base)、资料集版本、启停、用户或用户组授权、可见/可检索/可生成策略	不自动写入任何作品的局域知识库
局域知识库与用户可见投影	单个作品 / Knowledge BC	局域知识库(Local Knowledge Base)的内部完整知识、用户可见投影(User-visible Projection)、投影水位和来源解释	不把系统内部全部事实默认展示给普通用户

2.1 用户级作品数据

作品(Work)、章节(Chapter)、文本块(Block)是普通用户创作的内容骨架：

• 作品(Work)：单个作品的根对象，绑定作品级模板、导入状态、解析状态和授权上下文边界。
• 章节(Chapter)：作品内的顺序结构，承载章节摘要、章节目标和文本块集合。
• 文本块(Block)：正文的最小编辑、保存、候选合并和冲突处理单元。

不变式：

• 文本块(Block)级修订号(revision)是强制并发保护。
• 用户保存正文后，正文就是规范数据(Canonical)，后续提取失败不得回滚正文。
• 导入正文可以初始化 Canonical 正文；导入后的解析结果仍必须进入 Shadow 等待章节级确认。

2.2 作品级知识数据

作品级知识数据不是一个泛泛的“知识库表单”，而是当前作品的正式事实和叙事运行态：

• 世界状态(World State)：人物、地点、物品、组织、规则、事件、时间线、因果链和实体关系。
• 叙事状态(Narrative State)：作品、章节或实体维度上的弧线进度、章节意图、角色目标、悬念、张力、节奏和叙事策略。
• 来源追溯：正式知识必须能追溯到文本块(Block)、章节确认、规划项或用户手动操作。

世界状态(World State)和叙事状态(Narrative State)可以被用户通过作品规划台和知识与一致性工作区理解和修正，但底层状态载体仍以 后端-04 和 架构-04 为准。

2.3 全局知识库与局域知识库

全局知识库(Global Knowledge Base)和局域知识库(Local Knowledge Base)的边界如下：

类型	写入归属	进入生成上下文的条件	普通用户看到什么
全局知识库(Global Knowledge Base)	管理员维护和授权	管理员授权为可用于生成，且当前用户/用户组/作品满足访问策略	被授权全局资料的摘要、来源和可用范围
局域知识库(Local Knowledge Base)	当前作品自动维护，来自正文、导入解析、规划和用户确认	内容已经进入规范数据(Canonical)，且元数据允许进入 AI 上下文	作品知识、角色设定、世界设定、来源追溯和允许展示的摘要
用户可见投影(User-visible Projection)	Knowledge BC 从局域知识生成	仅作为读模型，不反向成为事实源	元数据允许展示、编辑、检索、导出的实体、关系、字段和摘要

全局知识库不会因为参与生成就成为作品事实。局域知识库也不会因为用户能看见某些字段，就把系统内部完整知识全部暴露出来。

3. 元结构定义(MetaSchema)边界

3.1 MetaSchema 的角色

元结构定义(MetaSchema)是模板、字段、校验规则、表单渲染和上下文注入的模型边界。普通用户界面里的“创作规则 / 作品模板 / 字段模板”，在底层都映射到 MetaSchema 或其字段定义。

MetaSchema 负责：

• 定义字段类型、必填、枚举、引用和校验规则。
• 定义字段所属领域、作用范围和目标类型。
• 决定哪些字段能进入 UI、AI 上下文、检索、导出或用户编辑。
• 给作品规划、提取、校验和投影提供结构约束。

MetaSchema 不负责：

• 保存 Narrative State 的运行态值。
• 替代作品正文、实体关系、事件时间线或用户确认记录。
• 直接表达每个 UI 面板。

3.2 领域、范围和目标类型

模型层继续使用三维分类：

• 领域(domain)：内容(content)、世界(world)、叙事(narrative)。
• 范围(scope)：作品(work)、章节(chapter)、实体(entity)、关系(relation)、事件(event)。
• 目标类型(targetType)：具体实体、事件、章节或模板类型。

叙事领域(narrative)的字段可以定义“角色弧光、章节意图、悬念、张力、节奏、叙事视角”等结构，但运行态值必须落到叙事状态(Narrative State)等真实载体中，不能只靠 MetaSchema 自身承载。

3.3 元数据可见性字段边界

元数据对象需要表达普通用户可见性和系统使用边界。模型层至少保留这些语义：

控制项	含义
uiVisible	是否在普通用户界面展示
aiContext	是否允许进入 AI 上下文
userEditable	普通用户是否可以编辑
userSearchable	普通用户是否可以检索
exportable	是否允许随作品导出

这些控制项的精确字段名、表结构和接口参数不在本文件定义。这里的模型约束是：

• uiVisible=false 不等于不能参与 AI 生成；是否进入上下文由 aiContext 决定。
• aiContext=true 不等于普通用户可见；是否展示由 uiVisible 决定。
• userEditable=true 不等于越过待审层(Shadow)；用户编辑正式知识仍需记录来源和变更。
• exportable=true 只能在用户拥有导出权限且对象属于可导出范围时生效。

4. 作品规划台到模型边界的映射

作品规划台(Planning Desk)是产品入口，不是新的一级模型集合。规划项需要映射到已有的世界状态(World State)、叙事状态(Narrative State)、元结构定义(MetaSchema)、作品(Work)、章节(Chapter)或文本块(Block)边界。

规划维度	用户语言	模型落点	说明
作品方向	题材、类型、主题、读者承诺、基调、禁区、结局方向	Work + MetaSchema + Narrative State(work)	作为作品级方向和后续生成约束
作品结构	章节顺序、章节摘要、当前字数、完成状态、近期目标	Work + Chapter + Narrative State(work/chapter)	章节骨架归 Content，推进状态归 Narrative State
世界实体	角色、地点、物品、组织、规则、关系	World State + MetaSchema(world/entity/relation)	正式事实进入局域知识库
事件时间线	重大事件、发生章节、参与角色、因果效果、长期影响	World State(event/relation) + Narrative State(chapter/entity)	连接世界事实和剧情推进
角色弧光	目标、动机、弱点、秘密、变化阶段、关系变化	Narrative State(entity) + World State(entity/relation)	角色档案事实和弧线进度分层保存
剧情结构	卷、幕、章节、主线、支线、伏笔与回收	Narrative State(work/chapter) + MetaSchema(narrative)	约束长期推进，不单独建剧情表单模型
章节叙事规划	章节目标、情节节拍、冲突、结果、下一步钩子	Chapter + Narrative State(chapter) + Block 上下文	近程控制面，承接产品语言里的“情节节拍 / 场景推进”
张力节奏	利害关系、阻力、反转、悬念问题、信息释放、高潮密度	Narrative State(work/chapter) + 风险标记	作为检查和生成约束，不做重表单
叙事策略	叙事视角、时态、叙事距离、多视角切换、信息遮蔽	MetaSchema(narrative) + Narrative State(chapter/work)	约束章节生成和风格一致性
文风与质量检查	作者声音、句式、节奏、描写密度、风格漂移、一致性风险	MetaSchema(content/narrative) + 风险标记 + Usage/Audit 评估结果	检查结果提示和定位，不自动写正式事实

4.1 小说场景(Scene)边界

当前阶段不把小说场景(Scene)升成独立一级模型，也不采用 Outline / Scene 作为两个并列一级模型。产品可以使用“情节节拍 / 场景推进”这类作者语言，但模型归入章节叙事规划，并通过 Chapter、Block 上下文和 Narrative State(chapter)承载。

如果未来需要让 Scene 成为独立模型，必须先补 架构决策记录(ADR)，并同步检查表结构、接口、前端状态和章节级确认边界；不能在产品或前端文档里先行假定已经存在。

5. 数据流转规则（模型视角）

5.1 Shadow -> Canonical

待审层(Shadow)进入规范数据(Canonical)的最小条件：

• 待审对象存在、未过期、未被替代。
• 正文合并必须通过文本块(Block)修订号保护。
• 知识草稿必须通过来源快照(Source Snapshot)校验。
• 需要用户确认的对象必须有明确用户决策。
• 成功后待审对象必须迁出活跃区，进入归档层(Archive)或审计历史。

5.2 外部内容 -> Canonical 与 Shadow

• 导入正文是用户动作，可以初始化 Canonical 正文。
• 导入后的全书解析结果仍是待确认知识草稿，必须先进 Shadow。
• 章节确认成功后，该章节范围内可确认对象一次性进入 Canonical；失败时不得部分写入。

5.3 冲突与一致性

• 内容冲突：文本块(Block)修订号不匹配，交给前端冲突处理和重试。
• 知识冲突：新提取事实和已确认事实不一致，只能生成待确认知识或风险标记，由用户取舍。
• 投影不一致：外部检索或图查询投影未追平时，不得把投影结果当事实源；需要通过 PostgreSQL 事实源和覆盖层补齐。

6. 关联阅读

• 系统边界与 BC：架构-01-系统全貌与边界上下文.md
• ADR：架构-03-关键决策与原则(ADR).md
• 生命周期与状态机：架构-04-状态机与约束清单.md
• 系统处理流程：流程-02-系统处理流程(系统视角).md
• 统一数据库表结构：后端-04-统一数据库Schema-v1.md
• 统一 API 契约：后端-05-统一API契约-v1.md