Home Esplora Aiuto
Accedi
caojunfei
/
audio_codebuddy
1
0
Forka 0
File Problemi 0 Pull Requests 0 Wiki
Albero (Tree): b76f56a46b
Rami (Branch) Tag
audio_codebuddy
/
.qoder
/
repowiki
/
zh
/
content
/
系统架构
/
模块架构
/
核心业务模块
/
AI书籍生成引擎
/
生成节点系统.md

生成节点系统.md 28 KB
Cronologia Originale

生成节点系统

本文档引用的文件

  • content.node.ts
  • foreword.node.ts
  • full-outline.node.ts
  • outline.node.ts
  • per-chapter.node.ts
  • plan.node.ts
  • sections.node.ts
  • graph.ts
  • book-generator.types.ts
  • book-type-config.ts
  • utils.ts
  • sequential.strategy.ts
  • one-step-outline.strategy.ts
  • per-chapter.strategy.ts
  • book-generator.controller.ts

目录

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

简介

本文件面向“生成节点系统”，系统性梳理并解释各节点的功能、输入输出、处理逻辑与协作关系，覆盖以下节点：

  • content.node（内容生成节点）
  • foreword.node（序言节点）
  • full-outline.node（完整大纲节点）
  • outline.node（大纲节点）
  • per-chapter.node（按章节生成节点）
  • plan.node（规划节点）
  • sections.node（章节节点）

同时阐明节点间依赖关系、执行顺序、数据传递机制，并提供扩展新节点类型、配置参数与调试执行过程的方法。

项目结构

生成节点系统位于服务端模块 book-generator 下，采用“节点 + 策略 + 图状态”的分层设计：

  • nodes：具体节点实现（每个文件对应一个节点）
  • strategies：生成策略（串联/并行组合不同节点）
  • graph.ts：LangGraph 状态定义与工作流编排
  • book-generator.types.ts：核心数据类型
  • book-type-config.ts：书籍规模与字数/章节数配置
  • utils.ts：通用工具（进度常量、字数统计等）

  • book-generator.controller.ts：对外 API（批量生成、取消、状态查询）

    graph TB
subgraph "节点"
PLAN["plan.node.ts"]
OUTLINE["outline.node.ts"]
FULL_OUTLINE["full-outline.node.ts"]
SECTIONS["sections.node.ts"]
PER_CHAPTER["per-chapter.node.ts"]
CONTENT["content.node.ts"]
FOREWORD["foreword.node.ts"]
end
subgraph "策略"
SEQ["sequential.strategy.ts"]
ONESTEP["one-step-outline.strategy.ts"]
PERCHAPTER["per-chapter.strategy.ts"]
end
subgraph "图与类型"
GRAPH["graph.ts"]
TYPES["book-generator.types.ts"]
CFG["book-type-config.ts"]
UTILS["utils.ts"]
end
PLAN --> OUTLINE
OUTLINE --> SECTIONS
SECTIONS --> CONTENT
FULL_OUTLINE --> CONTENT
PER_CHAPTER --> CONTENT
FOREWORD --> CONTENT
SEQ --> PLAN
SEQ --> OUTLINE
SEQ --> SECTIONS
SEQ --> CONTENT
ONESTEP --> PLAN
ONESTEP --> FULL_OUTLINE
ONESTEP --> CONTENT
PERCHAPTER --> PLAN
PERCHAPTER --> OUTLINE
PERCHAPTER --> PER_CHAPTER

图表来源

  • sequential.strategy.ts:1-60
  • one-step-outline.strategy.ts:1-56
  • per-chapter.strategy.ts:1-56
  • plan.node.ts:145-201
  • outline.node.ts:14-129
  • sections.node.ts:19-235
  • content.node.ts:102-332
  • full-outline.node.ts:135-218
  • per-chapter.node.ts:92-233
  • foreword.node.ts:14-48

章节来源

  • graph.ts:1-83
  • book-generator.types.ts:1-226
  • book-type-config.ts:1-133
  • utils.ts:1-24

核心组件

  • 节点（Node）：每个文件代表一个独立的处理单元，负责特定阶段的任务（规划、大纲、章节、内容、序言等），接收 GraphState，返回部分状态更新。
  • 策略（Strategy）：定义节点的执行顺序与组合方式，如串行策略、一步大纲策略、逐章策略。
  • 图状态（GraphState）：LangGraph 的状态注解，包含 bookId、topic、bookScale、genLevel、progress、finished 等字段，支持 reducer 保证进度只增不减。
  • 类型与配置：book-generator.types.ts 定义书籍、章节、任务等核心类型；book-type-config.ts 提供书籍规模、字数/章节数、安全上限等配置；utils.ts 提供进度常量与字数统计。

