report-to-pdf

PDF へのレポート出力

このスキルは、既存のデータ分析レポート、ダッシュボード、またはインラインのグラフ表示から PDF が明示的に必要な場合にのみ使用してください。ソースには、静的な HTML エクスポートまたは静的なレポートファイルを優先してください。MCP アプリのライブ表示からフレーム内で直接印刷する方法には頼らないでください。Codex MCP アプリはサンドボックス化されたホストで実行されるため、サポート対象の印刷／PDF ブリッジが公開されていません。

想定する手順は、静的 HTML → Chrome のヘッドレス印刷による PDF 化 → PDF の検証です。レポートが MCP アプリのライブ表示としてしか存在しない場合は、まず対応する静的 HTML／エクスポートのソースを作成するか取得してください。

ワークフロー

1. 静的なソースを特定します。

   静的 HTML のレポート／エクスポートへの絶対ローカルパス、またはその静的エクスポートを配信するローカル URL を使用してください。ソースが MCP アプリのライブ表示、blob スタブ、サインインページ、リダイレクトページ、不完全なビューアー、またはレポートの内容ではなく起動スクリプトを含むだけのアプリシェルである場合は、作業を中止し、続行する前に静的 HTML／エクスポートのソースを取得してください。

   ユーザーからホストされたアーティファクトの URL が提供された場合は、まず利用可能な静的エクスポートまたはパッケージソースが公開されているかを確認してください。静的エクスポートが利用できなくても、検証済みのアーティファクトペイロードが現在の実行環境で利用できる場合は、そのペイロードから対応する静的 HTML／エクスポートを作成し、引き継ぎ時にソースの来歴を保持してください。静的エクスポートもアーティファクトペイロードも利用できない場合は、ライブアプリのシェルを印刷したり、記憶を頼りにレポートを再構築したりせず、作業を中止してブロッカーを報告してください。

   静的ソースを作成または修復する際は、表示するメタデータを読者向けの内容にしてください。内部アーティファクトのランタイムフィールド、パッケージの仕組み、バリデーターやデバッグの状態を、レポート本文、ヘッダー、フッター、ソースセクションにコピーしないでください。たとえば、スナップショットの状態、パッケージパス、ウィジェットの種類、マニフェストパス、レンダラー ID、検証状態、ローカルの一時パスなどの生のラベルは、PDF 上に表示しないでください。監査やトラブルシューティングにランタイムの詳細が必要な場合は、PDF には表示せず、サポート用のメモに残してください。データの状態に関する注意事項は、解釈に影響する場合に限り、「合成デモデータ」や「ソースの一部のみを網羅」など、読者向けの表現にしてください。

2. Chrome CLI のヘッドレス印刷で PDF を生成します。

   環境で利用可能なプラットフォーム固有の Chrome 実行ファイルを使用してください。一般的な例として、macOS では /Applications/Google Chrome.app/Contents/MacOS/Google Chrome、Linux では google-chrome、chromium、chromium-browser があります。ブラウザーのレンダリングエンジンで静的 HTML を印刷でき、通常は選択可能なテキスト、レイアウト、グラフ、表、印刷用 CSS が維持されるため、これを主な変換方法とします。

   chrome \
     --headless=new \
     --disable-gpu \
     --no-first-run \
     --no-default-browser-check \
     --no-pdf-header-footer \
     --print-to-pdf=/absolute/path/to/report.pdf \
     /absolute/path/to/report.html
   

3. Chrome が利用できない場合、または有効な PDF を生成できない場合は、レンダラーを使用する代替手段を使います。

   同じ静的 HTML／エクスポートのソースをレンダリングし、そのページを印刷または PDF として保存できる、次に利用可能なローカル手段を使用してください。代替手段は特定のツールに依存しないものとしてください。必要なのは忠実な HTML レンダリングの後に PDF を出力することであり、特定の実装ではありません。モデルが作成した PDF レイアウト、手作業で描き直したグラフ、または記憶を頼りに再構築したレポートに置き換えないでください。

   代替手段を使用できるのは、次の条件を満たす場合に限ります。

   • 静的 HTML／エクスポートが信頼できる唯一のソースであること
   • レンダリングされた出力に、レポートのタイトル、説明文、グラフ、表、注意事項、ソースの詳細が保持されていること
   • アプリ専用の操作要素が除外されていること
   • 生成された PDF が、Chrome を使用する主な方法と同じ検証項目に合格すること

   利用可能なローカルレンダラーで静的 HTML／エクスポートを忠実に印刷できない場合は、必要な機能と変換できなかったソースファイルを示して作業を中止し、ブロッカーを報告してください。

