飞书 (Lark) 平台事件实体完整参考 — 消息事件、通知事件、工厂映射。

---

Quick Reference

事件架构

ncatbot.event.lark
├── LarkMessageEvent          # 消息事件基类
│   ├── LarkGroupMessageEvent     # 群消息
│   └── LarkPrivateMessageEvent   # 私聊消息
├── LarkMessageReadEvent      # 消息已读通知
└── LarkMessageRecalledEvent  # 消息撤回通知

事件速查表

from ncatbot.event.lark import (
    LarkGroupMessageEvent,
    LarkPrivateMessageEvent,
    LarkMessageReadEvent,
    LarkMessageRecalledEvent,
)

事件类	Trait 组合	关键属性
LarkGroupMessageEvent	Replyable, HasSender	chat_id, group_id, content, message_id, sender
LarkPrivateMessageEvent	Replyable, HasSender	chat_id, content, message_id, sender, user_id
LarkMessageReadEvent	—	message_id_list, reader_open_id, read_time
LarkMessageRecalledEvent	—	message_id, chat_id, recall_time, recall_type

注册装饰器

装饰器	事件类型
@registrar.lark.on_message()	所有飞书消息
@registrar.lark.on_group_message()	群消息
@registrar.lark.on_private_message()	私聊消息
@registrar.lark.on_command("关键词")	命令匹配
@registrar.lark.on_message_read()	消息已读通知
@registrar.lark.on_message_recalled()	消息撤回通知

---

消息事件

LarkMessageEvent（基类）

所有飞书消息事件的公共基类，实现 Replyable + HasSender Trait。

属性	类型	说明
api	LarkBotAPI	飞书 API 客户端
user_id	str	发送者 open_id
sender	LarkSender	发送者详情（open_id, union_id, tenant_key）
message_id	str	消息 ID
content	str	消息文本内容
chat_id	str	会话 ID

方法	签名	说明
reply	async (content: str | MessageArray, title="") → Any	引用回复原消息
post_message	async (content: str | MessageArray, title="") → Any	主动发送到当前会话

reply() 行为：

• 传入 str → 调用 reply_text()
• 传入 MessageArray → 调用 reply_msg_array()（纯文本自动降级为 text 类型）

post_message() 行为：

• 传入 str → 调用 send_text()
• 传入 MessageArray → 调用 send_msg_array()

LarkGroupMessageEvent

群消息事件。继承 LarkMessageEvent。

额外属性	类型	说明
group_id	str	群 chat_id（与 chat_id 相同）

@registrar.lark.on_group_message()
async def handle(self, event: LarkGroupMessageEvent):
    print(f"群 {event.group_id} 收到来自 {event.user_id} 的消息: {event.content}")
    await event.reply("已收到！")

LarkPrivateMessageEvent

私聊消息事件。继承 LarkMessageEvent。

post_message() 在私聊中使用 open_id 而非 chat_id 发送，确保消息正确送达用户。

@registrar.lark.on_private_message()
async def handle(self, event: LarkPrivateMessageEvent):
    await event.reply(f"你说了: {event.content}")
    # 或主动发送（非引用回复）
    await event.post_message("这是一条新消息")

---

通知事件

LarkMessageReadEvent

消息已读通知。收到此事件表示有用户已阅读了 Bot 发送的消息。

属性	类型	说明
api	LarkBotAPI	飞书 API 客户端
message_id_list	List[str]	被阅读的消息 ID 列表
reader_open_id	str	阅读者 open_id
reader_union_id	str	阅读者 union_id
read_time	str	阅读时间戳
tenant_key	str	租户 key

@registrar.lark.on_message_read()
async def handle(self, event: LarkMessageReadEvent):
    print(f"用户 {event.reader_open_id} 已读消息: {event.message_id_list}")

LarkMessageRecalledEvent

消息撤回通知。收到此事件表示某条消息被撤回。

属性	类型	说明
api	LarkBotAPI	飞书 API 客户端
message_id	str	被撤回的消息 ID
chat_id	str	所在会话 ID
recall_time	str	撤回时间戳
recall_type	str	撤回类型

@registrar.lark.on_message_recalled()
async def handle(self, event: LarkMessageRecalledEvent):
    print(f"消息 {event.message_id} 在 {event.chat_id} 中被撤回")

---

继承关系

BaseEvent
├── LarkMessageEvent (Replyable, HasSender)
│   ├── LarkGroupMessageEvent
│   └── LarkPrivateMessageEvent
├── LarkMessageReadEvent
└── LarkMessageRecalledEvent

---

工厂映射表

数据模型	事件实体	post_type	message_type / notice_type
LarkGroupMessageEventData	LarkGroupMessageEvent	message	group
LarkPrivateMessageEventData	LarkPrivateMessageEvent	message	private
LarkMessageReadEventData	LarkMessageReadEvent	notice	message_read
LarkMessageRecalledEventData	LarkMessageRecalledEvent	notice	message_recalled

工厂函数 create_lark_entity(data, api) 根据数据模型类型精确匹配实体类。

---

交叉引用

如果你在找…	去这里
飞书 Bot API	Lark API
飞书数据类型	Lark 类型
飞书适配器指南	Lark 适配器
通用事件基类	通用事件

版权所有

版权归属：GEYUANwuqi

许可证：署名 4.0 国际 (CC-BY-4.0)