章节来源

  • graph.ts:23-82
  • book-generator.types.ts:8-139
  • book-type-config.ts:47-133
  • utils.ts:15-24

架构总览

系统通过 LangGraph 将多个节点串联或并行组合，形成不同的生成策略。策略文件定义节点连接关系，节点文件实现具体业务逻辑，类型与配置为节点提供数据契约与约束。

sequenceDiagram
participant Client as "客户端"
participant Controller as "book-generator.controller.ts"
participant Strategy as "策略(Sequential/OneStep/PerChapter)"
participant Plan as "plan.node.ts"
participant Outline as "outline.node.ts 或 full-outline.node.ts"
participant Sections as "sections.node.ts"
participant Content as "content.node.ts"
participant Foreword as "foreword.node.ts"
Client->>Controller : POST /books/ : id/batch-generate
Controller->>Strategy : 创建并启动生成任务
Strategy->>Plan : plan_book
Plan-->>Strategy : 返回 genLevel 与 bookPlan
alt 串行策略
Strategy->>Outline : generate_outline
Outline-->>Strategy : 返回 outlineJson
Strategy->>Sections : generate_sections
Sections-->>Strategy : 补充节大纲
Strategy->>Sections : generate_subsections
Sections-->>Strategy : 补充小节大纲
Strategy->>Content : write_chapters
Content-->>Strategy : 完成内容生成
else 一步大纲策略
Strategy->>Outline : generate_full_outline
Outline-->>Strategy : 返回完整树形大纲
Strategy->>Content : write_chapters
Content-->>Strategy : 完成内容生成
else 逐章策略
Strategy->>Outline : generate_outline
Outline-->>Strategy : 返回章大纲
Strategy->>Content : per_chapter
Content-->>Strategy : 每章独立生成结构+内容
end
Strategy->>Foreword : 生成前言/后记
Foreword-->>Strategy : 完成
Strategy-->>Controller : 返回完成状态
Controller-->>Client : 返回任务结果

图表来源

  • book-generator.controller.ts:24-119
  • sequential.strategy.ts:33-58
  • one-step-outline.strategy.ts:33-53
  • per-chapter.strategy.ts:33-53
  • plan.node.ts:145-201
  • outline.node.ts:14-129
  • full-outline.node.ts:135-218
  • sections.node.ts:19-235
  • content.node.ts:102-332
  • foreword.node.ts:14-48

详细组件分析

规划节点（plan.node）

  • 功能：在生成任何内容之前，由 AI 对书籍进行规划，确定大纲层级（1/2/3层）、写作风格、结构逻辑、内容深度与目标读者分析。
  • 输入：GraphState.bookId、topic、description、bookScale
  • 输出：GraphState.genLevel、GraphState.bookPlan（JSON字符串）
  • 关键逻辑：
    • 构建规划提示词，调用 LLM，解析 JSON，持久化到数据库并回传给后续节点。
    • 若用户已指定 genLevel，则在特定条件下保留用户选择。
  • 典型用途：为 outline.node、sections.node、content.node 提供 genLevel 与规划上下文。

章节来源

  • plan.node.ts:145-201
  • plan.node.ts:101-139
  • plan.node.ts:41-96

大纲节点（outline.node）

  • 功能：生成章级大纲，支持容错重试与超时控制，解析并校验章节数范围，补充默认章节。
  • 输入：GraphState.bookId、topic、bookScale、description、bookPlan
  • 输出：GraphState.progress（OUTLINE_DONE）、更新书籍 outlineJson
  • 关键逻辑：
    • 使用提示词构建器生成消息，调用 LLM，解析 JSON，校验章节数（±20%浮动），必要时补充默认章节。
    • 容错包装器封装 AI 调用与超时。
  • 典型用途：为 sections.node 提供章级大纲。

章节来源

  • outline.node.ts:14-129

完整大纲节点（full-outline.node）

  • 功能：一步生成完整树形大纲（章→节→小节），并存入数据库。
  • 输入：GraphState.bookId、topic、bookScale、genLevel、bookPlan
  • 输出：GraphState.progress（OUTLINE_DONE）、更新书籍 outlineJson
  • 关键逻辑：
    • 构建一步大纲提示词，调用 LLM，解析 JSON，按 genLevel 写入章/节/小节记录。
    • 容错包装器与超时控制。
  • 典型用途：配合 content.node 的并行内容生成。

章节来源

  • full-outline.node.ts:135-218
  • full-outline.node.ts:18-108

