Files

K2cr2O1 7880f0f928 docs: 更新文档内容并优化语言风格

重构所有文档内容，使用更简洁直接的语言风格
更新架构、插件开发、部署等核心文档
优化代码示例和图表说明
统一术语和格式规范

2026-01-13 04:09:13 +08:00

2.5 KiB

Raw Blame History

插件开发入门

写插件是给 NEO Bot 添加功能的唯一方式。这玩意儿很简单，一个 Python 文件就是一个插件。

1. 创建你的第一个插件

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

# 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 文件。

如果你是在 Bot 运行时新增或修改了插件，只需要在控制台输入 reload 命令，或者让管理员在群里发 /reload，就能热重载所有插件。

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 这部分字符串。

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

2.5 KiB Raw Blame History Unescape Escape