add-model-provider

モデルプロバイダーを追加する

ユーザーが設定、識別し、サポート対象の API 経路を通じて利用できるプロバイダーを提供します。このスキルには、プロバイダーのドキュメント作成手順も含まれます。

以下のパスは、オープンソースリポジトリのルートからの相対パスです。Cloud のチェックアウトでは、先頭に lobehub/ を付け、親リポジトリのインストールおよび Git のルールに従ってください。ホスト型モデルの設定は別のワークフローです。それが依頼対象の場合は、デプロイ運用者のモデルオンボーディング手順を使用してください。非公開のデプロイ設定やルーティング情報を、このスキルや OSS の変更にコピーしないでください。

ドキュメントのみの依頼では、実装済みの設定を確認し、プロバイダーのドキュメントに従ってください。このチェックリストを満たすためだけに、ランタイムコードを追加しないでください。

既存プロバイダーへのモデル追加のみの依頼では、knowledgeCutoff、family、generation については model-bank-metadata に従い、リポジトリ全体を対象とした一括確認ではなく、単一モデル向けのガイダンスを使用してください。モデルカードのその他の項目（機能、価格、コンテキスト制限など）については、以下の調査と対象を絞った検証を行ってください。依頼されたモデルによって該当箇所の不備が確認された場合を除き、新しいプロバイダーの登録、認証設定、プロバイダー一覧の並べ替えは省略してください。

統合の前提を確認する

• 新しいプロバイダーと既存プロバイダーへのモデル追加を区別します。安定したプロバイダー ID、表示名、モデル ID、認証方式、エンドポイント、サポート対象の API モードを記録してください。ファイル名やエクスポート名の大文字・小文字は、小文字のプロバイダー ID と異なる場合があります。実際の利用箇所に従ってください。
• 公式発表、API リファレンス、モデルカタログ、価格情報、移行に関する注意事項を確認します。機能、制約、価格について、参照元の URL とアクセス日を記録してください。ドキュメントだけでなく、発表も検索します。パラメーターの変更は、リリースノートにしか記載されていないことがよくあります。取得したページがクライアント側でレンダリングされる空のシェルの場合は、レンダリング可能なブラウザーを使用してください。
• 統合対象のエンドポイントを実際に確認します。モデルで公表されている機能が、互換性のあるエンドポイントで検索パラメーター、ツール、画像、構造化出力をサポートしている証拠にはなりません。サードパーティのエンドポイントや認証情報を、そのプロバイダーの公式 API として説明しないでください。
• ローカルサーバーやデスクトップアプリの場合は、ローカルプロバイダーの統合を確認してください。起動モード、インストール済みモデルの検出、ブラウザーからのアクセス、機能の更新をそれぞれ個別に検証します。OpenAI 互換のモデル一覧だけでは、これらの動作が確認できたことにはなりません。
• 直近のプロバイダー追加と、プロトコルおよび認証方式が最も近い既存実装を比較します。ファイル一覧だけでなく、差分も確認してください。統合マップと先例には、登録の流れと対照的な例が示されています。過去の漏れを、繰り返すべき要件として扱わないでください。
• 根拠に基づいてモデルのメタデータを設定します。正確な ID、ファミリー／世代、コンテキストと出力の上限、判明している場合はリリース日／カットオフ日、機能、拡張パラメーター、検索の動作、価格の通貨と単位を確認してください。API の利用料金とサブスクリプションの利用資格、キャッシュ済み入力と通常の入力、現在のキャンペーン価格と定価を区別します。不明な値は推測せず不明として示し、既存のサポート対象モデルは維持してください。

プロバイダーを実装する

リクエストの流れを設定からランタイムまで追跡する際は、統合マップと先行事例を参照してください。

