# 插件开发入门

写插件是给 NEO Bot 添加功能的唯一方式，一个 Python 文件就是一个插件。（或者一个文件夹里边有__init__.py）

## 1. 创建你的第一个插件

在 `plugins/` 目录下，新建一个 `hello.py` 文件。

```python
# plugins/hello.py

from core.managers.command_manager import matcher
from models.events.message import MessageEvent

# __plugin_meta__ 是插件元信息，会在 /help 指令里显示
__plugin_meta__ = {
    "name": "你好世界",
    "description": "一个简单的示例插件",
    "usage": "/hello - 发送你好"
}

# @matcher.command() 装饰器注册一个命令
# "hello" 是命令名，aliases 是别名
@matcher.command("hello", aliases=["hi", "你好"])
async def handle_hello(event: MessageEvent):
    """
    处理 /hello 命令
    """
    # event.reply() 是一个快捷方法，可以直接回复消息
    await event.reply(f"你好，{event.sender.nickname}！")

```

## 2. 加载插件

不用你动手，NEO Bot 启动时会自动加载 `plugins/` 目录下的所有 `.py` 文件。

## 3. 测试插件

现在，去群里或者私聊给 Bot 发送：

*   `/hello`
*   `/hi`
*   `/你好`

Bot 应该会回复你：“你好，[你的昵称]！”

## 插件剖析

### `__plugin_meta__`

这个字典不是必须的，但强烈建议写上。它定义了插件的元信息，主要给 `/help` 命令用。

*   `name`: 插件叫啥。
*   `description`: 这插件是干嘛的。
*   `usage`: 怎么用，写上具体的指令和说明。

### `@matcher.command()`

这是最核心的装饰器，用来注册一个命令处理器。

*   **第一个参数**: `name` (str)，命令的主名。
*   `aliases`: `List[str]`，命令的别名列表。
*   `permission`: `int`，执行该命令所需的权限等级，默认为 `USER` (所有人可用)。可以是 `ADMIN`, `OP`。

### 处理器函数

被 `@matcher.command()` 装饰的函数就是处理器。它必须是一个 `async` 异步函数。

*   **参数**: 框架会自动往里注入参数，你只需要用类型提示声明你需要什么。
    *   `event: MessageEvent`: 这是最常用的，包含了消息的所有信息，比如发送者、群号、消息内容等。
    *   `args: str`: 如果命令有参数（比如 `/echo hello world`），`args` 就是 `hello world` 这部分字符串。

就这么简单，一个最基础的插件就写完了。

## 极简插件开发（推荐新手）

如果你觉得上面的装饰器写法太复杂，或者只是想快速写几个简单的指令，我们提供了一种**极简模式**。
你只需要定义一个类，写几个方法，它们就会自动变成指令！

- [查看极简插件开发指南](./simple-plugin.md)

## 进阶阅读

- [指令处理](./command-handling.md): 了解如何处理参数、获取用户输入。
- [最佳实践](./best-practices.md): 学习如何编写更健壮、更高效的插件。
- [插件详解：/status 状态监控](./status-plugin.md): 深入了解内置的状态监控插件是如何实现的。