xinyin025/LangBot
1
0
Fork 0
mirror of https://github.com/langbot-app/LangBot.git synced 2026-11-04 14:52:12 +08:00
Code Issues Packages Projects Releases Wiki Activity

i18n初步测试

Browse Source
This commit is contained in:
lazy
2025-01-02 23:30:44 +08:00
parent 85ecc12cac
commit 89ca9228ba
111 changed files with 3622 additions and 218 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/plugin/dev/api-ref.md
+59
View File
@@ -0,0 +1,59 @@
# API Reference
:::info Table of Contents
[[toc]]
:::
The following APIs are only available for **event plugins**. For component extensions, please refer to the source code directly.
## Message Handling
### Reply to a Message
```python
ctx.reply(message_chain: MessageChain)
```
Replies to the conversation that triggered the event.
- `message_chain`: [MessageChain object](./messages.md), which the program can automatically convert into the target message platform's message chain.
### Send an Active Message
> Due to poor support for active messages in the official QQ API, sending active messages may fail if the user is using the official QQ API.
```python
ctx.send_message(target_type: str, target_id: str, message_chain: MessageChain)
```
Sends an active message to the target.
- `target_type`: The type of target, with possible values: `"person"`, `"group"`.
- `target_id`: The target ID (QQ number or group number).
- `message_chain`: [MessageChain object](./messages.md), which the program can automatically convert into the target message platform's message chain.
## Event Handling
### Prevent Default Event Behavior
```python
ctx.prevent_default()
```
Prevents the default behavior of the event, stopping subsequent processing actions (e.g., fetching a reply from the interface when a private message is received, or fetching a reply from the interface when a group message is received).
### Prevent Subsequent Plugin Execution
```python
ctx.prevent_postorder()
```
Prevents the execution of subsequent plugins for this event. The execution order of plugins can be modified by adjusting priorities as described in the `Plugin Management` section of the `Plugin Introduction`.
### Add a Return Value
```python
ctx.add_return(name: str, value: Any)
```
Adds a return value. Return values for events are **optional**. For the return values supported by each event, please refer to the comments in `pkg.plugin.events` for each event.
docs/en/plugin/dev/extension.md
+104
View File
@@ -0,0 +1,104 @@
# Component Extension
> Please read the [Plugin Introduction Page](/plugin/plugin-intro) first.
:::info Table of Contents
[[toc]]
:::
Plugins wrapped in subclasses of `BasePlugin` can only listen to predefined events, whereas component extensions can replace entire components, enabling more powerful functionality.
- Component extensions do not need to be wrapped in a subclass of `BasePlugin` and can be placed in any module within the plugin directory.
- Extended components are not controlled by the plugin's on/off switch.
- Extended components are typically selected via options in the configuration file.
## Extendable Components
![Component Extension Diagram](/assets/image/develop_comp_arch_1.png)
To extend a component, create a new class that inherits from the component's base class, then use the corresponding decorator on the class, and configure the component to use this implementation based on the usage method.
Most components contain an `ap: pkg.core.app.Application` object, which can be used to interact with various parts of the entire program.
Most components support implementing the `async def initialize(self)` method for asynchronous initialization when the component is loaded.
The `ap` object includes manager objects for various configuration files, which can be used to access these configurations.
### Command
Add a new command.
- Base Class: `pkg.command.operator.CommandOperator`
- Decorator: `pkg.command.operator.operator_class(name: str, help: str="", usage: str=None, alias: list[str]=[], privilege: int=1, parent_class: typing.Type[CommandOperator] = None)`
- Reference Implementation: `pkg.command.operators/`
- Usage: After successful loading, execute the command `!cmd` to view all commands and their help information.
### Content Filter
Add a new content processor that determines whether to continue processing before and after handling a message.
- Base Class: `pkg.pipeline.cntfilter.filter.ContentFilter`
- Decorator: `pkg.pipeline.cntfilter.filter.filter_class(name: str)`
- Reference Implementation: `pkg.pipeline.cntfilter.filters/`
- Usage: After successful loading, the `process` method of the content filter will be called at the declared inspection stage for each filter implementation.
### Long Message Handling Strategy
Add a new long message handling strategy. Examples include components that convert text to merged forwarded messages or text to images.
- Base Class: `pkg.pipeline.longtext.strategy.LongTextStrategy`
- Decorator: `pkg.pipeline.longtext.strategy.strategy_class(name: str)`
- Reference Implementation: `pkg.pipeline.longtext.strategies/`
- Usage: Set the `strategy` field in the `long-text-strategy` section of `data/config/platform.json` to the name of the newly added strategy.
### Conversation Rate Limiting Algorithm
Add a new conversation rate limiting algorithm. The rate limiting algorithm implementation class methods are called when a conversation request enters and exits, allowing the implementation class to control waiting or dropping requests.
- Base Class: `pkg.pipeline.ratelimit.algo.RateLimitAlgo`
- Decorator: `pkg.pipeline.ratelimit.algo.algo_class(name: str)`
- Reference Implementation: `pkg.pipeline.ratelimit.algos/`
- Usage: Set the `algo` field in the `rate-limit` section of `data/config/pipeline.json` to the name of the newly added algorithm.
### LLM Interface Requester
Add a new LLM interface requester, such as integrating the ChatGLM interface.
- Base Class: `pkg.provider.modelmgr.api.LLMAPIRequester`
- Decorator: `pkg.provider.modelmgr.api.api_requester_class(name: str)`
- Reference Implementation: `pkg.provider.modelmgr.apis/`
- Usage: Add a model in `data/metadata/llm-models.json` and set the `requester` field of the model to the name of the newly added requester. For details, refer to the metadata configuration section.
### Prompt Loader
Add a new Prompt loader.
- Base Class: `pkg.provider.sysprompt.loader.PromptLoader`
- Decorator: `pkg.provider.sysprompt.loader.loader_class(name: str)`
- Reference Implementation: `pkg.provider.sysprompt.loaders/`
- Usage: Set the `prompt-mode` field in `data/config/provider.json` to the name of the newly added loader.
### Message Platform Adapter
Add a new message platform adapter, such as integrating WhatsApp or Discord.
- Base Class: `pkg.platform.adapter.MessageSourceAdapter`
- Decorator: `pkg.platform.adapter.adapter_class(name: str)`
- Reference Implementation: `pkg.platform.adapters/`
- Usage: The configuration information in the `platform-adapters` section of `data/config/platform.json` will automatically look up the corresponding adapter implementation based on the `adapter` name during initialization and pass the configuration to the adapter for initialization. Message platform adapters are complex to implement, so it is recommended to refer to existing implementations.
### Conversation History Message Truncator
Add a new conversation history message truncator that truncates historical messages before sending them to the model.
- Base Class: `pkg.pipeline.msgtrun.truncator.Truncator`
- Decorator: `pkg.pipeline.msgtrun.truncator.truncator_class(name: str)`
- Reference Implementation: `pkg.pipeline.msgtrun.truncators/`
- Usage: Set the `method` field in the `msg-truncate` section of `data/config/pipeline.json` to the name of the newly added truncator.
### Chat Request Runner
Add a new chat message runner. The default is local-agent, which provides basic Prompt composition, Agent orchestration, and multi-turn requests. If you need to integrate a knowledge base or local RAG, implement it here.
- Base Class: `pkg.provider.runner.RequesterRunner`
- Decorator: `pkg.provider.runner.runner_class(name: str)`
- Reference Implementation: `pkg.provider.runners/`
- Usage: Set the `runner` field in the `runner` section of `data/config/provider.json` to the name of the newly added runner.
docs/en/plugin/dev/messages.md
+82
View File
@@ -0,0 +1,82 @@
# Message Platform Entities
:::info Table of Contents
[[toc]]
:::
LangBot supports multiple message platforms, but the format of `message entities` varies across different platforms. To abstract these differences, LangBot has a unified standard. Plugin developers only need to understand and use the message entities described on this page within their plugins. LangBot's internal message processing logic will automatically handle the parsing and conversion of messages.
:::info
LangBot's message platform entities are based on a modified implementation of [YiriMirai](https://github.com/YiriMiraiProject/YiriMirai).
:::
## Message Chain
The `messages` on message platforms are different from the messages used for AI interactions. Messages on message platforms are described in the form of `message chains`. Each independent message displayed on QQ is a message chain. A message chain can contain various `message chain components` such as `text`, `images`, `@ components`, etc. For example:
![](/assets/image/plugin_dev_messages_01.png)
This is a message chain containing a Plain component ("Hello World") and an Image component ("Usagi").
The definitions of message chains and message chain components are located in `pkg/platform/types/messages.py`.
### Constructing a Message Chain
First, import the `pkg.platform.types` package to use the message components within it.
```python
from pkg.platform.types import *
# Construct a message containing the text "Hello LangBot" and an image (fetched from a URL)
msg_chain = MessageChain([
Plain("Hello LangBot"),
Image(url='https://qchatgpt.rockchin.top/langbot-logo.png')
])
# Construct a message containing an @All component and the text "Hello LangBot"
msg_chain = MessageChain([
AtAll(),
Plain("Hello LangBot")
])
# Construct a message containing an @ component for a specific member and the text "Hello LangBot"
msg_chain = MessageChain([
At(123456),
Plain("Hello LangBot")
])
```
Currently supported message chain components:
- `Source`: Source message chain information. If the message is received from a message platform, this component will be included at the beginning of the message chain, recording the message information.
- `Plain`: Plain text message.
- `Quote`: Quoted message.
- `Image`: Image message.
- `AtAll`: @All members message.
- `At`: @Specific member message.
- `Voice`: Voice message.
- Requires checking platform support.
- `Forward`: Forwarded message.
- Not supported on many platforms, not recommended for use.
- `File`: File message.
For specific usage, refer to the definitions in `pkg/platform/types/messages.py`.
## Message Platform Events
These events are different from LangBot plugin events and are part of an independent event system for message platforms. These events are the source events for LangBot plugin events and can be obtained from each `Query.message_event`.
The definitions of message platform events are located in `pkg/platform/types/events.py`.
## Other Entities
In addition to the entities mentioned above, there are entities such as `Friend` and `Group`. The definitions of these entities are located in `pkg/platform/types/entities.py`.
They are generally included in the event objects mentioned above and can be used to retrieve information not included in plugin events.
## Backward Compatibility
Plugins developed based on version 3.x can seamlessly adapt to version 3.4. However, `import mirai` is no longer supported in the new version, and the editor will report errors when developing plugins. Please make the following changes:
- Change `import mirai` to `import pkg.platform.types as mirai`
- It is not recommended to directly change it to `as mirai`. Instead, use `import pkg.platform.types as platform_types` and replace the corresponding `mirai.xxx` in the plugin code with `platform_types.xxx`.
- Change `from mirai import *` to `from pkg.platform.types import *`
docs/en/plugin/dev/tutor.md
+225
View File
@@ -0,0 +1,225 @@
# Plugin Development Tutorial
> Please read the [Plugin Introduction Page](/plugin/plugin-intro) first.
> It is recommended to read the project source code to understand the project architecture.
> For issues and feature requests, please create an issue in the repository.
> **Please try to solve the problem on your own before asking questions.**
:::info Table of Contents
[[toc]]
:::
## 💬 Introduction
This page explains the steps for developing a regular plugin. There are two methods inside a plugin: event listeners and content functions.
Event listeners can respond to certain events and modify behavior. Content functions can be called by large language models. For more details, please refer to the plugin introduction page.
LangBot also supports component extensions, allowing you to replace entire components without being limited to listening to predefined events. Please read this page and then check the **Component Extension** page for more details.
## 💻 Quick Start
Deploy this project according to the documentation and ensure it runs properly.
Use [hello_plugin](https://github.com/RockChinQ/hello_plugin) as a template to generate a plugin code repository, then clone the repository code into the `plugins` directory.
Modify the necessary parts in the plugin's README.md file.
Edit `main.py` and input the following content:
```Python
from pkg.plugin.context import register, handler, llm_func, BasePlugin, APIHost, EventContext
from pkg.plugin.events import * # Import event classes
"""
When receiving a private or group chat message "hello", reply with "hello, <sender_id>!" or "hello, everyone!"
"""
# Register the plugin
@register(name="Hello", description="hello world", version="0.1", author="RockChinQ")
class HelloPlugin(BasePlugin):
# Triggered when the plugin is loaded
def __init__(self, host: APIHost):
pass
# Asynchronous initialization
async def initialize(self):
pass
# Triggered when a private message is received
@handler(PersonNormalMessageReceived)
async def person_normal_message_received(self, ctx: EventContext):
msg = ctx.event.text_message # Here, event is the object of PersonNormalMessageReceived
if msg == "hello": # If the message is "hello"
# Output debug information
self.ap.logger.debug("hello, {}".format(ctx.event.sender_id))
# Reply with "hello, <sender_id>!"
ctx.add_return("reply", ["hello, {}!".format(ctx.event.sender_id)])
# Prevent the default behavior of this event (fetching a reply from the API)
ctx.prevent_default()
# Triggered when a group message is received
@handler(GroupNormalMessageReceived)
async def group_normal_message_received(self, ctx: EventContext):
msg = ctx.event.text_message # Here, event is the object of GroupNormalMessageReceived
if msg == "hello": # If the message is "hello"
# Output debug information
self.ap.logger.debug("hello, {}".format(ctx.event.sender_id))
# Reply with "hello, everyone!"
ctx.add_return("reply", ["hello, everyone!"])
# Prevent the default behavior of this event (fetching a reply from the API)
ctx.prevent_default()
# Triggered when the plugin is unloaded
def __del__(self):
pass
```
This plugin will implement: when a private chat receives a `hello` message, it replies with `hello, <sender QQ number>!`, and when a group chat receives a `hello` message, it replies with `hello, everyone!`.
### Interpreting This Plugin Program
- `import pkg.plugin.context` imports `register (for registering plugin classes)`, `handler (for registering event listeners)`, `llm_func (for registering content functions)`, `BasePlugin (plugin base class)`, `APIHost (API host)`, `EventContext (event context class)`, etc.
- `import pkg.plugin.events` imports all supported event classes.
- `@register` marks the class `HelloPlugin` as a plugin class, declaring the plugin name as `Hello` along with the plugin description, version, and author.
- The class `HelloPlugin` inherits from `BasePlugin`. This class can be named arbitrarily; the plugin name is only related to the parameters in the `register` call.
- The `__init__` method of this class is optional, and the code inside it will be executed when the plugin is loaded during the main program startup.
- The plugin class also supports adding an asynchronous method `async def initialize(self)` for asynchronous initialization.
- `@handler` marks the method `person_normal_message_received` as an event listener, handling the `PersonNormalMessageReceived` event (triggered when a private message is received before fetching a reply from OpenAI). This method can be named arbitrarily; the bound event is only related to the parameters in `handler`. For more supported events, please refer to the `pkg.plugin.events` file or the `API` section below.
- Debug information is output through the `self.ap.logger` logger. The `ap` object in the plugin class's parent class is the context object of the entire program, through which all objects in the program can be accessed.
- The second parameter `ctx` obtained by the event listener method is the context of this event, where `event` is the event object of this event. Relevant parameters can be extracted from it. For specific parameters that can be obtained from events, please refer to the comments of each event class in the `pkg.plugin.events` file.
- Inside the event listener method, the `text_message` parameter is extracted from the parameters, and if it is `hello`, the return value `reply` is set to `["hello, {}!".format(ctx.event.sender_id)]`. Then, the `ctx.prevent_default()` method is called to prevent the default behavior of the original program.
- For the return values supported by each event, please refer to the comments of each event in `pkg.plugin.events`.
- A similar program is used to register the `GroupNormalMessageReceived` event to handle group messages.
After saving the changes, restart the main program and send the `!plugin` command to the bot. If the `Hello` plugin appears, it means the plugin has been successfully loaded.
## ❗ Guidelines (Important)
- Each plugin should be in a separate directory for easier management. It is recommended to create a repository on GitHub to store a single plugin for easy access and updates.
- Plugin names should use `PascalCase`, such as `Hello`, `ExamplePlugin`, `ChineseCommands`, etc.
- Multiple Python program files can be stored in one directory to separate the various functions of the plugin, making it easier for developers to manage. However, it is not recommended to register multiple plugins in one directory.
- The dependencies required by the plugin should be specified in the `requirements.txt` file in the plugin directory. The program will automatically install the dependencies when fetching this plugin from the repository.
## 🪝 Content Functions
`Content functions` are implemented through [GPT's Function Calling capability](https://platform.openai.com/docs/guides/gpt/function-calling). These are functions embedded in conversations and automatically called by GPT.
> Your plugin does not necessarily need to include content functions. Please read the content function page to understand this feature first.
### Steps to Write Content Functions
1️⃣ First, follow the steps above to write the basic structure of your plugin. Now, please delete (or you can keep them for simplicity) the class functions decorated with `@handler` in the plugin content above.
<details>
<summary>Class Structure After Deletion</summary>
```python
# Register the plugin
@register(name="Hello", description="hello world", version="0.1", author="RockChinQ")
class HelloPlugin(Plugin):
# Triggered when the plugin is loaded
def __init__(self, plugin_host: APIHost):
pass
# Triggered when the plugin is unloaded
def __del__(self):
pass
```
</details>
2️⃣ Now, add the following function to the position where the functions were deleted (as a class method).
```Python
# Function to add
@llm_func(name="access_the_web") # Set the function name
async def access_web(self, query, url: str):
"""Call this function to search about the question before you answer any questions.
- Do not search through baidu.com at any time.
- If you need to search somthing, visit https://www.google.com/search?q=xxx.
- If user ask you to open a url (start with http:// or https://), visit it directly.
- Summary the plain content result by yourself, DO NOT directly output anything in the result you got.
Args:
url(str): url to visit
Returns:
str: plain text content of the web page
"""
import requests
from bs4 import BeautifulSoup
# You need to first use
# pip install beautifulsoup4
# to install the dependencies
r = requests.get(
url,
timeout=10,
headers={
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36 Edg/115.0.1901.183"
}
)
soup = BeautifulSoup(r.text, 'html.parser')
s = soup.get_text()
# Remove extra blank lines or lines with only \t and spaces
s = re.sub(r'\n\s*\n', '\n', s)
if len(s) >= 512: # Truncate the first 512 characters of the obtained webpage plain text content
return s[:512]
return s
```
#### Please Note:
- The function's comments must be written strictly according to the required format. For the specific format, please refer to [this document](https://github.com/RockChinQ/CallingGPT/wiki/1.-Function-Format#function-format).
- Content functions and `event listeners decorated with @handler` can coexist in the same plugin and are simultaneously controlled by the plugin switch in `plugins/plugins.json`.
- Ensure that the model you are using supports function calling.
3️⃣ Now your program has web access capabilities. Restart the program and ask the bot about online content or directly send an article link to request a summary.
- This is just an example. For more efficient web access capabilities, please refer to [WebwlkrPlugin](https://github.com/RockChinQ/WebwlkrPlugin).
## 📄 Terminology Explanation
### Explanation
The `ctx: EventContext` object obtained by event listener methods can be viewed in the `pkg.plugin.context` module. The `event` property of the `ctx` object is the event object of this event, from which relevant parameters can be extracted. For specific parameters that can be obtained from events, please refer to the comments of each event class in the `pkg.plugin.events` file.
Event return values are **optional** and can be submitted by calling `ctx.add_return(key: str, ret)`.
### Events
If an event is part of a request (user sending a message), its event object will contain a `query` object, which includes the context data of this request (the process of handling a user sending a message, where one request process may trigger multiple events).
For all supported events, please refer to the comments of each event class in the `pkg.plugin.events` file.
For `message chain components`, please refer to [Message Platform Entities](./messages).
### BasePlugin Structure
#### self.ap
Accessing `self.ap` in plugin methods refers to the object of the `pkg.core.app.Application` class, which contains the context object of the entire program. All objects in the program can be accessed through this object.
#### self.host
Accessing `self.host` in plugin methods refers to the object of the `pkg.plugin.context.APIHost` class, which provides some APIs of the main program. For more details, please refer to its source code.
### API Reference
For the APIs that plugins can call, please refer to the [API Reference](./api-ref).