15.5. 内置事件参考：所有系统事件、参数与可改字段

导读 这一节是 第 15 章 事件系统 的配套参考表。第 15 章讲的是“事件系统怎么用、心智模型是什么”，这一节回答另一个更具体的问题：框架到底内置了哪些事件？每个事件发布时 params 里有哪些字段？哪些字段我改了真的会生效？ 全节按生命周期 / 消息链路 / Chatter 步进 / 提示词 / LLM / Tool·Action·Command 六组列出，每条都标注“发布者会回写”的字段，方便你判断改动是否真的影响主流程。

15.5.1 先把“可修改”这件事讲准

第 15 章已经强调过：事件系统是链式传递共享参数，你可以改 params 里的字段。但“能改”和“改了有用”不是一回事。

按发布者是否会把你的改动读回去，字段分三类：

标记	含义
回写	事件链跑完后，发布者会把这个字段读回去并应用到主流程。改它会对系统行为产生真实影响。
链内	发布者不读回，但字段会沿链传给后续处理器。改它只影响下游订阅者看到的内容。
—	纯通知字段，一般只读。改了既不回写也不影响下游（除非下游恰好读它）。

另外两点通用规则：

• 拦截：几乎所有事件都可以用 EventDecision.STOP 终止后续处理器。但只有当后续处理器里包含“真正干活的订阅者”时，STOP 才有拦截意义（例如 ON_MESSAGE_RECEIVED 后面跟着消息分发器）。下文在每个事件上会单独点出 STOP 是否有实际拦截效果。
• 结构稳定：无论哪种字段，都不要增删 params 的 key 集合，只能改值。这是第 15.4 节就定下的硬约束。

术语对齐：本节“发布者”指框架内部调用 event_bus.publish(...) 的那一段代码；“订阅者 / 处理器”指你的 BaseEventHandler。

15.5.2 系统生命周期事件

这一组事件参数很少，基本是“到点了，通知一声”，几乎没有可改字段。

ON_START — "on_start"

• 何时触发：Bot 完成全部初始化、即将进入主运行循环时（bot.py 的 run()）。
• 典型用途：插件做一次性启动初始化、连接外部资源、启动后台任务。

字段	类型	说明
（无）	—	发布时 params 为空字典 {}

• 可修改字段：无。这是一个纯通知事件，params 是空的，你只能“听到”，没有可改的东西。
• 拦截：STOP 没有实际意义（后面没有关键订阅者依赖它）。

ON_STOP — "on_stop"

• 何时触发：Bot 开始关闭、但在插件卸载之前。
• 典型用途：插件在卸载前做收尾清理（关连接、刷盘、停任务）。

字段	类型	说明
（无）	—	params 为空字典 {}

• 可修改字段：无。
• 拦截：无意义。

ON_ALL_PLUGIN_LOADED — "on_all_plugin_loaded"

• 何时触发：所有插件加载并注册完成后触发一次。
• 典型用途：依赖其他插件组件的初始化（例如 skill_manager 在此刻收集已注册技能）。

字段	类型	说明
（无）	—	params 为空字典 {}

• 可修改字段：无。
• 注意：消息分发器（StreamLoopManager）以低优先级订阅了这个事件来启动自身，所以不要 STOP，否则会话循环可能起不来。

15.5.3 组件与插件生命周期事件

这一组在加载 / 卸载时触发，字段主要是身份信息。

ON_COMPONENT_LOADED — "on_component_loaded"

• 何时触发：任意组件被注册到 Registry 之后。
• 典型用途：发现别的插件挂上来的组件、做反向索引、延迟绑定依赖。

字段	类型	说明
signature	str	组件签名，plugin:component_type:component_name
plugin_name	str	所属插件名
component_type	str	组件类型字符串（tool/action/event_handler …）
component_name	str	组件名
component_class	type	组件类对象本身

• 可修改字段：均为链内字段，发布者不回写。改了只影响后续处理器看到的内容。
• 拦截：一般不拦截。

ON_COMPONENT_UNLOADED — "on_component_unloaded"

• 何时触发：单个组件被注销时。

字段	类型	说明
signature	str	被卸载组件的签名
plugin_name	str	所属插件名

• 可修改字段：无回写。链内。
• 拦截：一般不拦截。

