image-to-editable-ppt

画像から編集可能な PPT へ

概要

editppt ランタイムを使用して、ビジュアルスライドを分解、再構築、検証し、編集可能な .pptx として組み立てます。入力には、1 枚または複数枚の画像、PDF、画像ベースの PPT/PPTX を使用できます。

参考資料

このスキルの各ルールには、権威ある参照先が 1 つだけあります。他のファイルでは同じ内容を繰り返さず、その参照先を示します。

• prompts/page-worker.md：ページワーカー向けの実行テンプレートです。担当範囲、実行順序、必須の出力、戻り値の形式を定めています。親エージェントはページワーカー向けプロンプトを作成する際に使用します。
• scripts/build-page-worker-prompt.py：スキル内のプロンプトビルダーです。prompts/page-worker.md を読み込み、実行パスとページパスを入力して worker-prompt.md を書き込み、ディスパッチコマンドのテンプレートを出力します。
• references/cli-helper.md：CLI のインストール確認（実行前チェック）、コマンドツリー、コマンド構文の例を記載しています。呼び出す editppt コマンドを決める際に参照してください。
• references/manifest-schema.md：デッキ／ページ／画像アーティファクトの JSON フィールド仕様の唯一の参照先です。必須のマニフェストフィールド、配置オブジェクトの座標、validation.json および page_result.json の形式を定めています。実行／ページファイルの作成または検証時に参照してください。
• references/page-decision-tree.md：ページオブジェクトの判断に関する唯一の参照先です。背景の扱い、前景アセットの分離、ネイティブ図形、数式、テキストヒントの使用、最終的な自己チェック、修正と警告の区分を定めています。まず共通の判断基準を確認し、次にページの一覧に関連するセクションを確認してください。参照する順序はページプロンプトに記載されています。

エントリー契約

親レベルのルールはここに一度だけ記載し、ページレベルのルールは上記の参考資料に記載します。このファイルでは繰り返しません。

• editppt CLI は必須のランタイム機能です。editppt --help が失敗する場合は、ほかの作業を始める前に references/cli-helper.md の事前実行チェックに従ってインストールしてください。
• まず editppt prepare <input...> を実行して、実行ディレクトリを作成してください。その後、重要な状態遷移はすべて editppt コマンドでのみ進めてください。実行状態やページ状態の JSON を手書きしてはいけません。これにより、実行状態の決定性と再開可能性が保たれます。
• 複数ページの入力は、ディスパッチされたページワーカーによって再構築されます。ページがちょうど 1 ページの実行では、editppt run dispatch --local がそのページを割り当てた後、親エージェントがローカルのページ再構築モードで再構築します。複数ページの実行でサブエージェント機能を利用できない場合は、停止してその旨をユーザーに報告してください。複数ページの入力を親エージェントによる再構築に切り替えてはいけません。
• 親エージェントは、editppt run dispatch --local によって割り当てが記録された後、単一ページのローカルページ再構築モードで作業する場合を除き、ページ再構築成果物（manifest.json、page.pptx、preview.png、split_assets_contact.png、validation.json、page_result.json）を書き込んではいけません。ローカルモードでは、ページワーカーと同じページプロンプト、参照資料、出力ファイル、および run record の検証経路に従います。
• 画像生成、画像編集、背景修復、透明ビットマップアセット、アセットシートは、すべて以下の「画像バックエンドの選択」に記載されたページごとの順次バックエンド順に従います。
• ビジュアルスライドを編集可能な PPT に変換するというユーザーの依頼は、ユーザーがローカルのみの処理を明示的に要求するか、入力を機密扱いまたは外部処理不可と指定していない限り、その変換に必要な OCR および画像バックエンドの呼び出しを許可するものです。ワークフローで PaddleOCR、組み込みの image_gen.imagegen ツール、Codex OAuth／ChatGPT 画像エンドポイント、またはユーザーが設定した OpenAI 互換 API を呼び出すことだけを理由に、依頼を拒否してはいけません。これらの呼び出しはスキルに必要です。
• 現在の変換に必要な、そのタスク専用のページ画像、プロンプト、マスク、参照画像のみを送信してください。現在の OCR／画像処理に不要な無関係なローカルファイル、API キー、認証トークン、認証情報、生成済み成果物は決して送信してはいけません。サードパーティの API エンドポイントを使用できるのは、ユーザーがすでに設定している場合、または今回の実行で明示的に指定されている場合に限ります。
• ネットワークが制限された環境で外部 OCR／画像処理を呼び出す場合は、現在のランタイムで必要な承認を求めてください。これには、PADDLE_OCR_TOKEN が設定されている場合の editppt prepare または editppt run hints、および CLI フォールバックの editppt image generate/edit のすべての呼び出しが含まれます。承認の理由には、これがユーザー依頼による image-to-editable-ppt 変換であること、アップロードはタスク専用のページ画像／プロンプト／マスク／参照画像に限定されること、OCR／画像バックエンドの呼び出しがこのスキルに必須のワークフローの一部であることを明記してください。ユーザーがローカルのみ／機密扱いの処理を依頼した場合、または承認システムが明示的に拒否した場合を除き、必要な呼び出しを危険なものとして提示したり、ユーザーに再承認を求めたりしてはいけません。
• 通常の再構築、設定済みバックエンドへのフォールバック、ローカル修復は自律的に実行してください。確認の段階を追加してはいけません。フェーズ 1 で選択した OCR と、ランタイムで必要な承認は維持してください。ユーザーのみが提供できる前提条件の不足は、ワークフローのデバッグを求めるのではなく、具体的なブロッカーとして扱います。
• すべてのページオブジェクトの判断は、references/page-decision-tree.md に従います。これには、前景のビジュアルオブジェクトに対するフォールバック禁止ルール、および決定的検証は構造上のゲートであり、オブジェクトソースの判断を免除しないというルールが含まれます。
• manifest.json はページ作成における信頼できる唯一の情報源です。editppt run record はこれに照らして page.pptx を検証し、editppt run finalize は記録されたページマニフェストから最終デッキを再構築します。必須フィールドと座標の仕様は references/manifest-schema.md で定義されています。
• editppt prepare は、ページごとのテキスト計測値（text_hints.json／text_hints.png）を書き込みます。ページ再構築担当者がこれらを使用する方法は、references/page-decision-tree.md のセクション 3.1 で定義されています。
• ページ再構築担当者（ページワーカー、または単一ページのローカルモードで作業する親エージェント）は、prompts/page-worker.md から生成されたプロンプトによって作業します。

