NekroAgent 文档

简体中文

English
日本語

简体中文

English
日本語

Appearance

快速上手 ​

本章节将引导您快速搭建插件开发环境，并创建您的第一个 Nekro Agent 插件。

开发环境准备 ​

在开始之前，请确保您已经安装并成功运行了 Nekro Agent。插件开发通常在 Nekro Agent 项目的 plugins/workdir/ 目录下进行。

您需要：

  1. Python 环境：与 Nekro Agent 主程序兼容的 Python 版本（通常为 Python 3.10+）。
  2. Nekro Agent 源码或已安装实例：方便查看核心代码和 API 定义。
  3. 代码编辑器：如 VSCode、PyCharm 等，用于编写插件代码。

创建您的第一个插件: "Hello Plugin" ​

让我们创建一个简单的插件，它会提供一个沙盒方法，当被调用时返回 "Hello from Plugin!"。

1. 创建插件目录和文件 ​

在 Nekro Agent 的插件工作目录（通常是 plugins/workdir/）下，创建一个新的插件目录，例如 hello_plugin。

plugins/
└── workdir/
    └── hello_plugin/
        ├── __init__.py
        └── plugin.py
  • __init__.py: 这个文件至关重要。它使得 hello_plugin 目录可以被 Python 视为一个包。更重要的是，Nekro Agent 的插件加载机制通常会从这个 __init__.py 文件中查找并导入 NekroPlugin 的实例。如果您的 NekroPlugin 实例（通常命名为 plugin）定义在同目录下的 plugin.py 文件中，那么 __init__.py 必须从 plugin.py 导入并导出该实例。其内容应如下：
    python
    # hello_plugin/__init__.py
from .plugin import plugin

# 可选，但推荐，用于明确导出的接口
__all__ = ["plugin"]
  • plugin.py: 这是我们插件的核心代码文件，其中定义了 NekroPlugin 实例以及相关的沙盒方法、配置等。

2. 编写插件核心代码 (plugin.py) ​

打开 hello_plugin/plugin.py 文件，并输入以下内容：

python
from nekro_agent.api.plugin import NekroPlugin, SandboxMethodType
from nekro_agent.api.schemas import AgentCtx

# 1. 创建插件实例
plugin = NekroPlugin(
    name="你好插件",  # 插件在 UI 中显示的名称
    module_name="hello_plugin",  # 插件的模块名，应与目录名一致且唯一
    description="一个简单的 Hello World 插件示例。",
    author="您的名字",
    version="0.1.0",
    url="https://your.plugin.repo.url" # 必填，插件的仓库或主页地址
)

# 2. 注册一个沙盒方法
@plugin.mount_sandbox_method(
    method_type=SandboxMethodType.TOOL, # 方法类型为 TOOL，结果直接返回给 AI
    name="say_hello",
    description="返回一个问候语。"
)
async def say_hello_from_plugin(_ctx: AgentCtx) -> str:
    """插件的问候方法

    不需要任何参数，直接返回一个固定的问候字符串。

    Returns:
        str: "Hello from Plugin!"
    """
    return "Hello from Plugin!"

# 您可以在这里添加更多的插件逻辑，如配置、初始化方法等

