pdf-to-markdown

PDF から Markdown への変換

PDF を視覚的な基準として維持しながら、検証済みの Markdown 版を作成します。既定では report.pdf と report.md を使用します。ユーザーが用途を指定しない限り、パーサーの JSON、座標、抽出したアセット、チャンクは保持しないでください。

安全に変換する

1. 各ソース PDF と出力先のパスを特定します。複数の PDF がある場合は、結果を個別に検証できるよう、一度に 1 つずつ処理します。

2. 出力先にファイルが存在する場合、そのファイルを置き換えることをユーザーが明示的に許可した場合に限り、--overwrite を使用します。許可がない場合は、変換を開始する前に停止してください。別の出力先を独自に決めないでください。別のパスを使用するのは、ユーザーが選択または承認した場合に限ります。

3. xberg 実行ファイルがあるか確認します。ない場合は、ホストプラットフォーム向けの現行の公式インストール方法を特定し、該当するユーザー承認があればそれに従い、承認がない場合に限り承認を求めます。その承認を超えて、インストールスクリプト、パッケージマネージャー、モデルの事前ダウンロードを実行しないでください。

4. この SKILL.md を基準に scripts/convert_pdf.py の場所を特定し、次を実行します。

   python3 scripts/convert_pdf.py /absolute/path/report.pdf
   

   このラッパーは report.md をアトミックに書き込み、PDF を保持し、空または構造に一貫性のない出力を拒否し、シェルを呼び出しません。すべての物理ページを検証できるよう Xberg に JSON を要求しますが、公開するのは Xberg の文書全体の Markdown のみで、パーサーの JSON は保持しません。

   ページマーカーを有効にすると、ラッパーは --config-json を通じてランダムな非公開マーカーも渡し、後からその非公開マーカーだけを ` に変換します。直接フォールバックする場合は、検証時に公開ページコメントを使わず、同等に衝突しにくい非公開マーカーを使用する必要があります。

   ラッパーは、Xberg のページレコードが連続した 1 始まりの順序を形成し、宣言されたページ数と一致することを検証します。Xberg が空白と判定したページのマーカーを省略した場合、ページメタデータからそのマーカーを復元し、Xberg の Markdown 本文は変更せずに保持します。マーカーとページメタデータを整合させられない場合、公開を拒否します。ページごとの Markdown を連結して文書を再構築しないでください。リストがリセットされたり、ページ境界をまたぐ構造が損なわれたりする可能性があります。最終成果物の作成時に、ラッパーをシェルへの直接リダイレクトに置き換えないでください。

5. スキャンされた韓国語のページを含む PDF には、--korean-ocr を追加します。これにより韓国語を明示的に選択して PaddleOCR を使用し、スキャンと判定されたページだけを OCR にかけ、それ以外のページではネイティブテキストを保持します。

   python3 scripts/convert_pdf.py /absolute/path/report.pdf --korean-ocr
   

   PaddleOCR を初めて使用する際は、要求された変換の一環としてモデルがダウンロードされる場合があります。現在の環境でネットワークの利用やモデルの保存が大きな影響を及ぼす場合は、開始前にユーザーへ伝えてください。

言語が韓国語であるという理由だけで、デジタル生成された PDF を OCR にかけないでください。文書全体が画像のみで構成されている場合、またはテキストレイヤーが明らかに破損している場合に限り、--force-ocr を使用します。韓国語の文書には、これと --korean-ocr を組み合わせてください。

Python が利用できず Xberg は利用できる場合は、scripts/convert_pdf.py を調べ、利用可能な実行手段でコマンドの構成と検証を再現し、上書き防止、一時出力、空でない結果、アトミックな最終処理について同じ保証を維持します。これらの保証を維持できない場合は停止し、利用できない機能を報告してください。

検証とエスカレーション

変換のたびに、次の手順を実施します。

1. Markdown の冒頭、中ほど、末尾を確認します。見出し、段落の順序、表、リスト、コード、想定されるハングル、数値、日付、ページの欠落、不審な繰り返し、文字化け、不自然な密度の変化を確認してください。

2. ラッパーの検証サマリーを読みます。物理ページ数、空白でないページ数、空白ページ数が報告され、該当する場合は復元された空白ページマーカーの数も報告されます。PDF の検査機能が利用できる場合は、その合計を独立して取得した PDF のページ数と比較してください。空白ページにテキストが含まれないことは正当な場合がありますが、--no-page-markers が指定されていない限り、最終的な Markdown にはそのページのマーカーが必要です。 pdf_oxide の辞書をストリームとして扱う警告が繰り返し発生した場合、詳細をすべて出力する代わりに要約されます。これは、不正または特殊な PDF オブジェクトが空のストリームとして扱われたことを意味するため、忠実性に不確実さがある場合は、該当箇所の前後を目視で確認してください。ラッパーは、Xberg の構造化処理に関する警告も出力を制限して報告します。ページまたはパイプライン固有の忠実性リスクとして確認してください。

3. 通常の抽出で読み取り順序、見出し、表、リスト、図の配置が失われる場合は、--layout を指定して一時的な比較ファイルに再実行します。

   python3 scripts/convert_pdf.py /absolute/path/report.pdf \
     --output /absolute/path/report.layout.md \
     --layout
   

   これにより、通常の Xberg コマンドに --layout --layout-strategy auto --use-layout-for-markdown が追加されます。

   内容の忠実性を比較したうえで、ユーザーから上書きの許可を得ている場合に限り、意図した出力を置き換えてください。出力が大きいからといって、品質が高いと決めつけないでください。レイアウト抽出で ONNX Runtime API の不一致が報告された場合は、後続のワーカーメッセージに Mutex poisoned と表示されても、それを原因として扱ってください。Windows では、古い C:\Windows\System32\onnxruntime.dll が読み込まれていないか確認してください。互換性のあるランタイムを ORT_DYLIB_PATH で指定できるのは、ユーザーの許可がある場合に限ります。システムライブラリを黙ってインストールまたは置き換えてはいけません。この失敗時、ラッパーはレイアウト抽出の部分的な出力を公開しません。

4. 韓国語 OCR でコンテンツが引き続き欠落または破損する場合は、ネイティブのテキストレイヤーが原因である場合に限り、--force-ocr を指定して再試行します。複雑な視覚的要素を含むページで信頼性が依然として低い場合は、問題のあるページを報告し、ツールを黙って切り替えたり別のパーサーをインストールしたりせず、Docling またはドキュメント VLM との比較を提案してください。

完了

Markdown が存在し、空でなく、代表的なソースチェックに合格し、ソース PDF が変更されていない場合にのみ完了とします。PDF と Markdown のパス、Xberg のバージョン、使用した OCR またはレイアウトのオプション、物理ページ数／空白でないページ数／空白ページ数、復元されたマーカー数、要約したパーサー警告、ユーザーが明示的に許可した上書きファイル、引き続き不確かなページや構造を報告してください。