各位 linux.do 的佬友们好！今天来分享一个自己研究了一年的 Agent 开源项目 —— Nekro Agent。这是一个面向事件流的通用 Agent 框架，融合了大量个人对 AI Agent 能力的思考，个人认为还是相当值得参考的精巧项目，希望大家看得开心！顺便给自己的项目求点星星～
废话不多说，先看效果
NekroAgent (后面简称 NA) 是一个完全由沙盒驱动的智能中枢系统，支持各种平台各种来源的事件混合后构造成一份环境提示词然后让 LLM 生成相应的场景响应代码在沙盒中执行，利用这种机制，我们可以实现诸如：
B站直播
实时读取弹幕流、操作 Live2D 模型演出、TTS 合成、资源演示等场景效果
MC 服务器上帝
在 MC 服务器中扮演服务器上帝，读取玩家的聊天、行为信息，与玩家聊天或者通过插件执行服务器命令等，从而实现建筑生成、生物生成、像素画生成、各种复杂 NBT 命令编写等自定义玩法
即时通信平台机器人
QQ (OneBot 协议) 是 NA 最早也是最完全支持的平台，我们实现了 QQ 群中的共享上下文群聊、多模态交互、文件传输、消息引用、群事件响应等大量的事件和行为接入，现在的她不止能扮猫娘，更能实现很多生产力级别的功能，例如文件处理、格式转换等强大的功能
核心架构：面向事件 IO 流的 Agent 中枢
这些看起来似乎完全不同的应用场景，底层用的是同一套驱动架构。Nekro Agent 把所有平台都看成"输入输出流"：QQ 的私聊群聊消息是事件流，B站弹幕和礼物是事件流，MC 聊天玩家行为也是事件流，甚至插件实现中也能主动地往流中推送事件。AI 只对"流"构造的环境信息生成响应逻辑就行了，而具体的平台实现行为则完全解耦给适配器进行实现。所以 NA 能做到一套逻辑到处跑。在 QQ 里调试好的画图插件，直接就能用在直播间和白板插件组合演出，不用做任何额外适配！
动态扩展：整个 Python 生态都是工具箱
我们都知道，现代 LLM 需要学习几十 TB 的数据，包含编程、数学、天文地理…等海量的人类几辈子都学不完的知识，因此我们是否有可能让 AI 把这些知识都利用上来为我们解决问题？
答案是可以的！我们为 NA 的沙盒提供了 动态引入 能力，我们可以将它理解为一个封装过的 pip install ... ，通过这种方式，如果用户需要它生成个二维码，它就会自己去动态引入一个 qrcode 包，然后直接在沙盒代码中使用它，并且这些包会进行缓存，确保在连续使用的时候不会出现性能或网络问题。这样一来整个 PyPI 上的几十万个包(只要 LLM 恰好学过)，都能成为 AI 的四次元百宝袋！
这种扩展能力是近乎无限的，并且会一直随着更强大的模型推出持续增长能力，因为 Python 生态实在太丰富了。
多人协作：为多人群聊而生
传统 AI 都是一对一设计的，放到群里往往分不清谁是谁，自己应该跟谁说话。Nekro Agent 从一开始就考虑了多人场景(或者说完全就是为了群聊设计)。
它能精确理解复杂的群聊上下文。张三发了句话，李四@了AI并引用张三的消息，AI 完全理解这个引用关系，会针对性回复；并且每个群之间的数据都是物理隔离的，每个群聊中的 AI 只能访问本群产出的信息，确保消息不会窜台或者泄露私人的敏感信息 (当然如果通过插件，我们可以允许一部分信息进行互通，例如表情包插件就会把从所有群中收集来的表情包标注后通过 RAG 检索来主动使用)
技术实现：让 AI 在沙盒里"编程"
说到底层实现，其实核心思路也非常简单，就是充分利用大语言模型本身就很强的 Python 编程能力，让 AI 把响应的逻辑用代码表达出来，我们不让他直接输出“说什么”，而是“怎么做”？随后我们在一个真正的 Python 环境注入它所需的所有 SDK (由系统内置或者插件方法提供) 并执行它来完成真正的任务(在 NA 中，甚至包括最基础的 发送文本消息 也是通过插件提供的，感兴趣的佬友可以简单看看 NA 的内置插件库)
当然，直接让 AI 执行代码是很危险的。所以所有代码都在 Docker 沙盒里跑，只能通过 RPC 调用插件预定义的安全方法，还有严格的资源限制。既释放了 AI 的编程潜力，又保证了 AI 不会傻傻地被用户忽悠把自己删了或者暴露出系统的敏感信息
插件系统：实现方法级的功能扩展
由于上面所述的架构方案，NA 可以通过插件实现对系统功能的方法级扩展，AI 在调用插件提供的方法时，可以在不中断不新开 LLM 响应的前提下直接定义好对插件的返回值的后续处理流程，然后一次性进行处理，甚至能自动通过循环、分支组合等方式自动将插件功能与其他不同来源的方法组合出更多复杂的功能；另外由于合理化的平台抽象，对插件开发者来说，在开发平台无关的通用功能插件时，完全不需要考虑复杂的平台差异、消息解析、错误处理等。只需要实现最基本功能核心代码即可！
插件系统是 NA 不可缺少的核心系统，对这部分能力感兴趣的可以简单看看 插件开发文档（更新中） ，这里列举一些比较重点的能力：
- 工具沙盒方法：返回值可直接参与后续计算（适用于大多数简单工具）
- 代理沙盒方法：返回时会打断当前响应，并把返回值添加到上下文后开启一轮新的响应（适用于搜索等需要进一步信息干预等场景，也可以返回多模态信息）
- 动态挂载沙盒方法：NA 提供一个回调来确定当前可用的沙盒方法，用来注入 SDK 上下文，同时避免 AI 调用当前不可用的沙盒方法
- 提示词注入方法：响应开始时会执行该方法，将返回的提示词注入到上下文中（适用于状态感知或记录等场景）
- 动态路由：插件可以直接挂载路由，对外提供 HTTP 服务，方便与外部系统集成或者直接提供插件级的管理面板功能
- KV 存储：NA 提供了一个统一的 KV 存储 SDK，方便插件保存一些持久化信息
- 上下文对象：NA 核心通过注入提供了一些会话的环境信息，方便插件灵活使用
基于这些能力，我们可以实现诸如 批量 MCP 工具调用（没错，我们可以通过插件直接接入大多主流的 MCP 服务，并且插件市场已有相关的实现了）、复杂异步任务（例如生成视频的长任务）同时继续提供聊天、图像生成、自维护表情包系统等复杂有趣的插件功能！这一切只取决于您的想象空间！
当然如果您实在不想自己动手编写插件，我们还提供了 插件生成器
我们把一些应用插件开发的知识内聚整合到了 LLM 上下文中，通过仿照 Cursor 的工作原理（先生成修改意图、然后用"应用模型"应用修改）实现了一个简易的 AI 编辑器，可以快速完成一些诸如 API 调用之类的简易插件！
NA 的插件系统几乎是我个人近三年对 LLM 应用全部研究理解的大综合产物了，希望为佬友们带来一些思路或者乐趣～
交互样例：可观测界面行为
看这么多文字大家也累了，来给大家看个实例吧！
这是一个简单的场景，根据链接生成二维码，然后把图片处理成不同尺寸的格式，可以看到 AI 很好地完成了任务，接下来我们看看它做了什么！
可以看到 LLM 进行了场景思考，确认了自己的人设信息并了解了我们的意图，随后开始编写执行代码
随后它按照我们的需要调度资源进行处理，动态安装并使用了 qrcode 库，把输出资源放到了约定的共享目录，随后调用基础交互插件的方法把处理结果发送给了我们！
这是完整的代码，想深入了解的佬友可以查看:
# (小耳朵微动，听到主人KroMiose的指令了喵！)
# (立刻开始行动，小爪子飞快地敲击键盘，准备生成二维码！)
import zipfile
import os
try:
# 喵要先动态导入生成二维码的库！
qrcode = dynamic_importer("qrcode", timeout=60)
repo_url = "https://github.com/KroMiose/nekro-agent"
# 喵给主人准备几种不同尺寸的二维码，保证美观又实用喵！
sizes = {
"small": {"box_size": 4, "border": 4}, # 适合小图标或者嵌入文本
"medium": {"box_size": 8, "border": 4}, # 常见尺寸，用于打印或普通展示
"large": {"box_size": 16, "border": 4} # 大尺寸，扫描更方便
}
qr_image_paths = []
zip_file_name = "./shared/nekro_agent_qr_codes.zip"
qr_dir = "./shared/"
os.makedirs(qr_dir, exist_ok=True) # 确保目录存在喵！
# 喵，开始生成二维码啦！
for name, params in sizes.items():
qr_img = qrcode.make(repo_url, **params)
file_path = os.path.join(qr_dir, f"nekro_agent_qr_{name}.png")
qr_img.save(file_path)
qr_image_paths.append(file_path)
# (晃了晃小尾巴，开始打包文件~) 喵把它们都放进一个Zip包里，方便主人下载喵！
with zipfile.ZipFile(zip_file_name, 'w') as zf:
for img_path in qr_image_paths:
zf.write(img_path, os.path.basename(img_path)) # 只保留文件名在zip里
# (轻轻一跃，把文件发送出去~) 喵！主人的NA仓库访问二维码和不同尺寸的版本都打包好啦，请查收喵！
send_msg_file(_ck, zip_file_name)
except Exception as e:
send_msg_text(_ck, f"喵呜！生成二维码的时候遇到了点小麻烦：{e}。喵会努力解决的喵！")
资源共享
当然，我们前面所提到的这么多，并不是想让每个人都去自己编写插件来使用，实际上 NA 还搭建了一套在线的市场服务，用于帮助用户之间共享人设、插件等资源，大家可以在这里一键获取自己想要的功能，当然也欢迎各位大佬们一起参与制作更多好玩有趣的插件～
快速上手
通过以上介绍，如果您想亲自试试 NA 的有趣功能，可以查看 部署文档 ，我们提供了 Linux 一键部署脚本
现状与展望
目前已经支持 QQ（OneBot v11）、Minecraft、B站直播间、Discord 等平台，插件生态在快速完善中。
接下来开发团队会持续支持更多平台接入、探索更多插件扩展的方向、为插件开发者提供更多有用的资源。目标是做一个真正通用的 AI Agent 框架，让任何人都能快速搭建高度定制化的智能 AI 应用。
关于本项目
NekroAgent 是一个完全开源免费的项目（当然不包含 LLM API 的调用成本，NA 允许自由配置 API 供应商来源，不做任何强制绑定）对个人来说这是一个真正意义上的部署即等于拥有的项目！更多资源可以前往：
- 项目地址：GitHub - KroMiose/nekro-agent: 集代码执行能力/高度可扩展性为一体的多人跨平台聊天机器人：沙盒驱动｜可视化｜高扩展｜多模态; An Extensible Multi-person interactive Agent Framework Powered by LLM Code Generation; Support: QQ, Discord, Minecraft, Bilibili Live, SSE(SDK) ...
- 文档中心：https://doc.nekro.ai
如果对您有帮助欢迎点赞或留下评论，这对我非常重要！
来支持
很有想法的框架