1. プロバイダー ID、プロバイダーカード、個別のモデルカード、モデルのインポート／マップ／エクスポート、およびパッケージのサブパスエクスポートを登録します。個別のモデルバンクが信頼できる情報源である場合、最新のプロバイダーカードでは chatModels: [] を維持してください。
2. プロバイダーがそのモデルの利用可能性を保証する場合は、使用可能な静的 checkModel を設定します。そうでない場合は省略し、取得したローカルリストから接続確認用モデルをユーザーが選択して保存できるようにします。カードに任意のサンプルを設定しないでください。認証、モデル取得、SDK ファミリー、ブラウザーリクエストの設定を正確に指定します。API にモデル一覧エンドポイントがない場合は、静的なモデルカタログが適切なことがあります。トップレベルとネストされたブラウザーリクエストフラグの両方を参照する箇所を追跡してから、いずれか一方に依存してください。
3. 適切なランタイムファクトリーまたはアダプターを再利用します。ランタイムとその公開エクスポートを登録します。プロバイダーに固有のルーティング API アダプターが必要な場合は、RouterRuntime の API タイプとベースランタイムマップも配線してください。プロバイダーを登録するだけでは、その経路は確立されません。
4. ストリーミングチャット、非ストリーミングチャット、構造化生成では、それぞれ別にプロトコル選択を検証します。Responses のみをサポートするプロバイダーでは、チャットと generateObject の両方の設定に加えて、呼び出し元が未対応のモードを選択できないようにする必要がある場合があります。ツール、検索、レスポンス形式、推論は、サポートされている場合に限りマッピングします。兄弟プロバイダーが対応しているという理由だけで、機能を有効にしないでください。
5. プロバイダーに適した認証／設定の配線を追加します。API キーを使うプロバイダーでは、環境スキーマとランタイムバインディングの両方を確認し、続いて汎用サーバー設定とランタイム初期化も確認します。OAuth プロバイダーでは、架空の API キー変数を追加するのではなく、認可、更新、切断、アカウントメタデータの各経路が必要です。
6. ユーザー向けの新しいパラメーターを追加する場合は、モデルカードの型、保存されるチャット設定、コントロール、リクエストリゾルバー、翻訳を追跡します。意味が一致する既存のパラメーター定義を優先してください。推論状態を複数ターンにわたって保持する必要がある場合は、初回リクエストだけでなく、実際のストリーム／非ストリーム経路を通したシリアライズと再生をテストします。

共通ファクトリーやエラーハンドラーの変更は、実際に不足が確認された場合に限ります。このチェックリストは、記載されたすべてのファイルを変更することを求めるものではありません。

ブランディング、順序、ドキュメント

• @lobehub/icons でプロバイダーとモデルのアイコンを個別に確認してください。プロバイダーのブランドとモデルファミリーで、異なるアートワークが必要になる場合があります。実際のモデル ID マッチャーを調べ、プレフィックス、大文字・小文字の違い、既存のモデル名との衝突を確認してください。マッチャーを変更する場合は、新しい ID を検証し、以前のファミリーのマッチを維持してください。
• アイコンが見つからない場合は、不足しているアセットやマッピングを特定し、許可された範囲内で適切な変更または明示的なフォールバックを用意してください。無関係なブランドを黙って使用してはいけません。外部アイコンの PR やリリースは別途許可が必要な作業です。UI が修正されたと主張する前に、利用側がインストールしているリリースに意図したマッピングが含まれていることを確認してください。
• DEFAULT_MODEL_PROVIDER_LIST にプロバイダーを適切に配置してください。この配列が制御するのはデフォルトのリスト順であり、インポートや enum 宣言ではありません。次の順序付けの原則を適用してください。
  • コミュニティでの人気が高いプロバイダーを前方に配置してください。アルファベット順、実装の都合、根拠のない数値の人気スコアではなく、現在の採用状況とエコシステムでの認知度を示す証拠を使用してください。
  • Ollama、LM Studio、vLLM、Unsloth Studio などのローカルモデルマネージャーと推論サーバーは、ひとまとまりにしてください。
  • ルーター／アグリゲーターサービスは、ひとまとまりにしてください。OpenRouter や AIHubMix など、統一された API を通じて複数の上流プロバイダーのモデルを公開するサービスが該当します。内部の RouterRuntime 抽象化を使用しているというだけでは、このグループには該当しません。
  • 個々のプロバイダーをすべて人気順に厳密に並べることより、グループの連続性を優先してください。コミュニティでの人気を基にグループや単独のプロバイダーの位置を決め、各グループ内のプロバイダーを並べてください。ユーザーが明示的に指定した位置と、既存のユーザーカスタム順序は維持してください。
  • 新しいプロバイダーは、無関係なプロバイダーの順序を変更せず、適切なグループに追加してください。より広範な順序の整理が依頼された場合は、影響を受けるプロバイダーをまとめて移動できます。
