knight-imagetopptx-skill

Knight Image To PPTX

対象範囲

既存のビジュアルスライドにのみ使用してください。

• 編集可能な PowerPoint に変換する必要がある PNG／JPG／WebP のスライド画像。
• スライドが画像のみのスクリーンショット、または生成された全ページ画像で構成される PPTX。
• 各ページを編集可能な PowerPoint スライドにする必要がある PDF または複数ページの画像セット。
• 編集可能なテキスト、コンテナー、矢印、アイコン、レイアウトオブジェクトが必要な、レンダリング済みのスライドページ。

新しいデッキをゼロから作成する場合、SVG のみを変換する場合、またはユーザーがオブジェクト単位の編集を必要としない単純な画像のパッケージ化には使用しないでください。

基本ルール

ユーザーが必要とする部分を、実用的な PowerPoint オブジェクトとして編集できるように、スライドを意味に沿って再構築します。

• テキスト、カード、パネル、区切り線、線、単純な矢印、箇条書き、バッジ、表：ネイティブの PowerPoint オブジェクトとして作成します。
• アイコン、絵文字、複雑なバッジ、装飾的なマーク、小さな UI グリフ、イラスト風の要素、複雑な画像、複雑なビジュアルオブジェクト：画像生成モデルで個別の透過 PNG アセットとして必ず生成し、PPTX に挿入します。
• 流れるリボン矢印、移行ストリーム、グラデーション付き矢印帯、複数レーンの流線矢印、または柔らかなフェード、束ねられた曲線、重なり合う流れ、融合した矢印先端を必要とする矢印システムは、複雑なビジュアルオブジェクトです。画像生成モデルで個別に生成し、1 つまたは少数の透過 PNG ビジュアルアセットとして PPTX に組み込んでください。多数のネイティブの四角形、三角形、曲線の断片から再構築しないでください。
• 元画像の切り抜きは参照素材としてのみ使用します。ユーザーが正確な状態を保つ必要がある実際のロゴ／ブランドマークを明示的に提供した場合を除き、スクリーンショットの切り抜き部分を最終的なアイコンアセットとして使用しないでください。

必須の実行要件

このスキルが起動された場合、以下のワークフローは任意の指針ではなく、必須です。スクリーンショットから直接 PPTX を作成してはならず、必要な証拠が揃うまでファイルを納品しないでください。

作成前に、実行状況をメモリまたはローカルのメモで追跡します。rebuild_execution_report.json は終盤に一度だけ、簡潔な最終サマリーとして書き込みます。詳細なフェーズログを何度も書き直さないでください。最終サマリーには、以下の必須フェーズを含めてください。

• input_prepared：ソースパス、スライド／ページ数、スライドサイズ、アスペクト比、出力先を記録済み。
• visual_inventory_done：主要なテキストブロック、ネイティブオブジェクト、コネクター、表、カード、アイコン、複雑なビジュアルを安定した ID 付きで一覧化済み。
• asset_classification_done：すべてのテキスト以外のビジュアルを native_editable または imagegen_asset に分類済み。
• imagegen_assets_done：すべての imagegen_asset に画像生成元、最終的な透過 PNG、マニフェスト項目、コンタクトシートまたは切り抜きによる QA が存在。
• text_fit_done：表示されるすべての PPT テキストオブジェクトを ppt_text_fit.py で確認済み、または例外を記録済み。レポートは簡潔でかまいません。
• pptx_built：ネイティブのテキスト／図形と個別の画像アセットを使用して編集可能な PPTX を生成済み。
• render_qa_done：PPTX を PNG にレンダリングし、参照画像とページ全体で比較済み。
• local_crop_qa_done：アイコンボタン、情報量の多いカード、表、ラベル、下部バー、ユーザーが指摘した領域などを切り抜いて確認済み。
• validation_done：アセットチェッカーおよび関連するスクリプト／コンパイルの確認を実行済み、または障害を記録済み。

いずれかのフェーズを完了できない場合は、黙って省略せず、作業を中止して障害を報告してください。ユーザーが迅速な対応や概略版を求めた場合も、最低限の簡潔な実行サマリー、アセットマニフェスト、レンダリング済みプレビュー、検証を行ってください。QA を意図的に省略した場合は、結果をドラフトとして明記してください。

最終回答には、PPTX のパスと、最も重要な証拠ファイルのパス（通常はレンダリング済みプレビュー、アセットコンタクトシート、簡潔なテキストフィットレポート、特筆すべき切り抜き QA）を含めてください。コードを生成しただけで作業完了と主張しないでください。

譲れない画像生成ゲート

最終的なアイコンや複雑なビジュアル素材は、画像生成モデルで作成する必要があります。 PIL、SVG、キャンバス、アイコンフォント、手作業で作成したベクターパス、PowerPoint の図形描画を使って、最終的なアイコンを手描き、スクリプトで生成、トレース、または近似してはいけません。これらの方法は、カード、線、矢印、表、区切り線、シンプルなバッジ、テキストコンテナーなど、ネイティブの編集可能なプリミティブに限って使用できます。

再構築の前に、テキスト以外のすべてのビジュアル領域を分類します。

• native_editable：パネル、角丸長方形、通常の単一矢印、表のセル、区切り線、小さな数字バッジ、シンプルな UI コンテナーなど、PowerPoint 上で編集可能な状態を保つべき単純な図形。
• imagegen_asset：アイコン、ピクトグラム、正確なブランド素材として提供されていないロゴ、装飾的なスカイライン、イラストの一部、複雑なバッジや印章、編集可能なスタイルにしたいスクリーンショット、細かなグリフが密集したもの、マスコット・人物・デバイス・シーン、複雑な画像、流れるリボン状の矢印、移行の流れ、複数レーンのグラデーション矢印、または忠実な再構築にカスタムの描画ロジックが必要となるビジュアル。

imagegen_asset ごとに、画像生成モデルを呼び出すか、この再構築用にそのモデルですでに生成された素材を再利用します。ツールが生成元ファイルを保存する場合は、そのファイルを保持して作業用の assets/ フォルダーにコピーし、必要に応じて切り抜き、再配置、クリーンアップして、個別の透過 PNG にします。素材マニフェストには、生成元のパスまたはプロンプトを記録します。

画像生成ツールが利用できない、ブロックされている、または繰り返し失敗する場合は、作業を停止して問題を報告します。必要な素材をスクリプトで描画した代替物や手作業で作成した代替物に無断で置き換えたり、そのような代替物を生成済みと説明したりしてはいけません。

ワークフロー

1. 入力を準備する

   • 元データの隣に、例：editable-replica-XX/ のような作業用フォルダーを作成します。
   • 入力が画像のみの PPTX または PDF の場合は、各ページ／スライドをまず PNG にレンダリングまたはエクスポートし、それぞれのレンダリング画像を参照画像として扱います。
   • 複数の画像が入力された場合は、順序を保持し、各画像を 1 枚の対象スライドとして扱います。
   • スライドサイズ、アスペクト比、元ファイル名／ページ番号、出力先のパスを記録します。
   • Mandatory Execution Contract で必須とされる実行フェーズの追跡を開始します。ただし、最終的な rebuild_execution_report.json は検証後に一度だけ作成し、簡潔な概要にまとめます。
   • 複数ページの入力では、各ページを独立した単一スライドの再構築タスクとして扱います。ビジュアルが実際に繰り返されており、レンダリング確認でもそれが確かめられない限り、ページ 1 をコピーして大まかに編集し、ページ 2 を作成してはいけません。

