147 lines
3.9 KiB
Markdown
147 lines
3.9 KiB
Markdown
# OneBot Chatbot Framework
|
||
|
||
该项目是一个基于OneBot标准的聊天机器人后端框架，采用高度可扩展的插件架构设计，支持消息的模块化处理和插件热加载。
|
||
|
||
## 项目特点
|
||
|
||
- **模块化设计**：每个功能作为独立插件实现，易于扩展和维护
|
||
- **插件生命周期管理**：支持插件加载、注册、依赖处理和实例管理
|
||
- **消息处理管道**：分阶段处理消息，支持各阶段拦截机制
|
||
- **会话管理**：支持群组消息和私聊消息的独立管理
|
||
- **内嵌依赖处理**：自动管理插件内嵌的Python依赖包
|
||
- **兼容性设计**：支持新旧版本插件并存运行
|
||
|
||
## 核心组件
|
||
|
||
### 消息处理流程 (`process_message`)
|
||
|
||
```python
|
||
def process_message(uid: str, gid: str | None, message: str) -> str:
|
||
# 1. 创建消息上下文
|
||
ctx = MessageContext(...)
|
||
|
||
# 2. 扫描并加载插件
|
||
plugin_manager.scan_plugins()
|
||
|
||
# 3. 消息处理阶段：
|
||
# - before_load: 加载数据前拦截点
|
||
# - after_load: 加载数据后处理点
|
||
# - after_save: 保存数据后处理点
|
||
|
||
# 4. 会话数据持久化
|
||
ctx.chat_manager.save_message(...)
|
||
|
||
return ctx.response or "ok"
|
||
```
|
||
|
||
### 插件管理器 (`PluginManager`)
|
||
|
||
```python
|
||
class PluginManager:
|
||
def __init__(self):
|
||
self._plugins = {} # 插件类注册表
|
||
self._active_instances = {} # 插件实例
|
||
self._hook_registry = {} # 兼容旧版钩子
|
||
self._temp_dirs = [] # 临时目录
|
||
self._dependency_manager = DependencyManager() # 依赖处理器
|
||
|
||
def scan_plugins(self):
|
||
"""扫描插件目录并加载ZIP格式插件"""
|
||
|
||
def load_plugin(self, zip_path: str) -> bool:
|
||
"""动态加载ZIP格式插件"""
|
||
|
||
def _load_embedded_dependencies(self, plugin_dir: str) -> bool:
|
||
"""加载插件内嵌的依赖包"""
|
||
|
||
def register_hook(self, hook_name: str):
|
||
"""注册兼容旧版钩子（装饰器模式）"""
|
||
|
||
def cleanup(self):
|
||
"""清理临时资源"""
|
||
```
|
||
|
||
## 插件开发指南
|
||
|
||
### 基本插件结构
|
||
|
||
```python
|
||
# process.py
|
||
from src.modules.plugin_modules import BasePlugin, MessageContext
|
||
|
||
class MyPlugin(BasePlugin):
|
||
def __init__(self, ctx: MessageContext):
|
||
super().__init__(ctx)
|
||
|
||
def process(self) -> str | None:
|
||
"""核心处理方法"""
|
||
if self.ctx.command == "help":
|
||
return self._show_help()
|
||
|
||
def before_load(self) -> str | None:
|
||
"""数据加载前拦截点"""
|
||
|
||
def after_load(self) -> str | None:
|
||
"""数据加载后处理点"""
|
||
|
||
def after_save(self) -> str | None:
|
||
"""数据保存后处理点"""
|
||
```
|
||
|
||
### 目录结构要求
|
||
|
||
插件应以ZIP格式打包，包含以下内容：
|
||
|
||
```
|
||
my_plugin.zip
|
||
├── process.py # 必需 - 插件入口文件
|
||
├── requirements.txt # 可选 - 依赖声明
|
||
└── packages/ # 可选 - 内嵌依赖包
|
||
├── package1/
|
||
└── package2/
|
||
```
|
||
|
||
### 依赖声明
|
||
|
||
插件可通过两种方式声明依赖：
|
||
|
||
1. `requirements.txt` 标准格式
|
||
2. `dependencies.json` 自定义格式
|
||
|
||
```json
|
||
// dependencies.json 示例
|
||
{
|
||
"requirements": [
|
||
"requests==2.28.2",
|
||
"numpy>=1.25.0"
|
||
]
|
||
}
|
||
```
|
||
|
||
## 快速启动
|
||
|
||
1. 为启动脚本授权(linux)：
|
||
|
||
```bash
|
||
chmod +x run.sh
|
||
```
|
||
2. 修改配置文件，list_port为接收消息推送端口，send_url为消息发送地址
|
||
3. 运行启动脚本
|
||
linux下
|
||
|
||
`./run.sh`
|
||
|
||
windows下
|
||
|
||
`.\run.bat`
|
||
|
||
## 设计优势
|
||
|
||
1. **解耦设计**：插件与核心系统完全解耦
|
||
2. **安全隔离**：使用临时目录加载插件
|
||
3. **版本兼容**：内建依赖版本验证机制
|
||
4. **灵活扩展**：支持多个消息处理点
|
||
5. **新旧兼容**：支持传统钩子和现代OOP插件的共存
|
||
|
||
更多插件开发支持请访问[聊天机器人插件开发支持](https://jianfgit.xyz/jianf/chat_rebot_plugen_support)
|