Naga Assistant 2.0

娜迦助手2.0版本 - 一个智能的对话助手系统，支持多MCP服务集成、对话索引和上下文管理。

⚠️ 重要：API配置

在开始使用之前，请确保完成以下步骤：

1. 在项目根目录创建 .env 文件
2. 在 .env 文件和 config.py 中配置以下必需的环境变量：

DEEPSEEK_API_KEY=你的API密钥 # 必填，从DeepSeek平台获取
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1 # 可选，默认值如左
DEEPSEEK_MODEL=deepseek-chat # 可选，默认值如左

系统要求

• Python 3.13 或更高版本
• Windows 10/11 操作系统

主要特性

• 🤖 智能对话：基于DeepSeek API，支持流式输出
• 🔌 MCP服务集成：支持多个MCP服务的动态调用
• 📝 对话索引：自动为重要对话生成主题索引
• 🔍 上下文检索：支持按时间戳和主题检索历史对话
• 💾 完整的对话历史管理
• 🌐 异步处理：高效的异步对话处理机制
• 🎯 精确的工具调用：支持各类MCP服务工具
• 📊 智能主题提取：自动为重要对话生成主题
• 实时响应：支持流式输出模式

快速开始

本项目已包含完整的Python环境，但需要确保系统安装了正确版本的Python。

1. 克隆项目：

git clone [项目地址]
cd naga-assistant-2.0

2. 运行配置脚本：

.\setup.ps1

配置脚本会自动：

• 检查Python 3.13是否已安装
• 如未安装，提供详细的安装指导
• 验证虚拟环境的完整性
• 配置IDE的Python解释器

3. 如果需要安装Python 3.13：

   • 访问 https://www.python.org/downloads/
   • 下载Python 3.13.x版本
   • 运行安装程序，务必勾选"Add Python to PATH"
   • 安装完成后重新运行setup.ps1

4. 配置环境变量： 复制.env.example为.env并填写必要的配置：

copy .env.example .env

5. 启动系统：

方式一：直接双击运行（推荐）

• 双击start.bat文件即可启动程序
• 如果首次运行提示需要配置，请先运行setup.ps1

方式二：命令行运行

python main.py

使用方法

1. 系统命令：

• 清屏/clear/cls：清除屏幕
• 查看索引/show index：显示对话主题索引
• 更新索引/update index：强制更新主题索引
• 退出/exit/quit：退出系统

2. 对话检索功能：

• 支持按时间戳检索：输入具体时间如"查看2024-03-20 15:30:00的对话"
• 支持模糊检索：如"查找关于量子计算的对话"
• 支持上下文关联：自动关联相关对话主题

常见问题

Python版本不兼容

1. 运行setup.ps1，它会：

   • 检查Python版本是否为3.13
   • 如果版本不符，提供安装指导
   • 验证虚拟环境的Python版本

2. 如果提示Python版本过低：

   • 按照脚本提供的步骤安装Python 3.13
   • 确保安装时勾选"Add Python to PATH"
   • 重新运行setup.ps1

导入模块报错 "Import xxx could not be resolve"

1. 运行setup.ps1配置解释器
2. 重启IDE（VS Code或Cursor）
3. 如果问题仍然存在：
   • VS Code：按Ctrl+Shift+P，输入"Python: Select Interpreter"，选择解释器
   • Cursor：点击左下角状态栏的Python版本，选择解释器

双击start.bat无法启动

1. 确认是否已运行setup.ps1完成初始配置
2. 检查.venv目录是否存在
3. 如果提示"找不到python"，请重新运行setup.ps1

注意事项

1. 确保MCP服务脚本路径正确配置
2. 调试时可开启DEBUG模式获取详细日志
3. 注意环境变量的安全性，不要将含有密钥的.env文件提交到代码库

许可证

MIT License

开发指南

项目结构

2.0/
├── main.py          # 主程序入口
├── config.py        # 配置文件
├── conversation.py  # 对话处理核心
├── mcp_manager.py  # MCP服务管理器
├── requirements.txt # 依赖配置
├── .env            # 环境变量
└── logs/           # 日志目录

添加新功能

1. MCP服务：

   • 在config.py中的MCP_SERVICES添加新服务配置
   • 在mcp_manager.py中实现服务连接和工具调用逻辑

2. 对话功能：

   • 在conversation.py中添加新的对话处理方法
   • 更新main.py中的命令处理逻辑

参考文档

OpenAI Agents SDK

• 文档地址：OpenAI Agents SDK
• 主要参考：
  • Agents设计理念和实现方式
  • 工具调用机制
  • 对话上下文管理
  • 异步处理流程

MCP协议文档

• 文档地址：MCP中文文档
• 主要参考：
  • MCP服务器连接配置
  • 客户端开发指南
  • 工具注册和调用规范
  • 环境变量管理