# 🚀 快速开始指南

## 📖 概述

这个指南将带你在5分钟内创建你的第一个MaiBot插件。我们将创建一个简单的问候插件，展示插件系统的基本概念。

## 🎯 学习目标

- 理解插件的基本结构
- 创建你的第一个Action组件
- 创建你的第一个Command组件
- 学会配置插件

## 📂 准备工作

确保你已经：
1. 克隆了MaiBot项目
2. 安装了Python依赖
3. 了解基本的Python语法

## 🏗️ 创建插件

### 1. 创建插件目录

在项目根目录的 `plugins/` 文件夹下创建你的插件目录：

```bash
mkdir plugins/hello_world_plugin
cd plugins/hello_world_plugin
```

### 2. 创建插件主文件

创建 `plugin.py` 文件：

```python
from typing import List, Tuple, Type
from src.plugin_system import (
    BasePlugin, register_plugin, BaseAction, BaseCommand,
    ComponentInfo, ActionActivationType, ChatMode
)

# ===== Action组件 =====

class HelloAction(BaseAction):
    """问候Action - 展示智能动作的基本用法"""

    # ===== 激活控制必须项 =====
    focus_activation_type = ActionActivationType.KEYWORD
    normal_activation_type = ActionActivationType.KEYWORD
    mode_enable = ChatMode.ALL
    parallel_action = False

    # ===== 基本信息必须项 =====
    action_name = "hello_greeting"
    action_description = "向用户发送友好的问候消息"

    # 关键词配置
    activation_keywords = ["你好", "hello", "hi"]
    keyword_case_sensitive = False

    # ===== 功能定义必须项 =====
    action_parameters = {
        "greeting_style": "问候风格：casual(随意) 或 formal(正式)"
    }

    action_require = [
        "用户发送问候语时使用",
        "营造友好的聊天氛围"
    ]

    associated_types = ["text", "emoji"]

    async def execute(self) -> Tuple[bool, str]:
        """执行问候动作"""
        # 获取参数
        style = self.action_data.get("greeting_style", "casual")
        
        # 根据风格生成问候语
        if style == "formal":
            message = "您好！很高兴为您服务！"
            emoji = "🙏"
        else:
            message = "嗨！很开心见到你！"
            emoji = "😊"
        
        # 发送消息
        await self.send_text(message)
        await self.send_type("emoji", emoji)
        
        return True, f"发送了{style}风格的问候"

# ===== Command组件 =====

class TimeCommand(BaseCommand):
    """时间查询Command - 展示命令的基本用法"""

    command_pattern = r"^/time$"
    command_help = "查询当前时间"
    command_examples = ["/time"]
    intercept_message = True  # 拦截消息处理

    async def execute(self) -> Tuple[bool, str]:
        """执行时间查询"""
        import datetime
        
        now = datetime.datetime.now()
        time_str = now.strftime("%Y-%m-%d %H:%M:%S")
        
        await self.send_text(f"⏰ 当前时间：{time_str}")
        
        return True, f"显示了当前时间: {time_str}"

# ===== 插件注册 =====

@register_plugin
class HelloWorldPlugin(BasePlugin):
    """Hello World插件 - 你的第一个MaiBot插件"""

    # 插件基本信息
    plugin_name = "hello_world_plugin"
    plugin_description = "Hello World演示插件，展示基本的Action和Command用法"
    plugin_version = "1.0.0"
    plugin_author = "你的名字"
    enable_plugin = True  # 默认启用插件
    config_file_name = "config.toml"
    
    # Python依赖声明（可选）
    python_dependencies = [
        # 如果你的插件需要额外的Python包，在这里声明
        # PythonDependency(
        #     package_name="requests",
        #     version=">=2.25.0", 
        #     description="HTTP请求库"
        # ),
    ]

    def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
        """返回插件包含的组件列表"""
        return [
            # Action组件 - 使用类中定义的所有属性
            (HelloAction.get_action_info(), HelloAction),
            
            # Command组件 - 需要指定name和description
            (TimeCommand.get_command_info(
                name="time_query", 
                description="查询当前系统时间"
            ), TimeCommand),
        ]
```

### 3. 创建配置文件

创建 `config.toml` 文件：

```toml
[plugin]
name = "hello_world_plugin"
version = "1.0.0"
enabled = true
description = "Hello World演示插件"

[greeting]
default_style = "casual"
enable_emoji = true

[time]
timezone = "Asia/Shanghai"
format = "%Y-%m-%d %H:%M:%S"

[logging]
level = "INFO"
```

### 4. 创建说明文档

创建 `README.md` 文件：

```markdown
# Hello World 插件

## 概述

这是一个简单的Hello World插件，演示了MaiBot插件系统的基本用法。

## 功能

- **HelloAction**: 智能问候动作，响应用户的问候语
- **TimeCommand**: 时间查询命令，显示当前时间

## 使用方法

### Action使用
当用户发送包含"你好"、"hello"或"hi"的消息时，插件会自动触发问候动作。

### Command使用
发送 `/time` 查询当前时间。

## 配置

可以通过 `config.toml` 调整插件行为。
```

