K2cr2O1
7f331970dd
- 简化插件开发指南中的描述，移除冗余内容 - 调整部署文档中的Python版本说明 - 优化最佳实践文档的措辞和格式 - 更新性能优化文档，删除不准确的数据 - 重构核心概念文档，使用更简洁的语言 - 修正README中的项目描述和技术栈说明 - 更新快速上手文档，简化安装步骤 - 调整事件流转文档的描述方式 - 简化架构文档内容 - 更新指令处理文档，添加参数注入示例 - 优化单例管理器文档的表述
75 lines
2.4 KiB
Markdown
75 lines
2.4 KiB
Markdown
# 插件开发入门
|
||
|
||
写插件是给 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` 这部分字符串。
|
||
|
||
就这么简单，一个最基础的插件就写完了。
|