Mofox-Core/plugins/example_plugin/README.md

综合示例插件

概述

这是一个展示新插件系统完整功能的综合示例插件，整合了所有旧示例插件的功能，并使用新的架构重写。

功能特性

🎯 Action组件

SmartGreetingAction - 智能问候

• 激活类型:
  • Focus模式: KEYWORD (关键词激活)
  • Normal模式: KEYWORD (关键词激活)
• 触发关键词: 你好、hello、hi、嗨、问候、早上好、晚上好
• 支持模式: 所有聊天模式
• 并行执行: 否
• 功能: 智能问候，支持多种风格和LLM个性化生成
• 参数: username(用户名), greeting_style(问候风格)
• 配置: 可自定义问候模板、启用表情、LLM生成

HelpfulAction - 智能助手

• 激活类型:
  • Focus模式: LLM_JUDGE (LLM智能判断)
  • Normal模式: RANDOM (随机激活，概率15%)
• 支持模式: 所有聊天模式
• 并行执行: 是
• 功能: 主动提供帮助和建议，展示LLM判断激活机制
• 参数: help_type(帮助类型), topic(主题), complexity(复杂度)
• 特点:
  • 通过LLM智能判断是否需要提供帮助
  • 展示两层决策机制的实际应用
  • 支持多种帮助类型（解释、建议、指导、提示）

📝 Command组件

1. ComprehensiveHelpCommand - 综合帮助系统

/help [命令名]

• 功能: 显示所有命令帮助或特定命令详情
• 拦截: ✅ 拦截消息处理
• 示例: /help, /help send

2. MessageSendCommand - 消息发送

/send <group|user> <ID> <消息内容>

• 功能: 向指定群聊或私聊发送消息
• 拦截: ✅ 拦截消息处理
• 示例: /send group 123456 大家好

3. SystemStatusCommand - 系统状态查询

/status [类型]

• 功能: 查询系统、插件、内存等状态
• 拦截: ✅ 拦截消息处理
• 示例: /status, /status 插件

4. EchoCommand - 回声命令

/echo <消息内容>

• 功能: 重复用户输入的消息
• 拦截: ✅ 拦截消息处理
• 示例: /echo Hello World

5. MessageInfoCommand - 消息信息查询

/info

• 功能: 显示当前消息的详细信息
• 拦截: ✅ 拦截消息处理
• 示例: /info

6. CustomPrefixCommand - 自定义前缀

/prefix <前缀> <内容>

• 功能: 为消息添加自定义前缀
• 拦截: ✅ 拦截消息处理
• 示例: /prefix [公告] 系统维护

7. LogMonitorCommand - 日志监控

/log [级别]

• 功能: 记录消息到日志但不拦截后续处理
• 拦截: ❌ 不拦截，继续处理消息
• 示例: /log, /log debug

🔧 拦截控制演示

此插件完美演示了新插件系统的拦截控制功能：

拦截型命令 (intercept_message = True)

• /help - 显示帮助后停止处理
• /send - 发送消息后停止处理
• /status - 查询状态后停止处理
• /echo - 回声后停止处理
• /info - 显示信息后停止处理
• /prefix - 添加前缀后停止处理

非拦截型命令 (intercept_message = False)

• /log - 记录日志但继续处理，可能触发其他功能

⚙️ 配置说明

插件支持通过 config.toml 进行详细配置：

组件控制

[components]
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配置

[greeting]
template = "你好，{username}！"  # 问候模板
enable_emoji = true              # 启用表情
enable_llm = false              # 启用LLM生成

[helpful]
enable_llm = false                    # 启用LLM生成帮助
enable_emoji = true                   # 启用鼓励表情
random_activation_probability = 0.15  # 随机激活概率

Command配置

[send]
max_message_length = 500        # 最大消息长度

[echo]
max_length = 200               # 回声最大长度
enable_formatting = true       # 启用格式化

[help]
enable_llm = false             # 启用LLM生成帮助内容
enable_emoji = true            # 启用帮助表情

🚀 使用示例

Action组件示例

智能问候Action (关键词激活)

用户: 你好
机器人: 嗨！很开心见到你～ 😊

用户: 早上好
机器人: 早上好！今天也要元气满满哦！ ✨

智能助手Action (LLM判断激活)

用户: 我不太懂怎么使用这个功能
机器人: 关于功能使用，我来为你解释一下：这是一个simple级别的概念...
这个概念其实很简单，让我用通俗的话来说明。 💡

用户: Python装饰器是什么？
机器人: 关于Python装饰器，我来为你解释一下：这是一个medium级别的概念...
装饰器是一种设计模式，用于在不修改原函数的情况下扩展功能。 🎯

Command组件示例

帮助查询

用户: /help
机器人: [显示完整命令帮助列表]

用户: /help send
机器人: [显示send命令的详细帮助]

消息发送

用户: /send group 123456 大家好！
机器人: ✅ 消息已成功发送到 群聊 123456

骰子命令

用户: !dice
机器人: 🎲 你投出了: 4

用户: !骰子 3
机器人: 🎲 你投出了3个骰子: 2, 5, 1 (总计: 8)

两层决策机制展示

第一层：激活控制

# SmartGreetingAction - 关键词激活
用户消息包含"你好" → Action被激活 → 进入候选池

# HelpfulAction - LLM判断激活  
用户表达困惑 → LLM判断"是" → Action被激活 → 进入候选池
用户正常聊天 → LLM判断"否" → Action不激活 → 不进入候选池

第二层：使用决策

# 即使Action被激活，LLM还会根据action_require判断是否真正使用
# 比如HelpfulAction的条件："避免过度频繁地提供帮助，要恰到好处"
# 如果刚刚已经提供了帮助，可能不会再次选择使用

📁 文件结构

plugins/example_plugin/     # 用户插件目录
├── plugin.py              # 主插件文件
├── config.toml            # 配置文件
└── README.md              # 说明文档

💡 目录说明：

• plugins/ - 用户自定义插件目录（推荐放置位置）
• src/plugins/builtin/ - 系统内置插件目录

🔄 架构升级

此插件展示了从旧插件系统到新插件系统的完整升级：

新系统特征

• 使用统一的组件注册机制
• 新的 BaseAction 和 BaseCommand 基类
• 拦截控制功能 - 灵活的消息处理流程
• 强大的配置驱动架构
• 统一的API接口
• 完整的错误处理和日志

💡 开发指南

此插件可作为开发新插件的完整参考：

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插件系统的最佳起点！🌟