From e5dd805d19140848fba1ba1a7d76b03bf4e8b5d6 Mon Sep 17 00:00:00 2001
From: snowy-yang <102860110+snowy-yang@users.noreply.github.com>
Date: Thu, 1 Oct 2026 23:04:49 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20=E7=A4=BA=E4=BE=8B=E4=B8=8E=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E8=B7=9F=E4=B8=8A=20handler=20=E6=B3=A8=E5=85=A5?=
 =?UTF-8?q?=E8=A7=84=E5=88=99=E2=80=94=E2=80=94FRIEND=5FADD=20=E6=94=B9?=
 =?UTF-8?q?=E6=A0=87=E6=B3=A8=20FriendAdd?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

0f3ed09 后 dict 标注不可注入，示例 handler 每次触发都被异常隔离吞掉；
官方 FRIEND_ADD 字段名为 openid，原 d.get('user_openid') 写法在重构
前也取不到值。payloads 模块 docstring 同步改为现行语义（未知事件只能
经 Event.typed 拿 dict）。
---
 examples/group_bot/main.py | 12 +++++++++---
 src/qqbotsdk/payloads.py   |  6 +++---
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/examples/group_bot/main.py b/examples/group_bot/main.py
index d98e7fd..30be4bf 100644
--- a/examples/group_bot/main.py
+++ b/examples/group_bot/main.py
@@ -13,7 +13,13 @@ from loguru import logger
 from qqbotsdk import EventEmitter, main
 from qqbotsdk.api import BotApi, button, keyboard
 from qqbotsdk.events import Event
-from qqbotsdk.payloads import C2CMessage, GroupAddRobot, GroupAtMessage, Interaction
+from qqbotsdk.payloads import (
+    C2CMessage,
+    FriendAdd,
+    GroupAddRobot,
+    GroupAtMessage,
+    Interaction,
+)
 
 ee = EventEmitter()
 
@@ -98,8 +104,8 @@ async def on_c2c_message(msg: C2CMessage, api: BotApi) -> None:
 
 
 @ee.on("FRIEND_ADD")
-async def on_friend_add(d: dict) -> None:
-    logger.info(f"新增用户：{d.get('user_openid')}")
+async def on_friend_add(added: FriendAdd) -> None:
+    logger.info(f"新增用户：{added.openid}")
 
 
 if __name__ == "__main__":
diff --git a/src/qqbotsdk/payloads.py b/src/qqbotsdk/payloads.py
index aa78e3d..452ad63 100644
--- a/src/qqbotsdk/payloads.py
+++ b/src/qqbotsdk/payloads.py
@@ -1,9 +1,9 @@
 """事件 payload 的 dataclass 定义与解析。
 
 handler 直接标注具体类型即可拿到解析后的对象（如
-`async def on_msg(msg: GroupAtMessage)`）；未收录的事件类型
-由 emitter 回退传原始 dict，新增事件只需在这里加 dataclass
-并登记到 EVENT_TYPES。
+`async def on_msg(msg: GroupAtMessage)`）；未收录的事件类型没有可标注的
+dataclass，只能经 `Event.typed` 拿到原始 dict——新增事件只需在这里加
+dataclass 并登记到 EVENT_TYPES。
 """
 
 from dataclasses import dataclass, fields