Markdown、HTML 和 PPT 如何稳定交付，真正困难的通常不是完成一次 API 调用，而是让结果可以校验、失败可以定位、后续能够回到原始证据。本文围绕"如何把 Markdown、HTML 和 PPT 转换任务设计成可重试、可验收的文档交付流水线"给出一套可以直接落到任务状态和数据契约上的实现方式。
问题与结果
源文件、转换参数、产物哈希和交付状态统一记录，失败重试不会产生无法区分的重复文件。
最终交付不是一段不可追溯的模型回答，而是一组带来源、版本、状态和失败记录的数据。这样既方便接入后续系统，也能在接口、页面或模型输出变化时定位问题。
适用场景
- 技术文档批量导出
- 运营内容生成 PDF 或 Word
- 演示文稿归档和图片化
实现前先确定边界
- 输入文件与转换参数共同决定幂等键
- 转换成功后还要校验文件类型、大小和页数
- 交付记录只能引用已验收产物
可验证工作流
API 编排与职责
| 输入或目标 | 接口 | 请求方式 | 用途 |
|---|---|---|---|
| Markdown 到 PDF | Markdown 转 PDF | POST | 把技术文档、周报、说明页导出为 PDF |
| HTML 到 PDF | HTML/URL 转 PDF | POST | 把网页或 HTML 内容导出为 PDF |
| HTML 到 Word | HTML 转 Word | POST | 生成可编辑 Word 文档 |
| PPT 到 PDF | PPT 转高精度 PDF | POST | 生成演示材料归档版本 |
| PPT 到图片 | PPT 转高精度图片 | POST | 生成封面图、缩略图或预览图 |
最小可运行实现
bash
curl -X POST "https://api.gugudata.com/imagerecognition/markdown2pdf" \
-H "Content-Type: application/json" \
-d '{
"appkey": "YOUR_APPKEY",
"content": "# 发布草稿\n\n这是一篇准备导出的技术文章。"
}'
bash
curl -X POST "https://api.gugudata.com/imagerecognition/ppt-to-pdf?appkey=YOUR_APPKEY" \
-F "file=@./deck.pptx"
bash
curl -X POST "https://api.gugudata.com/imagerecognition/ppt-to-images?appkey=YOUR_APPKEY&scale_factor=2" \
-F "file=@./deck.pptx"应用侧可以按目标格式选择接口：
python
def choose_conversion_endpoint(source_type: str, target_type: str) -> str:
"""Choose a document conversion endpoint."""
if source_type == "markdown" and target_type == "pdf":
return "https://api.gugudata.com/imagerecognition/markdown2pdf"
if source_type == "ppt" and target_type == "pdf":
return "https://api.gugudata.com/imagerecognition/ppt-to-pdf"
if source_type == "ppt" and target_type == "images":
return "https://api.gugudata.com/imagerecognition/ppt-to-images"
raise ValueError("Unsupported conversion target")发布记录结构
| 字段 | 说明 |
|---|---|
| source_id | 原始内容 ID |
| source_type | Markdown、HTML、URL 或 PPT |
| target_type | PDF、Word、图片等目标格式 |
| output_url | 转换结果地址或文件记录 |
| generated_at | 转换时间 |
| publish_status | 待审核、已发布或失败 |
失败分类与降级
文件格式错误、文件过大或转换失败时，Agent 应停止发布流程，并把失败原因写入发布记录。对于重复发布任务，建议用 source_id + target_type 做幂等控制，避免同一篇内容生成多个冲突版本。
工程化注意事项
- 转换任务适合放到后台队列，避免用户请求长时间等待。
- 发布页面只展示业务结果，例如下载链接、预览图和更新时间。
- APPKEY 保存在服务端，不要放进 Markdown 文件或前端代码。
- 对输出文件设置访问权限和过期策略，避免内部资料被误公开。
数据契约与留痕
建议至少保存以下字段；真实项目可以继续拆分，但不要删除来源、版本和状态信息。
| 字段 | 作用 |
|---|---|
job_id |
稳定业务标识，用于关联记录并避免名称冲突 |
input_hash |
内容哈希，用于完整性校验、版本识别和去重 |
conversion_type |
规则、输入或产物版本，变更时保留旧版本 |
options |
业务数据字段，保存时记录来源、口径和缺失状态 |
output_hash |
内容哈希，用于完整性校验、版本识别和去重 |
page_count |
业务数据字段，保存时记录来源、口径和缺失状态 |
delivery_status |
显式状态或结果，禁止用空值代替失败 |
所有派生结果都应带生成时间和输入版本。发生重试时新增尝试记录，不要覆盖最后一次失败，以免排查时只剩"最终成功"而看不到中间问题。
验收清单
- 重复请求不会覆盖不同版本
- 空文件和错误 MIME 类型会被拒绝
- 产物可追溯到源文件和参数
能力边界
格式转换不保证复杂排版、字体和交互元素完全一致，关键文档仍需要视觉验收。
示例中的 YOUR_APPKEY 仅为占位符。真实密钥只能放在服务端环境变量或密钥管理系统中，不应进入前端、文章、日志或版本库。