目录
简介
QQ 官方机器人的指令面板（用户在聊天输入框旁看到的命令菜单）目前只能通过 OpenAPI 管理，官方没有提供可视化界面。Maestro 是一个 NoneBot 插件，随 bot 启动后在本地提供一个网页版的管理界面：
- 按
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/* 请求都要携带 X-Maestro-Token 请求头；WebUI 会弹窗引导输入，也可以在网址后加 ?token=... 传入 |
WebUI 使用独立的 uvicorn 服务，端口与 NoneBot 的 PORT 互不影响。默认选 8100，就是为了避开 NoneBot 常用的 8080。
QQ 适配器要求 driver 提供 HTTP 客户端（连接 QQ 事件用 WebSocket），.env 里这样配置：
DRIVER=~httpx+~websockets
使用
启动 bot 后用浏览器打开 http://127.0.0.1:8100。机器人要等 WebSocket 连接成功后才会出现在列表里。
注意事项
字段长度按显示宽度计算，不是字符数。 QQ 服务端统计长度时非 ASCII 字符按 2 计：name 上限 14，desc 上限 30。
宽度超限时服务端返回 code=30013「超出数量限制」——这个错误码同时用于真正的数量超限，光看报错很容易误判。WebUI 会实时显示当前宽度，并在提交前拦下超限内容。
写接口（创建 / 修改 / 删除）限频 10 QPM，每个机器人最多 20 个面板（跨场景合计）。连续保存触发限频时会收到 429 提示，稍等片刻再试即可。
开发
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.5.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.5.0.tar.gz | 51.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nonebot_plugin_maestro-0.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 109.1 kB
Release files / nonebot_plugin_maestro-0.5.0.tar.gz
| Download URL | nonebot_plugin_maestro-0.5.0.tar.gz |
|---|---|
| Size | 51.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e51fc8ac6233dec30955d1d2b1049e7060f189ab34c45a85145763299a771d98
|
|
BLAKE2b-256 checksum How to use checksums |
7ec781bcbbff5a326ec4b873a0290de40266e15446b58c5da2ef5f04986fc3cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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.5.0-py3-none-any.whl
| Download URL | nonebot_plugin_maestro-0.5.0-py3-none-any.whl |
|---|---|
| Size | 57.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
12b85dc654d46de41affa34a5cdf3fce864fa06cd0c427346845b4d1b897b81b
|
|
BLAKE2b-256 checksum How to use checksums |
a2e45325342250736d03df865a96a3ad629ef45f842f2f820781a59e084ba053
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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}
|