章节节点（sections.node）

  • 功能：为每章生成节的大纲（genLevel>1 时生效），并写入数据库。
  • 输入：GraphState.bookId、genLevel、outlineJson
  • 输出：GraphState.progress（SECTIONS_DONE）、更新 outlineJson（带 sections）
  • 关键逻辑：
    • 逐章构建提示词，调用 LLM，解析节大纲，写入节记录。
    • 多次重试确保解析成功。
  • 典型用途：为小节节点提供节级大纲。

章节来源

  • sections.node.ts:19-110

小节节点（sections.node）

  • 功能：为每节生成小节的大纲（genLevel>2 时生效），并写入数据库。
  • 输入：GraphState.bookId、genLevel、outlineJson
  • 输出：GraphState.progress（SUBSECTIONS_DONE）、更新 outlineJson（带 subsections）
  • 关键逻辑：
    • 逐节构建提示词，调用 LLM，解析小节大纲，写入小节记录。
    • 多次重试确保解析成功。
  • 典型用途：为 content.node 提供完整层级结构。

章节来源

  • sections.node.ts:117-235

内容生成节点（content.node）

  • 功能：为叶节点（没有子节点）生成正文内容，支持串行与并行两种实现。
  • 输入：GraphState.bookId、topic、bookScale、genLevel、outlineJson
  • 输出：GraphState.progress（CONTENT_END）、更新章节内容与字数、触发音频生成
  • 关键逻辑：
    • 识别叶节点，过滤未完成内容的目标。
    • 串行实现：逐个生成，额度与字数安全控制，异常处理与重试。
    • 并行实现：AsyncPool 并发生成，拓扑排序与依赖处理，统一更新父节点状态。
    • 安全防护：章节预算偏差检测、全书累计字数上限、全局绝对上限。

  • 典型用途：生成最终内容并触发音频生成。

    flowchart TD
Start(["进入 writeChaptersNode"]) --> LoadBook["加载书籍与大纲"]
LoadBook --> FindLeaves["查找叶节点并过滤未完成项"]
FindLeaves --> HasTargets{"是否存在待生成目标？"}
HasTargets --> |否| Skip["跳过生成，触发音频生成"] --> End
HasTargets --> |是| BuildCtx["构建父节点映射与工具"]
BuildCtx --> Loop["遍历每个目标"]
Loop --> Quota["额度检查与字数上限校验"]
Quota --> GenType{"短文还是长篇？"}
GenType --> |短文| ShortMsg["构建短文消息"]
GenType --> |长篇| LongMsg["构建小节内容消息"]
ShortMsg --> CallLLM["调用 LLM 生成内容"]
LongMsg --> CallLLM
CallLLM --> Clean["清理思考标签与无关文本"]
Clean --> Safety["三层安全防护：预算偏差/全书上限/全局上限"]
Safety --> Consume["消耗音频分钟配额"]
Consume --> Save["保存内容与字数，推进阶段"]
Save --> Trigger["触发音频生成"]
Trigger --> Next["下一个目标"]
Next --> Loop
Loop --> Done["全部完成，更新父节点状态"] --> End(["退出"])

图表来源

  • content.node.ts:102-332
  • content.node.ts:22-55
  • content.node.ts:240-317

章节来源

  • content.node.ts:102-332
  • content.node.ts:334-546

按章节生成节点（per-chapter.node）

  • 功能：先生成章大纲，再为每章独立生成内部结构（节/小节）+ 内容，支持容错与重试。
  • 输入：GraphState.bookId、topic、bookScale、genLevel、bookPlan
  • 输出：GraphState.progress（CONTENT_END）、更新章节内容与结构
  • 关键逻辑：
    • 逐章构建提示词，调用 LLM，解析 JSON，创建内部结构（节/小节）并保存内容。
    • 数据库写入验证与重试，确保内容落库。
  • 典型用途：逐章内聚生成，便于并行扩展。

章节来源

  • per-chapter.node.ts:92-233
  • per-chapter.node.ts:28-86

序言节点（foreword.node）

  • 功能：生成前言与后记，分别更新进度与完成状态。
  • 输入：GraphState.bookId、topic
  • 输出：GraphState.progress（FOREWORD_DONE/AFTERWORD_DONE）、更新书籍 foreword/afterword
  • 关键逻辑：构建提示词，调用 LLM，保存到数据库。

章节来源

  • foreword.node.ts:14-48

