audio_codebuddy/.qoder/repowiki/zh/content/核心模块/AI内容生成引擎/生成策略系统/大纲生成策略.md

大纲生成策略

本文引用的文件

• one-step-outline.strategy.ts
• per-chapter.strategy.ts
• base.ts
• types.ts
• selector.ts
• plan.node.ts
• full-outline.node.ts
• outline.node.ts
• per-chapter.node.ts
• content.node.ts
• graph.ts
• book-type-config.ts
• utils.ts
• fault-tolerance.ts
• README.md
• FAULT_TOLERANCE.md

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考量
8. 故障排查指南
9. 结论
10. 附录

简介

本文件面向“大纲生成策略”的技术文档，聚焦两类策略：

• OneStepOutlineStrategy 单步大纲生成策略：一次 AI 生成完整树形大纲（章→节→小节），随后对所有叶节点并行生成内容。
• PerChapterStrategy 逐章生成策略：先生成章大纲，再对每章独立生成内部结构与内容，章节间可并行。

文档将从输入参数处理、输出格式规范、质量控制机制入手，深入解析两者的实现原理、数据流、并行与进度控制，并给出参数调优、错误恢复与质量评估建议及使用案例与最佳实践。

项目结构

围绕“大纲生成策略”，相关代码主要位于 server/src/modules/book-generator/strategies 与 nodes 目录，配合 LangGraph 状态机与容错层，形成可扩展、可观测、可恢复的生成流水线。

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
• per-chapter.strategy.ts:1-56
• base.ts:1-73
• types.ts:1-29
• selector.ts:1-81
• plan.node.ts:1-201
• full-outline.node.ts:1-243
• outline.node.ts:1-129
• per-chapter.node.ts:1-324
• content.node.ts:1-546
• graph.ts:1-83
• fault-tolerance.ts:1-387
• book-type-config.ts:1-133
• utils.ts:1-24

章节来源

• README.md:1-215

核心组件

• 策略接口与类型
  • 策略名称与接口定义见 types.ts:1-29，统一约束 generate(bookId, topic, bookScale, genLevel)。
• 策略选择器
  • 通过 selector.ts:1-81 注册并切换策略，默认当前推荐策略为 DeepPlanParallel（策略选择器亦支持运行时切换）。
• 基础执行器
  • base.ts:1-73 提供统一的 LangGraph 编译、流式执行、进度监控与错误处理模板。
• LangGraph 状态机
  • graph.ts:1-83 定义状态字段（bookId、topic、bookScale、genLevel、progress、currentChapter、completedChapters、finished、error 等）与 reducer 策略。
• 容错层
  • fault-tolerance.ts:1-387 提供 AI 调用重试、节点超时、进度监控、自动恢复与用户通知。

章节来源

• types.ts:1-29
• selector.ts:1-81
• base.ts:1-73
• graph.ts:1-83
• fault-tolerance.ts:1-387

架构总览

两策略共享同一执行框架：先规划（planBookNode），再生成大纲，最后生成内容；差异在于大纲生成与内容生成阶段的并行化程度与并发控制。

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
• per-chapter.strategy.ts:21-56
• base.ts:26-72
• graph.ts:23-82

详细组件分析

OneStepOutlineStrategy 单步大纲生成策略

• 工作流
  • plan_book → generate_full_outline → write_chapters
  • 一次性生成完整树形大纲（章→节→小节），随后对所有叶节点并行生成内容。
• 输入参数处理
  • generate(bookId, topic, bookScale, genLevel)：其中 genLevel 由规划节点决定或用户覆盖。
  • 规划节点 plan.node.ts:145-200 会根据 bookScale 与用户输入决定最终 genLevel。
• 输出格式规范
  • 一步大纲节点 full-outline.node.ts:135-218 输出 JSON，包含 mainTheme、structureLogic、chapters（含 sections/subsections）。
  • 内容生成节点 content.node.ts:102-332 为叶节点生成正文，按 genLevel 决定消息构造与内容清理。
• 质量控制机制
  • 容错层：AI 调用重试、节点超时、进度监控、自动恢复。
  • 字数预算与上限：章节预算偏差检测、全书累计字数上限、全局绝对上限。
  • 额度与配额：订阅配额检查与音频分钟消耗。

