Maestro

QQ 官方机器人指令面板可视化管理工具

随 NoneBot 启动一个本地 WebUI，在浏览器里查看和编辑 QQ 机器人的指令面板。

简介

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。

适配器要求 driver 提供 HTTP 客户端，需要在 .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/。

许可

MIT

Metadata

Release files for nonebot-plugin-maestro 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nonebot-plugin-maestro 0.4.0
File	Size	Uploaded
nonebot_plugin_maestro-0.4.0.tar.gz	46.9 kB	Sep 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for nonebot-plugin-maestro 0.4.0
File	Interpreter	ABI	Platform	Reset
nonebot_plugin_maestro-0.4.0-py3-none-any.whl 52.7 kB Sep 5, 2026	Python 3	none	any	Details

Total release size: 99.6 kB

Release files / nonebot_plugin_maestro-0.4.0.tar.gz

Download URL	nonebot_plugin_maestro-0.4.0.tar.gz
Size	46.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`76a7433b3bda78fcd6dfd31a3686bde8a321417da2f7fdc4812ca2e8eb1c555d`
BLAKE2b-256 checksum How to use checksums	`c66e90693bf5b78ff248c557ad0c770d9e48247ab8ab46dbb193c9f6538bb134`
Upload date	Sep 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","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.4.0-py3-none-any.whl

Download URL	nonebot_plugin_maestro-0.4.0-py3-none-any.whl
Size	52.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1717108eac6dbe7b45046f09058944daa077c8cbc92c5a31ef721ad0ce4993f9`
BLAKE2b-256 checksum How to use checksums	`80d7d35aabbfd946bdc6f01322a3f551c3923bf784e6a5073e9ef9b6ec241666`
Upload date	Sep 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","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}`