proofreader-api

Proofreader API

手順

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

1. ワークスペースを調べ、ブラウザーのエントリーポイント、エディターまたはフォームの UI ハンドラー、既存の組み込み AI 抽象化レイヤーを確認します。
2. Node ランタイムが利用可能な場合は、node scripts/find-proofreader-targets.mjs . を実行して、該当する可能性のあるフロントエンドファイルと既存の Proofreader API マーカーを一覧表示します。
3. Node ランタイムが利用できない場合は、近くにある package.json、HTML エントリーポイント、フレームワークのブートストラップファイルを手動で調べ、ブラウザーアプリの境界を特定します。
4. ワークスペースに複数のフロントエンドアプリがある場合は、テキスト入力に使用中のルート、エディターコンポーネント、またはユーザーが指定した校正機能を含むアプリを優先します。
5. 一覧を確認してもフロントエンドの候補が複数残る場合は、作業を中止し、どのアプリに Proofreader API を組み込むか確認します。
6. プロジェクトがブラウザー向け Web アプリでない場合は、作業を中止し、このスキルが適用されないことを説明します。

ステップ 2：API の実行可能性とオプションの形式を確認する

1. コードを書く前に、references/proofreader-reference.md を読みます。
2. この機能でセッション作成、ダウンロードの監視、結果の表示、クォータを考慮した事前確認が必要な場合は、references/examples.md を読みます。
3. プレビュー用フラグ、ブラウザーチャネル、ハードウェア要件、iframe の制約、ブラウザー固有のオプションの不足が関係する場合は、references/compatibility.md を読みます。
4. 機能の検出、利用可能性の確認、作成、校正に失敗した場合は、references/troubleshooting.md を読みます。
5. この機能が安全な Window コンテキストで実行され、現在のフレームで proofreader Permissions Policy 機能の使用が許可されていることを確認します。
6. 特に対象ブラウザーがサポートしている場合は、expectedInputLanguages、includeCorrectionTypes、includeCorrectionExplanations、correctionExplanationLanguage のオプション形式に注意し、availability() と create() の形式を正確に一致させます。
7. この機能をワーカー内、サーバー上、または汎用テキスト生成インターフェース経由で実行する必要がある場合は、作業を中止し、プラットフォームが適合しないことを説明します。
8. プロジェクトで TypeScript を使用している場合は、この機能で実際に使用する Proofreader API の範囲のみを対象とする型定義を追加するか、既存の型定義を維持します。

ステップ 3：ガード付き校正ラッパーを実装する

1. assets/proofreader-session.template.ts を読み、ワークスペースのフレームワーク、状態モデル、ファイル構成に合わせて調整します。
2. 実行時のセッションで使用するものと同じ、一時的でない作成オプションを使って Proofreader.availability() を確認してからセッションを作成します。
3. availability() は機能の有無を確認するものであり、ユーザー操作、ダウンロード時間、ポリシーの承認なしに作成が成功することを保証するものではないと考えてください。
4. 対象ブラウザーでモデルのダウンロード開始にユーザー操作が必要になる可能性がある場合は、ユーザー操作の後にのみセッションを作成します。
5. UI でダウンロードの進行状況を表示する必要がある場合は、create() で monitor オプションを使用します。
6. キャンセル可能な作成または校正の呼び出しには AbortController を使用し、校正 UI でセッションが不要になったら destroy() を呼び出します。
7. 作成後にオプション依存の動作を変更するのではなく、セッションを再作成します。セッションオプションはインスタンスごとに固定されます。
8. タスクで修正ラベルまたは説明が必要な場合は、すべてのプレビュー実装が仕様のオプション一式を完全に備えていると決めつけず、ブラウザー固有のフォールバックを明示します。 ステップ 4：UX と結果処理を組み込む
9. API が利用できない場合、デバイスが利用できない場合、モデルをダウンロードできる場合またはダウンロード中の場合、セッションの準備が完了した場合、校正中の場合、処理がキャンセルされた場合、致命的なエラーが発生した場合に、それぞれ異なる状態を表示します。
10. サポート対象外のブラウザー、ブロックされたフレーム、または現在のプレビュー要件を満たさないデバイス向けに、AI を使わないフォールバックを用意します。
11. 目に見える差分の表示や個別の採用が必要な場合は、correctedInput と構造化された corrections 配列の両方を表示します。
12. クォータを考慮した動作や大きな入力の事前チェックが機能上必要な場合に限り、高負荷な校正の前に measureInputUsage() を使用します。
13. サポート対象言語に応じた振り分けが機能上必要な場合は、入力言語を明示します。
14. Proofreader を一般的なチャット、要約、書き換えの用途には使用しないでください。校正以外のタスクでは、適切な組み込み API に切り替えてください。

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

1. node scripts/find-proofreader-targets.mjs . を実行し、意図したアプリの境界と Proofreader のマーカーが、編集した連携部分を引き続き正しく特定できることを確認します。
2. より深い実行時エラーを調査する前に、機能検出、安全なコンテキストの確認、Permissions Policy へのアクセス、availability() の動作を検証します。
3. 本番環境で使用するものとまったく同じオプションを使ってセッション作成をテストします。環境でモデルの初回ダウンロードが必要な場合は、ダウンロードの進行状況の処理も含めます。
4. 代表的なユーザーテキストに対して、proofread() が期待される correctedInput と修正範囲を返すことを確認します。
5. 連携で measureInputUsage() を使用する場合は、ブラウザーでクォータ関連のエラーが発生する前に、大きな入力が拒否または切り詰められることを確認します。
6. キャンセルによって処理が適切に停止し、破棄されたセッションが再利用されないことを確認します。
7. 対象環境がプレビュー用フラグ、オリジントライアル、またはチャネル固有の動作に依存する場合は、失敗をアプリケーションのバグと判断する前に、references/compatibility.md で必要なブラウザーの状態を確認します。
8. 編集後に、ワークスペースのビルド、型チェック、またはテストを実行します。

エラー処理

• Proofreader が存在しない場合は、AI を使わないフォールバックを維持し、プロダクトのロジックを変更する前に、環境が安全なコンテキスト、ブラウザー、プレビューの要件を満たしていることを確認します。
• availability() が downloadable または downloading を返す場合は、校正の準備ができていると案内する前に、ユーザー操作によるセッション作成を必須にします。
• create() または proofread() が NotAllowedError をスローした場合は、Permissions Policy の制約、ダウンロードに必要なユーザーアクティベーションの不足、ブラウザーのポリシー制限、またはユーザーによる拒否を確認します。
• create() または proofread() が NotSupportedError をスローした場合は、指定した言語とオプションの組み合わせをブラウザーのサポート対象に合わせ、サポートされていないプレビュー限定の前提を取り除きます。
• OperationError、UnknownError、またはその他の実行時例外で作成に失敗した場合は、デバイスの適格性、ストレージ、ブラウザーフラグが引き続き references/compatibility.md の要件を満たしていることを確認してから、一度だけ再試行します。
• 機能をワーカーまたはサーバーのコンテキストで実行する必要がある場合は、そこでの使用を中止し、Proofreader API はウィンドウでのみ使用できるブラウザー API であることを説明します。