iflow-mcp_xxiii8322766509-nagaagent 4.0.0

NagaAgent 4.0 - 智能对话助手，支持多MCP服务、流式语音交互、GRAG知识图谱记忆系统、RESTful API接口、控制台托盘功能

NagaAgent

简体中文|繁體中文|English

此处获取教程视频与一键运行整合包

框架联动（QQ机器人）：Undefined QQbot

---

介绍

NagaAgent 是一个功能丰富的智能对话助手系统，具有以下特色功能：

🎯 核心功能

• 智能对话系统：支持流式对话和工具调用循环
• 多Agent协作：基于博弈论的智能任务调度
• 知识图谱记忆：GRAG系统支持长期记忆和智能检索
• 完整语音交互：实时语音输入输出处理
• 现代化界面：PyQt5 GUI + Live2D虚拟形象
• 系统托盘集成：后台运行和快捷操作

🛠️ 技术架构

系统整体架构

graph TB
    %% 用户界面层
    subgraph "用户界面层 (UI Layer)"
        UI[PyQt5 GUI界面]
        Live2D[Live2D虚拟形象]
        Tray[系统托盘]
        Chat[聊天界面]
    end

    %% 核心服务层
    subgraph "核心服务层 (Core Services)"
        API[API服务器<br/>:8000]
        Agent[Agent服务器<br/>:8001]
        MCP[MCP服务器<br/>:8003]
        TTS[TTS服务器<br/>:5048]
    end

    %% 业务逻辑层
    subgraph "业务逻辑层 (Business Logic)"
        Game[博弈论系统<br/>多Agent协作]
        Memory[GRAG记忆系统<br/>知识图谱]
        Voice[语音处理系统<br/>实时语音交互]
        Tools[工具调用系统<br/>MCP协议]
    end

    %% 数据存储层
    subgraph "数据存储层 (Data Storage)"
        Neo4j[(Neo4j图数据库<br/>知识图谱存储)]
        Files[文件系统<br/>配置/日志/缓存]
        MemoryCache[内存缓存<br/>会话状态]
    end

    %% 外部服务层
    subgraph "外部服务层 (External Services)"
        LLM[LLM服务商<br/>OpenAI/通义千问等]
        Portal[NagaPortal<br/>门户服务]
        MQTT[物联网设备<br/>MQTT通讯]
        Web[网络爬虫<br/>在线搜索]
    end

    %% 连接关系
    UI --> API
    UI --> Agent
    UI --> MCP
    UI --> TTS
    
    API --> Game
    API --> Memory
    API --> Voice
    API --> Tools
    
    Agent --> Game
    Agent --> Tools
    
    MCP --> Tools
    MCP --> Portal
    MCP --> MQTT
    MCP --> Web
    
    TTS --> Voice
    
    Game --> Memory
    Memory --> Neo4j
    Voice --> LLM
    Tools --> LLM
    
    API --> MemoryCache
    Agent --> MemoryCache
    MCP --> MemoryCache
    
    %% 样式
    classDef uiLayer fill:#e1f5fe
    classDef coreLayer fill:#f3e5f5
    classDef businessLayer fill:#e8f5e8
    classDef dataLayer fill:#fff3e0
    classDef externalLayer fill:#fce4ec
    
    class UI,Live2D,Tray,Chat uiLayer
    class API,Agent,MCP,TTS coreLayer
    class Game,Memory,Voice,Tools businessLayer
    class Neo4j,Files,MemoryCache dataLayer
    class LLM,Portal,MQTT,Web externalLayer

核心特性

• 多服务并行：API服务器(8000)、Agent服务器(8001)、MCP服务器(8003)、TTS服务器(5048)
• 模块化设计：各服务独立运行，支持热插拔
• 配置驱动：实时配置热更新，无需重启
• 跨平台支持：Windows、macOS、Linux

🔧 技术栈

技术栈架构