2. ページの要素を棚卸しする

   • タイトル／サブタイトル／本文テキスト、カード、パネル、コンテナー、矢印、コネクター、アイコン、ラベル、フッター、背景を含むビジュアル要素の一覧を作成します。
   • 例：process_log_parse、output_excel_sheet、bottom_human_reviewer のように、テキスト以外の各ビジュアル素材に安定した ID を割り当てます。
   • 各素材のおおよそのバウンディングボックスと目標ビジュアルサイズを記録します。
   • 上記の「譲れない画像生成ゲート」に従い、テキスト以外の各ビジュアルを native_editable または imagegen_asset に分類します。
   • 単純な直線ではない矢印やコネクターごとに、安定した ID、尾から先端への方向、経路の種類（straight、elbow、arc、U-turn、hook、loop、ribbon）、線または塗りの役割、おおよそのバウンディングボックス、付随するラベルがあればそのラベルを記録します。矢印と付随するラベルは、後の QA では 1 つのビジュアルコンポーネントとして扱います。

3. アイコンとビジュアル素材を生成する

   • すべての imagegen_asset に画像生成モデルを使用します。テキスト、ラベル、数字、カード枠、影（参照画像に見える場合を除く）がなく、単独で配置されたフラット／ベクタースタイルの素材を生成するよう指示します。
   • 色の忠実性は初回生成で必須です。 プロンプトを作成する前に、各アイコンの参照色をサンプリングして記録します。前景の線／塗り、内部のディテール色、コンテナー／ホスト色、およびアイコンが透明、モノクロ、色付きの背景に白、白地に色、マルチカラーのいずれを意図しているかを記録してください。最初の画像生成プロンプトでは、素材ごと、またはグリッドのセルごとに、これらの色の役割とおおよその16進数値を指定します。モデルに汎用パレットを選ばせないでください。
   • 色の役割も素材のアイデンティティの一部として扱います。参照画像で同じ絵文字が異なる色や状態で使われている場合は、色ごとに別の素材、またはグリッドの別セルとして生成します。生成した素材の色の役割が参照画像と一致しない場合は無効として、PPTに挿入する前にプロンプト／ソースシートから再生成してください。PPTの色合い変更、再着色、不透明度の調整、後からのクリーンアップで、初回生成の色違いを修正しようとしないでください。
   • 複雑なビジュアル領域では、まず意味的な対象を分析し、ピクセルを切り抜いて複製するのではなく、きれいに再構築した素材を生成するようモデルに指示します。PowerPointで編集可能なネイティブテキストにできる場合は、テキストを画像の外に配置します。
   • 流れる矢印、移行の流れ、リボン状の帯、その他の複合的な矢印のビジュアルでは、ビジュアル全体を透明なPNG素材として生成します。後からPPTに配置するために必要なレーン数、方向、色の役割、フェードの動作、曲率、矢印の先端のスタイル、中央／端の空き領域を正確に指定します。独立した位置合わせが必要な場合は、生成したソースを左向きの流れと右向きの流れなど、意味のある少数の透明素材に分割します。各レーンや矢印の先端を個別のPPTオブジェクトに細分化しないでください。
   • 画像生成モデルには、本物の透明背景を持つPNGを要求します。ネイティブのアルファチャンネルを保持してください。生成素材は、切り抜きや挿入の前に、RGBA形式であること、四隅が透明であること、空でないアルファ境界ボックスがあること、被写体の占有範囲が妥当であることを確認してください。
   • 素材グリッドは、列数を C または N、行数を R または M とする明示的な C×R ／ N×M の配置ルールがある場合にのみ使用できます。これには正方形の N×N グリッドや、5×4、4×2 などの長方形グリッドが含まれます。
   • 画像生成プロンプトでは、グリッドの寸法を正確に指定します。C columns × R rows、キャンバス全体の比率 C:R、セルがすべて同じサイズであること、セル間に目視できる、または意図的に空けた溝があること、各アイコンがそれぞれのセルの中心に配置されること、各アイコンが中央の55～65％の安全領域内に収まること、各セル内に20～25％以上の透明な余白があることを指定します。端が切れないこと、溝にはみ出さないこと、セルをまたいで重ならないことも必須とします。
   • 正方形の N×N グリッドでは、正方形のキャンバスと、同じ数の行と列を指定します。長方形の C×R ／ N×M グリッドでは、列数と行数の比率に一致するアスペクト比のキャンバスを指定します。端のセルにも、内部のセルと同じ安全領域と余白のルールを適用します。5×4、4×2、または特定のグリッドサイズを固定で指定しないでください。列数と行数はパラメーターとして渡します。
   • 切り抜く前に、ネイティブのアルファチャンネルを持つグリッド出力を検証します。RGBAモードであること、四隅が透明であること、空でないアルファ境界ボックスがあること、予期しない不透明な背景がないことを確認してください。
   • 各セルは、意味的に独立した素材1点に正確に切り分けます。複数のアイコンを1つの素材にまとめないでください。
   • グリッドの計算だけを信用しないでください。素材グリッドを切り分けた後、セルをまたぐ断片を除去し、最終的な個別PNGのコンタクトシートを確認します。アイコンに余計な弧、点、くさび形、切れた線、隣接するセルの断片、または生成シート自体による端のセルの切れが含まれている場合は、グリッドを無効とみなし、より厳しい安全領域、溝、余白の制約を設定して再生成してから、素材をPPTに挿入してください。
   • 切り分け後、各PNGを十分な安全余白を持つ正方形の透明キャンバスに正規化します。目標は、各辺に10 px以上の透明な余白を設けることです。アルファ境界ボックスの中心だけでなく、アルファの視覚的重心を基準に中央揃えします。ターゲット、星、光線、矢印、虫眼鏡などの非対称なアイコンは、境界ボックスを基準に中央揃えすると中央からずれて見えることがあります。
   • 生成したソースシートは assets/source/ または同等のソースフォルダーに保存し、最終的な素材ディレクトリには、PPTに挿入する個別の透明PNGのみを格納します。これにより、QA中にソースシートを最終素材と取り違えるのを防げます。
   • PPTに挿入する際は、透明なキャンバス全体ではなく、アルファチャンネルで透明でない領域のサイズに合わせて拡大縮小し、アルファの重心を基準に位置を合わせます。アスペクト比を維持し、任意のサイズの枠に合わせてアイコンを引き伸ばさないでください。

