NeoBot/docs/plugin-development/simple-plugin.md

极简插件开发指南

如果你是 Python 新手，或者只是想快速写一些简单的指令，那么 SimplePlugin 是你的最佳选择。它让你无需理解复杂的装饰器和事件处理机制，只需要写普通的 Python 方法即可。

1. 快速开始

在 plugins/ 目录下创建一个新文件，例如 my_simple_plugin.py：

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

自动参数解析

框架会根据你定义的参数类型，自动解析用户输入的参数。

字符串参数

async def greet(self, event: MessageEvent, name: str):
    return f"你好, {name}"

• 发送 /greet Neo -> name 参数为 "Neo"

数字参数 (自动转换类型)

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），那么该参数会捕获指令后的所有文本。

async def broadcast(self, event: MessageEvent, content: str):
    return f"广播内容: {content}"

• 发送 /broadcast 这是一个 很长 的消息 -> content 为 "这是一个 很长 的消息"

自动回复

如果你的方法返回了字符串（str），框架会自动将其作为回复发送给用户。 如果返回 None（即没有 return 语句），则不发送回复。

async def silent(self, event: MessageEvent):
    # 执行一些操作，但不回复
    print("Silent command executed")
    # 也可以手动调用 reply
    await event.reply("手动回复")

3. 进阶用法

访问事件对象

所有方法的第一个参数（除了 self）必须是 event。通过 event 对象，你可以获取更多信息：

async def whoami(self, event: MessageEvent):
    user_id = event.user_id
    nickname = event.sender.nickname
    return f"你是 {nickname} ({user_id})"

混合使用装饰器

虽然 SimplePlugin 旨在简化开发，但你仍然可以使用装饰器来处理更复杂的场景，例如权限控制或监听非指令消息。

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()），否则插件不会生效。