插件开发入门文档

如果你想让 N.E.K.O 多做一件事，插件通常是最简单的起点。插件可以看作一个小型 Python 项目：它用 plugin.toml 介绍自己，再通过 NekoPluginBase 子类提供具体功能。开始制作插件之前，不需要先读懂整个 N.E.K.O 项目或理解它的内部架构。

先认识两个文件

CLI 会自动创建常用的项目结构。刚开始时，只需要关注两个文件：

plugin/plugins/hello_world/
├── plugin.toml   # 插件 ID、名称、版本和 Python 类
└── __init__.py  # 插件提供的功能

plugin.toml 告诉 N.E.K.O 这是哪个插件，以及应当加载哪个 Python 类。__init__.py 中的 @plugin_entry 等装饰器，则把具体功能开放给用户、Agent 或宿主调用。

一个最小的插件功能是这样的：

from plugin.sdk.plugin import NekoPluginBase, Ok, neko_plugin, plugin_entry


@neko_plugin
class HelloWorldPlugin(NekoPluginBase):
    @plugin_entry(id="hello", name="Hello", description="Say hello")
    async def hello(self, name: str = "World", **_):
        return Ok({"message": f"Hello, {name}!"})

运行时入口使用 async def，并返回 Ok(...) 或 Err(...)。配置、定时任务、生命周期、消息、存储和 UI 等能力，可以等插件真正需要时再添加。

插件怎样运行

plugin.toml → 加载插件类 → 注册插件入口 → 启动插件进程
                                           ↓
                              调用某个入口 → Ok / Err

这里有两种容易混淆的“入口”：plugin.toml 中的 [plugin].entry 指向 N.E.K.O 要加载的 Python 类；@plugin_entry 声明的 hello 等 ID，则代表插件启动后可以调用的具体功能。

完成第一个插件

1. 运行 uv run neko-plugin init <plugin_id> --type plugin --name "<插件名称>" 创建插件。
2. 打开生成的 plugin.toml 和 __init__.py。
3. 添加或修改一个异步的 @plugin_entry 函数。
4. 运行 uv run neko-plugin check <plugin_id> 和生成的测试。
5. 在 N.E.K.O 的插件页面中刷新插件列表，再启动插件并触发入口；后续修改可以重载正在运行的插件。
6. 准备分享给其他用户时，再构建 .neko-plugin 安装包。

开发时，把随包代码和资源视为只读内容。配置通过 self.config 管理，需要保留的数据使用 self.data_path(...)，可以重新生成的缓存使用 self.cache_path(...)。

快速开始会带你完整做出并运行一个 Hello World 插件。完成后再阅读插件配置和入口与参数；其余页面都是按需查阅的参考资料，不需要一开始全部看完。