4. PPTX を再構築する

   • python-pptx、PowerPoint の自動化、またはリポジトリで確立されている PPT ツールを使用します。
   • 無地の白またはオフホワイトのページには、スライド全体を覆う白い長方形を追加するのではなく、ネイティブのスライド背景塗りつぶし（slide.background.fill）を優先してください。PowerPoint の背景塗りつぶしでは表現できない、目に見える編集可能な装飾を伴う場合に限り、下部に背景用の長方形を使用します。
   • 読み取れるテキストには、すべてネイティブの PowerPoint テキストボックスを使用します。編集可能なテキストを画像にラスタライズしないでください。
   • 角丸カード、パネル、枠線、区切り線、破線、通常の矢印には、ネイティブ図形を使用します。
   • PPT オブジェクトの種類を選ぶ前に、矢印の形状を一致させます。方向、尾端と先端の位置、経路の種類、線や塗りつぶしの太さ、折れ曲がりや曲率、ラベルとの位置関係はすべて重要です。参照画像にカードやステップの間の太い塗りつぶし矢印の軸と先端がある場合は、矢印付きコネクタ線ではなく、DOWN_ARROW、UP_ARROW、LEFT_ARROW、RIGHT_ARROW などのネイティブ塗りつぶし矢印図形を作成します。参照画像で細い線やコネクタに見える場合に限り、コネクタを使用します。
   • コンパクトな戻り矢印、U ターン矢印、フック矢印、フィードバック矢印、コールアウト矢印を、直線矢印や方向が異なる既定図形に単純化してはいけません。参照画像に合う場合は、ネイティブの矢印先端を備えた単一の編集可能なオープン自由曲線または弧のパスを使用します。組み込みの U ターン／フック図形を使う場合は、候補を対象サイズで回転角 0、90、180、270 で描画したうえで、先端の向きとループの側が一致するものを選びます。参照画像で明らかに曲線の戻り矢印を、参照画像自体が直角の分割形状でない限り、複数の直線断片で近似しないでください。
   • セクション見出し、タイトルバー、ピル、指標カード、タブ、ラベル帯などの長方形状のオブジェクトには、ネイティブの RECTANGLE または ROUNDED_RECTANGLE 図形を使用します。参照画像にはっきりと斜めの切り欠きや旗の尾がある場合を除き、リボン、シェブロン、三角形、自由曲線のテール用ヘルパーは使用しないでください。
   • 流れるリボン矢印、高密度のスクリーンショット、イラスト風の領域など、生成した複雑なビジュアルアセットは、参照画像に合わせてネイティブオブジェクトの背面または間に配置する透過 PNG として挿入します。表示されるアルファ境界に基づいて拡大縮小し、測定した対象の端に位置合わせします。編集可能なラベル、カード、中央の円、凡例、コールアウトは、アセットの上または周囲にネイティブ PPT オブジェクトとして配置します。
   • じょうご、台形、シェブロン、矢じり、三角形のタブ、斜めのバッジなど、方向に依存するネイティブ図形は、PowerPoint の既定の向きをそのまま使わないでください。参照画像と描画後の向きを比較し、必要に応じて回転するか、ネイティブ自由曲線パスで作り直します。
   • PowerPoint の角丸長方形は明示的に調整します。MSO_SHAPE.ROUNDED_RECTANGLE はアスペクト比によっては角が極端に大きいカプセル状になるため、shape.adjustments[0] を 0.025-0.08 程度に設定し、レンダリング結果を確認してください。
   • アイコンや複雑なビジュアルごとに、端が切れていない透過背景の PNG を 1 つ生成して使用します。
   • アイコンを引き伸ばさないでください。アスペクト比を維持し、アルファコンテンツの境界ボックスを基準に中央揃えします。
   • 高密度の表セル、カード、ボタンラベル、中国語と英語が混在するラベル、長いタイトルやサブタイトルを書き込む前に、実際に使用できるテキスト領域全体（枠線、アイコン、実際の余白を差し引いた後）を測定し、テキストフィットの事前確認を実行します。その書き出し済みピクセル境界ボックス、使用するフォント、太字の有無、参照画像での最大行数を指定して、scripts/ppt_text_fit.py を実際に実行してください。recommended_pt を最初の構築サイズとして使用し、text_fit_report.json などの簡潔な証拠ファイルを保存します。
   • テキストフィットの対象範囲は、add_fitted_text() などのヘルパーを使用したかどうかではなく、最終的に表示されるテキストに基づきます。PowerPoint のテキストを作成するコードパスはすべて、書き込み前にフィットの証拠を用意してください。対象には、add_text()、text_frame の手動編集、paragraph.add_run()、数値と単位が混在する行、表セル、バッジ、ラベル、凡例、グラフや軸のラベル、小さな UI キャプションが含まれます。固定の run サイズは、表示されるフレーズ全体または個別に指定したサブボックスのフィット確認後に限り使用でき、レポートにはフィットを確認したテキストオブジェクト名を記載します。
   • テキストのはみ出し、表の枠線との重なり、意図しない改行を避けると同時に、参照画像の視覚的な階層を損なうほど文字を小さくすることも避けます。役割に対して明らかに小さくしなければテキストが収まらない場合は、まずテキスト領域の形状に問題があると考えます。利用できる余白までテキストボックスを広げる、重複する内部余白を減らす、アイコンや区切り線、列の割り当てを調整する、または参照画像と同じ折り返し方を許可するといった方法を検討してください。フォントサイズを下げるのは最終手段であり、既定の修正方法ではありません。
   • python-pptx で中国語テキストを扱う場合は、run.font.name だけでなく、OOXML の東アジア書体（a:ea）も設定します。そうしないと、PowerPoint が宋体やセリフ体のフォントにフォールバックし、レイアウトがずれることがあります。
   • 繰り返し使うラベルやボタンのコンポーネントは、固定ではなくレスポンシブに扱います。Agents 工作流 のような英語と中国語が混在するラベルでは、純粋な中国語ラベルと比べて、フォントを小さくする、テキストボックスを広くする、またはテキストのオフセットを調整する必要が生じることがあります。
   • ツールやサンプルのボタンは、ボタン図形、独立したアイコン PNG 1 つ、編集可能なテキストで構成します。Doc、PPT、frontend、imagegen、GitHub などのラベルをアイコン画像に埋め込まないでください。
   • 円形のプロセスループでは、参照画像に滑らかな弧矢印がある場合、曲線コネクタだけに頼らないでください。真の PowerPoint ネイティブの弧／矢印オブジェクト、または高精度のオープン自由曲線パスを使用します。滑らかな弧を、多数の個別の直線コネクタ線で再現しないでください。継ぎ目が目立つことや、選択ウィンドウが煩雑になることは実際の欠陥です。
   • 弧状ループに複数の曲線矢印が必要な場合は、各弧のセグメントを連続した編集可能オブジェクト 1 つとして作成し、それらを最上位のビジュアルオブジェクト 1 つにグループ化します。ユーザーがループをひとまとめに移動でき、必要に応じてグループ解除して編集できるように、グループには center_cycle_curved_arrows_group のような説明的な名前を付けます。
   • レンダリング前に、レイヤー順序の最終確認を行います。厳守すること：ネイティブオブジェクトの内部順序を維持し、アイコンとテキストのみを前面に移動します。ネイティブオブジェクトの視覚的な内部順序を保ち、画像生成で作成したアイコンアセットをネイティブオブジェクトより前面に配置し、すべてのテキストを最前面に配置します。図形が編集可能なテキストを覆わないようにし、アイコンがラベルを覆わないようにしてください。
   • 各コンポーネントは、自然な表示順に構築することを優先します。最初にネイティブのコンテナーやカード、次にアイコン／画像アセット、最後に編集可能なテキストを配置します。コンポーネント内の順序ですでに正しい視覚的な重なりが得られている場合は、スライド全体の XML 順序を無差別に入れ替えないでください。
   • z オーダーを変更した後は、PPTX の図形一覧だけでなく、レンダリングした PPT の切り抜き画像で確認します。PPTX 内に画像が存在しても、PowerPoint の図形ツリーの実際の順序によっては、後から配置されたネイティブ図形の背後に隠れていることがあります。
   • 薄い構築用のリングやガイド円は控えめにします。半透明の PPT 楕円の線は重なり合い、書き出し後に不要な灰色のリングになることがあります。曖昧なリングは削除するか、透明度を非常に高く設定し、継承された影を明示的に削除してください。

