Skip to content

Latest commit

 

History

History
295 lines (204 loc) · 10 KB

插件开发文档.md

File metadata and controls

295 lines (204 loc) · 10 KB

插件开发文档

本文档旨在详细描述如何创建与加载符合要求的单文件插件和文件夹插件。在继续之前，请确保你已熟悉 Python 的基本语法和模块导入机制。

1. 单文件插件要求

单文件插件是以一个 Python 文件形式存在的插件，必须满足以下条件才能被插件管理器正确加载和执行。

1.1 文件命名和存放位置

  • 命名规则: 单文件插件的文件名应简洁且清晰，要求必须以 p_ 开头，通常使用小写字母,加入下划线分隔（如 p_example_plugin.py ,p_echo.py）。
  • 存放位置: 所有单文件插件应放置在指定的插件目录（plugins/example 文件夹）中。
  • 禁止前缀: 文件名不能以下划线 _ 开头（例如 _example.py 将被忽略）。以 u_ 开头（例如 u_example.py ）将被视为已卸载（停用）插件。

1.2 文件结构

每个单文件插件必须定义一个与文件名对应的插件类，且该类名必须以 P_ 开头，并以 Plugin 结尾。例如，echo.py 文件应包含一个 P_echoPlugin 类。

1.2.1 插件类定义

  • 插件类名: 类名应以 P_ 开头，并以 Plugin 作为后缀。例如，echo.py 的插件类应为 P_echoPlugin。

    • 注: P_echoPlugin 中的 echo 应为全小写

  • 类的构造函数 (__init__):

    • 参数: 接受一个 bot 实例，该参数将被插件用于调用机器人的功能。
    • 初始化: 在构造函数中进行必要的初始化设置。

  • 必需的方法:

    • on_message(self, message): 每个插件类必须异步定义此方法，用于处理传入的消息。message 参数通常是一个字典，包含消息的相关信息。

1.2.2 插件类示例

# plugins/example/p_echo.py
from plugin_base import Plugin
import logging
from api.send import send_msg

logger = logging.getLogger("bot")

class P_echoPlugin(Plugin):
    def __init__(self, bot):
        logger.info("p_echo 插件正在初始化...")
        self.bot = bot

    async def on_message(self, message):
        user_id = message['user_id']
        raw_message = message['raw_message']
        message_type = message.get('message_type', '')  # 获取消息类型，默认为空字符串

        # 仅复读私聊消息
        if message_type == 'private':  # 这里的 'private' 需要根据实际消息类型值来调整

            # 复读消息
            send_msg(self.bot.base_url, "private", user_id, raw_message, self.bot.token)
            logger.info("Echo 插件成功复读消息\n")
        else:
            #logger.info("Echo 插件忽略群组消息\n", message)
            pass

1.3 插件行为和日志

  • 日志记录: 插件应在适当的地方添加日志，以便在插件加载、消息处理等过程中记录信息。
  • 异常处理: 插件应尽量捕获并处理可能的异常，以避免影响其他插件或整个系统的运行。

2. 文件夹插件要求

文件夹插件是一个更复杂的插件结构，通常用于需要包含多个文件或子模块的插件。

2.1 文件夹命名和结构

  • 命名规则: 文件夹插件的名称应遵循 p_ 前缀规则，使用小写字母和下划线分隔（如 p_example）。
  • 入口文件: 文件夹内必须包含一个名为 main.py 的文件作为插件的入口点。
  • 禁止前缀: 文件夹名称不能以下划线 _ 开头（例如__pycache__ 将被忽略），以 u_ 开头（例如 u_test ）将被视为已卸载（停用）插件。

2.2 入口文件 (main.py)

  • main.py 定义: 作为插件的入口文件，main.py 必须定义一个与文件夹名称对应的插件类，且该类名首字母大写并以 Plugin 结尾。
  • 导入插件基类: 插件类应该继承自 Plugin 基类，确保一致性和可扩展性。

2.2.1 插件类定义

  • 插件类名: 类名应以 P_ 开头，并以 Plugin 作为后缀。例如，p_example 文件夹的插件类应为 P_examplePlugin。

    • 注: P_examplePlugin 中的 example 应为全小写，不得有如 exampleApple ， P_exampleApplePlugin 这样的写法。

  • 类的构造函数 (__init__):

    • 参数: 接受一个 bot 示例，该示例将被插件用于调用机器人的功能。
    • 初始化: 在构造函数中进行必要的初始化设置。

  • 必需的方法:

    • on_message(self, message): 每个插件类必须异步定义此方法，用于处理传入的消息。message 参数通常是一个字典，包含消息的相关信息。

2.2.2 插件类示例

# plugins/p_example/main.py
from plugin_base import Plugin
import logging

logger = logging.getLogger("p_example")

