NagaAgent 2.3

智能对话助手，支持多MCP服务、流式语音交互、主题树检索、RESTful API接口、极致精简代码风格。

⚡ 快速开始

克隆项目
```
git clone [项目地址]
cd NagaAgent
```
一键配置

Windows:
```
.\setup.ps1
```
Mac:
```
chmod +x quick_deploy_mac.sh
./quick_deploy_mac.sh
```
- 自动创建虚拟环境并安装依赖
- 检查/下载中文向量模型
- 配置支持toolcall的LLM，推荐DeepSeekV3
启动

Windows:
```
.\start.bat
```
Mac:
```
./start_mac.sh
```

启动后将自动开启PyQt5界面和RESTful API服务器，可同时使用界面对话和API接口。

🖥️ 系统要求

Windows: Windows 10/11 + PowerShell 5.1+
Mac: macOS 10.15 (Catalina) 或更高版本 + Homebrew
通用: Python 3.8+ (推荐 3.11)

🛠️ 依赖安装与环境配置

Windows 环境

所有依赖见requirements.txt
如遇greenlet、pyaudio等安装失败，需先装Microsoft Visual C++ Build Tools，勾选C++ build tools，重启命令行后再pip install -r requirements.txt
浏览器自动化需playwright，首次用需python -m playwright install chromium

依赖安装命令：

python -m venv .venv
.venv\Scripts\Activate
pip install -r requirements.txt
python -m playwright install chromium

Mac 环境

系统依赖通过Homebrew安装：

# 安装基础依赖
brew install [email protected] portaudio
brew install --cask google-chrome

Python依赖安装：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m playwright install chromium

如遇PyAudio安装失败：

brew install portaudio
pip install pyaudio

环境检查（跨平台通用）

python check_env.py

⚙️ 配置说明

API 密钥配置

直接修改 config.py 文件中的配置：

DEEPSEEK_API_KEY = "<your_deepseek_api>"

API服务器配置

在 config.py 中可配置API服务器相关参数：

API_SERVER_ENABLED = True  # 是否启用API服务器
API_SERVER_HOST = "127.0.0.1"  # API服务器主机
API_SERVER_PORT = 8000  # API服务器端口
API_SERVER_AUTO_START = True  # 启动时自动启动API服务器

获取 DeepSeek API 密钥

访问 DeepSeek 官网
注册账号并创建 API 密钥
将密钥填入 config.py 或 .env 文件

🌟 主要特性

全局变量/路径/密钥统一config.py管理，支持.env和环境变量，所有变量唯一、无重复定义
RESTful API接口，自动启动HTTP服务器，支持完整对话功能和流式输出，可集成到任何前端或服务
DeepSeek流式对话，支持上下文召回与主题树分片检索
faiss向量数据库，HNSW+PQ混合索引，异步加速，动态调整深度，权重动态调整，自动清理
TOOL_REQUEST工具调用循环，自动解析和执行LLM返回的工具调用，支持多轮递归调用
多Agent能力扩展：浏览器、文件、代码等多种Agent即插即用，所有Agent均可通过工具调用循环机制统一调用
跨平台兼容：Windows/Mac自动适配，浏览器路径自动检测，依赖智能安装
代码极简，注释全中文，组件解耦，便于扩展
PyQt5动画与UI，支持PNG序列帧，loading动画极快
日志/检索/索引/主题/参数全部自动管理
记忆权重动态调整，支持AI/人工标记important，权重/阈值/清理策略全部在config.py统一管理
所有前端UI与后端解耦，前端只需解析后端JSON，自动适配message/data.content等多种返回结构
前端换行符自动适配，无论后端返回\n还是\\n，PyQt界面都能正确分行显示
所有Agent的注册元数据已集中在mcpserver/mcp_registry.py，主流程和管理器极简，扩展维护更方便。只需维护一处即可批量注册/扩展所有Agent服务。
自动注册/热插拔Agent机制，新增/删除Agent只需增删py文件，无需重启主程序
聊天窗口支持Markdown语法，包括标题、粗体、斜体、代码块、表格、图片等。

