128 lines
4.0 KiB
Markdown
128 lines
4.0 KiB
Markdown
# 极简插件开发指南
|
||
|
||
如果你是 Python 新手，或者只是想快速写一些简单的指令，那么 `SimplePlugin` 是你的最佳选择。它让你无需理解复杂的装饰器和事件处理机制，只需要写普通的 Python 方法即可。
|
||
|
||
## 1. 快速开始
|
||
|
||
在 `plugins/` 目录下创建一个新文件，例如 `my_simple_plugin.py`：
|
||
|
||
```python
|
||
from core.plugin import SimplePlugin
|
||
from models.events.message import MessageEvent
|
||
|
||
class MyPlugin(SimplePlugin):
|
||
|
||
async def hello(self, event: MessageEvent):
|
||
"""
|
||
发送 /hello 即可调用
|
||
"""
|
||
return "你好！这是极简插件。"
|
||
|
||
async def echo(self, event: MessageEvent, msg: str):
|
||
"""
|
||
发送 /echo <内容> 即可调用
|
||
"""
|
||
return f"你说了: {msg}"
|
||
|
||
# 必须实例化插件以生效
|
||
plugin = MyPlugin()
|
||
```
|
||
|
||
就是这么简单！现在你可以发送 `/hello` 和 `/echo 测试` 来测试你的插件了。
|
||
|
||
## 2. 核心特性
|
||
|
||
### 方法即指令
|
||
|
||
在 `SimplePlugin` 的子类中，任何**不以下划线开头**的方法都会自动注册为指令。
|
||
指令名称就是方法名。
|
||
|
||
例如：
|
||
- `async def ping(self, ...)` -> 注册为 `/ping`
|
||
- `async def help_me(self, ...)` -> 注册为 `/help_me`
|
||
|
||
### 自动参数解析
|
||
|
||
框架会根据你定义的参数类型，自动解析用户输入的参数。
|
||
|
||
#### 字符串参数
|
||
```python
|
||
async def greet(self, event: MessageEvent, name: str):
|
||
return f"你好, {name}"
|
||
```
|
||
- 发送 `/greet Neo` -> `name` 参数为 `"Neo"`
|
||
|
||
#### 数字参数 (自动转换类型)
|
||
```python
|
||
async def add(self, event: MessageEvent, a: int, b: int):
|
||
return f"{a} + {b} = {a + b}"
|
||
```
|
||
- 发送 `/add 10 20` -> `a` 为 `10` (int), `b` 为 `20` (int)
|
||
- 如果用户输入非数字（如 `/add a b`），框架会自动提示参数类型错误。
|
||
|
||
#### 捕获剩余文本
|
||
如果你的方法只有一个参数（除了 `event`），那么该参数会捕获指令后的所有文本。
|
||
```python
|
||
async def broadcast(self, event: MessageEvent, content: str):
|
||
return f"广播内容: {content}"
|
||
```
|
||
- 发送 `/broadcast 这是一个 很长 的消息` -> `content` 为 `"这是一个 很长 的消息"`
|
||
|
||
### 自动回复
|
||
|
||
如果你的方法返回了字符串（`str`），框架会自动将其作为回复发送给用户。
|
||
如果返回 `None`（即没有 return 语句），则不发送回复。
|
||
|
||
```python
|
||
async def silent(self, event: MessageEvent):
|
||
# 执行一些操作，但不回复
|
||
print("Silent command executed")
|
||
# 也可以手动调用 reply
|
||
await event.reply("手动回复")
|
||
```
|
||
|
||
## 3. 进阶用法
|
||
|
||
### 访问事件对象
|
||
|
||
所有方法的第一个参数（除了 `self`）必须是 `event`。通过 `event` 对象，你可以获取更多信息：
|
||
|
||
```python
|
||
async def whoami(self, event: MessageEvent):
|
||
user_id = event.user_id
|
||
nickname = event.sender.nickname
|
||
return f"你是 {nickname} ({user_id})"
|
||
```
|
||
|
||
### 混合使用装饰器
|
||
|
||
虽然 `SimplePlugin` 旨在简化开发，但你仍然可以使用装饰器来处理更复杂的场景，例如权限控制或监听非指令消息。
|
||
|
||
```python
|
||
from core.plugin import SimplePlugin, command, on_message
|
||
from core.permission import Permission
|
||
|
||
class AdvancedPlugin(SimplePlugin):
|
||
|
||
# 普通指令
|
||
async def normal(self, event: MessageEvent):
|
||
return "普通指令"
|
||
|
||
# 使用装饰器添加权限控制
|
||
@command("admin_only", permission=Permission.ADMIN)
|
||
async def admin_op(self, event: MessageEvent, args: list[str]):
|
||
return "只有管理员能看到这个"
|
||
|
||
# 监听所有消息
|
||
@on_message()
|
||
async def handle_all(self, event: MessageEvent):
|
||
if "敏感词" in event.raw_message:
|
||
await event.reply("检测到敏感词！")
|
||
```
|
||
|
||
## 4. 注意事项
|
||
|
||
1. **方法名**：不要使用以 `_` 开头的方法名作为指令，这些方法会被忽略。
|
||
2. **参数类型**：目前支持 `str`, `int`, `float` 的自动转换。
|
||
3. **实例化**：不要忘记在文件末尾实例化你的类（`plugin = MyPlugin()`），否则插件不会生效。
|