mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-31 04:45:23 +08:00
Update plugin/dev/api-ref.md to match Chinese structure
Co-Authored-By: Junyan Qin <Chin> <[email protected]>
This commit is contained in:
Devin AI
co-authored by
Junyan Qin <Chin>
Junyan Qin <Chin>
parent
b29355b814
commit
0e48d25412
+147
-595
@@ -1,612 +1,164 @@
|
||||
# API Reference
|
||||
|
||||
This document provides a reference for the LangBot API that is available to plugins.
|
||||
|
||||
## APIHost
|
||||
|
||||
The `APIHost` class provides access to LangBot's API from plugins. It is passed to the plugin's constructor.
|
||||
|
||||
```python
|
||||
from langbot.api import APIHost
|
||||
|
||||
class MyPlugin(Plugin):
|
||||
def __init__(self, api_host: APIHost):
|
||||
super().__init__(api_host)
|
||||
self.api = api_host
|
||||
```
|
||||
|
||||
## Message API
|
||||
|
||||
### send_message
|
||||
|
||||
Sends a message to a specific destination.
|
||||
|
||||
```python
|
||||
def send_message(self, source, content, **kwargs) -> str:
|
||||
"""
|
||||
Send a message to a specific destination.
|
||||
|
||||
Args:
|
||||
source: The destination to send the message to
|
||||
content: The content of the message
|
||||
**kwargs: Additional arguments
|
||||
|
||||
Returns:
|
||||
The message ID
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
message_id = self.api.send_message(
|
||||
ctx.event.message.source,
|
||||
"Hello, World!"
|
||||
)
|
||||
```
|
||||
|
||||
### reply_message
|
||||
|
||||
Replies to a specific message.
|
||||
|
||||
```python
|
||||
def reply_message(self, message, content, **kwargs) -> str:
|
||||
"""
|
||||
Reply to a specific message.
|
||||
|
||||
Args:
|
||||
message: The message to reply to
|
||||
content: The content of the reply
|
||||
**kwargs: Additional arguments
|
||||
|
||||
Returns:
|
||||
The message ID
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
message_id = self.api.reply_message(
|
||||
ctx.event.message,
|
||||
"This is a reply"
|
||||
)
|
||||
```
|
||||
|
||||
### delete_message
|
||||
|
||||
Deletes a specific message.
|
||||
|
||||
```python
|
||||
def delete_message(self, message_id, **kwargs) -> bool:
|
||||
"""
|
||||
Delete a specific message.
|
||||
|
||||
Args:
|
||||
message_id: The ID of the message to delete
|
||||
**kwargs: Additional arguments
|
||||
|
||||
Returns:
|
||||
True if successful, False otherwise
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
success = self.api.delete_message(message_id)
|
||||
```
|
||||
|
||||
## User API
|
||||
|
||||
### get_user_info
|
||||
|
||||
Gets information about a user.
|
||||
|
||||
```python
|
||||
def get_user_info(self, user_id, **kwargs) -> dict:
|
||||
"""
|
||||
Get information about a user.
|
||||
|
||||
Args:
|
||||
user_id: The ID of the user
|
||||
**kwargs: Additional arguments
|
||||
|
||||
Returns:
|
||||
A dictionary containing user information
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
user_info = self.api.get_user_info("12345678")
|
||||
print(user_info["nickname"])
|
||||
```
|
||||
|
||||
### get_friend_list
|
||||
|
||||
Gets a list of the bot's friends.
|
||||
|
||||
```python
|
||||
def get_friend_list(self, **kwargs) -> list:
|
||||
"""
|
||||
Get a list of the bot's friends.
|
||||
|
||||
Args:
|
||||
**kwargs: Additional arguments
|
||||
|
||||
Returns:
|
||||
A list of friend information
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
friends = self.api.get_friend_list()
|
||||
for friend in friends:
|
||||
print(friend["nickname"])
|
||||
```
|
||||
|
||||
## Group API
|
||||
|
||||
### get_group_info
|
||||
|
||||
Gets information about a group.
|
||||
|
||||
```python
|
||||
def get_group_info(self, group_id, **kwargs) -> dict:
|
||||
"""
|
||||
Get information about a group.
|
||||
|
||||
Args:
|
||||
group_id: The ID of the group
|
||||
**kwargs: Additional arguments
|
||||
|
||||
Returns:
|
||||
A dictionary containing group information
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
group_info = self.api.get_group_info("12345678")
|
||||
print(group_info["name"])
|
||||
```
|
||||
|
||||
### get_group_member_list
|
||||
|
||||
Gets a list of members in a group.
|
||||
|
||||
```python
|
||||
def get_group_member_list(self, group_id, **kwargs) -> list:
|
||||
"""
|
||||
Get a list of members in a group.
|
||||
|
||||
Args:
|
||||
group_id: The ID of the group
|
||||
**kwargs: Additional arguments
|
||||
|
||||
Returns:
|
||||
A list of member information
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
members = self.api.get_group_member_list("12345678")
|
||||
for member in members:
|
||||
print(member["nickname"])
|
||||
```
|
||||
|
||||
### get_group_list
|
||||
|
||||
Gets a list of groups the bot is in.
|
||||
|
||||
```python
|
||||
def get_group_list(self, **kwargs) -> list:
|
||||
"""
|
||||
Get a list of groups the bot is in.
|
||||
|
||||
Args:
|
||||
**kwargs: Additional arguments
|
||||
|
||||
Returns:
|
||||
A list of group information
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
groups = self.api.get_group_list()
|
||||
for group in groups:
|
||||
print(group["name"])
|
||||
```
|
||||
|
||||
## LLM API
|
||||
|
||||
### call_llm
|
||||
|
||||
Calls the LLM with a specific prompt.
|
||||
|
||||
```python
|
||||
def call_llm(self, prompt, model=None, **kwargs) -> str:
|
||||
"""
|
||||
Call the LLM with a specific prompt.
|
||||
|
||||
Args:
|
||||
prompt: The prompt to send to the LLM
|
||||
model: The model to use (defaults to the system default)
|
||||
**kwargs: Additional arguments
|
||||
|
||||
Returns:
|
||||
The LLM's response
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
response = self.api.call_llm(
|
||||
"What is the capital of France?",
|
||||
model="gpt-3.5-turbo"
|
||||
)
|
||||
print(response)
|
||||
```
|
||||
|
||||
### call_llm_with_functions
|
||||
|
||||
Calls the LLM with a specific prompt and available functions.
|
||||
|
||||
```python
|
||||
def call_llm_with_functions(self, prompt, functions, model=None, **kwargs) -> dict:
|
||||
"""
|
||||
Call the LLM with a specific prompt and available functions.
|
||||
|
||||
Args:
|
||||
prompt: The prompt to send to the LLM
|
||||
functions: A list of function definitions
|
||||
model: The model to use (defaults to the system default)
|
||||
**kwargs: Additional arguments
|
||||
|
||||
Returns:
|
||||
A dictionary containing the LLM's response and any function calls
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
functions = [
|
||||
{
|
||||
"name": "get_weather",
|
||||
"description": "Get the weather for a location",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {
|
||||
"type": "string",
|
||||
"description": "The location to get weather for"
|
||||
}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
response = self.api.call_llm_with_functions(
|
||||
"What's the weather in Paris?",
|
||||
functions,
|
||||
model="gpt-3.5-turbo"
|
||||
)
|
||||
|
||||
if "function_call" in response:
|
||||
function_name = response["function_call"]["name"]
|
||||
function_args = response["function_call"]["arguments"]
|
||||
# Handle the function call
|
||||
```
|
||||
|
||||
## Storage API
|
||||
|
||||
### storage.set
|
||||
|
||||
Stores a value with a specific key.
|
||||
|
||||
```python
|
||||
def set(self, key, value) -> None:
|
||||
"""
|
||||
Store a value with a specific key.
|
||||
|
||||
Args:
|
||||
key: The key to store the value under
|
||||
value: The value to store
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
self.api.storage.set("my_plugin:counter", 42)
|
||||
```
|
||||
|
||||
### storage.get
|
||||
|
||||
Gets a value with a specific key.
|
||||
|
||||
```python
|
||||
def get(self, key, default=None):
|
||||
"""
|
||||
Get a value with a specific key.
|
||||
|
||||
Args:
|
||||
key: The key to get the value for
|
||||
default: The default value to return if the key doesn't exist
|
||||
|
||||
Returns:
|
||||
The stored value or the default value
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
counter = self.api.storage.get("my_plugin:counter", 0)
|
||||
```
|
||||
|
||||
### storage.has
|
||||
|
||||
Checks if a key exists.
|
||||
|
||||
```python
|
||||
def has(self, key) -> bool:
|
||||
"""
|
||||
Check if a key exists.
|
||||
|
||||
Args:
|
||||
key: The key to check
|
||||
|
||||
Returns:
|
||||
True if the key exists, False otherwise
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
if self.api.storage.has("my_plugin:counter"):
|
||||
# Key exists
|
||||
```
|
||||
|
||||
### storage.delete
|
||||
|
||||
Deletes a key.
|
||||
|
||||
```python
|
||||
def delete(self, key) -> None:
|
||||
"""
|
||||
Delete a key.
|
||||
|
||||
Args:
|
||||
key: The key to delete
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
self.api.storage.delete("my_plugin:counter")
|
||||
```
|
||||
|
||||
## Config API
|
||||
|
||||
### config.get
|
||||
|
||||
Gets a configuration value.
|
||||
|
||||
```python
|
||||
def get(self, key, default=None):
|
||||
"""
|
||||
Get a configuration value.
|
||||
|
||||
Args:
|
||||
key: The key to get the value for
|
||||
default: The default value to return if the key doesn't exist
|
||||
|
||||
Returns:
|
||||
The configuration value or the default value
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
api_key = self.api.config.get("my_plugin:api_key")
|
||||
```
|
||||
|
||||
### config.set
|
||||
|
||||
Sets a configuration value.
|
||||
|
||||
```python
|
||||
def set(self, key, value) -> None:
|
||||
"""
|
||||
Set a configuration value.
|
||||
|
||||
Args:
|
||||
key: The key to set the value for
|
||||
value: The value to set
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
self.api.config.set("my_plugin:api_key", "my-api-key")
|
||||
```
|
||||
:::info Table of Contents
|
||||
[[toc]]
|
||||
:::
|
||||
|
||||
## Event API
|
||||
|
||||
### register_event_handler
|
||||
The following APIs are only available in event handler functions.
|
||||
|
||||
Registers a handler for a specific event.
|
||||
### Reply to Message
|
||||
|
||||
```python
|
||||
def register_event_handler(self, event_type, handler) -> None:
|
||||
"""
|
||||
Register a handler for a specific event.
|
||||
|
||||
Args:
|
||||
event_type: The type of event to handle
|
||||
handler: The handler function
|
||||
"""
|
||||
await ctx.reply(message_chain: MessageChain)
|
||||
```
|
||||
|
||||
Reply to the conversation that initiated this event.
|
||||
|
||||
- `message_chain`: [Message Chain object](./messages.md), the program can automatically convert it to the target message platform's message chain
|
||||
|
||||
### Send Active Message
|
||||
|
||||
> Due to poor support for active messages in QQ Official API, if users are using QQ Official API, sending active messages may fail
|
||||
|
||||
```python
|
||||
await ctx.send_message(target_type: str, target_id: str, message_chain: MessageChain)
|
||||
```
|
||||
|
||||
Send an active message to the target.
|
||||
|
||||
- `target_type`: Target type, possible values: `"person"`, `"group"`
|
||||
- `target_id`: Target ID (QQ number or group number)
|
||||
- `message_chain`: [Message Chain object](./messages.md), the program can automatically convert it to the target message platform's message chain
|
||||
|
||||
### Prevent Default Event Behavior
|
||||
|
||||
```python
|
||||
ctx.prevent_default()
|
||||
```
|
||||
|
||||
Prevent the default behavior of this event, i.e., stop the subsequent behaviors in the processing flow (such as getting a reply from the interface when receiving a private chat message, getting a reply from the interface when receiving a group message, etc.).
|
||||
|
||||
### Prevent Subsequent Plugin Execution
|
||||
|
||||
```python
|
||||
ctx.prevent_postorder()
|
||||
```
|
||||
|
||||
Prevent the execution of subsequent plugins for this event. To modify the execution order of plugins, please change the priority through the methods described in the "Plugin Management" section of the "Plugin Introduction".
|
||||
|
||||
### Add Return Value
|
||||
|
||||
```python
|
||||
ctx.add_return(name: str, value: Any)
|
||||
```
|
||||
|
||||
Add a return value. Event return values are all **optional**. For return values supported by each event, please check the comments of each event in `pkg.plugin.events`.
|
||||
|
||||
## Request API
|
||||
|
||||
A `Request (Query)` refers to the program context when a user sends a question to LangBot and LangBot processes that question. The APIs in this section are used to interact with these contexts.
|
||||
|
||||
- In event handler functions, the Query object is usually located at `ctx.event.query`
|
||||
|
||||
### Set Request Variable
|
||||
|
||||
```python
|
||||
ctx.event.query.set_variable(key: str, value: typing.Any)
|
||||
```
|
||||
|
||||
Request variables are a `dict` bound to this Query, which contains some program context information. If you are using Dify or Alibaba Cloud Bailian or other LLMOps runners, [these variables will be passed to the corresponding platform's API as variables](/en/deploy/pipelines/readme.html#conversation-variables).
|
||||
If you need to set variables using plugins, it is recommended to handle them during the `PromptPreProcessing` event.
|
||||
|
||||
- `key`: The name of the variable
|
||||
- `value`: The value of the variable
|
||||
|
||||
### Get Request Variable
|
||||
|
||||
```python
|
||||
ctx.event.query.get_variable(key: str)
|
||||
```
|
||||
|
||||
Get a request variable.
|
||||
|
||||
- `key`: Variable name
|
||||
- Return value: `typing.Any`
|
||||
|
||||
### Get All Request Variables
|
||||
|
||||
```python
|
||||
ctx.event.query.get_variables()
|
||||
```
|
||||
|
||||
Get all variable values set for this Query object.
|
||||
|
||||
- Return value: `dict[str, typing.Any]`
|
||||
|
||||
|
||||
## LangBot API
|
||||
|
||||
The following APIs are provided directly by LangBot for plugins to call and can be called outside of event handler functions.
|
||||
|
||||
- `host` represents an object of the `pkg.plugin.context.APIHost` class, which is included in each plugin class.
|
||||
|
||||
### Get Enabled Message Platform Adapters List
|
||||
|
||||
```python
|
||||
host.get_platform_adapters()
|
||||
```
|
||||
|
||||
Get a list of enabled message platform adapters.
|
||||
|
||||
- Return value: `list[pkg.platform.adapter.MessageSourceAdapter]`
|
||||
|
||||
### Send Active Message
|
||||
|
||||
```python
|
||||
await host.send_active_message(adapter: pkg.platform.adapter.MessageSourceAdapter, target_type: str, target_id: str, message_chain: MessageChain)
|
||||
```
|
||||
|
||||
Send an active message to the target.
|
||||
|
||||
- `adapter`: Message platform adapter, obtained through `host.get_platform_adapters()` and selecting one of them
|
||||
- `target_type`: Target type, possible values: `"person"`, `"group"`
|
||||
- `target_id`: Target ID (QQ number or group number)
|
||||
- `message_chain`: [Message Chain object](./messages.md), the program can automatically convert it to the target message platform's message chain
|
||||
|
||||
:::info
|
||||
- Some message platforms may not support active messages or have strict limitations
|
||||
- Some message platform adapters (such as `aiocqhttp`) act as servers waiting for message platforms to connect and push messages. Before a successful connection, sending active messages will fail
|
||||
:::
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
def my_handler(ctx):
|
||||
# Handle the event
|
||||
pass
|
||||
import asyncio
|
||||
import pkg.platform.types as platform_types
|
||||
|
||||
self.api.register_event_handler(PersonNormalMessageReceived, my_handler)
|
||||
```
|
||||
...
|
||||
|
||||
### unregister_event_handler
|
||||
|
||||
Unregisters a handler for a specific event.
|
||||
|
||||
```python
|
||||
def unregister_event_handler(self, event_type, handler) -> None:
|
||||
"""
|
||||
Unregister a handler for a specific event.
|
||||
|
||||
Args:
|
||||
event_type: The type of event
|
||||
handler: The handler function
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
self.api.unregister_event_handler(PersonNormalMessageReceived, my_handler)
|
||||
```
|
||||
|
||||
## Command API
|
||||
|
||||
### register_command
|
||||
|
||||
Registers a command.
|
||||
|
||||
```python
|
||||
def register_command(self, name, handler, description=None) -> None:
|
||||
"""
|
||||
Register a command.
|
||||
|
||||
Args:
|
||||
name: The name of the command
|
||||
handler: The handler function
|
||||
description: The description of the command
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
def echo_handler(args):
|
||||
return args
|
||||
|
||||
self.api.register_command("echo", echo_handler, "Echo a message")
|
||||
```
|
||||
|
||||
### unregister_command
|
||||
|
||||
Unregisters a command.
|
||||
|
||||
```python
|
||||
def unregister_command(self, name) -> None:
|
||||
"""
|
||||
Unregister a command.
|
||||
|
||||
Args:
|
||||
name: The name of the command
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
self.api.unregister_command("echo")
|
||||
```
|
||||
|
||||
## Utility API
|
||||
|
||||
### logger
|
||||
|
||||
Provides access to the logger.
|
||||
|
||||
```python
|
||||
self.api.logger.debug("Debug message")
|
||||
self.api.logger.info("Info message")
|
||||
self.api.logger.warning("Warning message")
|
||||
self.api.logger.error("Error message")
|
||||
```
|
||||
|
||||
### schedule
|
||||
|
||||
Schedules a function to be called at a specific time.
|
||||
|
||||
```python
|
||||
def schedule(self, func, when, *args, **kwargs) -> str:
|
||||
"""
|
||||
Schedule a function to be called at a specific time.
|
||||
|
||||
Args:
|
||||
func: The function to call
|
||||
when: When to call the function (datetime or timedelta)
|
||||
*args: Arguments to pass to the function
|
||||
**kwargs: Keyword arguments to pass to the function
|
||||
# initialize function of a plugin
|
||||
# This code will attempt to send a message "hello, world!" to QQ number 1010553892 10 seconds after LangBot starts
|
||||
async def initialize(self):
|
||||
print(self.host.get_platform_adapters())
|
||||
|
||||
Returns:
|
||||
The schedule ID
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
from datetime import timedelta
|
||||
|
||||
def my_function():
|
||||
# Do something
|
||||
pass
|
||||
|
||||
schedule_id = self.api.schedule(my_function, timedelta(hours=1))
|
||||
```
|
||||
|
||||
### cancel_schedule
|
||||
|
||||
Cancels a scheduled function.
|
||||
|
||||
```python
|
||||
def cancel_schedule(self, schedule_id) -> bool:
|
||||
"""
|
||||
Cancel a scheduled function.
|
||||
|
||||
Args:
|
||||
schedule_id: The ID of the schedule
|
||||
|
||||
Returns:
|
||||
True if successful, False otherwise
|
||||
"""
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```python
|
||||
success = self.api.cancel_schedule(schedule_id)
|
||||
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())
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user