Skip to content

[Feature] 为插件 _conf_schema.json 增加通用、安全的动作按钮能力 #9292

Description

@RhoninSeiei

Description / 描述

当前情况

插件配置渲染器已经存在一个专用动作控件:ConfigItemRenderer.vue_special=get_embedding_dim 内置“自动探测”按钮,并通过 get-embedding-dim 事件交由上层处理。该实现与 Embedding 维度检测绑定,插件的 _conf_schema.json 无法复用。

TemplateListEditor.vue 会逐项调用 ConfigItemRenderer 渲染 template_list 条目,但 schema 目前无法声明通用动作,也没有将当前条目作为动作请求参数的约定。

插件后端已经具备承载此能力的基础设施:插件可以通过 register_web_api() 注册接口,Dashboard 通过 /api/plug/{plugin_path:path} 调用,并继承 Dashboard 用户认证。

实际问题

RSS、Webhook、对象存储、网络搜索等插件经常需要在保存配置前验证一组关联参数。例如 RSS 来源通常需要同时探测 URL、代理、TLS 校验、请求头和超时设置。只有把当前表单中的组合提交给插件后端,才能给出有效反馈。

目前插件通常需要另做一个 Pages 页面或聊天命令。配置填写、连通性探测和结果查看分散在不同入口;尚未保存的表单值还需要重复填写或复制,使用体验较为割裂。

建议设计

建议给现有配置字段增加通用的 _action 元数据。该方式不会新增需要持久化的“动作字段”,旧版 Dashboard 忽略未知元数据后仍可正常显示原字段,动作按钮自然隐藏。

{
  "url": {
    "type": "string",
    "description": "来源地址",
    "_action": {
      "label": "探测连接",
      "name": "probe-source",
      "payload": "current_template_entry"
    }
  }
}

点击按钮时,由 Dashboard 固定发起:

POST /api/plug/<current_plugin_name>/probe-source
Authorization: Bearer <dashboard_jwt>
Content-Type: application/json
{
  "config_key": "sources.templates.rss.url",
  "template_key": "rss",
  "entry_index": 0,
  "value": "https://example.com/feed.xml",
  "entry": {
    "__template_key": "rss",
    "url": "https://example.com/feed.xml",
    "proxy": "http://127.0.0.1:7890",
    "verify_tls": true,
    "timeout": 15
  }
}

也可以采用 _special=plugin_actiontype=action,但建议保留以下安全语义:

  1. schema 仅声明相对动作名;插件名由当前配置页面提供,Dashboard 统一拼接为 /api/plug/<current_plugin_name>/<action_name>
  2. 动作名拒绝协议、主机、查询串、.. 和以 / 开头的值,schema 无法指定任意外部 URL,也无法访问其他插件命名空间。
  3. 请求继承现有 Dashboard JWT;建议固定使用 POST,避免 schema 自由指定 HTTP 方法。
  4. 普通字段默认发送当前字段值;template_list 支持 payload=current_template_entry,发送当前条目的全部未保存值以及 template_keyentry_indexconfig_key
  5. 按钮在请求期间显示 loading 并禁止重复提交;响应的 message 统一显示为成功或失败提示。
  6. 动作执行与配置保存完全分离。动作只读取当前表单快照,只有显式点击保存按钮时才持久化配置。

建议的响应形式可以沿用 Dashboard API 的常见结构:

{
  "status": "ok",
  "message": "连接成功,检测到 RSS 2.0,共 20 个条目",
  "data": {}
}

兼容性

采用附着在现有字段上的 _action 时,未识别该元数据的旧版 Dashboard 会继续渲染原字段,仅隐藏动作按钮。插件仍应保留命令或 Pages 等降级入口,以覆盖旧版 Dashboard 和非图形界面环境。

如果最终采用独立的 type=action,建议 Dashboard 对未知控件类型采用跳过渲染的行为,避免旧式文本框占位。

相关 Issue

已检查 #8358#8209#3060

本建议关注 schema 声明的轻量动作调用、未保存表单快照传递和当前插件命名空间限制,与上述条目互补。

Use Case / 使用场景

以网络来源配置为例,一个 template_list 中可能同时包含 RSS、Atom、Webhook 等多种模板。每个条目都有 URL、代理、TLS、请求头和超时等组合。填写当前条目后点击“探测连接”,插件后端即可使用该条目的未保存值执行实际请求,并在原配置界面显示格式识别结果或失败原因;配置内容保持未保存状态,确认无误后再由使用者保存。

同一能力也适用于对象存储凭据检测、数据库连通性测试、Webhook 试发、第三方 API 鉴权检查、模型服务探测等多个插件场景。

Willing to Submit PR? / 是否愿意提交PR?

  • Yes, I am willing to submit a PR. / 是的,我愿意提交 PR。

Code of Conduct

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:webuiThe bug / feature is about webui(dashboard) of astrbot.feature:pluginThe bug / feature is about AstrBot plugin system.

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions