# 提示词工程与模板

<cite>
**本文引用的文件**
- [builder.ts](file://server/src/modules/book-generator/prompts/builder.ts)
- [templates.ts](file://server/src/modules/book-generator/prompts/templates.ts)
- [outline.parser.ts](file://server/src/modules/book-generator/parsers/outline.parser.ts)
- [section.parser.ts](file://server/src/modules/book-generator/parsers/section.parser.ts)
- [subsection.parser.ts](file://server/src/modules/book-generator/parsers/subsection.parser.ts)
- [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)
- [sequential.strategy.ts](file://server/src/modules/book-generator/strategies/sequential.strategy.ts)
- [selector.ts](file://server/src/modules/book-generator/strategies/selector.ts)
- [types.ts](file://server/src/modules/book-generator/strategies/types.ts)
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.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)
- [README.md](file://server/src/modules/book-generator/README.md)
- [book-generator-optimizations.ts](file://server/src/modules/book-generator/book-generator-optimizations.ts)
- [test_import.ts](file://server/src/modules/book-generator/test_import.ts)
- [strategy-compare.ts](file://server/src/modules/book-generator/test/strategy-compare.ts)
- [book-generator.types.ts](file://server/src/modules/book-generator/book-generator.types.ts)
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)
- [graph.ts](file://server/src/modules/book-generator/graph.ts)
- [stage-manager.ts](file://server/src/modules/book-generator/stage-manager.ts)
- [utils.ts](file://server/src/modules/book-generator/utils.ts)
- [langgraph-controller.ts](file://server/src/modules/book-generator/langgraph-controller.ts)
- [langgraph-types.ts](file://server/src/modules/book-generator/langgraph-types.ts)
- [book-type-config.ts](file://server/src/modules/book-generator/book-type-config.ts)
- [book-tools.ts](file://server/src/modules/services/llm/book-tools.ts)
- [index.ts](file://server/src/modules/services/llm/index.ts)
- [index.ts](file://server/src/config/index.ts)
- [models.json](file://server/src/config/models.json)
- [models-validator.ts](file://server/src/config/models-validator.ts)
- [index.js](file://deploy-package/server/config/index.js)
- [models.json](file://deploy-package/server/config/models.json)
- [models-validator.js](file://deploy-package/server/config/models-validator.js)
- [templates.controller.js](file://deploy-package/server/modules/templates/templates.controller.js)
- [templates.service.js](file://deploy-package/server/modules/templates/templates.service.js)
</cite>

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

## 引言
本文件面向“提示词工程与模板系统”的技术文档，聚焦于提示词设计原则、模板构建方法、上下文管理策略，并深入解析以下关键模块：
- 提示词构建器：builder.ts 中的提示词构建逻辑
- 模板系统：templates.ts 中的模板定义与复用机制
- 解析器体系：outline.parser.ts、section.parser.ts、subsection.parser.ts 的解析策略
- 策略与执行：多种生成策略（一次性大纲、逐章、顺序）及选择器
- 上下文与优化：上下文压缩、阶段化处理、LangGraph 集成与工具链

本文件同时提供提示词优化技巧、多轮对话管理、上下文压缩方法、实际提示词示例与效果对比分析，以及最佳实践指导。

## 项目结构
提示词工程与模板系统位于服务端模块 book-generator 下，围绕“提示词构建 → 解析与分层 → 策略执行 → 结果产出”的主干流程展开；前端通过模板控制器与服务进行交互，后端通过 LLM 服务与配置中心协同。

```mermaid
graph TB
subgraph "提示词与模板"
B["builder.ts<br/>提示词构建器"]
T["templates.ts<br/>模板系统"]
end
subgraph "解析器"
OP["outline.parser.ts<br/>大纲解析"]
SP["section.parser.ts<br/>章节解析"]
SUBP["subsection.parser.ts<br/>小节解析"]
end
subgraph "策略与执行"
SEL["selector.ts<br/>策略选择器"]
OS["one-step-outline.strategy.ts"]
PCS["per-chapter.strategy.ts"]
SEQ["sequential.strategy.ts"]
SVC["book-generator.service.ts"]
CTRL["book-generator.controller.ts"]
AICTRL["ai-generate-controller.ts"]
end
subgraph "上下文与优化"
STAGE["stage-manager.ts"]
STORE["book-generator.store.ts"]
GRAPH["graph.ts"]
OPT["book-generator-optimizations.ts"]
end
subgraph "LLM与配置"
LLMIDX["services/llm/index.ts"]
CFG["config/index.ts<br/>models.json"]
end
B --> T
T --> OP
OP --> SP
SP --> SUBP
SUBP --> SEL
SEL --> OS
SEL --> PCS
SEL --> SEQ
OS --> SVC
PCS --> SVC
SEQ --> SVC
SVC --> STAGE
STAGE --> STORE
STAGE --> GRAPH
SVC --> LLMIDX
LLMIDX --> CFG
```

图示来源
- [builder.ts](file://server/src/modules/book-generator/prompts/builder.ts)
- [templates.ts](file://server/src/modules/book-generator/prompts/templates.ts)
- [outline.parser.ts](file://server/src/modules/book-generator/parsers/outline.parser.ts)
- [section.parser.ts](file://server/src/modules/book-generator/parsers/section.parser.ts)
- [subsection.parser.ts](file://server/src/modules/book-generator/parsers/subsection.parser.ts)
- [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)
- [sequential.strategy.ts](file://server/src/modules/book-generator/strategies/sequential.strategy.ts)
- [selector.ts](file://server/src/modules/book-generator/strategies/selector.ts)
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.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)
- [stage-manager.ts](file://server/src/modules/book-generator/stage-manager.ts)
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)
- [graph.ts](file://server/src/modules/book-generator/graph.ts)
- [book-generator-optimizations.ts](file://server/src/modules/book-generator/book-generator-optimizations.ts)
- [index.ts](file://server/src/modules/services/llm/index.ts)
- [index.ts](file://server/src/config/index.ts)

章节来源
- [README.md](file://server/src/modules/book-generator/README.md)
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.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)

## 核心组件
- 提示词构建器（builder.ts）
  - 职责：基于模板与上下文动态拼装提示词，支持变量注入、格式化与校验
  - 关键点：提示词片段组合、占位符替换、安全校验、可读性与可维护性
- 模板系统（templates.ts）
  - 职责：集中管理提示词模板，提供模板检索、参数化与复用
  - 关键点：模板分类、参数约束、版本化与回滚策略
- 解析器（outline/section/subsection.parser.ts）
  - 职责：将原始输入拆解为大纲、章节、小节等层级结构，支撑后续策略执行
  - 关键点：层级判定、边界识别、容错与回退
- 策略与选择器（selector.ts 及各 strategy）
  - 职责：根据输入特征与业务目标选择最优生成策略（一次性/逐章/顺序），并驱动执行
  - 关键点：策略评估指标、切换条件、降级与补偿
- 执行与上下文（service/controller/阶段管理）
  - 职责：编排提示词构建、调用 LLM、管理上下文与中间态、持久化与可视化
  - 关键点：阶段化推进、上下文压缩、错误恢复、可观测性

章节来源
- [builder.ts](file://server/src/modules/book-generator/prompts/builder.ts)
- [templates.ts](file://server/src/modules/book-generator/prompts/templates.ts)
- [outline.parser.ts](file://server/src/modules/book-generator/parsers/outline.parser.ts)
- [section.parser.ts](file://server/src/modules/book-generator/parsers/section.parser.ts)
- [subsection.parser.ts](file://server/src/modules/book-generator/parsers/subsection.parser.ts)
- [selector.ts](file://server/src/modules/book-generator/strategies/selector.ts)
- [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)
- [sequential.strategy.ts](file://server/src/modules/book-generator/strategies/sequential.strategy.ts)
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.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)

## 架构总览
提示词工程与模板系统的整体流程如下：

```mermaid
sequenceDiagram
participant FE as "前端"
participant CTRL as "book-generator.controller.ts"
participant SVC as "book-generator.service.ts"
participant B as "builder.ts"
participant T as "templates.ts"
participant P as "解析器(大纲/章节/小节)"
participant STR as "策略选择器(selector.ts)"
participant LLM as "LLM服务(index.ts)"
participant STAGE as "stage-manager.ts/store.ts"
FE->>CTRL : 发起生成请求(含输入/参数)
CTRL->>SVC : 触发生成流程
SVC->>B : 请求构建提示词(模板+上下文)
B->>T : 加载模板并注入参数
T-->>B : 返回模板实例
B-->>SVC : 返回最终提示词
SVC->>P : 解析输入为层级结构
P-->>SVC : 返回结构化大纲/章节/小节
SVC->>STR : 依据输入特征选择策略
STR-->>SVC : 返回选定策略
SVC->>LLM : 调用模型生成内容
LLM-->>SVC : 返回生成结果
SVC->>STAGE : 写入阶段状态/上下文
SVC-->>CTRL : 返回阶段性结果
CTRL-->>FE : 返回进度/结果
```

图示来源
- [book-generator.controller.ts](file://server/src/modules/book-generator/book-generator.controller.ts)
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.ts)
- [builder.ts](file://server/src/modules/book-generator/prompts/builder.ts)
- [templates.ts](file://server/src/modules/book-generator/prompts/templates.ts)
- [outline.parser.ts](file://server/src/modules/book-generator/parsers/outline.parser.ts)
- [section.parser.ts](file://server/src/modules/book-generator/parsers/section.parser.ts)
- [subsection.parser.ts](file://server/src/modules/book-generator/parsers/subsection.parser.ts)
- [selector.ts](file://server/src/modules/book-generator/strategies/selector.ts)
- [stage-manager.ts](file://server/src/modules/book-generator/stage-manager.ts)
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)
- [index.ts](file://server/src/modules/services/llm/index.ts)

## 详细组件分析

### 提示词构建器（builder.ts）
- 设计原则
  - 可组合性：将提示词拆分为多个片段，按需拼接
  - 参数化：通过占位符与上下文映射实现模板复用
  - 安全性：对注入参数进行白名单与长度限制，避免越界与注入风险
  - 可观测性：保留原始模板与最终提示词，便于调试与审计
- 关键流程
  - 加载模板：从 templates.ts 获取模板定义
  - 注入上下文：将输入参数、历史上下文、结构化数据注入模板
  - 格式化与校验：统一换行、截断与长度校验
  - 输出最终提示词：返回可用于 LLM 调用的字符串
- 优化要点
  - 模板缓存：热点模板预热，减少重复加载
  - 分块策略：超长提示词分块处理，结合上下文压缩
  - 回退机制：模板缺失或参数异常时的默认兜底

章节来源
- [builder.ts](file://server/src/modules/book-generator/prompts/builder.ts)
- [templates.ts](file://server/src/modules/book-generator/prompts/templates.ts)

### 模板系统（templates.ts）
- 组织方式
  - 模板分类：按用途（大纲、章节、小节、提示词片段）划分
  - 参数约束：定义必填/可选参数与默认值，确保模板一致性
  - 版本化：支持模板版本与回滚，保障稳定性
- 使用模式
  - 单模板调用：直接传入参数渲染
  - 组合模板：将多个模板片段拼接，形成复合提示词
- 最佳实践
  - 明确模板职责边界，避免过度耦合
  - 为模板编写单元测试与回归用例
  - 对高频模板进行性能监控与优化

章节来源
- [templates.ts](file://server/src/modules/book-generator/prompts/templates.ts)

### 解析器体系（outline/section/subsection.parser.ts）
- 大纲解析（outline.parser.ts）
  - 目标：从输入中提取顶层结构与主题
  - 方法：基于标题层级、关键词识别与段落切分
  - 输出：结构化大纲节点（含标题、摘要、目标字数等）
- 章节解析（section.parser.ts）
  - 目标：将大纲细化为章节
  - 方法：识别章节标识、统计字数、估算子节点数量
  - 输出：章节节点集合（含子节点、预期字数）
- 小节解析（subsection.parser.ts）
  - 目标：进一步拆分子章节为小节
  - 方法：基于段落、标点与语义边界
  - 输出：小节节点集合（含正文、要点、示例等）
- 容错与回退
  - 当解析失败时，采用默认策略或降级方案
  - 对异常输入进行清洗与标准化

```mermaid
flowchart TD
Start(["开始"]) --> Detect["识别输入类型<br/>主题/关键词/结构化"]
Detect --> Outline["大纲解析<br/>outline.parser.ts"]
Outline --> Sections["章节解析<br/>section.parser.ts"]
Sections --> Subsections["小节解析<br/>subsection.parser.ts"]
Subsections --> Validate{"是否满足字数/层级要求？"}
Validate --> |是| Output["输出结构化节点"]
Validate --> |否| Fallback["回退/重试/人工干预"]
Fallback --> Output
```

图示来源
- [outline.parser.ts](file://server/src/modules/book-generator/parsers/outline.parser.ts)
- [section.parser.ts](file://server/src/modules/book-generator/parsers/section.parser.ts)
- [subsection.parser.ts](file://server/src/modules/book-generator/parsers/subsection.parser.ts)

章节来源
- [outline.parser.ts](file://server/src/modules/book-generator/parsers/outline.parser.ts)
- [section.parser.ts](file://server/src/modules/book-generator/parsers/section.parser.ts)
- [subsection.parser.ts](file://server/src/modules/book-generator/parsers/subsection.parser.ts)

### 策略与选择器（selector.ts 与各 strategy）
- 策略类型
  - 一次性生成（one-step-outline.strategy.ts）：适用于短文本或明确结构
  - 逐章生成（per-chapter.strategy.ts）：按章节独立生成，便于并行与质量控制
  - 顺序生成（sequential.strategy.ts）：严格顺序，保证上下文连贯性
- 选择器（selector.ts）
  - 输入：输入规模、结构复杂度、目标字数、历史上下文长度
  - 输出：最优策略与参数组合
- 执行流程
  - 选择策略 → 初始化阶段 → 逐步生成 → 上下文更新 → 结果汇总

```mermaid
classDiagram
class 策略选择器 {
+评估输入特征
+计算策略权重
+返回最优策略
}
class 一次性策略 {
+一次性生成大纲
}
class 逐章策略 {
+按章节生成
+并行/串行控制
}
class 顺序策略 {
+严格顺序
+上下文传递
}
策略选择器 --> 一次性策略
策略选择器 --> 逐章策略
策略选择器 --> 顺序策略
```

图示来源
- [selector.ts](file://server/src/modules/book-generator/strategies/selector.ts)
- [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)
- [sequential.strategy.ts](file://server/src/modules/book-generator/strategies/sequential.strategy.ts)

章节来源
- [selector.ts](file://server/src/modules/book-generator/strategies/selector.ts)
- [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)
- [sequential.strategy.ts](file://server/src/modules/book-generator/strategies/sequential.strategy.ts)

### 执行与上下文管理（service/controller/stage-manager/store）
- 服务编排（book-generator.service.ts）
  - 负责提示词构建、调用 LLM、解析结果、写入阶段状态
  - 管理上下文窗口与压缩策略
- 控制器（book-generator.controller.ts / ai-generate-controller.ts）
  - 接收前端请求，校验参数，调度服务层
  - 提供进度查询与结果返回
- 阶段管理（stage-manager.ts / store.ts）
  - 将生成过程拆分为多个阶段，便于断点续跑与可视化
  - 存储中间态，支持回溯与重试
- 图谱与工具（graph.ts / book-tools.ts）
  - 通过 LangGraph 构建生成图谱，串联节点与工具
  - 工具链用于外部能力扩展（如查询、校验）

章节来源
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.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)
- [stage-manager.ts](file://server/src/modules/book-generator/stage-manager.ts)
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)
- [graph.ts](file://server/src/modules/book-generator/graph.ts)
- [book-tools.ts](file://server/src/modules/services/llm/book-tools.ts)

## 依赖关系分析
- 模块内聚与耦合
  - builder.ts 与 templates.ts 高内聚，通过接口解耦
  - 解析器与策略层通过统一的数据结构衔接，降低耦合
  - 服务层作为编排中枢，向上承接控制器，向下连接 LLM 与存储
- 外部依赖
  - LLM 服务：统一入口与模型配置
  - 配置中心：模型清单与验证规则
  - 前端模板控制器与服务：模板检索与应用

```mermaid
graph LR
TPL["templates.ts"] --> BLD["builder.ts"]
BLD --> SVC["book-generator.service.ts"]
PARSER["解析器层"] --> SVC
STRAT["策略层"] --> SVC
SVC --> LLM["services/llm/index.ts"]
LLM --> CFG["config/index.ts"]
FE_CTRL["templates.controller.js"] --> FE_SRV["templates.service.js"]
FE_SRV --> TPL
```

图示来源
- [templates.ts](file://server/src/modules/book-generator/prompts/templates.ts)
- [builder.ts](file://server/src/modules/book-generator/prompts/builder.ts)
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.ts)
- [index.ts](file://server/src/modules/services/llm/index.ts)
- [index.ts](file://server/src/config/index.ts)
- [templates.controller.js](file://deploy-package/server/modules/templates/templates.controller.js)
- [templates.service.js](file://deploy-package/server/modules/templates/templates.service.js)

章节来源
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.ts)
- [index.ts](file://server/src/modules/services/llm/index.ts)
- [index.ts](file://server/src/config/index.ts)
- [templates.controller.js](file://deploy-package/server/modules/templates/templates.controller.js)
- [templates.service.js](file://deploy-package/server/modules/templates/templates.service.js)

## 性能考量
- 提示词长度控制
  - 通过模板参数化与上下文压缩，避免超过模型上下文上限
  - 对超长输入采用分块与摘要策略
- 并行与顺序权衡
  - 逐章策略支持并行生成，提升吞吐
  - 顺序策略保证一致性，适用于强依赖场景
- 缓存与预热
  - 热门模板与提示词片段缓存
  - 预热常用模型与工具链
- 监控与告警
  - 关键指标：提示词长度、生成耗时、错误率、上下文命中率
  - 异常快速回退与降级策略

## 故障排查指南
- 常见问题
  - 提示词过长导致截断：检查模板参数与上下文长度，启用压缩
  - 解析失败：核对输入格式与解析器边界规则，必要时人工干预
  - 策略选择不当：调整评估权重与阈值，增加策略对比测试
  - LLM 调用失败：检查模型配置与限流策略，启用重试与熔断
- 调试手段
  - 启用详细日志与追踪 ID，定位具体环节
  - 使用阶段管理器查看中间态，复现问题
  - 对比不同策略与模板的输出差异，定位根因

章节来源
- [book-generator-optimizations.ts](file://server/src/modules/book-generator/book-generator-optimizations.ts)
- [stage-manager.ts](file://server/src/modules/book-generator/stage-manager.ts)
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)

## 结论
提示词工程与模板系统以“可组合、可复用、可演进”为核心目标，通过模板化与策略化实现高效稳定的生成流程。结合解析器的层级化处理、阶段化的上下文管理与 LangGraph 的图谱化编排，系统在复杂内容生成场景下具备良好的扩展性与鲁棒性。建议持续完善模板库、优化策略选择算法、加强监控与回退机制，以应对更广泛的业务需求。

## 附录

### 提示词设计原则与优化技巧
- 明确角色与目标：限定角色、设定目标、给出约束
- 分层提示：先总体后细节，先结构后内容
- 参数化与最小化：仅注入必要参数，避免冗余
- 可观测性：保留原始模板与最终提示词，便于审计与复现
- 多轮对话管理
  - 通过上下文窗口与摘要机制控制历史长度
  - 使用“总结上一轮要点”“请基于以上信息回答”等指令引导模型
- 上下文压缩方法
  - 关键句抽取、摘要生成、层级化裁剪
  - 基于重要度评分的动态截断

### 实际提示词示例与效果对比（示例路径）
- 示例A：一次性生成（适合短文本）
  - 路径参考：[one-step-outline.strategy.ts](file://server/src/modules/book-generator/strategies/one-step-outline.strategy.ts)
- 示例B：逐章生成（适合长文）
  - 路径参考：[per-chapter.strategy.ts](file://server/src/modules/book-generator/strategies/per-chapter.strategy.ts)
- 示例C：顺序生成（适合强连贯内容）
  - 路径参考：[sequential.strategy.ts](file://server/src/modules/book-generator/strategies/sequential.strategy.ts)

### 最佳实践清单
- 模板命名规范：清晰表达用途与适用范围
- 参数校验：必填项、取值范围、默认值
- 版本管理：变更记录与回滚预案
- 测试覆盖：单元测试、回归测试、策略对比测试
- 文档与知识沉淀：模板使用手册、常见问题解答