Event API
src.app.plugin_system.api.event_api 提供事件的发布、处理器注册和临时监听器管理。
所有涉及 I/O 的操作均为异步函数，调用时需 await；unregister_handler 和 get_event_stats 为同步函数。
导入
from src.app.plugin_system.api.event_api import (
publish_event,
register_handler,
unregister_handler,
build_subscription_map,
create_temporary_handler,
unregister_temporary_handler,
get_event_stats,
set_event_handler_timeout,
)函数
事件发布
publish_event(event: EventType | str, kwargs: dict[str, Any] | None = None) -> dict[str, Any]
发布事件给订阅者。支持系统事件（EventType 枚举）和自定义事件（字符串）。返回发布结果，包含最终决策和参数。
from src.core.components import EventType
# 系统事件
result = await publish_event(EventType.ON_MESSAGE_RECEIVED, {"message": msg})
# 自定义事件
result = await publish_event("my_plugin:user_action", {"action": "click"})处理器注册
| 函数 | 说明 |
|---|---|
register_handler(signature: str, handler: BaseEventHandler) -> None | 注册事件处理器（异步） |
unregister_handler(signature: str) -> None | 注销事件处理器（同步） |
build_subscription_map() -> None | 构建事件订阅映射表，遍历所有已注册的事件处理器并注册到 EventBus，处理器按权重降序排序，并透传 BaseEventHandler.timeout 作为订阅者级超时（异步） |
临时监听器
create_temporary_handler(event_names: list[EventType | str], handle_func: Callable[[str, dict[str, Any]], tuple[EventDecision, dict[str, Any]] | Any], priority: int = 0) -> str
创建运行时临时事件监听器。临时监听器执行后，只要回调返回的 decision 不是 PASS，就会自动从所有订阅事件上清除。返回临时监听器 ID，可用于手动注销。此函数为异步函数。
event_names: 需要订阅的事件名称列表handle_func: 监听器回调，签名(event_name: str, kwargs: dict[str, Any]) -> tuple[EventDecision, dict[str, Any]] | Any，与 EventBus 订阅者协议一致priority: 监听器优先级
unregister_temporary_handler(temporary_id: str) -> bool
手动注销运行时临时事件监听器。此函数为异步函数。
统计
get_event_stats() -> dict[str, int]
获取事件统计信息。返回字典包含：
handler_count: 处理器总数event_type_count: 事件类型总数total_subscriptions: 总订阅数
超时配置
set_event_handler_timeout(timeout_seconds: float) -> None
设置 EventBus 的全局默认事件处理器超时时间。同步函数。
timeout_seconds > 0：使用此秒数作为全局默认超时timeout_seconds <= 0：禁用全局超时检查
from src.app.plugin_system.api.event_api import set_event_handler_timeout
set_event_handler_timeout(60) # 全局默认调到 60 秒
set_event_handler_timeout(0) # 全局禁用超时检查全局 vs 订阅者级
本函数影响所有未显式声明 timeout 的处理器，属于进程级全局开关。推荐在启动时（如 ON_START 事件中）一次性调用。
长耗时处理器（agent 工具调用、多轮 LLM 编排等）应通过 BaseEventHandler.timeout 类属性声明订阅者级超时，而非调全局值——避免影响其他 handler。详见 EventHandler 组件。
相关文档
贡献者
minecraft1024a micraft1024a
Windpicker-owo