better：优化文档
This commit is contained in:
SengokuCola
@@ -9,11 +9,29 @@
|
||||
### 🎯 Action组件
|
||||
|
||||
#### SmartGreetingAction - 智能问候
|
||||
- **触发方式**: 关键词触发 (你好、hello、hi、嗨等)
|
||||
- **激活类型**:
|
||||
- Focus模式: KEYWORD (关键词激活)
|
||||
- Normal模式: KEYWORD (关键词激活)
|
||||
- **触发关键词**: 你好、hello、hi、嗨、问候、早上好、晚上好
|
||||
- **支持模式**: 所有聊天模式
|
||||
- **功能**: 智能问候，支持LLM个性化生成
|
||||
- **并行执行**: 否
|
||||
- **功能**: 智能问候，支持多种风格和LLM个性化生成
|
||||
- **参数**: username(用户名), greeting_style(问候风格)
|
||||
- **配置**: 可自定义问候模板、启用表情、LLM生成
|
||||
|
||||
#### HelpfulAction - 智能助手
|
||||
- **激活类型**:
|
||||
- Focus模式: LLM_JUDGE (LLM智能判断)
|
||||
- Normal模式: RANDOM (随机激活，概率15%)
|
||||
- **支持模式**: 所有聊天模式
|
||||
- **并行执行**: 是
|
||||
- **功能**: 主动提供帮助和建议，展示LLM判断激活机制
|
||||
- **参数**: help_type(帮助类型), topic(主题), complexity(复杂度)
|
||||
- **特点**:
|
||||
- 通过LLM智能判断是否需要提供帮助
|
||||
- 展示两层决策机制的实际应用
|
||||
- 支持多种帮助类型（解释、建议、指导、提示）
|
||||
|
||||
### 📝 Command组件
|
||||
|
||||
#### 1. ComprehensiveHelpCommand - 综合帮助系统
|
||||
@@ -94,36 +112,69 @@
|
||||
### 组件控制
|
||||
```toml
|
||||
[components]
|
||||
enable_greeting = true # 启用智能问候
|
||||
enable_help = true # 启用帮助系统
|
||||
enable_send = true # 启用消息发送
|
||||
# ... 其他组件开关
|
||||
enable_greeting = true # 启用智能问候Action
|
||||
enable_helpful = true # 启用智能助手Action
|
||||
enable_help = true # 启用帮助系统Command
|
||||
enable_send = true # 启用消息发送Command
|
||||
enable_echo = true # 启用回声Command
|
||||
enable_info = true # 启用消息信息Command
|
||||
enable_dice = true # 启用骰子Command
|
||||
```
|
||||
|
||||
### 功能配置
|
||||
### Action配置
|
||||
```toml
|
||||
[greeting]
|
||||
template = "你好，{username}！" # 问候模板
|
||||
enable_emoji = true # 启用表情
|
||||
enable_llm = false # 启用LLM生成
|
||||
|
||||
[helpful]
|
||||
enable_llm = false # 启用LLM生成帮助
|
||||
enable_emoji = true # 启用鼓励表情
|
||||
random_activation_probability = 0.15 # 随机激活概率
|
||||
```
|
||||
|
||||
### Command配置
|
||||
```toml
|
||||
[send]
|
||||
max_message_length = 500 # 最大消息长度
|
||||
|
||||
[echo]
|
||||
max_length = 200 # 回声最大长度
|
||||
enable_formatting = true # 启用格式化
|
||||
|
||||
[help]
|
||||
enable_llm = false # 启用LLM生成帮助内容
|
||||
enable_emoji = true # 启用帮助表情
|
||||
```
|
||||
|
||||
## 🚀 使用示例
|
||||
|
||||
### 智能问候
|
||||
### Action组件示例
|
||||
|
||||
#### 智能问候Action (关键词激活)
|
||||
```
|
||||
用户: 你好
|
||||
机器人: 你好，朋友！欢迎使用MaiBot综合插件系统！😊
|
||||
机器人: 嗨！很开心见到你～ 😊
|
||||
|
||||
用户: 早上好
|
||||
机器人: 早上好！今天也要元气满满哦！ ✨
|
||||
```
|
||||
|
||||
### 帮助查询
|
||||
#### 智能助手Action (LLM判断激活)
|
||||
```
|
||||
用户: 我不太懂怎么使用这个功能
|
||||
机器人: 关于功能使用，我来为你解释一下：这是一个simple级别的概念...
|
||||
这个概念其实很简单，让我用通俗的话来说明。 💡
|
||||
|
||||
用户: Python装饰器是什么？
|
||||
机器人: 关于Python装饰器，我来为你解释一下：这是一个medium级别的概念...
|
||||
装饰器是一种设计模式，用于在不修改原函数的情况下扩展功能。 🎯
|
||||
```
|
||||
|
||||
### Command组件示例
|
||||
|
||||
#### 帮助查询
|
||||
```
|
||||
用户: /help
|
||||
机器人: [显示完整命令帮助列表]
|
||||
@@ -132,27 +183,53 @@ enable_formatting = true # 启用格式化
|
||||
机器人: [显示send命令的详细帮助]
|
||||
```
|
||||
|
||||
### 消息发送
|
||||
#### 消息发送
|
||||
```
|
||||
用户: /send group 123456 大家好！
|
||||
机器人: ✅ 消息已成功发送到 群聊 123456
|
||||
```
|
||||
|
||||
### 日志监控（不拦截）
|
||||
#### 骰子命令
|
||||
```
|
||||
用户: /log info 这是一条测试消息
|
||||
[日志记录但消息继续处理，可能触发智能问候等其他功能]
|
||||
用户: !dice
|
||||
机器人: 🎲 你投出了: 4
|
||||
|
||||
用户: !骰子 3
|
||||
机器人: 🎲 你投出了3个骰子: 2, 5, 1 (总计: 8)
|
||||
```
|
||||
|
||||
### 两层决策机制展示
|
||||
|
||||
#### 第一层：激活控制
|
||||
```
|
||||
# SmartGreetingAction - 关键词激活
|
||||
用户消息包含"你好" → Action被激活 → 进入候选池
|
||||
|
||||
# HelpfulAction - LLM判断激活
|
||||
用户表达困惑 → LLM判断"是" → Action被激活 → 进入候选池
|
||||
用户正常聊天 → LLM判断"否" → Action不激活 → 不进入候选池
|
||||
```
|
||||
|
||||
#### 第二层：使用决策
|
||||
```
|
||||
# 即使Action被激活，LLM还会根据action_require判断是否真正使用
|
||||
# 比如HelpfulAction的条件："避免过度频繁地提供帮助，要恰到好处"
|
||||
# 如果刚刚已经提供了帮助，可能不会再次选择使用
|
||||
```
|
||||
|
||||
## 📁 文件结构
|
||||
|
||||
```
|
||||
src/plugins/built_in/example_comprehensive/
|
||||
├── plugin.py # 主插件文件
|
||||
├── config.toml # 配置文件
|
||||
└── README.md # 说明文档
|
||||
plugins/example_plugin/ # 用户插件目录
|
||||
├── plugin.py # 主插件文件
|
||||
├── config.toml # 配置文件
|
||||
└── README.md # 说明文档
|
||||
```
|
||||
|
||||
> 💡 **目录说明**：
|
||||
> - `plugins/` - 用户自定义插件目录（推荐放置位置）
|
||||
> - `src/plugins/builtin/` - 系统内置插件目录
|
||||
|
||||
## 🔄 架构升级
|
||||
|
||||
此插件展示了从旧插件系统到新插件系统的完整升级：
|
||||
@@ -169,13 +246,48 @@ src/plugins/built_in/example_comprehensive/
|
||||
|
||||
此插件可作为开发新插件的完整参考：
|
||||
|
||||
1. **Action开发**: 参考 `SmartGreetingAction`
|
||||
2. **Command开发**: 参考各种Command实现
|
||||
3. **拦截控制**: 根据需要设置 `intercept_message`
|
||||
4. **配置使用**: 通过 `self.api.get_config()` 读取配置
|
||||
5. **错误处理**: 完整的异常捕获和用户反馈
|
||||
6. **日志记录**: 结构化的日志输出
|
||||
### Action开发规范
|
||||
1. **必须项检查清单**:
|
||||
- ✅ 激活控制必须项：`focus_activation_type`, `normal_activation_type`, `mode_enable`, `parallel_action`
|
||||
- ✅ 基本信息必须项：`action_name`, `action_description`
|
||||
- ✅ 功能定义必须项：`action_parameters`, `action_require`, `associated_types`
|
||||
|
||||
2. **激活类型选择**:
|
||||
- `KEYWORD`: 适合明确触发词的功能（如问候）
|
||||
- `LLM_JUDGE`: 适合需要智能判断的功能（如帮助）
|
||||
- `RANDOM`: 适合增加随机性的功能
|
||||
- `ALWAYS`: 适合总是考虑的功能
|
||||
- `NEVER`: 用于临时禁用
|
||||
|
||||
3. **两层决策设计**:
|
||||
- 第一层（激活控制）：控制Action是否进入候选池
|
||||
- 第二层（使用决策）：LLM根据场景智能选择
|
||||
|
||||
### Command开发规范
|
||||
1. **拦截控制**: 根据需要设置 `intercept_message`
|
||||
2. **正则表达式**: 使用命名组捕获参数
|
||||
3. **错误处理**: 完整的异常捕获和用户反馈
|
||||
|
||||
### 通用开发规范
|
||||
1. **配置使用**: 通过 `self.api.get_config()` 读取配置
|
||||
2. **日志记录**: 结构化的日志输出
|
||||
3. **API调用**: 使用新的统一API接口
|
||||
4. **注册简化**: Action使用 `get_action_info()` 无参数调用
|
||||
|
||||
## 🎉 总结
|
||||
|
||||
这个综合示例插件完美展示了新插件系统的强大功能，特别是**拦截控制机制**，让开发者可以精确控制消息处理流程，实现更灵活的插件交互模式。
|
||||
这个综合示例插件完美展示了新插件系统的强大功能：
|
||||
|
||||
### 🚀 核心特性
|
||||
- **两层决策机制**：优化LLM决策压力，提升性能
|
||||
- **完整的Action规范**：所有必须项都在类中统一定义
|
||||
- **灵活的激活控制**：支持多种激活类型和条件
|
||||
- **精确的拦截控制**：Command可以精确控制消息处理流程
|
||||
|
||||
### 📚 学习价值
|
||||
- **Action vs Command**: 清晰展示两种组件的不同设计理念
|
||||
- **激活机制**: 实际演示关键词、LLM判断、随机等激活方式
|
||||
- **配置驱动**: 展示如何通过配置文件控制插件行为
|
||||
- **错误处理**: 完整的异常处理和用户反馈机制
|
||||
|
||||
这个插件是理解和掌握MaiBot插件系统的最佳起点！🌟
|
||||
Reference in New Issue
Block a user