🗂️ 目录结构

NagaAgent/
├── main.py                     # 主入口
├── config.py                   # 全局配置
├── conversation_core.py        # 对话核心（含工具调用循环主逻辑）
├── apiserver/                  # API服务器模块
│   ├── api_server.py           # FastAPI服务器
│   ├── start_server.py         # 启动脚本
│   └── README.md               # API文档
├── agent/                      # 预处理系统模块
│   ├── preprocessor.py         # 消息预处理
│   ├── plugin_manager.py       # 插件管理
│   ├── api_server.py           # 代理API服务器
│   ├── image_processor.py      # 图片处理
│   ├── start_server.py         # 启动脚本
│   └── README.md               # 预处理系统文档
├── mcpserver/
│   ├── mcp_manager.py          # MCP服务管理
│   ├── mcp_registry.py         # Agent注册与schema元数据
│   ├── agent_xxx/              # 各类自定义Agent（如file、coder、browser等）
├── requirements.txt            # 依赖
├── setup.ps1                   # Windows配置脚本
├── start.bat                   # Windows启动脚本
├── setup_mac.sh                # Mac配置脚本
├── quick_deploy_mac.sh         # Mac一键部署脚本
├── check_env.py                # 跨平台环境检查
├── summer/                     # faiss与向量相关
│   ├── memory_manager.py       # 记忆管理主模块
│   ├── summer_faiss.py         # faiss相关操作
│   ├── faiss_index.py          # faiss索引管理
│   ├── embedding.py            # 向量编码
│   ├── memory_flow/            # 记忆分层相关
│   └── summer_upgrade/         # 兼容升级相关脚本
│       └── compat_txt_to_faiss.py # 历史对话兼容主脚本
├── logs/                       # 日志（含历史txt对话）
│   ├── 2025-04-27.txt
│   ├── 2025-05-05.txt
│   ├── ...
│   └── faiss/                  # faiss索引与元数据
├── voice/                      # 语音相关
│   ├── voice_config.py
│   └── voice_handler.py
├── ui/                         # 前端UI
│   ├── pyqt_chat_window.py     # PyQt聊天窗口
│   └── response_utils.py       # 前端通用响应解析工具
├── models/                     # 向量模型等
├── README.md                   # 项目说明
└── ...

🔧 工具调用循环机制

TOOL_REQUEST格式

系统仅支持如下格式的工具调用：

<<<[TOOL_REQUEST]>>>
tool_name: 「始」服务名称「末」
param1: 「始」参数值1「末」
param2: 「始」参数值2「末」
<<<[END_TOOL_REQUEST]>>>

工具调用流程

LLM输出TOOL_REQUEST格式：LLM根据用户需求输出工具调用请求
自动解析工具调用：系统自动解析TOOL_REQUEST块，提取工具名称和参数
执行工具调用：调用对应的MCP服务执行具体任务
结果返回LLM：将工具执行结果返回给LLM
循环处理：重复步骤2-4，直到LLM输出普通文本或无工具调用

配置参数

# config.py中的工具调用循环配置
MAX_VCP_LOOP_STREAM = 5      # 流式模式最大工具调用循环次数
MAX_VCP_LOOP_NON_STREAM = 5  # 非流式模式最大工具调用循环次数
SHOW_VCP_OUTPUT = False      # 是否显示工具调用输出

使用示例

# 浏览器操作
await mcp.handoff(
    service_name="playwright",
    task={"action": "open_browser", "url": "https://www.bilibili.com"}
)

# 文件操作
await mcp.handoff(
    service_name="file",
    task={"action": "read", "path": "test.txt"}
)

# 代码执行
await mcp.handoff(
    service_name="coder",
    task={"action": "run", "file": "main.py"}
)

🌐 多Agent与MCP服务

所有Agent的注册、schema、描述均集中在mcpserver/mcp_registry.py，批量管理，极简扩展
支持浏览器、文件、代码等多种Agent，全部可通过工具调用循环机制统一调用
Agent能力即插即用，自动注册/热插拔，无需重启主程序
典型用法示例：

