# 小说引擎现状与设计 V1

> 文档状态：当前有效  
> 基线日期：2026-07-15  
> 适用范围：小说导入、阅读、原创生成、质量循环、版本与派生任务。

## 1. 当前定位

小说引擎不是单一“生成一章”接口，而是平台的长文本内容底座。它负责把来源、创作约束、世界观、角色、剧情记忆和质量标准组织成可追踪的章节生产流程，并为短剧、听书等下游提供稳定文本资产。

## 2. 能力边界

### 已实现

- 粘贴、TXT、DOCX、PDF 等来源导入和章节切割。
- 小说目录、分页阅读、阅读进度、书签和批注。
- 原创小说创作向导与生成计划。
- StoryBible、WorldBible、角色和项目规则接入。
- Agent Prompt、AgentRun 与章节生成编排。
- 上下文记忆、章节版本、质量报告、自动修复和重写。
- 小说版本快照和听书/短剧派生任务数据结构。

### 尚未达到稳定基线

- 无人值守长批次生产。
- 全链路自动测试和正式 E2E。
- Agent 策略、质量阈值和人工确认的统一运营界面。
- 派生任务的完整异步执行覆盖。

## 3. 核心对象

| 对象 | 作用 |
| --- | --- |
| `NovelSource` | 导入或原创小说的主记录 |
| `NovelChapter` | 当前可读章节 |
| `NovelGenerationPlan` | 原创目标、结构、节奏和批次计划 |
| `NovelChapterVersion` | 草稿、修复、重写和确认版本 |
| `NovelContextMemory` | 供后续章节消费的压缩上下文 |
| `NovelQualityReport` | 章节质量维度、问题与修改建议 |
| `NovelVersionSnapshot` | 可追踪的整书状态快照 |
| `NovelDerivativeJob` | 听书、短剧等下游派生请求 |
| `AgentPrompt` | 可版本化 Agent 指令 |
| `AgentRun` | Agent 实际执行与输入输出记录 |
| `StoryBible` / `WorldBible` | 故事、世界规则和不可违反约束 |
| `CharacterMemory` / `PlotMemory` | 人物和剧情连续性信息 |

## 4. 生产流程

```mermaid
flowchart LR
  Brief[创作 Brief / 导入文本] --> Plan[生成计划]
  Plan --> Bible[故事与世界观规则]
  Bible --> Context[上下文构建]
  Context --> Prompt[Agent Prompt]
  Prompt --> Draft[章节草稿]
  Draft --> Quality[质量报告]
  Quality --> Pass{达到阈值?}
  Pass -- 否 --> Repair[定向修复或重写]
  Repair --> Quality
  Pass -- 是 --> Confirm[确认章节版本]
  Confirm --> Memory[更新上下文与伏笔]
  Memory --> Snapshot[版本快照 / 下游派生]
```

## 5. 上下文构建

每章生成不应把整本小说无差别塞入模型。上下文按优先级组成：

1. 当前项目和生成计划的硬约束。
2. StoryBible、WorldBible 中与本章相关的规则。
3. 当前角色状态、关系、服装/身份等连续性信息。
4. 上一章结尾和当前章目标。
5. 尚未回收的伏笔与必须推进的剧情线程。
6. 长篇压缩记忆和必要的原文片段。
7. 文风、篇幅、视角和禁用项。

所有自动压缩都必须保留来源章节和版本，以便发现错漏后回溯。

## 6. 质量循环

质量检查至少覆盖：

- 章节目标是否完成。
- 因果、时间线、人物动机是否成立。
- 角色口吻、能力、关系和状态是否连续。
- 伏笔是否误删、提前泄露或遗忘。
- 节奏、冲突、信息增量和章节钩子。
- 文风、重复、空泛解释和模板化表达。
- 与版权、合规和项目制作规则的冲突。

修复策略应优先定向改写问题段落；只有结构性失败时才整章重写。每次修复生成新版本，不覆盖原始版本。

## 7. 人工确认点

建议保留以下人工闸门：

- 生成计划确认。
- StoryBible/WorldBible 锁定。
- 核心角色和长期伏笔确认。
- 首章与关键转折章确认。
- 质量循环多次失败后的人工处置。
- 下游改编前的版本冻结。

## 8. Provider 策略

- NovelProvider 与 TextProvider 均可参与，但必须记录实际模型。
- 章节生成、质量审查和定向修复可使用不同模型配置。
- 用户偏好、项目偏好、显式 `provider_code` 与系统默认的优先级必须可解释。
- 真实调用失败后可回退，但不可静默切换后仍展示原模型名称。
- 成本记录需区分估算值和 Provider 返回的实际值。

## 9. 与短剧引擎的契约

下游短剧不直接读取“任意最新草稿”，应消费明确的小说快照或已确认章节版本。派生输入至少包含：

- 来源小说、章节和版本 ID。
- 已确认的人物、世界观和不可更改事实。
- 可压缩、可改编和禁止删减的内容范围。
- 目标时长、集数、媒介风格和受众。

改编产生的新事实不得反向污染小说正史，除非人工确认并写入新的 StoryBible/版本。

## 10. 当前风险

1. 新增 Prisma 依赖后部分单元测试 mock 未同步。
2. Agent、上下文和质量逻辑分布在多个服务，缺少稳定 E2E。
3. 长篇记忆任务声明存在，但 Worker 执行映射不完整。
4. 状态字符串缺少统一字典，历史数据可能出现兼容问题。
5. 批量生产的暂停、恢复、幂等和成本上限需要更强验证。

## 11. 不可破坏的规则

1. 所有章节修改必须形成版本，不直接覆盖已确认稿。
2. 生成请求必须能追溯到 Prompt、上下文和 Provider。
3. 故事圣经的硬约束优先于模型自由发挥。
4. 长篇记忆是辅助索引，不是原文唯一副本。
5. 下游派生必须绑定明确快照。
6. 质量评分不能替代人工对关键章节的确认。

## 12. 下一阶段

- 修复小说相关测试桩和状态期望。
- 增加“计划 -> 3 章批次 -> 质量修复 -> 快照”的 E2E。
- 明确章节状态机和迁移规则。
- 补齐长篇记忆与派生任务的 Worker 执行器。
- 为 AgentRun 增加成本、实际模型和输入摘要展示。