graph TB
    %% 前端技术栈
    subgraph "前端技术栈 (Frontend Stack)"
        PyQt5[PyQt5<br/>GUI框架]
        Live2D[Live2D<br/>虚拟形象]
        QSS[QSS<br/>样式表]
    end
    
    %% 后端技术栈
    subgraph "后端技术栈 (Backend Stack)"
        FastAPI[FastAPI<br/>Web框架]
        Uvicorn[Uvicorn<br/>ASGI服务器]
        AsyncIO[AsyncIO<br/>异步编程]
    end
    
    %% 数据库技术栈
    subgraph "数据库技术栈 (Database Stack)"
        Neo4j[Neo4j<br/>图数据库]
        GRAG[GRAG<br/>知识图谱]
        Memory[内存缓存<br/>会话管理]
    end
    
    %% AI技术栈
    subgraph "AI技术栈 (AI Stack)"
        OpenAI[OpenAI API<br/>GPT模型]
        Qwen[通义千问<br/>多模态模型]
        MCP[MCP协议<br/>工具调用]
    end
    
    %% 语音技术栈
    subgraph "语音技术栈 (Voice Stack)"
        ASR[语音识别<br/>ASR]
        TTS[语音合成<br/>TTS]
        Realtime[实时语音<br/>WebRTC]
    end
    
    %% 网络技术栈
    subgraph "网络技术栈 (Network Stack)"
        HTTP[HTTP/HTTPS<br/>RESTful API]
        WebSocket[WebSocket<br/>实时通信]
        MQTT[MQTT<br/>物联网协议]
    end
    
    %% 样式
    classDef frontend fill:#e3f2fd
    classDef backend fill:#f1f8e9
    classDef database fill:#fff3e0
    classDef ai fill:#fce4ec
    classDef voice fill:#e8f5e8
    classDef network fill:#f3e5f5
    
    class PyQt5,Live2D,QSS frontend
    class FastAPI,Uvicorn,AsyncIO backend
    class Neo4j,GRAG,Memory database
    class OpenAI,Qwen,MCP ai
    class ASR,TTS,Realtime voice
    class HTTP,WebSocket,MQTT network

核心技术

• Python 3.11 + PyQt5 + FastAPI
• Neo4j图数据库 + GRAG知识图谱
• MCP (Model Context Protocol) 工具调用
• OpenAI兼容API + 多种LLM服务商支持

---

部署运行教程

环境要求

• Python 3.11
• 可选：uv工具（加速依赖安装，且无需特定python版本）

快速开始

如果您的部署有困难，可以参考视频教程或下载一键运行整合包。

1. 安装依赖

使用setup脚本

# 可选：先安装uv
pip install uv

# 使用 setup.py 自动初始化
python setup.py

# 或使用 setup.sh (Linux/macOS)
./setup.sh

# 或使用 setup.bat (Windows)
setup.bat

初始化脚本会自动：

• 检测Python版本
• 创建虚拟环境
• 安装依赖包
• 复制配置文件模板
• 打开配置文件供编辑

手动部署

# 无uv
python -m venv .venv

# linux/Mac OS
source .venv/bin/activate
# Windows
.\.venv\Scripts\activate

pip install -r requirements.txt

# 使用uv
uv sync

2. 配置LLM API

编辑 config.json 文件，配置您的LLM API信息：

{
  "api": {
    "api_key": "你的api_key",
    "base_url": "模型服务商OPENAI API端点",
    "model": "模型名称"
  }
}

可选配置

启用知识图谱记忆

使用 docker 安装 neo4j 或安装 neo4j desktop 并在 config.json 中配置 Neo4j 连接参数：

{
  "grag": {
    "enabled": true,
    "neo4j_uri": "neo4j://127.0.0.1:7687",
    "neo4j_user": "neo4j",
    "neo4j_password": "你安装neo4j时设置的密码"
  }
}

启用语音输出功能

{
  "system": {
    "voice_enabled": true
  },
  "tts": {
    "port": 5048
  }
}

Live2D 相关配置

  "live2d": {
    "enabled": false, # 是否启用Live2D
    "model_path": "ui/live2d_local/live2d_models/重音テト/重音テト.model3.json", # Live2D模型路径
    "fallback_image": "ui/img/standby.png", # 备用图片
    "auto_switch": true, # 是否自动切换
    "animation_enabled": true, # 是否启用动画
    "touch_interaction": true # 是否启用触摸交互
  },

其他配置项可参考注释

3. 启动应用

# 使用启动脚本
./start.sh          # Linux/macOS
start.bat           # Windows


# 或直接运行py文件
# linux/Mac OS
source .venv/bin/activate
# Windows
.\.venv\Scripts\activate
python main.py

# uv
uv run main.py

程序会自动检测上次系统检测时间，如果检测通过且超过7天，会自动执行更新并重启。

手动更新

# 使用更新脚本
./update.sh         # Linux/macOS
update.bat          # Windows

# 或直接运行py文件
python update.py

更新脚本会自动执行 git pull（自动检测当前分支）和 uv sync 同步依赖。

故障排除

1. Python 版本不兼容：确保使用Python 3.11
2. 端口被占用：检查8000、8001、8003、5048端口是否可用
3. Neo4j 连接失败：确保Neo4j服务正在运行
4. 检测 Neo4j 连接时出现 json 解析错误：退出并重新启动程序
5. 未知错误：请创建issue以反馈

环境检测

# 运行系统环境检测
python main.py --check-env --force-check

# 快速检测
python main.py --quick-check

许可证

NagaAgent License

贡献

欢迎创建Issue和Pull Request！

构建一键运行整合包

python build.py

构建完成的文件位于dist/目录下

Star History

感谢所有开发者对本项目做出的贡献

⭐ 如果这个项目对您有帮助，请考虑给我们一个 Star