7.4 KiB
7.4 KiB
好友 API
这一页讲的是怎么管理好友：获取好友列表、给好友点赞、处理加好友请求，还有获取陌生人信息。
好友列表
get_friend_list - 获取好友列表
async def get_friend_list(self, no_cache: bool = False) -> List[FriendInfo]
获取机器人账号的所有好友列表。默认会缓存 1 小时。
参数：
no_cache: 是否跳过缓存，直接从服务器获取最新列表
返回值：
List[FriendInfo]: 好友信息对象列表
示例：
friends = await bot.get_friend_list()
print(f"我有 {len(friends)} 个好友")
for friend in friends:
print(f"{friend.user_id}: {friend.nickname} (备注: {friend.remark})")
FriendInfo 对象包含以下字段：
user_id: QQ 号nickname: 昵称remark: 备注（你给好友设置的备注名）- 其他可能的信息字段
陌生人信息
get_stranger_info - 获取陌生人信息
async def get_stranger_info(
self,
user_id: int,
no_cache: bool = False
) -> StrangerInfo
获取非好友的 QQ 用户信息。默认会缓存 1 小时。
参数：
user_id: 目标用户的 QQ 号no_cache: 是否跳过缓存
返回值：
StrangerInfo: 陌生人信息对象
示例：
@matcher.command("who")
async def handle_who(event: MessageEvent, args: str):
if not args.isdigit():
await event.reply("参数错误，需要 QQ 号")
return
target_id = int(args)
info = await event.bot.get_stranger_info(target_id)
msg = f"用户 {target_id} 的信息：\n"
msg += f"昵称: {info.nickname}\n"
msg += f"性别: {info.sex}\n"
msg += f"年龄: {info.age}\n"
msg += f"等级: {info.level}"
await event.reply(msg)
StrangerInfo 对象包含以下字段：
user_id: QQ 号nickname: 昵称sex: 性别（male/female/unknown）age: 年龄level: QQ 等级- 其他可能的信息字段
互动功能
send_like - 发送点赞（戳一戳）
async def send_like(
self,
user_id: int,
times: int = 1
) -> Dict[str, Any]
给指定用户发送"戳一戳"（点赞）。每天有次数限制，建议不要超过 10 次。
参数：
user_id: 目标用户的 QQ 号times: 点赞次数，建议 1-10 次
示例：
@matcher.command("like")
async def handle_like(event: MessageEvent, args: str):
# 给发送者点赞
await event.bot.send_like(event.user_id, times=1)
await event.reply("给你点了个赞！")
# 如果提供了参数，给指定用户点赞
if args.isdigit():
target_id = int(args)
await event.bot.send_like(target_id, times=1)
await event.reply(f"给 {target_id} 点了个赞！")
注意：
- 不是所有 OneBot 实现都支持这个 API
- 有每日次数限制，不要滥用
- 对方可能关闭了"戳一戳"功能，这时会失败
加好友请求处理
set_friend_add_request - 处理加好友请求
async def set_friend_add_request(
self,
flag: str,
approve: bool = True,
remark: str = ""
) -> Dict[str, Any]
处理收到的加好友请求。需要在 request 事件中调用。
参数：
flag: 请求标识，从request事件的flag字段获取approve: 是否同意，True同意，False拒绝remark: 同意请求时，为该好友设置的备注（可选）
示例：
from models.events.request import RequestEvent
from core.managers.command_manager import matcher
# 处理所有加好友请求
@matcher.on_event(RequestEvent)
async def handle_friend_request(event: RequestEvent):
if event.request_type == "friend":
# 自动同意并设置备注
await event.bot.set_friend_add_request(
flag=event.flag,
approve=True,
remark=f"自动添加-{event.user_id}"
)
# 给新好友发个欢迎消息
await event.bot.send_private_msg(
event.user_id,
"你好！我是机器人，已自动通过你的好友请求。"
)
实用示例
好友信息查询插件
@matcher.command("friendinfo")
async def handle_friendinfo(event: MessageEvent):
# 获取好友列表
friends = await event.bot.get_friend_list()
# 按备注名排序
sorted_friends = sorted(friends, key=lambda f: f.remark or f.nickname)
# 生成好友列表消息
if len(sorted_friends) > 50:
msg = f"好友太多啦，只显示前50个（共{len(sorted_friends)}个）\n"
sorted_friends = sorted_friends[:50]
else:
msg = f"我的好友列表（共{len(sorted_friends)}个）:\n"
for i, friend in enumerate(sorted_friends, 1):
remark_display = friend.remark if friend.remark else "（无备注）"
msg += f"{i}. {friend.nickname} ({friend.user_id}) - 备注: {remark_display}\n"
await event.reply(msg)
自动通过特定用户的好友请求
@matcher.on_event(RequestEvent)
async def handle_specific_friend_request(event: RequestEvent):
if event.request_type != "friend":
return
# 允许列表
allowed_users = [123456, 789012, 345678]
if event.user_id in allowed_users:
# 自动同意
await event.bot.set_friend_add_request(
flag=event.flag,
approve=True,
remark="重要联系人"
)
# 发送欢迎消息
await event.bot.send_private_msg(
event.user_id,
"你好！已通过你的好友请求。\n"
"发送 /help 查看可用指令。"
)
else:
# 拒绝其他人
await event.bot.set_friend_add_request(
flag=event.flag,
approve=False,
reason="仅限授权用户添加"
)
批量给好友发送消息（谨慎使用！）
@matcher.command("broadcast", permission="admin")
async def handle_broadcast(event: MessageEvent, args: str):
if not args:
await event.reply("需要广播内容")
return
# 获取好友列表
friends = await event.bot.get_friend_list()
success_count = 0
fail_count = 0
await event.reply(f"开始向 {len(friends)} 个好友发送广播...")
for friend in friends:
try:
await event.bot.send_private_msg(friend.user_id, args)
success_count += 1
# 避免发送太快被限制
await asyncio.sleep(0.5)
except Exception as e:
print(f"发送给 {friend.user_id} 失败: {e}")
fail_count += 1
await event.reply(
f"广播完成！\n"
f"成功: {success_count} 个\n"
f"失败: {fail_count} 个"
)
注意：批量发送消息容易被腾讯限制，谨慎使用！
注意事项
- 频率限制: 获取好友列表、查询陌生人信息等操作有频率限制。
- 缓存: 好友列表和陌生人信息默认缓存 1 小时，如果需要实时数据，设
no_cache=True。 - 权限: 有些 API 需要特定的权限或客户端支持。
- 隐私: 处理好友请求时，注意保护用户隐私。