4. PDF 自体を検証します。 pdfinfo などでページ数とメタデータを確認します。PDF に選択可能なテキストが含まれるはずの場合は、pdftotext などでテキストを抽出します。代表的なページを pdftoppm などでレンダリングし、空白のグラフ、コンテンツの切れ、ソース詳細の欠落、不要なコントロール、内部ランタイムメタデータ、レイアウトの崩れがないか確認します。短いレポートでは、すべてのページをレンダリングします。共有、編集、更新、公開、ツールバー、メニュー、ドラッグ操作など、アプリ専用のコントロールラベルに加え、スナップショットのステータス、ウィジェットの種類、マニフェストのパス、パッケージのパス、検証ステータス、ローカルの一時パスなど、内部アーティファクトのラベルについても、表示されていないことを確認します。

5. 引き渡し前に修正します。

   出力が空白、コンテンツの切れ、グラフの欠落、ソース詳細の欠落、またはアプリ専用の装飾を含む場合は、静的 HTML／エクスポートソース、印刷用スタイルシート、またはレンダラーの呼び出し方法を修正して再生成します。ユーザーが制約を明示的に了承していない限り、検証していない PDF を引き渡さないでください。

6. PDF を引き渡します。

   PDF のパスを返し、必要に応じてソース HTML のパスまたは URL も返します。通常の確認内容はサポート用アーティファクトに記録します。確認に失敗した場合、確認できなかった場合、またはユーザーに関係する注意事項が生じた場合を除き、ユーザー向けの引き渡し内容に内部確認を列挙しないでください。ホストされた URL からエクスポート用アーティファクトを取得できず、アーティファクトのペイロードから静的 HTML／エクスポートを作成する必要があった場合は、その旨を簡潔に伝えます。必須の確認を完了できなかった場合は、その不足を明確に伝えます。

基準

• 読者向けアーティファクトの内容を保持します。タイトル、説明文、グラフ、表、注意事項、ソース詳細、存在する場合は生成日時やソースの鮮度に関する詳細が含まれます。
• アプリ専用のコントロールは省きます。上部バー、共有メニュー、編集コントロール、更新コントロール、ドラッグハンドル、ホバー時のみ表示されるメニュー、インタラクティブ操作専用の要素が該当します。
• 表示される PDF から、内部アーティファクトや変換に関するメタデータを省きます。アプリやエクスポートパイプラインの運用にのみ使われる、生のランタイムフィールド、実装状態、パッケージラベル、ローカルパス、バリデーター／デバッグ用ラベル、ステータス文字列を表示しないでください。監査に役立つ内部情報はサポートファイルに保持し、データの状態が解釈に影響する場合は、読者向けの平易な注意書きを PDF に記載します。
• 選択や検索が可能なテキスト PDF を優先します。忠実なテキスト PDF を作成できない場合に限り、スクリーンショット／画像形式の PDF を使用し、テキストを選択または検索できない可能性があることを明記します。
• PDF のソースは静的ソースに統一します。ソース HTML／エクスポートが存在する場合、記憶を頼りにレポートを再構成しないでください。
• 通常の代替手段として、モデルが一から作成した PDF を生成しないでください。PDF を直接作成する方法は、ユーザーが品質上の制約を了承した後の、最終手段として明示する回避策に限り許容されます。
• 可能であれば、生成した PDF のサポートファイルをまとめて保管します。静的 HTML ソース、PDF 出力、抽出したテキスト、ページのプレビュー、ソース取得またはレンダラーの代替手段に関するメモが含まれます。

検証の手引き

引き渡し前に、環境で利用できるローカルツールを使って PDF を検証します。

• PDF が存在し、空でなく、ページ数とページサイズが想定どおりであることを確認します。
• テキスト PDF が想定される場合、テキストを選択／検索できることを確認します。
• 代表的なページをレンダリングまたはプレビューします。短いレポートでは、すべてのページを確認することを推奨します。
• 空白ページ、グラフの切れ、表の欠落、ソース詳細の欠落、不要なアプリコントロール、内部アーティファクトや変換メタデータの漏出がないか確認します。
• スキルファイル自体を編集した場合は、リポジトリで通常使用している Markdown または差分のチェックを実行します。

利用可能な場合の例：pdfinfo、pdftotext、pdftoppm、ファイルサイズの確認、git diff --check。