feat: 新增自动同意请求插件和API文档

docs: 更新文档结构和内容
2026-01-14 23:53:56 +08:00
parent 520462b4c6
commit 03bcded7ed
10 changed files with 1998 additions and 1 deletions
--- a/docs/api/friend.md
+++ b/docs/api/friend.md
@@ -0,0 +1,273 @@
+# 好友 API
+
+这一页讲的是怎么管理好友：获取好友列表、给好友点赞、处理加好友请求，还有获取陌生人信息。
+
+## 好友列表
+
+### `get_friend_list` - 获取好友列表
+
+```python
+async def get_friend_list(self, no_cache: bool = False) -> List[FriendInfo]
+```
+
+获取机器人账号的所有好友列表。默认会缓存 1 小时。
+
+**参数：**
+- `no_cache`: 是否跳过缓存，直接从服务器获取最新列表
+
+**返回值：**
+- `List[FriendInfo]`: 好友信息对象列表
+
+**示例：**
+```python
+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` - 获取陌生人信息
+
+```python
+async def get_stranger_info(
+    self,
+    user_id: int,
+    no_cache: bool = False
+) -> StrangerInfo
+```
+
+获取非好友的 QQ 用户信息。默认会缓存 1 小时。
+
+**参数：**
+- `user_id`: 目标用户的 QQ 号
+- `no_cache`: 是否跳过缓存
+
+**返回值：**
+- `StrangerInfo`: 陌生人信息对象
+
+**示例：**
+```python
+@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` - 发送点赞（戳一戳）
+
+```python
+async def send_like(
+    self,
+    user_id: int,
+    times: int = 1
+) -> Dict[str, Any]
+```
+
+给指定用户发送"戳一戳"（点赞）。每天有次数限制，建议不要超过 10 次。
+
+**参数：**
+- `user_id`: 目标用户的 QQ 号
+- `times`: 点赞次数，建议 1-10 次
+
+**示例：**
+```python
+@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` - 处理加好友请求
+
+```python
+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`: 同意请求时，为该好友设置的备注（可选）
+
+**示例：**
+```python
+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,
+            "你好！我是机器人，已自动通过你的好友请求。"
+        )
+```
+
+## 实用示例
+
+### 好友信息查询插件
+
+```python
+@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)
+```
+
+### 自动通过特定用户的好友请求
+
+```python
+@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="仅限授权用户添加"
+        )
+```
+
+### 批量给好友发送消息（谨慎使用！）
+
+```python
+@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. **频率限制**: 获取好友列表、查询陌生人信息等操作有频率限制。
+2. **缓存**: 好友列表和陌生人信息默认缓存 1 小时，如果需要实时数据，设 `no_cache=True`。
+3. **权限**: 有些 API 需要特定的权限或客户端支持。
+4. **隐私**: 处理好友请求时，注意保护用户隐私。
+
+## 下一步
+
+- [账号 API](./account.md): 管理机器人自己的信息
+- [群组 API](./group.md): 管理群聊相关功能
+- [消息 API](./message.md): 怎么发消息、撤回消息