プロバイダーアダプターの作成
これは、信頼済みのプロバイダー統合を追加するメンテナー向けの高度なガイドです。組み込みプロバイダーから選ぶオペレーターは、まず プロバイダー を参照してください。
ThreadCells Provider Adapter API V1 は、オブザーバープラグインとは異なる、信頼済みコードの拡張境界です。threadcells.provider_adapters.v1 エントリーポイントグループの下に ProviderAdapterDefinition オブジェクトを登録する、レビュー済み Python パッケージとしてアダプターをインストールします。インストール後、ローカル候補/ランタイムを再起動してエントリーポイントを再検出してください。
契約
アダプター定義は次を提供します。
- 安定した
adapter_id、プラグイン API1.0、実装バージョン、説明、機能、JSON 設定スキーマを持つAdapterManifest。 - 宣言的設定用の
AdapterSettingsPydantic モデル。 ProviderLaunchContextと検証済み設定を受け取るファクトリー。- 正規化済み状態、インストール、認証、バージョン、互換性、モデル、理由コード、シークレットを含まないメッセージを返すプリフライト関数。
返されるプロバイダーは、既存の BaseProvider ライフサイクルを通じて、正規化された開始/再開/キャンセル、ターミナル状態/結果、使用量、健全性のセマンティクスを実装します。未サポートと条件付きの機能を正直に宣言してください。CLI が報告しなかった使用量を生成してはいけません。
信頼と設定
アダプターパッケージは実行可能であるため、信頼されたホストオペレーターだけがインストールします。レジストリー JSON でバイナリーを選択したりコマンドを注入したりすることはできません。ThreadCells は、実行可能、コマンド、シェル、引数、フラグ、環境、資格情報、パスワード、トークン、シークレットのキーを再帰的に拒否します。未加工のシークレットを settings に入れてはいけません。意味を持つ不透明な secret_refs を使い、インストールのシークレットポリシーに従って信頼済みアダプターコード内だけで解決してください。
エラーは安定した理由コードと公開しても安全なメッセージで正規化してください。プリフライトはプロバイダー設定を変更したり、オペレーターの代理で認証したりしてはいけません。
サンプル
インストール済みのソース/候補には、エントリーポイント、スキーマ、設定検証、ライフサイクル、プリフライト、未サポートの使用量を実演する決定的なパッケージおよびマニフェスト examples/provider-adapters/threadcells-echo が含まれます。これはモデルプロバイダーではなく、既定では無効です。インストール前に独立してビルド/テストしてください。
schemas/v1/adapter-manifest.schema.json および schemas/v1/capabilities.schema.json のパッケージ済みスキーマは、ポータブルアーティファクトの参照です。インストール済みコードでは Python 契約検証が権威を持ち続けます。
準備状況は正確でなければならない
プロバイダーの正規実行ファイル名と、範囲が限定され変更を行わないプローブを使用してください。プリフライトは、インストール、互換性、安全に検出できる場合の認証、公開しても安全な失敗理由に答えます。アダプター登録により CLI が利用可能になると主張してはいけません。
レジストリー API、Settings、Spawn Agent はすべて同じ結果を投影します。未インストールのコマンドが無効になること、認証失敗が不在と区別されること、認証が真に不明なインストール済みプロバイダーが未検証とラベル付けされ続けることを証明するカバレッジを追加してください。
使用量は正確でなければならない
ターミナルテキスト解析よりも、プロバイダーネイティブの構造化イベントを優先してください。プロバイダーが出力するフィールドだけを記録し、累積チェックポイント ID を保持し、再起動/再生を冪等にしてください。利用できないメトリクスをゼロにしたり、明示的なプロバイダー契約なしにトークンからコストを推定したりしてはいけません。
レビューチェックリスト
- 安定したアダプター ID、バージョン、表示名、設定スキーマ。
- 呼び出し元が選択する実行ファイル、シェル、引数、環境、未加工シークレットフィールドがないこと。
- 設定または認証を変更しない、範囲限定のプリフライト。
- 正直なサポート/条件付き/未サポート機能。
- 開始、状態、キャンセル、回復可能な失敗のライフサイクルテスト。
- テレメトリーがサポートされる場合の正確な使用量テスト。
- レジストリー/Settings/Spawn の一貫性テスト。
- 資格情報またはプライベートパスを含まない、公開しても安全なエラー。