0d0e1d4473
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
178 lines
12 KiB
Markdown
178 lines
12 KiB
Markdown
# 架构-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`
|