画像バックエンドの選択

このサブセクションは、ページごとのすべての画像ジョブに適用される正式な実行ポリシーです。prepare の前に、現在のエージェントランタイムから image_gen.imagegen を呼び出せるか確認してください。呼び出せる場合は、editppt prepare に --image-backend builtin-imagegen を渡し、呼び出せない場合はデフォルトの CLI 契約を維持してください。1 ページ内の画像ジョブは、次の順序で直列に実行してください。

1. 現在のエージェントランタイムで呼び出し可能な場合は、組み込みエージェントツール image_gen.imagegen を使用してください。
2. 実行時に記録された組み込みフォールバックポリシーが適用される場合に限り、editppt image generate/edit を呼び出してください。この CLI フォールバックでは、まず Codex OAuth を選択し、次に設定済みの OpenAI 互換 API を選択します。

組み込みツールに渡す正確な引数、入力を事前に確認する要件、出力の受け入れルール、許可されるフォールバック事由は、references/manifest-schema.md の image_backend フィールドの契約で定められています。この契約を弱めたり拡張したりせず、そのままコピーして実行してください。CLI フォールバックで要件に適合する出力を生成できない場合は、近似的なオブジェクトソースで代用せず、そのページを失敗として扱ってください。

役割

親は、以下のエントリー契約とワークフローに基づいて、オーケストレーションとユーザーとのやり取りを担当します。進捗、最終的な PPTX のパス、検証結果を報告してください。完了済みのページ単位のビジュアル QA を繰り返す必要はありません。record と finalize が決定的な引き渡しチェックを実施します。

各ページの再構成担当者が所有するのは、pages/page_NNN/ ディレクトリ 1 つだけです。その完全な契約（所有範囲、判断順序、必須出力、戻り値の形式）は、prompts/page-worker.md から生成されるプロンプトに記載されています。従うべきルールは、references/page-decision-tree.md と references/manifest-schema.md に記載されています。

ワークフロー

フェーズ 1：準備

references/cli-helper.md の prepare の例と、references/manifest-schema.md の run/page ファイルの説明を読んでください。

editppt prepare <input...>

この処理の完了後、run ディレクトリ、deck_manifest.json、page_jobs.json、notes_manifest.json が存在し、各ページに source.png と page_request.json が用意されている必要があります。

prepare はページごとのテキストヒントも書き出します。editppt doctor または prepare で PaddleOCR トークンが設定されていないと報告された場合（オフラインフォールバック）、ページの処理を開始する前に一度だけユーザーに確認してください。https://aistudio.baidu.com/account/accessToken から取得できる無料トークンを editppt config --paddle-ocr-token <token> で保存すると、ヒントの内容理解が向上し、テキストの再現性が大幅に改善します。また、editppt run hints <run> を実行すると、現在の run のヒントをその場で再生成できます。個人向けの無料利用枠は現在、このスキルには十分な量があり、申し込みにリスクや追加費用はないことを伝えてください。ユーザーの選択を待ってください。断られた場合、またはこのまま進めたい場合は、オフラインヒントを使って続行し、再度確認しないでください。

