audio_codebuddy/.qoder/repowiki/zh/content/核心模块/AI内容生成引擎/提示词工程与模板.md

提示词工程与模板

本文引用的文件

• builder.ts
• templates.ts
• outline.parser.ts
• section.parser.ts
• subsection.parser.ts
• one-step-outline.strategy.ts
• per-chapter.strategy.ts
• sequential.strategy.ts
• selector.ts
• types.ts
• book-generator.service.ts
• book-generator.controller.ts
• ai-generate-controller.ts
• README.md
• book-generator-optimizations.ts
• test_import.ts
• strategy-compare.ts
• book-generator.types.ts
• book-generator.store.ts
• graph.ts
• stage-manager.ts
• utils.ts
• langgraph-controller.ts
• langgraph-types.ts
• book-type-config.ts
• book-tools.ts
• index.ts
• index.ts
• models.json
• models-validator.ts
• index.js
• models.json
• models-validator.js
• templates.controller.js
• templates.service.js

目录

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 服务与配置中心协同。

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
• templates.ts
• outline.parser.ts
• section.parser.ts
• subsection.parser.ts
• one-step-outline.strategy.ts
• per-chapter.strategy.ts
• sequential.strategy.ts
• selector.ts
• book-generator.service.ts
• book-generator.controller.ts
• ai-generate-controller.ts
• stage-manager.ts
• book-generator.store.ts
• graph.ts
• book-generator-optimizations.ts
• index.ts
• index.ts

章节来源

• README.md
• book-generator.service.ts
• book-generator.controller.ts
• ai-generate-controller.ts

核心组件

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

章节来源

• builder.ts
• templates.ts
• outline.parser.ts
• section.parser.ts
• subsection.parser.ts
• selector.ts
• one-step-outline.strategy.ts
• per-chapter.strategy.ts
• sequential.strategy.ts
• book-generator.service.ts
• book-generator.controller.ts
• ai-generate-controller.ts

架构总览

提示词工程与模板系统的整体流程如下：

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
• book-generator.service.ts
• builder.ts
• templates.ts
• outline.parser.ts
• section.parser.ts
• subsection.parser.ts
• selector.ts
• stage-manager.ts
• book-generator.store.ts
• index.ts

详细组件分析

提示词构建器（builder.ts）

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

章节来源

• builder.ts
• templates.ts

模板系统（templates.ts）

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

章节来源

• templates.ts

解析器体系（outline/section/subsection.parser.ts）

• 大纲解析（outline.parser.ts）
  • 目标：从输入中提取顶层结构与主题
  • 方法：基于标题层级、关键词识别与段落切分
  • 输出：结构化大纲节点（含标题、摘要、目标字数等）
• 章节解析（section.parser.ts）
  • 目标：将大纲细化为章节
  • 方法：识别章节标识、统计字数、估算子节点数量
  • 输出：章节节点集合（含子节点、预期字数）
• 小节解析（subsection.parser.ts）
  • 目标：进一步拆分子章节为小节
  • 方法：基于段落、标点与语义边界
  • 输出：小节节点集合（含正文、要点、示例等）

• 容错与回退

  • 当解析失败时，采用默认策略或降级方案

  • 对异常输入进行清洗与标准化

    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
• section.parser.ts
• subsection.parser.ts

章节来源

• outline.parser.ts
• section.parser.ts
• subsection.parser.ts

策略与选择器（selector.ts 与各 strategy）

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

• 执行流程

  • 选择策略 → 初始化阶段 → 逐步生成 → 上下文更新 → 结果汇总

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

图示来源

• selector.ts
• one-step-outline.strategy.ts
• per-chapter.strategy.ts
• sequential.strategy.ts

章节来源

• selector.ts
• one-step-outline.strategy.ts
• per-chapter.strategy.ts
• 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
• book-generator.controller.ts
• ai-generate-controller.ts
• stage-manager.ts
• book-generator.store.ts
• graph.ts
• book-tools.ts

依赖关系分析

• 模块内聚与耦合
  • builder.ts 与 templates.ts 高内聚，通过接口解耦
  • 解析器与策略层通过统一的数据结构衔接，降低耦合
  • 服务层作为编排中枢，向上承接控制器，向下连接 LLM 与存储

• 外部依赖

  • LLM 服务：统一入口与模型配置
  • 配置中心：模型清单与验证规则

  • 前端模板控制器与服务：模板检索与应用

    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
• builder.ts
• book-generator.service.ts
• index.ts
• index.ts
• templates.controller.js
• templates.service.js

章节来源

• book-generator.service.ts
• index.ts
• index.ts
• templates.controller.js
• templates.service.js

性能考量

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

故障排查指南

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

章节来源

• book-generator-optimizations.ts
• stage-manager.ts
• book-generator.store.ts

结论

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

附录

提示词设计原则与优化技巧

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

实际提示词示例与效果对比（示例路径）

• 示例A：一次性生成（适合短文本）
  • 路径参考：one-step-outline.strategy.ts
• 示例B：逐章生成（适合长文）
  • 路径参考：per-chapter.strategy.ts
• 示例C：顺序生成（适合强连贯内容）
  • 路径参考：sequential.strategy.ts

最佳实践清单

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