# 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)