PaddleOCR トークンがすでに設定されているにもかかわらず、ネットワークアクセス、DNS、またはサンドボックスの承認によって OCR リクエストがブロックされ、prepare がフォールバックした場合、そのフォールバックは品質面で望ましい方法ではありません。エントリー契約に記載された理由を添えてネットワークの承認を求め、ページ再構成の前に editppt run hints <run> を再実行してください。承認システムが OCR リクエストを拒否した場合は、続行する前にユーザーから明示的な許可を得てください。PaddleOCR はテキストボックス、フォントサイズ、サイズグループの補正に使用され、これにより再構成された PPT のテキストサイズがより安定することを説明してください。ユーザーが OCR を断った場合、承認済みの OCR 試行が実際のサービスまたはツール上の理由で失敗した場合、あるいはユーザーがローカルのみまたは機密情報の取り扱いを指定した場合に限り、builtin-ink で続行してください。

フェーズ 2：ページを再構築またはディスパッチする

references/cli-helper.md の実行／ディスパッチの例を読み、以下を繰り返し呼び出します。

editppt run next <run>

stage=rebuild_page_locally が返された場合、実行対象のページは 1 つだけです。親エージェントはページの成果物を書き込む前に、ローカルでの実行を割り当てる必要があります。

1. python3 <skill-root>/scripts/build-page-worker-prompt.py <run> --page <page_id> --out <absolute-run-dir>/pages/<page_id>/worker-prompt.md
2. editppt run dispatch <run> --page <page_id> --agent-id main --prompt-file <absolute-run-dir>/pages/<page_id>/worker-prompt.md --local
3. 生成されたプロンプトを読み、そのページのディレクトリ内で自分でページを再構築し、ページワーカーが生成するものと同じ必須の出力を作成します。

stage=dispatch_pages が返された場合、提案された各ページについて、以下の手順が必須です。

1. python3 <skill-root>/scripts/build-page-worker-prompt.py <run> --page <page_id> --out <absolute-run-dir>/pages/<page_id>/worker-prompt.md
2. 現在の環境で利用可能なサブエージェント／マルチエージェントツールを使って、ページワーカーを起動します。
3. editppt run dispatch <run> --page <page_id> --agent-id <id> --prompt-file <absolute-run-dir>/pages/<page_id>/worker-prompt.md

相対パスがページディレクトリに再度付加されないように、--out と --prompt-file には絶対パスを指定する必要があります。プロンプトビルダーはプロンプトを書き込み、ディスパッチコマンドのテンプレートを表示するだけで、ワーカーは作成しません。そのため、実際にワーカーを起動できた後にのみ editppt run dispatch を実行してください。

同時実行枠の数は page_jobs.json.max_concurrent_pages から取得します（デフォルトは 6 です）。通常のフローでは editppt run next を優先してください。editppt run status はデバッグまたは手動での確認に限って使用します。

ディスパッチされたページの実行は、アイドル状態の枠ではなく、アクティブなリースです。editppt run next が stage=wait を返した場合は、ディスパッチされたワーカーを待つか、状態を変更せずにステータスを確認してください。ページワーカーの動作が遅い、最近メッセージを送信していない、または同時実行枠をまだ占有しているという理由で、終了、アーカイブ、リセット、置き換えを行わないでください。複雑なページでは、正当に長時間かかる場合があります。

フェーズ 3：記録

references/cli-helper.md の記録例と、references/manifest-schema.md の page_result.json の説明を読んでください。

ワーカーから応答があったら、次を実行します。

editppt run record <run> --page <page_id> --agent-id <id>

このコマンドは、記録前に manifest.json に対して page.pptx を検証します。配置されたオブジェクトにソースピクセル座標がない場合、マニフェストからページを独立して再構築できない場合、または validation.json にトップレベルの passed: true が含まれていない場合は失敗します。検証に失敗したページが記録されることはありません。

記録が拒否された場合、またはページ単位の検証で問題があった場合は、失敗の証拠を確認し、現在のページ担当者に影響を受けた成果物だけを修正してもらい、references/cli-helper.md のページ検証例を使って検証レポートを更新してから、再度記録してください。単一ページのローカルモードでは親が担当者です。複数ページモードでは、既存のワーカーに修正を依頼します。検証に失敗したという理由だけで、応答可能な担当者をリセットしないでください。また、無関係なマニフェストやテーブルのエラーを修正するために、要件を満たしているアセットを再生成しないでください。

