read-pdfs

read-pdfs

トークンを浪費せずにPDFを読みます。PDFをそのままコンテキストに追加するとコストが高く、多くの場合、ほとんどが画像です。このスキルはPDFを一度だけMarkdownのワークスペースに変換します。テキストは低コストで読み取れるようにし、画像・図・グラフがあった場所にはプレースホルダーを残し、作業に必要なビジュアルがあるページだけをレンダリングします。

基本的な考え方

1. 一度だけ取り込む → pdf_to_markdown.py がPDFごとにワークスペースフォルダー（元のPDF、.md、manifest.json）を作成します。
2. Markdownを読む → すべてのテキスト、見出し、表が含まれます。画像は 🖼 [[fig:p4:1]] のようなプレースホルダートークンで表示されます。
3. 必要に応じてレンダリングする → 図の実際の画像が必要な場合に限り、そのページをPNGにレンダリングして読み取ります。

これにより、トークンコストはPDFのサイズではなく、参照する内容に応じて増減します。

前提条件

スクリプトには pymupdf4llm と pymupdf が必要です。実行時にモジュールが見つからないというエラーが表示された場合は、インストールしてください。

pip install -r requirements.txt

pymupdf4llm の使用を推奨します（構造化されたMarkdownを生成し、画像の位置を示します）。存在しない場合、コンバーターはプレーンテキストの抽出に切り替え、その旨を表示します。構造は簡素になりますが、それでも利用できます。

スクリプトの実行。 このスキルをインストールした場所への完全なパスを指定して実行してください（scripts/... のみの形式が使えるのは、カレントディレクトリがスキルのルートである場合だけです）。Windows／PowerShellでは、スペースを含むパスを二重引用符で囲んでください。

python "<skill-dir>/scripts/pdf_to_markdown.py" "path/to/report.pdf"

変換後、絶対パスが入力済みの正確なレンダリングコマンドが、変換されたファイルのフロントマターに記載されます。再構成せず、そこからコピーしてください。

ワークフロー

このチェックリストをコピーして、進捗を記録してください。

- [ ] Step 1: Ingest the PDF  (run pdf_to_markdown.py)
- [ ] Step 2: Read the .md    (text, tables, figure index, placeholders)
- [ ] Step 3: Render a page   (only when a visual must be seen, then Read the PNG)

ステップ 1 — PDFを取り込む

PDFに対してコンバーターを実行します。ファイル名に基づいたクリーンなワークスペースフォルダーが作成されます。

python "<skill-dir>/scripts/pdf_to_markdown.py" "path/to/report.pdf"

デフォルトでは、PDFと同じ場所に次のものが作成されます。

report/
├── report.pdf        # the original, copied in (workspace is self-contained)
├── report.md         # Markdown + YAML front matter + image placeholders
└── manifest.json     # structured record of what's in the .md vs the original

便利なフラグ：--out-dir DIR（ワークスペースを別の場所に作成）、--force（既存のワークスペースを上書き）、--move（元のPDFをコピーではなく移動）、--dpi N（フロントマターに記録するデフォルトのレンダリングDPI）。スクリプトは、ワークスペースのパスと正確なレンダリングコマンドを含むJSONの概要を出力します。保存しておいてください。

前回の実行でワークスペースがすでに作成されている場合は、再変換せず、既存の .md を読んでください。

ステップ 2 — Markdownを読む

report/report.md を読みます。冒頭のフロントマターには、ページ数、図と表の数、レンダリングコマンドが記載されています。その下には、すべてのプレースホルダーをページとキャプションに対応付けた 「図と画像のインデックス」 の表があります。続いてページ本文があり、各ページは ## Page N セクションで構成され、表はMarkdown形式、ビジュアルはインラインのプレースホルダーで表示されます。

要約、引用、表のデータ、「Xはどこで説明されていますか」といった質問のほとんどは、Markdownだけで答えられます。ページ番号を示して回答してください。

ステップ 3 — ビジュアルが必要な場合に限りページをレンダリングする

図、グラフ、ダイアグラム、写真、またはスキャンしたページのキャプションだけでなく、実際の画像を見る必要がある場合は、.md 内のプレースホルダーを見つけ、トークンからページ番号を確認して、そのページをレンダリングしてから、生成されたPNGを読み取ります。

python "<skill-dir>/scripts/render_page.py" "path/to/report" 4

render_page.py は、ワークスペースフォルダー（または直接指定した .pdf パス）と、1始まりのページ指定を受け付けます。指定例は 4、3-5、1,4,7、2-3,9 です。report/pages/[email protected] を生成し、キャッシュに保存して、パスを出力します。そのPNGを読み取ってページを確認してください。

ページ番号なのはトークンの p<N> の部分だけです。末尾の :n は同じページ上の複数のビジュアルを区別するためのものです。たとえば [[fig:p4:2]] の場合は、ページ 4 をレンダリングします。

フィードバックループ： 細かい文字や密集したグラフが読みづらい場合は、--dpi 220（または 300）を指定して高解像度で再レンダリングしてください。ざっと確認するだけなら、--dpi 100 のほうが低コストです。

プレースホルダーの概要

• 🖼 [[fig:p4:1]] — image (~300×180) not shown; render page 4 to view. — 4 ページのその位置にある画像／図です。通常、キャプションは次の行に続き、図の索引に表示されます。
• ⚠ [[fig:p3:1]] — scanned / image-only page; render page 3 to read. — 抽出可能なテキストがほとんど、またはまったくありません。ページをレンダリングして内容を確認してください。
• トークンの形式は [[fig:p<page>:<n>]] です。すべてのビジュアルを一覧表示するには、.md 内の [[fig: を検索するか、フロントマターの図の索引を確認してください。

プレースホルダーの仕様と解析の詳細については、references/placeholders.md を参照してください。

ヒント

• 複数の PDF： それぞれを個別のワークスペースに変換してください（ファイルごとに 1 つのフォルダー）。ページを参照して相互に確認できます。
• 大きな PDF（数百ページ）： それでも一度だけ変換し、.md と図の索引を確認してから、必要なページだけを選択してレンダリングしてください。「念のため」と多数のページをレンダリングするのは避けてください。目的に反します。
• スキャン済み／画像のみの PDF： テキストは少量になります。該当するページをレンダリングし、画像として確認してください。ビジョンの代わりに自動 OCR を使う方法については、references/conversion-internals.md を参照してください。
• PDF を再度ダンプしないでください： ワークスペースが作成されたら、元の PDF をコンテキストに読み込むのではなく、.md と対象を絞ったレンダリングを使って作業してください。

参照ファイル

• references/placeholders.md — プレースホルダートークンの形式、図の索引、スキャン済みページのマーカー、およびそれらの検索・解析方法。
• references/conversion-internals.md — 変換の仕組み、キャプションとスキャンの判定ヒューリスティクスおよび調整可能な定数、DPI のガイダンス、OCR、Playwright ベースのレンダリング方法、およびトラブルシューティング（暗号化／巨大な PDF）。