# 读取文件内容
await s.mcp.handoff(
  service_name="file",
  task={"action": "read", "path": "test.txt"}
)
# 运行Python代码
await s.mcp.handoff(
  service_name="coder",
  task={"action": "run", "file": "main.py"}
)

📝 前端UI与响应适配

所有后端返回均为结构化JSON，前端通过ui/response_utils.py的extract_message方法自动适配多种返回格式
优先显示data.content，其次message，最后原样返回，兼容所有Agent
PyQt前端自动将所有\n和\\n换行符转为<br>，多行内容显示无障碍
UI动画、主题、昵称、透明度等全部可在config.py和pyqt_chat_window.py灵活配置

🔊 流式语音交互

支持语音输入（流式识别，自动转文字）与语音输出（流式合成，边播边出）
依赖与配置详见voice/voice_config.py和README相关章节

📝 其它亮点

记忆权重、遗忘阈值、冗余去重、短期/长期记忆容量等全部在config.py统一管理，便于灵活调整
主题归类、召回、权重提升、清理等全部自动化，AI/人工可标记important内容，重要内容一年内不会被清理
检索日志自动记录，参数可调，faiss配置示例见config.py
聊天窗口背景透明度、用户名、主题树召回、流式输出、侧栏动画等全部可自定义
支持历史对话一键导入AI多层记忆系统，兼容主题、分层、embedding等所有新特性
工具调用循环自动执行机制，支持多轮递归调用，最大循环次数可配置

🆙 历史对话兼容升级

支持将旧版txt对话内容一键导入AI多层记忆系统，兼容主题、分层、embedding等所有新特性。
激活指令：
```
#夏园系统兼容升级
```
- 系统会自动遍历logs目录下所有txt日志，列出所有历史对话内容并编号，输出到终端和summer/summer_upgrade/history_dialogs.json。

用户可查看编号后，选择导入方式：

全部导入：

python summer/summer_upgrade/compat_txt_to_faiss.py import all

选择性导入（如第1、3、5-8条）：

python summer/summer_upgrade/compat_txt_to_faiss.py import 1,3,5-8

兼容过程自动判重，已入库内容不会重复导入，支持断点续跑。
兼容内容全部走AI自动主题归类与分层，完全与新系统一致。
详细进度、结果和异常均有反馈，安全高效。

❓ 常见问题

环境检查：python check_env.py

Windows 环境

Python版本/依赖/虚拟环境/浏览器驱动等问题，详见setup.ps1与本README
IDE报import错误，重启并选择正确解释器
语音依赖安装失败，先装C++ Build Tools

Mac 环境

Python版本过低：brew install [email protected]
PyAudio安装失败：brew install portaudio && pip install pyaudio
权限问题：chmod +x *.sh

API服务器问题

端口占用：修改config.py中的API_SERVER_PORT
代理干扰：临时禁用代理 unset ALL_PROXY http_proxy https_proxy
依赖缺失：确保安装了FastAPI和Uvicorn pip install fastapi uvicorn[standard]
无法访问：检查防火墙设置，确保端口未被阻塞

工具调用问题

工具调用循环次数过多：调整config.py中的MAX_VCP_LOOP_STREAM和MAX_VCP_LOOP_NON_STREAM
工具调用失败：检查MCP服务是否正常运行，查看日志输出
格式错误：确保LLM输出严格遵循TOOL_REQUEST格式

通用问题

浏览器无法启动，检查playwright安装与网络
主题树/索引/参数/密钥全部在config.py统一管理
聊天输入#devmode进入开发者模式，后续对话不写入faiss，仅用于工具调用测试

📝 许可证

MIT License

如需详细功能/API/扩展说明，见各模块注释与代码，所有变量唯一、注释中文、极致精简。

聊天窗口自定义

聊天窗口背景透明度由config.BG_ALPHA统一控制，取值0~1，默认0.4。
用户名自动识别电脑名，变量config.USER_NAME，如需自定义可直接修改该变量。

智能历史召回机制

