# 内容质量控制

<cite>
**本文引用的文件**
- [feature_list_content_generate.json](file://feature_list_content_generate.json)
- [fault-tolerance.ts](file://server/src/modules/book-generator/fault-tolerance.ts)
- [FAULT_TOLERANCE.md](file://server/src/modules/book-generator/FAULT_TOLERANCE.md)
- [outline-quality.ts](file://server/src/modules/book-generator/utils/outline-quality.ts)
- [content.node.ts](file://server/src/modules/book-generator/nodes/content.node.ts)
- [book-generator.controller.ts](file://server/src/modules/book-generator/book-generator.controller.ts)
- [ai-generate-controller.ts](file://server/src/modules/book-generator/ai-generate-controller.ts)
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.ts)
- [ai-content.service.js](file://deploy-package/server/modules/ai-content/ai-content.service.js)
</cite>

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

## 简介
本技术文档围绕“内容质量控制系统”展开，系统覆盖内容质量评估标准与指标、质量控制实现机制（敏感内容过滤、重复检测、合规检查）、故障容错设计（错误恢复、异常处理、数据完整性保障）、自动化流程（自动审核、人工复核、质量评分）、监控与报告（趋势分析、问题统计、改进建议）、配置与自定义规则，以及实际示例与调试技巧。文档基于仓库中的功能清单与实现文件进行梳理，帮助开发者与使用者快速理解并高效落地质量控制能力。

## 项目结构
质量控制相关能力主要分布在以下模块与文件：
- 功能清单与质量流程：feature_list_content_generate.json
- 容错与稳定性：fault-tolerance.ts、FAULT_TOLERANCE.md
- 大纲质量评估：outline-quality.ts
- 内容节点与预算控制：content.node.ts
- 批量生成编排与进度推送：book-generator.controller.ts、book-generator.service.ts
- 单次AI生成接口：ai-generate-controller.ts
- 质量服务（部署包演示）：ai-content.service.js

```mermaid
graph TB
subgraph "前端"
UI["内容生成界面<br/>进度查看"]
end
subgraph "后端"
BGCtrl["批量生成控制器<br/>book-generator.controller.ts"]
BGService["批量生成编排器<br/>book-generator.service.ts"]
FT["容错与恢复<br/>fault-tolerance.ts"]
OQ["大纲质量评估<br/>outline-quality.ts"]
CN["内容节点<br/>content.node.ts"]
AICtrl["AI生成控制器<br/>ai-generate-controller.ts"]
AISvc["质量服务(演示)<br/>ai-content.service.js"]
end
UI --> BGCtrl
BGCtrl --> BGService
BGService --> FT
BGService --> OQ
BGService --> CN
UI --> AICtrl
AICtrl --> AISvc
```

**图表来源**
- [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)
- [fault-tolerance.ts:1-387](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L387)
- [outline-quality.ts:1-173](file://server/src/modules/book-generator/utils/outline-quality.ts#L1-L173)
- [content.node.ts:235-264](file://server/src/modules/book-generator/nodes/content.node.ts#L235-L264)
- [ai-generate-controller.ts:1-152](file://server/src/modules/book-generator/ai-generate-controller.ts#L1-L152)
- [ai-content.service.js:645-904](file://deploy-package/server/modules/ai-content/ai-content.service.js#L645-L904)

**章节来源**
- [feature_list_content_generate.json:640-668](file://feature_list_content_generate.json#L640-L668)
- [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)

## 核心组件
- 质量评估与指标
  - 大纲质量评估：章节数量、标题重复、摘要/知识点缺失、粒度合理性、节结构完整性
  - 质量评分维度：语言流畅度、表达自然度、情感一致性、主题相关性、结构完整性
  - 敏感词检测与合规检查：实时检测、规则库、问题定位与修复建议
- 质量控制实现机制
  - 敏感内容过滤：实时检测与高亮、阻止生成、可配置忽略
  - 重复检测：标题去重、知识点粒度校验
  - 合规检查：行业规则匹配、问题列表与自动修复建议
- 故障容错系统
  - AI调用重试（指数退避）、节点超时控制、进度监控、自动恢复
- 自动化流程
  - 自动审核（敏感/合规/大纲质量）、人工复核（问题列表）、质量评分与报告
- 监控与报告
  - 质量趋势、问题统计、改进建议、分析报告（词云、情感曲线、阅读时长）

**章节来源**
- [feature_list_content_generate.json:81-92](file://feature_list_content_generate.json#L81-L92)
- [feature_list_content_generate.json:239-284](file://feature_list_content_generate.json#L239-L284)
- [feature_list_content_generate.json:601-639](file://feature_list_content_generate.json#L601-L639)
- [outline-quality.ts:8-173](file://server/src/modules/book-generator/utils/outline-quality.ts#L8-L173)
- [fault-tolerance.ts:17-51](file://server/src/modules/book-generator/fault-tolerance.ts#L17-L51)

## 架构总览
内容质量控制贯穿“意图识别-内容规划-分步生成-质量控制-音频合成”的全流程。质量控制阶段对生成内容进行敏感词检测、合规检查与质量评分，并结合大纲质量评估与预算控制，确保内容完整性与一致性。

```mermaid
sequenceDiagram
participant U as "用户"
participant C as "批量生成控制器"
participant S as "批量生成编排器"
participant G as "LangGraph生成器"
participant Q as "质量控制模块"
participant F as "容错系统"
U->>C : 提交批量生成请求
C->>S : 创建编排器并启动
S->>G : 启动内容生成
G-->>S : 推送章节生成进度
S->>Q : 对章节内容执行质量控制
Q-->>S : 返回敏感/合规/评分结果
S->>F : 监控进度与节点超时
F-->>S : 超时/失败时自动恢复
S-->>U : 推送最终进度与结果
```

**图表来源**
- [book-generator.controller.ts:24-119](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L119)
- [book-generator.service.ts:149-217](file://server/src/modules/book-generator/book-generator.service.ts#L149-L217)
- [fault-tolerance.ts:188-261](file://server/src/modules/book-generator/fault-tolerance.ts#L188-L261)

## 详细组件分析

### 大纲质量评估器
- 功能要点
  - 章节数范围检查、标题重复检测、摘要/知识点缺失统计、粒度合理性评估、节结构完整性检查
  - 输出通过性、得分与警告列表，支持不同生成层级的差异化校验
- 关键指标
  - 章节数偏离度扣分、重复标题扣分、缺失摘要/知识点扣分、粒度过粗/过细则扣分
- 复杂度
  - 时间复杂度 O(n)（n 为章节数），空间复杂度 O(k)（k 为唯一标题数量）

```mermaid
flowchart TD
Start(["开始评估"]) --> Validate["校验输入参数"]
Validate --> Empty{"章节为空？"}
Empty --> |是| Fail["返回失败与高严重度警告"]
Empty --> |否| Titles["统计标题出现次数"]
Titles --> Dup{"存在重复标题？"}
Dup --> |是| AddDupWarn["添加重复标题警告并扣分"]
Dup --> |否| ChaptersRange["检查章节数范围"]
ChaptersRange --> RangeWarn{"超出推荐范围？"}
RangeWarn --> |是| AddRangeWarn["添加范围警告并扣分"]
RangeWarn --> |否| SummaryKP["检查摘要与知识点"]
SummaryKP --> SummaryEmpty{"摘要缺失？"}
SummaryEmpty --> |是| AddSummaryWarn["添加摘要缺失警告并扣分"]
SummaryEmpty --> |否| KPEmpty{"知识点缺失？"}
KPEmpty --> |是| AddKPWarn["添加知识点缺失警告并扣分"]
KPEmpty --> |否| Granularity["检查粒度合理性"]
Granularity --> Fine{"粒度过细/过粗？"}
Fine --> |是| AddGranWarn["添加粒度警告并扣分"]
Fine --> |否| Sections{"检查节结构层级≥2"}
Sections --> PassScore["计算最终得分与通过性"]
PassScore --> End(["结束"])
```

**图表来源**
- [outline-quality.ts:37-172](file://server/src/modules/book-generator/utils/outline-quality.ts#L37-L172)

**章节来源**
- [outline-quality.ts:8-173](file://server/src/modules/book-generator/utils/outline-quality.ts#L8-L173)

### 内容节点与预算控制
- 功能要点
  - 章节内容生成后进行字数统计与预算偏差检测，超过预算上限按智能边界截断，防止内容膨胀
  - 三层安全防护：工具可用性降级、预算偏差截断、异常日志记录
- 关键流程
  - LLM调用 → 清洗内容 → 统计字数 → 预算校验 → 截断处理（如需） → 更新进度

```mermaid
flowchart TD
Enter(["进入内容节点"]) --> CallLLM["调用LLM生成内容"]
CallLLM --> Clean["清洗内容"]
Clean --> Count["统计字数"]
Count --> Budget{"是否超出预算上限？"}
Budget --> |是| Truncate["按边界截断智能段落"]
Budget --> |否| Proceed["继续处理"]
Truncate --> Proceed
Proceed --> Update["更新章节统计与进度"]
Update --> Exit(["退出节点"])
```

**图表来源**
- [content.node.ts:235-264](file://server/src/modules/book-generator/nodes/content.node.ts#L235-L264)

**章节来源**
- [content.node.ts:235-264](file://server/src/modules/book-generator/nodes/content.node.ts#L235-L264)

### 故障容错系统
- 重试机制
  - AI调用最多重试 N 次，采用指数退避策略，每次重试前通知用户
- 节点超时控制
  - 不同节点配置不同超时阈值；超时后通知用户并触发恢复流程
- 进度监控
  - 定期检查书籍进度，长时间无进展发出警告，第三次尝试自动恢复
- 自动恢复
  - 限制最大恢复次数，超过则标记失败并提示手动重新生成

```mermaid
sequenceDiagram
participant S as "编排器"
participant FT as "容错系统"
participant LLM as "LLM服务"
participant WS as "WebSocket通知"
S->>FT : 调用带重试的LLM
loop 重试循环
FT->>LLM : 发起请求
alt 成功
LLM-->>FT : 返回结果
FT-->>S : 返回结果
else 失败
FT->>WS : 通知用户重试
FT->>FT : 指数退避等待
end
end
S->>FT : 节点执行带超时
FT-->>S : 超时/完成/失败
S->>FT : 启动进度监控
FT-->>S : 长时间无响应时尝试自动恢复
```

**图表来源**
- [fault-tolerance.ts:68-123](file://server/src/modules/book-generator/fault-tolerance.ts#L68-L123)
- [fault-tolerance.ts:131-180](file://server/src/modules/book-generator/fault-tolerance.ts#L131-L180)
- [fault-tolerance.ts:188-261](file://server/src/modules/book-generator/fault-tolerance.ts#L188-L261)
- [fault-tolerance.ts:268-323](file://server/src/modules/book-generator/fault-tolerance.ts#L268-L323)

**章节来源**
- [fault-tolerance.ts:17-51](file://server/src/modules/book-generator/fault-tolerance.ts#L17-L51)
- [FAULT_TOLERANCE.md:182-237](file://server/src/modules/book-generator/FAULT_TOLERANCE.md#L182-L237)

### 质量评分与合规检查（部署包演示）
- 质量评分
  - 维度：流畅度、自然度、情感一致性、主题相关性、结构完整性
  - 输出整体分数与维度明细，支持生成分析报告
- 合规检查
  - 基于行业规则进行检查，输出问题列表与修复建议
- 敏感词检测
  - 实时检测并高亮敏感词，提供替换建议

```mermaid
classDiagram
class QualityService {
+scoreQuality(text) QualityReport
+optimizeContent(text, target) OptimizeResult
+checkCompliance(text, industry) ComplianceResult
+checkSensitive(text) SensitiveResult
}
class QualityReport {
+number overall
+map dimensions
+string report
}
class ComplianceResult {
+boolean passed
+array issues
+array warnings
}
class SensitiveResult {
+boolean isClean
+array foundWords
+array positions
+array suggestions
}
QualityService --> QualityReport : "返回"
QualityService --> ComplianceResult : "返回"
QualityService --> SensitiveResult : "返回"
```

**图表来源**
- [ai-content.service.js:694-705](file://deploy-package/server/modules/ai-content/ai-content.service.js#L694-L705)
- [ai-content.service.js:877-883](file://deploy-package/server/modules/ai-content/ai-content.service.js#L877-L883)
- [ai-content.service.js:681-690](file://deploy-package/server/modules/ai-content/ai-content.service.js#L681-L690)

**章节来源**
- [feature_list_content_generate.json:260-284](file://feature_list_content_generate.json#L260-L284)
- [feature_list_content_generate.json:601-618](file://feature_list_content_generate.json#L601-L618)
- [feature_list_content_generate.json:240-257](file://feature_list_content_generate.json#L240-L257)
- [ai-content.service.js:694-705](file://deploy-package/server/modules/ai-content/ai-content.service.js#L694-L705)

### 批量生成与进度监控
- 批量生成编排器负责按步骤顺序执行：内容生成、音频生成、音频合并、视频生成、视频合并
- 每步执行前推送进度，支持取消标志与超时检查
- 通过 WebSocket 推送进度，便于前端实时展示

```mermaid
sequenceDiagram
participant C as "控制器"
participant O as "编排器"
participant P as "进度推送"
participant DB as "数据库"
C->>O : 创建并启动编排器
loop 每个步骤
O->>P : 推送步骤开始
O->>DB : 轮询检查状态/进度
alt 步骤完成
O->>P : 推送步骤完成
else 步骤失败/取消
O-->>C : 返回错误信息
end
end
O-->>C : 推送最终完成
```

**图表来源**
- [book-generator.controller.ts:24-119](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L119)
- [book-generator.service.ts:77-143](file://server/src/modules/book-generator/book-generator.service.ts#L77-L143)

**章节来源**
- [book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)

## 依赖关系分析
- 模块耦合
  - 编排器依赖容错系统与存储服务，确保生成过程稳定与可观测
  - 大纲质量评估独立于生成流程，作为前置校验
  - 质量服务（评分/合规/敏感词）可插拔接入，便于替换与扩展
- 外部依赖
  - LLM 服务、WebSocket 通知、队列服务（用于恢复重试）

```mermaid
graph LR
BGService["编排器"] --> FT["容错系统"]
BGService --> Store["存储/进度"]
BGService --> WS["WebSocket通知"]
BGService --> OQ["大纲质量评估"]
BGService --> CN["内容节点"]
AISvc["质量服务(演示)"] --> LLM["LLM服务"]
```

**图表来源**
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)
- [fault-tolerance.ts:1-387](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L387)
- [outline-quality.ts:1-173](file://server/src/modules/book-generator/utils/outline-quality.ts#L1-L173)
- [ai-content.service.js:645-904](file://deploy-package/server/modules/ai-content/ai-content.service.js#L645-L904)

**章节来源**
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)
- [fault-tolerance.ts:1-387](file://server/src/modules/book-generator/fault-tolerance.ts#L1-L387)

## 性能考量
- 重试与超时
  - 指数退避降低对上游服务的压力峰值，避免雪崩效应
  - 节点超时阈值按任务复杂度分级，平衡吞吐与稳定性
- 进度轮询
  - 合理的轮询间隔与最大等待时间，避免过度占用资源
- 截断策略
  - 智能边界截断减少无效内容，提升后续处理效率

[本节为通用指导，无需具体文件引用]

## 故障排查指南
- 常见问题
  - 生成超时：检查节点超时配置与网络状况，确认容错监控是否触发自动恢复
  - 重试失败：查看失败日志与错误消息，确认是否超过最大重试次数
  - 进度停滞：确认数据库状态更新是否正常，检查取消标志与任务状态
- 调试技巧
  - 启用详细日志，关注“容错”、“进度监控”、“自动恢复”关键节点
  - 使用单步生成接口验证 LLM 调用与清洗逻辑
  - 对比大纲质量评估结果，定位章节数量、标题重复、摘要/知识点缺失等问题

**章节来源**
- [fault-tolerance.ts:188-261](file://server/src/modules/book-generator/fault-tolerance.ts#L188-L261)
- [fault-tolerance.ts:268-323](file://server/src/modules/book-generator/fault-tolerance.ts#L268-L323)
- [ai-generate-controller.ts:16-95](file://server/src/modules/book-generator/ai-generate-controller.ts#L16-L95)

## 结论
内容质量控制系统通过“大纲质量评估 + 内容预算控制 + 敏感词/合规/评分 + 容错与恢复”的组合拳，实现了从结构到语义再到稳定性的一体化质量保障。配合批量生成编排与进度监控，系统具备良好的可观测性与可维护性。建议在生产环境中结合业务场景进一步细化规则与阈值，并持续迭代质量评估维度与恢复策略。

[本节为总结，无需具体文件引用]

## 附录

### 质量控制流程与API参考
- 批量生成
  - POST /api/book-generator/books/:id/batch-generate
  - POST /api/book-generator/books/:id/batch-generate/cancel
  - GET /api/book-generator/books/:id/batch-generate/status
- 单次AI生成
  - POST /api/book-generator/ai-generate
  - POST /api/book-generator/ai-generate/sync
- 质量服务（部署包演示）
  - 质量评分：scoreQuality(text)
  - 合规检查：checkCompliance(text, industry)
  - 敏感词检测：checkSensitive(text)

**章节来源**
- [book-generator.controller.ts:24-197](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L197)
- [ai-generate-controller.ts:16-149](file://server/src/modules/book-generator/ai-generate-controller.ts#L16-L149)
- [ai-content.service.js:694-705](file://deploy-package/server/modules/ai-content/ai-content.service.js#L694-L705)
- [ai-content.service.js:877-883](file://deploy-package/server/modules/ai-content/ai-content.service.js#L877-L883)
- [ai-content.service.js:681-690](file://deploy-package/server/modules/ai-content/ai-content.service.js#L681-L690)

### 配置与自定义规则
- 容错配置
  - AI重试次数、初始/最大延迟、指数退避倍数
  - 节点超时阈值（按节点类型配置）
  - 进度监控空闲时间阈值与检查间隔
  - 自动恢复最大尝试次数与延迟
- 大纲质量评估
  - 章节数范围（最小/最大）、摘要/知识点缺失阈值、粒度上下限
- 行业规则与敏感词库
  - 合规规则按行业配置，敏感词库可动态更新与忽略列表

**章节来源**
- [fault-tolerance.ts:17-51](file://server/src/modules/book-generator/fault-tolerance.ts#L17-L51)
- [outline-quality.ts:71-91](file://server/src/modules/book-generator/utils/outline-quality.ts#L71-L91)
- [feature_list_content_generate.json:81-92](file://feature_list_content_generate.json#L81-L92)