File size: 7,945 Bytes
8ede856 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 |
# Plugin Configuration
As plugin functionality grows, you may need to define configurations to allow users to customize plugin behavior.
AstrBot provides "powerful" configuration parsing and visualization features. Users can configure plugins directly in the management panel without modifying code.
## Configuration Definition
To register configurations, first add a `_conf_schema.json` JSON file in your plugin directory.
The file content is a `Schema` that represents the configuration. The Schema is in JSON format, for example:
```json
{
"token": {
"description": "Bot Token",
"type": "string",
},
"sub_config": {
"description": "Test nested configuration",
"type": "object",
"hint": "xxxx",
"items": {
"name": {
"description": "testsub",
"type": "string",
"hint": "xxxx"
},
"id": {
"description": "testsub",
"type": "int",
"hint": "xxxx"
},
"time": {
"description": "testsub",
"type": "int",
"hint": "xxxx",
"default": 123
}
}
}
}
```
- `type`: **Required**. The type of the configuration. Supports `string`, `text`, `int`, `float`, `bool`, `object`, `list`, `dict`, `template_list`, `file`. When the type is `text`, it will be visualized as a larger resizable textarea component to accommodate large text.
- `description`: Optional. Description of the configuration. A one-sentence description of the configuration's behavior is recommended.
- `hint`: Optional. Hint information for the configuration, displayed in the question mark button on the right in the image above, shown when hovering over it.
- `obvious_hint`: Optional. Whether the configuration hint should be prominently displayed, like `token` in the image above.
- `default`: Optional. The default value of the configuration. If the user hasn't configured it, the default value will be used. Default values: int is 0, float is 0.0, bool is False, string is "", object is {}, list is [].
- `items`: Optional. If the configuration type is `object`, the `items` field needs to be added. The content of `items` is the sub-Schema of this configuration item. Theoretically, it can be nested infinitely, but excessive nesting is not recommended.
- `invisible`: Optional. Whether the configuration is hidden. Default is `false`. If set to `true`, it will not be displayed in the management panel.
- `options`: Optional. A list, such as `"options": ["chat", "agent", "workflow"]`. Provides dropdown list options.
- `editor_mode`: Optional. Whether to enable code editor mode. Requires AstrBot >= `v3.5.10`. Versions below this won't report errors but won't take effect. Default is false.
- `editor_language`: Optional. The code language for the code editor, defaults to `json`.
- `editor_theme`: Optional. The theme for the code editor. Options are `vs-light` (default) and `vs-dark`.
- `_special`: Optional. Used to call AstrBot's visualization features for provider selection, persona selection, knowledge base selection, etc. See details below.
When the code editor is enabled, it looks like this:
The **_special** field is only available after v4.0.0. Currently supports `select_provider`, `select_provider_tts`, `select_provider_stt`, `select_persona`, allowing users to quickly select model providers, personas, and other data already configured in the WebUI. Results are all strings. Using select_provider as an example, it will present the following effect:
### `file` type schema
Introduced in v4.13.0, this allows plugins to define file-upload configuration items to guide users to upload files required by the plugin.
```json
{
"demo_files": {
"type": "file",
"description": "Uploaded files for demo",
"default": [],
"file_types": ["pdf", "docx"]
}
}
```
### `dict` type schema
Used to visualize editing a Python `dict` type configuration. For example, AstrBot Core's custom extra body parameter configuration:
```py
"custom_extra_body": {
"description": "Custom request body parameters",
"type": "dict",
"items": {},
"hint": "Used to add extra parameters to requests, such as temperature, top_p, max_tokens, etc.",
"template_schema": {
"temperature": {
"name": "Temperature",
"description": "Temperature parameter",
"hint": "Controls randomness of output, typically 0-2. Higher is more random.",
"type": "float",
"default": 0.6,
"slider": {"min": 0, "max": 2, "step": 0.1},
},
"top_p": {
"name": "Top-p",
"description": "Top-p sampling",
"hint": "Nucleus sampling parameter, typically 0-1. Controls probability mass considered.",
"type": "float",
"default": 1.0,
"slider": {"min": 0, "max": 1, "step": 0.01},
},
"max_tokens": {
"name": "Max Tokens",
"description": "Maximum tokens",
"hint": "Maximum number of tokens to generate.",
"type": "int",
"default": 8192,
},
},
}
```
### `template_list` type schema
> [!NOTE]
> Introduced in v4.10.4. For more details see: [#4208](https://github.com/AstrBotDevs/AstrBot/pull/4208)
Plugin developers can add a template-style configuration to `_conf_schema` in the following format (somewhat similar to nested configs):
```json
"field_id": {
"type": "template_list",
"description": "Template List Field",
"templates": {
"template_1": {
"name": "Template One",
"hint":"hint",
"items": {
"attr_a": {
"description": "Attribute A",
"type": "int",
"default": 10
},
"attr_b": {
"description": "Attribute B",
"hint": "This is a boolean attribute",
"type": "bool",
"default": true
}
}
},
"template_2": {
"name": "Template Two",
"hint":"hint",
"items": {
"attr_c": {
"description": "Attribute A",
"type": "int",
"default": 10
},
"attr_d": {
"description": "Attribute B",
"hint": "This is a boolean attribute",
"type": "bool",
"default": true
}
}
}
}
}
```
Saved config example:
```json
"field_id": [
{
"__template_key": "template_1",
"attr_a": 10,
"attr_b": true
},
{
"__template_key": "template_2",
"attr_c": 10,
"attr_d": true
}
]
```
<img width="1000" alt="image" src="https://github.com/user-attachments/assets/74876d30-11a4-491b-a7a0-8ebe8d603782" />
## Using Configuration in Plugins
When loading plugins, AstrBot will check if there's a `_conf_schema.json` file in the plugin directory. If it exists, it will automatically parse the configuration and save it under `data/config/<plugin_name>_config.json` (a configuration file entity created according to the Schema), and pass it to `__init__()` when instantiating the plugin class.
```py
from astrbot.api import AstrBotConfig
class ConfigPlugin(Star):
def __init__(self, context: Context, config: AstrBotConfig): # AstrBotConfig inherits from Dict and has all dictionary methods
super().__init__(context)
self.config = config
print(self.config)
# Supports direct configuration saving
# self.config.save_config() # Save configuration
```
## Configuration Updates
When you update the Schema across different versions, AstrBot will recursively inspect the configuration items in the Schema, automatically adding default values for missing items and removing those that no longer exist. |