默认按主题分片检索历史，极快且相关性高。
若分片查不到，自动兜底遍历所有主题分片模糊检索（faiss_fuzzy_recall），话题跳跃也能召回历史。
faiss_fuzzy_recall支持直接调用，返回全局最相关历史。
兜底逻辑已集成主流程，无需手动切换。

⚡️ 全新流式输出机制

AI回复支持前后端全链路流式输出，边生成边显示，极致丝滑。
后端采用async生成器yield分段内容，前端Worker线程streaming信号实时追加到对话框。
彻底无终端print污染，支持大文本不卡顿。
如遇依赖包冲突，建议彻底清理全局PYTHONPATH和环境变量，仅用虚拟环境。

侧栏与主聊天区动画优化说明

侧栏点击切换时，侧栏宽度、主聊天区宽度、输入框高度均采用同步动画，提升视觉流畅度。
输入框隐藏采用高度动画，动画结束后自动清除焦点，避免输入法残留。
线程处理增加自动释放，避免内存泄漏。
相关动画效果可在ui/pyqt_chat_window.py的toggle_full_img方法中自定义。

使用方法

点击侧栏即可切换立绘展开/收起，主聊天区和输入框会自动让位并隐藏/恢复。
动画时长、缓动曲线等可根据需要调整源码参数。

工具调用循环机制详解

核心特性

自动解析：系统自动解析LLM返回的TOOL_REQUEST格式工具调用
递归执行：支持多轮工具调用循环，最大循环次数可配置
错误处理：完善的错误处理和回退机制
流式支持：支持流式和非流式两种模式

工具调用格式

LLM必须严格按照以下格式输出工具调用：

<<<[TOOL_REQUEST]>>>
tool_name: 「始」服务名称「末」
param1: 「始」参数值1「末」
param2: 「始」参数值2「末」
<<<[END_TOOL_REQUEST]>>>

执行流程

接收用户消息
调用LLM API
解析TOOL_REQUEST格式工具调用
执行工具调用（通过MCP服务）
将结果返回给LLM
重复步骤2-5直到无工具调用或达到最大循环次数

配置参数

# config.py中的工具调用循环配置
MAX_VCP_LOOP_STREAM = 5      # 流式模式最大工具调用循环次数
MAX_VCP_LOOP_NON_STREAM = 5  # 非流式模式最大工具调用循环次数
SHOW_VCP_OUTPUT = False      # 是否显示工具调用输出

错误处理

工具调用失败时会记录错误信息并继续执行
达到最大循环次数时会停止
支持回退到原始处理方式

扩展开发

如需添加新的工具调用处理逻辑，可以：

在mcpserver/目录下添加新的Agent
在mcpserver/mcp_registry.py中注册新Agent
更新API接口以支持新的功能

🌐 RESTful API 服务

NagaAgent内置完整的RESTful API服务器，启动时自动开启，支持所有对话功能：

API接口说明

基础地址: http://127.0.0.1:8000 (可在config.py中配置)
交互式文档: http://127.0.0.1:8000/docs
OpenAPI规范: http://127.0.0.1:8000/openapi.json

主要接口

健康检查

GET /health

对话接口

# 普通对话
POST /chat
{
  "message": "你好，娜迦",
  "session_id": "optional-session-id"
}

# 流式对话 (Server-Sent Events)
POST /chat/stream
{
  "message": "请介绍一下人工智能的发展历程"
}

系统管理接口

# 获取系统信息
GET /system/info

# 切换开发者模式
POST /system/devmode

# 获取记忆统计
GET /memory/stats

# 获取MCP服务列表
GET /mcp/services

# 调用MCP服务
POST /mcp/handoff
{
  "service_name": "file",
  "task": {
    "action": "read",
    "path": "test.txt"
  }
}

API使用示例

curl命令

# 基本对话
curl -X POST "http://127.0.0.1:8000/chat" \
     -H "Content-Type: application/json" \
     -d '{"message": "你好，娜迦"}'

# 流式对话
curl -X POST "http://127.0.0.1:8000/chat/stream" \
     -H "Content-Type: application/json" \
     -d '{"message": "请介绍一下人工智能"}' \
     --no-buffer

