插件配置
一个设计良好的插件通常需要提供一些可配置的选项，允许用户根据自己的需求调整插件的行为，或者提供必要的凭证（如 API 密钥）。Nekro Agent 提供了一套强大的插件配置系统，基于 Pydantic 模型，并能自动生成用户友好的 WebUI 管理界面。
为什么需要配置？
- 灵活性：允许用户调整插件参数以适应不同场景。
- 安全性：避免在代码中硬编码敏感信息（如 API 密钥、密码）。
- 可维护性：当插件需要更新或部署到不同环境时，配置项比修改代码更方便。
- 用户友好：通过 WebUI，非技术用户也能方便地管理插件设置。
注册配置类
插件的配置是通过定义一个继承自 nekro_agent.api.plugin.ConfigBase 的类，并使用 @plugin.mount_config() 装饰器将其注册到插件实例来实现的。
python
from nekro_agent.api.plugin import ConfigBase
from pydantic import Field, HttpUrl
from typing import List, Literal
@plugin.mount_config()
class MyPluginConfig(ConfigBase):
"""我的插件的配置项定义
这里是配置类的整体描述
"""
# 示例配置项
api_key: str = Field(
default="",
title="服务 API 密钥",
description="请输入从第三方服务获取的 API 密钥。这是必需的。",
json_schema_extra={"is_secret": True, "required": True}
)
max_items: int = Field(
default=10,
title="最大处理项目数",
description="单次操作允许处理的最大项目数量。",
)
service_url: str = Field(
default="https://api.example.com/v1",
title="服务接入点 URL",
description="插件将连接的外部服务的 URL。"
)
enable_feature_x: bool = Field(
default=True,
title="启用特性 X",
description="是否启用插件的特性 X。"
)
processing_mode: Literal["fast", "accurate", "balanced"] = Field(
default="balanced",
title="处理模式",
description="选择插件的处理模式：快速、精确或均衡。"
)
allowed_user_ids: List[str] = Field(
default=[],
title="允许的用户 ID 列表",
description="只有列表中的用户 ID 才能使用此插件的特定功能（留空则不限制）。",
json_schema_extra={"is_textarea": True, "placeholder": "一行一个用户ID"}
)
# 更多配置项...关键点：
- 配置类必须继承
ConfigBase。 - 使用
@plugin.mount_config()装饰在类定义之上。 - 类级别的文档字符串 (docstring) 会作为配置页面的整体说明。
- 每个配置项都应该是一个类属性，并使用 Pydantic 的
Field进行详细定义。
定义配置项 (Field)
Pydantic 的 Field 用于为配置项提供默认值、类型约束、描述以及控制其在 WebUI 中的显示和行为。
Field 的常用参数：
default: 配置项的默认值。如果用户未提供值，将使用此默认值。title(str): 在 WebUI 中显示的配置项名称（标签）。如果未提供，会根据属性名自动生成。description(str): 对配置项的详细说明，将显示在 WebUI 中作为提示信息。可以包含简单的 HTML 标签，如链接 (<a>)。- Pydantic 验证参数: 你可以直接在
Field中使用 Pydantic 的验证参数，如min_length,max_length,ge(大于等于),le(小于等于),pattern(正则表达式) 等，来约束输入值的格式和范围。- 例如:
Field(default=5, ge=1, le=10)表示一个默认值为5，范围在1到10之间的整数。
- 例如:
json_schema_extra(dict): 一个字典，用于传递额外的、Nekro Agent 特定的控制参数，以影响 WebUI 的渲染或行为。常用的键包括："is_secret"(bool): 如果为True，该字段在 WebUI 中会显示为密码输入框，其值在保存和日志中通常会被屏蔽。适用于 API 密钥、密码等敏感信息。"is_hidden"(bool): 如果为True，该配置项默认不会在 WebUI 中显示（除非用户选择显示所有）。"is_textarea"(bool): 如果为True，字符串类型的输入会使用多行文本区域 (<textarea>) 而非单行输入框。适用于需要输入较长文本的配置，如List[str]也可以配合此项，提示用户每行输入一个列表元素。"placeholder"(str): 输入框的占位提示文本。"required"(bool): (通常由 Pydantic 的类型是否为 Optional 或有无默认值推断，但也可显式设置) 标记字段是否为必填项。Nekro Agent UI 会据此进行提示。"ref_model_groups"(bool): 如果为True，该字段（通常是str或Literal类型）会在 WebUI 中渲染为一个下拉选择框，选项为系统中已配置的 AI 模型组名称。适用于让用户选择插件应使用的模型。"model_type"(str): 通常与ref_model_groups一起出现，用于筛选对应类型的模型组，可选值有chat embedding 以及 draw
支持的字段类型及 WebUI 渲染
Nekro Agent 的配置界面会根据 Pydantic 模型的字段类型自动渲染合适的输入控件：
| Python 类型 | Pydantic 类型示例 | WebUI 控件 |
|---|---|---|
| 字符串 | str | 文本输入框 |
| 整数 | int | 数字输入框 |
| 浮点数 | float | 数字输入框 (带小数) |
| 布尔值 | bool | 开关 (Toggle) |
| 枚举 (固定选项) | Literal["a", "b"] | 下拉选择框 |
| 字符串列表 | List[str] | 标签输入器 |
| 字典 | Dict[str, Any] | 暂无 |
访问配置
一旦配置类被注册，你就可以在插件的任何地方通过 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={"is_secret": True}。 - 优雅降级：当某些配置项缺失或无效时，插件应尝试优雅地处理（例如，禁用依赖该配置的功能，并给出明确提示），而不是直接崩溃。
- 配置热更新：Nekro Agent 通常支持配置的即时生效，无需重启插件或 Agent。在插件代码中访问
plugin.config时，获取到的通常就是最新的配置值。
通过精心设计插件配置，你可以极大地提升插件的易用性、灵活性和安全性。