• 并行与进度

  • 内容生成采用并行池（默认并发数见 content.node.ts:444-545），按叶节点并行推进。

  • 进度常量 utils.ts:15-23 控制 outline/content 阶段的进度区间。

    flowchart TD
    Start(["开始：OneStepOutlineStrategy.generate"]) --> Plan["planBookNode<br/>生成规划(genLevel)"]
    Plan --> FullOutline["generateFullOutlineNode<br/>一次性生成完整大纲(JSON)"]
    FullOutline --> FindLeaves["定位所有叶节点(level=3)"]
    FindLeaves --> ParallelWrite["并行写入叶节点内容<br/>writeChaptersParallelNode"]
    ParallelWrite --> AudioTrigger["完成后触发音频生成"]
    AudioTrigger --> End(["结束"])
    

图示来源

• one-step-outline.strategy.ts:25-54
• plan.node.ts:145-200
• full-outline.node.ts:135-218
• content.node.ts:444-545
• utils.ts:15-23

章节来源

• one-step-outline.strategy.ts:1-56
• full-outline.node.ts:1-243
• content.node.ts:1-546
• utils.ts:1-24

PerChapterStrategy 逐章生成策略

• 工作流
  • plan_book → generate_outline → per_chapter（每章独立生成内部结构+内容）
  • 章节间可并行执行（受 MAX_CONCURRENCY 限制）。
• 输入参数处理
  • 与 OneStepOutlineStrategy 相同，先规划 genLevel，再生成章大纲。
• 输出格式规范
  • 章大纲节点 outline.node.ts:14-128 输出章节列表（含 number/title/summary/keyPoints/estimatedWords），并入库 level=1。
  • 逐章节点 per-chapter.node.ts:92-233 为每章生成完整内容（Markdown），并按 genLevel 创建节/小节索引。
• 质量控制机制
  • 容错层：AI 调用重试、节点超时、进度监控、自动恢复。
  • 章节数校验：允许 ±20% 浮动，超出范围进行截断或补充默认章节。
  • 内容写入验证：写入后二次校验，失败则重试。

• 并行与进度

  • 逐章处理采用串行推进（避免并发写入竞争），但可在外部调度层面对多本书或批次进行并行。

  • 进度常量 utils.ts:15-23 控制 outline/content 阶段的进度区间。

    flowchart TD
    Start2(["开始：PerChapterStrategy.generate"]) --> Plan2["planBookNode<br/>生成规划(genLevel)"]
    Plan2 --> Outline2["generateOutlineNode<br/>生成章大纲(JSON)"]
    Outline2 --> LoopChapters["遍历每章(perChapterNode)"]
    LoopChapters --> BuildMsg["构建单章提示(含规划/上下文)"]
    BuildMsg --> CallLLM["调用LLM生成内容(JSON/纯文本)"]
    CallLLM --> Parse["解析内容并写入数据库"]
    Parse --> Verify["写入验证(失败重试)"]
    Verify --> Next["下一章"]
    Next --> |完成| End2(["结束"])
    

图示来源

• per-chapter.strategy.ts:25-54
• outline.node.ts:14-128
• per-chapter.node.ts:92-233
• utils.ts:15-23

章节来源

• per-chapter.strategy.ts:1-56
• outline.node.ts:1-129
• per-chapter.node.ts:1-324
• utils.ts:1-24

策略对比与适用场景

• 适用场景
  • OneStepOutlineStrategy：适合追求“快出结果”的场景，一次性生成完整大纲，随后并行填充内容，整体吞吐更高。
  • PerChapterStrategy：适合对“章节质量”要求更高的场景，每章独立生成，便于局部迭代与质量把关。
• 性能差异
  • OneStepOutlineStrategy：总调用次数约为 1(规划)+1(大纲)+N(内容)；内容阶段并行度高，吞吐更快。
  • PerChapterStrategy：总调用次数约为 1(规划)+1(大纲)+N(章)；每章独立生成，整体时延更稳定，但并行度受限于外部调度。
• 资源消耗
  • OneStepOutlineStrategy：内存与并发压力集中在内容生成阶段，需关注数据库写入与音频生成并发。
  • PerChapterStrategy：每章生成相对均衡，但总调用次数更多，需关注 LLM 调用与队列压力。

章节来源

• one-step-outline.strategy.ts:7-11
• per-chapter.strategy.ts:7-11

依赖分析

• 策略与节点耦合
  • OneStepOutlineStrategy 依赖 planBookNode、generateFullOutlineNode、writeChaptersNode；PerChapterStrategy 依赖 planBookNode、generateOutlineNode、perChapterNode。
• 基础设施依赖
  • 均依赖 base.ts 的 runGraphWorkflow，统一 LangGraph 编译、流式执行、进度监控与错误处理。
  • 容错层 fault-tolerance.ts 提供统一的 AI 调用重试、节点超时、进度监控与自动恢复。