ON_PLUGIN_UNLOADED — "on_plugin_unloaded"

• 何时触发：整个插件被卸载、其 on_plugin_unloaded() 钩子执行完之后。

字段	类型	说明
plugin_name	str	被卸载的插件名
manifest	PluginManifest | None	插件清单对象（可能为 None）

• 可修改字段：无回写。链内。
• 拦截：一般不拦截。

15.5.4 消息链路事件

这一组是事件系统最常用的入口，也是真正能“拦截 / 改写消息”的地方。

ON_MESSAGE_RECEIVED — "on_message_received"

• 何时触发：适配器把一条标准消息送进核心后，MessageReceiver 发布。
• 典型用途：消息审计、内容过滤、改写 message 内容、拦截消息。

字段	类型	说明
message	Message	标准消息对象
envelope	MessageEnvelope	原始消息信封
adapter_signature	str	来源适配器签名

• 可修改字段：
  • message：链内（强生效）。发布者本身不回写，但系统消息分发器 _on_message_received 以默认优先级订阅了这个事件，会从 params["message"] 取消息去建流、入未读队列。所以高优先级处理器改 message，分发器看到的就是改后的。
  • envelope / adapter_signature：链内，仅影响下游订阅者。
• 拦截：STOP 有实际拦截效果——会阻止消息分发器运行，等于把这条消息“吃掉”不进对话流。这是事件系统做消息拦截的正门。

ON_RECEIVED_OTHER_MESSAGE — "on_received_other_message"

• 何时触发：收到非标准消息（适配器无法直接转成 Message 的内容）时发布，给插件一个把它“翻译成标准消息”的机会。
• 典型用途：把特殊平台消息（如某种自定义事件）转成可读文本，纳入对话流。

字段	类型	说明
raw	dict	原始信封内容
processed	str	处理后的可读文本，初始为空串 ""

• 可修改字段：
  • processed：回写。发布者会读回这个字段；若非空，就用它构造一条简化 Message 并再发一次 ON_MESSAGE_RECEIVED。这是本事件的核心写入点。
• 拦截：STOP 等价于让 processed 保持空，消息被丢弃。

ON_MESSAGE_SENT — "on_message_sent"

• 何时触发：核心决定发送一条消息、在真正交给适配器之前。
• 典型用途：发送前最后改写、发送风控、拦截发送。

字段	类型	说明
message	Message	即将发送的消息
envelope	MessageEnvelope	发送信封
adapter_signature	str	目标适配器签名
continue_send	bool	是否继续发送，初始 True

• 可修改字段：
  • continue_send：回写。发布者读回它，若为 False 则取消本次发送。这是“软拦截”发送的标准做法。
• 拦截：STOP 同样会取消发送（直接不走后续发送逻辑）。

AFTER_MESSAGE_SENT — "after_message_sent"

• 何时触发：平台发送成功、历史持久化完成之后。
• 典型用途：发送后统计、落库、通知。

字段	类型	说明
message	Message	已发送的消息
envelope	MessageEnvelope	发送信封
adapter_signature	str	目标适配器签名

• 可修改字段：无回写。链内，纯通知。
• 拦截：无意义（消息已经发出去了）。

15.5.5 Chatter 步进事件

这一组围绕 Chatter 生成器的每一步。

ON_CHATTER_STEP — "on_chatter_step"

• 何时触发：驱动器取出一个 ConversationTick、即将让 Chatter 生成器步进之前。
• 典型用途：按条件跳过某一步、步进前注入状态。

字段	类型	说明
stream_id	str	聊天流 ID
context	StreamContext	流上下文对象
tick	ConversationTick	当前 tick
chatter_gene	异步生成器	Chatter 会话生成器
continue	bool	是否继续执行本 tick，初始 True

• 可修改字段：
  • continue：回写。发布者读回它，若为 False 则跳过本次 tick，不调用 Chatter。
• 拦截：STOP 会终止后续处理器；效果上类似把 continue 置 False，但更“粗暴”——建议优先用 continue=False。

AFTER_CHATTER_STEP — "after_chatter_step"

• 何时触发：Chatter 单步执行完成之后（无论结果是 Wait/Success/Failure/Stop）。
• 典型用途：步后统计、记忆工具使用跟踪（booku_memory 即订阅此事件）。

