プラグイン設定

よく設計されたプラグインは通常、ユーザーがニーズに応じてプラグインの動作を調整できるようにする設定オプションを提供したり、必要な認証情報（APIキーなど）を提供したりする必要があります。Nekro Agentは、Pydanticモデルに基づいた強力なプラグイン設定システムを提供し、ユーザーフレンドリーなWebUI管理インターフェースを自動生成します。

なぜ設定が必要ですか？

柔軟性: ユーザーがプラグインパラメータを調整して、異なるシナリオに適応できるようにします。
セキュリティ: APIキーやパスワードなどの機密情報をコードにハードコーディングすることを避けます。
保守性: プラグインを更新したり異なる環境にデプロイしたりする際に、コードを修正するよりも設定項目の方が便利です。
ユーザーフレンドリー: WebUIを通じて、技術に詳しくないユーザーもプラグイン設定を便利に管理できます。

設定クラスの登録

プラグイン設定は、nekro_agent.api.plugin.ConfigBaseを継承するクラスを定義し、@plugin.mount_config()デコレータを使用してプラグインインスタンスに登録することで実装されます。

python

from nekro_agent.api.plugin import ConfigBase, ExtraField
from pydantic import Field, HttpUrl
from typing import List, Literal

@plugin.mount_config()
class MyPluginConfig(ConfigBase):
    """私のプラグインの設定項目定義
    これは設定クラスの全体的な説明です
    """

    # APIキー設定（機密情報）
    api_key: str = Field(
        default="",
        title="サービスAPIキー",
        description="サードパーティサービスから取得したAPIキーを入力してください。これは必須です。",
        json_schema_extra=ExtraField(is_secret=True, required=True).model_dump()
    )

    # 基本的な数値設定
    max_items: int = Field(
        default=10,
        title="処理するアイテムの最大数",
        description="1回の操作で許可されるアイテムの最大数。",
    )

    # URL設定
    service_url: str = Field(
        default="https://api.example.com/v1",
        title="サービスエンドポイントURL",
        description="プラグインが接続する外部サービスのURL。",
        json_schema_extra=ExtraField(placeholder="https://api.example.com/v1").model_dump()
    )

    # スイッチ設定
    enable_feature_x: bool = Field(
        default=True,
        title="機能Xを有効にする",
        description="プラグインの機能Xを有効にするかどうか。"
    )

    # 列挙選択設定
    processing_mode: Literal["fast", "accurate", "balanced"] = Field(
        default="balanced",
        title="処理モード",
        description="プラグインの処理モードを選択します：高速、正確、またはバランス。"
    )

    # モデルグループ参照設定
    model_group: str = Field(
        default="default-chat",
        title="使用するモデルグループ",
        description="プラグインが使用するチャットモデルグループを選択します",
        json_schema_extra=ExtraField(ref_model_groups=True, model_type="chat", required=True).model_dump()
    )

    # 複数行テキスト設定
    system_prompt: str = Field(
        default="あなたはインテリジェントなアシスタントです",
        title="システムプロンプト",
        description="プラグインが使用するシステムレベルのプロンプト、複数行入力をサポート",
        json_schema_extra=ExtraField(is_textarea=True, placeholder="システムプロンプトを入力...").model_dump()
    )

    # ユーザーリスト設定
    allowed_user_ids: List[str] = Field(
        default=[],
        title="許可されたユーザーIDリスト",
        description="このリスト内のユーザーIDのみがこのプラグインの特定機能を使用できます（空の場合は制限なし）。",
        json_schema_extra=ExtraField(
            is_textarea=True, 
            placeholder="ユーザーIDを入力してください",
            sub_item_name="ユーザー"
        ).model_dump()
    )

    # 再起動が必要な設定
    cache_size: int = Field(
        default=1000,
        title="キャッシュサイズ",
        description="プラグインのメモリキャッシュサイズを設定します（変更後の再起動が必要）",
        json_schema_extra=ExtraField(is_need_restart=True).model_dump()
    )

    # 非表示の高度な設定（設定ファイルからのみ変更可能）
    debug_mode: bool = Field(
        default=False,
        title="デバッグモード",
        description="詳細なデバッグログ出力を有効にします（開発者専用）",
        json_schema_extra=ExtraField(is_hidden=True).model_dump()
    )

    # その他の設定項目...

