feat：重构插件api

src/plugins/README.md

@@ -0,0 +1,206 @@
+# MaiBot 插件系统架构
+
+## 概述
+
+MaiBot 插件系统采用组件化设计，支持插件包含多种组件类型：
+- **Action组件**：处理聊天中的动作逻辑
+- **Command组件**：处理命令请求
+- **未来扩展**：Scheduler（定时任务）、Listener（事件监听）等
+
+## 目录结构
+
+```
+src/plugins/
+├── core/                          # 插件核心管理
+│   ├── plugin_manager.py          # 插件管理器
+│   ├── plugin_loader.py           # 插件加载器（预留）
+│   └── component_registry.py      # 组件注册中心
+├── apis/                          # API模块
+│   ├── plugin_api.py              # 统一API聚合
+│   ├── message_api.py             # 消息API
+│   ├── llm_api.py                 # LLM API
+│   ├── database_api.py            # 数据库API
+│   ├── config_api.py              # 配置API
+│   ├── utils_api.py               # 工具API
+│   ├── stream_api.py              # 流API
+│   └── hearflow_api.py            # 心流API
+├── base/                          # 基础类
+│   ├── base_plugin.py             # 插件基类
+│   ├── base_action.py             # Action组件基类
+│   ├── base_command.py            # Command组件基类
+│   └── component_types.py         # 组件类型定义
+├── built_in/                      # 内置组件
+│   ├── actions/                   # 内置Action
+│   └── commands/                  # 内置Command
+└── examples/                      # 示例插件
+    └── simple_plugin/             # 简单插件示例
+        ├── plugin.py
+        └── config.toml
+```
+
+## 核心特性
+
+### 1. 组件化设计
+- 插件可以包含多种组件类型
+- 每种组件有明确的职责和接口
+- 支持组件的独立启用/禁用
+
+### 2. 统一的API访问
+- 所有插件组件通过 `PluginAPI` 访问系统功能
+- 包含消息发送、数据库操作、LLM调用等
+- 提供统一的错误处理和日志记录
+
+### 3. 灵活的配置系统
+- 支持 TOML 格式的配置文件
+- 插件可以读取自定义配置
+- 支持全局配置和插件特定配置
+
+### 4. 统一的注册管理
+- 组件注册中心管理所有组件
+- 支持组件的动态启用/禁用
+- 提供丰富的查询和统计接口
+
+## 插件开发指南
+
+### 创建基本插件
+
+```python
+from src.plugins.base.base_plugin import BasePlugin, register_plugin
+from src.plugins.base.base_action import BaseAction
+from src.plugins.base.component_types import ActionInfo, ActionActivationType
+
+class MyAction(BaseAction):
+    async def execute(self) -> tuple[bool, str]:
+        # 使用API发送消息
+        response = "Hello from my plugin!"
+        return True, response
+
+@register_plugin
+class MyPlugin(BasePlugin):
+    plugin_name = "my_plugin"
+    plugin_description = "我的第一个插件"
+    
+    def get_plugin_components(self):
+        action_info = ActionInfo(
+            name="my_action",
+            description="我的动作",
+            activation_keywords=["hello"]
+        )
+        return [(action_info, MyAction)]
+```
+
+### 创建命令组件
+
+```python
+from src.plugins.base.base_command import BaseCommand
+from src.plugins.base.component_types import CommandInfo
+
+class MyCommand(BaseCommand):
+    async def execute(self) -> tuple[bool, str]:
+        # 获取命令参数
+        param = self.matched_groups.get("param", "")
+        
+        # 发送回复
+        await self.send_reply(f"收到参数: {param}")
+        return True, f"处理完成: {param}"
+
+# 在插件中注册
+def get_plugin_components(self):
+    command_info = CommandInfo(
+        name="my_command",
+        description="我的命令",
+        command_pattern=r"^/mycmd\s+(?P<param>\w+)$",
+        command_help="用法：/mycmd <参数>"
+    )
+    return [(command_info, MyCommand)]
+```
+
+### 使用配置文件
+
+```toml
+# config.toml
+[plugin]
+name = "my_plugin"
+enabled = true
+
+[my_settings]
+max_items = 10
+default_message = "Hello World"
+```
+
+```python
+class MyPlugin(BasePlugin):
+    config_file_name = "config.toml"
+    
+    def get_plugin_components(self):
+        # 读取配置
+        max_items = self.get_config("my_settings.max_items", 5)
+        message = self.get_config("my_settings.default_message", "Hi")
+        
+        # 使用配置创建组件...
+```
+
+## API使用示例
+
+### 消息操作
+```python
+# 发送文本消息
+await self.api.send_text_to_group(chat_stream, "Hello!")
+
+# 发送图片
+await self.api.send_image_to_group(chat_stream, image_path)
+```
+
+### 数据库操作
+```python
+# 查询数据
+data = await self.api.db_get("table_name", "key")
+
+# 保存数据
+await self.api.db_set("table_name", "key", "value")
+```
+
+### LLM调用
+```python
+# 生成文本
+response = await self.api.llm_text_request("你好，请介绍一下自己")
+
+# 生成图片
+image_url = await self.api.llm_image_request("一只可爱的猫咪")
+```
+
+## 内置组件迁移
+
+现有的内置Action和Command将迁移到新架构：
+
+### Action迁移
+- `reply_action.py` → `src/plugins/built_in/actions/reply_action.py`
+- `emoji_action.py` → `src/plugins/built_in/actions/emoji_action.py`
+- `no_reply_action.py` → `src/plugins/built_in/actions/no_reply_action.py`
+
+### Command迁移
+- 现有命令系统将封装为内置Command组件
+- 保持现有的命令模式和功能
+
+## 兼容性
+
+新插件系统保持与现有系统的兼容性：
+- 现有的Action和Command继续工作
+- 提供兼容层和适配器
+- 逐步迁移到新架构
+
+## 扩展性
+
+系统设计支持未来扩展：
+- 新的组件类型（Scheduler、Listener等）
+- 插件间依赖和通信
+- 插件热重载
+- 插件市场和分发
+
+## 最佳实践
+
+1. **单一职责**：每个组件专注于特定功能
+2. **配置驱动**：通过配置文件控制行为
+3. **错误处理**：妥善处理异常情况
+4. **日志记录**：记录关键操作和错误
+5. **测试覆盖**：为插件编写单元测试