代码解释：

  • from nekro_agent.api.plugin import NekroPlugin, SandboxMethodType: 导入了创建插件实例和定义沙盒方法类型所需的核心类。
  • from nekro_agent.api.schemas import AgentCtx: 导入了 AgentCtx，它是沙盒方法和许多其他插件回调函数的标准上下文参数，包含了会话信息等。
  • plugin = NekroPlugin(...): 创建了一个 NekroPlugin 类的实例。您需要提供插件的名称、模块名、描述等基本信息。
    • name: 用户在界面上看到的插件名称。
    • module_name: 插件的唯一标识符，通常与您的插件目录名一致。
    • description: 插件的简短描述。
    • author: 插件作者名。
    • version: 插件版本号。
    • url: 插件的仓库或主页地址（必填）。
    • support_adapter: 可选，限制插件只在指定适配器下生效，如 ["onebot_v11"]。
    • is_builtin: 可选，是否为内置插件（默认 False）。
    • is_package: 可选，是否为云端包插件（默认 False）。
    • i18n_name / i18n_description: 可选，插件名称/描述的国际化字典。
    • allow_sleep: 可选，是否允许插件休眠（None 表示跟随全局设置）。
    • sleep_brief: 可选，插件休眠时的简要描述。
  • @plugin.mount_sandbox_method(...): 这是一个装饰器，用于将一个函数注册为插件的沙盒方法。AI 可以通过沙盒环境调用这些方法。
    • method_type=SandboxMethodType.TOOL: 指定了这个方法是一个"工具"类型的方法。这类方法的返回值会直接提供给 AI 使用。可用的方法类型有：
      • SandboxMethodType.TOOL — 工具方法，返回值直接给 AI 读取。
      • SandboxMethodType.AGENT — Agent 方法，调用后会再次触发 LLM 推理（返回内容作为新的 user 消息）。
      • SandboxMethodType.BEHAVIOR — 行为方法，执行后不会触发再次 LLM 调用（适合纯副作用操作）。
      • SandboxMethodType.MULTIMODAL_AGENT — 多模态 Agent 方法，可返回多模态消息并触发再次推理。
  • async def say_hello_from_plugin(_ctx: AgentCtx) -> str:: 定义了沙盒方法的实际执行逻辑。
    • 它是一个异步函数 (async def)。
    • 第一个参数必须是 _ctx: AgentCtx。
    • 类型注解 -> str 表明它返回一个字符串。
    • 文档字符串 (docstring) 详细描述了方法的功能、参数和返回值，这对于 AI 正确使用该方法至关重要。

3. 加载和测试插件 ​

  1. 启动/重启 Nekro Agent： 如果您是在 plugins/workdir/ 目录下创建的插件，Nekro Agent 在启动时通常会自动扫描并加载该目录下的所有插件。 如果 Agent 已经在运行，您可能需要重启 Agent 或通过其管理界面重新加载插件。

  2. 在 Agent 中测试： 加载成功后，您就可以在与 Nekro Agent 的对话中尝试调用这个插件方法了。例如，您可以对 Agent 说： "调用 say_hello_from_plugin 方法" 或者更自然地： "让 hello_plugin 说你好"

    Agent 的 AI 模型会根据您的指令，结合函数中的文档字符串，决定是否以及如何调用 say_hello_from_plugin 方法。如果调用成功，AI 应该会告诉您插件返回了 "Hello from Plugin!"。

    您也可以通过指令调用代码：

    python
    /exec say_hello_from_plugin()

    发送指令前确保机器人也处在同一会话内

恭喜！您已经成功创建并测试了您的第一个 Nekro Agent 插件。

在接下来的章节中，我们将深入学习插件的各项核心概念和高级功能。

插件目录结构说明 ​

插件可以从以下三个位置加载：

  • plugins/workdir/ — 工作目录插件（开发时使用）
  • 内置插件目录 — 随 Nekro Agent 一起分发的内置插件
  • 云端包插件目录 — 从插件市场安装的插件包

注意：插件也可以是单个 .py 文件，不必是目录包。只要文件中定义了 NekroPlugin 实例并正确导出即可。

可用的 API 模块 ​

插件开发中可通过 nekro_agent.api 导入以下模块：

模块说明
nekro_agent.api.plugin插件核心类（NekroPlugin、SandboxMethodType、PluginStore 等）
nekro_agent.api.schemas类型定义（AgentCtx、WebhookRequest 等）
nekro_agent.api.message消息发送（send_text、send_image、send_file、push_system）
nekro_agent.api.timer一次性定时器（set_timer、get_timers、clear_timers）
nekro_agent.api.recurring_timer周期定时器（add_job、update_job、list_jobs 等）
nekro_agent.api.core核心功能（logger、config、get_qdrant_client）
nekro_agent.api.i18n国际化工具（i18n_text、I18nDict）
nekro_agent.api.signal信号定义（MsgSignal）
发现文档问题？报告问题