插件配置

一个设计良好的插件通常需要提供一些可配置的选项，允许用户根据自己的需求调整插件的行为，或者提供必要的凭证（如 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="单次操作允许处理的最大项目数量。",
    )

    # 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 中作为提示信息。可以包含简单的 HTML 标签，如链接 (<a>)。
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`	开关 (Toggle)
枚举 (固定选项)	`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"已使用 API 密钥 '{api_key[:4]}...' 在 '{service_url}' 上处理了 '{some_input}'，最大项目数为 {max_items}。"

最佳实践

提供合理的默认值：确保插件在用户未进行任何配置的情况下也能以一种安全或基本可用的方式运行（如果可能）。
清晰的 title 和 description：这是用户理解配置项作用的关键。描述应尽可能详细，说明预期值、格式、从何处获取等。
敏感数据标记：对于 API 密钥、密码等，务必使用 json_schema_extra=ExtraField(is_secret=True).model_dump()。
优雅降级：当某些配置项缺失或无效时，插件应尝试优雅地处理（例如，禁用依赖该配置的功能，并给出明确提示），而不是直接崩溃。
配置热更新：Nekro Agent 通常支持配置的即时生效，无需重启插件或 Agent。在插件代码中访问 plugin.config 时，获取到的通常就是最新的配置值。

通过精心设计插件配置，你可以极大地提升插件的易用性、灵活性和安全性。

插件配置 ​

为什么需要配置？ ​

注册配置类 ​

定义配置项 (Field) ​

Field 的常用参数： ​

支持的字段类型及 WebUI 渲染 ​

使用 ExtraField 的详细示例 ​

基础用法 ​

高级功能示例 ​

访问配置 ​

最佳实践 ​

插件配置

为什么需要配置？

注册配置类

定义配置项 (`Field`)

`Field` 的常用参数：

支持的字段类型及 WebUI 渲染

使用 `ExtraField` 的详细示例

基础用法

高级功能示例

访问配置

最佳实践