506 lines
12 KiB
Markdown
506 lines
12 KiB
Markdown
# 群组 API
|
||
|
||
管群是个技术活。这一页讲的是怎么管理群聊：踢人、禁言、改名片、设管理员……所有跟群相关的操作都在这里。
|
||
|
||
## 权限说明
|
||
|
||
**重要提醒**：很多群管理 API 需要机器人有相应的权限：
|
||
- **管理员权限**：禁言、踢人、改群名片等
|
||
- **群主权限**：解散群、设置管理员等
|
||
|
||
如果机器人权限不足，API 调用会失败。建议先检查机器人的权限，或者做好错误处理。
|
||
|
||
## 成员管理
|
||
|
||
### `set_group_kick` - 踢出群聊
|
||
|
||
```python
|
||
async def set_group_kick(
|
||
self,
|
||
group_id: int,
|
||
user_id: int,
|
||
reject_add_request: bool = False
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
把指定成员踢出群聊。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `user_id`: 要踢出的成员的 QQ 号
|
||
- `reject_add_request`: 是否同时拒绝该用户此后的加群请求（默认 `False`）
|
||
|
||
**示例：**
|
||
```python
|
||
@matcher.command("kick")
|
||
async def handle_kick(event: MessageEvent, args: str):
|
||
if not args.isdigit():
|
||
await event.reply("参数错误，需要 QQ 号")
|
||
return
|
||
|
||
target_id = int(args)
|
||
await event.bot.set_group_kick(event.group_id, target_id)
|
||
await event.reply(f"已踢出 {target_id}")
|
||
```
|
||
|
||
### `set_group_ban` - 禁言/解除禁言
|
||
|
||
```python
|
||
async def set_group_ban(
|
||
self,
|
||
group_id: int,
|
||
user_id: int,
|
||
duration: int = 1800
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
禁言群成员。设置 `duration=0` 可以解除禁言。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `user_id`: 要禁言的成员的 QQ 号
|
||
- `duration`: 禁言时长，单位秒。默认 1800 秒（30 分钟），0 表示解除禁言
|
||
|
||
**示例：**
|
||
```python
|
||
# 禁言 10 分钟
|
||
await bot.set_group_ban(123456, 789012, duration=600)
|
||
|
||
# 解除禁言
|
||
await bot.set_group_ban(123456, 789012, duration=0)
|
||
```
|
||
|
||
### `set_group_anonymous_ban` - 禁言匿名用户
|
||
|
||
```python
|
||
async def set_group_anonymous_ban(
|
||
self,
|
||
group_id: int,
|
||
anonymous: Optional[Dict[str, Any]] = None,
|
||
duration: int = 1800,
|
||
flag: Optional[str] = None
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
禁言发送匿名消息的用户。需要从消息事件的 `anonymous` 字段获取匿名用户信息。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `anonymous`: 匿名用户对象（从事件中获取）
|
||
- `duration`: 禁言时长，单位秒
|
||
- `flag`: 匿名用户的 flag 标识（从事件中获取）
|
||
|
||
**示例：**
|
||
```python
|
||
@matcher.command("ban_anonymous")
|
||
async def handle_ban_anonymous(event: GroupMessageEvent):
|
||
if not event.anonymous:
|
||
await event.reply("这不是匿名消息")
|
||
return
|
||
|
||
# 方法 1: 使用 anonymous 对象
|
||
await event.bot.set_group_anonymous_ban(
|
||
event.group_id,
|
||
anonymous=event.anonymous,
|
||
duration=3600 # 禁言 1 小时
|
||
)
|
||
|
||
# 方法 2: 使用 flag（如果事件中有的话）
|
||
# await event.bot.set_group_anonymous_ban(
|
||
# event.group_id,
|
||
# flag=event.anonymous.get("flag"),
|
||
# duration=3600
|
||
# )
|
||
```
|
||
|
||
### `set_group_whole_ban` - 全员禁言
|
||
|
||
```python
|
||
async def set_group_whole_ban(
|
||
self,
|
||
group_id: int,
|
||
enable: bool = True
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
开启或关闭全员禁言。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `enable`: `True` 开启全员禁言，`False` 关闭
|
||
|
||
**示例：**
|
||
```python
|
||
# 开启全员禁言
|
||
await bot.set_group_whole_ban(123456, enable=True)
|
||
|
||
# 关闭全员禁言
|
||
await bot.set_group_whole_ban(123456, enable=False)
|
||
```
|
||
|
||
## 权限设置
|
||
|
||
### `set_group_admin` - 设置/取消管理员
|
||
|
||
```python
|
||
async def set_group_admin(
|
||
self,
|
||
group_id: int,
|
||
user_id: int,
|
||
enable: bool = True
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
设置或取消群管理员。**需要机器人是群主**。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `user_id`: 目标成员的 QQ 号
|
||
- `enable`: `True` 设为管理员，`False` 取消管理员
|
||
|
||
**示例：**
|
||
```python
|
||
# 设某人为管理员
|
||
await bot.set_group_admin(123456, 789012, enable=True)
|
||
|
||
# 取消某人的管理员
|
||
await bot.set_group_admin(123456, 789012, enable=False)
|
||
```
|
||
|
||
### `set_group_anonymous` - 匿名聊天设置
|
||
|
||
```python
|
||
async def set_group_anonymous(
|
||
self,
|
||
group_id: int,
|
||
enable: bool = True
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
开启或关闭群匿名聊天功能。**需要机器人是管理员**。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `enable`: `True` 开启匿名，`False` 关闭
|
||
|
||
## 成员信息
|
||
|
||
### `set_group_card` - 设置群名片
|
||
|
||
```python
|
||
async def set_group_card(
|
||
self,
|
||
group_id: int,
|
||
user_id: int,
|
||
card: str = ""
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
设置群成员的群名片（群内显示的名称）。传空字符串可以删除群名片，恢复为昵称。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `user_id`: 目标成员的 QQ 号
|
||
- `card`: 要设置的群名片内容，空字符串表示删除
|
||
|
||
**示例：**
|
||
```python
|
||
# 设置群名片
|
||
await bot.set_group_card(123456, 789012, "技术大佬")
|
||
|
||
# 删除群名片（恢复为昵称）
|
||
await bot.set_group_card(123456, 789012, "")
|
||
```
|
||
|
||
### `set_group_special_title` - 设置专属头衔
|
||
|
||
```python
|
||
async def set_group_special_title(
|
||
self,
|
||
group_id: int,
|
||
user_id: int,
|
||
special_title: str = "",
|
||
duration: int = -1
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
为群成员设置专属头衔（群主/管理员才有权限设置）。**需要机器人是群主**。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `user_id`: 目标成员的 QQ 号
|
||
- `special_title`: 专属头衔内容，空字符串表示删除
|
||
- `duration`: 头衔有效期，单位秒。-1 表示永久
|
||
|
||
**示例：**
|
||
```python
|
||
# 设置永久头衔
|
||
await bot.set_group_special_title(123456, 789012, "御用摄影师", duration=-1)
|
||
|
||
# 设置 7 天有效的头衔
|
||
await bot.set_group_special_title(123456, 789012, "本周活跃之星", duration=7*24*3600)
|
||
|
||
# 删除头衔
|
||
await bot.set_group_special_title(123456, 789012, "")
|
||
```
|
||
|
||
## 群信息管理
|
||
|
||
### `set_group_name` - 修改群名
|
||
|
||
```python
|
||
async def set_group_name(
|
||
self,
|
||
group_id: int,
|
||
group_name: str
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
修改群名称。**需要机器人是群主或管理员**。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `group_name`: 新的群名称
|
||
|
||
**示例：**
|
||
```python
|
||
await bot.set_group_name(123456, "技术交流群")
|
||
```
|
||
|
||
### `set_group_leave` - 退出/解散群聊
|
||
|
||
```python
|
||
async def set_group_leave(
|
||
self,
|
||
group_id: int,
|
||
is_dismiss: bool = False
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
退出群聊，如果是群主还可以解散群。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `is_dismiss`: 是否解散群（仅群主有效）
|
||
|
||
**示例：**
|
||
```python
|
||
# 普通退群
|
||
await bot.set_group_leave(123456)
|
||
|
||
# 解散群（需要是群主）
|
||
await bot.set_group_leave(123456, is_dismiss=True)
|
||
```
|
||
|
||
## 获取信息
|
||
|
||
### `get_group_info` - 获取群信息
|
||
|
||
```python
|
||
async def get_group_info(
|
||
self,
|
||
group_id: int,
|
||
no_cache: bool = False
|
||
) -> GroupInfo
|
||
```
|
||
|
||
获取群的详细信息，包括群名、成员数、创建时间等。默认会缓存 1 小时。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `no_cache`: 是否跳过缓存，直接从服务器获取最新信息
|
||
|
||
**返回值：**
|
||
- `GroupInfo` 对象，包含群信息
|
||
|
||
**示例：**
|
||
```python
|
||
info = await bot.get_group_info(123456)
|
||
print(f"群名: {info.group_name}")
|
||
print(f"成员数: {info.member_count}")
|
||
print(f"创建时间: {info.create_time}")
|
||
```
|
||
|
||
### `get_group_list` - 获取群列表
|
||
|
||
```python
|
||
async def get_group_list(self) -> List[GroupInfo]
|
||
```
|
||
|
||
获取机器人加入的所有群列表。
|
||
|
||
**示例：**
|
||
```python
|
||
groups = await bot.get_group_list()
|
||
for group in groups:
|
||
print(f"{group.group_id}: {group.group_name}")
|
||
```
|
||
|
||
### `get_group_member_info` - 获取群成员信息
|
||
|
||
```python
|
||
async def get_group_member_info(
|
||
self,
|
||
group_id: int,
|
||
user_id: int,
|
||
no_cache: bool = False
|
||
) -> GroupMemberInfo
|
||
```
|
||
|
||
获取指定群成员的详细信息，包括昵称、群名片、加群时间、最后发言时间等。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `user_id`: 成员 QQ 号
|
||
- `no_cache`: 是否跳过缓存
|
||
|
||
**返回值：**
|
||
- `GroupMemberInfo` 对象
|
||
|
||
**示例：**
|
||
```python
|
||
member = await bot.get_group_member_info(123456, 789012)
|
||
print(f"昵称: {member.nickname}")
|
||
print(f"群名片: {member.card}")
|
||
print(f"权限: {member.role}") # owner, admin, member
|
||
```
|
||
|
||
### `get_group_member_list` - 获取群成员列表
|
||
|
||
```python
|
||
async def get_group_member_list(self, group_id: int) -> List[GroupMemberInfo]
|
||
```
|
||
|
||
获取群的所有成员列表。
|
||
|
||
**示例：**
|
||
```python
|
||
members = await bot.get_group_member_list(123456)
|
||
print(f"群里有 {len(members)} 个成员")
|
||
for member in members:
|
||
print(f"{member.user_id}: {member.nickname}")
|
||
```
|
||
|
||
### `get_group_honor_info` - 获取群荣誉信息
|
||
|
||
```python
|
||
async def get_group_honor_info(
|
||
self,
|
||
group_id: int,
|
||
type: str
|
||
) -> GroupHonorInfo
|
||
```
|
||
|
||
获取群的荣誉信息，比如龙王、群聊之火、快乐源泉等。
|
||
|
||
**参数：**
|
||
- `group_id`: 群号
|
||
- `type`: 荣誉类型，可选值:
|
||
- `"talkative`:" 龙王（发言最多）
|
||
- `"performer"`: 群聊之火（发言最活跃）
|
||
- `"legend"`: 群传奇（连续多天发言最多）
|
||
- `"strong_newbie"`: 冒尖小萌新（新人中发言最多）
|
||
- `"emotion"`: 快乐源泉（发送表情包最多）
|
||
|
||
**示例：**
|
||
```python
|
||
honor = await bot.get_group_honor_info(123456, "talkative")
|
||
print(f"本周龙王: {honor.current_talkative.user_id}")
|
||
```
|
||
|
||
## 加群请求处理
|
||
|
||
### `set_group_add_request` - 处理加群请求/邀请
|
||
|
||
```python
|
||
async def set_group_add_request(
|
||
self,
|
||
flag: str,
|
||
sub_type: str,
|
||
approve: bool = True,
|
||
reason: str = ""
|
||
) -> Dict[str, Any]
|
||
```
|
||
|
||
处理加群请求或邀请。需要在 `request` 事件中调用。
|
||
|
||
**参数：**
|
||
- `flag`: 请求标识，从 `request` 事件的 `flag` 字段获取
|
||
- `sub_type`: 请求类型，`"add"`（加群请求）或 `"invite"`（群邀请）
|
||
- `approve`: 是否同意，`True` 同意，`False` 拒绝
|
||
- `reason`: 拒绝理由（仅在 `approve=False` 时有效）
|
||
|
||
**示例：**
|
||
```python
|
||
from models.events.request import RequestEvent
|
||
|
||
# 在请求事件处理函数中
|
||
async def handle_group_request(event: RequestEvent):
|
||
if event.request_type == "group":
|
||
# 自动同意所有加群请求
|
||
await event.bot.set_group_add_request(
|
||
flag=event.flag,
|
||
sub_type=event.sub_type,
|
||
approve=True
|
||
)
|
||
```
|
||
|
||
## 实用示例
|
||
|
||
### 自动同意加群请求
|
||
|
||
```python
|
||
from models.events.request import RequestEvent
|
||
from core.managers.command_manager import matcher
|
||
|
||
@matcher.on_event(RequestEvent)
|
||
async def handle_all_requests(event: RequestEvent):
|
||
if event.request_type == "group":
|
||
# 检查是否来自特定用户
|
||
if event.user_id in [123456, 789012]:
|
||
await event.bot.set_group_add_request(
|
||
flag=event.flag,
|
||
sub_type=event.sub_type,
|
||
approve=True
|
||
)
|
||
await event.bot.send_private_msg(
|
||
event.user_id,
|
||
f"已同意你的加群请求，欢迎加入！"
|
||
)
|
||
```
|
||
|
||
### 群活跃度统计
|
||
|
||
```python
|
||
@matcher.command("active")
|
||
async def handle_active(event: MessageEvent):
|
||
# 获取群成员列表
|
||
members = await event.bot.get_group_member_list(event.group_id)
|
||
|
||
# 找出最后发言时间最近的一批成员
|
||
active_members = sorted(
|
||
members,
|
||
key=lambda m: m.last_sent_time or 0,
|
||
reverse=True
|
||
)[:10]
|
||
|
||
# 生成统计消息
|
||
msg = "本群最近活跃成员TOP10:\n"
|
||
for i, member in enumerate(active_members, 1):
|
||
msg += f"{i}. {member.nickname} (最后发言: {member.last_sent_time})\n"
|
||
|
||
await event.reply(msg)
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **权限检查**: 调用管理 API 前，最好先检查机器人的权限。
|
||
2. **频率限制**: 不要频繁调用 API，尤其是获取群成员列表这种大数据量的操作。
|
||
3. **缓存**: 获取信息的 API 默认有缓存，如果需要实时数据，记得设 `no_cache=True`。
|
||
4. **错误处理**: 管理操作可能失败（权限不足、参数错误等），要做好错误处理。
|
||
|
||
## 下一步
|
||
|
||
- [好友 API](./friend.md): 处理好友相关操作
|
||
- [账号 API](./account.md): 管理机器人自身状态
|
||
- [消息 API](./message.md): 怎么发消息、撤回消息 |