# Nekro Agent - 更智能、更优雅的代理执行 AI
Switch to [English](./README_en.md)
## 💬 社区与贡献
我们很高兴地宣布,我们正在计划进行国际化改造,以更好地支持我们的全球社区。我们欢迎来自世界各地的开发者加入我们的行列。
来我们的官方 Discord 服务器上与我们聊天,分享您的想法,成为 Nekro Agent 未来的重要一员!
- **加入我们的 Discord:** [NekroAI Official](https://discord.gg/eMsgwFnxUB)
## 🚀 核心能力
NekroAgent 通过强大灵活的提示词构建系统,引导 AI 生成准确的代码并在沙盒中执行,通过 RPC 通信来与真实环境交互。主要特点包括:
**核心执行与扩展能力:**
- **代码生成与安全沙盒**:引导 AI 生成代码并在安全的容器化环境中执行,实现复杂任务与方法级扩展性的坚固基石!
- **高度可扩展的插件系统**:提供多种关键节点回调、提示词注入、自定义沙盒方法,从小型工具扩展到大型系统优雅集成的超智能中枢解决方案!
- **原生多人场景互动**:高效洞悉群聊场景需求,在复杂的多人对话中保持交互能力!
- **极致的降本增效**:拒绝无效提示词与滥用迭代智能体,聚焦解决问题的逻辑根本。
- **自动纠错与反馈**:深耕提示词纠错与反馈机制,打破困于错误与重复的循环。
**连接与交互:**
- **多平台适配器架构**:原生支持 `OneBot v11` (QQ)、`Discord`、`Telegram`、`Minecraft`、`B站直播`、`微信`、`邮件` 及 `SSE+SDK` 等多种聊天平台,提供统一的开发接口。
- **原生多模态视觉理解**:可处理图片、文件等多种资源,与用户进行多模态交互。
- **基于事件驱动的异步架构**:遵循异步优先的高效响应机制。
**生态与易用性:**
- **云端资源共享**:包括插件、人设等,拥有强大友好的社区驱动能力。
- **功能齐全的可视化界面**:提供强大的应用管理与监控面板。
## 🧪 预览版新特性
以下内容为当前 `main` / `preview` 版本中的重点新能力:
- **全新工作区 / Claude Code 沙盒体系(预览版)**:统一管理提示词、技能、模型预设、文件、扩展、MCP、沙盒与运行状态,面向更完整的 Agent 工作流。
- **Memory System 长期记忆(预览版)**:引入实体、关系、段落、episode、向量检索与重建维护机制,为 Agent 提供可持续沉淀的长期上下文能力。
- **结构化 MCP 服务管理(预览版)**:新增 registry 与卡片式管理界面,让外部工具与 MCP 服务接入更清晰、更可控。
- **命令系统重构(预览版)**:命令注册、解析、分组、补全、输出查看与前端管理能力完成一轮系统化升级。
- **定时器与运行治理增强(预览版)**:新增 timers 管理、停止回复流程、频道配额与插件激活策略,提升自动化和可运营性。
- **WebUI 与实时状态体验升级(预览版)**:聊天消息样式、SSE 实时推送、系统事件、Agent 活动卡片、工作区导航与多语言支持都有明显增强。
## 🏛️ 架构概览
Nekro Agent 的核心是面向 **输入/输出流** 设计的。适配器(Adapter)作为连接外部平台的桥梁,仅需实现对具体平台消息的接收(输入流)和发送(输出流)。所有复杂的业务逻辑,如频道管理、插件执行、沙盒调用等,都由 Nekro Agent 的核心引擎自动接管和处理。这种设计确保了极高的扩展性和维护性,让开发者可以专注于实现适配器本身的功能,而无需关心核心的复杂实现。
```mermaid
graph TD
subgraph 外部平台
P1["平台 A (例如: QQ)"]
P2["平台 B (例如: Minecraft)"]
P3[...]
end
subgraph Nekro Agent
subgraph 适配器层
A1["适配器 A"]
A2["适配器 B"]
A3[...]
end
subgraph 核心引擎
Input["输入流 (collect_message)"] --> Dispatcher
Dispatcher{"消息
分发器"} --> Services["核心共享服务
(频道, 插件, 沙盒等)"]
Services --> Output["输出流 (forward_message)"]
end
end
P1 <==> A1
P2 <==> A2
P3 <==> A3
A1 --> Input
A2 --> Input
A3 --> Input
Output --> A1
Output --> A2
Output --> A3
```
## 📘 API 文档与响应规范
启用 `--docs` 参数后可访问:
- **Swagger UI**: http://localhost:8021/api/docs
- **ReDoc**: http://localhost:8021/api/redoc
API 使用标准 HTTP 状态码,错误响应为结构化格式并支持 `Accept-Language`:
```json
{
"error": "ValidationError",
"message": "参数校验失败",
"detail": "field: error detail",
"data": null
}
```
## ⚙️ 效果演示
Nekro Agent 提供了强大而直观的可视化界面,方便您管理和监控 Agent 的所有行为,以及实现多种精细化的 Agent 行为策略控制等。


## 🎨 应用场景
Nekro Agent 提供多样化的应用场景,从情感陪伴到复杂任务处理,满足各类需求:
- 💖 **情感交互与陪伴**:通过灵活的人设系统和先进的大语言模型,提供自然流畅的情感互动体验,支持多种角色定制和可扩展的记忆能力
- 📊 **数据与文件处理**:高效处理各类图像、文档及数据,无需额外软件支持,轻松完成格式转换与内容提取
- 🎮 **创意与开发辅助**:从网页应用生成到数据可视化,让创意实现变得简单高效
- 🔄 **自动化与集成**:支持事件订阅推送和多 AI 协作,实现复杂任务的智能自动化
- 📚 **学习与生活助手**:从学习辅导到内容创作,再到智能家居控制,全方位提升生活品质
👉 更多精彩用例与演示,请访问[应用场景展示页面](https://doc.nekro.ai/docs/01_intro/application_scenarios)!
## 💡 功能列表
- ✅ **多平台适配**:
- ✅ OneBot v11 (QQ)
- ✅ Discord
- ✅ Telegram
- ✅ Minecraft
- ✅ Bilibili Live (B 站直播)
- ✅ WeChat (微信,通过 WeChatPad)
- ✅ Email (邮件,SMTP/IMAP)
- ✅ SSE+SDK (Server-Sent Events + SDK)
- ✅ ... 更多适配器开发中
- ✅ **智能聊天**:群聊/私聊场景下的上下文智能聊天
- ✅ **自定义人设**:支持自定义人设与云端人设市场
- ✅ **沙盒执行**:安全的容器化代码执行环境
- ✅ **多模态交互**:支持发送、接收和处理图片及文件资源
- ✅ **插件生态**:高度可扩展的插件系统与云端插件市场
- ✅ **一键部署**:基于 `docker-compose` 的容器编排一键部署
- ✅ **热重载**:配置热更新与指令控制支持
- ✅ **定时任务**:支持定时自触发插件与节日祝福
- ✅ **WebUI**:功能齐全的可视化应用管理控制面板
- ✅ **事件支持**:可响应多种平台事件通知并理解其上下文
- ✅ 外置思维链 (CoT) 能力支持
- ✅ 完善第三方插件能力及 AI 生成插件
- 🧪 **工作区 / Claude Code 沙盒(预览版)**:统一管理沙盒任务、提示词、技能、模型预设、文件与扩展
- 🧪 **Memory System(预览版)**:长期记忆、向量检索、记忆维护与可视化管理面板
- 🧪 **结构化 MCP 管理(预览版)**:MCP 服务注册、共享配置与可视化卡片管理
- 🧪 **命令管理中心(预览版)**:新命令系统、命令输出页与可视化管理界面
## 🎁 快速部署
我们提供了多种部署方式,请访问 [快速开始文档](https://doc.nekro.ai/docs/02_quick_start/quickstart) 查看详细教程:
- [Linux 部署教程](https://doc.nekro.ai/docs/02_quick_start/deploy/linux)
- [Windows 部署教程](https://doc.nekro.ai/docs/02_quick_start/deploy/windows)
- [MacOS 部署教程](https://doc.nekro.ai/docs/02_quick_start/deploy/macos)
### 一键部署脚本 (推荐)
#### 从 Github (推荐)
```bash
sudo -E bash -c "$(curl -fsSL https://raw.githubusercontent.com/KroMiose/nekro-agent/main/docker/install.sh)" - --with-napcat
```
如果从 Github 下载脚本遇到网络问题,您可以使用 Nekro Endpoint 的边缘代理访问地址:
#### 从 [NekroEndpoint](https://ep.nekro.ai) (Cloudflare 镜像)
```bash
sudo -E bash -c "$(curl -fsSL https://ep.nekro.ai/e/KroMiose/nekro-agent/main/docker/install.sh)" - --with-napcat
```
提示:
上述命令中的 --with-napcat 参数会启动全自动标准部署。
如果不加此参数,脚本会以交互模式启动,届时请选择 Y 以安装 Napcat。
### Docker 镜像说明
Nekro Agent 提供两种 Docker 镜像标签,同时发布到 **Docker Hub** 和 **GitHub Container Registry (GHCR)**:
- **latest**: 稳定版本,基于 tag 发布,适用于生产环境
- **preview**: 预览版本,每次 main 分支更新自动构建,包含最新功能,适用于测试和开发
#### 从 Docker Hub 拉取(推荐)
```bash
# 使用稳定版本(推荐)
docker pull kromiose/nekro-agent:latest
# 使用预览版本(体验最新功能)
docker pull kromiose/nekro-agent:preview
```
#### 从 GitHub Container Registry 拉取
```bash
# 使用稳定版本
docker pull ghcr.io/kromiose/nekro-agent:latest
# 使用预览版本
docker pull ghcr.io/kromiose/nekro-agent:preview
```
## 🖥️ 开发者资源
我们欢迎所有开发者为 Nekro Agent 社区贡献代码或想法!
- [插件开发指南(施工中)](https://doc.nekro.ai/docs/04_plugin_dev/01_concepts/architecture)
- [应用开发指南](https://doc.nekro.ai/docs/05_app_dev/dev_linux)
- [项目架构解析](https://deepwiki.com/KroMiose/nekro-agent)[](https://deepwiki.com/KroMiose/nekro-agent)
注意:贡献代码前请先阅读[许可说明](./LICENSE)中的条款,贡献代码即表示您同意这些条款。
## 📖 常见问题
常见问题及解答请访问 [故障排除与 FAQ](https://doc.nekro.ai/docs/06_troubleshooting/faq)
## 🎉 更新日志
前往 [Release 页面](https://github.com/KroMiose/nekro-agent/releases) 查看重要更新日志
## 📜 许可说明
NekroAgent 采用 [自定义的开源协议](./LICENSE)(基于 Apache License 2.0 修改)进行分发。请在遵守协议的前提下使用本项目!
## 🤝 贡献列表
感谢以下开发者对本项目做出的贡献
## ⭐ Star 历史

```