438 lines
20 KiB
Markdown
438 lines
20 KiB
Markdown
# 插件配置文件标准(Plugin Config Standard)
|
||
|
||
> HeXi 统一插件配置标准 —— 机器可读、带类型的 schema 声明 + 持久化值文件，
|
||
> 让 Web 管理台(/hub)能对任意插件**读取、展示、修改、热刷新、重启生效**。
|
||
>
|
||
> 插件整体骨架/目录/入口/职责划分见《插件结构标准》(docs/plugin-structure-standard.md)。
|
||
|
||
---
|
||
|
||
## 0. 目标与一句话总结
|
||
|
||
- **核心原则**：插件只声明 `schema`，Web 自动生成表单；值统一写入值库；插件通过统一 API 读取生效值。
|
||
- **一句话**：插件在导入时调用 `register_plugin_config(plugin_id, schema, apply, getter)` 声明配置；值写入 `../../hexi/config/plugin_config.json`；Web 端读 `{schema, values}` 渲染、保存后写回并热应用。
|
||
|
||
- **`plugin_id` 约定**：必须等于 NoneBot 插件模块名（如 `hexi.plugins.nonebot_plugin_helldivers_tools`）。Web 的 `/api/plugins/<id>/config` 才能命中，插件目录合表也用该 id。
|
||
|
||
---
|
||
|
||
## 1. 相关文件与位置
|
||
|
||
```text
|
||
hexi/
|
||
├── web_hub/ # 统一 Web 管理台 / 鉴权 / 配置标准
|
||
│ ├── web_config.py # 配置标准核心：schema 注册 / 值库 / 保存热刷新
|
||
│ ├── config_standard.py # pydantic Config 一键接入的辅助封装
|
||
│ ├── web_auth.py # 统一 Web 鉴权（OAuth2 + SQLite）
|
||
│ ├── web_plugin_registry.py # 统一 Web 插件注册中心
|
||
│ └── web_hub_auth.py # 兼容 shim
|
||
├── config/
|
||
│ └── plugin_config.json # 统一值库：{ "<plugin_id>": { key: value, ... } }
|
||
└── web/ # /hub 前端(通用 schema 表单渲染器)
|
||
```
|
||
|
||
> 值库按**插件聚合**，不每个插件一个文件：Web「插件管理」一页聚合所有插件配置、统一热刷新、统一迁移。
|
||
|
||
---
|
||
|
||
## 2. Schema 字段标准
|
||
|
||
每个插件声明一份 schema：
|
||
|
||
```jsonc
|
||
{
|
||
"version": 1, // 插件配置 schema 版本(用于迁移)
|
||
"fields": [
|
||
{
|
||
"key": "hd2_api_base_url", // 必填，插件读取的字段名(snake_case)
|
||
"label": "API 根地址", // 必填，前端显示名
|
||
"type": "string", // 必填，见 §3
|
||
"default": "https://api.helldivers2.dev",
|
||
"description": "自托管 API 根地址；不填用公共社区 API。",
|
||
"secret": false, // true → 前端脱敏/掩码
|
||
"required": false,
|
||
"placeholder": "http://192.168.2.15:18080",
|
||
"env": "HD2_API_BASE_URL", // 写回 .env 的变量名；缺省 = key.upper()
|
||
"options": [ // type=enum 时必填
|
||
{ "value": "auto", "label": "自动" },
|
||
{ "value": "manual", "label": "手动" }
|
||
],
|
||
"min": 0, "max": 86400, // int/float 范围(可选)
|
||
"pattern": "^https?://", // 字符串校验(可选)
|
||
"group": "API 连接", // 表单分组(可选)
|
||
"depends_on": { "field": "enabled", "value": true }, // 条件显示(可选)
|
||
"item_type": "int", // type=list 的元素类型 int/float/str/bool(可选)
|
||
"newline_list": true // type=list 时：多行/逗号分隔(可选)
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `key` | string | 是 | 插件读取字段名，snake_case，唯一 |
|
||
| `label` | string | 是 | 前端显示名(中文) |
|
||
| `type` | string | 是 | 见 §3 |
|
||
| `default` | any | 否 | 用户未改时的回填默认 |
|
||
| `description` | string | 否 | 前端提示 |
|
||
| `secret` | bool | 否 | 敏感字段前端掩码，返回时脱敏 |
|
||
| `required` | bool | 否 | 保存时校验非空 |
|
||
| `options` | array | enum 必填 | `[{value,label}]` |
|
||
| `env` | string | 否 | 写 .env 变量名；缺省 `key.upper()` |
|
||
| `min` / `max` | number | 否 | 数值范围 |
|
||
| `pattern` | string | 否 | 字符串正则 |
|
||
| `item_type` | string | list 推荐 | 元素类型 |
|
||
| `newline_list` / `group` / `depends_on` | - | 否 | 展示/校验增强 |
|
||
|
||
---
|
||
|
||
## 3. 支持的 type
|
||
|
||
| type | 前端控件 | 存储 | 说明 |
|
||
|---|---|---|---|
|
||
| `string` | 单行输入 | 字符串 | 通用文本 |
|
||
| `text` | 多行文本域 | 字符串(支持 \n) | 长文本/提示词/模板 |
|
||
| `password` | 密码框(掩码) | 字符串 | 自动 `secret:true` |
|
||
| `int` | 数字输入 | 整数 | |
|
||
| `float` | 数字输入 | 浮点数 | |
|
||
| `bool` | 开关 | 布尔 | |
|
||
| `enum` | 下拉 | `options[].value` | 必须提供 options |
|
||
| `list` | 多行文本(每行一项) | 数组 | 需 `item_type`；兼容逗号分隔 |
|
||
| `json`/object | 代码文本域 | JSON 对象(校验后存) | 高级 |
|
||
| `path` | 单行输入 | 路径字符串 | 运行期转 `Path` |
|
||
| `object_set` | 通用表格(增删改) | list[dict] | 一组结构化条目；需 `item_schema` + `key_field`，见 §14 |
|
||
|
||
**约定**
|
||
- `key` 一律 snake_case。
|
||
- `secret` 字段只返回 `****`，绝不返回明文；提交未修改的 `****` 表示保持原值，只有提交 `null` 才清除。
|
||
- 复杂类型(`list`/`path`/`object`/`object_set`)在 `../../.env` 里不易安全表达，**只做运行期热更新**，不落 `../../.env`；重启需插件自行从值库读取。
|
||
|
||
---
|
||
|
||
## 4. 值文件存储标准
|
||
|
||
```jsonc
|
||
{
|
||
"hexi.plugins.nonebot_plugin_helldivers_tools": {
|
||
"hd2_api_base_url": "http://192.168.2.15:18080",
|
||
"hd2_api_language": "zh-Hans",
|
||
"hd2_cache_ttl": 60,
|
||
"hd2_super_client": "hexi-bot.local",
|
||
"hd2_super_contact": "https://github.com/..."
|
||
},
|
||
"hexi.plugins.nonebot_plugin_steam_info": {
|
||
"steam_api_key": ["key1", "key2"],
|
||
"steam_request_interval": 300,
|
||
"steam_broadcast_type": "part",
|
||
"steam_playtime_theme": "light",
|
||
"proxy": null
|
||
}
|
||
}
|
||
```
|
||
|
||
- 键 = `plugin_id`；值 = 仅**用户显式设置过**的字段（未设置不写死，避免覆盖 .env）。
|
||
- `null` 表示「清空/恢复默认」。
|
||
- **原子写入**：先写临时文件再 `os.replace`；启动读取失败时保留原文件并告警，不得静默覆盖为空。
|
||
- 读取优先级：**用户值库 > getter 生效值 > schema default**。
|
||
- 保存校验失败返回 HTTP 422，不能静默把非法输入替换成默认值。
|
||
- 值库按插件保存 `revision`；保存必须携带当前 revision，冲突返回 HTTP 409。
|
||
|
||
---
|
||
|
||
## 5. 插件读取配置的标准 API
|
||
|
||
### 方式 A：pydantic Config 一键接入(推荐)
|
||
|
||
```python
|
||
# 在插件 __init__.py 里
|
||
from hexi.web_hub.config_standard import register_model_config
|
||
from .config import config
|
||
|
||
register_model_config(
|
||
__name__, # = NoneBot 插件模块名
|
||
config, # 模块级 pydantic Config 实例
|
||
fields=["hd2_api_base_url", "hd2_cache_ttl", ...],
|
||
labels={"hd2_api_base_url": "API 根地址", ...},
|
||
descriptions={...},
|
||
options={"mode": [{"value": "auto", "label": "自动"}]},
|
||
types={"mode": "enum"}, # 覆盖自动推断的 type
|
||
)
|
||
```
|
||
|
||
运行期插件直接读 `config.hd2_api_base_url`。
|
||
|
||
`register_model_config` 自动：
|
||
- 推断字段类型(`bool/int/float/string/enum/text`)；
|
||
- `Literal[...]` → 下拉枚举；`list[str]`/`list[int]` → 多行文本并按元素类型转换；
|
||
- 内置 getter(回填当前生效值) 与 apply(保存后热更新 pydantic 对象，无需重启)；
|
||
- 密码/key/token 类字段自动 `secret=True`。
|
||
|
||
### 方式 B：非 pydantic 插件手动注册
|
||
|
||
```python
|
||
from hexi.web_hub.web_config import register_plugin_config
|
||
|
||
def _get(): # 返回当前生效值 dict
|
||
return {"field": get_my_cur_value("field")}
|
||
|
||
def _apply(values): # 保存后热应用
|
||
set_my_config(values)
|
||
|
||
register_plugin_config(
|
||
__name__,
|
||
{"fields": [{"key": "field", "label": "字段", "type": "string", "default": ""}]},
|
||
apply=_apply,
|
||
getter=_get,
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
> **同一插件可多次注册**：`register_plugin_config` / `register_model_config` / `register_config_items` / `register_object_set` 对同一 `plugin_id` 重复调用时，**字段按 key 自动合并到一个 schema**，getter 合并取值，apply 按注册顺序依次应用(不覆盖)。所以 `config.py` 里分多段注册(如 temp 清理 / S3 / 群分组 / object_set)是合理且推荐的。
|
||
|
||
## 6. 值读取优先级
|
||
|
||
`get_config(plugin_id)` 对每个字段按序取值：
|
||
|
||
1. **用户已保存值**(值库 `plugin_config.json`)；
|
||
2. **getter 返回的当前生效值**(插件运行态)；
|
||
3. **schema.default**；
|
||
4. `None`。
|
||
|
||
这样 Web 表单打开时显示的是**插件当前真正生效的配置**，而不是只看默认值。
|
||
|
||
---
|
||
|
||
## 7. 保存流程(热刷新)
|
||
|
||
`save_config(plugin_id, values)`：
|
||
|
||
1. 按 schema 字段的 type/`item_type` 做 **类型校验与转换**(string/int/float/bool/enum/list)。
|
||
2. **写值库** `plugin_config.json`(原子写)。
|
||
3. **写 .env**：非 list 字段写入 `os.environ` + `../../.env`(保证重启仍生效)；list/path/object 跳过，避免 `str(list)` 破坏重启解析。
|
||
4. **调 `apply(values)`**：把值热应用到插件运行态对象(list/path/object 也在此生效)。
|
||
5. 若插件未提供 apply，则 `hot_reload(plugin_id)` 让插件重载；**library/非 application 插件不受热重载**（见《插件类型分类》，热拔插会破坏依赖它的插件）。
|
||
|
||
**为什么 apply 与 env 都做**：NoneBot 的 `get_driver().config` 在启动时即固定，重载插件也读不到新 env；所以运行期必须 apply，重启靠 env。
|
||
|
||
---
|
||
|
||
## 8. Web 端「读 / 改」标准接口(/hub)
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| GET | `/api/plugins` | 所有已注册 Web 插件 |
|
||
| GET | `/api/plugins/catalog` | 所有 application/library 插件（含带配置项的 library）+ `type/has_config/has_web/web_path` |
|
||
| GET | `/api/plugins/{id}/config` | 读 `{schema, values, revision}`(登录)；secret 值只返回 `****` |
|
||
| POST | `/api/plugins/{id}/config` | 保存 `{ "revision": n, "values": { key: value } }`；冲突 409，校验失败 422 |
|
||
| DELETE | `/api/plugins/{id}/config` | 清空该插件覆盖，恢复默认(可选) |
|
||
|
||
响应示例(GET)：
|
||
|
||
```jsonc
|
||
{
|
||
"ok": true,
|
||
"revision": 3,
|
||
"schema": { "fields": [ { "key": "hd2_cache_ttl", "type": "int", "default": 60, ... } ] },
|
||
"values": { "hd2_cache_ttl": 60, "hd2_api_base_url": "http://192.168.2.15:18080" }
|
||
}
|
||
```
|
||
|
||
前端 `../../hexi/web/src/pages/plugins/index.tsx` 已按 `type` 自动渲染：bool→开关、enum→下拉、text→多行、password→掩码、int/float→数字、secret→脱敏。
|
||
|
||
---
|
||
|
||
## 9. 权限与安全
|
||
|
||
- 全部配置接口走 `hexi.web_hub.web_auth.require_admin`(OAuth2 + SQLite)。
|
||
- 配置 POST 必须携带 GET 返回的 `revision`；缺失返回 428，冲突返回 409。
|
||
- 只允许 `plugin_id` 存在于注册表，未注册返回 `ok:false`(防任意写入)。
|
||
- 部署时必须显式设置 Web 管理员凭据；禁止生产环境使用默认的 `admin/admin`。
|
||
- `secret` 字段只返回 `****`；提交 `****` 保持原值，提交 `null` 清除，写回明文仅限服务端受控存储。
|
||
- 写 .env 用「原行更新/追加」，保留注释，不整文件覆盖。
|
||
|
||
---
|
||
|
||
## 10. 版本与迁移
|
||
|
||
配置保存状态至少区分：`persisted`（值库已保存）、`applied`（运行态已应用）、`restart_required`（需重启）和 `apply_failed`（应用失败）。apply 失败时接口必须返回错误，且保留上一份可恢复配置。
|
||
|
||
```jsonc
|
||
{
|
||
"$schema_version": 3,
|
||
"plugins": {
|
||
"hexi.plugins.xxx": {
|
||
"schema_version": 1,
|
||
"values": { "...": "..." }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- 升级 schema 时保留 `values`：新增字段取 `default`，删除字段清理。
|
||
- 提供 `migrate(plugin_id, old_schema, new_schema)` 钩子，支持字段改名/类型升级/`str` 列表迁 `list[int]`；迁移必须幂等，失败时保留旧值文件并阻止该插件配置加载。
|
||
- 读到未知插件条目时保留并上报，不强制删除。
|
||
|
||
---
|
||
|
||
## 11. 落地示例
|
||
|
||
```python
|
||
# hexi/plugins/nonebot_plugin_helldivers_tools/__init__.py
|
||
from hexi.web_hub.config_standard import register_model_config
|
||
from .config import config as _hd2_config
|
||
|
||
register_model_config(
|
||
__name__,
|
||
_hd2_config,
|
||
fields=["hd2_api_base_url", "hd2_api_language", "hd2_cache_ttl",
|
||
"hd2_super_client", "hd2_super_contact"],
|
||
labels={"hd2_api_base_url": "API 根地址", "hd2_cache_ttl": "数据缓存秒数", ...},
|
||
descriptions={"hd2_api_base_url": "自托管 API 根地址；不填用公共社区 API", ...},
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 已接入与待接入
|
||
|
||
- **已接入**：`helldivers_tools`、`mc_server_status`、`video_analysis`、`steam_info`、`picstatus`、`galgame_card`。
|
||
- **未接入(建议后续)**：`learning_chat`、`group_daily_analysis`(已有独自 Web 配置，避免冲突)、`picfinder_take`、`bf_bot`、`group_tools`、`hexi/core`(模块级常量/SUPERUSERS，运行期热更复杂)。
|
||
|
||
|
||
---
|
||
|
||
## 13. 插件内部配置项(来源无关)接入标准
|
||
|
||
> **不只是 `../../.env`**：插件内部自己的配置项(module 常量、YAML/JSON 配置、数据库里的开关等)同样遵循统一 schema，Web 可读可改。核心是让每个配置项自带 **getter/setter**，与来源解耦。
|
||
|
||
### 13.1 四种来源与接入方式
|
||
|
||
| 配置来源 | 接入方式 | getter/setter | 持久化 | 运行期生效点 |
|
||
|---|---|---|---|---|
|
||
| pydantic Config(`../../.env` 驱动) | `register_model_config` | 自动(读写 Config 对象) | 写值库 + 写 `../../.env` | apply 热更新对象 |
|
||
| 模块常量 | `register_config_items(..., store=模块)` | 自动(getattr/setattr) | 写值库(可选写 `../../.env`) | 需插件用 `get_effective_value` 读取 |
|
||
| 配置文件(dict/JSON/YAML) | `register_config_items(..., store=dict)` | 自动(读写 dict) | 插件自身写回文件 / 值库 | 插件从 dict 读取时即生效 |
|
||
| 自定义(DB/运行态) | `register_config_items` 传 `getter`/`setter` | 自定义 | 自定义回写 | 自定义 |
|
||
|
||
### 13.2 通用注册 API(任意来源)
|
||
|
||
```python
|
||
from hexi.web_hub.config_standard import register_config_items
|
||
|
||
register_config_items(
|
||
__name__, # = NoneBot 插件模块名
|
||
[
|
||
{"key": "DAILY_LIMIT", "label": "每日限额", "type": "int", "default": 50},
|
||
{"key": "CHECK", "label": "开启截屏判定", "type": "bool", "default": True},
|
||
{"key": "SAUCENAO_KEY", "label": "API Key", "type": "password", "secret": True},
|
||
# 也可为某条目自定义 getter/setter
|
||
{"key": "custom", "label": "自定义", "type": "string",
|
||
"getter": lambda: my_get(), "setter": lambda v: my_set(v)},
|
||
],
|
||
store=config_module, # dict 或模块；未写 getter/setter 时默认读写这里
|
||
apply_extra=None, # 可选：保存后做额外持久化/热加载
|
||
getter_extra=None, # 可选：getter 额外返回非 items 的值
|
||
)
|
||
```
|
||
|
||
### 13.3 关键规则：运行期要生效，插件必须读生效值
|
||
|
||
Web 保存后 apply 会把新值写回来源(模块属性/dict/自定义)，但若插件在别处是用 `from .config import X` **值拷贝**进来的量，不受影响。要真正运行期生效，插件在读配置处改用统一 API：
|
||
|
||
```python
|
||
from hexi.web_hub.web_config import get_effective_value
|
||
|
||
limit = get_effective_value("hexi.plugins.nonebot_plugin_picfinder_take", "DAILY_LIMIT", 50)
|
||
if not check_quota(limit): ...
|
||
```
|
||
|
||
优先级：**用户值库 > getter 生效值 > default**。这样 Web 改完即可生效，重启也不丢。
|
||
|
||
### 13.4 已接入的非 env 示例
|
||
|
||
- `picfinder_take`：把 `SAUCENAO_KEY / DAILY_LIMIT / SEARCH_TIMEOUT / CHECK / THUMB_ON / CHAIN_REPLY / IGNORE_STAMP / threshold` 这些内部常量注册为 Web 可读可改配置项(store=config 模块)。
|
||
|
||
- `video_analysis`：把原本硬编码在 `storage/s3.py` 的 S3 连接配置(PLANA/PLANB/PLANC/公网 endpoint/access/secret/bucket/region/secure/domain)注册为 Web 可读可改项；apply 时清空懒加载 S3 客户端缓存，且 s3 客户端创建时经 `get_effective_value` 读取，因此**运行期与重启均生效**。另用 `type=json` 暴露 `data/list.json` 的**群分组配置**(`groups` + `blacklist`)，自定义 getter/setter 同步读写，并标记 `nosave`(不写入 plugin_config.json，权威源是 list.json)，避免与 `添加白名单` 等指令互相覆盖为陈旧值。
|
||
|
||
- **生效说明**：注册后 Web 能读、能改、会持久化；若希望改完立刻反映到插件行为，需把插件内对应读取点改成 `get_effective_value`(见 §13.3)，或让 apply_extra 里 `hot_reload` 并让 config 模块从值库初始化。
|
||
|
||
---
|
||
|
||
## 14. 通用对象集标准(object_set)
|
||
|
||
> 当插件要暴露「一组结构化条目」时(群分组、测速站点、服务器列表、白/黑名单成员、装备表等)，用 `object_set` 类型声明 **item_schema + key_field**，Web 端通用渲染成可增删改的表格，后端通用按子字段校验/去重。
|
||
|
||
### 14.1 Schema 形态
|
||
|
||
```jsonc
|
||
{
|
||
"key": "groups",
|
||
"label": "群分组配置",
|
||
"type": "object_set",
|
||
"key_field": "group_id", // 子字段主键(定位/去重/删除行)
|
||
"item_schema": {
|
||
"fields": [
|
||
{"key": "group_id", "label": "群号", "type": "string", "required": true},
|
||
{"key": "auto", "label": "自动解析", "type": "bool", "default": false},
|
||
{"key": "plan", "label": "存储方案", "type": "enum",
|
||
"options": [{"value":"A","label":"A"},{"value":"B","label":"B"}]},
|
||
{"key": "auto_link", "label": "自动链接关键词", "type": "text", "item_type": "str"}
|
||
]
|
||
},
|
||
"default": [],
|
||
"nosave": true // 权威源在插件自身文件/DB 时填 true
|
||
}
|
||
```
|
||
|
||
### 14.2 值形态
|
||
|
||
```jsonc
|
||
[
|
||
{"group_id":"123", "auto":true, "plan":"A", "auto_link":["xhs"]},
|
||
{"group_id":"456", "auto":false, "plan":null, "auto_link":[]}
|
||
]
|
||
```
|
||
|
||
### 14.3 一键注册 API
|
||
|
||
```python
|
||
from hexi.web_hub.config_standard import register_object_set
|
||
|
||
register_object_set(
|
||
__name__, # NoneBot 插件模块名
|
||
"groups", # 对象集配置 key
|
||
[ # item_schema 子字段
|
||
{"key": "group_id", "label": "群号", "type": "string"},
|
||
{"key": "auto", "label": "自动解析", "type": "bool", "default": True},
|
||
{"key": "plan", "label": "方案", "type": "enum",
|
||
"options": [{"value":"A","label":"A"},{"value":"B","label":"B"}]},
|
||
{"key": "auto_link", "label": "关键词", "type": "text", "item_type": "str"},
|
||
],
|
||
key_field="group_id",
|
||
getter=get_groups, # () -> list[dict]
|
||
setter=set_groups, # (list[dict]) -> None(插件自行写回来源)
|
||
label="群分组配置",
|
||
nosave=True, # 权威源在 list.json/DB,不写 plugin_config.json
|
||
)
|
||
```
|
||
|
||
框架自动做：**按 `item_schema` 逐字段类型转换**(bool/int/float/string/enum/text/list/json)、触发 `_coerce_value` 的值转成目标类型、**按 `key_field` 去重并丢弃缺主键行**，再把归一整形的 list 交给你的 setter。
|
||
|
||
### 14.4 Web 端通用表格组件(建议)
|
||
|
||
- 前端新增 `ObjectSetEditor` 组件，读 `field.item_schema.fields` 渲染表头 + 每行输入(与 §3 type 一一对应)；
|
||
- 支持：**添加行、删除行、编辑单元格、上移/下移**(可选)；主键列默认唯一校验；
|
||
- 保存时把整个 list 提交到既有 `POST /api/plugins/{id}/config`，无需新接口；
|
||
- 也可按需加细粒度：`POST /api/plugins/{id}/config/{key}` 单条 upsert、`DELETE .../{key}/{key_value}` 删除单行(后端需在 apply 里实现 upsert/delete)。
|
||
|
||
### 14.5 可接入示范(候选)
|
||
|
||
- `video_analysis`：`list.json` 的 `groups` 群分组(从纯 JSON 升级为结构化 object_set，Key=group_id)；
|
||
- `picstatus`：`ps_test_sites` 测速站点列表(Key=name)；
|
||
- `mc_server_status`：`var.group_list` 每群服务器列表(Key=群号)；
|
||
- `helldivers_tools`：战备数据(可只读展示，来源 SQLite，Key=id)；
|
||
- `learning_chat`：分群配置(Key=group_id)。
|