字段	类型	说明
stream_id	str	聊天流 ID
context	StreamContext	流上下文对象
tick	ConversationTick	当前 tick
chatter_name	str	Chatter 名称
result	Wait | Success | Failure | Stop	本步结果对象
result_type	str	结果类型名（wait/success/failure/stop）
step_data	dict | None	Chatter 在结果对象上挂的步骤元数据
(step_data 展开字段)	视 Chatter 而定	若 step_data 非空，其键值会被 update 进 params 顶层

• 可修改字段：无回写。链内——step_data 展开出的字段（如 step_scope、used_tools）会传给后续处理器。
• 拦截：无意义（步子已经跑完了）。

15.5.6 上下文请求与提示词事件

ON_INTERNAL_CONTEXT_REQUESTED — "on_internal_context_requested"

• 何时触发：default_chatter 在会话中遇到 internal_context 等待恢复事件，需要向插件索取额外上下文时。
• 典型用途：插件按 context_key 提供内部上下文片段。

字段	类型	说明
stream_id	str	聊天流 ID
context_key	str	请求的上下文键
content	str	上下文文本，初始空串 ""
context_ids	list[str]	关联上下文 ID 列表，初始 []

• 可修改字段：
  • content：回写。发布者读回，作为返回给 Chatter 的文本。
  • context_ids：回写。发布者读回，作为关联 ID 列表。
• 拦截：一般不拦截。

ON_PROMPT_BUILD — "on_prompt_build"

• 何时触发：PromptTemplate.build() 真正渲染模板之前。
• 典型用途：往 values.extra 注入内容、改模板、调整渲染策略（booku_memory 的记忆闪回即用此事件）。

字段	类型	说明
name	str	模板名
template	str	模板字符串
values	dict[str, Any]	占位符值映射
policies	dict[str, RenderPolicy]	占位符渲染策略
strict	bool	是否严格模式

• 可修改字段：
  • template：回写。改后用新模板渲染。
  • values：回写。改后用新值映射渲染（往 values.extra 追加内容是最常见用法）。
  • policies：回写。改后用新策略。
• 拦截：一般不拦截（拦截等于不渲染，会直接静默降级用原模板）。

15.5.7 LLM 请求生命周期事件

这一组三件套围绕一次大模型请求：BEFORE → 成功则 AFTER，重试耗尽则 ON_..._FAILED。

BEFORE_LLM_REQUEST — "before_llm_request"

• 何时触发：组装好 payloads / tools / stream、即将调用 provider 的 create() 之前。
• 典型用途：改请求体、注入/裁剪工具、切换流式开关。

字段	类型	说明
request_name	str	请求名
model_identifier	str	模型标识
stream	bool	是否流式
tools	list	工具列表
payloads	list[LLMPayload]	请求载荷
meta_data	dict	请求元数据

• 可修改字段：
  • payloads：回写（需为 list）。
  • tools：回写（需为 list）。
  • stream：回写（需为 bool）。
• 拦截：STOP 会跳过后续处理器，但发布者仍按当前 params 发请求；想真正“不发请求”应改 payloads 或在更上层处理。

AFTER_LLM_REQUEST — "after_llm_request"

• 何时触发：大模型请求成功返回、LLMResponse 组装好之后。
• 典型用途：改写模型回复、调整 reasoning、增删 tool_calls。

字段	类型	说明
request_name	str	请求名
model_identifier	str	模型标识
stream	bool	是否流式
success	bool	是否成功（此事件恒为 True）
latency	float	耗时（秒）
retry_count	int	重试次数
message	str | None	模型回复文本
reasoning_content	str | None	思维链文本
reasoning_parts	list	思维链分段
tool_calls	list[ToolCall]	工具调用列表
usage	dict | None	token 用量
meta_data	dict	请求元数据

• 可修改字段：
  • message：回写（需为 str 或 None）。
  • reasoning_content：回写（需为 str 或 None）。
  • reasoning_parts：回写（需为 list）。
  • tool_calls：回写（需为 list，元素可为 ToolCall 或 dict）。
• 拦截：一般不拦截。

ON_LLM_REQUEST_FAILED — "on_llm_request_failed"

