用途与实际影响
这项功能怎样使用
为什么需要它
有些转换器没有生成文件却返回成功；只检查目标是否存在，就可能把上一次 PDF 冒充本次成果。
举个实际例子
原来已有一份 PDF，这次转换器报错。脚本只清本次暂存文件，旧 PDF 保留，并返回真实错误。
最后我会得到什么
获得本次生成且可解析的 PDF，或者具体失败原因；不靠旧文件大小判成功。
正常时
新 PDF 真实生成、能打开且有页面，原文没有被改动后，才替换目标文件。
发现问题时
转换失败或新文件无效时保留旧 PDF，并报告这次没有交付。
入口不可用或证据不足时
转换器、输入文件或输出位置不可用时，在替换前停止。
从哪里开始
先运行 python tools/configure_converter.py --converter <converter.py> 记录兼容转换器，或本次在 export_pdf.py 指定 --converter；再选 Markdown、模式与输出。
需要准备什么
- 要导出的 Markdown
- 选定的版式与 PDF 目标
- 如尚未配置，指定已有兼容转换器
从开始到拿到结果
- 1
准备输入与转换器
核对原文、输出位置和转换器可运行。
- 2
先生成暂存结果
工具调用转换器后检查原文摘要未变、PDF 可解析且有页。
- 3
确认再替换
仅合格暂存结果替换目标文件；失败留下原文和旧交付物并说明原因。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
回归与本机三模式导出通过关键规则与设计选择
--converter > MD_PDF_TOOLKIT_CONVERTER > 本机 JSON；不猜默认打印器。
输出必须为 .pdf，不能等于源 Markdown 或转换器。
暂存文件名短且位于目标同目录，避免跨卷原子移动和长文件名问题。
本模块用到的名词
- 本次暂存
- 使用新路径，旧目标不能充当新输出证据。
- 摘要检查
- 发现原文发生变化，不能保证外部程序从未写过它。
专业定义
新 PDF 检查通过，才替换上一次成果
解决什么
源摘要变化时拒绝成功，但这是检测而不是对外部程序的写入隔离。
当前怎样实现
- configure_converter.py 原子保存 typora-theme-pack.local.v1；相对路径按配置目录解析。
- export_pdf.py 生成 profile CSS 临时文件，调用 sys.executable + converter，带 --input、--output、--css-file、--document-style-policy、--require-style 和可选 --expected-pages。
- 在外部执行前后核对源 SHA-256；成功后由 pypdf.PdfReader 解析实际 staged PDF，至少一页才 os.replace。finally 尝试清理本次 CSS 与 staged 文件，清理错误不覆盖原失败结果。
执行流程
- 1
校验输入输出与配置
- 2
计算源摘要并预约暂存 PDF
- 3
调用外部转换器
- 4
核对源摘要和 PDF 页数
- 5
替换目标并清理本次临时文件
边界
- 包不实现底层 PDF 排版；兼容引擎由用户既有配置提供。
- 不会自动恢复被其他程序修改的源文档。
失败与恢复
- 无输出、损坏 PDF、0 页或非零退出
- 保留旧目标并报告失败。
- 源摘要变化
- 拒绝交付，不把变动文件对应的 PDF 写成已验证。
真实入口
tools/export_pdf.py交付和校验
tools/configure_converter.py本机配置
tests/test_project.py失败路径与原件保全
如何验证
- 20 项测试覆盖旧 PDF 保留、损坏/0页拒绝和原子替换；实际三模式输出也已生成。
与其他模块的关系
连接选中的样式和外部引擎，负责这一份输出的交付判断。