依赖关系分析

  • 节点依赖：
    • outline.node 依赖 bookPlan（来自 plan.node）与书籍规模配置。
    • sections.node 依赖 outline.node 的章级大纲。
    • full-outline.node 与 per-chapter.node 均可替代 outline.node 的作用，但前者生成完整树形大纲，后者仅生成章级大纲。
    • content.node 依赖 outlineJson 与 genLevel，支持串行与并行两种实现。
    • foreword.node 独立于大纲生成，完成后置处理。
  • 策略依赖：
    • sequential.strategy 串联 plan → outline → sections → subsections → content。
    • one-step-outline.strategy 串联 plan → full-outline → content。
    • per-chapter.strategy 串联 plan → outline → per-chapter。

  • 类型与配置：

    • GraphState 定义状态字段与 reducer。
    • book-type-config 提供字数/章节数/安全上限等配置。

    • utils 提供进度常量。

      graph LR
PLAN["plan.node"] --> OUTLINE["outline.node"]
PLAN --> FULL_OUTLINE["full-outline.node"]
PLAN --> PERCHAPTER["per-chapter.node"]
OUTLINE --> SECTIONS["sections.node"]
SECTIONS --> CONTENT["content.node"]
FULL_OUTLINE --> CONTENT
PERCHAPTER --> CONTENT
FOREWORD["foreword.node"] --> CONTENT

图表来源

  • sequential.strategy.ts:33-44
  • one-step-outline.strategy.ts:33-40
  • per-chapter.strategy.ts:33-40

章节来源

  • graph.ts:23-82
  • book-type-config.ts:95-133
  • utils.ts:15-24

性能考量

  • 并行优化：
    • content.node 的并行实现通过 AsyncPool 控制并发数，减少整体生成时间。
    • per-chapter.node 的逐章处理避免并发写入冲突，适合大规模书籍。
  • 容错与超时：
    • outline.node、full-outline.node、per-chapter.node 均使用容错包装器与超时控制，提升稳定性。
  • 配额与安全：
    • 字数安全三重防护：章节预算偏差检测、全书累计字数上限、全局绝对上限（50 万字）。
    • 音频分钟配额消耗，结合订阅服务进行额度控制。
  • 进度只增不减：
    • GraphState 的 reducer 设计确保进度不会回退，便于前端展示与任务追踪。

章节来源

  • content.node.ts:444-546
  • outline.node.ts:29-46
  • full-outline.node.ts:149-160
  • per-chapter.node.ts:138-143
  • book-type-config.ts:120-133
  • graph.ts:12-21

故障排查指南

  • 常见问题与定位：
    • 大纲解析失败：检查 outline.node 与 full-outline.node 的 JSON 解析逻辑，确认提示词格式与 LLM 输出一致性。
    • 章节内容未落库：查看 per-chapter.node 的写入验证与重试逻辑，确认数据库查询条件与 ID 映射。
    • 并行内容生成异常：检查 content.node 的并行池配置与任务上下文，关注工具调用与截断逻辑。
    • 额度不足或字数超限：查看额度检查与字数上限逻辑，确认用户配额与累计字数统计。
  • 调试建议：
    • 在节点入口打印 bookId、genLevel、进度等关键信息。
    • 使用容错包装器捕获错误并记录重试次数与最后一次错误。
    • 逐步缩小问题范围：先验证 outline 生成，再验证 sections/subsections，最后验证 content 生成。
  • API 层辅助：
    • 使用批量生成 API 的状态查询与取消接口，便于任务管理与资源回收。

章节来源

  • outline.node.ts:14-129
  • full-outline.node.ts:135-218
  • per-chapter.node.ts:169-201
  • content.node.ts:240-317
  • book-generator.controller.ts:162-199

结论

生成节点系统通过“节点 + 策略 + 图状态”的架构实现了可插拔、可扩展的书籍生成流水线。不同策略在不同场景下平衡了生成质量与效率，节点间通过 GraphState 实现稳定的数据传递与进度管理。安全与容错机制保障了大规模生成的可靠性，而并行优化显著提升了吞吐能力。建议在扩展新节点时遵循现有模式：定义输入输出、实现容错与日志、接入进度更新与安全检查，并通过策略文件进行编排。

附录