• 何时触发：重试耗尽、最终抛出异常之前。
• 典型用途：记录失败、改写最终抛出的异常。

字段	类型	说明
request_name	str	请求名
model_identifier	str	模型标识
payloads	list	请求载荷
tools	list	工具列表
stream	bool	是否流式
error	BaseException	分类后的异常对象
error_type	str	异常类型名
error_message	str	异常消息字符串
retry_count	int	重试次数
latency	float	耗时（秒）
meta_data	dict	请求元数据

• 可修改字段：
  • error：回写（需为 BaseException 实例）。改后这个异常会被作为最终异常抛出。
• 拦截：一般不拦截。

15.5.8 Tool / Action / Command 调用生命周期事件

这三类组件共享同一套“BEFORE → 成功 AFTER / 失败 ON_..._FAILED”三段式，字段结构也很像，放在一起看。

Tool 调用

BEFORE_TOOL_CALL — "before_tool_call"

字段	类型	说明
signature	str	工具签名
tool_name	str	工具名
tool_description	str	工具描述
args	dict	调用参数
message	Message	触发调用的消息

• 可修改字段：args（回写，需为 dict，会替换实际传给 Tool 的参数）、message（回写，非 None 则替换）。

AFTER_TOOL_CALL — "after_tool_call"

字段	类型	说明
signature	str	工具签名
tool_name	str	工具名
tool_description	str	工具描述
args	dict	调用参数
result	Any	工具返回值
success	bool	是否成功
execution_time	float	耗时（秒）
message	Message	触发调用的消息

• 可修改字段：result（回写，非 None 则替换返回值）。

ON_TOOL_CALL_FAILED — "on_tool_call_failed"

字段	类型	说明
signature	str	工具签名
tool_name	str	工具名
tool_description	str	工具描述
args	dict	调用参数
error	BaseException	异常对象
error_type	str	异常类型名
error_message	str	异常消息字符串
execution_time	float	耗时（秒）
message	Message	触发调用的消息

• 可修改字段：无回写。链内，纯通知（异常照常抛出）。

Action 调用

BEFORE_ACTION_CALL — "before_action_call"

字段	类型	说明
signature	str	动作签名
action_name	str	动作名
action_description	str	动作描述
args	dict	调用参数
message	Message	触发调用的消息

• 可修改字段：args（回写，需为 dict）、message（回写，非 None 则替换）。

AFTER_ACTION_CALL — "after_action_call"

字段	类型	说明
signature	str	动作签名
action_name	str	动作名
action_description	str	动作描述
args	dict	调用参数
result	Any	动作返回值
success	bool	是否成功
execution_time	float	耗时（秒）
message	Message	触发调用的消息

• 可修改字段：result（回写）、message（回写）。

ON_ACTION_CALL_FAILED — "on_action_call_failed"

字段	类型	说明
signature	str	动作签名
action_name	str	动作名
action_description	str	动作描述
args	dict	调用参数
error	BaseException	异常对象
error_type	str	异常类型名
error_message	str	异常消息字符串
execution_time	float	耗时（秒）
message	Message	触发调用的消息

• 可修改字段：无回写。链内，纯通知。

Command 执行

BEFORE_COMMAND_EXECUTE — "before_command_execute"

字段	类型	说明
signature	str	命令签名
command_name	str	命令名
command_description	str	命令描述
command_path	str	命令路径
args	dict	命令参数
message_text	str	传给命令的子路由文本
message	Message	触发命令的消息

• 可修改字段：message_text（回写，需为 str，会替换传给命令的文本）、message（回写，非 None 则替换）。

AFTER_COMMAND_EXECUTE — "after_command_execute"

字段	类型	说明
signature	str	命令签名
command_name	str	命令名
command_description	str	命令描述
command_path	str	命令路径
args	dict	命令参数
message_text	str	子路由文本
result	Any	命令返回值
success	bool	是否成功
execution_time	float	耗时（秒）
message	Message	触发命令的消息

• 可修改字段：result（回写）。

ON_COMMAND_EXECUTE_FAILED — "on_command_execute_failed"

