📖 介绍
NoneBot2 群头衔管理插件，支持单用户设置和批量设置 QQ 群专属头衔。
- 单用户设置头衔：快速修改自己或指定群成员的专属头衔
- 批量设置头衔：一次 @多名成员，批量设置相同头衔，自动串行限流防风控
- 权限校验：机器人需为群主（QQ 官方接口硬性限制），修改他人头衔需管理员
- 头衔长度校验：自动检测 GBK 字节数，防止超长头衔被 QQ 拒绝
- 冷却限流：单用户命令和批量命令分别设置冷却时间，防止滥用
- Alconna 优化：使用 Alconna 命令解析器，类型安全参数获取，支持自动生成帮助信息
💿 安装
使用 nb-cli 安装
在 nonebot2 项目的根目录下打开命令行, 输入以下指令即可安装nb plugin install nonebot-plugin-set-title --upgrade
使用 pypi 源安装
nb plugin install nonebot-plugin-set-title --upgrade -i "https://pypi.org/simple"
使用 清华源 安装
nb plugin install nonebot-plugin-set-title --upgrade -i "https://pypi.tuna.tsinghua.edu.cn/simple"
使用包管理器安装
在 nonebot2 项目的插件目录下, 打开命令行, 根据你使用的包管理器, 输入相应的安装命令uv
uv add nonebot-plugin-set-title
安装仓库 master 分支
uv add git+https://github.com/FlakoWESH/nonebot-plugin-set-title@master
pdm
pdm add nonebot-plugin-set-title
安装仓库 master 分支
pdm add git+https://github.com/FlakoWESH/nonebot-plugin-set-title@master
poetry
poetry add nonebot-plugin-set-title
安装仓库 master 分支
poetry add git+https://github.com/FlakoWESH/nonebot-plugin-set-title@master
打开 nonebot2 项目根目录下的 pyproject.toml 文件, 在 [tool.nonebot] 部分追加写入
plugins = ["nonebot_plugin_set_title"]
⚙️ 配置
在 .env 文件中添加以下配置（均为可选，有默认值）：
| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
| SET_TITLE_BATCH_INTERVAL | 否 | 0.5 |
批量修改时每次 API 调用间隔（秒），防止 QQ 风控 |
| SET_TITLE_BATCH_ADMIN_ONLY | 否 | true |
批量功能是否仅允许群管理员使用 |
| SET_TITLE_MAX_GBK_LENGTH | 否 | 12 |
头衔最大 GBK 字节数（约 6 个汉字） |
| SET_TITLE_CD | 否 | 10 |
单用户命令冷却时间（秒） |
| SET_TITLE_BATCH_CD | 否 | 15 |
批量命令冷却时间（秒） |
🎉 使用
指令表
| 指令 | 说明 |
|---|---|
| qst <头衔> | 修改自己的头衔 |
| qst <头衔> @用户 | 修改指定用户的头衔 |
| 批量设置头衔 <头衔> @用户1 @用户2 | 批量设置多名成员的头衔 |
别名：批量改头衔、批量设置群头衔
使用示例
qst 已登记
qst 管理员 @123456
批量设置头衔 已登记 @用户1 @用户2 @用户3
⚠️ 注意事项
- 机器人必须为群主：QQ 官方接口
set_group_special_title要求调用者为群主，否则会失败 - 头衔长度限制：QQ 官方限制头衔最多约 6 个汉字（12 字节 GBK），超长会被拒绝
- 批量限流：批量设置几十人不会触发风控；若需批量上百人，建议调大
SET_TITLE_BATCH_INTERVAL - 协议端兼容：基于 OneBot v11 标准 API 开发，适配 go-cqhttp、NapCatQQ、Lagrange.Core 等主流协议端
1 maintainer
Metadata
1 maintainer
Release files for nonebot-plugin-set-title 0.1.1
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_set_title-0.1.1.tar.gz | 7.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nonebot_plugin_set_title-0.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 15.5 kB
Release files / nonebot_plugin_set_title-0.1.1.tar.gz
| Download URL | nonebot_plugin_set_title-0.1.1.tar.gz |
|---|---|
| Size | 7.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a814ca993ecac91b224d97cb6ecc419d55f3e1bb78db2629584f23983e6a4c93
|
|
BLAKE2b-256 checksum How to use checksums |
a15b2d84e5d78fefc5c6bc04f3f42ce7f14f43eec2a8ccf016b7069d096a358f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.11
|
Release files / nonebot_plugin_set_title-0.1.1-py3-none-any.whl
| Download URL | nonebot_plugin_set_title-0.1.1-py3-none-any.whl |
|---|---|
| Size | 8.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
af065728b034d49274be3267fe8ad5648b45bc15a8add735900c61d2bb609b96
|
|
BLAKE2b-256 checksum How to use checksums |
b6e33f967a31b4a22e0c5f4fc68909d30bfdd4eb6bcb83d746d392b92d6ed10f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.11
|
