gardel/Mofox-Core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

quick start 文档和管理插件更新

Browse Source
This commit is contained in:
UnCLAS-Prommer
2025-07-25 17:35:00 +08:00
parent a725f70ee2
commit ca503fbd9b
4 changed files with 191 additions and 255 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/plugins/action-components.md
View File

@@ -22,7 +22,7 @@ class ExampleAction(BaseAction):
action_name = "example_action" # 动作的唯一标识符
action_description = "这是一个示例动作" # 动作描述
activation_type = ActionActivationType.ALWAYS # 这里以 ALWAYS 为例
mode_enable = ChatMode.ALL # 这里以 ALL 为例
mode_enable = ChatMode.ALL # 一般取ALL，表示在所有聊天模式下都可用
associated_types = ["text", "emoji", ...] # 关联类型
parallel_action = False # 是否允许与其他Action并行执行
action_parameters = {"param1": "参数1的说明", "param2": "参数2的说明", ...}
@@ -60,7 +60,7 @@ class ExampleAction(BaseAction):
**请知悉，对于不同的处理器，其支持的消息类型可能会有所不同。在开发时请注意。**
#### action_parameters: 该Action的参数说明。
这是一个字典，键为参数名，值为参数说明。这个字段可以帮助LLM理解如何使用这个Action，并由LLM返回对应的参数，最后传递到 Action 的 action_data 属性中。其格式与你定义的格式完全相同 **（除非LLM哈气了，返回了错误的内容）**。
这是一个字典，键为参数名，值为参数说明。这个字段可以帮助LLM理解如何使用这个Action，并由LLM返回对应的参数，最后传递到 Action 的 **`action_data`** 属性中。其格式与你定义的格式完全相同 **（除非LLM哈气了，返回了错误的内容）**。
---
@@ -180,6 +180,8 @@ class GreetingAction(BaseAction):
return True, "发送了问候"
```
一个完整的使用`ActionActivationType.KEYWORD`的例子请参考`plugins/hello_world_plugin`中的`ByeAction`。
#### 第二层：使用决策
**在Action被激活后，使用条件决定麦麦什么时候会"选择"使用这个Action**。

437
docs/plugins/quick-start.md
View File

@@ -1,20 +1,14 @@
# 🚀 快速开始指南
本指南将带你用5分钟时间，从零开始创建一个功能完整的MaiCore插件。
本指南将带你从零开始创建一个功能完整的MaiCore插件。
## 📖 概述
这个指南将带你快速创建你的第一个MaiCore插件。我们将创建一个简单的问候插件，展示插件系统的基本概念。无需阅读其他文档，跟着本指南就能完成！
这个指南将带你快速创建你的第一个MaiCore插件。我们将创建一个简单的问候插件，展示插件系统的基本概念。
## 🎯 学习目标
以下代码都在我们的`plugins/hello_world_plugin/`目录下。
- 理解插件的基本结构
- 从最简单的插件开始，循序渐进
- 学会创建Action组件（智能动作）
- 学会创建Command组件（命令响应）
- 掌握配置Schema定义和配置文件自动生成（可选）
## 📂 准备工作
### 📂 准备工作
确保你已经：
@@ -26,16 +20,29 @@
### 1. 创建插件目录
在项目根目录的 `plugins/` 文件夹下创建你的插件目录，目录名与插件名保持一致：
在项目根目录的 `plugins/` 文件夹下创建你的插件目录
可以用以下命令快速创建：
这里我们创建一个名为 `hello_world_plugin` 的目录
```bash
mkdir plugins/hello_world_plugin
cd plugins/hello_world_plugin
### 2. 创建`_manifest.json`文件
在插件目录下面创建一个 `_manifest.json` 文件，内容如下：
```json
{
"manifest_version": 1,
"name": "Hello World 插件",
"version": "1.0.0",
"description": "一个简单的 Hello World 插件",
"author": {
"name": "你的名字"
}
}
```
### 2. 创建最简单的插件
有关 `_manifest.json` 的详细说明，请参考 [Manifest文件指南](./manifest-guide.md)。
### 3. 创建最简单的插件
让我们从最基础的开始！创建 `plugin.py` 文件：
@@ -43,34 +50,33 @@ cd plugins/hello_world_plugin
from typing import List, Tuple, Type
from src.plugin_system import BasePlugin, register_plugin, ComponentInfo
# ===== 插件注册 =====
@register_plugin
@register_plugin # 注册插件
class HelloWorldPlugin(BasePlugin):
"""Hello World插件 - 你的第一个MaiCore插件"""
# 插件基本信息（必须填写）
# 以下是插件基本信息和方法（必须填写）
plugin_name = "hello_world_plugin"
plugin_description = "我的第一个MaiCore插件"
plugin_version = "1.0.0"
plugin_author = "你的名字"
enable_plugin = True # 启用插件
dependencies = [] # 插件依赖列表（目前为空）
python_dependencies = [] # Python依赖列表（目前为空）
config_file_name = "config.toml" # 配置文件名
config_schema = {} # 配置文件模式（目前为空）
def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]: # 获取插件组件
"""返回插件包含的组件列表（目前是空的）"""
return []
```
🎉 **恭喜！你刚刚创建了一个最简单但完整的MaiCore插件！**
🎉 恭喜！你刚刚创建了一个最简单但完整的MaiCore插件！
**解释一下这些代码：**
- 首先，我们在plugin.py中定义了一个HelloWorldPulgin插件类，继承自 `BasePlugin` ，提供基本功能。
- 首先，我们在`plugin.py`中定义了一个HelloWorldPlugin插件类，继承自 `BasePlugin` ，提供基本功能。
- 通过给类加上，`@register_plugin` 装饰器，我们告诉系统"这是一个插件"
- `plugin_name` 等是插件的基本信息，必须填写，**此部分必须与目录名称相同，否则插件无法使用**
- `get_plugin_components()` 返回插件的功能组件，现在我们没有定义任何action（动作）或者command(指令)，是空的
- `plugin_name` 等是插件的基本信息，必须填写
- `get_plugin_components()` 返回插件的功能组件，现在我们没有定义任何 Action, Command 或者 EventHandler，所以返回空列表。
### 3. 测试基础插件
### 4. 测试基础插件
现在就可以测试这个插件了！启动MaiCore：
@@ -80,7 +86,7 @@ class HelloWorldPlugin(BasePlugin):
![1750326700269](image/quick-start/1750326700269.png)
### 4. 添加第一个功能：问候Action
### 5. 添加第一个功能：问候Action
现在我们要给插件加入一个有用的功能，我们从最好玩的Action做起
@@ -107,40 +113,34 @@ class HelloAction(BaseAction):
# === 基本信息（必须填写）===
action_name = "hello_greeting"
action_description = "向用户发送问候消息"
activation_type = ActionActivationType.ALWAYS # 始终激活
# === 功能描述（必须填写）===
action_parameters = {
"greeting_message": "要发送的问候消息"
}
action_require = [
"需要发送友好问候时使用",
"当有人向你问好时使用",
"当你遇见没有见过的人时使用"
]
action_parameters = {"greeting_message": "要发送的问候消息"}
action_require = ["需要发送友好问候时使用", "当有人向你问好时使用", "当你遇见没有见过的人时使用"]
associated_types = ["text"]
async def execute(self) -> Tuple[bool, str]:
"""执行问候动作 - 这是核心功能"""
# 发送问候消息
greeting_message = self.action_data.get("greeting_message","")
message = "嗨！很开心见到你！😊" + greeting_message
greeting_message = self.action_data.get("greeting_message", "")
base_message = self.get_config("greeting.message", "嗨！很开心见到你！😊")
message = base_message + greeting_message
await self.send_text(message)
return True, "发送了问候消息"
# ===== 插件注册 =====
@register_plugin
class HelloWorldPlugin(BasePlugin):
"""Hello World插件 - 你的第一个MaiCore插件"""
# 插件基本信息
plugin_name = "hello_world_plugin"
plugin_description = "我的第一个MaiCore插件，包含问候功能"
plugin_version = "1.0.0"
plugin_author = "你的名字"
enable_plugin = True
dependencies = []
python_dependencies = []
config_file_name = "config.toml"
config_schema = {}
def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
"""返回插件包含的组件列表"""
@@ -150,13 +150,17 @@ class HelloWorldPlugin(BasePlugin):
]
```
**新增内容解释：**
**解释一下这些代码：**
- `HelloAction` 是一个Action组件，MaiCore可能会选择使用它
- `HelloAction` 是我们定义的问候动作类，继承自 `BaseAction`，并实现了核心功能。
- 在 `HelloWorldPlugin` 中，我们通过 `get_plugin_components()` 方法，通过调用`get_action_info()`这个内置方法将 `HelloAction` 注册为插件的一个组件。
- 这样一来，当插件被加载时，问候动作也会被一并加载，并可以在MaiCore中使用。
- `execute()` 函数是Action的核心，定义了当Action被MaiCore选择后，具体要做什么
- `self.send_text()` 是发送文本消息的便捷方法
### 5. 测试问候功能
Action 组件中有关`activation_type`、`action_parameters`、`action_require`、`associated_types` 等的详细说明请参考 [Action组件指南](./action-components.md)。
### 6. 测试问候Action
重启MaiCore，然后在聊天中发送任意消息，比如：
@@ -174,96 +178,17 @@ MaiCore可能会选择使用你的问候Action，发送回复：
> **💡 小提示**：MaiCore会智能地决定什么时候使用它。如果没有立即看到效果，多试几次不同的消息。
🎉 **太棒了！你的插件已经有实际功能了！**
🎉 太棒了！你的插件已经有实际功能了！
### 5.5. 了解激活系统（重要概念）
Action固然好用简单，但是现在有个问题，当用户加载了非常多的插件，添加了很多自定义Action，LLM需要选择的Action也会变多
而不断增多的Action会加大LLM的消耗和负担，降低Action使用的精准度。而且我们并不需要LLM在所有时候都考虑所有Action
例如，当群友只是在进行正常的聊天，就没有必要每次都考虑是否要选择“禁言”动作，这不仅影响决策速度，还会增加消耗。
那有什么办法，能够让Action有选择的加入MaiCore的决策池呢？
**什么是激活系统？**
激活系统决定了什么时候你的Action会被MaiCore"考虑"使用：
- **`ActionActivationType.ALWAYS`** - 总是可用（默认值）
- **`ActionActivationType.KEYWORD`** - 只有消息包含特定关键词时才可用
- **`ActionActivationType.PROBABILITY`** - 根据概率随机可用
- **`ActionActivationType.NEVER`** - 永不可用（用于调试）
> **💡 使用提示**：
>
> - 推荐使用枚举类型（如 `ActionActivationType.ALWAYS`），有代码提示和类型检查
> - 也可以直接使用字符串（如 `"always"`），系统都支持
### 5.6. 进阶：尝试关键词激活（可选）
现在让我们尝试一个更精确的激活方式！添加一个只在用户说特定关键词时才激活的Action：
```python
# 在HelloAction后面添加这个新Action
class ByeAction(BaseAction):
"""告别Action - 只在用户说再见时激活"""
action_name = "bye_greeting"
action_description = "向用户发送告别消息"
# 使用关键词激活
focus_activation_type = ActionActivationType.KEYWORD
normal_activation_type = ActionActivationType.KEYWORD
# 关键词设置
activation_keywords = ["再见", "bye", "88", "拜拜"]
keyword_case_sensitive = False
action_parameters = {"bye_message": "要发送的告别消息"}
action_require = [
"用户要告别时使用",
"当有人要离开时使用",
"当有人和你说再见时使用",
]
associated_types = ["text"]
async def execute(self) -> Tuple[bool, str]:
bye_message = self.action_data.get("bye_message","")
message = "再见！期待下次聊天！👋" + bye_message
await self.send_text(message)
return True, "发送了告别消息"
```
然后在插件注册中添加这个Action：
```python
def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
return [
(HelloAction.get_action_info(), HelloAction),
(ByeAction.get_action_info(), ByeAction), # 添加告别Action
]
```
现在测试：发送"再见"，应该会触发告别Action！
**关键词激活的特点：**
- 更精确：只在包含特定关键词时才会被考虑
- 更可预测：用户知道说什么会触发什么功能
- 更适合：特定场景或命令式的功能
### 6. 添加第二个功能：时间查询Command
### 7. 添加第二个功能：时间查询Command
现在让我们添加一个Command组件。Command和Action不同，它是直接响应用户命令的：
Command是最简单，最直接的相应，不由LLM判断选择使用
Command是最简单，最直接的响应，不由LLM判断选择使用
```python
# 在现有代码基础上，添加Command组件
# ===== Command组件 =====
import datetime
from src.plugin_system import BaseCommand
#导入Command基类
@@ -275,53 +200,49 @@ class TimeCommand(BaseCommand):
# === 命令设置（必须填写）===
command_pattern = r"^/time$" # 精确匹配 "/time" 命令
command_help = "查询当前时间"
command_examples = ["/time"]
intercept_message = True # 拦截消息，不让其他组件处理
async def execute(self) -> Tuple[bool, str]:
async def execute(self) -> Tuple[bool, Optional[str], bool]:
"""执行时间查询"""
import datetime
# 获取当前时间
time_format = self.get_config("time.format", "%Y-%m-%d %H:%M:%S")
time_format: str = "%Y-%m-%d %H:%M:%S"
now = datetime.datetime.now()
time_str = now.strftime(time_format)
# 发送时间信息
message = f"⏰ 当前时间：{time_str}"
await self.send_text(message)
return True, f"显示了当前时间: {time_str}"
# ===== 插件注册 =====
return True, f"显示了当前时间: {time_str}", True
@register_plugin
class HelloWorldPlugin(BasePlugin):
"""Hello World插件 - 你的第一个MaiCore插件"""
# 插件基本信息
plugin_name = "hello_world_plugin"
plugin_description = "我的第一个MaiCore插件，包含问候和时间查询功能"
plugin_version = "1.0.0"
plugin_author = "你的名字"
enable_plugin = True
dependencies = []
python_dependencies = []
config_file_name = "config.toml"
config_schema = {}
def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
return [
(HelloAction.get_action_info(), HelloAction),
(ByeAction.get_action_info(), ByeAction),
(TimeCommand.get_command_info(), TimeCommand),
]
```
同样的，我们通过 `get_plugin_components()` 方法，通过调用`get_action_info()`这个内置方法将 `TimeCommand` 注册为插件的一个组件。
**Command组件解释：**
- Command是直接响应用户命令的组件
- `command_pattern` 使用正则表达式匹配用户输入
- `^/time$` 表示精确匹配 "/time"
- `intercept_message = True` 表示处理完命令后不再让其他组件处理
### 7. 测试时间查询功能
有关 Command 组件的更多信息，请参考 [Command组件指南](./command-components.md)。
### 8. 测试时间查询Command
重启MaiCore，发送命令：
@@ -332,106 +253,147 @@ class HelloWorldPlugin(BasePlugin):
你应该会收到回复：
```
⏰ 当前时间：2024-01-01 12:30:45
⏰ 当前时间：2024-01-01 12:00:00
```
🎉 **太棒了！现在你的插件有3个功能了！**
🎉 太棒了！现在你已经了解了基本的 Action 和 Command 组件的使用方法。你可以根据自己的需求，继续扩展插件的功能，添加更多的 Action 和 Command 组件，让你的插件更加丰富和强大！
### 8. 添加配置文件（可选进阶）
---
如果你想让插件更加灵活，可以添加配置支持。
## 进阶教程
如果你想让插件更加灵活和强大，可以参考接下来的进阶教程。
### 1. 添加配置文件
想要为插件添加配置文件吗？让我们一起来配置`config_schema`属性！
> **🚨 重要：不要手动创建config.toml文件！**
>
> 我们需要在插件代码中定义配置Schema，让系统自动生成配置文件。
#### 📄 配置架构说明
在新的插件系统中，我们采用了**职责分离**的设计：
- **`_manifest.json`** - 插件元数据（名称、版本、描述、作者等）
- **`config.toml`** - 运行时配置（启用状态、功能参数等）
这样避免了信息重复，提高了维护性。
首先，在插件类中定义配置Schema：
```python
from src.plugin_system.base.config_types import ConfigField
from src.plugin_system import ConfigField
@register_plugin
class HelloWorldPlugin(BasePlugin):
"""Hello World插件 - 你的第一个MaiCore插件"""
plugin_name = "hello_world_plugin"
plugin_description = "我的第一个MaiCore插件，包含问候和时间查询功能"
plugin_version = "1.0.0"
plugin_author = "你的名字"
enable_plugin = True
config_file_name = "config.toml" # 配置文件名
# 配置节描述
config_section_descriptions = {
"plugin": "插件启用配置",
"greeting": "问候功能配置",
"time": "时间查询配置"
}
# 插件基本信息
plugin_name: str = "hello_world_plugin" # 内部标识符
enable_plugin: bool = True
dependencies: List[str] = [] # 插件依赖列表
python_dependencies: List[str] = [] # Python包依赖列表
config_file_name: str = "config.toml" # 配置文件名
# 配置Schema定义
config_schema = {
config_schema: dict = {
"plugin": {
"enabled": ConfigField(type=bool, default=True, description="是否启用插件")
"name": ConfigField(type=str, default="hello_world_plugin", description="插件名称"),
"version": ConfigField(type=str, default="1.0.0", description="插件版本"),
"enabled": ConfigField(type=bool, default=False, description="是否启用插件"),
},
"greeting": {
"message": ConfigField(
type=str,
default="嗨！很开心见到你！😊",
description="默认问候消息"
),
"enable_emoji": ConfigField(type=bool, default=True, description="是否启用表情符号")
"message": ConfigField(type=str, default="嗨！很开心见到你！😊", description="默认问候消息"),
"enable_emoji": ConfigField(type=bool, default=True, description="是否启用表情符号"),
},
"time": {
"format": ConfigField(
type=str,
default="%Y-%m-%d %H:%M:%S",
description="时间显示格式"
)
}
"time": {"format": ConfigField(type=str, default="%Y-%m-%d %H:%M:%S", description="时间显示格式")},
}
def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
return [
(HelloAction.get_action_info(), HelloAction),
(ByeAction.get_action_info(), ByeAction),
(TimeCommand.get_command_info(), TimeCommand),
]
```
然后修改Action和Command代码，让它们读取配置：
这会生成一个如下的 `config.toml` 文件：
```toml
# hello_world_plugin - 自动生成的配置文件
# 我的第一个MaiCore插件，包含问候功能和时间查询等基础示例
# 插件基本信息
[plugin]
# 插件名称
name = "hello_world_plugin"
# 插件版本
version = "1.0.0"
# 是否启用插件
enabled = false
# 问候功能配置
[greeting]
# 默认问候消息
message = "嗨！很开心见到你！😊"
# 是否启用表情符号
enable_emoji = true
# 时间查询配置
[time]
# 时间显示格式
format = "%Y-%m-%d %H:%M:%S"
```
然后修改Action和Command代码，通过 `get_config()` 方法让它们读取配置（配置的键是命名空间式的）：
```python
# 在HelloAction的execute方法中：
async def execute(self) -> Tuple[bool, str]:
# 从配置文件读取问候消息
greeting_message = self.action_data.get("greeting_message", "")
base_message = self.get_config("greeting.message", "嗨！很开心见到你！😊")
message = base_message + greeting_message
await self.send_text(message)
return True, "发送了问候消息"
class HelloAction(BaseAction):
"""问候Action - 简单的问候动作"""
# 在TimeCommand的execute方法中：
async def execute(self) -> Tuple[bool, str]:
import datetime
# 从配置文件读取时间格式
time_format = self.get_config("time.format", "%Y-%m-%d %H:%M:%S")
now = datetime.datetime.now()
time_str = now.strftime(time_format)
message = f"⏰ 当前时间：{time_str}"
await self.send_text(message)
return True, f"显示了当前时间: {time_str}"
# === 基本信息（必须填写）===
action_name = "hello_greeting"
action_description = "向用户发送问候消息"
activation_type = ActionActivationType.ALWAYS # 始终激活
# === 功能描述（必须填写）===
action_parameters = {"greeting_message": "要发送的问候消息"}
action_require = ["需要发送友好问候时使用", "当有人向你问好时使用", "当你遇见没有见过的人时使用"]
associated_types = ["text"]
async def execute(self) -> Tuple[bool, str]:
"""执行问候动作 - 这是核心功能"""
# 发送问候消息
greeting_message = self.action_data.get("greeting_message", "")
base_message = self.get_config("greeting.message", "嗨！很开心见到你！😊")
message = base_message + greeting_message
await self.send_text(message)
return True, "发送了问候消息"
class TimeCommand(BaseCommand):
"""时间查询Command - 响应/time命令"""
command_name = "time"
command_description = "查询当前时间"
# === 命令设置（必须填写）===
command_pattern = r"^/time$" # 精确匹配 "/time" 命令
async def execute(self) -> Tuple[bool, str, bool]:
"""执行时间查询"""
import datetime
# 获取当前时间
time_format: str = self.get_config("time.format", "%Y-%m-%d %H:%M:%S") # type: ignore
now = datetime.datetime.now()
time_str = now.strftime(time_format)
# 发送时间信息
message = f"⏰ 当前时间：{time_str}"
await self.send_text(message)
return True, f"显示了当前时间: {time_str}", True
```
**配置系统工作流程：**
@@ -441,47 +403,18 @@ async def execute(self) -> Tuple[bool, str]:
3. **用户修改**: 用户可以修改生成的配置文件
4. **代码读取**: 使用 `self.get_config()` 读取配置值
**配置功能解释：**
**绝对不要手动创建 `config.toml` 文件！**
- `self.get_config()` 可以读取配置文件中的值
- 第一个参数是配置路径（用点分隔），第二个参数是默认值
- 配置文件会包含详细的注释和说明，用户可以轻松理解和修改
- **绝不要手动创建配置文件**，让系统自动生成
### 2. 创建说明文档
### 9. 创建说明文档（可选）
你可以创建一个 `README.md` 文件，描述插件的功能和使用方法。
创建 `README.md` 文件来说明你的插件：
### 3. 发布到插件市场
```markdown
# Hello World 插件
如果你想让更多人使用你的插件，可以将它发布到MaiCore的插件市场。
## 概述
我的第一个MaiCore插件，包含问候和时间查询功能。
这部分请参考 [plugin-repo](https://github.com/Maim-with-u/plugin-repo) 的文档。
## 功能
- **问候功能**: 当用户说"你好"、"hello"、"hi"时自动回复
- **时间查询**: 发送 `/time` 命令查询当前时间
---
## 使用方法
### 问候功能
发送包含以下关键词的消息：
- "你好"
- "hello"
- "hi"
### 时间查询
发送命令：`/time`
## 配置文件
插件会自动生成 `config.toml` 配置文件，用户可以修改：
- 问候消息内容
- 时间显示格式
- 插件启用状态
注意：配置文件是自动生成的，不要手动创建！
```
```
```
🎉 恭喜你！你已经成功的创建了自己的插件了！