feat(plugin): 新增极简插件开发模式
新增 SimplePlugin 基类,提供面向新手的极简插件开发方式 添加相关示例代码和文档说明
This commit is contained in:
127
docs/plugin-development/simple-plugin.md
Normal file
127
docs/plugin-development/simple-plugin.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# 极简插件开发指南
|
||||
|
||||
如果你是 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()`),否则插件不会生效。
|
||||
Reference in New Issue
Block a user