## 🎮 测试插件

### 1. 启动MaiBot

将插件放入 `plugins/` 目录后，启动MaiBot：

```bash
python main.py
```

### 2. 测试Action

发送消息：
```
你好
```

期望输出：
```
嗨！很开心见到你！😊
```

### 3. 测试Command

发送命令：
```
/time
```

期望输出：
```
⏰ 当前时间：2024-01-01 12:00:00
```

## 🔍 解析代码

### Action组件重点

1. **激活控制**: 使用 `KEYWORD` 激活类型，当检测到指定关键词时触发
2. **必须项完整**: 包含所有必须的类属性
3. **智能决策**: 麦麦会根据情境决定是否使用这个Action

### Command组件重点

1. **正则匹配**: 使用 `^/time$` 精确匹配 `/time` 命令
2. **消息拦截**: 设置 `intercept_message = True` 防止命令继续处理
3. **即时响应**: 匹配到命令立即执行

### 插件注册重点

1. **@register_plugin**: 装饰器自动注册插件
2. **组件列表**: `get_plugin_components()` 返回所有组件
3. **配置加载**: 自动加载 `config.toml` 文件

## 📦 添加依赖包（可选）

如果你的插件需要额外的Python包，可以声明依赖：

```python
from src.plugin_system import PythonDependency

@register_plugin
class HelloWorldPlugin(BasePlugin):
    # ... 其他配置 ...
    
    # 声明Python依赖
    python_dependencies = [
        PythonDependency(
            package_name="requests",
            version=">=2.25.0",
            description="HTTP请求库，用于网络功能"
        ),
        PythonDependency(
            package_name="numpy", 
            version=">=1.20.0",
            optional=True,
            description="数值计算库（可选功能）"
        ),
    ]
```

### 依赖检查

系统会自动检查依赖，你也可以手动检查：

```python
from src.plugin_system import plugin_manager

# 检查所有插件依赖
result = plugin_manager.check_all_dependencies()
print(f"缺少依赖的插件: {result['plugins_with_missing_required']}个")

# 生成requirements文件
plugin_manager.generate_plugin_requirements("plugin_deps.txt")
```

📚 **详细了解**: [依赖管理系统](dependency-management.md)

## 🎯 下一步

恭喜！你已经创建了第一个MaiBot插件。接下来可以：

1. 学习 [Action组件详解](action-components.md) 掌握更复杂的Action开发
2. 学习 [Command组件详解](command-components.md) 创建更强大的命令
3. 了解 [依赖管理系统](dependency-management.md) 管理Python包依赖
4. 查看 [API参考](api/) 了解所有可用的接口
5. 参考 [完整示例](examples/complete-examples.md) 学习最佳实践

## 🐛 常见问题

### Q: 插件没有加载怎么办？
A: 检查：
1. 插件是否放在 `plugins/` 目录下
2. `plugin.py` 文件语法是否正确
3. 查看启动日志中的错误信息

### Q: Action没有触发怎么办？
A: 检查：
1. 关键词是否正确配置
2. 消息是否包含激活关键词
3. 聊天模式是否匹配

### Q: Command无响应怎么办？
A: 检查：
1. 正则表达式是否正确
2. 命令格式是否精确匹配
3. 是否有其他插件拦截了消息

## 🔧 插件启用状态管理

### 启用状态控制方式

插件可以通过以下两种方式控制启用状态：

1. **类属性控制**
```python
class MyPlugin(BasePlugin):
    enable_plugin = True  # 在类中设置启用状态
```

2. **配置文件控制**
```toml
[plugin]
enabled = true  # 在配置文件中设置启用状态
```

### 启用状态优先级

1. 配置文件中的设置优先级高于类属性
2. 如果配置文件中没有 `[plugin] enabled` 设置，则使用类属性中的值
3. 如果类属性也没有设置，则使用 `BasePlugin` 的默认值 `False`

### 最佳实践

1. 在开发插件时，建议在类中设置 `enable_plugin = True`
2. 在部署插件时，通过配置文件控制启用状态
3. 在文档中明确说明插件的默认启用状态
4. 提供配置示例，说明如何启用/禁用插件

### 常见问题

1. **插件未加载**
   - 检查类属性 `enable_plugin` 是否设置为 `True`
   - 检查配置文件中的 `[plugin] enabled` 设置
   - 查看日志中是否有插件加载相关的错误信息

2. **配置文件不生效**
   - 确保配置文件名称正确（默认为 `config.toml`）
   - 确保配置文件格式正确（TOML格式）
   - 确保配置文件中的 `[plugin]` 部分存在

3. **动态启用/禁用**
   - 修改配置文件后需要重启MaiBot才能生效
   - 目前不支持运行时动态启用/禁用插件

---

🎉 **成功！你已经掌握了MaiBot插件开发的基础！**