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 python@3.11 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混合索引，异步加速，动态调整深度，权重动态调整，自动清理
MCP服务集成，Agent Handoff智能分发，支持自定义过滤器与回调
多Agent能力扩展：浏览器、文件、代码等多种Agent即插即用，所有Agent均可通过handoff机制统一调用
跨平台兼容：Windows/Mac自动适配，浏览器路径自动检测，依赖智能安装
代码极简，注释全中文，组件解耦，便于扩展
PyQt5动画与UI，支持PNG序列帧，loading动画极快
日志/检索/索引/主题/参数全部自动管理
记忆权重动态调整，支持AI/人工标记important，权重/阈值/清理策略全部在config.py统一管理
所有前端UI与后端解耦，前端只需解析后端JSON，自动适配message/data.content等多种返回结构
前端换行符自动适配，无论后端返回\n还是\\n，PyQt界面都能正确分行显示
所有Agent的handoff schema和注册元数据已集中在mcpserver/mcp_registry.py，主流程和管理器极简，扩展维护更方便。只需维护一处即可批量注册/扩展所有Agent服务。
自动注册/热插拔Agent机制，新增/删除Agent只需增删py文件，无需重启主程序
聊天窗口支持Markdown语法，包括标题、粗体、斜体、代码块、表格、图片等。

🗂️ 目录结构

NagaAgent/
├── main.py                     # 主入口
├── config.py                   # 全局配置
├── api_server.py               # RESTful API服务器
├── conversation_core.py        # 对话核心（含兼容模式主逻辑）
├── handoff_executor.py         # 任务流调度器，自动解析plan并执行多步/分支/并行任务
├── 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                   # 项目说明
└── ...

🌐 多Agent与MCP服务

所有Agent的注册、schema、描述均集中在mcpserver/mcp_registry.py，批量管理，极简扩展
支持浏览器、文件、代码等多种Agent，全部可通过handoff机制统一调用
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等所有新特性
多Agent分步流水线自动执行机制，支持plan结构自动解析与多步执行

🆙 历史对话兼容升级

支持将旧版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 python@3.11
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]
无法访问：检查防火墙设置，确保端口未被阻塞

通用问题

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

📝 许可证

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方法中自定义。

使用方法

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

多Agent分步流水线自动执行机制

系统支持LLM输出plan结构时自动解析并依次执行每一步：

每步可包含action结构，指明agent和params参数
支持每步用id唯一标识，next可为字符串（线性）、对象（条件分支），parallel为并行分支数组
系统自动解析plan为任务图，支持链式、条件跳转、分支、并行等任意流程
每步执行结果实时反馈，全部完成后汇总
其它无action的步骤仅输出描述，不自动执行

精简plan结构示例：

{
  "plan": {
    "start": "s1",
    "steps": [
      {
        "id": "s1",
        "desc": "读取文件",
        "action": {"agent": "file", "params": {"action": "read", "path": "test.txt"}},
        "next": {"success": "s2", "fail": "s3"}
      },
      {
        "id": "s2",
        "desc": "写入文件",
        "action": {"agent": "file", "params": {"action": "write", "path": "out.txt"}},
        "next": "s4"
      },
      {
        "id": "s3",
        "desc": "失败通知",
        "action": {"agent": "notify", "params": {"msg": "失败"}}
      },
      {
        "id": "s4",
        "desc": "并行处理",
        "parallel": ["s5", "s6"]
      },
      {
        "id": "s5",
        "desc": "分支A",
        "action": {"agent": "A", "params": {}}
      },
      {
        "id": "s6",
        "desc": "分支B",
        "action": {"agent": "B", "params": {}}
      }
    ]
  }
}

只保留必要字段：id、desc、action、next、parallel
next可为字符串（线性）或对象（条件分支）
parallel为并行分支数组
不要输出多余字段

系统会自动解析plan为任务图，支持链式、分支、并行等复杂流程，兼容原有线性plan。

如需自定义Agent或扩展plan协议，请参考mcpserver/agent_xxx/和mcp_registry.py。

🌐 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

Python客户端

import requests

# 基本对话
response = requests.post(
    "http://127.0.0.1:8000/chat",
    json={"message": "你好，娜迦"}
)
result = response.json()
print(result['response'])

# 流式对话
response = requests.post(
    "http://127.0.0.1:8000/chat/stream",
    json={"message": "请介绍一下机器学习"},
    stream=True
)

for line in response.iter_lines():
    if line and line.startswith(b'data: '):
        import json
        data = json.loads(line[6:])
        if 'content' in data:
            print(data['content'], end='')

JavaScript/Node.js客户端

// 基本对话
const response = await fetch('http://127.0.0.1:8000/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: '你好，娜迦' })
});
const result = await response.json();
console.log(result.response);

// 流式对话
const streamResponse = await fetch('http://127.0.0.1:8000/chat/stream', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: '请介绍一下人工智能' })
});

const reader = streamResponse.body.getReader();
const decoder = new TextDecoder();

while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');
    
    for (const line of lines) {
        if (line.startsWith('data: ')) {
            const data = JSON.parse(line.slice(6));
            if (data.content) {
                process.stdout.write(data.content);
            }
        }
    }
}

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": "微信"}
```
打开WPS Office：
```
{"action": "open", "app": "WPS Office"}
```

打开网易云音乐：

{"action": "open", "app": "网易云音乐"}

列出所有可用应用：
```
{"action": "list"}
```
刷新应用缓存：
```
{"action": "refresh"}
```

智能适配说明

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

常见问题与注意事项

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

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
__pycache__		__pycache__
apiserver		apiserver
logs		logs
mcpserver		mcpserver
summer		summer
ui		ui
voice		voice
.env		.env
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
check_env.py		check_env.py
config.py		config.py
conversation_core.py		conversation_core.py
handoff_executor.py		handoff_executor.py
main.py		main.py
pyproject.toml		pyproject.toml
quick_deploy_mac.sh		quick_deploy_mac.sh
requirements.txt		requirements.txt
setup.ps1		setup.ps1
setup_mac.sh		setup_mac.sh
start.bat		start.bat
start_mac.sh		start_mac.sh
summer_requirements.txt		summer_requirements.txt

Folders and files

Latest commit

History

Repository files navigation

NagaAgent 2.3

⚡ 快速开始

🖥️ 系统要求

🛠️ 依赖安装与环境配置

Windows 环境

Mac 环境

环境检查（跨平台通用）

⚙️ 配置说明

API 密钥配置

API服务器配置

获取 DeepSeek API 密钥

🌟 主要特性

🗂️ 目录结构

🌐 多Agent与MCP服务

📝 前端UI与响应适配

🔊 流式语音交互

📝 其它亮点

🆙 历史对话兼容升级

❓ 常见问题

Windows 环境

Mac 环境

API服务器问题

通用问题

📝 许可证

聊天窗口自定义

智能历史召回机制

⚡️ 全新流式输出机制

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

使用方法

多Agent分步流水线自动执行机制

🌐 RESTful API 服务

API接口说明

主要接口

健康检查

对话接口

系统管理接口

API使用示例

curl命令

Python客户端

JavaScript/Node.js客户端

API错误处理

代理环境配置

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

功能简介

支持的操作

参数说明

用法示例

智能适配说明

常见问题与注意事项

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages