From 08d8ef204459d290ea3a3a852e4f6b410dafd666 Mon Sep 17 00:00:00 2001 From: "Junyan Qin (Chin)" Date: Wed, 8 Oct 2025 14:40:21 +0800 Subject: [PATCH] docs: update pipeline event apis (#64) --- docs/en/plugin/dev/apis/pipeline-events.md | 112 ++++++++++++++------ docs/zh/plugin/dev/apis/pipeline-events.md | 116 +++++++++++++++------ 2 files changed, 166 insertions(+), 62 deletions(-) diff --git a/docs/en/plugin/dev/apis/pipeline-events.md b/docs/en/plugin/dev/apis/pipeline-events.md index 42ce929b4..006fb8a3b 100644 --- a/docs/en/plugin/dev/apis/pipeline-events.md +++ b/docs/en/plugin/dev/apis/pipeline-events.md @@ -1,4 +1,4 @@ -# Pipeline Events +# Pipeline Events and APIs :::info Table of Contents [[toc]] @@ -6,7 +6,11 @@ LangBot plugins can register and handle pipeline events. For usage instructions, see [Component: Event Listener](/en/plugin/dev/components/event-listener). -## *MessageReceived +## List of Events + +Some events have `settable attributes`, which can be modified by plugin code and used in subsequent LangBot processing. + +### *MessageReceived Triggered when any message is received in group chat or private chat. @@ -49,7 +53,7 @@ class GroupMessageReceived(BaseEventModel): ) ``` -## *NormalMessageReceived +### *NormalMessageReceived Triggered when a group chat or private chat message is received and determined to be a message that needs to be processed by LLM (non-command message). @@ -68,11 +72,13 @@ class PersonNormalMessageReceived(BaseEventModel): text_message: str """Message text""" - alter: typing.Optional[str] = None - """Modified message text""" + # ========== Settable Attributes ========== - reply: typing.Optional[list] = None - """Reply message component list""" + user_message_alter: typing.Optional[provider_message.ContentElement] = None + """Modified message text, langbot_plugin.api.entities.builtin.provider.message.ContentElement type""" + + reply_message_chain: typing.Optional[platform_message.MessageChain] = None + """Reply message component list, only effective when preventing default behavior""" class GroupNormalMessageReceived(BaseEventModel): """Triggered when a group chat normal message that should be processed is determined""" @@ -88,14 +94,16 @@ class GroupNormalMessageReceived(BaseEventModel): text_message: str """Message text""" - alter: typing.Optional[str] = None - """Modified message text""" + # ========== Settable Attributes ========== - reply: typing.Optional[list] = None - """Reply message component list""" + user_message_alter: typing.Optional[provider_message.ContentElement] = None + """Modified message text, langbot_plugin.api.entities.builtin.provider.message.ContentElement type""" + + reply_message_chain: typing.Optional[platform_message.MessageChain] = None + """Reply message component list, only effective when preventing default behavior""" ``` -## *CommandSent +### *CommandSent :::warning Note No longer recommended for use, please use [Component: Command](/en/plugin/dev/components/command) instead. @@ -127,11 +135,6 @@ class PersonCommandSent(BaseEventModel): is_admin: bool """Whether it's an administrator""" - alter: typing.Optional[str] = None - """Modified complete command text""" - - reply: typing.Optional[list] = None - """Reply message component list""" class GroupCommandSent(BaseEventModel): """Triggered when a group chat command that should be processed is determined""" @@ -156,14 +159,9 @@ class GroupCommandSent(BaseEventModel): is_admin: bool """Whether it's an administrator""" - alter: typing.Optional[str] = None - """Modified complete command text""" - - reply: typing.Optional[list] = None - """Reply message component list""" ``` -## NormalMessageResponded +### NormalMessageResponded Triggered when a message receives an LLM response. @@ -194,11 +192,13 @@ class NormalMessageResponded(BaseEventModel): funcs_called: list[str] """List of called functions""" - reply: typing.Optional[list] = None - """Reply message component list""" + # ========== Settable Attributes ========== + + reply_message_chain: typing.Optional[platform_message.MessageChain] = None + """Reply message component list, only effective when preventing default behavior""" ``` -## PromptPreProcessing +### PromptPreProcessing Triggered when building the LLM response context (prompt). @@ -210,9 +210,59 @@ class PromptPreProcessing(BaseEventModel): session_name: str - default_prompt: list[provider_message.Message] - """Scenario preset for this conversation, can be modified""" + # ========== Settable Attributes ========== - prompt: list[provider_message.Message] - """Existing message records for this conversation, can be modified""" -``` \ No newline at end of file + default_prompt: list[typing.Union[provider_message.Message, provider_message.MessageChunk]] + """Scenario preset for this conversation, can be modified, langbot_plugin.api.entities.builtin.provider.message.Message or langbot_plugin.api.entities.builtin.provider.message.MessageChunk type""" + + prompt: list[typing.Union[provider_message.Message, provider_message.MessageChunk]] + """Existing message records for this conversation, can be modified, langbot_plugin.api.entities.builtin.provider.message.Message or langbot_plugin.api.entities.builtin.provider.message.MessageChunk type""" +``` + +## Event Context APIs + +```python +... + @self.handler(events.PersonMessageReceived) + async def handler(event_context: context.EventContext): + ... +``` + +Event processing methods will be passed the `EventContext` object, which contains event context information, and the object has both [Request API](/en/plugin/dev/apis/common) and event context specific APIs. The following is a list of event context specific APIs: + +### Prevent Default Behavior + +```python +def prevent_default(self): + """Prevent default behavior""" + +# Usage example +event_context.prevent_default() +``` + +Calling this method will prevent the default subsequent behavior of this event, and the pipeline will end directly. + +:::info +Only the following events can prevent default behavior: + +- PersonMessageReceived +- GroupMessageReceived +- PersonNormalMessageReceived +- GroupNormalMessageReceived +- PersonCommandSent +- GroupCommandSent +- NormalMessageResponded + +::: + +### Prevent Postorder Execution + +```python +def prevent_postorder(self): + """Prevent postorder execution""" + +# Usage example +event_context.prevent_postorder() +``` + +Calling this method will prevent the subsequent plugins from executing this time. diff --git a/docs/zh/plugin/dev/apis/pipeline-events.md b/docs/zh/plugin/dev/apis/pipeline-events.md index 772703b5e..9ddee973c 100644 --- a/docs/zh/plugin/dev/apis/pipeline-events.md +++ b/docs/zh/plugin/dev/apis/pipeline-events.md @@ -1,4 +1,4 @@ -# 流水线事件 +# 流水线事件和 API :::info 目录 [[toc]] @@ -6,7 +6,11 @@ LangBot 插件可注册并处理流水线事件。使用方法见[组件：事件监听器](/zh/plugin/dev/components/event-listener)。 -## *MessageReceived +## 可监听的事件列表 + +某些事件具有`可设置的属性`，这些属性可以被插件代码修改，并在之后被用在 LangBot 后续的处理中。 + +### *MessageReceived 接收到群聊或私聊任何消息时触发。 @@ -49,7 +53,7 @@ class GroupMessageReceived(BaseEventModel): ) ``` -## *NormalMessageReceived +### *NormalMessageReceived 接收到群聊或私聊消息，并判断为需要由 LLM 处理的消息（非命令消息）时触发。 @@ -68,11 +72,14 @@ class PersonNormalMessageReceived(BaseEventModel): text_message: str """消息文本""" - alter: typing.Optional[str] = None - """修改后的消息文本""" + # ========== 可设置的属性 ========== + + user_message_alter: typing.Optional[provider_message.ContentElement] = None + """修改后的消息文本，langbot_plugin.api.entities.builtin.provider.message.ContentElement 类型""" + + reply_message_chain: typing.Optional[platform_message.MessageChain] = None + """直接回复消息链，仅在阻止默认行为时生效""" - reply: typing.Optional[list] = None - """回复消息组件列表""" class GroupNormalMessageReceived(BaseEventModel): """判断为应该处理的群聊普通消息时触发""" @@ -88,14 +95,16 @@ class GroupNormalMessageReceived(BaseEventModel): text_message: str """消息文本""" - alter: typing.Optional[str] = None - """修改后的消息文本""" + # ========== 可设置的属性 ========== - reply: typing.Optional[list] = None - """回复消息组件列表""" + user_message_alter: typing.Optional[provider_message.ContentElement] = None + """修改后的消息文本，langbot_plugin.api.entities.builtin.provider.message.ContentElement 类型""" + + reply_message_chain: typing.Optional[platform_message.MessageChain] = None + """直接回复消息链，仅在阻止默认行为时生效""" ``` -## *CommandSent +### *CommandSent :::warning 注意 不再推荐使用，请改为使用[组件：命令](/zh/plugin/dev/components/command)。 @@ -127,11 +136,6 @@ class PersonCommandSent(BaseEventModel): is_admin: bool """是否为管理员""" - alter: typing.Optional[str] = None - """修改后的完整命令文本""" - - reply: typing.Optional[list] = None - """回复消息组件列表""" class GroupCommandSent(BaseEventModel): """判断为应该处理的群聊命令时触发""" @@ -156,20 +160,15 @@ class GroupCommandSent(BaseEventModel): is_admin: bool """是否为管理员""" - alter: typing.Optional[str] = None - """修改后的完整命令文本""" - - reply: typing.Optional[list] = None - """回复消息组件列表""" ``` -## NormalMessageResponded +### NormalMessageResponded 消息得到 LLM 响应时触发。 ```python class NormalMessageResponded(BaseEventModel): - """回复普通消息时触发""" + """收到对普通消息的响应时触发""" event_name: str = "NormalMessageResponded" @@ -194,11 +193,13 @@ class NormalMessageResponded(BaseEventModel): funcs_called: list[str] """调用的函数列表""" - reply: typing.Optional[list] = None - """回复消息组件列表""" + # ========== 可设置的属性 ========== + + reply_message_chain: typing.Optional[platform_message.MessageChain] = None + """直接回复消息链，仅在阻止默认行为时生效""" ``` -## PromptPreProcessing +### PromptPreProcessing 在构建 LLM 响应的上下文（prompt）时触发。 @@ -210,9 +211,62 @@ class PromptPreProcessing(BaseEventModel): session_name: str - default_prompt: list[provider_message.Message] - """此对话的情景预设，可修改""" + # ========== 可设置的属性 ========== + + default_prompt: list[ + typing.Union[provider_message.Message, provider_message.MessageChunk] + ] + """此对话的情景预设（系统提示词），可修改，langbot_plugin.api.entities.builtin.provider.message.Message 或 langbot_plugin.api.entities.builtin.provider.message.MessageChunk 类型""" + + prompt: list[typing.Union[provider_message.Message, provider_message.MessageChunk]] + """此对话现有消息记录，可修改，langbot_plugin.api.entities.builtin.provider.message.Message 或 langbot_plugin.api.entities.builtin.provider.message.MessageChunk 类型""" - prompt: list[provider_message.Message] - """此对话现有消息记录，可修改""" ``` + +## 事件上下文 API + +```python +... + @self.handler(events.PersonMessageReceived) + async def handler(event_context: context.EventContext): + ... +``` + +事件处理方法将被传入`EventContext`对象，该对象包含事件的上下文信息，该对象同时具有[请求 API](/zh/plugin/dev/apis/common)和事件上下文特定 API，以下为事件上下文特定 API 列表： + +### 阻止默认行为 + +```python +def prevent_default(self): + """阻止默认行为""" + +# 调用示例 +event_context.prevent_default() +``` + +调用该方法后，该事件后续默认行为将被阻止，流水线将直接结束。 + +:::info +仅以下事件可阻止默认行为： + +- PersonMessageReceived +- GroupMessageReceived +- PersonNormalMessageReceived +- GroupNormalMessageReceived +- PersonCommandSent +- GroupCommandSent +- NormalMessageResponded + +::: + +### 阻止后序插件执行 + +```python +def prevent_postorder(self): + """阻止后序插件执行""" + +# 调用示例 +event_context.prevent_postorder() +``` + +调用该方法后，注册了该事件的后序插件此次将不被执行。