# 架构-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`