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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions