pdf-to-html

PDF 转 HTML

将 PDF 转换为单个独立、易读的 HTML 文件——保留图片、表格、图表和阅读顺序——并可选择翻译，同时让每个图表都保持原位。

此流程为 提取 → 查看 →（翻译）→ 构建 → 验证。中间的“查看”和最后的“验证”步骤才是真正保证忠实度的关键：PDF 是一种版式，而不只是文本流，因此构建前要先阅读渲染后的页面，交付前再查看渲染后的 HTML。

此技能以 内联 方式运行（没有 context: fork）：翻译会编排动态工作流，而子 Agent 无法启动此工作流。

何时使用／何时不使用

• 当目标是以 HTML／网页形式阅读 PDF、将 PDF 转换为带样式的 HTML 文档，或在保留图表和表格的同时将 PDF 翻译成另一种语言时，使用此工具。
• 如果用户想要纯 Markdown 文本（不需要样式，图表可选），则改用 doc-to-markdown。
• 如果要进行反向转换（Markdown → PDF），则改用 pdf-creator。

它不会做什么

• 扫描件／纯图片 PDF（没有文本层）：先进行 OCR（例如使用 ocrmypdf），再使用此工具。
• 复杂的多列表格：单元格文本会保留且可读，但列对齐可能会被压平成文本流——PyMuPDF 会将表格读取为文本块，而非网格，因此网格线会消失。PDF 中以图片形式存在的表格会作为图片保留。如果表格的网格结构至关重要，请使用 doc-to-markdown（pandoc 会重建真正的表格），或单独转换该页面。
• 像素级精确复刻：输出是简洁的重排版，会保留图片和阅读顺序，但不是原始页面布局的 1:1 副本。
• 改写：此工具会翻译并重新排版；不会总结、添加 TL;DR 或发表编辑意见。忠实还原才是重点（见下文“忠实度”）。

依赖项

uv（使用内联依赖运行 Python）、Google Chrome 或 Chromium（用于视觉验证）。Python 包通过 uv run --with 获取：PyMuPDF、Pillow、numpy。除 Chrome 和 uv 外，无需预先安装其他内容。

工作流

复制此检查清单，并在操作过程中逐项勾选：

- [ ] 1. Extract structure + render pages   (extract_pdf.py)
- [ ] 2. Read pages/*.png — SEE the layout, find content vs decorative images
- [ ] 3. (only if translating) run the translation workflow
- [ ] 4. Build the single-file HTML          (build_html.py)
- [ ] 5. Verify visually                      (verify_render.py → Read every segment)
- [ ] 6. Deliver the .html

1. 提取

uv run --with pymupdf python scripts/extract_pdf.py input.pdf

此步骤会生成 input-build/，其中包含 structure.json（带字体大小的文本块，以及标记为 decorative 的图片块）、images/ 和 pages/（每页一个 PNG）。

2. 构建前先查看

阅读 input-build/pages/*.png。这一步不可省略：你需要查看实际版式，确认哪些图片是内容、哪些是装饰，并找出表格／图表。对于较长的 PDF，请阅读每一页；较短的 PDF 很快就能看完。这也有助于你充分理解文档，从而做好翻译。

3. 翻译（可选）

仅当用户要求翻译成其他语言时才执行。阅读 references/translation_workflow.md，并按其中说明操作：动态工作流会并行翻译各页面、为数据图表添加说明文字，并统一术语。它会生成两个叠加文件（units.json、caps.json），供第 4 步使用。不要对超过一页的内容进行内联手动翻译——工作流能保持术语一致，而且速度快得多。

4. 构建

# original-language HTML
uv run --with Pillow python scripts/build_html.py input-build/structure.json --out output.html

# translated HTML (overlays from step 3)
uv run --with Pillow python scripts/build_html.py input-build/structure.json --out output.html \
    --translation input-build/units.json --captions input-build/caps.json --lang zh-CN

build_html.py 采用数据驱动方式：根据字体大小推断标题级别（出现最频繁的字号为正文；更大的字号依次对应 h3／h2／h1），移除装饰图片，并将内容图片内联为压缩后的 base64 数据，从而生成单个可移植文件。它不会针对任何特定文档进行手动调整。如果某个 PDF 的结构特殊（例如多栏、侧边栏，或尺寸启发式判断错误的图表），请阅读脚本并进行调整——脚本很短，设计上就是供你按文档编辑的。

5. 进行视觉验证（必须）

uv run --with Pillow --with numpy python scripts/verify_render.py output.html

然后，逐一查看每个 seg-*.png 并检查：字体是否正常显示（没有方框乱码）、表格和图表是否被裁切、标题和列表是否显示正确、所有预期图片是否齐全。文本正确不代表渲染结果正确（failure_cases #7）。修复并重新验证，直到一切正常。

也可以快速进行结构交叉检查，但要正确统计出现次数： grep -o '<figure>' output.html | wc -l——不要使用 grep -c（failure_cases #1）。

6. 交付

交付单个 .html 文件。它是独立文件（图片已内嵌），双击即可打开，不会遗漏任何内容。

脚本

脚本	运行命令	用途
scripts/extract_pdf.py	uv run --with pymupdf	PDF → structure.json + images/ + 页面渲染图
scripts/build_html.py	uv run --with Pillow	structure.json（+ 可选的翻译/图片说明）→ 单文件 HTML
scripts/verify_render.py	uv run --with Pillow --with numpy	无头 Chrome 渲染 → 可读的 PNG 分段图

忠实度（翻译前阅读）

交付成果看起来很权威，因此内容错误比外观不佳更糟糕。不可妥协的规则，以及以往出错的具体方式，都列在 references/failure_cases.md 中。最容易出问题的一点是：绝不能擅自推断并翻译真实人物的姓名；所有数字和专有名词都必须原样照抄（failure_cases #6）。每次开始翻译前都要阅读该文件；每次运行前都要浏览一遍。

下一步

生成 HTML 后，建议自然的后续步骤：

Conversion complete: output.html (single self-contained file).

Options:
A) Make a PDF of it — run /daymade-docs:pdf-creator if you want a print/share copy (Recommended if they need to send it)
B) Extract the text as Markdown instead — run /daymade-docs:doc-to-markdown (if they wanted editable text, not a reading page)
C) No thanks — the HTML is what I wanted