feat：继续重构插件api

2025-06-10 19:16:58 +08:00
parent e5007cc8cd
commit de0bdd3766
19 changed files with 2161 additions and 682 deletions
--- a/docs/plugin_guide_overview.md
+++ b/docs/plugin_guide_overview.md
@@ -0,0 +1,155 @@
+# MaiBot 插件编写指南 - 总览
+
+## 📋 目录结构
+
+本指南分为三个部分：
+
+- **[总览](plugin_guide_overview.md)** - 插件系统架构和设计理念（当前文档）
+- **[快速开始](plugin_quick_start.md)** - 5分钟创建你的第一个插件
+- **[详细解析](plugin_detailed_guide.md)** - 深入理解各个组件和API
+
+## 🎯 插件系统概述
+
+MaiBot 采用组件化的插件系统，让开发者可以轻松扩展机器人功能。系统支持两种主要组件类型：
+
+- **Action组件** - 智能动作，基于关键词、LLM判断等条件自动触发
+- **Command组件** - 命令处理，基于正则表达式匹配用户输入的命令
+
+## 🏗️ 系统架构
+
+```
+src/
+├── plugin_system/          # 🔧 系统核心（框架代码）
+│   ├── core/               # 插件管理和注册中心
+│   ├── apis/               # 统一API接口（7大模块）
+│   ├── base/               # 插件和组件基类
+│   └── registry/           # 组件注册和查询
+└── plugins/                # 🔌 插件内容（用户代码）
+    ├── built_in/           # 内置插件
+    └── examples/           # 示例插件
+```
+
+### 核心设计理念
+
+1. **分离关注点** - 系统框架与插件内容完全分离
+2. **组件化设计** - 一个插件可包含多个Action和Command组件
+3. **统一API访问** - 通过PluginAPI统一访问所有系统功能
+4. **声明式配置** - 通过类属性声明组件行为，简化开发
+5. **类型安全** - 完整的类型定义，IDE友好
+
+## 🧩 组件类型详解
+
+### Action组件 - 智能动作
+
+Action用于实现智能交互逻辑，支持多种激活方式：
+
+- **关键词激活** - 消息包含特定关键词时触发
+- **LLM判断激活** - 使用大模型智能判断是否需要触发
+- **随机激活** - 按概率随机触发
+- **始终激活** - 每条消息都触发（谨慎使用）
+
+**适用场景：**
+- 智能问候、闲聊互动
+- 情感分析和回应
+- 内容审核和提醒
+- 数据统计和分析
+
+### Command组件 - 命令处理
+
+Command用于处理结构化的用户命令，基于正则表达式匹配：
+
+- **精确匹配** - 支持参数提取和验证
+- **灵活模式** - 正则表达式的完整威力
+- **帮助系统** - 自动生成命令帮助信息
+
+**适用场景：**
+- 功能性操作（查询、设置、管理）
+- 工具类命令（计算、转换、搜索）
+- 系统管理命令
+- 游戏和娱乐功能
+
+## 🔌 API系统概览
+
+系统提供7大API模块，涵盖插件开发的所有需求：
+
+| API模块 | 功能描述 | 主要用途 |
+|---------|----------|----------|
+| **MessageAPI** | 消息发送和交互 | 发送文本、图片、语音等消息 |
+| **LLMAPI** | 大模型调用 | 文本生成、智能判断、创意创作 |
+| **DatabaseAPI** | 数据库操作 | 存储用户数据、配置、历史记录 |
+| **ConfigAPI** | 配置访问 | 读取全局配置和用户信息 |
+| **UtilsAPI** | 工具函数 | 文件操作、时间处理、ID生成 |
+| **StreamAPI** | 流管理 | 聊天流控制和状态管理 |
+| **HearflowAPI** | 心流系统 | 与消息处理流程集成 |
+
+## 🎨 开发体验
+
+### 简化的导入接口
+
+```python
+from src.plugin_system import (
+    BasePlugin, register_plugin, BaseAction, BaseCommand,
+    ComponentInfo, ActionInfo, CommandInfo, ActionActivationType, ChatMode
+)
+```
+
+### 声明式组件定义
+
+```python
+class HelloAction(BaseAction):
+    # 🎯 直接通过类属性定义行为
+    focus_activation_type = ActionActivationType.KEYWORD
+    activation_keywords = ["你好", "hello", "hi"]
+    mode_enable = ChatMode.ALL
+    
+    async def execute(self) -> Tuple[bool, str]:
+        return True, "你好！我是MaiBot 😊"
+```
+
+### 统一的API访问
+
+```python
+class MyCommand(BaseCommand):
+    async def execute(self) -> Tuple[bool, Optional[str]]:
+        # 💡 通过self.api访问所有系统功能
+        await self.api.send_message("text", "处理中...")
+        models = self.api.get_available_models()
+        await self.api.store_user_data("key", "value")
+        return True, "完成！"
+```
+
+## 🚀 开发流程
+
+1. **创建插件目录** - 在 `src/plugins/` 下创建插件文件夹
+2. **定义插件类** - 继承 `BasePlugin`，设置基本信息
+3. **创建组件类** - 继承 `BaseAction` 或 `BaseCommand`
+4. **注册组件** - 在插件的 `get_plugin_components()` 中返回组件列表
+5. **测试验证** - 启动系统测试插件功能
+
+## 📚 学习路径建议
+
+1. **初学者** - 从[快速开始](plugin_quick_start.md)开始，5分钟体验插件开发
+2. **进阶开发** - 阅读[详细解析](plugin_detailed_guide.md)，深入理解各个组件
+3. **实战练习** - 参考 `simple_plugin` 示例，尝试开发自己的插件
+4. **API探索** - 逐步尝试各个API模块的功能
+
+## 💡 设计亮点
+
+- **零配置启动** - 插件放入目录即可自动加载
+- **热重载支持** - 开发过程中可动态重载插件（规划中）
+- **依赖管理** - 支持插件间依赖关系声明
+- **配置系统** - 支持TOML配置文件，灵活可定制
+- **完整API** - 覆盖机器人开发的各个方面
+- **类型安全** - 完整的类型注解，IDE智能提示
+
+## 🎯 下一步
+
+选择适合你的起点：
+
+- 🚀 [立即开始 →](plugin_quick_start.md) 
+- 📖 [深入学习 →](plugin_detailed_guide.md)
+- 🔍 [查看示例 →](../src/plugins/examples/simple_plugin/)
+
+---
+
+> 💡 **提示**: 插件系统仍在持续改进中，欢迎提出建议和反馈！