重要なポイント：

設定クラスはConfigBaseを継承する必要があります。
クラス定義の上に@plugin.mount_config()デコレータを使用します。
クラスレベルのdocstringが設定ページの全体的な説明として機能します。
各設定項目はクラス属性である必要があり、PydanticのFieldを使用して詳細に定義します。

設定項目の定義（`Field`）

PydanticのFieldは、デフォルト値、型制約、説明を提供し、WebUIでの設定項目の表示と動作を制御するために使用されます。

`Field`の一般的なパラメータ：

default: 設定項目のデフォルト値。ユーザーが値を提供しない場合、このデフォルト値が使用されます。
title (str): WebUIに表示される設定項目の名前（ラベル）。提供されない場合、属性名に基づいて自動生成されます。
description (str): 設定項目の詳細な説明で、WebUIにプロンプト情報として表示されます。リンク（<a>）などの単純なHTMLタグを含めることができます。
json_schema_extra: 追加のWebUI制御パラメータを渡すために使用されます。現在、辞書を手動で構築するのではなく、ExtraFieldモデルを使用してこれらを生成することが推奨されています。ExtraFieldは以下の属性を提供します：
- is_secret (bool): 機密情報保護、Trueに設定すると入力ボックスがパスワード形式で表示されます
- is_hidden (bool): 設定項目の表示制御、Trueに設定するとWebUIで非表示になります
- is_textarea (bool): 複数行テキストサポート、Trueに設定すると複数行テキストエリアを使用します
- placeholder (str): 入力プロンプトテキスト、入力ボックスにプレースホルダーテキストを表示します
- required (bool): 必須フィールド識別子、Trueに設定するとフロントエンド検証で必須入力になります
- ref_model_groups (bool): モデルグループ参照識別子、Trueに設定するとシステムモデルグループから選択します
- model_type (str): モデルタイプ指定、オプション値はchat、embedding、draw
- overridable (bool): オーバーライド可能フィールド識別子、アダプターまたはチャネルレベルで独立してオーバーライドできます
- sub_item_name (str): サブアイテム名、リストタイプ設定項目の要素名
- load_to_sysenv (bool): 環境変数読み込み制御、システム環境変数に読み込みます
- load_sysenv_as (str): 環境変数名定義、読み込み時の変数名を指定します
- load_to_nonebot_env (bool): nonebot環境変数読み込み制御
- load_nbenv_as (str): nonebot環境変数名定義
- is_need_restart (bool): 再起動要件識別子、変更後にアプリケーションの再起動が必要です

サポートされるフィールドタイプとWebUIレンダリング

Nekro Agentの設定インターフェースは、Pydanticモデルのフィールドタイプに基づいて適切な入力コントロールを自動的にレンダリングします：

Pythonタイプ	Pydanticタイプ例	WebUIコントロール
文字列	`str`	テキスト入力ボックス
整数	`int`	数値入力ボックス
浮動小数点数	`float`	数値入力ボックス（小数点付き）
ブール値	`bool`	スイッチ（トグル）
列挙（固定オプション）	`Literal["a", "b"]`	ドロップダウン選択ボックス
文字列リスト	`List[str]`	タグ入力ボックス
辞書	`Dict[str, Any]`	まだ利用不可

`ExtraField`の使用に関する詳細な例

基本的な使用法

python

from nekro_agent.api.plugin import ConfigBase, ExtraField

# 単純な機密情報設定
api_key: str = Field(
    default="",
    title="APIキー",
    description="サービスのAPIキー",
    json_schema_extra=ExtraField(is_secret=True, required=True).model_dump()
)

# 複数行テキスト設定
prompt_template: str = Field(
    default="",
    title="プロンプトテンプレート", 
    description="カスタムプロンプトテンプレート",
    json_schema_extra=ExtraField(
        is_textarea=True,
        placeholder="プロンプトテンプレートを入力してください..."
    ).model_dump()
)

