教学文档自动生成系统 开发复盘

背景

这个项目不是“写一篇文章”工具，而是“稳定交付文档产物”的流水线工具。需求来自实际场景：需要持续产出长文，并且要直接导出结构化 PDF，不能每次都手工整理目录、样式和版式。

技术选型

后端主语言选 Python，原因是生态完整且适合快速组装多阶段任务。渲染层选 ReportLab，是因为它在可控排版和中文字体处理上更稳定，能覆盖目录、页码、章节样式、代码块等出版相关能力。模型接入采用 OpenAI-Compatible 抽象，便于切换供应商并统一调用。

实现过程

流程层面采用 5 层管道：信息采集、内容规划、分段生成、风格重写、组装质检。CLI 入口负责把 topic、manifest、模板、渲染参数统一注入到 DocPipeline。在导出侧，Markdown 是中间事实源，PDF 渲染器在此基础上追加目录、书签、章节视觉元素和页眉页脚。

遇到的问题

最大问题是上游模型偶发 504 与连接超时，导致任务反复重试、耗时失控。修复策略是引入降级状态与快速失败，让系统尽快进入 fallback 分支，优先保证“流程完成”。另一个问题是 PDF 目录与正文边界处理，早期逻辑会误切正文，后续通过修正 TOC 剥离与书签注册后恢复稳定。

总结

这次迭代的关键收获是：内容系统不能只优化“正常路径质量”，更要先保证“异常路径可收敛”。当系统具备稳定完成能力后，再去持续提升文本质量与视觉质量，整体收益更高，也更适合真实生产环境。