mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-30 20:35:22 +08:00
164 lines
4.9 KiB
Markdown
164 lines
4.9 KiB
Markdown
# API 参考
|
||
|
||
:::info 目录
|
||
[[toc]]
|
||
:::
|
||
|
||
## 事件 API
|
||
|
||
以下 API 仅在事件处理函数中可用。
|
||
|
||
### 回复消息
|
||
|
||
```python
|
||
await ctx.reply(message_chain: MessageChain)
|
||
```
|
||
|
||
回复此次事件的发起会话。
|
||
|
||
- `message_chain`：[消息链对象](./messages.md)，程序能自动转换为目标消息平台消息链
|
||
|
||
### 发送主动消息
|
||
|
||
> 由于 QQ 官方 API 对主动消息的支持性很差，故若用户使用的是 QQ 官方 API，发送主动消息可能会失败
|
||
|
||
```python
|
||
await ctx.send_message(target_type: str, target_id: str, message_chain: MessageChain)
|
||
```
|
||
|
||
发送主动消息给目标。
|
||
|
||
- `target_type`：目标类型，可选值：`"person"`、`"group"`
|
||
- `target_id`：目标 ID（QQ 号或群号）
|
||
- `message_chain`：[消息链对象](./messages.md)，程序能自动转换为目标消息平台消息链
|
||
|
||
### 阻止事件默认行为
|
||
|
||
```python
|
||
ctx.prevent_default()
|
||
```
|
||
|
||
阻止此次事件的默认行为即停止处理流程之后的行为（如私聊收到消息时向接口获取回复、群消息收到消息时向接口获取回复等）。
|
||
|
||
### 阻止后续插件执行
|
||
|
||
```python
|
||
ctx.prevent_postorder()
|
||
```
|
||
|
||
阻止此次事件后续插件的执行。插件的执行顺序请通过`插件介绍`中的`插件管理`介绍的方式修改优先级。
|
||
|
||
### 添加返回值
|
||
|
||
```python
|
||
ctx.add_return(name: str, value: Any)
|
||
```
|
||
|
||
添加返回值，事件返回值均为**可选**的，每个事件支持的返回值请查看`pkg.plugin.events`中的每个事件的注释。
|
||
|
||
## 请求 API
|
||
|
||
`请求（Query）`指的是用户向 LangBot 发送一个问题时，LangBot 处理该问题的程序上下文。此段落的 API 用于与这些上下文交互。
|
||
|
||
- 事件处理函数中，Query 对象一般位于`ctx.event.query`
|
||
|
||
### 设置请求变量
|
||
|
||
```python
|
||
ctx.event.query.set_variable(key: str, value: typing.Any)
|
||
```
|
||
|
||
请求变量是与此次 Query 绑定的一个 `dict`，其中包含了一些程序上下文信息。如果使用的是 Dify 或者 阿里云百炼 等 LLMOps 的runner，[这些变量将被传入对应平台的 API 作为变量](/zh/deploy/pipelines/readme.html#%E5%AF%B9%E8%AF%9D%E5%8F%98%E9%87%8F)。
|
||
如果您需要使用插件设置变量，建议在`PromptPreProcessing`事件时处理。
|
||
|
||
- `key`：该变量的名称
|
||
- `value`：该变量的值
|
||
|
||
### 获取请求变量
|
||
|
||
```python
|
||
ctx.event.query.get_variable(key: str)
|
||
```
|
||
|
||
获取请求变量。
|
||
|
||
- `key`：变量名称
|
||
- 返回值：`typing.Any`
|
||
|
||
### 获取所有请求变量
|
||
|
||
```python
|
||
ctx.event.query.get_variables()
|
||
```
|
||
|
||
获取此 Query 对象所有已设置的变量值。
|
||
|
||
- 返回值：`dict[str, typing.Any]`
|
||
|
||
|
||
## LangBot API
|
||
|
||
以下 API 是 LangBot 直接提供给插件调用的，可以在事件处理函数之外调用。
|
||
|
||
- `host` 表示 `pkg.plugin.context.APIHost` 类的对象，会被包含在每个插件类中。
|
||
|
||
### 获取已启用的消息平台适配器列表
|
||
|
||
```python
|
||
host.get_platform_adapters()
|
||
```
|
||
|
||
获取已启用的消息平台适配器列表。
|
||
|
||
- 返回值：`list[pkg.platform.adapter.MessageSourceAdapter]`
|
||
|
||
### 发送主动消息
|
||
|
||
```python
|
||
await host.send_active_message(adapter: pkg.platform.adapter.MessageSourceAdapter, target_type: str, target_id: str, message_chain: MessageChain)
|
||
```
|
||
|
||
发送主动消息给目标。
|
||
|
||
- `adapter`：消息平台适配器，通过 `host.get_platform_adapters()` 获取并选择其中一个
|
||
- `target_type`：目标类型，可选值：`"person"`、`"group"`
|
||
- `target_id`：目标 ID（QQ 号或群号）
|
||
- `message_chain`：[消息链对象](./messages.md)，程序能自动转换为目标消息平台消息链
|
||
|
||
:::info
|
||
- 某些消息平台可能不支持主动消息，或有严格限制
|
||
- 某些消息平台适配器（例如`aiocqhttp`）是作为服务端等待消息平台连接上来推送消息，在连接成功之前，发送主动消息会失败
|
||
:::
|
||
|
||
示例：
|
||
|
||
```python
|
||
import asyncio
|
||
import pkg.platform.types as platform_types
|
||
|
||
...
|
||
|
||
# 某个插件的 initialize 函数
|
||
# 此代码将在 LangBot 启动 10 秒后尝试向 QQ 号 1010553892 发送消息 "hello, world!"
|
||
async def initialize(self):
|
||
print(self.host.get_platform_adapters())
|
||
|
||
async def send_message():
|
||
print("send message start waiting")
|
||
await asyncio.sleep(10)
|
||
|
||
try:
|
||
await self.host.send_active_message(
|
||
adapter=self.host.get_platform_adapters()[0],
|
||
target_type="person",
|
||
target_id="1010553892",
|
||
message=platform_types.MessageChain([
|
||
platform_types.Plain("hello, world!")
|
||
])
|
||
)
|
||
except Exception as e:
|
||
traceback.print_exc()
|
||
print("send message end")
|
||
|
||
asyncio.get_running_loop().create_task(send_message())
|
||
``` |