prompt-api

Prompt API

手順

ステップ 1：統合する箇所を特定します

1. ワークスペースを調べ、ブラウザーのエントリーポイント、UI ハンドラー、既存の AI 抽象化レイヤーを確認します。
2. Node ランタイムを利用できる場合は、node scripts/find-frontend-targets.mjs . を実行して、有力なフロントエンドファイルと既存の Prompt API の使用状況を一覧にします。
3. Node ランタイムを利用できない場合は、最も近い package.json、HTML エントリーポイント、フレームワークのエントリーファイルを手動で調べ、ブラウザーアプリの境界を特定します。
4. ワークスペースに複数のフロントエンドアプリが含まれている場合は、アクティブなルート、コンポーネント、またはユーザーが指定した機能の箇所を含むアプリを優先します。
5. 一覧を確認しても有力なフロントエンドの候補が複数残る場合は、いったん作業を中止し、Prompt API をどのアプリに統合するかユーザーに確認します。
6. プロジェクトがブラウザー向けの Web アプリでない場合は、いったん作業を中止し、このスキルの対象外であることを説明します。

ステップ 2：Prompt API が利用可能か確認します

1. コードを書く前に references/prompt-api-reference.md を読みます。
2. 機能にテキスト、マルチモーダル、プレフィックス、またはツール対応セッション向けの仕様に準拠したメッセージ形式が必要な場合は、references/examples.md を読みます。
3. 複数世代のブラウザーをサポートする必要がある場合や、ネイティブサポートとポリフィルのどちらを選ぶか判断する必要がある場合は、references/compatibility.md を読みます。
4. Prompt API または Task API のポリフィルについて、具体的なパッケージのインストール方法やバックエンドの設定例が必要な場合は、references/polyfills.md を読みます。
5. セキュアなウィンドウコンテキストで機能が実行されること、および language-model 権限ポリシーで現在のフレームからのアクセスが許可されていることを確認します。
6. 統合を Web Worker やその他の非ウィンドウコンテキストで実行する必要がある場合は、いったん作業を中止し、プラットフォーム上の制約を説明します。
7. 機能に必要なセッション形式を選択します：prompt()、promptStreaming()、initialPrompts、append()、measureContextUsage()、または responseConstraint。機能にツール呼び出しが必要な場合は、仕様上 tools は EXPERIMENTAL（実験的なコンテキストのみ）であることに留意し、機能検出で制御するか、オリジントライアルまたは拡張機能のコンテキストに限定します。
8. プロジェクトで TypeScript を使用している場合は、プロジェクトで使用する Prompt API の範囲を網羅する型定義を追加するか、維持します。

ステップ 3：ガード付きセッションラッパーを実装します

1. assets/language-model-service.template.ts を読み、ワークスペースのフレームワーク、状態モデル、ファイル構成に合わせて調整します。
2. 機能の実行時に使用するものと同じ作成オプション（想定されるモダリティを含む）を使い、LanguageModel.availability() によってセッション作成を制御します。ポータブルなページコードでは tools は EXPERIMENTAL のため、availability() に渡さないでください。
3. モデルのダウンロードまたはインスタンス化が始まる可能性がある場合は、ユーザー操作後にのみセッションを作成します。
4. キャンセル可能なプロンプトには AbortController を使用し、セッションが不要になったら destroy() を呼び出します。
5. 機能をクロスオリジンの iframe で実行する場合は、埋め込み側の iframe に allow="language-model" を指定します。
6. params()、topK、または temperature に依存しないでください。仕様では topK と temperature が DEPRECATED（拡張機能のコンテキストのみ）とされているため、ポータブルな Web ページへの統合ではこれらを必須にしてはなりません。
7. availability() は受動的な機能確認として扱います。ユーザー操作前に downloading を返した場合、現在のページがそのダウンロードを開始したと判断したり、UI をアプリ起動時からのビジー状態に固定したりしないでください。 ステップ 4：UX とフォールバック動作を組み込む
8. デバイスを利用できない状態、モデルのダウンロード中、セッションの準備完了、プロンプトの処理中をそれぞれ区別して表示します。
9. ダウンロードの進捗が機能上重要な場合は、LanguageModel.create() の実行中に monitor リスナーを登録し、UI に進捗を表示します。
10. 未対応のブラウザー、未対応のデバイス、またはブロックされた iframe コンテキストに備えて、AI を使わないフォールバックを用意します。
11. 機能で構造化出力が必要な場合は、responseConstraint に JSON Schema を渡し、プロンプトに必要な形式の指示がすでに含まれている場合に限り omitResponseConstraintInput を使用します。また、返された文字列を解析してから使用します。
12. プロンプト形式の検証ルールを守ります。system メッセージは initialPrompts に含め、prefix: true は最後の assistant メッセージにのみ適用し、assistant メッセージの内容はテキストのみとします。
13. アプリが create() を呼び出す前に availability() が downloading を報告した場合は、アプリが開始したダウンロードではなく、ブラウザーの情報として表示します。また、アプリ自体が処理中でない限り、操作を可能な状態に保ちます。

ステップ 5：動作を検証する

1. 該当する場合は、短い応答には prompt() を、長い応答には promptStreaming() を使用してテストします。
2. 繰り返しのプロンプトで意図どおりにコンテキストが再利用されること、破棄されたセッションが再利用されないこと、ブラウザーのバージョンをまたいだコンテキストの測定と上限超過への対応に互換性チェックが使われていることを確認します。
3. 統合で NotSupportedError が発生した場合や、フレームまたは実行コンテキストによって動作が異なる場合は、references/troubleshooting.md を確認します。
4. 編集後に、ワークスペースのビルド、型チェック、またはテストを実行します。

エラー処理

• LanguageModel が存在しない場合は、独自の互換レイヤーを作るのではなく、メンテナンスされている Prompt API ポリフィル、または AI を使わないフォールバックによる段階的な機能強化を優先します。
• アプリが create() を呼び出す前に availability() が downloading を返した場合は、受動的なブラウザー状態として扱います。進捗をリアルタイムで表示し、プロンプトの送信をブロックするのは、アプリ自体が LanguageModel.create() を開始した場合に限ります。
• availability() または prompt() が NotSupportedError をスローした場合は、機能で実際に使用するモダリティ、言語、メッセージロールに合わせて、作成オプションとプロンプトオプションを調整します。availability() または create() に tools を渡した場合は、tools が EXPERIMENTAL であり、現在のブラウザーコンテキストではサポートされない可能性があることに留意します。
• 機能を Web Workers で実行する必要がある場合は、Prompt API はワーカーで利用できないため、統合先をウィンドウコンテキストに変更します。
• 機能がクロスオリジン iframe 内にある場合は、続行する前に埋め込み元のページで allow="language-model" を指定する必要があります。
• node scripts/find-frontend-targets.mjs . を実行できない場合は、ブラウザーアプリの境界を手動で特定し、対象となるアプリが 1 つに絞れてから作業を続けます。