5. レンダリングして比較する

   • 可能な場合は、PowerPoint のエクスポート機能を使って、再構築した PPTX を PNG にレンダリングします。
   • ビジュアルプレビュー／コンタクトシートを作成し、参照画像と比較します。
   • アイコンのクリッピング、アイコンのサイズ、矢印の向き、テキストの折り返し、カードの枠線、配置、間隔など、明らかな不一致を修正して繰り返します。
   • スライド全体だけでなく、混み合った領域も切り抜いて QA を行います。下部のタグ、情報量の多いカード、円形の図、右側のツールパネル、フィードバックバー、小さな戻り矢印／吹き出し矢印、選択オブジェクトに関する指摘があった箇所について、1:1 の PNG 切り抜きを保存します。
   • 小さく折れ曲がった矢印や注釈付きの吹き出しはすべて、レンダリングした切り抜きを同じ範囲の参照画像と比較します。矢印の先端の向き、経路／ループの側、線または塗りの太さ、端点、ラベルの位置を一体として確認します。全体的な流れの向きが意味的に正しくても、不一致は納品前に修正します。
   • 狭いアイコン領域、特にボタン／ツール／UI のアイコンはすべて、挿入した PPT 領域の 1:1 の部分切り抜きをレンダリングします。アセットのサムネイルだけでは不十分です。最終的にレンダリングした PPT に、端のクリッピング、余計な断片、隣接セルの残骸がないことを確認します。
   • 複数ページの入力では、再構築したすべてのスライドを、それぞれの元ページと比較してレンダリングします。納品前に、ページごとに不一致を修正します。

6. 複数ページの出力をまとめる

   • 複数の元画像／ページがある場合は、個別に再構築したすべてのスライドを元の順序で 1 つの .pptx に追加します。
   • ページごとのアセット、マニフェスト、レンダリング済みプレビュー、QA 用の切り抜きは、スライド番号／ページ番号で追跡できるようにします。
   • ユーザーから明示的な依頼がない限り、PPTX ファイルを別々に納品しないでください。標準の納品物は、編集可能な PPTX 1 つにまとめたものです。

実装パターン

• CJK フォント XML： run.font.name を設定した後、実行 XML の a:latin、a:ea、a:cs の typeface も設定します。これは中国語のテキストランすべてに適用します。
• テキスト収まりの事前確認： 情報量の多い表のセル、カードのタイトル／本文、サブタイトル、ボタンラベル、アイコンに隣接するラベルについて、PPTX の生成前にテキストの幅と高さを見積もります。以下の同梱ヘルパーを優先して使用してください。

python scripts/ppt_text_fit.py --text="升级方向不是少做事，而是更会定义、拆解、验收和复盘。" \
  --box 980x42 --font "Microsoft YaHei" --max-pt 22 --min-pt 12 --max-lines 1

返された recommended_pt と lines を使って、最初の PPT ビルドを設定します。高リスクのタイトルや複数言語が混在するラベルには、--target-pt <reference-size> も渡します。これにより、レポートに required_box_px と box_deficit_px が返され、適切な修正がフォントの縮小ではなくテキストボックスの幅または高さの拡張かどうかが明確になります。最終的な text_fit_report.json は簡潔に保ち、called、notfits、exceptions、および参照サイズとボックス不足量を含む代表的な高リスクの長文を記録します。デフォルトでは、正常に収まった短いラベルをすべて記録しないでください。失敗を調査している間だけ、図形ごとの詳細を一時的なデバッグデータに保持します。このヘルパーは、Windows のフォントファイル、スライドのエクスポート倍率、可視グリフのバウンディングボックス、CJK 対応の折り返し、二分探索、安全マージン、先頭がマイナス記号のテキストへの堅牢な argparse 処理、中国語や記号を含む JSON 出力向けの強制 UTF-8 標準出力に対応しています。ヘルパーを利用できない場合は、Microsoft YaHei／SimHei／Arial と同じロジックで PIL の ImageFont.truetype() を使用します。大まかな CJK 推定へのフォールバックは最終手段としてのみ使用してください。フォントのアセントとディセントの合計だけを行の高さの推定値として使用しないでください。これでは YaHei の不可視の余白が過剰に計上され、ラベルが小さくなりすぎます。