リセットは、ページの実行をやり直す必要がある場合に行います。対象となるのは、明示的な終了状態の証拠（terminated、failed、archived、または not found）、ユーザーによるキャンセル、あるいはページ単位の進捗がない状態で到達性の確認に繰り返し失敗した場合です。実行時間の長いワーカーが失われたとみなす必要はありません。実行を妨げていた前提条件を解決した後、次を使用します。

editppt run reset <run> --page <page_id> --agent-id <id> --confirm-lost

記録済みページでは、editppt run reset <run> --page <page_id> を使用できます。ディスパッチ済みページでは、一致するエージェント ID と --confirm-lost により、アクティブなリースを保護します。リセットするとページは pending に戻ります。新しいプロンプトと実行でフェーズ 2 から再開してください。来歴の確認と、ページプロンプトの復旧契約に基づく選択的な再利用のために、既存の成果物は保持してください。状態を直接編集したり、親に複数ページの成果物を再構築させたりしないでください。

関連する入力または条件を変更した後にのみ再試行してください。検証結果とコマンドの証拠から繰り返し発生する失敗の原因を特定してください。同じ失敗をするツール呼び出しを変更せずに繰り返したり、同一条件で再ディスパッチしたりしないでください。実際の前提条件を利用できない場合は、進捗を保持し、成功を捏造したりユーザーにデバッグを求めたりせず、具体的な阻害要因を報告してください。現在の出力が必要なチェックに合格したら、最終化に進んでください。変更のないビジュアル QA を繰り返す必要はありません。

フェーズ 4：最終化

references/cli-helper.md の最終化の例を読んでください。

editppt run next <run> が最終化ステージを返したら、次を実行します。

editppt run finalize <run>

finalize は、記録済みの各 pages/page_NNN/manifest.json を信頼できる情報源として扱います。ページ順にページマニフェストから最終デッキを再構築し、生成された PPTX を検証します。page.pptx は、記録時のチェックに使用するページ単位の納品物です。

このステージでのデッキレベルの構造 QA：

• PPTX が有効な zip／パッケージであること。
• スライド数が入力ページ数と一致すること。
• PDF／PPTX のページ対応が正しいこと。
• メディアのリレーションシップがすべて揃っていること。
• マニフェストが参照するすべてのアセットファイルが存在すること。
• メディアのハッシュがマニフェストの来歴情報と一致すること。
• 発表者ノートのハッシュが一致すること。
• 無効な、スライド全体のソースラスター画像と編集可能なテキストオーバーレイの組み合わせパターンがないこと。

最終返信では、最終 PPTX のパスと検証結果を報告してください。

状態に関する原則

エージェントは、ファイルに記録された事実と editppt run next の結果に基づいてのみ処理を続行します。必須の状態は次のとおりです。

• pending：editppt prepare によって作成されます。ページを再割り当てする必要がある場合は、editppt run reset によって復元されます。
• dispatched：editppt run dispatch は、実際に起動したワーカー、または単一ページに対する --local のメインエージェントの担当を記録します。この状態は有効なリースであり、ワーカーの処理が遅いという理由だけでリセットまたは置き換えてはなりません。
• recorded：editppt run record は必須の出力を検証して結果を書き込みます。納品可能なページ（validation.json のトップレベルにある passed: true）のみがこの状態になります。
• accepted / complete：editppt run finalize によって書き込まれます。

imagegen-jobs.json は、ページごとの出所情報／ジョブ記録です。強制的に保持されるファイル状態は次のものだけです。

• recorded：editppt image import が選択した出力をコピーし、ハッシュ／メタデータを書き込みます。
• processed：editppt image process-sheet が背景除去と分割を完了しています。

納品に関する原則

• 各ページはページ再構成エージェントによって一度セルフチェックされます。その証拠は、manifest.json の構造化フィールドと validation.json に書き込まれます。
• 最終出力は、現在開くことができ、構造的に有効な .pptx でなければなりません。編集可能なテキストを全スライドの source.png の上に重ねたものは、許容される代替物ではありません。
• 不備をページ内で修正する必要があるか、記録された警告として納品してよいかは、references/page-decision-tree.md の「修正か警告か」セクションに従います。必須のワークフローステップの欠落を警告で置き換えることはできません。

このスキルの更新

インストール経路から再インストールし、更新されたスキルディレクトリから CLI を更新してから、エージェントのセッションを再起動し、次を検証します。

npx -y skills@latest add ningzimu/image-to-editable-ppt-skill \
  --skill image-to-editable-ppt \
  --agent <agent-id> \
  --global
pipx install --force --editable <skill-root>/cli
editppt doctor