API错误处理

API使用标准HTTP状态码：

200 - 成功
400 - 请求参数错误
500 - 服务器内部错误
503 - 服务不可用

代理环境配置

如果您的环境中配置了代理（如SOCKS代理），测试本地API时可能需要临时禁用：

# 临时禁用代理
unset ALL_PROXY http_proxy https_proxy

# 然后测试API
curl http://127.0.0.1:8000/health

本地应用启动与管理（AppLauncher Agent）

功能简介

支持通过MCP自动打开电脑上的任意应用（如微信、WPS、网易云音乐等），无需手动配置应用路径。
自动扫描并缓存所有本机可用应用（包括开始菜单快捷方式、注册表、Applications等），支持智能模糊匹配和别名自学习。
兼容Windows、Mac、Linux，支持.lnk快捷方式和.exe等可执行文件。

支持的操作

open：打开指定应用
list：列出所有可用应用
refresh：刷新应用缓存

参数说明

参数名	类型	说明	是否必填
action	string	操作类型（open/list/refresh）	是
app	string	应用名或路径（open时必填）	否
args	array	启动参数（可选）	否

用法示例

打开微信：
```
{"action": "open", "app": "微信"}
```
列出所有可用应用：
```
{"action": "list"}
```
刷新应用缓存：
```
{"action": "refresh"}
```

智能适配说明

支持拼音、英文、别名、模糊匹配等多策略查找，极大提升容错率。
用户每次成功打开后，系统会自动记录"用户说法→真实应用名"映射，越用越准。
支持.lnk快捷方式自动用系统方式打开，.exe等可执行文件用subprocess启动。

常见问题与注意事项

如果"未找到应用"，请先用list操作确认缓存中真实的应用名。
新安装应用后请先refresh再open。
Windows下建议将常用应用快捷方式放到开始菜单，便于自动识别。
仅支持明确的action（open/list/refresh），其他操作会被拒绝。

工具调用机制

本系统仅支持如下格式的工具调用循环：

<<<[TOOL_REQUEST]>>>
tool_name: 「始」服务名称「末」
param1: 「始」参数值1「末」
param2: 「始」参数值2「末」
<<<[END_TOOL_REQUEST]>>>

如无需调用工具，直接回复message字段内容即可。

LLM每次输出可包含多个TOOL_REQUEST块，系统会自动循环解析和执行，直到无工具调用为止。
不再支持plan结构的多步分解，所有多步任务请LLM分多轮TOOL_REQUEST实现。

主要功能

智能对话与工具调用循环
插件化消息预处理与图片处理
API代理与MCP服务集成

NagaAgent

NagaAgent 2.3

⚡ 快速开始

🖥️ 系统要求

🛠️ 依赖安装与环境配置

Windows 环境

Mac 环境

环境检查（跨平台通用）

⚙️ 配置说明

API 密钥配置

API服务器配置

获取 DeepSeek API 密钥

🌟 主要特性

🗂️ 目录结构

🔧 工具调用循环机制

TOOL_REQUEST格式

工具调用流程

配置参数

使用示例

🌐 多Agent与MCP服务

📝 前端UI与响应适配

🔊 流式语音交互

📝 其它亮点

🆙 历史对话兼容升级

❓ 常见问题

Windows 环境

Mac 环境

API服务器问题

工具调用问题

通用问题

📝 许可证

聊天窗口自定义

智能历史召回机制

⚡️ 全新流式输出机制

侧栏与主聊天区动画优化说明

使用方法

工具调用循环机制详解

核心特性

工具调用格式

执行流程

配置参数

错误处理

扩展开发

🌐 RESTful API 服务

API接口说明

主要接口

健康检查

对话接口

系统管理接口

API使用示例

curl命令

API错误处理

代理环境配置

本地应用启动与管理（AppLauncher Agent）

功能简介

支持的操作

参数说明

用法示例

智能适配说明

常见问题与注意事项

工具调用机制

主要功能

Install

Related