writing-assistance-apis

文章作成支援 API

手順

ステップ 1：ブラウザー連携の対象を特定する

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

ステップ 2：API の実用性を確認し、適切な対象を選ぶ

1. コードを書く前に、references/writing-assistance-reference.md を読みます。
2. ダウンロードの監視、バッチ出力、ストリーミング出力、キャンセルのためにセッションの形式が必要な場合は、references/examples.md を読みます。
3. プレビュー用フラグ、ブラウザーのチャネル、ハードウェア要件、iframe の制約が関係する場合は、references/compatibility.md を読みます。
4. 利用可否の確認、作成、ストリーミング、セッションのクリーンアップに失敗した場合は、references/troubleshooting.md を読みます。
5. 機能がセキュアな Window コンテキストで実行されること、および関連する permissions-policy 機能によって現在のフレームからのアクセスが許可されていることを確認します。
6. タスクに合う最も用途を絞った対象を選びます。
   • 記事、ドキュメント、会話の要約には Summarizer。
   • 短いプロンプトや文章作成タスクから新しいテキストを生成するには Writer。
   • 意図を保ちながら既存のテキストを変換するには Rewriter。
7. 機能をワーカー内、サーバー上、またはリモートモデルプロバイダーに対して実行する必要がある場合は、プラットフォームが適合しないことを説明し、作業を中断します。
8. プロジェクトが TypeScript を使用している場合は、機能で使う特定のブラウザー API を網羅する型定義を追加するか、既存の型定義を維持します。

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

1. assets/writing-assistance-session.template.ts を読み、ワークスペースのフレームワーク、状態モデル、ファイル構成に合わせて調整します。
2. 実行時に使うものと同じ作成オプションを指定して、API の availability() メソッドでセッションの作成を制御します。
3. availability() は機能の利用可否を確認するものであり、ユーザー操作やダウンロード時間なしで作成が成功する保証ではないことを前提にします。
4. 作成によってダウンロードが始まる可能性がある場合は、ユーザー操作の後にのみセッションを作成します。
5. UI でダウンロードの進捗状況を表示する必要がある場合は、create() で monitor オプションを使用します。
6. キャンセル可能な create 呼び出しと run 呼び出しには AbortController を使用し、セッションが不要になったら destroy() を呼び出します。
7. 作成後にオプションを変更するのではなく、セッションを再作成します。セッションのオプションはインスタンスごとに固定されます。
8. 機能がクロスオリジン iframe 内にある場合は、そのフレームが必要とする各 API について明示的な委譲を必須とします。 ステップ 4：UX とフォールバックの動作を組み込む
9. API の欠如、デバイスが利用できない状態、モデルのダウンロードが可能または進行中の状態、セッションの準備完了、生成中、処理の中止といった状態を、それぞれ区別して表示します。
10. サポート対象外のブラウザー、ブロックされたフレーム、または現在のプレビュー要件を満たさないデバイスでは、AI を使わないフォールバックを維持します。
11. レンダリング済みページのコンテンツから取得したテキストを要約または書き換える場合は、その前に HTML を除去または正規化します。
12. 続行する前に結果全体が必要な機能ではバッチメソッドを使用し、UI で出力を順次表示する機能ではストリーミングメソッドを使用します。
13. sharedContext はセッション全体にわたって保持するガイダンスにのみ渡し、呼び出しごとの context はリクエスト固有の背景情報にのみ渡します。
14. 機能がサポート対象の入力言語、コンテキスト言語、または出力言語に依存する場合は、言語オプションを明示します。
15. 汎用チャットボット、ツール呼び出し、または自由形式のアシスタントタスクをこれらの API に割り当てないでください。タスクが要約、文章作成、書き換えではない場合は、Prompt API または別の承認済み機能に切り替えてください。

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

1. node scripts/find-writing-assistance-targets.mjs . を実行し、意図したアプリの境界と API マーカーが、引き続き編集した統合部分を指していることを確認します。
2. より深いランタイムエラーの調査に進む前に、機能検出、セキュアコンテキストの確認、availability() の動作を検証します。
3. この機能で両方のモードを公開している場合は、少なくとも 1 回のバッチ呼び出しと 1 回のストリーミング呼び出しをテストします。
4. キャンセルによって生成が適切に停止し、破棄されたセッションが再利用されないことを確認します。
5. 対象環境がプレビュー用ブラウザーフラグやチャンネル固有の動作に依存する場合は、エラーをアプリケーションの不具合と判断する前に、references/compatibility.md で必要なブラウザーの状態を確認します。
6. 編集後にワークスペースのビルド、型チェック、またはテストを実行します。

エラー処理

• Summarizer、Writer、または Rewriter が見つからない場合は、AI を使わないフォールバックを維持し、プロダクトのロジックを変更する前に、環境がブラウザーとプレビューの要件を満たしていることを確認します。
• availability() が downloadable または downloading を返す場合は、生成の準備が整っていると案内する前に、ユーザー操作によるセッション作成を必須とします。
• create() が NotAllowedError をスローする場合は、Permissions Policy の制約、ダウンロードに必要なユーザーアクティベーションの欠如、ブラウザーポリシーによる制限、またはユーザーによる拒否を確認します。
• create() または実行呼び出しが NotSupportedError をスローする場合は、指定した言語、出力形式、要約の種類、トーン、または長さを、ブラウザーがサポートする組み合わせに合わせます。
• 呼び出しが QuotaExceededError をスローする場合は、再試行する前に sharedContext、呼び出しごとの context、またはユーザー入力を短くします。
• この機能をワーカーまたはサーバーのコンテキストで実行する必要がある場合は、処理を中止し、Writing Assistance API はウィンドウ専用のブラウザー API であることを説明します。