Auto_Bangumi/docs/dev/plugins/config-forms.md

配置表单

插件声明 config_model（pydantic 模型），WebUI 在 设置 → 插件 里据此自动生成表单，插件作者不需要写前端。

from pydantic import BaseModel, Field
from ab_sdk import Plugin, secret_field

class Options(BaseModel):
    endpoint: str = Field("https://push.example.com", title="推送地址")
    key: str = secret_field(description="推送密钥")
    retries: int = Field(3, ge=0, le=10, title="重试次数")

class MyPlugin(Plugin[Options]):
    config_model = Options

字段类型

Python 类型	表单控件
str	文本框
secret_field() 声明的 str	密码框
int / float	数字框（int 输入后取整）
bool	开关
Literal[...] / Enum	下拉框
list[str]	标签输入
list[<BaseModel>]	对象数组：每行一组子字段，可添加和删除行
其它（dict、嵌套对象）	显示为「不支持的字段」，请直接编辑 config.json

Field(title=..., description=...) 成为标签和说明文字。Optional[T] 按 T 渲染。默认值用于未保存过的字段。

校验

• 保存时 AB 用模型校验。不合法的值返回 HTTP 422，不会写入配置。
• 在 field_validator 里做深度校验：例如内置的 rename 在保存时试渲染模板，写错的模板当场被拒绝。
• 没有默认值的必填字段在首次启用时缺失，插件进入错误状态。用户填写并保存后，插件自动恢复。
• 未启用的插件也显示表单：AB 导入可信插件的代码，只读取 config_model，不调用 setup。尚未开启「允许未签名插件」的本地插件不执行任何代码，也就没有表单。

秘密字段

secret_field() 声明密码、令牌、Cookie 等。

• WebUI 以密码框渲染。
• 读取配置的接口只返回掩码。浏览器永远拿不到原值。
• 保存时收到掩码，AB 保留原值。掩码处理覆盖嵌套结构，对象数组行里的秘密字段也会掩码。数组行数被改变而无法对应原行时，该秘密字段被清空，需要用户重新输入。

配置保存在 config.json 的 plugins.options.<插件 id> 下，启用开关在 plugins.enabled.<插件 id>。

超出表单的界面

表单满足不了时（图表、操作按钮、列表），插件可以提供前端组件，见 前端挂载点。内置 hardlink 的「链接已有文件」按钮就是一个 settings.section 组件。