• 二言語での使用方法／セットアップ手順、環境変数の説明、既存の Docker 設定、安全なサンプル、スクリーンショットについては、プロバイダーのドキュメントに従ってください。公開されるプロバイダーの識別情報と、実際に必要な認証情報／エンドポイントが UI とドキュメントで一致するようにしてください。
• プロバイダーの説明には、locales/en-US/providers.json と locales/zh-CN/providers.json に <provider-id>.description を追加してください。packages/locales/src/default/providers.ts のデフォルトの名前空間はプロバイダーカードから派生するため、そこに説明を重複して追加する必要はありません。新しい文言についてはリポジトリの規約に従い、フォールバックの動作を確認してください。少数のプロバイダーキーのために、リポジトリ全体の翻訳ジョブを実行するのは避けてください。

ユーザーの操作経路を検証する

既存のプロバイダーテストハーネス（packages/model-runtime/src/providerTestUtils.ts）と、対象を絞ったパッケージテストを使用してください。登録文字列の存在を確認するのではなく、サポートされている動作を網羅してください。

• プロバイダー／モデルの検索で、新しいカードとランタイムが解決されることを確認してください。接続チェックには、サポートされているモデルを使用してください。
• リクエストで意図した API モードとエンドポイントが選択され、適切な認証情報が付与され、サポート対象のパラメーターが変換され、ツール呼び出しと構造化された結果が保持されることを確認してください。サポートされている場合は、ストリーミングと非ストリーミングの両方の経路をテストしてください。
• 認証情報の欠落や無効、モデル取得の失敗、接続エラーの際に、生のコードや翻訳キーではなく、適切にローカライズされたメッセージが表示されることを確認してください。古い形式や無効なワイヤーペイロードには、現在の厳格なレスポンス型へキャストするのではなく、合成 HTTP レスポンスを使用してください。
• 接続失敗を発生させて詳細を展開し、設定ページ内でエラーから復帰できることを確認してください。接続が成功しただけでは、遅延読み込みされるエラーコンポーネントや、それらが共有する UI コンテキストは検証できません。
• プロバイダー設定ページとモデル行に、意図した名前、アイコン、機能、デフォルトの順序がライトテーマとダークテーマで表示されることを確認してください。文言を変更した場合は、英語と中国語も確認してください。プロバイダーとモデルの両方のアイコンを、実際の UI で確認してください。
• 共有ランタイムエラーや遅延読み込みされる名前空間を変更した場合は、Workbench など、影響を受ける他の画面も確認してください。メインアプリケーションですでに読み込まれている場合でも、別の言語バンドルには名前空間が必要なことがあります。

リポジトリ指定の品質チェックと、関連するパッケージテストを実行してください。Cloud 内で開発した OSS 向け PR については、OSS の型チェック／ビルド環境も検証してください。親プロジェクトの型チェックが成功しても、単独の OSS 設定が通ることの証明にはなりません。ワークスペース解決の失敗は別途分類し、成功を装うために有効なチェックを削除しないでください。

許可されたライブチェックには、リポジトリの受け入れワークフローを使用してください。シークレットファイルを読んだり、認証情報をログやスクリーンショットに記載したり、スクリーンショットを捏造したり、モックから推論が成功したと主張したりしないでください。ライブ認証情報やアクセスが利用できない場合は、検証できていない経路を具体的に報告し、完了したオフラインチェックも報告してください。

納品に PR が含まれる場合は、リポジトリのコミット／PR ワークフローに従い、現在のヘッドに対する CI とデプロイの進行状況を監視してください。失敗の原因を特定し、対象範囲内の問題を修正して検証したうえで、チェックが完了するか、具体的なブロッカーに達するまで対応を続けてください。適用される独立レビューのゲートと、人間のみが行えるマージのルールを維持してください。変更した動作、検証内容、証拠、残る制限事項を報告してください。