• 配置与工具

  • book-type-config.ts 提供书籍规模、章节数与字数范围等配置；utils.ts 提供进度常量与字数统计。

    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
• per-chapter.strategy.ts:13-19
• base.ts:26-72
• fault-tolerance.ts:1-387
• book-type-config.ts:1-133
• utils.ts:1-24

章节来源

• selector.ts:12-20
• base.ts:1-73

性能考量

• 并发与吞吐
  • OneStepOutlineStrategy 的内容并行池（默认并发数见 content.node.ts:444-545）可显著提升吞吐；需结合数据库写入能力与音频生成队列容量进行调优。
  • PerChapterStrategy 的逐章处理在外部调度层面可并行多本书，但单书内部仍为串行推进。
• 字数与配额
  • 章节预算偏差检测与全书累计字数上限（见 content.node.ts:255-281 与 book-type-config.ts:10-132）可避免超预算与资源浪费。
  • 订阅配额检查与音频分钟消耗（见 content.node.ts）确保成本可控。
• 超时与重试
  • 节点超时配置（见 fault-tolerance.ts:27-38）与 AI 调用重试（见 fault-tolerance.ts:68-123）降低不稳定因素对整体性能的影响。

章节来源

• content.node.ts:255-281
• book-type-config.ts:10-132
• fault-tolerance.ts:27-38
• fault-tolerance.ts:68-123

故障排查指南

• 常见问题与定位
  • AI 调用失败：检查重试日志与数据库 errorMsg 字段，确认是否触发自动恢复。
  • 节点超时：核对节点超时配置与执行时间，必要时延长超时或优化提示词。
  • 长时间无响应：进度监控器会在 10/20/30 分钟发出告警，随后尝试自动恢复。
  • 内容写入失败：逐章节点对写入进行二次验证，失败会重试；若持续失败，检查数据库连接与并发写入。
• 容错机制
  • AI 调用重试（指数退避）、节点超时、进度监控、自动恢复与用户通知详见 fault-tolerance.ts:1-387 与 FAULT_TOLERANCE.md:1-334。
• 快速恢复
  • 若达到最大恢复次数，系统会标记最终失败并提示手动操作；可重新发起生成任务。

章节来源

• fault-tolerance.ts:188-261
• FAULT_TOLERANCE.md:86-164

结论

• OneStepOutlineStrategy 更适合“快速产出、高吞吐”的场景，通过一次性生成完整大纲与并行内容生成实现高效交付。
• PerChapterStrategy 更适合“质量优先、可控迭代”的场景，通过逐章生成与写入验证确保每章内容质量。
• 两者共享统一的容错层与状态机，具备完善的错误恢复与进度监控能力，适合在生产环境长期运行。

附录

参数调优指南

• 策略选择
  • 默认策略为 DeepPlanParallel（策略选择器），可通过运行时切换策略（见 selector.ts:42-56）。
• 并发与超时
  • OneStepOutlineStrategy：调整内容并行池并发数（见 content.node.ts:444-545）与节点超时（见 fault-tolerance.ts:27-38）。
  • PerChapterStrategy：外部调度可并行多本书，单书内部仍为串行推进。
• 字数与配额
  • 章节预算偏差阈值与全书上限（见 content.node.ts:255-281 与 book-type-config.ts:10-132）可根据业务目标调整。
  • 订阅配额检查与音频分钟消耗（见 content.node.ts）需与产品定价策略匹配。

输出格式规范

• 一步大纲 JSON（见 full-outline.node.ts:65-99）：包含 mainTheme、structureLogic、chapters（含 sections/subsections）。
• 章大纲 JSON（见 outline.node.ts:48-104）：包含 chapters（number/title/summary/keyPoints/estimatedWords）。
• 单章内容 JSON（见 per-chapter.node.ts:76-80）：包含 content、wordCount；若非 JSON 则直接按纯文本处理。

实际使用案例与最佳实践

• 快速试读/短文：选择 OneStepOutlineStrategy，利用并行内容生成快速产出。
• 教程/教材：选择 PerChapterStrategy，逐章生成确保结构与质量，便于后续修订。
• 大规模生成：结合外部调度对多本书并行，单书内部采用 PerChapterStrategy，提高稳定性与可控性。
• 质量评估：依据章节预算偏差检测与全书累计字数上限，结合用户反馈与音频生成完成度进行综合评估。

章节来源

• selector.ts:23-33
• content.node.ts:255-281
• book-type-config.ts:10-132
• full-outline.node.ts:65-99
• outline.node.ts:48-104
• per-chapter.node.ts:76-80