1仕組みと動作原理
パイプラインは extract → look → (translate) → build → verify で構成され、中間の「確認（look）」と末尾の「検証（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.
ワークフロー節でチェック可能なリストに落とし込まれています（1. 抽出、2. ページPNGの確認、3. 任意での翻訳、4. ビルド、5. 視覚検証、6. 納品）。
extract_pdf.py は再確認可能な中間状態を出力します：structure.json（各ページのテキストブロックとbbox・最大フォントサイズ、装飾画像フラグ付きの画像ブロック）+ 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に出現（ヘッダー/フッターのロゴなど）。ヒューリスティックにフラグ付けされ、残すかどうかは build 側で決定されます。
build_html.py はデータ駆動型の汎用ビルダーです。フォントサイズの統計から見出しレベルを推定（最頻サイズ＝本文、それより大きいものを順次 h3/h2/h1 に昇格）、装飾画像を除去し、コンテンツ画像を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）。特殊なレイアウトの場合はスクリプトをドキュメントごとに調整可能です。
翻訳ブランチは「全文機械翻訳」を行わず、references/translation_workflow.md に従いエージェントが Dynamic Workflow でページ並行翻訳、図表・キャプションの個別処理、用語統一を行い、build に渡す2つのオーバーレイ（units.json/caps.json）を生成します。
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.
オーバーレイのテキスト規則（空行＝段落、"- "＝リスト、"## "＝小見出し）により翻訳後テキストも整形されます。原文にこれらの記号がない場合は通常の段落として流し込まれます。
強制的な視覚検証：verify_render.py はヘッドレスChromeでスクリーンショットを取得し、約2600pxごとにスライスします（16384pxの制限を回避するため、まず1倍で実際の高さを計測し、最大device-scale-factorを選択）。エージェントは各 seg-*.png を Read で確認する必要があります。
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内の注意点として、<figure> のカウントには grep -c ではなく -o | wc -l を使用する必要があります（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 → 他言語（すべての図表を保持、オーバーレイ駆動＋用語統一ワークフロー）
04検査可能な構造中間状態：structure.json ＋ 各ページPNG（レイアウトを確認してからビルド）
05ヘッドレス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結論
最適な用途： 「PDFを図表を崩すことなく、スマホやWeb上で読みやすい単一ファイルに変換したい」ケース（レポートのWeb版化、PDFの日本語訳作成、講義資料のHTML化など）に最適です。uv と Chrome がインストールされていること、および「ビルド前のページ確認」「納品前のレンダリング確認」という2段階の目視検査フローを受け入れられることが前提となります。
不向きな用途： 編集可能なテキストが必要なケース（doc-to-markdown を推奨）；ピクセル単位でのPDF完全複製や厳密な表の罫線保持が必要なケース；テキスト層のないスキャン文書（先にOCRが必要）；翻訳後に一切のレイアウト崩れを許容しないユーザーには適していません。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload pdf-to-html.tar.gz
sha256:
Option B · Copy Guide for Agenta8f3ffec2f8cdcaa…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.