• テキスト引数の安全性： Python またはシェルから ppt_text_fit.py を呼び出すときは、--text <value> ではなく --text=<value> としてテキストを渡してください。これにより、マイナス記号、プラス記号、各種ダッシュ、矢印、括弧、記号を多く含む指標の接頭辞で始まる値が、コマンドオプションとして誤認されるのを防げます。ラッパーでサブプロセスの引数を構築する場合は、f"--text={text}" を1つの argv 項目として組み立ててください。
• テキストフィットの厳格な適用範囲： フィット処理を add_fitted_text() のような単一のラッパーに限定しないでください。add_run() 分岐、shape.text_frame の直接編集、表のセルテキスト、手作業で組み立てる数値指標、バッジラベル、分割されたタイトル／本文の run、グラフラベル、フッターノートなど、テキストを生成するすべての操作を対象とします。数値＋単位、英語の略語＋数値＋単位、符号付きの値＋単位、値＋傾向記号の組み合わせなど、サイズが混在する指標行では、まず表示されるフレーズ全体をバウンディングボックス全体に対してフィットさせ、その後、フィット済みの基準サイズから数値／単位の run サイズを導出するか、明示的なサブボックスで数値と単位をフィットさせます。作成中は、適用範囲を内部で追跡してください。最終的な簡潔版 text_fit_report.json には called、notfits、exceptions、代表的な key_long_texts を含めます。オブジェクトごとの詳細が必要なのは、失敗したテキスト、例外、高リスクの長文のみです。
• 手動 run の例外管理： 小さな装飾ラベル、ページ番号、意図的に固定サイズにしたバッジなど、ppt_text_fit.py を本当に使用できない場合は、バウンディングボックスと理由を添えて簡潔なレポートの exceptions に記録し、ローカルのレンダリング画像を切り抜いて確認してください。レポートに記録されていないハードコードされたテキストサイズは不備です。
• 参照行数の固定： フィット前に、元画像から目標の最大行数を導き出します。元画像で1行のラベルは1行に収め、2行のタイトルは2行のままにします。元画像でそうなっていない限り、手動の改行を入れて行数を増やさないでください。
• PPT のポイントからピクセルへの換算： 記憶ではなく、実際のエクスポート設定から計算してください。幅 13.333333 in のスライドを幅 1672 px で出力する場合、px_per_pt = (1672 / 13.333333) / 72 ~= 1.742 です。ヘルパーはこのスケールにレンダリング補正値を加えて適用します。スライドサイズやエクスポート幅が異なる場合は、--slide-px と --slide-in を渡してください。
• 役割ごとのテキスト階層： フォントサイズは柔軟にし、固定の数値範囲ではなく参照ページから導き出してください。タイトル、サブタイトル、カードタイトル、表見出し、表本文、ツール名、ラベル、注記の相対的な階層を維持します。同じ役割の他のテキストと比べて明らかに弱くなるサイズまで縮小しないと収まらない場合は、小さな文字サイズを黙って許容するのではなく、形状、余白、列幅、折り返しを調整してください。
• テキストスロットの形状固定： テキストボックスは元画像のグリフの黒い画素のバウンディングボックスではなく、そのフレーズに使える編集可能な領域全体として扱います。すべてのタイトル、1行の長いラベル、CJK とラテン文字が混在するフレーズについて、参照ポイントサイズを記録し、target_required_box_px／target_box_deficit_px を確認します。reference_scale が低い場合は、小さなポイントサイズを受け入れる前に、ボックス、アイコン用の空き領域、または余白を修正する必要があります。レンダリング画像の切り抜きで、元画像の視覚的なテキストの高さを維持してください。fits: true だけでは不十分です。
• 同等なチェックリスト行の扱い： チェックリストのすべての行を、固定の text_w × text_h ヘルパーに通さないでください。まずアイコン用の空きを確保し、その後、行ごとに残りのカード幅を割り当てます。CJK とラテン文字が混在する長い識別子では、より広いボックス、重複した余白の縮小、明示的な参照ポイントサイズが必要になることがよくあります。各1行のチェックリスト項目について reference_scale を報告します。0.90 未満の場合は、行スロットまたはカードの形状を修正し、結果を受け入れる前に隣接する行と切り抜きを比較してください。長い識別子を少し小さくしてよいのは、元画像でも同様に小さく表示されている場合のみです。
• はみ出し防止： 表本文は各セル内に収め、垂直の罫線から視覚的に少なくとも 10-16 px の余白を確保します。カード内のテキストは、まずアイコン用の空きを確保してから、残りのテキスト領域に対してフィットさせます。元画像で1行のラベルを意図せず折り返さないでください。複数行のラベルは、実際に確認できる行数と行間に合わせます。看 diff、看运行结果 のような CJK とラテン文字が混在するラベルは、CJK のみのテキストより幅を広く取ります。レンダリング前に、幅を広げるか、同じ役割にふさわしいサイズまで小さくしてください。
• カードテキストの中央揃え： ピル、ボタン、ワークフローカード、アイコン＋ラベルのカードでは、意図した視覚的な領域全体にテキストボックスを合わせ、垂直方向のアンカーを中央に設定します（MSO_ANCHOR.MIDDLE または同等の設定）。ベースラインの位置を目測して、小さなテキストボックスを配置しないでください。元画像で中央揃えの場合、カード本文は確保した領域内で垂直方向に中央揃えし、行数と行間も元画像に合わせます。
• 傾向矢印用の予約領域： ラベル、符号付きの値、単位、傾向の矢印／アイコンを組み合わせたコンパクトな指標行では、行をラベル、値、矢印／アイコンの各スロットに明確に分けてから、テキストをフィットさせます。フィット対象のテキストのバウンディングボックスに矢印用のスロットを含めないでください。カードの端から十分な余白を確保し、矢印は専用のスロット内に配置します。長いパーセンテージや数値と単位が混在する run に重なる可能性のある、絶対 x オフセットで傾向矢印を配置しないでください。こうした高密度の行は、納品前にローカル画像を切り抜いて確認してください。
• 傾向矢印の形状忠実性： 元画像に塗りつぶされた軸と三角形の先端を持つ太い傾向矢印がある場合は、テキストグリフ、細いコネクタ、矢印付きの線ではなく、UP_ARROW や DOWN_ARROW などの PowerPoint 標準矢印図形として作成します。矢印用に別のスロットを確保し、その横に編集可能な指標テキストを配置します。
• カードレイアウトの柔軟性： 繰り返し並ぶカードでも、カードごとに形状を上書きする必要がある場合があります。タイトルや中国語／英語が混在する本文が異なる場合に、仕切りの位置、テキストオフセット、本文幅の計算式をすべてのカードに強制適用しないでください。カードごとに仕切りの x 位置、本文ボックスの幅、アイコン用スロット、タイトル／本文のフォント倍率を調整し、ローカルの切り抜きで確認してください。
• 過度な縮小の防止： フィット後のテキストが使用可能な幅をあまり使わず、隣接する同じ役割のラベルより明らかに小さく見える場合は、同等の役割または参照サイズに近づくよう拡大してください。はみ出しの修正によって表の文字が不釣り合いに小さくなることがないようにしてください。
• ネイティブアルファのアイコンシート： ネイティブの透過 RGBA 出力を要求し、切り出し前にアルファモード、透明な角、アルファのバウンディングボックス、被写体の占有範囲を検証します。色の再設定や背景除去処理を行わず、このアルファを保持します。
• 汎用 N×M 切り出し： columns と rows のパラメーターを明示してグリッドを切り出す実装にしてください。アセット仕様数が columns * rows と一致することを検証し、これらのパラメーターからセルの境界を計算します。5×4 や 4×2 など、特定のグリッドをハードコードしないでください。グリッドの寸法、ソースパス、セルごとのバウンディングボックス、中央揃えの指標をアセットマニフェストに保存します。
• 重心を使った中央揃えの再配置： アルファに基づいて切り出した後、アルファのバウンディングボックスでクロップし、各アセットを正方形の透過キャンバスに再配置します。アルファの視覚的重心を中央に合わせます。再配置後の重心のずれを記録し、ほぼゼロに保ちます。バウンディングボックスだけを中央揃えする方法では、ターゲット矢印、人や星のグループ、光線のある頭部、虫眼鏡、幅広の傾向マークなど、非対称なアイコンには不十分です。
• アルファ画像の配置： 各透過 PNG のアルファのバウンディングボックスと重心を調べます。可視アルファの範囲を基準に拡大縮小し、重心を配置先スロットの中央に合わせたうえで、透過キャンバス全体を配置します。これにより、透過部分の安全な余白を維持しつつ、アイコンが縮みすぎたり、見た目上ずれたりするのを防げます。
• 複雑な視覚オブジェクトの配置： フローリボン、移行ストリーム、複雑なイラスト、情報密度の高い UI スクリーンショット、その他の複雑な画像が imagegen_asset に分類された場合は、デザインされた視覚レイヤーとして扱います。可能であれば編集可能なテキストを含めずに生成し、実際の RGBA に整えてから、測定した可視アルファの端を基準に配置します。中央の円、カード、タグ、凡例、吹き出し、ラベルなどのネイティブ編集可能オブジェクトは、その上に配置します。生成ソースの分割は、位置合わせに必要な意味上の領域（例：左側と右側のストリーム）に限定し、細かい各レーンや矢印の先端ごとには分割しないでください。
• アイコンの色に関する規約： 初回の画像生成プロンプトには、元画像に基づく色の役割を正確に含めます。各アセットについて、サンプリングまたは推定した 16 進数カラーを記録し、前景の線／塗り、内部の細部、背景またはホスト図形の色、およびその色がアイコン本体とコンテナのどちらに属するかを指定します。色が混在するグリッドでは、各セルの色を明示します。アセットマニフェストには、各アイコンの意図した色の役割またはサンプリングした 16 進数カラーの注記を含めます。色が一致しないアイコンは無効なアセットです。PPT に挿入する前に、再生成するか、正しい色で画像生成から作り直したバリエーションに置き換えてください。
• コンテンツグリッドの切り出し： 生成したアセットシートは、切り出し前に実際の C×R／N×M コンテンツグリッドを検出します。ネイティブアルファから前景マスクを作成し、X 軸と Y 軸に沿って前景ピクセルを集計し、列の中心を正確に C 個、行の中心を R 個検出します。その後、隣り合う中心の中点からセルの端を計算します。プロンプトでシート全体が均一なグリッドとして意図的に生成され、外側の余白に曖昧さがなく、検出で確認できた場合を除き、(0,0) から画像を等分するのではなく、検出した端を基準にセルを切り出します。検出された中心の数が宣言された列数／行数と一致しない場合は、シートを却下して再生成します。検出した中心、端、セルごとのバウンディングボックス、余白の検証失敗をアセットマニフェストまたはグリッド位置合わせレポートに保存します。
• 角丸長方形： ROUNDED_RECTANGLE を作成した後、shape.adjustments[0] を設定します。大きなパネルには小さめの値（0.025-0.04）、ピルやボタンにはやや大きめの値（0.06-0.10）を使用します。
• 長方形のように見える見出しのルール： 長方形に見えるセクション見出しやタイトルバーには、ネイティブの長方形または角丸長方形のみを使用します。元画像にはっきりと見られる場合を除き、装飾として三角形の尾、リボンの斜辺、シェブロン、フリーフォームのくさび形を追加しないでください。ribbon などの名前のヘルパーが余分な頂点を作成する場合は、通常のネイティブ長方形に置き換え、ローカル画像を切り抜いて確認してください。
• 効果の整理： PowerPoint の図形、画像、グラフ、コネクタは、元画像がフラットでもテーマ効果を引き継ぐ場合があります。元画像にその効果が明確に必要な場合を除き、各種類の図形を作成した後に、影、光彩、ソフトエッジ、反射、効果リストの XML を明示的にクリアします。保存前にスライド全体の効果を最終的に整理し、PPTX の XML に予期しない outerShdw、glow、softEdge、reflection ノードがないことを確認します。
• 線の節度： 作成に役立つという理由だけで、仕切り線、コネクタの線、パネルの枠線を追加しないでください。すべての線は、元画像に見える線に対応しているか、ネイティブの境界線として必要でなければなりません。線の太さと不透明度は控えめに合わせてください。線がスクリーンショットより濃く見える場合は、元画像にない視覚的なグリッドをそのまま残さず、線幅や色を弱めます。
• ツールボタン： 各ボタンは、ネイティブの角丸長方形、add_picture(icon_id, ...)、add_text(label, ...) を組み合わせて作成します。アイコン用スロット、テキストのオフセット、フォントサイズはラベルごとに調整します。
• 幅広のアイコン用スロット： 虫眼鏡、ループ、同期、人が輪になった図、矢印の多いアイコンは、正方形の記号よりも透過キャンバスやハンドル部分の幅が大きいことがよくあります。狭いカードでは、こうしたアイコンに小さめのスロットや左下寄りのスロットを設けるか、専用のバリエーションを用意し、可視アイコンと PPT の選択ボックスの両方がテキストに重ならないようにします。
• 滑らかな弧状矢印： 開いたフリーフォーム曲線を使う場合は、それぞれの可視弧を、ネイティブの線スタイルとネイティブの矢印先端を持つ1本のパスとして作成し、多数の独立した線図形で構成しないでください。PowerPoint の整数パス座標で弧がギザギザになったり階段状になったりしないように、PPT 座標に変換する前に内部座標の倍率を大きくします。使用できる場合は丸い線端／接合部を優先し、作成後は関連する弧のパスをグループ化します。
• 円グラフ／ドーナツと中央円の扱い： 円グラフ／ドーナツグラフ、放射状のダッシュボード、大きな円形 KPI ノードでは、まず外側のリング、主な塗りつぶし円、中空の中央、中央ラベル、アイコン、実際に存在するハイライトなど、目に見える役割をすべて列挙します。すべてのオーバーレイは、同じ測定済みの中心から導き出します。元画像が外側の線だけを示す場合は、塗りつぶさずに線のみで作成してください。元画像にはっきりと存在しない限り、装飾的なハイライトの楕円、光彩の円、白い背景円、余分な中央円盤を追加しないでください。中心部をぴったりと切り抜いた画像を添え、はみ出した円や中心からずれた円がないことを証明します。
• レイヤー順の確認： 作成とグループ化の後、図形をテキスト、画像アセット、ネイティブオブジェクトに分類します。**「ネイティブオブジェクトの内部順序を維持し、アイコンとテキストだけを前面に移動する」**という原則に従って作成します。具体的な不一致を修正する必要がない限り、ネイティブオブジェクトの既存の内部順序を維持します。すべてのネイティブオブジェクトを機械的に背面へ移動しないでください。色付きのピル、中央の塗りつぶし、前景の線が白いパネルやリングの背面に隠れることがあります。画像アセット／アイコンを前面に移動し、その後、すべてのテキストボックス／テキスト図形を最前面に移動します。意図的にグループ化されたネイティブの視覚要素は1つのオブジェクトとして維持します。ただし、それがアイコンでない限り、ネイティブオブジェクトのレイヤーにとどめてください。
• アイコンのレンダリングレイヤーの安全性： slide.shapes の列挙結果やオブジェクトの存在を、挿入した PNG アイコンがカードより前面にレンダリングされる根拠として信頼しないでください。PowerPoint は ppt/slides/slideN.xml の物理的なシェイプツリー順でレンダリングします。誤った _spTree.append()、insert_element_before()、または反復中に対象を変更するヘルパーによって pic ノードが後続の sp ノードより前に置かれると、PPTX に画像が含まれているにもかかわらず、アイコンが白いカードの背面に隠れることがあります。全体的な XML の変更より、コンポーネント内での作成順序を優先してください。全体的なレイヤー移動が必要な場合は、まず安定した図形参照を収集し、検証済みのヘルパーを1回使って移動してから、保存済みスライド XML の順序を確認し、最終スロットで各アイコンが見えることを証明するローカル画像を切り抜きます。
• アイコンが見えない場合の診断： レンダリング後の PPT でアイコンが見えない場合は、アセットを再生成する前に、アルファの完全性と Z オーダーを確認します。PNG がアルファ値の空でない RGBA であること、画像の寸法がゼロでないこと、pic ノードがカード／コンテナ図形の後かつテキストの前または意図した最前面にあること、ローカルのレンダリング画像を切り抜いたときにアイコンが見えることを確認します。アセットのコンタクトシートが正しいのにレンダリング結果が空白の場合、通常はレイヤー順の問題です。
• ローカル画像の切り抜きによる QA： レンダリング後、疑わしい領域を PIL で切り抜き、別々に確認します。ラベルの間隔が狭いスライド、右側のツールグリッド、下部のフィードバックバーがある場合は、最終納品前にこれを行います。
• アセットマニフェストによる証明： すべての imagegen_asset について、プロンプトの要約、入手可能な場合は生成元のパス、最終 PNG のパス、実施したクリーンアップ／切り出し操作を記載します。画像生成元がないアセットは、最終的なアイコン／複雑なアセットとして有効ではありません。

