目录
简介
QQ 官方机器人的指令面板（用户在聊天框看到的命令菜单）只能通过 OpenAPI 管理，没有官方可视化界面。Maestro 作为 NoneBot 插件随 bot 启动，提供一个本地 WebUI 来做这件事：
- 多机器人卡片，按
QQ_BOTS配置逐个列出 - 四种场景（群聊 / 私聊 / 频道 / 频道私信）分别管理，标签页显示各自面板数
- 指令项增删改、拖拽排序
- 提交前本地校验：显示宽度、
https链接、数量上限 - QQ 侧业务错误转成可读提示，不再是
500 Internal Server Error
界面预览
 |
 |
| 机器人列表 | 面板编辑 |
安装
nb-cli
nb plugin install nonebot-plugin-maestro
包管理器
uv add nonebot-plugin-maestro
# 或
pip install nonebot-plugin-maestro
安装后在 pyproject.toml 的 [tool.nonebot] 中加载：
plugins = ["nonebot_plugin_maestro"]
配置
在宿主 bot 的 .env 中配置。全部可选，插件支持零配置加载。
| 配置项 | 默认值 | 说明 |
|---|---|---|
MAESTRO_HOST |
127.0.0.1 |
WebUI 监听地址 |
MAESTRO_PORT |
8100 |
WebUI 监听端口 |
MAESTRO_ENABLED |
true |
是否启用 WebUI |
MAESTRO_TOKEN |
空（不启用） | API 访问令牌。设置后所有 /api/* 请求须携带 X-Maestro-Token 头；WebUI 会弹窗引导输入，也支持 ?token=... 直接带入 |
WebUI 跑在自己的 uvicorn 上，端口与 NoneBot 的 PORT 相互独立（默认 8100 就是为了避开 NoneBot 的 8080）。
driver 需提供 HTTP 客户端——适配器 setup() 强制要求 HTTPClientMixin：
DRIVER=~httpx+~websockets
使用
bot 启动后访问 http://127.0.0.1:8100。机器人 WebSocket 连接成功后才会出现在列表中。
注意事项
字段长度按显示宽度计算，不是字符数。QQ 服务端对非 ASCII 字符计 2：name ≤ 14、desc ≤ 30。
超限时服务端返回 code=30013「超出数量限制」——这个错误码同时用于数量超限，容易误判。WebUI 会实时显示宽度并在提交前拦截。
写接口限频 10 QPM（创建 / 修改 / 删除），每个机器人最多 20 个面板（跨场景合计）。
开发
uv sync # 安装依赖
uv run poe test # 测试（含覆盖率）
uv run poe lint # ruff 检查
uv run poe typecheck # pyrefly 类型检查
uv run python bot.py # 本地起一个 bot 调试
前端资源在 src/nonebot_plugin_maestro/static/（index.html / app.css / app.js），不内嵌在 Python 里。
想贡献代码？看 CONTRIBUTING.md。面板接口的实测细节与架构决策见 docs/。
许可
1 maintainer
Metadata
1 maintainer
Release files for nonebot-plugin-maestro 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| nonebot_plugin_maestro-0.2.0.tar.gz | 45.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nonebot_plugin_maestro-0.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 96.9 kB
Release files / nonebot_plugin_maestro-0.2.0.tar.gz
| Download URL | nonebot_plugin_maestro-0.2.0.tar.gz |
|---|---|
| Size | 45.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f5135811e0e151e03141f3daa1009551aeb4f134fcace47134baf8acf0372125
|
|
BLAKE2b-256 checksum How to use checksums |
36e5c9e7871521ec31b77a7b722fd883429afd7ac7205536f22f646216a68efa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / nonebot_plugin_maestro-0.2.0-py3-none-any.whl
| Download URL | nonebot_plugin_maestro-0.2.0-py3-none-any.whl |
|---|---|
| Size | 51.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a30e1855e67a96b5a48214c8c2e144016e4b300e80c9e22d0bf8b6c7c635adb1
|
|
BLAKE2b-256 checksum How to use checksums |
ace7374f63b178ef1351315bc9f55baaf0430dd19a829a27268db5dc793efb1e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
