mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-30 04:15:45 +08:00
docs: update pipeline event apis (#64)
This commit is contained in:
Junyan Qin (Chin)
@@ -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"""
|
||||
```
|
||||
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.
|
||||
|
||||
@@ -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()
|
||||
```
|
||||
|
||||
调用该方法后，注册了该事件的后序插件此次将不被执行。
|
||||
|
||||
Reference in New Issue
Block a user