N.E.K.O.插件SDK v2开发完全指南进程隔离、装饰器API、Result类型与push_message实战【免费下载链接】N.E.K.OA catgirl who lives with you in real time — reaching out first, sharing your media, and actually getting things done, powered by an embodied emotional engine.❤️一只会主动找你玩的 AI 猫娘。项目地址: https://gitcode.com/gh_mirrors/ne/N.E.K.ON.E.K.O 是一只会主动找你玩的 AI 猫娘而它的「插件 SDK v2」正是让猫娘学会新技能的扩展系统。本指南面向新手开发者用最短的篇幅讲清 N.E.K.O 插件开发的核心进程隔离、装饰器 API、**Result 类型Ok/Err**和push_message 消息推送四大要点帮你从零写出第一个能主动开口说话的插件。一、N.E.K.O 插件是什么一句话插件就是运行在独立进程里的小 Python 项目通过装饰器声明功能通过消息总线与猫娘对话。SDK v2 支持两种包类型类型导入路径适用场景Pluginplugin.sdk.plugin独立功能搜索、提醒、音乐推送99% 的开发者选这个Adapterplugin.sdk.adapter桥接外部协议MCP、NoneBot 等完整的官方教程见 plugin/PLUGIN_DEVELOPMENT_GUIDE.mdSDK 入口在 plugin/sdk/plugin/。二、为什么进程隔离是 SDK v2 的灵魂N.E.K.O 的架构非常「稳」主进程Host负责插件生命周期管理、Bus 事件系统与 ZMQ IPC 传输每个 Plugin 或 Adapter 都运行在自己的独立进程中通过 ZMQ IPC 与主系统通信。这意味着✅崩溃隔离你的插件崩了猫娘照常营业其他插件也不受影响✅依赖隔离插件可以装自己的第三方库不污染主环境✅安全边界插件读写只能落在宿主分配给它的data/与cache/目录宿主侧的进程管理与消息平面实现在 plugin/core/ 与 plugin/message_plane/对开发者完全透明——你只需专注写业务逻辑。三、30 秒上手两个文件写出第一个插件新建插件只需要两个文件plugin/plugins/hello_world/ ├── plugin.toml # 插件清单id、版本、入口类 └── __init__.py # 插件功能代码plugin.toml声明插件身份可参考内置插件 plugin/plugins/memo_reminder/plugin.toml__init__.py则用装饰器暴露功能from plugin.sdk.plugin import NekoPluginBase, Ok, neko_plugin, plugin_entry neko_plugin class HelloWorldPlugin(NekoPluginBase): plugin_entry(idhello, name打招呼, descriptionSay hello) async def hello(self, name: str World, **_): return Ok({message: fHello, {name}!})关键约定记住三条运行时入口必须async def、返回值必须是Ok/Err、类上必须有neko_plugin。四、装饰器 API 速查表SDK v2 用一套优雅的装饰器覆盖了插件的全部能力装饰器作用典型用法neko_plugin注册插件类必须标记入口类plugin_entry定义可被外部调用的功能入口带input_schema做参数校验lifecycle生命周期钩子startup/shutdown/reload等timer_interval定时任务每小时自动清理、心跳上报message响应主系统消息监听聊天、弹幕等来源before_entry/after_entry/around_entry/replace_entryHook 切面编程拦截入口做鉴权、计时、统计例如给所有入口加一层耗时统计around_entry(target*, priority0) async def timing(self, *, proceed, args, **_): start time.time() result await proceed(**args) self.logger.info(f耗时 {time.time() - start:.2f}s) return result想要更简洁的写法也可以用命名空间风格plugin.entry(...)/plugin.timer(...)。五、Result 类型告别异常流的错误处理SDK v2 采用 Rust 风格的Ok/Err类型让错误处理变得显式且类型安全# 成功 return Ok({message: done}) # 失败 return Err(SdkError(name 不能为空)) # 消费其他插件的返回结果 result await self.plugins.call_entry(other_plugin:do_work, {k: v}) if isinstance(result, Ok): data result.value else: self.logger.error(f调用失败: {result.error})两个小工具能大幅提升体验unwrap(result)出错即抛异常和unwrap_or(result, 默认值)出错给兜底值。跨插件调用、持久化存储self.store.set/get等所有异步 API 都遵循这一约定——先看Ok还是Err再取数据。六、push_message 实战让猫娘开口说话push_message是插件向主系统唯一的消息推送入口v2 schema 源文件plugin/sdk/shared/core/push_message_schema.py设计细节见 docs/changelog/plugin-push-message-v2.md。v2 用两条正交轴替代了旧的message_typevisibility— 用户在哪看到内容[chat]聊天气泡、[hud]通知面板、[]用户不直接看到ai_behavior— 猫娘 AI 怎么处理respond立即接茬回复、read静默记入上下文、blindAI 完全不知情parts— OpenAI 风格的多模态内容列表text/image/audio/video/ui_action几个最常用的组合# 1. 最常用让猫娘 AI 立刻回应这条事件 self.push_message(parts[{type: text, text: {MASTER_NAME} 给你发了新消息}]) # 2. 安静通知不打断对话下次用户开口时猫娘自然提及 self.push_message(visibility[], ai_behaviorread, parts[{type: text, text: 后台任务已完成}]) # 3. 纯前端音乐卡片AI 不知情聊天框直接渲染播放按钮 self.push_message( visibility[chat], ai_behaviorblind, parts[{type: ui_action, action: media_play_url, url: song_url, media_type: audio}], )两个新手高频坑大图片不要 inline整条 payload 上限 512 KiB大图请改用await self.images.upload(...)走独立上传通道别硬编码主人/用户文本里写{MASTER_NAME}/{LANLAN_NAME}占位符宿主会按会话自动替换成真实名字多角色场景也不会失真。七、发布前检查清单 所有入口返回Ok/Err而不是裸 dict 或异常入口参数有input_schema或 Pydanticparams签名明确声明用到的字段定时器与入口共享的状态用锁保护跨插件调用处理了Err分支shutdown钩子里优雅关闭会话与连接plugin.toml的entry路径与 SDK 版本约束正确写在最后N.E.K.O 插件 SDK v2 的设计哲学可以浓缩成一句装饰器声明功能Result 承载结果push_message 驱动对话进程隔离保证稳定。内置的 plugin/plugins/web_search/、plugin/plugins/mcp_adapter/ 都是很好的对照范本。现在打开你的编辑器让猫娘学会第一个新技能吧✨【免费下载链接】N.E.K.OA catgirl who lives with you in real time — reaching out first, sharing your media, and actually getting things done, powered by an embodied emotional engine.❤️一只会主动找你玩的 AI 猫娘。项目地址: https://gitcode.com/gh_mirrors/ne/N.E.K.O创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考