# モデルグループ選択設定
model_group: str = Field(
    default="default-chat",
    title="チャットモデルグループ",
    description="チャット用のモデルグループを選択します",
    json_schema_extra=ExtraField(
        ref_model_groups=True,
        model_type="chat",
        required=True
    ).model_dump()
)

高度な機能の例

python

# 再起動が必要な設定
thread_count: int = Field(
    default=4,
    title="スレッド数",
    description="並列処理のためのスレッド数（変更後の再起動が必要）",
    json_schema_extra=ExtraField(is_need_restart=True).model_dump()
)

# オーバーライド可能な設定項目
timeout: int = Field(
    default=30,
    title="リクエストタイムアウト",
    description="APIリクエストのタイムアウト（秒）",
    json_schema_extra=ExtraField(overridable=True).model_dump()
)

# 環境変数読み込み設定
debug_level: str = Field(
    default="INFO",
    title="デバッグレベル",
    description="システムログのデバッグレベル",
    json_schema_extra=ExtraField(
        load_to_sysenv=True,
        load_sysenv_as="LOG_LEVEL"
    ).model_dump()
)

設定へのアクセス

設定クラスが登録されると、プラグイン内のどこからでもplugin.configプロパティを通じて設定クラスのインスタンスにアクセスでき、各設定項目にアクセスできます。

python

@plugin.mount_sandbox_method(SandboxMethodType.TOOL, "perform_action", "設定が必要な操作を実行します。")
async def my_action(ctx: AgentCtx, some_input: str) -> str:
    # 設定項目にアクセス
    api_key = plugin.config.api_key
    max_items = plugin.config.max_items
    service_url = plugin.config.service_url

    if not api_key:
        return "エラー: APIキーが設定されていません。プラグイン設定ページで設定してください。"

    # 設定項目を使用して操作を実行
    # response = await some_api_call(service_url, api_key, some_input, limit=max_items)
    
    return f"'{some_input}'を'{service_url}'でAPIキー'{api_key[:4]}...'を使用して最大{max_items}アイテムで処理しました。"

ベストプラクティス

合理的なデフォルト値を提供: ユーザーが何も設定していない場合でも、プラグインが安全または基本的に使用可能な方法で実行できるようにします（可能であれば）。
明確なtitleとdescription: これはユーザーが設定項目の目的を理解するための鍵です。説明は可能な限り詳細で、期待される値、フォーマット、取得方法などを説明する必要があります。
機密データのマーキング: APIキー、パスワードなどについては、必ずjson_schema_extra=ExtraField(is_secret=True).model_dump()を使用してください。
グレースフルデグラデーション: 特定の設定項目が欠落しているか無効な場合、プラグインは直接クラッシュするのではなく、グレースフルに処理しようとする必要があります（例：設定に依存する機能を無効にし、明確なプロンプトを提供する）。
ホット設定更新: Nekro Agentは通常、プラグインまたはエージェントを再起動せずに設定を即座に有効にすることをサポートしています。プラグインコードでplugin.configにアクセスする場合、取得されるのは通常、最新の設定値です。

プラグイン設定を注意深く設計することで、プラグインの使いやすさ、柔軟性、セキュリティを大幅に向上させることができます。

プラグイン設定 ​

なぜ設定が必要ですか？ ​

設定クラスの登録 ​

設定項目の定義（Field） ​

Fieldの一般的なパラメータ： ​

サポートされるフィールドタイプとWebUIレンダリング ​

ExtraFieldの使用に関する詳細な例 ​

基本的な使用法 ​

高度な機能の例 ​

設定へのアクセス ​

ベストプラクティス ​

プラグイン設定

なぜ設定が必要ですか？

設定クラスの登録

設定項目の定義（`Field`）

`Field`の一般的なパラメータ：

サポートされるフィールドタイプとWebUIレンダリング

`ExtraField`の使用に関する詳細な例

基本的な使用法

高度な機能の例

設定へのアクセス

ベストプラクティス