feat：继续重构插件api
This commit is contained in:
SengokuCola
752
docs/plugin_detailed_guide.md
Normal file
752
docs/plugin_detailed_guide.md
Normal file
@@ -0,0 +1,752 @@
|
||||
# MaiBot 插件详细解析指南
|
||||
|
||||
## 📋 目录
|
||||
|
||||
1. [插件基类详解](#插件基类详解)
|
||||
2. [Action组件深入](#action组件深入)
|
||||
3. [Command组件深入](#command组件深入)
|
||||
4. [API系统详解](#api系统详解)
|
||||
5. [配置系统](#配置系统)
|
||||
6. [注册中心机制](#注册中心机制)
|
||||
7. [高级功能](#高级功能)
|
||||
8. [最佳实践](#最佳实践)
|
||||
|
||||
---
|
||||
|
||||
## 插件基类详解
|
||||
|
||||
### BasePlugin 核心功能
|
||||
|
||||
`BasePlugin` 是所有插件的基类，提供插件的生命周期管理和基础功能。
|
||||
|
||||
```python
|
||||
@register_plugin
|
||||
class MyPlugin(BasePlugin):
|
||||
# 必需的基本信息
|
||||
plugin_name = "my_plugin" # 插件唯一标识
|
||||
plugin_description = "插件功能描述" # 简短描述
|
||||
plugin_version = "1.0.0" # 版本号
|
||||
plugin_author = "作者名称" # 作者信息
|
||||
enable_plugin = True # 是否启用
|
||||
|
||||
# 可选配置
|
||||
dependencies = ["other_plugin"] # 依赖的其他插件
|
||||
config_file_name = "config.toml" # 配置文件名
|
||||
|
||||
def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
|
||||
"""返回插件包含的组件列表（必须实现）"""
|
||||
return [
|
||||
(MyAction.get_action_info(), MyAction),
|
||||
(MyCommand.get_command_info(), MyCommand)
|
||||
]
|
||||
```
|
||||
|
||||
### 插件生命周期
|
||||
|
||||
1. **加载阶段** - 插件管理器扫描插件目录
|
||||
2. **实例化阶段** - 创建插件实例，传入 `plugin_dir`
|
||||
3. **配置加载** - 自动加载配置文件（如果指定）
|
||||
4. **依赖检查** - 验证依赖的插件是否存在
|
||||
5. **组件注册** - 注册所有组件到注册中心
|
||||
6. **运行阶段** - 组件响应用户交互
|
||||
|
||||
### 配置访问
|
||||
|
||||
```python
|
||||
class MyPlugin(BasePlugin):
|
||||
config_file_name = "config.toml"
|
||||
|
||||
def some_method(self):
|
||||
# 获取配置值
|
||||
max_retry = self.get_config("network.max_retry", 3)
|
||||
api_key = self.get_config("api.key", "")
|
||||
|
||||
# 配置支持嵌套结构
|
||||
db_config = self.get_config("database", {})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Action组件深入
|
||||
|
||||
### Action激活机制
|
||||
|
||||
Action组件支持多种激活方式，可以组合使用：
|
||||
|
||||
#### 1. 关键词激活
|
||||
|
||||
```python
|
||||
class KeywordAction(BaseAction):
|
||||
focus_activation_type = ActionActivationType.KEYWORD
|
||||
normal_activation_type = ActionActivationType.KEYWORD
|
||||
activation_keywords = ["天气", "weather", "温度"]
|
||||
keyword_case_sensitive = False # 是否区分大小写
|
||||
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
# 获取触发的关键词
|
||||
triggered_keyword = self.action_data.get("triggered_keyword")
|
||||
return True, f"检测到关键词: {triggered_keyword}"
|
||||
```
|
||||
|
||||
#### 2. LLM智能判断
|
||||
|
||||
```python
|
||||
class SmartAction(BaseAction):
|
||||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||||
llm_judge_prompt = """
|
||||
判断用户消息是否表达了情感支持的需求。
|
||||
如果用户显得沮丧、焦虑或需要安慰，返回True，否则返回False。
|
||||
"""
|
||||
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
# LLM判断为需要情感支持
|
||||
user_emotion = self.action_data.get("emotion", "neutral")
|
||||
return True, "我理解你现在的感受，有什么可以帮助你的吗？ 🤗"
|
||||
```
|
||||
|
||||
#### 3. 随机激活
|
||||
|
||||
```python
|
||||
class RandomAction(BaseAction):
|
||||
focus_activation_type = ActionActivationType.RANDOM
|
||||
random_activation_probability = 0.1 # 10%概率触发
|
||||
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
import random
|
||||
responses = ["今天天气不错呢！", "你知道吗，刚才想到一个有趣的事...", "随便聊聊吧！"]
|
||||
return True, random.choice(responses)
|
||||
```
|
||||
|
||||
#### 4. 始终激活
|
||||
|
||||
```python
|
||||
class AlwaysAction(BaseAction):
|
||||
focus_activation_type = ActionActivationType.ALWAYS
|
||||
parallel_action = True # 允许与其他Action并行
|
||||
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
# 记录所有消息到数据库
|
||||
await self.api.store_user_data("last_message", self.action_data.get("message"))
|
||||
return True, "" # 静默执行，不发送回复
|
||||
```
|
||||
|
||||
### Action数据访问
|
||||
|
||||
```python
|
||||
class DataAction(BaseAction):
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
# 访问消息数据
|
||||
message = self.action_data.get("message", "")
|
||||
username = self.action_data.get("username", "用户")
|
||||
user_id = self.action_data.get("user_id", "")
|
||||
platform = self.action_data.get("platform", "")
|
||||
|
||||
# 访问系统数据
|
||||
thinking_id = self.thinking_id
|
||||
reasoning = self.reasoning # 执行该动作的理由
|
||||
|
||||
# 访问计时器信息
|
||||
timers = self.cycle_timers
|
||||
|
||||
return True, f"处理来自 {platform} 的用户 {username} 的消息"
|
||||
```
|
||||
|
||||
### 聊天模式支持
|
||||
|
||||
```python
|
||||
class ModeAwareAction(BaseAction):
|
||||
mode_enable = ChatMode.PRIVATE # 只在私聊中启用
|
||||
# mode_enable = ChatMode.GROUP # 只在群聊中启用
|
||||
# mode_enable = ChatMode.ALL # 在所有模式中启用
|
||||
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
current_mode = self.action_data.get("chat_mode", ChatMode.PRIVATE)
|
||||
return True, f"当前聊天模式: {current_mode.name}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Command组件深入
|
||||
|
||||
### 高级正则表达式模式
|
||||
|
||||
Command使用正则表达式进行精确匹配，支持复杂的参数提取：
|
||||
|
||||
#### 1. 基础命令
|
||||
|
||||
```python
|
||||
class BasicCommand(BaseCommand):
|
||||
command_pattern = r"^/hello$"
|
||||
command_help = "简单的问候命令"
|
||||
|
||||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||||
await self.send_reply("Hello!")
|
||||
return True, "Hello!"
|
||||
```
|
||||
|
||||
#### 2. 带参数命令
|
||||
|
||||
```python
|
||||
class ParameterCommand(BaseCommand):
|
||||
command_pattern = r"^/user\s+(?P<action>add|remove|list)\s+(?P<name>\w+)?$"
|
||||
command_help = "用户管理命令，用法：/user <add|remove|list> [用户名]"
|
||||
command_examples = ["/user add alice", "/user remove bob", "/user list"]
|
||||
|
||||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||||
action = self.matched_groups.get("action")
|
||||
name = self.matched_groups.get("name")
|
||||
|
||||
if action == "add" and name:
|
||||
# 添加用户逻辑
|
||||
await self.api.store_user_data(f"user_{name}", {"name": name, "created": self.api.get_current_time()})
|
||||
response = f"用户 {name} 已添加"
|
||||
elif action == "remove" and name:
|
||||
# 删除用户逻辑
|
||||
await self.api.delete_user_data(f"user_{name}")
|
||||
response = f"用户 {name} 已删除"
|
||||
elif action == "list":
|
||||
# 列出用户逻辑
|
||||
users = await self.api.get_user_data_pattern("user_*")
|
||||
response = f"用户列表: {', '.join(users.keys())}"
|
||||
else:
|
||||
response = "参数错误，请查看帮助信息"
|
||||
|
||||
await self.send_reply(response)
|
||||
return True, response
|
||||
```
|
||||
|
||||
#### 3. 复杂参数解析
|
||||
|
||||
```python
|
||||
class AdvancedCommand(BaseCommand):
|
||||
command_pattern = r"^/remind\s+(?P<time>\d{1,2}:\d{2})\s+(?P<date>\d{4}-\d{2}-\d{2})?\s+(?P<message>.+)$"
|
||||
command_help = "设置提醒，用法：/remind <时间> [日期] <消息>"
|
||||
command_examples = [
|
||||
"/remind 14:30 买牛奶",
|
||||
"/remind 09:00 2024-12-25 圣诞节快乐"
|
||||
]
|
||||
|
||||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||||
time_str = self.matched_groups.get("time")
|
||||
date_str = self.matched_groups.get("date")
|
||||
message = self.matched_groups.get("message")
|
||||
|
||||
# 解析时间
|
||||
from datetime import datetime, date
|
||||
try:
|
||||
hour, minute = map(int, time_str.split(":"))
|
||||
if date_str:
|
||||
reminder_date = datetime.strptime(date_str, "%Y-%m-%d").date()
|
||||
else:
|
||||
reminder_date = date.today()
|
||||
|
||||
# 创建提醒
|
||||
reminder_time = datetime.combine(reminder_date, datetime.min.time().replace(hour=hour, minute=minute))
|
||||
|
||||
await self.api.store_user_data("reminder", {
|
||||
"time": reminder_time.isoformat(),
|
||||
"message": message,
|
||||
"user_id": self.api.get_current_user_id()
|
||||
})
|
||||
|
||||
response = f"已设置提醒：{reminder_time.strftime('%Y-%m-%d %H:%M')} - {message}"
|
||||
|
||||
except ValueError as e:
|
||||
response = f"时间格式错误: {e}"
|
||||
|
||||
await self.send_reply(response)
|
||||
return True, response
|
||||
```
|
||||
|
||||
### 命令权限控制
|
||||
|
||||
```python
|
||||
class AdminCommand(BaseCommand):
|
||||
command_pattern = r"^/admin\s+(?P<operation>\w+)"
|
||||
command_help = "管理员命令（需要权限）"
|
||||
|
||||
async def execute(self) -> Tuple[bool, Optional[str]]:
|
||||
# 检查用户权限
|
||||
user_id = self.api.get_current_user_id()
|
||||
user_role = await self.api.get_user_info(user_id, "role", "user")
|
||||
|
||||
if user_role != "admin":
|
||||
await self.send_reply("❌ 权限不足，需要管理员权限")
|
||||
return False, "权限不足"
|
||||
|
||||
operation = self.matched_groups.get("operation")
|
||||
# 执行管理员操作...
|
||||
|
||||
return True, f"管理员操作 {operation} 已执行"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API系统详解
|
||||
|
||||
### MessageAPI - 消息发送
|
||||
|
||||
```python
|
||||
class MessageExampleAction(BaseAction):
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
# 发送文本消息
|
||||
await self.api.send_message("text", "这是一条文本消息")
|
||||
|
||||
# 发送带格式的消息
|
||||
await self.api.send_message("text", "**粗体文本** *斜体文本*")
|
||||
|
||||
# 发送图片（如果支持）
|
||||
await self.api.send_message("image", "/path/to/image.jpg")
|
||||
|
||||
# 发送文件（如果支持）
|
||||
await self.api.send_message("file", "/path/to/document.pdf")
|
||||
|
||||
# 获取消息发送状态
|
||||
success = await self.api.send_message("text", "测试消息")
|
||||
if success:
|
||||
logger.info("消息发送成功")
|
||||
|
||||
return True, "消息发送演示完成"
|
||||
```
|
||||
|
||||
### LLMAPI - 大模型调用
|
||||
|
||||
```python
|
||||
class LLMExampleAction(BaseAction):
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
# 获取可用模型
|
||||
models = self.api.get_available_models()
|
||||
|
||||
if not models:
|
||||
return False, "没有可用的模型"
|
||||
|
||||
# 选择第一个可用模型
|
||||
model_name, model_config = next(iter(models.items()))
|
||||
|
||||
# 生成文本
|
||||
prompt = "写一首关于春天的诗"
|
||||
success, response, usage, model_used = await self.api.generate_with_model(
|
||||
prompt=prompt,
|
||||
model_config=model_config,
|
||||
max_tokens=200,
|
||||
temperature=0.7
|
||||
)
|
||||
|
||||
if success:
|
||||
logger.info(f"使用模型 {model_used} 生成了 {usage.get('total_tokens', 0)} 个token")
|
||||
return True, f"生成的诗歌：\n{response}"
|
||||
else:
|
||||
return False, f"生成失败：{response}"
|
||||
```
|
||||
|
||||
### DatabaseAPI - 数据库操作
|
||||
|
||||
```python
|
||||
class DatabaseExampleAction(BaseAction):
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
user_id = self.api.get_current_user_id()
|
||||
|
||||
# 存储用户数据
|
||||
await self.api.store_user_data("user_score", 100)
|
||||
await self.api.store_user_data("user_level", "beginner")
|
||||
|
||||
# 存储复杂数据结构
|
||||
user_profile = {
|
||||
"name": "Alice",
|
||||
"age": 25,
|
||||
"interests": ["music", "reading", "coding"],
|
||||
"settings": {
|
||||
"theme": "dark",
|
||||
"language": "zh-CN"
|
||||
}
|
||||
}
|
||||
await self.api.store_user_data("profile", user_profile)
|
||||
|
||||
# 读取数据
|
||||
score = await self.api.get_user_data("user_score", 0)
|
||||
profile = await self.api.get_user_data("profile", {})
|
||||
|
||||
# 删除数据
|
||||
await self.api.delete_user_data("old_key")
|
||||
|
||||
# 批量查询
|
||||
all_user_data = await self.api.get_user_data_pattern("user_*")
|
||||
|
||||
# 存储Action执行记录
|
||||
await self.api.store_action_info(
|
||||
action_build_into_prompt=True,
|
||||
action_prompt_display="用户查询了个人信息",
|
||||
action_done=True
|
||||
)
|
||||
|
||||
return True, f"用户数据操作完成，当前积分：{score}"
|
||||
```
|
||||
|
||||
### ConfigAPI - 配置访问
|
||||
|
||||
```python
|
||||
class ConfigExampleAction(BaseAction):
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
# 读取全局配置
|
||||
bot_name = self.api.get_global_config("bot.name", "MaiBot")
|
||||
debug_mode = self.api.get_global_config("system.debug", False)
|
||||
|
||||
# 获取用户信息
|
||||
current_user = self.api.get_current_user_id()
|
||||
platform, user_id = await self.api.get_user_id_by_person_name("Alice")
|
||||
|
||||
# 获取特定用户信息
|
||||
user_nickname = await self.api.get_person_info(current_user, "nickname", "未知用户")
|
||||
user_language = await self.api.get_person_info(current_user, "language", "zh-CN")
|
||||
|
||||
return True, f"配置信息获取完成，机器人名称：{bot_name}"
|
||||
```
|
||||
|
||||
### UtilsAPI - 工具函数
|
||||
|
||||
```python
|
||||
class UtilsExampleAction(BaseAction):
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
# 时间相关
|
||||
current_time = self.api.get_current_time()
|
||||
formatted_time = self.api.format_time(current_time, "%Y-%m-%d %H:%M:%S")
|
||||
|
||||
# ID生成
|
||||
unique_id = self.api.generate_unique_id()
|
||||
random_string = self.api.generate_random_string(length=8)
|
||||
|
||||
# 文件操作
|
||||
if self.api.file_exists("/path/to/file.txt"):
|
||||
content = self.api.read_file("/path/to/file.txt")
|
||||
self.api.write_file("/path/to/backup.txt", content)
|
||||
|
||||
# JSON处理
|
||||
data = {"key": "value", "number": 42}
|
||||
json_str = self.api.to_json(data)
|
||||
parsed_data = self.api.from_json(json_str)
|
||||
|
||||
# 安全字符串处理
|
||||
safe_filename = self.api.sanitize_filename("用户文件 (1).txt")
|
||||
|
||||
return True, f"工具函数演示完成，时间：{formatted_time}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置系统
|
||||
|
||||
### TOML配置文件
|
||||
|
||||
```toml
|
||||
# config.toml
|
||||
|
||||
[plugin]
|
||||
name = "my_plugin"
|
||||
description = "插件描述"
|
||||
enabled = true
|
||||
debug = false
|
||||
|
||||
[features]
|
||||
enable_ai = true
|
||||
enable_voice = false
|
||||
max_users = 100
|
||||
|
||||
[api]
|
||||
timeout = 30
|
||||
retry_count = 3
|
||||
base_url = "https://api.example.com"
|
||||
|
||||
[database]
|
||||
cache_size = 1000
|
||||
auto_cleanup = true
|
||||
|
||||
[messages]
|
||||
welcome = "欢迎使用插件！"
|
||||
error = "操作失败，请重试"
|
||||
success = "操作成功完成"
|
||||
|
||||
[advanced]
|
||||
custom_settings = { theme = "dark", language = "zh-CN" }
|
||||
feature_flags = ["beta_feature", "experimental_ui"]
|
||||
```
|
||||
|
||||
### 配置使用示例
|
||||
|
||||
```python
|
||||
class ConfigurablePlugin(BasePlugin):
|
||||
config_file_name = "config.toml"
|
||||
|
||||
def get_plugin_components(self):
|
||||
# 根据配置决定加载哪些组件
|
||||
components = []
|
||||
|
||||
if self.get_config("features.enable_ai", False):
|
||||
components.append((AIAction.get_action_info(), AIAction))
|
||||
|
||||
if self.get_config("features.enable_voice", False):
|
||||
components.append((VoiceCommand.get_command_info(), VoiceCommand))
|
||||
|
||||
return components
|
||||
|
||||
class ConfigurableAction(BaseAction):
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
# 注意：这里不能直接创建插件实例获取配置
|
||||
# 应该通过其他方式访问配置，比如从API或全局配置中获取
|
||||
|
||||
# 使用默认值或硬编码配置
|
||||
welcome_message = "欢迎使用插件！" # 应该从配置获取
|
||||
timeout = 30 # 应该从配置获取
|
||||
|
||||
return True, welcome_message
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注册中心机制
|
||||
|
||||
### 组件查询
|
||||
|
||||
```python
|
||||
from src.plugin_system.core.component_registry import component_registry
|
||||
|
||||
# 获取所有注册的Action
|
||||
actions = component_registry.get_components_by_type(ComponentType.ACTION)
|
||||
|
||||
# 获取所有注册的Command
|
||||
commands = component_registry.get_components_by_type(ComponentType.COMMAND)
|
||||
|
||||
# 查找特定命令
|
||||
command_info = component_registry.find_command_by_text("/help")
|
||||
|
||||
# 获取插件信息
|
||||
plugin_info = component_registry.get_plugin_info("simple_plugin")
|
||||
|
||||
# 获取插件的所有组件
|
||||
plugin_components = component_registry.get_plugin_components("simple_plugin")
|
||||
```
|
||||
|
||||
### 动态组件操作
|
||||
|
||||
```python
|
||||
# 注册新组件
|
||||
component_info = ActionInfo(name="dynamic_action", ...)
|
||||
component_registry.register_component(component_info, DynamicAction)
|
||||
|
||||
# 注销组件
|
||||
component_registry.unregister_component("dynamic_action")
|
||||
|
||||
# 检查组件是否存在
|
||||
exists = component_registry.component_exists("my_action")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 高级功能
|
||||
|
||||
### 组件依赖管理
|
||||
|
||||
```python
|
||||
class DependentPlugin(BasePlugin):
|
||||
plugin_name = "dependent_plugin"
|
||||
dependencies = ["simple_plugin", "core_plugin"] # 依赖其他插件
|
||||
|
||||
def get_plugin_components(self):
|
||||
# 只有在依赖满足时才会被调用
|
||||
return [(MyAction.get_action_info(), MyAction)]
|
||||
```
|
||||
|
||||
### 动态组件创建
|
||||
|
||||
```python
|
||||
def create_dynamic_action(keyword: str, response: str):
|
||||
"""动态创建Action组件"""
|
||||
|
||||
class DynamicAction(BaseAction):
|
||||
focus_activation_type = ActionActivationType.KEYWORD
|
||||
activation_keywords = [keyword]
|
||||
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
return True, response
|
||||
|
||||
return DynamicAction
|
||||
|
||||
# 使用
|
||||
WeatherAction = create_dynamic_action("天气", "今天天气很好！")
|
||||
```
|
||||
|
||||
### 组件生命周期钩子
|
||||
|
||||
```python
|
||||
class LifecycleAction(BaseAction):
|
||||
def __init__(self, *args, **kwargs):
|
||||
super().__init__(*args, **kwargs)
|
||||
self.on_initialize()
|
||||
|
||||
def on_initialize(self):
|
||||
"""组件初始化时调用"""
|
||||
logger.info("Action组件初始化")
|
||||
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
result = await self.on_execute()
|
||||
self.on_complete()
|
||||
return result
|
||||
|
||||
async def on_execute(self) -> Tuple[bool, str]:
|
||||
"""实际执行逻辑"""
|
||||
return True, "执行完成"
|
||||
|
||||
def on_complete(self):
|
||||
"""执行完成后调用"""
|
||||
logger.info("Action执行完成")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 错误处理
|
||||
|
||||
```python
|
||||
class RobustAction(BaseAction):
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
try:
|
||||
# 主要逻辑
|
||||
result = await self.process_main_logic()
|
||||
return True, result
|
||||
|
||||
except ValueError as e:
|
||||
# 参数错误
|
||||
logger.warning(f"参数错误: {e}")
|
||||
return False, "参数格式不正确"
|
||||
|
||||
except ConnectionError as e:
|
||||
# 网络错误
|
||||
logger.error(f"网络连接失败: {e}")
|
||||
return False, "网络连接异常，请稍后重试"
|
||||
|
||||
except Exception as e:
|
||||
# 未知错误
|
||||
logger.error(f"未知错误: {e}", exc_info=True)
|
||||
return False, "处理失败，请联系管理员"
|
||||
|
||||
async def process_main_logic(self):
|
||||
# 具体业务逻辑
|
||||
pass
|
||||
```
|
||||
|
||||
### 2. 性能优化
|
||||
|
||||
```python
|
||||
class OptimizedAction(BaseAction):
|
||||
def __init__(self, *args, **kwargs):
|
||||
super().__init__(*args, **kwargs)
|
||||
self._cache = {} # 本地缓存
|
||||
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
cache_key = self.generate_cache_key()
|
||||
|
||||
# 检查缓存
|
||||
if cache_key in self._cache:
|
||||
logger.debug("使用缓存结果")
|
||||
return True, self._cache[cache_key]
|
||||
|
||||
# 计算结果
|
||||
result = await self.compute_result()
|
||||
|
||||
# 存储到缓存
|
||||
self._cache[cache_key] = result
|
||||
|
||||
return True, result
|
||||
|
||||
def generate_cache_key(self) -> str:
|
||||
# 根据输入生成缓存键
|
||||
message = self.action_data.get("message", "")
|
||||
return f"result_{hash(message)}"
|
||||
```
|
||||
|
||||
### 3. 资源管理
|
||||
|
||||
```python
|
||||
class ResourceAction(BaseAction):
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
# 使用上下文管理器确保资源正确释放
|
||||
async with self.api.get_resource_manager() as resources:
|
||||
# 获取资源
|
||||
db_connection = await resources.get_database()
|
||||
file_handle = await resources.get_file("data.txt")
|
||||
|
||||
# 使用资源进行处理
|
||||
result = await self.process_with_resources(db_connection, file_handle)
|
||||
|
||||
return True, result
|
||||
# 资源会自动释放
|
||||
```
|
||||
|
||||
### 4. 测试友好设计
|
||||
|
||||
```python
|
||||
class TestableAction(BaseAction):
|
||||
def __init__(self, *args, **kwargs):
|
||||
super().__init__(*args, **kwargs)
|
||||
self.dependencies = self.create_dependencies()
|
||||
|
||||
def create_dependencies(self):
|
||||
"""创建依赖对象，便于测试时注入mock"""
|
||||
return {
|
||||
'weather_service': WeatherService(),
|
||||
'user_service': UserService()
|
||||
}
|
||||
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
weather = await self.dependencies['weather_service'].get_weather()
|
||||
user = await self.dependencies['user_service'].get_current_user()
|
||||
|
||||
return True, f"今天{weather}，{user}！"
|
||||
```
|
||||
|
||||
### 5. 日志记录
|
||||
|
||||
```python
|
||||
class LoggedAction(BaseAction):
|
||||
async def execute(self) -> Tuple[bool, str]:
|
||||
start_time = self.api.get_current_time()
|
||||
|
||||
logger.info(f"{self.log_prefix} 开始执行，用户: {self.action_data.get('username')}")
|
||||
|
||||
try:
|
||||
result = await self.process()
|
||||
|
||||
duration = self.api.get_current_time() - start_time
|
||||
logger.info(f"{self.log_prefix} 执行成功，耗时: {duration}ms")
|
||||
|
||||
return True, result
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"{self.log_prefix} 执行失败: {e}", exc_info=True)
|
||||
raise
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
通过本详细指南，你已经深入了解了MaiBot插件系统的各个方面：
|
||||
|
||||
- **插件基类** - 生命周期管理和配置系统
|
||||
- **Action组件** - 多种激活机制和智能交互
|
||||
- **Command组件** - 强大的正则表达式匹配和参数处理
|
||||
- **API系统** - 7大模块提供完整功能支持
|
||||
- **高级功能** - 依赖管理、动态创建、生命周期钩子
|
||||
- **最佳实践** - 错误处理、性能优化、资源管理
|
||||
|
||||
现在你已经具备了开发复杂插件的所有知识！
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- [系统总览](plugin_guide_overview.md) - 了解整体架构
|
||||
- [快速开始](plugin_quick_start.md) - 5分钟创建第一个插件
|
||||
- [示例插件](../src/plugins/examples/simple_plugin/) - 完整功能参考
|
||||
|
||||
---
|
||||
|
||||
> 💡 **持续学习**: 插件开发是一个实践的过程，建议边学边做，逐步掌握各种高级特性！
|
||||
Reference in New Issue
Block a user