事件系统

LumenBridge 内置事件总线，子插件通过 lumen.on / once / off / emit 操作。

OneBot 事件

由 OneBot 协议端（NapCat / go-cqhttp / Lagrange）上报的事件，按 post_type 分层派发：

事件名	触发时机	回调参数
message.group.normal	群普通消息	(pack, reply)
message.private.friend	私聊消息	(pack, reply)
notice.group_increase	群成员加入	(pack)
notice.group_decrease	群成员离开	(pack)
notice.notify	通知类事件	(pack)
request.group	加群请求	(pack)
request.friend	好友请求	(pack)
meta_event.heartbeat	心跳	(pack)
meta_event.lifecycle	生命周期	(pack)
bot.online	机器人上线	()
onebot.pack	原始数据包（最底层）	(pack)

pack 是 OneBot v11 标准事件对象 dict，常用字段：

{
    "post_type": "message",
    "message_type": "group",
    "sub_type": "normal",
    "group_id": 123456789,
    "user_id": 987654321,
    "message_id": 12345,
    "raw_message": "你好",
    "message": [{"type": "text", "data": {"text": "你好"}}],
    "sender": {"user_id": 987654321, "nickname": "张三", "card": "群名片"}
}

reply 是快捷回复函数：reply(msg, quote=False)，quote=True 时以引用方式回复。

游戏事件

事件名	触发时机	回调参数
mc.player_join	玩家进服	(player_name: str)
mc.player_left	玩家退服	(player_name: str)
mc.player_chat	玩家聊天	(player_name: str, message: str)
mc.player_death	玩家死亡	(player_name: str, death_message: str)

自定义事件

子插件可用 lumen.emit 触发自定义事件，实现子插件间通信：

# 插件 A 发送
lumen.emit("my_plugin.gift", user_id=123, amount=100)

# 插件 B 监听
def on_gift(user_id, amount):
    ...
lumen.on("my_plugin.gift", on_gift)

环境变量更新事件

当 lumen.env.set(key, value) 被调用时，自动触发：

• env.update.<key> — 参数 value
• env.update — 参数 key, value

---