K2cr2O1
d458413e4b
- 新增 `/status` 指令，展示机器人运行状态和系统指标 - 实现Redis Lua脚本支持原子化计数器操作 - 添加消息收发统计功能 - 完善文档，包括插件开发和性能优化指南 - 重构WebSocket连接池，增加健康检查机制 - 移除旧版编译脚本，优化项目结构
16 KiB
16 KiB
群组 API
管群是个技术活。这一页讲的是怎么管理群聊：踢人、禁言、改名片、设管理员……所有跟群相关的操作都在这里。
权限说明
重要提醒：很多群管理 API 需要机器人有相应的权限：
- 管理员权限：禁言、踢人、改群名片等
- 群主权限：解散群、设置管理员等
如果机器人权限不足，API 调用会失败。建议先检查机器人的权限，或者做好错误处理。
成员管理
set_group_kick - 踢出群聊
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）
示例：
@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 - 禁言/解除禁言
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 表示解除禁言
示例：
# 禁言 10 分钟
await bot.set_group_ban(123456, 789012, duration=600)
# 解除禁言
await bot.set_group_ban(123456, 789012, duration=0)
set_group_anonymous_ban - 禁言匿名用户
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 标识（从事件中获取）
示例：
@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 - 全员禁言
async def set_group_whole_ban(
self,
group_id: int,
enable: bool = True
) -> Dict[str, Any]
开启或关闭全员禁言。
参数：
group_id: 群号enable:True开启全员禁言，False关闭
示例：
# 开启全员禁言
await bot.set_group_whole_ban(123456, enable=True)
# 关闭全员禁言
await bot.set_group_whole_ban(123456, enable=False)
权限设置
set_group_admin - 设置/取消管理员
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取消管理员
示例：
# 设某人为管理员
await bot.set_group_admin(123456, 789012, enable=True)
# 取消某人的管理员
await bot.set_group_admin(123456, 789012, enable=False)
set_group_anonymous - 匿名聊天设置
async def set_group_anonymous(
self,
group_id: int,
enable: bool = True
) -> Dict[str, Any]
开启或关闭群匿名聊天功能。需要机器人是管理员。
参数：
group_id: 群号enable:True开启匿名，False关闭
成员信息
set_group_card - 设置群名片
async def set_group_card(
self,
group_id: int,
user_id: int,
card: str = ""
) -> Dict[str, Any]
设置群成员的群名片（群内显示的名称）。传空字符串可以删除群名片，恢复为昵称。
参数：
group_id: 群号user_id: 目标成员的 QQ 号card: 要设置的群名片内容，空字符串表示删除
示例：
# 设置群名片
await bot.set_group_card(123456, 789012, "技术大佬")
# 删除群名片（恢复为昵称）
await bot.set_group_card(123456, 789012, "")
set_group_special_title - 设置专属头衔
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 表示永久
示例：
# 设置永久头衔
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 - 修改群名
async def set_group_name(
self,
group_id: int,
group_name: str
) -> Dict[str, Any]
修改群名称。需要机器人是群主或管理员。
参数：
group_id: 群号group_name: 新的群名称
示例：
await bot.set_group_name(123456, "技术交流群")
set_group_leave - 退出/解散群聊
async def set_group_leave(
self,
group_id: int,
is_dismiss: bool = False
) -> Dict[str, Any]
退出群聊，如果是群主还可以解散群。
参数：
group_id: 群号is_dismiss: 是否解散群（仅群主有效）
示例：
# 普通退群
await bot.set_group_leave(123456)
# 解散群（需要是群主）
await bot.set_group_leave(123456, is_dismiss=True)
获取信息
get_group_info - 获取群信息
async def get_group_info(
self,
group_id: int,
no_cache: bool = False
) -> GroupInfo
获取群的详细信息，包括群名、成员数、创建时间等。默认会缓存 1 小时。
参数：
group_id: 群号no_cache: 是否跳过缓存，直接从服务器获取最新信息
返回值：
GroupInfo对象，包含群信息
示例：
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 - 获取群列表
async def get_group_list(self) -> List[GroupInfo]
获取机器人加入的所有群列表。
示例：
groups = await bot.get_group_list()
for group in groups:
print(f"{group.group_id}: {group.group_name}")
get_group_member_info - 获取群成员信息
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对象
示例：
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 - 获取群成员列表
async def get_group_member_list(self, group_id: int) -> List[GroupMemberInfo]
获取群的所有成员列表。
示例：
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 - 获取群荣誉信息
async def get_group_honor_info(
self,
group_id: int,
type: str
) -> GroupHonorInfo
获取群的荣誉信息，比如龙王、群聊之火、快乐源泉等。
参数：
group_id: 群号type: 荣誉类型，可选值:"talkative:" 龙王（发言最多）"performer": 群聊之火（发言最活跃）"legend": 群传奇（连续多天发言最多）"strong_newbie": 冒尖小萌新（新人中发言最多）"emotion": 快乐源泉（发送表情包最多）
示例：
honor = await bot.get_group_honor_info(123456, "talkative")
print(f"本周龙王: {honor.current_talkative.user_id}")
get_group_info_ex - 获取群扩展信息 (NapCat)
async def get_group_info_ex(self, group_id: int) -> Dict[str, Any]
获取群的扩展信息（NapCatQQ 特有 API）。
参数：
group_id: 群号
返回值：
- 包含群扩展信息的字典
精华消息
delete_essence_msg - 删除精华消息
async def delete_essence_msg(self, message_id: int) -> Dict[str, Any]
删除一条精华消息。
参数：
message_id: 目标消息的 ID
互动与状态
group_poke - 群内戳一戳
async def group_poke(self, group_id: int, user_id: int) -> Dict[str, Any]
在群内对指定成员发送"戳一戳"。
参数：
group_id: 群号user_id: 目标成员的 QQ 号
mark_group_msg_as_read - 标记群消息已读
async def mark_group_msg_as_read(self, group_id: int, time: int = 0) -> Dict[str, Any]
将指定群聊的消息标记为已读。
参数：
group_id: 群号time: 将此时间戳（秒）之前的消息标记为已读，传0表示全部标记
消息转发
forward_group_single_msg - 转发单条群消息
async def forward_group_single_msg(self, group_id: int, message_id: str) -> Dict[str, Any]
将一条群消息转发到当前群聊。
参数：
group_id: 群号message_id: 要转发的消息的 ID
群设置 (高级)
set_group_portrait - 设置群头像
async def set_group_portrait(self, group_id: int, file: str, cache: int = 1) -> Dict[str, Any]
设置群头像。
参数：
group_id: 群号file: 图片文件的路径、URL 或 Base64 字符串cache: 是否使用缓存（1是，0否）
set_group_remark - 设置群备注
async def set_group_remark(self, group_id: int, remark: str) -> Dict[str, Any]
设置群备注（NapCatQQ 特有 API）。
参数：
group_id: 群号remark: 要设置的备注
set_group_sign - 群签到
async def set_group_sign(self, group_id: int) -> Dict[str, Any]
在指定群聊中进行签到。
参数：
group_id: 群号
群公告
_send_group_notice - 发送群公告
async def _send_group_notice(self, group_id: int, content: str, **kwargs) -> Dict[str, Any]
发送群公告。
参数：
group_id: 群号content: 公告内容**kwargs: 其他可选参数，如image
_get_group_notice - 获取群公告
async def _get_group_notice(self, group_id: int) -> Dict[str, Any]
获取群公告列表。
参数：
group_id: 群号
_del_group_notice - 删除群公告
async def _del_group_notice(self, group_id: int, notice_id: str) -> Dict[str, Any]
删除指定的群公告。
参数：
group_id: 群号notice_id: 要删除的公告的 ID
其他信息获取
get_group_at_all_remain - 获取@全体剩余次数
async def get_group_at_all_remain(self, group_id: int) -> Dict[str, Any]
获取当天在指定群聊中 @全体成员 的剩余次数。
参数：
group_id: 群号
get_group_system_msg - 获取群系统消息
async def get_group_system_msg(self) -> Dict[str, Any]
获取群系统消息（如加群请求、退群通知等）。
get_group_shut_list - 获取群禁言列表
async def get_group_shut_list(self, group_id: int) -> Dict[str, Any]
获取被禁言的群成员列表。
参数：
group_id: 群号
加群请求处理
set_group_add_request - 处理加群请求/邀请
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时有效）
示例：
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
)
实用示例
自动同意加群请求
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"已同意你的加群请求，欢迎加入！"
)
群活跃度统计
@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)
注意事项
- 权限检查: 调用管理 API 前，最好先检查机器人的权限。
- 频率限制: 不要频繁调用 API，尤其是获取群成员列表这种大数据量的操作。
- 缓存: 获取信息的 API 默认有缓存，如果需要实时数据，记得设
no_cache=True。 - 错误处理: 管理操作可能失败（权限不足、参数错误等），要做好错误处理。