Metadata-Version: 2.5
Name: nonebot-plugin-set-title
Version: 0.1.0
Summary: NoneBot2 群头衔管理插件，支持单用户/批量设置QQ群专属头衔（Alconna优化版）
Project-URL: Homepage, https://github.com/FlakoWESH/nonebot-plugin-set-title
Project-URL: Repository, https://github.com/FlakoWESH/nonebot-plugin-set-title
Project-URL: Issues, https://github.com/FlakoWESH/nonebot-plugin-set-title/issues
Author-email: FlakoWESH <FlakoWESH@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: alconna,group,nonebot,nonebot2,plugin,qq,set-title,title
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: nonebot-adapter-onebot>=2.0.0
Requires-Dist: nonebot-plugin-alconna>=0.50.0
Requires-Dist: nonebot2>=2.0.0
Description-Content-Type: text/markdown

<div align="center">
    <a href="https://v2.nonebot.dev/store">
    <img src="https://raw.githubusercontent.com/fllesser/nonebot-plugin-template/refs/heads/resource/.docs/NoneBotPlugin.svg" width="310" alt="logo"></a>

## ✨ nonebot-plugin-set-title ✨
[![LICENSE](https://img.shields.io/github/license/FlakoWESH/nonebot-plugin-set-title.svg)](./LICENSE)
[![pypi](https://img.shields.io/pypi/v/nonebot-plugin-set-title.svg)](https://pypi.python.org/pypi/nonebot-plugin-set-title)
[![python](https://img.shields.io/badge/python-3.10|3.11|3.12|3.13-blue.svg)](https://www.python.org)
<br/>
[![ruff](https://img.shields.io/badge/code%20style-ruff-black?style=flat-square&logo=ruff)](https://github.com/astral-sh/ruff)
[![nonebot2](https://img.shields.io/badge/nonebot-2.0+-red.svg)](https://v2.nonebot.dev)
[![alconna](https://img.shields.io/badge/Alconna-powered-blue?style=flat-square)](https://github.com/nonebot/plugin-alconna)

</div>

## 📖 介绍

NoneBot2 群头衔管理插件，支持单用户设置和批量设置 QQ 群专属头衔。基于 Alconna 命令解析器优化，类型安全，跨平台兼容。

- **单用户设置头衔**：快速修改自己或指定群成员的专属头衔
- **批量设置头衔**：一次 @多名成员，批量设置相同头衔，自动串行限流防风控
- **权限校验**：机器人需为群主（QQ 官方接口硬性限制），修改他人头衔需管理员
- **头衔长度校验**：自动检测 GBK 字节数，防止超长头衔被 QQ 拒绝
- **冷却限流**：单用户命令和批量命令分别设置冷却时间，防止滥用
- **Alconna 优化**：使用 Alconna 命令解析器，类型安全参数获取，支持自动生成帮助信息

## 💿 安装

<details open>
<summary>使用 nb-cli 安装</summary>
在 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"

</details>

<details>
<summary>使用包管理器安装</summary>
在 nonebot2 项目的插件目录下, 打开命令行, 根据你使用的包管理器, 输入相应的安装命令

<details open>
<summary>uv</summary>

    uv add nonebot-plugin-set-title

安装仓库 master 分支

    uv add git+https://github.com/FlakoWESH/nonebot-plugin-set-title@master
</details>

<details>
<summary>pdm</summary>

    pdm add nonebot-plugin-set-title

安装仓库 master 分支

    pdm add git+https://github.com/FlakoWESH/nonebot-plugin-set-title@master
</details>

<details>
<summary>poetry</summary>

    poetry add nonebot-plugin-set-title

安装仓库 master 分支

    poetry add git+https://github.com/FlakoWESH/nonebot-plugin-set-title@master
</details>

打开 nonebot2 项目根目录下的 `pyproject.toml` 文件, 在 `[tool.nonebot]` 部分追加写入

    plugins = ["nonebot_plugin_set_title"]

</details>

## ⚙️ 配置

在 `.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
```

## ⚠️ 注意事项

1. **机器人必须为群主**：QQ 官方接口 `set_group_special_title` 要求调用者为群主，否则会失败
2. **头衔长度限制**：QQ 官方限制头衔最多约 6 个汉字（12 字节 GBK），超长会被拒绝
3. **批量限流**：批量设置几十人不会触发风控；若需批量上百人，建议调大 `SET_TITLE_BATCH_INTERVAL`
4. **协议端兼容**：基于 OneBot v11 标准 API 开发，适配 go-cqhttp、NapCatQQ、Lagrange.Core 等主流协议端