class P_examplePlugin(Plugin):
    def __init__(self, bot):
        self.bot = bot

    async def on_message(self, message):
        logger.info("P_example 插件接收到消息: %s", message)

2.3 初始化文件 (__init__.py)

  • 用途: __init__.py 文件通常用于初始化插件模块或定义全局变量。对于文件夹插件，该文件并非必须，但建议包含以下内容：
    • 日志配置: 设置模块的日志配置，以便调试和监控。
    • 版本信息: 可以包含插件的版本信息和作者信息。

2.3.1 __init__.py 示例

# plugins/p_example/__init__.py
import logging

logger = logging.getLogger("p_example")

__version__ = "1.0.0"
__author__ = "Your Name"

#其他内容可选

logger.info("p_example 插件包正在初始化...")

2.4 插件行为和日志

  • 日志记录: 插件应在适当的地方添加日志，以便在插件加载、消息处理等过程中记录信息。
  • 异常处理: 插件应尽量捕获并处理可能的异常，以避免影响其他插件或整个系统的运行。

2.5 插件示例

2.5.1 插件文件夹结构

plugins/
├── p_example/
│   ├── __init__.py
│   ├── main.py
|   └── ...

2.5.2 插件入口文件 main.py

# plugins/p_example/main.py
from plugin_base import Plugin
import logging

logger = logging.getLogger("p_example")

class P_examplePlugin(Plugin):
    def __init__(self, bot):
        self.bot = bot

    async def on_message(self, message):
        logger.info("P_example 插件接收到消息: %s", message)

2.5.3 初始化文件 __init__.py

# plugins/p_example/__init__.py
import logging

logger = logging.getLogger("p_example")

__version__ = "1.0.0"
__author__ = "Your Name"

logger.info("p_example 插件包正在初始化...")

结论

通过遵循上述规则，你可以确保你的插件能够被插件管理器正确加载和使用。单文件插件和文件夹插件都有其特定的结构和要求，请根据你的实际需求选择合适的插件类型进行开发。插件的可扩展性和健壮性至关重要，因此在开发过程中应保持代码整洁并遵循良好的编程实践。

最后一次编辑

  • 24/09/01 Yei_J_




.

注意事项

  • 有关插件名冲突

    • 单文件插件允许与多文件插件重名。例如：允许同时存在 plugins\p_echo 与 plugins\example\p_echo.py
    • 单文件插件允许与多文件插件类名相同。
      例如，允许 plugins\p_echo\main.py 与 plugins\example\p_echo.py 同时使用P_echoPlugin作为类名：\
    class P_echoPlugin(Plugin):
  def __init__(self, bot):
      self.bot = bot

  async def on_message(self, message):

  • 有关插件运行时机

    • 在单文件插件与多文件插件的构造函数 __init__ ，以及多文件插件的 __init__.py 中的逻辑会在插件加载器加载插件时执行，例如：\

      # plugins/p_test/__init__.py

logger.info("💡 p_echo (文件夹) 插件包已初始化")

      输出

      [11:36:06] INFO - -*-*-*-*-*-*-*-*-*-*-*-*-*-*-||
[11:36:06] INFO - 正在启动插件管理器...

  ...

[11:36:06] INFO - -----------------------------
[11:36:06] INFO - 💡 p_echo (文件夹) 插件包已初始化
[11:36:06] INFO - ✔️ 插件 p_echo 加载成功
[11:36:06] INFO - -----------------------------

  ...

[11:36:06] INFO - ✔️所有插件均已成功加载
[11:36:06] INFO - -----------------------------||

      所以请不要在这一部分添加过多对log识别易产生干扰的逻辑。

  • 有关插件版本号

    • 多文件插件请在 __init__.py 文件第二行使用 # __version__ = "1.0.0" 声明版本号，第三行使用 # __name__ = "一个测试插件" 声明插件的名字。例如 plugins/p_test/__init__.py 是这样的：

      # plugins/p_test/__init__.py
# __version__ = "1.0.0"
# __name__ = "一个测试插件"
# __project__ = "项目地址（如有）"

import logging

logger = logging.getLogger("p_test")

__version__ = "1.0.0"
__author__ = "Yei_J_"

logger.info("p_test 插件包正在初始化...")

    • 单文件插件同样在在文件第二行以

      # plugins\example\p_echo.py
# __version__ = "1.0.0"
# __name__ = "一个测试插件"
# __project__ = "项目地址（如有）"

      的形式声明。

  • 有关日志记录

    • 项目根目录的 logs 文件夹用于记录在项目运行时，必须调用 logging 库所产生的日志。类似如 print 或其他方法输出的日志不会被保存在日志文件中。

      例如：

      import logging  # 导入 logging 库

logger = logging.getLogger("p_test")  # 调用该库

logger.info("p_test 插件包正在初始化...")  #输出 info 级别的日志

    • 注： 日志文件只保留最新的 30 个。

  • 更多方法