7. 納品前に検証する
   • 同梱のヘルパーを実行します。

python scripts/check_rebuild_assets.py --asset-dir path/to/assets

• 完了を宣言する前に、レンダリングされた PNG を開くか確認します。
• 簡潔な最終版の rebuild_execution_report.json を一度だけ書き込み、最終回答で出力がドラフトであることを明記して不足している証拠を説明しない限り、必須フェーズに未完了のものがないことを確認します。

実際の修復から得た教訓

• アイコンの一部が切れるのを防ぐため、生成するグリッド内で各アイコンがそれぞれのセルに完全に収まるよう必須条件とし、検証済みのグリッドセルで切り出してから、より大きな透明キャンバスにコンテンツを再配置します。
• 透過画像のネイティブ生成を必須のアセット作成手段とします。生成直後に RGBA モード、アルファ境界ボックス、四隅の透明性、不透明な被写体の占有範囲を検証し、切り出し、再配置、挿入の全工程で有効なアルファチャンネルを維持します。
• アイコンを切り出した後は、アルファ境界ボックスではなく、アルファの視覚的重心を基準に中央揃えします。エクスプローラーのサムネイルでは、PowerPoint より先にこの問題が見つかることがよくあります。非対称アイコンは余白チェックに合格していても、見た目には中央からずれていることがあります。
• 重心を基準に再配置した後、貼り付け位置を調整し、最終的なアルファ境界ボックスに必要な透明な端の余白が残るようにします。縦長の矢印やトレンドマークは、視覚的には中央に配置されていても上端に接することがあります。unsafe transparent padding (..., 0, ...) のようなアセットチェッカーのエラーには、PowerPoint での拡大縮小ではなく、再配置で対処します。
• チャットのプレビューや見かけ上のスクリーンショットの縦横比ではなく、実際の入力ファイルの寸法を基準にします。PIL で元画像を開き、size と aspect を記録し、何かを配置する前にその比率に基づいて PowerPoint のページサイズを選択します。1536×1024 の元画像には、12×8 in のスライドを使うと 128 px/in で正確に対応でき、水平方向に誤って引き伸ばすことを防げます。
• グリッドの切り出し処理は汎用性を保ちます。パラメーター化された columns × rows ／ N×M のロジックを使い、指定されたアセット数がグリッドと一致しない場合は失敗させます。新しいタスクに以前のスライドの 4×2 や 5×4 の定数を流用しないでください。
• 生成シートには、厳密なグリッドを指示していても、外側に余白が含まれていることがよくあります。実際のコンテンツの中心を先に検出し、その中心間の中点を境界として切り出します。画像の原点から単純に均等分割すると、アイコン全体が消えたり、端のセルが切れたりする一方、見た目にはもっともらしい一覧画像ができてしまうことがあります。
• 色の忠実度は、最初の画像生成時に指定する必要があります。前景色、コンテナー色、内部の詳細色、状態色が異なるアセットは、それぞれ別の対象として扱います。参照画像でアセットや状態ごとに特定の色が指定されている場合、汎用的なアイコン用パレットに頼らないでください。構造は正しく見えても色の役割が異なる一覧画像は、アセットシートとして不合格です。
• 「生成した」というだけでは不十分です。スクリプトで描画した PNG も手作業で作成した代替物であり、アイコンや複雑なビジュアルにこのスキルを適用する際の要件に違反します。まず画像生成モデルを使い、その後に生成画像を後処理します。
• アセットシートでは、隣接セルの断片がボタンアイコンに混入することがあります。切り出したアセットが余白チェックに合格していても、下部の弧、点、くさび形、部分的なマークなどの混入は、実際のグリッド作成または切り出しの不具合として扱います。グリッドのプロンプト、アルファ成分のクリーンアップ、または再切り出しのロジックを修正し、実際の PowerPoint の切り抜きを再レンダリングします。
• 生成アイコンシートの端のセルにも、内側のセルと同じ安全領域と余白を確保します。端のセルの切れ、はみ出し、セル間の重なりがあるグリッドシートは使用しないでください。
• Windows エクスプローラーのサムネイルでは、PowerPoint より先に端の問題が見つかることがあります。サムネイルの一部が切れている場合は、実際のアセットの不具合として扱います。
• 通常の単独矢印、直線コネクタ、単純な山形矢印はネイティブの図形で作成できます。流れるようなリボン矢印、移行の流れ、グラデーションの矢印帯、複数レーンの矢印システム、矢じりが融合した流れは、画像生成モデルで透明な複雑ビジュアルアセットとして生成し、その上にネイティブのテキストや周囲のオブジェクトを維持した状態で PPTX に重ねます。
• 縦または横に並んだカード間のステップフロー矢印は、必ずしもコネクタ線ではありません。元の矢印が塗りつぶされたコンパクトなブロック矢印なら、塗りつぶしのネイティブ矢印図形を使い、カード間の見える隙間に配置します。矢印の端を次のカードの枠線に接触させたり、その下に隠したりしないでください。後から作成したカード図形がコネクタの矢じりを覆い、レンダリングで矢印が消えたように見えることがあります。
• PowerPoint の既定値によって、方向に依存する図形が視覚的に逆向きになることがあります。漏斗の各段階について、上端と下端の幅および傾斜の向きを参照画像と照合します。組み込み図形の向きが違う場合は、回転するか、編集可能なネイティブのフリーフォームとして作り直し、既定の向きをそのまま使わないでください。
• テキストのフィットは、おおよその座標だけで対処するのではなく、最初のレンダリング前に済ませます。参照画像の階層構造に基づいて事前にフィットを確認し、その後、レンダリングした PowerPoint とローカルの切り抜きをチェックします。ボックスの幅を広げる、列を調整する、フォントサイズを小さくするのは、隣接するテキストと同じ視覚的役割を保てる場合に限ります。
• PowerPoint のテキストは、単純なピクセル数の推測よりも幅や高さが大きくなるのが一般的です。最初の作成での失敗は、スクリーンショットのピクセル数からフォントサイズを推測したことが原因である場合がよくあります。PPTX を作成する前に、実際に書き出したピクセル境界ボックス、フォント、太字の設定、参照画像の行数を使って scripts/ppt_text_fit.py を実行します。
• ppt_text_fit.py を呼び出すとは、ルールを覚えて適用するだけでなく、実際に実行して簡潔な証拠を保存することを意味します。通常の実行では、called、notfits、exceptions、長いテキストの主要なサンプルを含む簡潔な text_fit_report.json で十分です。具体的なオーバーフローを修正する場合に限り、オブジェクトごとのデバッグ情報を追加します。
• 先頭がマイナス、プラス、ダッシュ、矢印、かっこなどの記号で始まるメトリックテキストは、argparse でよく問題になります。検証時には、符号付きの値、トレンド矢印付きの語句、かっこ付きラベル、数値と単位が混在する文字列を必ず代表例として含めます。ヘルパーの標準エラー出力に起因する JSON 解析例外や、空の標準出力がレポートに含まれていてはいけません。
• ppt_text_fit.py は Windows 上で UTF-8 の JSON を出力する必要があります。中国語のテキスト、記号、順位を示す字形のために、呼び出し側で毎回 PYTHONIOENCODING を設定する必要があってはいけません。標準出力のエンコーディングはヘルパー側で処理します。
• テキストのフィット確認用の証拠には、手動で実行した処理も含めます。数値が混在するメトリックや分割されたラベルは、add_fitted_text() を経由しないため、オーバーフローのよくある原因になります。実行を追加する前に、表示される語句全体または宣言したサブボックスをフィットさせ、最終的な PowerPoint に追跡されていないテキスト生成コードの経路が残っている場合は QA を失敗とします。
• CJK フォントの割り当ては、PowerPoint の書き出し後も維持される必要があります。レンダリングでセリフ体や宋体のような字形が表示された場合は、実行 XML の a:latin、a:ea、a:cs の書体を設定します。
• 再利用するタグやボタンのコンポーネントでは、ラベルごとに上書き設定が必要です。ラベルに英語と中国語が混在する場合は、ローカルの切り抜きを確認し、最終納品前に font_size、text_offset、または幅を調整します。
• PowerPoint の角丸長方形は、過度に大きなカプセル形状になることがあります。大きなパネル、カード、小さなツールボタンでは、必ず角の半径を調整してレンダリングを確認します。
• 矩形のセクション見出しが、既定でリボンになるわけではありません。タイトル帯が青い長方形にしか見えない場合は、ネイティブの長方形または角丸長方形として作成します。余分な三角形の端は視覚的な欠陥になります。
• 右側のツールパネルは編集可能な状態を保ちます。ネイティブの角丸ボタン、生成したアイコン PNG、個別のテキストラベルを使います。
• 選択ウィンドウの一番下に、スライド全体を覆う白い長方形を残さないでください。これはページ背景に図形を使った場合に発生することがよくあります。単色の背景にはネイティブのスライド背景の塗りつぶしを使い、編集可能なオブジェクト一覧をすっきり保ちます。
• 薄い装飾用の円環は、増やしすぎやすい要素です。ユーザーから余分な灰色の円が見える場合は、楕円の数を減らし、透明度を上げ、影を消します。参照画像で見える円環だけを残します。
• 円形のワークフローでは、編集可能な状態を保ちながら参照画像に近づける方法として、コネクタ曲線よりフリーフォームの円弧矢印が適している場合があります。表示される各円弧は、矢じり付きの連続したネイティブの円弧またはフリーフォームパスにします。パスをグループ化してもかまいませんが、短い直線セグメントを積み重ねる方法は使いません。
• 角丸の破線フィードバックループでは、まず、ネイティブの破線スタイルとネイティブの終端矢印を使った、編集可能な単一の開いたフリーフォームパスを試します。選択ウィンドウを最もすっきり保ち、編集可能性も維持できます。PowerPoint の組み込みコネクタは直線、折れ線、曲線のみなので、複数の折れ曲がりが必要なループにはフリーフォームパスを使います。きれいにレンダリングされない場合に限り、直線部分はネイティブの破線コネクタ全体で、折れ曲がり部分は分割したものに切り替えます。
• カードやピル型ラベルの位置は、見た目の偶然ではなく、図形の寸法を基準に中央揃えします。ピル型やカード型のテキスト領域全体を使い、垂直方向の中央揃えを設定してから、切り抜きをレンダリングします。テキストの位置が上下にずれている、または切れている場合は、フォントサイズを変える前にテキストボックスとアンカーを修正します。
• テキストのはみ出しは、カードの枠線を数ピクセル越えるだけでもレイアウトの不具合として扱います。同じ種類のカードでも、すべてのカードのフォントを一律に小さくするのではなく、各カードの区切り線、本文の幅、複数言語が混在するテキストのサイズを個別に調整します。
• トレンド矢印付きの情報量が多いメトリックカードは、要素が重なりやすくなります。まず矢印用の領域を確保し、残りのテキストボックスだけでラベルや値をフィットさせます。参照画像の同じ行に長い割合、符号、単位、上向き・下向きの矢印がある場合は、切り抜きを確認します。
• 数値と単位を並べた KPI カードの幅が足りず、全体をフィットさせると折り返しが発生したり、フォントが極端に小さくなったりする場合は、数値と単位など、編集可能なサブボックスに分けます。各サブボックスを ppt_text_fit.py でフィットさせ、1 行の視覚要素として整列させ、両方のサブボックスを text_fit_report.json に記録します。1 行の参照メトリックに対して、line_count: 2 のようなヘルパー出力を許容してはいけません。
• 塗りつぶしのトレンド矢印はテキストではなく図形です。テキストの矢印は細すぎたり、フォントに左右されたりすることがあります。元の矢印が明らかに太い場合は、塗りつぶしのネイティブ矢印図形を使います。
• 塗りつぶしのプロセス矢印は、コネクタの線種ではなく図形です。end_arrowhead を設定したコネクタは、細い線としてレンダリングされたり、カードの境界で三角形の矢じりが消えたり、重ね順によって隠れたりすることがあります。カード間の縦または横のプロセスステップでは、カード間の隙間に矢印用の領域を確保し、塗りつぶしのネイティブ矢印図形を作成して、レンダリングした切り抜きを確認します。
• 矢印の形状を忠実に再現するには、単に「左・右・上・下を向いている」だけでは不十分です。コンパクトなフック形、U ターン、フィードバック、ループ、注釈付きコールアウトの矢印はすべて、尾と先端、パスの種類、ループの向き、線幅または塗りつぶしの太さ、境界ボックス、付随するラベルを確認します。ネイティブの U ターン図形は、既定の向きが予想外の場合があります。選択する前に、使用するサイズで 4 方向すべてに回転させてレンダリングします。参照画像に合う候補がなければ、直線矢印で代用したり、作成用の線分を積み重ねたりせず、矢じり付きの連続した編集可能なフリーフォームまたは円弧パスを使います。
• 矢印とラベルを含む切り抜きの QA：ラベルが近くにある矢印は、ひとつの視覚要素として扱います。パス全体、矢じり、ラベル、隣接する境界を含む範囲をぴったり切り抜いて保存し、納品前に同等の参照画像の切り抜きと比較します。流れの意味が正しくても、パスの形状やラベルの位置が元画像と異なるコールアウトは許容しません。
• ドーナツ、放射状グラフ、KPI の中央に重ねる要素は、目視で位置を調整せず、グラフまたはプロットの中心、あるいは円の境界ボックスを基準に計算します。グラフサイズ、穴のサイズ、コールアウトラベル、中央ノードのサイズを変えた後は、同じ座標を基準に重ねた円とテキストを中央に配置し直し、切り抜きを厳密に確認します。よくある不具合は、outer_ring、center_white、highlight などのヘルパーの再利用によって、意図しない余分な白い円やハイライト円ができることです。参照画像で明示的な役割が確認できない中央の円は削除します。
• テーマ効果は、忠実度を誤って判断させる隠れた要因です。元画像が主にフラットなデザインであれば、既定の影や効果を全体的に解除します。PowerPoint の控えめな影でも、カード、矢印、見出しが余分なオブジェクトのように見えることがあります。
• 効果のチェックでは、スライド XML だけでなく、ppt/theme/theme1.xml を含むすべての PPTX XML パーツを調べる必要があります。テーマレベルの outerShdw ノードは、スライド図形に影が明示されていない場合でも残ることがあります。正しい XML の書き換え、または <a:outerShdw\b...> のような検証済みの正規表現で削除し、その後、outerShdw、glow、softEdge、reflection の件数がすべてゼロであることを再スキャンして確認します。
• Windows では、PPTX を shutil.move で置き換える前に、tempfile.mkstemp() が返すファイル記述子を閉じます。そうしないと、PowerPoint が原因でなくても、クリーンアップの段階で WinError 32 が発生することがあります。また、同じ PPTX を再構築または上書きする前に、COM プレゼンテーションを閉じて PowerPoint を終了します。
• 作成時に使った余分な線は、不具合であり、無害な装飾ではありません。参照画像に明確にある場合に限り、区切り線や補助的な枠線を残し、レンダリングした切り抜きを見て線の太さと色を調整します。
• 重ね順は忠実度の一部です。PowerPoint のレンダリングでテキストやアイコンが切れている、薄い、隠れている、または見つからない場合は、内容を変更する前にスライドの実際のレイヤー順を確認します。最終的な標準の重ね順は、テキスト、アイコンや画像、ネイティブのコンテナー・矢印・線の順にしつつ、ネイティブレイヤー内の前景と背景の順序は維持します。アセットの一覧画像がきれいなだけでは不十分です。アイコンが正しく見えることを、レンダリングした PowerPoint の切り抜きで確認する必要があります。
• 出力 PPTX が開かれてロックされている場合は、ユーザーのアプリを強制終了したり、開いているファイルを上書きしたりせず、新しいバージョン番号付きのファイル名で保存します。
• PowerShell で *.png のようなワイルドカードを使ってコピーする場合は、Copy-Item -Path を使います。-LiteralPath はワイルドカードを展開しないため、QA 用の切り抜きや最終的なアイコンアセットが納品物から漏れることがあります。

納品物

最終的な .pptx のパスに加え、生成した場合は以下も返します。

• レンダリング済みの PNG プレビュー。
• 生成した透過アイコン PNG を含む assets/ フォルダー。
• アセットのマニフェストまたはビジュアル一覧。

残っている制限事項があれば明記してください。特に、複雑なアイコンが完璧なベクターでの再現ではなく、生成による近似である場合は、その旨を明記してください。