1实现原理 · 为什么它能做到

管线是 extract → look → (translate) → build → verify，中间『看』与结尾『验』被定为忠实度的真正来源——PDF 是版式不是文本流。

daymade-docs/pdf-to-html/SKILL.md

The pipeline is **extract → look → (translate) → build → verify**. The middle "look" and final "verify" steps are where faithfulness actually comes from: a PDF is a layout, not just a text stream, so you read the rendered pages before building and the rendered HTML before delivering.

工作流节把它转成可勾选 checklist（1.提取 2.读页 PNG 3.可选翻译 4.构建 5.视觉验证 6.交付）。

extract_pdf.py 产出可复核中间态：structure.json（每页文本块带 bbox+最大字号，图片块带 decorative 标记）+ images/ + 每页渲染 PNG，阅读顺序沿用 PyMuPDF 的 get_text('dict') 块序。

daymade-docs/pdf-to-html/scripts/extract_pdf.py

The point of a separate extraction step is a *verifiable intermediate output*: structure.json is the plan. Inspect it (and the rendered page PNGs) before building, instead of going PDF -> HTML in one opaque jump.

decorative 判定=字节数 <3000 或同一 bbox 出现在 >半数页面（页眉/页脚 logo）——启发式标标记、由 build 决定去留。

build_html.py 是数据驱动通用构建器：从字号统计推断标题层级（最常见字号=正文，更大逐级升 h3/h2/h1），去掉 decorative 图，内容图压成 base64 内联——单文件可双击打开。

daymade-docs/pdf-to-html/SKILL.md

`build_html.py` is **data-driven**: it infers heading levels from font size (most common size = body; larger steps up to h3/h2/h1), drops decorative images, and inlines content images as compressed base64 → one portable file. It is not hand-tuned to any document.

宽图 >1400px 缩小；宽幅照片转 JPEG、线图保 PNG（PHOTO_WIDTH_THRESHOLD=1000/JPEG_QUALITY=82）；独特版式允许读脚本按文档调。

翻译分支不走『整文机器翻译』，而是 agent 按 references/translation_workflow.md 用 Dynamic Workflow 并行翻页、图表图注单独成文、术语统一，产出 units.json/caps.json 两个 overlay 交给 build 消费。

daymade-docs/pdf-to-html/SKILL.md

It produces two overlay files (`units.json`, `caps.json`) that step 4 consumes. **Do not** hand-translate inline for anything longer than a page — the workflow keeps terminology consistent and is far faster.

overlay 文本约定（空行=段、"- "=列表、"## "=小标题）使翻译文本也能被排版；原文无这些标记则按普通段落流动。

强制视觉验证：verify_render.py 用 headless Chrome 截图并按 ~2600px 切片（先 1x 探真实内容高、再选最大 device-scale-factor 避开 16384px 截图上限），agent 必须逐张 Read seg-*.png。

daymade-docs/pdf-to-html/SKILL.md

```bash uv run --with Pillow --with numpy python scripts/verify_render.py output.html ``` Then **Read every `seg-*.png`** and check: fonts render (no tofu boxes), no clipped tables/figures, headings/lists look right, all expected images present.

SKILL 提醒 grep 数 <figure> 要用 -o | wc -l 而不是 grep -c（failure_cases #1）；文本对 ≠ 渲染对。

忠实度铁律写在 references/failure_cases.md：绝不给人名/专名推断翻译、每个数字/专名逐字照抄（failure_cases #6），翻译前必读。

daymade-docs/pdf-to-html/SKILL.md

The one that bites hardest: **never give a real person an inferred translated name, and copy every number/proper-noun verbatim** (failure_cases #6). Read that file before any translation run; skim it before any run.

能力边界也划清：扫描件要先 OCR、多栏表格会摊平、不做像素级复制、不做 TL;DR——『faithfulness is the point』。

2核心能力

01PDF → 单个自包含可读 HTML（图片/表格/图表/阅读序保留，base64 内联）

02从字号推断标题层级、滤装饰图、压缩内联（数据驱动，不按文档手调）

03PDF → 另一种语言（保留全部图与表；overlay 驱动 + 术语一致性工作流）

04结构中间态可检：structure.json + 每页 PNG（先看版式再构建）

05headless Chrome 视觉回归：逐段 PNG 切片验证（字体/裁切/图全）

06能力边界管理：扫描件/多栏表格/像素级仿真的已知取舍

3外部依赖

Kind	Dependency / Endpoint
package	PyMuPDF (fitz)（extract_pdf.py，uv run --with pymupdf）
cli	Google Chrome / Chromium（headless 视觉验证）
package	Pillow / numpy（build 与 verify，uv --with）

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: python extract_pdf.py / build_html.py / verify_render.py（本地解析/构建）
外部端点: 将本地内容或会话向第三方云存储外发
本地工作目录: 文件读写与工件输出: input-build/（structure.json、images/、pages/ 每页 PNG）

审计说明： 。纯本地 Python + 本地 Chrome 渲染：运行期零网络外发（verify 甚至显式 --no-proxy-server）、零凭证读取、无删除操作；写出的仅是构建目录与输出 HTML。注意：首次 uv 拉取 PyPI 包为预置动作。

5第二遍独立确认

[ok] extract→look→build→verify 管线 — SKILL 三步命令与三个脚本一一对应；structure.json 字段（bbox/字号/decorative）在 extract_pdf.py 实现。
[ok] 字号推断标题层级 — build_html.py 从 font size 推断 h3/h2/h1 的逻辑在 docstring 与代码中均有（'larger sizes step up to h3/h2/h1'）。
[ok] base64 内联单文件 — build_html.py data_uri()：压缩→JPEG/PNG→base64；'single portable .html you can double-click' 相符。
[ok] decorative 判定启发式 — extract_pdf.py：DECORATIVE_MAX_BYTES=3000 + bbox 重复 > 半数页面（max(2, npages//2)）。
[ok] 强制视觉验证 headless Chrome 分片 — verify_render.py：1x 探高 + device-scale-factor 选择 + SEGMENT_PHYSICAL 分片；SKILL 要求 Read every seg-*.png。
[ok] 翻译 overlay 机制 — translation_workflow.md 存在且描述 units.json/caps.json 产出；build_html.py 接受 --translation/--captions 参数。
[ok] 无网络外发/转义防注入 — 三脚本无 requests/urllib/http；build_html.py md() 对段落文本 html.escape；--no-proxy-server 防代理泄漏。
[ok] 元数据 — GitHub API：MIT / 1385 stars / pushed 2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678。

6结论

可读 HTML 重排 + 图/表全保 + 单文件交付，是『读 PDF』场景的最短路径；翻译分支连图表图注都不丢。

视觉验证是强制的、机制化的（Chrome 分片 PNG + 逐张 Read），不是口头建议。

数据驱动构建器不按文档硬编码，异常版式还允许按文档改短脚本。

失败案例与忠实度铁律（专名不推断、数字照抄）文档化，防『看着权威实则编造』。

适合： 适合『要把 PDF 变成手机/网页上好读的单文件、且图表不能丢』的场景（报告转网页版、PDF 中文翻译件、课件 HTML）；要求装 uv + Chrome 并接受『先看页再构建、再看渲染再交付』的两道人工目检。

不适合： 不适合需要可编辑文本的场景（应选 doc-to-markdown）；不适合像素级 PDF 仿件/表格网格必须保留的场景；不适合无文本层扫描件（先 OCR）；不适合翻译后要保证零排版走样的用户。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload pdf-to-html.tar.gz

sha256: a8f3ffec2f8cdcaa…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.