跳到主要内容

插件使用

本模块为实现 Maa 的部分拓展功能，通过侧载插件的方式提供额外能力。插件与主程序独立更新，缺少某个插件时对应功能会自动禁用，不影响主程序正常运行。

插件是什么​

插件是独立于主程序的功能模块，以标准化的目录结构存放在 agent/plugins/ 目录下。程序启动时会自动扫描并加载所有已安装的插件，同时自动安装插件所需的依赖。

目前可用的插件​

目前插件均还在开发中，作者开发的插件目前均会放在 协会组织仓库 中

安装方式​

第一步：获取插件​

从插件的 Release 页面 下载对应的插件压缩包，形如 example_plugin-1.0.0.zip

第二步：放置插件​

将下载的插件文件夹解压到Maa小助手主程序目录下的 agent/plugins/ 中。以抓包插件为例，正确的目录结构如下：

agent/
└── plugins/
    └── example_plugin/
        ├── plugin.json
        ├── lib/
        │   └── example_plugin.pyz
        └── deps/
            ├── scapy-xxx.whl
            └── ...
注意

请确保插件文件夹直接位于 agent/plugins/ 下，不要多套一层目录。

第三步：启动程序​

正常启动程序即可。程序会自动完成以下操作：

  1. 扫描 agent/plugins/ 目录，发现已安装的插件
  2. 检查插件所需的依赖是否已安装
  3. 自动从插件的 deps/ 目录安装缺失的依赖
  4. 加载插件并启用对应功能
提示

首次加载插件时，依赖安装可能需要等待一小段时间，属于正常现象。

使用方式​

插件加载成功后，对应的功能会自动启用，无需额外操作。

以抓包插件为例，加载成功后程序即可实时获取玩家位置、身份等信息，用于辅助其他功能模块。

如何确认插件已加载​

  • 程序启动日志中会显示插件加载结果
  • 加载成功时会出现类似 成功加载插件: example_plugin 的日志
  • 加载失败时会出现警告信息，并说明失败原因

插件未安装时​

如果某个插件未安装，依赖该插件的功能会自动禁用。程序本身仍然可以正常使用其他功能。

插件更新​

  1. 从 Release 页面下载新版本的插件压缩包
  2. 将新版本的插件文件夹覆盖到 agent/plugins/ 目录中对应的旧文件夹
  3. 重启程序，新版本插件会自动加载
信息

插件更新不需要更新主程序，两者可以独立更新。

注意事项​

  • 每个插件可能有各自的系统要求，请参考插件文件夹中的 plugin.json 或对应的说明
  • 抓包插件需要 Windows 系统，并且需要提前安装 Npcap，程序需以管理员权限运行
  • 不要手动修改插件目录中的文件，可能导致插件无法正常加载
  • 如果插件加载失败，请检查日志中的错误信息，常见原因包括：
    • 插件目录结构不正确
    • 系统依赖缺失（如未安装 Npcap）
    • .pyz 文件损坏