字段	类型	说明
signature	str	命令签名
command_name	str	命令名
command_description	str	命令描述
command_path	str	命令路径
args	dict	命令参数
message_text	str	子路由文本
error	BaseException	异常对象
error_type	str	异常类型名
error_message	str	异常消息字符串
execution_time	float	耗时（秒）
message	Message	触发命令的消息

• 可修改字段：无回写。链内，纯通知。

15.5.9 预留事件

ON_NOTICE_RECEIVED — "on_notice_received"

• 状态：已在 EventType 中定义，但当前核心尚未发布，是为适配器预留的通知通道。
• 典型用途：适配器可自行用它广播平台通知（如戳一戳、撤回）。注意 onebot_adapter 目前用的是自定义的 OneBotEvent.ON_RECEIVED.* 事件，而非此枚举。
• 建议：订阅前先确认你的目标适配器是否真的发布了这个事件；插件之间协作优先用自定义事件。

15.5.10 速查总表

下表把所有内置事件压成一行，方便快速回查。“回写字段”列空表示无回写字段（纯通知或空参数）。

事件枚举	字符串值	何时触发	回写字段（改了真生效）	STOP 有意义？
ON_START	on_start	Bot 启动完成	—	否
ON_STOP	on_stop	Bot 开始关闭	—	否
ON_ALL_PLUGIN_LOADED	on_all_plugin_loaded	所有插件加载完	—	否（会阻断会话循环启动）
ON_COMPONENT_LOADED	on_component_loaded	组件注册后	—	一般否
ON_COMPONENT_UNLOADED	on_component_unloaded	组件注销时	—	一般否
ON_PLUGIN_UNLOADED	on_plugin_unloaded	插件卸载后	—	一般否
ON_MESSAGE_RECEIVED	on_message_received	收到标准消息	（发布者不回写，但 message 影响下游分发器）	是（拦截消息入流）
ON_RECEIVED_OTHER_MESSAGE	on_received_other_message	收到非标准消息	processed	是（等价丢弃）
ON_MESSAGE_SENT	on_message_sent	发送前	continue_send	是（取消发送）
AFTER_MESSAGE_SENT	after_message_sent	发送成功后	—	否
ON_CHATTER_STEP	on_chatter_step	Chatter 步进前	continue	可，但优先用 continue=False
AFTER_CHATTER_STEP	after_chatter_step	Chatter 步进后	—	否
ON_INTERNAL_CONTEXT_REQUESTED	on_internal_context_requested	索取内部上下文	content、context_ids	一般否
ON_PROMPT_BUILD	on_prompt_build	模板渲染前	template、values、policies	一般否
BEFORE_LLM_REQUEST	before_llm_request	LLM 请求前	payloads、tools、stream	可，但请求仍按当前 params 发
AFTER_LLM_REQUEST	after_llm_request	LLM 请求成功后	message、reasoning_content、reasoning_parts、tool_calls	一般否
ON_LLM_REQUEST_FAILED	on_llm_request_failed	LLM 重试耗尽	error	一般否
BEFORE_TOOL_CALL	before_tool_call	Tool 调用前	args、message	可
AFTER_TOOL_CALL	after_tool_call	Tool 调用后	result	一般否
ON_TOOL_CALL_FAILED	on_tool_call_failed	Tool 调用失败	—	否
BEFORE_ACTION_CALL	before_action_call	Action 调用前	args、message	可
AFTER_ACTION_CALL	after_action_call	Action 调用后	result、message	一般否
ON_ACTION_CALL_FAILED	on_action_call_failed	Action 调用失败	—	否
BEFORE_COMMAND_EXECUTE	before_command_execute	命令执行前	message_text、message	可
AFTER_COMMAND_EXECUTE	after_command_execute	命令执行后	result	一般否
ON_COMMAND_EXECUTE_FAILED	on_command_execute_failed	命令执行失败	—	否
ON_NOTICE_RECEIVED	on_notice_received	（预留，核心未发布）	—	—

最后提醒：所有事件都遵循第 15.4 节的硬约束——返回的 params 必须保留原始 key 集合，只能改值，不能增删字段。回写字段也必须满足发布者校验的类型（如 bool / list / str），否则会被静默忽略。

贡献者

micraft1024a

页面历史

最后编辑于 14 天前

查看完整历史

f9e770a-feat: 添加内置事件参考文档，提供系统事件及可回写字段速查