# 大纲生成策略
**本文引用的文件**
- [one-step-outline.strategy.ts](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts)
- [per-chapter.strategy.ts](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts)
- [base.ts](file://server/src/modules/book-generator/strategies/base.ts)
- [types.ts](file://server/src/modules/book-generator/strategies/types.ts)
- [selector.ts](file://server/src/modules/book-generator/strategies/selector.ts)
- [plan.node.ts](file://server/src/modules/book-generator/nodes/plan.node.ts)
- [full-outline.node.ts](file://server/src/modules/book-generator/nodes/full-outline.node.ts)
- [outline.node.ts](file://server/src/modules/book-generator/nodes/outline.node.ts)
- [per-chapter.node.ts](file://server/src/modules/book-generator/nodes/per-chapter.node.ts)
- [content.node.ts](file://server/src/modules/book-generator/nodes/content.node.ts)
- [graph.ts](file://server/src/modules/book-generator/graph.ts)
- [book-type-config.ts](file://server/src/modules/book-generator/book-type-config.ts)
- [utils.ts](file://server/src/modules/book-generator/utils.ts)
- [fault-tolerance.ts](file://server/src/modules/book-generator/fault-tolerance.ts)
- [README.md](file://server/src/modules/book-generator/README.md)
- [FAULT_TOLERANCE.md](file://server/src/modules/book-generator/FAULT_TOLERANCE.md)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向“大纲生成策略”的技术文档，聚焦两类策略：
- OneStepOutlineStrategy 单步大纲生成策略：一次 AI 生成完整树形大纲（章→节→小节），随后对所有叶节点并行生成内容。
- PerChapterStrategy 逐章生成策略：先生成章大纲，再对每章独立生成内部结构与内容，章节间可并行。
文档将从输入参数处理、输出格式规范、质量控制机制入手，深入解析两者的实现原理、数据流、并行与进度控制，并给出参数调优、错误恢复与质量评估建议及使用案例与最佳实践。
## 项目结构
围绕“大纲生成策略”，相关代码主要位于 server/src/modules/book-generator/strategies 与 nodes 目录，配合 LangGraph 状态机与容错层，形成可扩展、可观测、可恢复的生成流水线。
```mermaid
graph TB
subgraph "策略层"
S1["one-step-outline.strategy.ts"]
S2["per-chapter.strategy.ts"]
ST["types.ts"]
SEL["selector.ts"]
SB["base.ts"]
end
subgraph "节点层"
N1["plan.node.ts"]
N2["full-outline.node.ts"]
N3["outline.node.ts"]
N4["per-chapter.node.ts"]
N5["content.node.ts"]
end
subgraph "基础设施"
G["graph.ts"]
FT["fault-tolerance.ts"]
CFG["book-type-config.ts"]
U["utils.ts"]
end
S1 --> N1
S1 --> N2
S1 --> N5
S2 --> N1
S2 --> N3
S2 --> N4
S1 --> SB
S2 --> SB
SB --> G
SB --> FT
N1 --> CFG
N2 --> CFG
N3 --> CFG
N4 --> CFG
N5 --> CFG
N5 --> U
```
图示来源
- [one-step-outline.strategy.ts:1-56](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L1-L56)
- [per-chapter.strategy.ts:1-56](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L1-L56)
- [base.ts:1-73](file://server/src/modules/book-generator/strategies/base.ts#L1-L73)
- [types.ts:1-29](file://server/src/modules/book-generator/strategies/types.ts#L1-L29)
- [selector.ts:1-81](file://server/src/modules/book-generator/strategies/selector.ts#L1-L81)
- [plan.node.ts:1-201](file://server/src/modules/book-generator/nodes/plan.node.ts#L1-L201)
- [full-outline.node.ts:1-243](file://server/src/modules/book-generator/nodes/full-outline.node.ts#L1-L243)
- [outline.node.ts:1-129](file://server/src/modules/book-generator/nodes/outline.node.ts#L1-L129)
- [per-chapter.node.ts:1-324](file://server/src/modules/book-generator/nodes/per-chapter.node.ts#L1-L324)
- [content.node.ts:1-546](file://server/src/modules/book-generator/nodes/content.node.ts#L1-L546)
- [graph.ts:1-83](file://server/src/modules/book-generator/graph.ts#L1-L83)
- [fault-tolerance.ts:1-387](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L387)
- [book-type-config.ts:1-133](file://server/src/modules/book-generator/book-type-config.ts#L1-L133)
- [utils.ts:1-24](file://server/src/modules/book-generator/utils.ts#L1-L24)
章节来源
- [README.md:1-215](file://server/src/modules/book-generator/README.md#L1-L215)
## 核心组件
- 策略接口与类型
- 策略名称与接口定义见 [types.ts:1-29](file://server/src/modules/book-generator/strategies/types.ts#L1-L29)，统一约束 generate(bookId, topic, bookScale, genLevel)。
- 策略选择器
- 通过 [selector.ts:1-81](file://server/src/modules/book-generator/strategies/selector.ts#L1-L81) 注册并切换策略，默认当前推荐策略为 DeepPlanParallel（策略选择器亦支持运行时切换）。
- 基础执行器
- [base.ts:1-73](file://server/src/modules/book-generator/strategies/base.ts#L1-L73) 提供统一的 LangGraph 编译、流式执行、进度监控与错误处理模板。
- LangGraph 状态机
- [graph.ts:1-83](file://server/src/modules/book-generator/graph.ts#L1-L83) 定义状态字段（bookId、topic、bookScale、genLevel、progress、currentChapter、completedChapters、finished、error 等）与 reducer 策略。
- 容错层
- [fault-tolerance.ts:1-387](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L387) 提供 AI 调用重试、节点超时、进度监控、自动恢复与用户通知。
章节来源
- [types.ts:1-29](file://server/src/modules/book-generator/strategies/types.ts#L1-L29)
- [selector.ts:1-81](file://server/src/modules/book-generator/strategies/selector.ts#L1-L81)
- [base.ts:1-73](file://server/src/modules/book-generator/strategies/base.ts#L1-L73)
- [graph.ts:1-83](file://server/src/modules/book-generator/graph.ts#L1-L83)
- [fault-tolerance.ts:1-387](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L387)
## 架构总览
两策略共享同一执行框架：先规划（planBookNode），再生成大纲，最后生成内容；差异在于大纲生成与内容生成阶段的并行化程度与并发控制。
```mermaid
sequenceDiagram
participant C as "控制器/调用方"
participant STR as "OneStepOutlineStrategy/PerChapterStrategy"
participant BASE as "runGraphWorkflow"
participant G as "LangGraph"
participant N1 as "planBookNode"
participant N2 as "大纲/内容节点"
participant DB as "bookStore/数据库"
C->>STR : 调用 generate(bookId, topic, bookScale, genLevel)
STR->>BASE : 初始化状态并编译工作流
BASE->>G : graph.stream(initialState)
G->>N1 : 执行规划
N1-->>G : 返回规划结果/进度
G->>N2 : 执行大纲/内容生成
N2->>DB : 写入大纲/内容
DB-->>N2 : 确认写入
N2-->>G : 返回阶段性进度/状态
G-->>BASE : 流式步骤输出
BASE-->>C : 完成/失败，更新进度与阶段
```
图示来源
- [one-step-outline.strategy.ts:21-56](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L21-L56)
- [per-chapter.strategy.ts:21-56](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L21-L56)
- [base.ts:26-72](file://server/src/modules/book-generator/strategies/base.ts#L26-L72)
- [graph.ts:23-82](file://server/src/modules/book-generator/graph.ts#L23-L82)
## 详细组件分析
### OneStepOutlineStrategy 单步大纲生成策略
- 工作流
- plan_book → generate_full_outline → write_chapters
- 一次性生成完整树形大纲（章→节→小节），随后对所有叶节点并行生成内容。
- 输入参数处理
- generate(bookId, topic, bookScale, genLevel)：其中 genLevel 由规划节点决定或用户覆盖。
- 规划节点 [plan.node.ts:145-200](file://server/src/modules/book-generator/nodes/plan.node.ts#L145-L200) 会根据 bookScale 与用户输入决定最终 genLevel。
- 输出格式规范
- 一步大纲节点 [full-outline.node.ts:135-218](file://server/src/modules/book-generator/nodes/full-outline.node.ts#L135-L218) 输出 JSON，包含 mainTheme、structureLogic、chapters（含 sections/subsections）。
- 内容生成节点 [content.node.ts:102-332](file://server/src/modules/book-generator/nodes/content.node.ts#L102-L332) 为叶节点生成正文，按 genLevel 决定消息构造与内容清理。
- 质量控制机制
- 容错层：AI 调用重试、节点超时、进度监控、自动恢复。
- 字数预算与上限：章节预算偏差检测、全书累计字数上限、全局绝对上限。
- 额度与配额：订阅配额检查与音频分钟消耗。
- 并行与进度
- 内容生成采用并行池（默认并发数见 [content.node.ts:444-545](file://server/src/modules/book-generator/nodes/content.node.ts#L444-L545)），按叶节点并行推进。
- 进度常量 [utils.ts:15-23](file://server/src/modules/book-generator/utils.ts#L15-L23) 控制 outline/content 阶段的进度区间。
```mermaid
flowchart TD
Start(["开始：OneStepOutlineStrategy.generate"]) --> Plan["planBookNode
生成规划(genLevel)"]
Plan --> FullOutline["generateFullOutlineNode
一次性生成完整大纲(JSON)"]
FullOutline --> FindLeaves["定位所有叶节点(level=3)"]
FindLeaves --> ParallelWrite["并行写入叶节点内容
writeChaptersParallelNode"]
ParallelWrite --> AudioTrigger["完成后触发音频生成"]
AudioTrigger --> End(["结束"])
```
图示来源
- [one-step-outline.strategy.ts:25-54](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L25-L54)
- [plan.node.ts:145-200](file://server/src/modules/book-generator/nodes/plan.node.ts#L145-L200)
- [full-outline.node.ts:135-218](file://server/src/modules/book-generator/nodes/full-outline.node.ts#L135-L218)
- [content.node.ts:444-545](file://server/src/modules/book-generator/nodes/content.node.ts#L444-L545)
- [utils.ts:15-23](file://server/src/modules/book-generator/utils.ts#L15-L23)
章节来源
- [one-step-outline.strategy.ts:1-56](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L1-L56)
- [full-outline.node.ts:1-243](file://server/src/modules/book-generator/nodes/full-outline.node.ts#L1-L243)
- [content.node.ts:1-546](file://server/src/modules/book-generator/nodes/content.node.ts#L1-L546)
- [utils.ts:1-24](file://server/src/modules/book-generator/utils.ts#L1-L24)
### PerChapterStrategy 逐章生成策略
- 工作流
- plan_book → generate_outline → per_chapter（每章独立生成内部结构+内容）
- 章节间可并行执行（受 MAX_CONCURRENCY 限制）。
- 输入参数处理
- 与 OneStepOutlineStrategy 相同，先规划 genLevel，再生成章大纲。
- 输出格式规范
- 章大纲节点 [outline.node.ts:14-128](file://server/src/modules/book-generator/nodes/outline.node.ts#L14-L128) 输出章节列表（含 number/title/summary/keyPoints/estimatedWords），并入库 level=1。
- 逐章节点 [per-chapter.node.ts:92-233](file://server/src/modules/book-generator/nodes/per-chapter.node.ts#L92-L233) 为每章生成完整内容（Markdown），并按 genLevel 创建节/小节索引。
- 质量控制机制
- 容错层：AI 调用重试、节点超时、进度监控、自动恢复。
- 章节数校验：允许 ±20% 浮动，超出范围进行截断或补充默认章节。
- 内容写入验证：写入后二次校验，失败则重试。
- 并行与进度
- 逐章处理采用串行推进（避免并发写入竞争），但可在外部调度层面对多本书或批次进行并行。
- 进度常量 [utils.ts:15-23](file://server/src/modules/book-generator/utils.ts#L15-L23) 控制 outline/content 阶段的进度区间。
```mermaid
flowchart TD
Start2(["开始：PerChapterStrategy.generate"]) --> Plan2["planBookNode
生成规划(genLevel)"]
Plan2 --> Outline2["generateOutlineNode
生成章大纲(JSON)"]
Outline2 --> LoopChapters["遍历每章(perChapterNode)"]
LoopChapters --> BuildMsg["构建单章提示(含规划/上下文)"]
BuildMsg --> CallLLM["调用LLM生成内容(JSON/纯文本)"]
CallLLM --> Parse["解析内容并写入数据库"]
Parse --> Verify["写入验证(失败重试)"]
Verify --> Next["下一章"]
Next --> |完成| End2(["结束"])
```
图示来源
- [per-chapter.strategy.ts:25-54](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L25-L54)
- [outline.node.ts:14-128](file://server/src/modules/book-generator/nodes/outline.node.ts#L14-L128)
- [per-chapter.node.ts:92-233](file://server/src/modules/book-generator/nodes/per-chapter.node.ts#L92-L233)
- [utils.ts:15-23](file://server/src/modules/book-generator/utils.ts#L15-L23)
章节来源
- [per-chapter.strategy.ts:1-56](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L1-L56)
- [outline.node.ts:1-129](file://server/src/modules/book-generator/nodes/outline.node.ts#L1-L129)
- [per-chapter.node.ts:1-324](file://server/src/modules/book-generator/nodes/per-chapter.node.ts#L1-L324)
- [utils.ts:1-24](file://server/src/modules/book-generator/utils.ts#L1-L24)
### 策略对比与适用场景
- 适用场景
- OneStepOutlineStrategy：适合追求“快出结果”的场景，一次性生成完整大纲，随后并行填充内容，整体吞吐更高。
- PerChapterStrategy：适合对“章节质量”要求更高的场景，每章独立生成，便于局部迭代与质量把关。
- 性能差异
- OneStepOutlineStrategy：总调用次数约为 1(规划)+1(大纲)+N(内容)；内容阶段并行度高，吞吐更快。
- PerChapterStrategy：总调用次数约为 1(规划)+1(大纲)+N(章)；每章独立生成，整体时延更稳定，但并行度受限于外部调度。
- 资源消耗
- OneStepOutlineStrategy：内存与并发压力集中在内容生成阶段，需关注数据库写入与音频生成并发。
- PerChapterStrategy：每章生成相对均衡，但总调用次数更多，需关注 LLM 调用与队列压力。
章节来源
- [one-step-outline.strategy.ts:7-11](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L7-L11)
- [per-chapter.strategy.ts:7-11](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L7-L11)
## 依赖分析
- 策略与节点耦合
- OneStepOutlineStrategy 依赖 planBookNode、generateFullOutlineNode、writeChaptersNode；PerChapterStrategy 依赖 planBookNode、generateOutlineNode、perChapterNode。
- 基础设施依赖
- 均依赖 base.ts 的 runGraphWorkflow，统一 LangGraph 编译、流式执行、进度监控与错误处理。
- 容错层 fault-tolerance.ts 提供统一的 AI 调用重试、节点超时、进度监控与自动恢复。
- 配置与工具
- book-type-config.ts 提供书籍规模、章节数与字数范围等配置；utils.ts 提供进度常量与字数统计。
```mermaid
graph LR
STR1["OneStepOutlineStrategy"] --> |调用| PLAN["planBookNode"]
STR1 --> |调用| FOUT["generateFullOutlineNode"]
STR1 --> |调用| WCON["writeChaptersNode"]
STR2["PerChapterStrategy"] --> |调用| PLAN
STR2 --> |调用| OUT["generateOutlineNode"]
STR2 --> |调用| PCH["perChapterNode"]
BASE["runGraphWorkflow"] --> STR1
BASE --> STR2
BASE --> FT["fault-tolerance.ts"]
PLAN --> CFG["book-type-config.ts"]
FOUT --> CFG
OUT --> CFG
PCH --> CFG
WCON --> CFG
WCON --> U["utils.ts"]
```
图示来源
- [one-step-outline.strategy.ts:13-19](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts#L13-L19)
- [per-chapter.strategy.ts:13-19](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts#L13-L19)
- [base.ts:26-72](file://server/src/modules/book-generator/strategies/base.ts#L26-L72)
- [fault-tolerance.ts:1-387](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L387)
- [book-type-config.ts:1-133](file://server/src/modules/book-generator/book-type-config.ts#L1-L133)
- [utils.ts:1-24](file://server/src/modules/book-generator/utils.ts#L1-L24)
章节来源
- [selector.ts:12-20](file://server/src/modules/book-generator/strategies/selector.ts#L12-L20)
- [base.ts:1-73](file://server/src/modules/book-generator/strategies/base.ts#L1-L73)
## 性能考量
- 并发与吞吐
- OneStepOutlineStrategy 的内容并行池（默认并发数见 [content.node.ts:444-545](file://server/src/modules/book-generator/nodes/content.node.ts#L444-L545)）可显著提升吞吐；需结合数据库写入能力与音频生成队列容量进行调优。
- PerChapterStrategy 的逐章处理在外部调度层面可并行多本书，但单书内部仍为串行推进。
- 字数与配额
- 章节预算偏差检测与全书累计字数上限（见 [content.node.ts:255-281](file://server/src/modules/book-generator/nodes/content.node.ts#L255-L281) 与 [book-type-config.ts:10-132](file://server/src/modules/book-generator/book-type-config.ts#L10-L132)）可避免超预算与资源浪费。
- 订阅配额检查与音频分钟消耗（见 [content.node.ts](file://server/src/modules/book-generator/nodes/content.node.ts#L181-L195, L283-L289)）确保成本可控。
- 超时与重试
- 节点超时配置（见 [fault-tolerance.ts:27-38](file://server/src/modules/book-generator/fault-tolerance.ts#L27-L38)）与 AI 调用重试（见 [fault-tolerance.ts:68-123](file://server/src/modules/book-generator/fault-tolerance.ts#L68-L123)）降低不稳定因素对整体性能的影响。
章节来源
- [content.node.ts:255-281](file://server/src/modules/book-generator/nodes/content.node.ts#L255-L281)
- [book-type-config.ts:10-132](file://server/src/modules/book-generator/book-type-config.ts#L10-L132)
- [fault-tolerance.ts:27-38](file://server/src/modules/book-generator/fault-tolerance.ts#L27-L38)
- [fault-tolerance.ts:68-123](file://server/src/modules/book-generator/fault-tolerance.ts#L68-L123)
## 故障排查指南
- 常见问题与定位
- AI 调用失败：检查重试日志与数据库 errorMsg 字段，确认是否触发自动恢复。
- 节点超时：核对节点超时配置与执行时间，必要时延长超时或优化提示词。
- 长时间无响应：进度监控器会在 10/20/30 分钟发出告警，随后尝试自动恢复。
- 内容写入失败：逐章节点对写入进行二次验证，失败会重试；若持续失败，检查数据库连接与并发写入。
- 容错机制
- AI 调用重试（指数退避）、节点超时、进度监控、自动恢复与用户通知详见 [fault-tolerance.ts:1-387](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L387) 与 [FAULT_TOLERANCE.md:1-334](file://server/src/modules/book-generator/FAULT_TOLERANCE.md#L1-L334)。
- 快速恢复
- 若达到最大恢复次数，系统会标记最终失败并提示手动操作；可重新发起生成任务。
章节来源
- [fault-tolerance.ts:188-261](file://server/src/modules/book-generator/fault-tolerance.ts#L188-L261)
- [FAULT_TOLERANCE.md:86-164](file://server/src/modules/book-generator/FAULT_TOLERANCE.md#L86-L164)
## 结论
- OneStepOutlineStrategy 更适合“快速产出、高吞吐”的场景，通过一次性生成完整大纲与并行内容生成实现高效交付。
- PerChapterStrategy 更适合“质量优先、可控迭代”的场景，通过逐章生成与写入验证确保每章内容质量。
- 两者共享统一的容错层与状态机，具备完善的错误恢复与进度监控能力，适合在生产环境长期运行。
## 附录
### 参数调优指南
- 策略选择
- 默认策略为 DeepPlanParallel（策略选择器），可通过运行时切换策略（见 [selector.ts:42-56](file://server/src/modules/book-generator/strategies/selector.ts#L42-L56)）。
- 并发与超时
- OneStepOutlineStrategy：调整内容并行池并发数（见 [content.node.ts:444-545](file://server/src/modules/book-generator/nodes/content.node.ts#L444-L545)）与节点超时（见 [fault-tolerance.ts:27-38](file://server/src/modules/book-generator/fault-tolerance.ts#L27-L38)）。
- PerChapterStrategy：外部调度可并行多本书，单书内部仍为串行推进。
- 字数与配额
- 章节预算偏差阈值与全书上限（见 [content.node.ts:255-281](file://server/src/modules/book-generator/nodes/content.node.ts#L255-L281) 与 [book-type-config.ts:10-132](file://server/src/modules/book-generator/book-type-config.ts#L10-L132)）可根据业务目标调整。
- 订阅配额检查与音频分钟消耗（见 [content.node.ts](file://server/src/modules/book-generator/nodes/content.node.ts#L181-L195, L283-L289)）需与产品定价策略匹配。
### 输出格式规范
- 一步大纲 JSON（见 [full-outline.node.ts:65-99](file://server/src/modules/book-generator/nodes/full-outline.node.ts#L65-L99)）：包含 mainTheme、structureLogic、chapters（含 sections/subsections）。
- 章大纲 JSON（见 [outline.node.ts:48-104](file://server/src/modules/book-generator/nodes/outline.node.ts#L48-L104)）：包含 chapters（number/title/summary/keyPoints/estimatedWords）。
- 单章内容 JSON（见 [per-chapter.node.ts:76-80](file://server/src/modules/book-generator/nodes/per-chapter.node.ts#L76-L80)）：包含 content、wordCount；若非 JSON 则直接按纯文本处理。
### 实际使用案例与最佳实践
- 快速试读/短文：选择 OneStepOutlineStrategy，利用并行内容生成快速产出。
- 教程/教材：选择 PerChapterStrategy，逐章生成确保结构与质量，便于后续修订。
- 大规模生成：结合外部调度对多本书并行，单书内部采用 PerChapterStrategy，提高稳定性与可控性。
- 质量评估：依据章节预算偏差检测与全书累计字数上限，结合用户反馈与音频生成完成度进行综合评估。
章节来源
- [selector.ts:23-33](file://server/src/modules/book-generator/strategies/selector.ts#L23-L33)
- [content.node.ts:255-281](file://server/src/modules/book-generator/nodes/content.node.ts#L255-L281)
- [book-type-config.ts:10-132](file://server/src/modules/book-generator/book-type-config.ts#L10-L132)
- [full-outline.node.ts:65-99](file://server/src/modules/book-generator/nodes/full-outline.node.ts#L65-L99)
- [outline.node.ts:48-104](file://server/src/modules/book-generator/nodes/outline.node.ts#L48-L104)
- [per-chapter.node.ts:76-80](file://server/src/modules/book-generator/nodes/per-chapter.node.ts#L76-L80)