A. 节点输入输出与处理逻辑速览

  • 规划节点（plan.node）
    • 输入：bookId、topic、description、bookScale
    • 输出：genLevel、bookPlan
    • 处理：构建提示词 → LLM → 解析 JSON → 持久化 → 回传
  • 大纲节点（outline.node）
    • 输入：bookId、topic、bookScale、description、bookPlan
    • 输出：outlineJson、progress（OUTLINE_DONE）
    • 处理：容错调用 → 解析 → 校验章节数 → 写入数据库
  • 完整大纲节点（full-outline.node）
    • 输入：bookId、topic、bookScale、genLevel、bookPlan
    • 输出：outlineJson、progress（OUTLINE_DONE）
    • 处理：一步生成树形大纲 → 写入章/节/小节
  • 章节节点（sections.node）
    • 输入：bookId、genLevel、outlineJson
    • 输出：更新 outlineJson（含 sections）、progress（SECTIONS_DONE）
    • 处理：逐章生成节大纲 → 写入数据库
  • 小节节点（sections.node）
    • 输入：bookId、genLevel、outlineJson
    • 输出：更新 outlineJson（含 subsections）、progress（SUBSECTIONS_DONE）
    • 处理：逐节生成小节大纲 → 写入数据库
  • 内容生成节点（content.node）
    • 输入：bookId、topic、bookScale、genLevel、outlineJson
    • 输出：progress（CONTENT_END）、章节内容与字数、触发音频生成
    • 处理：识别叶节点 → 串行/并行生成 → 安全防护 → 保存与推进
  • 按章节生成节点（per-chapter.node）
    • 输入：bookId、topic、bookScale、genLevel、bookPlan
    • 输出：progress（CONTENT_END）、章节内容与结构
    • 处理：逐章生成 → 解析 JSON → 创建内部结构 → 写入数据库
  • 序言节点（foreword.node）
    • 输入：bookId、topic
    • 输出：foreword、afterword、progress（FOREWORD_DONE/AFTERWORD_DONE）
    • 处理：构建提示词 → LLM → 保存

章节来源

  • plan.node.ts:145-201
  • outline.node.ts:14-129
  • full-outline.node.ts:135-218
  • sections.node.ts:19-235
  • content.node.ts:102-332
  • per-chapter.node.ts:92-233
  • foreword.node.ts:14-48

B. 执行顺序与策略对照

  • 串行策略（sequential）：plan → outline → sections → subsections → content
  • 一步大纲策略（one-step-outline）：plan → full-outline → content
  • 逐章策略（per-chapter）：plan → outline → per-chapter

章节来源

  • sequential.strategy.ts:21-59
  • one-step-outline.strategy.ts:21-55
  • per-chapter.strategy.ts:21-55

C. 扩展新节点类型指南

  • 步骤
    • 定义节点函数：接收 GraphState，返回部分状态更新。
    • 引入容错与日志：使用容错包装器与超时控制，打印关键信息。
    • 解析与持久化：解析 LLM 输出，写入数据库或更新 GraphState。
    • 进度管理：更新 progress 常量，确保只增不减。
    • 加入策略：在策略文件中注册节点并设置边连接。
  • 示例路径
    • 新节点实现：参考 content.node.ts:102-332
    • 容错与超时：参考 outline.node.ts:29-46
    • 进度常量：参考 utils.ts:15-24

章节来源

  • content.node.ts:102-332
  • outline.node.ts:14-129
  • utils.ts:15-24

D. 配置节点参数

  • 书籍规模与层级
    • bookScale：影响章节数与字数上限（参考 book-type-config.ts:95-133）
    • genLevel：1/2/3 层级（参考 graph.ts:40-44）
  • 进度与安全
    • 进度常量：OUTLINE_DONE、SECTIONS_DONE、SUBSECTIONS_DONE、CONTENT_START、CONTENT_END、FOREWORD_DONE、AFTERWORD_DONE（参考 utils.ts:15-24）
    • 字数上限：章节预算偏差检测、全书累计字数上限、全局绝对上限（参考 content.node.ts:255-281、book-type-config.ts:120-133）
  • 并发与容错
    • 并行内容生成并发数：参考 content.node.ts:336-338
    • 容错重试与超时：参考 outline.node.ts:29-46、full-outline.node.ts:149-160、per-chapter.node.ts:138-143

章节来源

  • book-type-config.ts:95-133
  • graph.ts:40-44
  • utils.ts:15-24
  • content.node.ts:255-281
  • outline.node.ts:29-46
  • full-outline.node.ts:149-160
  • per-chapter.node.ts:138-143

E. 调试节点执行过程

  • 关键调试点
    • 节点入口：打印 bookId、genLevel、topic、进度等。
    • 容错日志：记录重试次数、最后一次错误、超时原因。
    • 数据落库验证：写入后二次查询确认内容已保存。
    • 并行任务：检查任务上下文、并发数与失败统计。
  • API 辅助
    • 批量生成状态查询与取消接口，便于任务管理（参考 book-generator.controller.ts:162-199）

章节来源

  • per-chapter.node.ts:183-198
  • content.node.ts:512-516
  • book-generator.controller.ts:162-199