report-to-google-doc

Google ドキュメントへのレポート出力

既存の HTML 分析レポートから共有可能な Google Drive ドキュメントを作成する必要があることを、ユーザーが明示した場合にのみこのスキルを使用してください。ソースは HTML レポートである必要があります。ローカルファイル、ダウンロードした blob ホストのレポート、または $build-report HTML モードで生成されたレポートを使用できます。このスキルでは、稼働中の MCP アプリのレポートを直接変換することはできません。

想定される流れは HTML -> DOCX -> Drive へのアップロードです。Drive 上で、アップロードしたファイルをネイティブな Google ドキュメントの MIME タイプではなく、DOCX ベースのビューアーファイルとしてホストすることは問題ありません。以前の Google ドキュメントのバッチ更新リクエスト経路は使用しないでください。

ワークフロー

1. HTML レポートを特定します。

   絶対パスを使用してください。ユーザーがリモートのレポートを指定した場合は、まず取得してから、ローカルの HTML ファイルをヘルパーに渡します。ファイルがサインインページ、リダイレクトページ、または小さなスタブである場合は、そこで停止し、実際のレポートを入手してください。

2. 同梱のヘルパーを実行します。

   python3 <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py \
     /absolute/path/to/report.html \
     --out-dir /tmp/report_to_google_doc_plan
   

   通常の経路では --render-workers を省略してください。同じレポート系列でローカルにベンチマークを実施した場合に限り、ワーカー数を指定してください。 依存関係が不足している場合は、beautifulsoup4、pillow、python-docx を含むローカルの仮想環境を使用してください。cairosvg またはヘッドレス Playwright は任意のレンダラーです。

3. ヘルパーの出力を確認します。

   必須の出力：

   • skeleton.txt：安定したプレースホルダーを含むソーステキスト
   • manifest.json：解析された見出し、表、コールアウト、リスト、スタイル、リンク、およびレンダリングされたビジュアルの一覧
   • preflight_checks.json：ソース、幅、DOCX、レンダリング画像のチェック結果
   • report.docx：生成されたローカルの Word ドキュメント
   • docx_upload_plan.json：簡潔なアップロード手順
   • placeholder_queries.json：ソースマッピングのデバッグラベル

   preflight_checks.json の status: "passed" となり、エラーがゼロになるまでアップロードしないでください。警告は解消するか、引き継ぎ時に伝えてください。

4. DOCX をアップロードします。

   mcp__codex_apps__google_drive._upload_file({
     "file_uri": "/tmp/report_to_google_doc_plan/report.docx",
     "file_name": "Report Name.docx",
     "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
   })
   

   返された Drive URL を納品物として扱ってください。ネイティブな Google ドキュメントへの変換を強制しようとしたり、_batch_update_document にフォールバックしたりしないでください。

5. アップロード結果を検証します。

   アップロードされたファイルが読み取り可能で空でないことを確認してください。アップロードされたテキストをソースの一覧と照合します。タイトル、セクション見出し、エグゼクティブサマリーまたは回答のコールアウト、注意事項、推奨事項、ソース注記、ソースリンクを確認してください。 利用可能な場合は、ローカルの report.docx の構造も確認してください。見出し数、リスト、表、ハイパーリンクの関係、画像の関係が manifest.json と一致している必要があります。

6. リンクを引き継ぎます。

   Drive/Docs の URL を返し、必要に応じてローカルの DOCX パスまたはソース HTML パスも伝えてください。コネクターの処理が成功しただけでは不十分です。アップロードされたファイルとローカルの DOCX 構造がソースレポートと照合されて初めて、引き継ぎが完了します。通常のチェックと事前確認の詳細はサポート用の成果物に記録してください。チェックが失敗した場合、実施できなかった場合、またはユーザーに関係する注意事項が発生した場合を除き、ユーザー向けの引き継ぎに内部チェックを列挙しないでください。

基準

• HTML レポートに含まれるすべてのセクション、見出しの主張、指標カード、指標の定義、出典注記、グラフの要点、推奨事項、注意事項、リンクを維持します。
• 意味を表す書式を維持します。見出し、段落、インラインの太字／強調、インラインコード、肯定／否定の色、リンク、リスト、コールアウト、指標カードのグリッド、表、注記、キャプション、グラフを維持します。
• 実用上可能な場合は、見出し、段落、表、箇条書き／番号付きリスト、リンク、インライン画像、段落の網掛け、表のセルの網掛け、テキストスタイルなど、DOCX ネイティブの構造を使用します。
• レポートのテキスト列を読みやすく保ちます。表、グラフ、レンダリングされた表のグリッド、スクリーンショット、視覚的なブロックは、DOCX のページのテキスト幅を超えてはなりません。
• グラフは、ソースのビジュアルまたは同じデータを使った SVG フォールバックからレンダリングしたインライン画像として維持し、テキストや表と同じ左端に揃えます。棒、凡例の色見本が欠けているグラフや、すべてのマークが黒または白のグラフは、DOCX に画像オブジェクトが含まれていても検証に不合格となります。
• 複数列のレポートブロックを維持します。タイトル付きの小さな表だけで構成された 2 列のグリッドは、テキスト幅に収まる 2 列のレンダリング画像として維持できます。ナラティブテキスト、ピル、コールアウト、表以外のパネルが混在する 2 列ブロックでは、内容を削除せず、ネイティブ形式で維持します。
• サニタイズ済みレポートで意図的に省略された顧客レベルの詳細情報や機密リンクは公開しません。
• seed_requests.json、remote_write_plan.json、all_requests*.json などの Google Docs のバッチ更新アーティファクトは作成しません。

修正

検証で変換の問題が見つかった場合は、次の修正を適用します。

問題	修正
見出しが標準の太さになっている	DOCX ライターの見出しスタイル、または明示的なランの太字設定を修正します。
タイトルまたは見出しの後に空行がある	スペーサー段落を削除します。スケルトンでは見出しの後に \n\n ではなく \n を出力する必要があります。
本文の段落間隔が広すぎる	文字どおりの空段落を削除し、スタイルの間隔を控えめに設定します。
表／画像の幅が広すぎる	表の列幅または画像幅を DOCX のテキスト列幅に設定します。
グラフのラベルはあるが棒が欠けている	SVG のクラススタイルをインライン化するか、挿入前にヘッドレススクリーンショットを使用します。
2 列の表グループが平坦化されている	タイトル付きの小さな表を維持したまま、グリッド全体を 1 つのレイアウトブロックとして扱います。
エグゼクティブサマリー、指標カード、またはセクションが欠けている	アップロード前にパーサーのインベントリを修正します。
グラフが表に重なっている	表の後に、グラフを独立した段落として挿入します。
グラフが重複している	余分な画像を削除し、ソースの順序に従ったコピーを 1 つだけ残します。
インラインの太字／コード／色が欠けている	DOCX ライターのマニフェスト範囲の分割を修正します。
ソースリンクに URL がそのまま表示されている	ネイティブのリンクラベル、または HTML のリンクテキストを使ったネイティブの箇条書きに置き換えます。

ローカルチェック

python3 -m py_compile <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py
python3 <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py \
  /absolute/path/to/report.html \
  --out-dir /tmp/report_to_google_doc_plan_smoke
jq '.status, .summary' /tmp/report_to_google_doc_plan_smoke/preflight_checks.json
test -f /tmp/report_to_google_doc_plan_smoke/report.docx
test -f /tmp/report_to_google_doc_plan_smoke/docx_upload_plan.json
git diff --check -- plugins/data-analytics/skills/build-report/report-to-google-doc