agent功能开发增加MCP后端

docs/AGENT_DEPLOYMENT.md

@@ -0,0 +1,381 @@
+# AI Agent 系统部署指南
+
+## 🎯 系统架构
+
+### 三阶段流程
+
+```
+用户输入
+    ↓
+[阶段1: 计划制定 Planning]
+    - LLM 分析用户需求
+    - 确定需要哪些工具
+    - 制定执行计划（steps）
+    ↓
+[阶段2: 工具执行 Execution]
+    - 按计划顺序调用 MCP 工具
+    - 收集数据
+    - 异常处理和重试
+    ↓
+[阶段3: 结果总结 Summarization]
+    - LLM 综合分析所有数据
+    - 生成自然语言报告
+    ↓
+输出给用户
+```
+
+## 📦 文件清单
+
+### 后端文件
+
+```
+mcp_server.py              # MCP 工具服务器（已有）
+mcp_agent_system.py        # Agent 系统核心逻辑（新增）
+mcp_config.py              # 配置文件（已有）
+mcp_database.py            # 数据库操作（已有）
+```
+
+### 前端文件
+
+```
+src/components/ChatBot/
+├── ChatInterfaceV2.js     # 新版聊天界面（漂亮）
+├── PlanCard.js            # 执行计划卡片
+├── StepResultCard.js      # 步骤结果卡片（可折叠）
+├── ChatInterface.js       # 旧版聊天界面（保留）
+├── MessageBubble.js       # 消息气泡组件（保留）
+└── index.js               # 统一导出
+
+src/views/AgentChat/
+└── index.js               # Agent 聊天页面
+```
+
+## 🚀 部署步骤
+
+### 1. 安装依赖
+
+```bash
+# 进入项目目录
+cd /home/ubuntu/vf_react
+
+# 安装 OpenAI SDK（支持多个LLM提供商）
+pip install openai
+```
+
+### 2. 获取 LLM API Key
+
+**推荐：通义千问（便宜且中文能力强）**
+
+1. 访问 https://dashscope.console.aliyun.com/
+2. 注册/登录阿里云账号
+3. 开通 DashScope 服务
+4. 创建 API Key
+5. 复制 API Key（格式：`sk-xxx...`）
+
+**其他选择**：
+- DeepSeek: https://platform.deepseek.com/ （最便宜）
+- OpenAI: https://platform.openai.com/ （需要翻墙）
+
+### 3. 配置环境变量
+
+```bash
+# 编辑环境变量
+sudo nano /etc/environment
+
+# 添加以下内容（选择一个）
+# 方式1: 通义千问（推荐）
+DASHSCOPE_API_KEY="sk-your-key-here"
+
+# 方式2: DeepSeek（更便宜）
+DEEPSEEK_API_KEY="sk-your-key-here"
+
+# 方式3: OpenAI
+OPENAI_API_KEY="sk-your-key-here"
+
+# 保存并退出，然后重新加载
+source /etc/environment
+
+# 验证环境变量
+echo $DASHSCOPE_API_KEY
+```
+
+### 4. 修改 mcp_server.py
+
+在文件末尾（`if __name__ == "__main__":` 之前）添加：
+
+```python
+# ==================== Agent 端点 ====================
+
+from mcp_agent_system import MCPAgent, ChatRequest, AgentResponse
+
+# 创建 Agent 实例
+agent = MCPAgent(provider="qwen")  # 或 "deepseek", "openai"
+
+@app.post("/agent/chat", response_model=AgentResponse)
+async def agent_chat(request: ChatRequest):
+    """智能代理对话端点"""
+    logger.info(f"Agent chat: {request.message}")
+
+    # 获取工具列表和处理器
+    tools = [tool.dict() for tool in TOOLS]
+
+    # 处理查询
+    response = await agent.process_query(
+        user_query=request.message,
+        tools=tools,
+        tool_handlers=TOOL_HANDLERS,
+    )
+
+    return response
+```
+
+### 5. 重启 MCP 服务
+
+```bash
+# 如果使用 systemd
+sudo systemctl restart mcp-server
+
+# 或者手动重启
+pkill -f mcp_server
+nohup uvicorn mcp_server:app --host 0.0.0.0 --port 8900 > mcp_server.log 2>&1 &
+
+# 查看日志
+tail -f mcp_server.log
+```
+
+### 6. 测试 Agent API
+
+```bash
+# 测试 Agent 端点
+curl -X POST http://localhost:8900/agent/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "全面分析贵州茅台这只股票",
+    "conversation_history": []
+  }'
+
+# 应该返回类似这样的JSON：
+# {
+#   "success": true,
+#   "message": "根据分析，贵州茅台...",
+#   "plan": {
+#     "goal": "全面分析贵州茅台",
+#     "steps": [...]
+#   },
+#   "step_results": [...],
+#   "metadata": {...}
+# }
+```
+
+### 7. 部署前端
+
+```bash
+# 在本地构建
+npm run build
+
+# 上传到服务器
+scp -r build/* ubuntu@your-server:/var/www/valuefrontier.cn/
+
+# 或者在服务器上构建
+cd /home/ubuntu/vf_react
+npm run build
+sudo cp -r build/* /var/www/valuefrontier.cn/
+```
+
+### 8. 重启 Nginx
+
+```bash
+sudo systemctl reload nginx
+```
+
+## ✅ 验证部署
+
+### 1. 测试后端 API
+
+```bash
+# 测试工具列表
+curl https://valuefrontier.cn/mcp/tools
+
+# 测试 Agent
+curl -X POST https://valuefrontier.cn/mcp/agent/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "今日涨停股票有哪些",
+    "conversation_history": []
+  }'
+```
+
+### 2. 测试前端
+
+1. 访问 https://valuefrontier.cn/agent-chat
+2. 输入问题："全面分析贵州茅台这只股票"
+3. 观察：
+   - ✓ 是否显示执行计划卡片
+   - ✓ 是否显示步骤执行过程
+   - ✓ 是否显示最终总结
+   - ✓ 步骤结果卡片是否可折叠
+
+### 3. 测试用例
+
+```
+测试1: 简单查询
+输入：查询贵州茅台的股票信息
+预期：调用 get_stock_basic_info，返回基本信息
+
+测试2: 深度分析（推荐）
+输入：全面分析贵州茅台这只股票
+预期：
+  - 步骤1: get_stock_basic_info
+  - 步骤2: get_stock_financial_index
+  - 步骤3: get_stock_trade_data
+  - 步骤4: search_china_news
+  - 步骤5: summarize_with_llm
+
+测试3: 市场热点
+输入：今日涨停股票有哪些亮点
+预期：
+  - 步骤1: search_limit_up_stocks
+  - 步骤2: get_concept_statistics
+  - 步骤3: summarize_with_llm
+
+测试4: 概念分析
+输入：新能源概念板块的投资机会
+预期：
+  - 步骤1: search_concepts（新能源）
+  - 步骤2: search_china_news（新能源）
+  - 步骤3: summarize_with_llm
+```
+
+## 🐛 故障排查
+
+### 问题1: Agent 返回 "Provider not configured"
+
+**原因**: 环境变量未设置
+
+**解决**:
+```bash
+# 检查环境变量
+echo $DASHSCOPE_API_KEY
+
+# 如果为空，重新设置
+export DASHSCOPE_API_KEY="sk-xxx..."
+
+# 重启服务
+sudo systemctl restart mcp-server
+```
+
+### 问题2: Agent 返回 JSON 解析错误
+
+**原因**: LLM 没有返回正确的 JSON 格式
+
+**解决**: 在 `mcp_agent_system.py` 中已经处理了代码块标记清理，如果还有问题：
+1. 检查 LLM 的 temperature 参数（建议 0.3）
+2. 检查 prompt 是否清晰
+3. 尝试不同的 LLM 提供商
+
+### 问题3: 前端显示 "查询失败"
+
+**原因**: 后端 API 未正确配置或 Nginx 代理问题
+
+**解决**:
+```bash
+# 1. 检查 MCP 服务是否运行
+ps aux | grep mcp_server
+
+# 2. 检查 Nginx 配置
+sudo nginx -t
+
+# 3. 查看错误日志
+sudo tail -f /var/log/nginx/error.log
+tail -f /home/ubuntu/vf_react/mcp_server.log
+```
+
+### 问题4: 执行步骤失败
+
+**原因**: 某个 MCP 工具调用失败
+
+**解决**: 查看步骤结果卡片中的错误信息，通常是：
+- API 超时：增加 timeout
+- 参数错误：检查工具定义
+- 数据库连接失败：检查数据库连接
+
+## 💰 成本估算
+
+### 使用通义千问（qwen-plus）
+
+**价格**: ¥0.004/1000 tokens
+
+**典型对话消耗**:
+- 简单查询（1步）: ~500 tokens = ¥0.002
+- 深度分析（5步）: ~3000 tokens = ¥0.012
+- 平均每次对话: ¥0.005
+
+**月度成本**（1000次深度分析）:
+- 1000次 × ¥0.012 = ¥12
+
+**结论**: 非常便宜！1000次深度分析只需要12元。
+
+### 使用 DeepSeek（更便宜）
+
+**价格**: ¥0.001/1000 tokens（比通义千问便宜4倍）
+
+**月度成本**（1000次深度分析）:
+- 1000次 × ¥0.003 = ¥3
+
+## 📊 监控和优化
+
+### 1. 添加日志监控
+
+```bash
+# 实时查看 Agent 日志
+tail -f mcp_server.log | grep -E "\[Agent\]|\[Planning\]|\[Execution\]|\[Summary\]"
+```
+
+### 2. 性能优化建议
+
+1. **缓存计划**: 相似的问题可以复用执行计划
+2. **并行执行**: 独立的工具调用可以并行执行
+3. **流式输出**: 使用 Server-Sent Events 实时返回进度
+4. **结果缓存**: 相同的工具调用结果可以缓存
+
+### 3. 添加统计分析
+
+在 `mcp_server.py` 中添加：
+
+```python
+from datetime import datetime
+import json
+
+# 记录每次 Agent 调用
+@app.post("/agent/chat")
+async def agent_chat(request: ChatRequest):
+    start_time = datetime.now()
+
+    response = await agent.process_query(...)
+
+    duration = (datetime.now() - start_time).total_seconds()
+
+    # 记录到日志
+    logger.info(f"Agent query completed in {duration:.2f}s", extra={
+        "query": request.message,
+        "steps": len(response.plan.steps) if response.plan else 0,
+        "success": response.success,
+        "duration": duration,
+    })
+
+    return response
+```
+
+## 🎉 完成！
+
+现在你的 AI Agent 系统已经部署完成！
+
+访问 https://valuefrontier.cn/agent-chat 开始使用。
+
+**特点**:
+- ✅ 三阶段智能分析（计划-执行-总结）
+- ✅ 漂亮的UI界面（卡片式展示）
+- ✅ 步骤结果可折叠查看
+- ✅ 实时进度反馈
+- ✅ 异常处理和重试
+- ✅ 成本低廉（¥3-12/月）

docs/MCP_ARCHITECTURE.md

@@ -0,0 +1,309 @@
+# MCP 架构说明
+
+## 🎯 MCP 是什么？
+
+**MCP (Model Context Protocol)** 是一个**工具调用协议**，它的核心职责是：
+
+1. ✅ **定义工具接口**：告诉 LLM 有哪些工具可用，每个工具需要什么参数
+2. ✅ **执行工具调用**：根据请求调用对应的后端 API
+3. ✅ **返回结构化数据**：将 API 结果返回给调用方
+
+**MCP 不负责**：
+- ❌ 自然语言理解（NLU）
+- ❌ 意图识别
+- ❌ 结果总结
+- ❌ 对话管理
+
+## 📊 当前架构
+
+### 方案 1：简单关键词匹配（已实现）
+
+```
+用户输入："查询贵州茅台的股票信息"
+    ↓
+前端 ChatInterface (关键词匹配)
+    ↓
+MCP 工具层 (search_china_news)
+    ↓
+返回 JSON 数据
+    ↓
+前端显示原始数据
+```
+
+**问题**：
+- ✗ 只能识别简单关键词
+- ✗ 无法理解复杂意图
+- ✗ 返回的是原始 JSON，用户体验差
+
+### 方案 2：集成 LLM（推荐）
+
+```
+用户输入："查询贵州茅台的股票信息"
+    ↓
+LLM (Claude/GPT-4/通义千问)
+    ↓ 理解意图：需要查询股票代码 600519 的基本信息
+    ↓ 选择工具：get_stock_basic_info
+    ↓ 提取参数：{"seccode": "600519"}
+MCP 工具层
+    ↓ 调用 API，获取数据
+返回结构化数据
+    ↓
+LLM 总结结果
+    ↓ "贵州茅台（600519）是中国知名的白酒生产企业，
+       当前股价 1650.00 元，市值 2.07 万亿..."
+前端显示自然语言回复
+```
+
+**优势**：
+- ✓ 理解复杂意图
+- ✓ 自动选择合适的工具
+- ✓ 自然语言总结，用户体验好
+- ✓ 支持多轮对话
+
+## 🔧 实现方案
+
+### 选项 A：前端集成 LLM（快速实现）
+
+**适用场景**：快速原型、小规模应用
+
+**优点**：
+- 实现简单
+- 无需修改后端
+
+**缺点**：
+- API Key 暴露在前端（安全风险）
+- 每个用户都消耗 API 额度
+- 无法统一管理和监控
+
+**实现步骤**：
+
+1. 修改 `src/components/ChatBot/ChatInterface.js`：
+
+```javascript
+import { llmService } from '../../services/llmService';
+
+const handleSendMessage = async () => {
+  // ...
+
+  // 使用 LLM 服务替代简单的 mcpService.chat
+  const response = await llmService.chat(inputValue, messages);
+
+  // ...
+};
+```
+
+2. 配置 API Key（在 `.env.local`）：
+
+```bash
+REACT_APP_OPENAI_API_KEY=sk-xxx...
+# 或者使用通义千问（更便宜）
+REACT_APP_DASHSCOPE_API_KEY=sk-xxx...
+```
+
+### 选项 B：后端集成 LLM（生产推荐）⭐
+
+**适用场景**：生产环境、需要安全和性能
+
+**优点**：
+- ✓ API Key 安全（不暴露给前端）
+- ✓ 统一管理和监控
+- ✓ 可以做缓存优化
+- ✓ 可以做速率限制
+
+**缺点**：
+- 需要修改后端
+- 增加服务器成本
+
+**实现步骤**：
+
+#### 1. 安装依赖
+
+```bash
+pip install openai
+```
+
+#### 2. 修改 `mcp_server.py`，添加聊天端点
+
+在文件末尾添加：
+
+```python
+from mcp_chat_endpoint import MCPChatAssistant, ChatRequest, ChatResponse
+
+# 创建聊天助手实例
+chat_assistant = MCPChatAssistant(provider="qwen")  # 推荐使用通义千问
+
+@app.post("/chat", response_model=ChatResponse)
+async def chat_endpoint(request: ChatRequest):
+    """智能对话端点 - 使用LLM理解意图并调用工具"""
+    logger.info(f"Chat request: {request.message}")
+
+    # 获取可用工具列表
+    tools = [tool.dict() for tool in TOOLS]
+
+    # 调用聊天助手
+    response = await chat_assistant.chat(
+        user_message=request.message,
+        conversation_history=request.conversation_history,
+        tools=tools,
+    )
+
+    return response
+```
+
+#### 3. 配置环境变量
+
+在服务器上设置：
+
+```bash
+# 方式1：使用通义千问（推荐，价格便宜）
+export DASHSCOPE_API_KEY="sk-xxx..."
+
+# 方式2：使用 OpenAI
+export OPENAI_API_KEY="sk-xxx..."
+
+# 方式3：使用 DeepSeek（最便宜）
+export DEEPSEEK_API_KEY="sk-xxx..."
+```
+
+#### 4. 修改前端 `mcpService.js`
+
+```javascript
+/**
+ * 智能对话 - 使用后端LLM处理
+ */
+async chat(userMessage, conversationHistory = []) {
+  try {
+    const response = await this.client.post('/chat', {
+      message: userMessage,
+      conversation_history: conversationHistory,
+    });
+
+    return {
+      success: true,
+      data: response,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message || '对话处理失败',
+    };
+  }
+}
+```
+
+#### 5. 修改前端 `ChatInterface.js`
+
+```javascript
+const handleSendMessage = async () => {
+  // ...
+
+  try {
+    // 调用后端聊天API
+    const response = await mcpService.chat(inputValue, messages);
+
+    if (response.success) {
+      const botMessage = {
+        id: Date.now() + 1,
+        content: response.data.message,  // LLM总结的自然语言
+        isUser: false,
+        type: 'text',
+        timestamp: new Date().toISOString(),
+        toolUsed: response.data.tool_used,  // 可选：显示使用了哪个工具
+        rawData: response.data.raw_data,    // 可选：原始数据（折叠显示）
+      };
+      setMessages((prev) => [...prev, botMessage]);
+    }
+  } catch (error) {
+    // ...
+  }
+};
+```
+
+## 💰 LLM 选择和成本
+
+### 推荐：通义千问（阿里云）
+
+**优点**：
+- 价格便宜（1000次对话约 ¥1-2）
+- 中文理解能力强
+- 国内访问稳定
+
+**价格**：
+- qwen-plus: ¥0.004/1000 tokens（约 ¥0.001/次对话）
+- qwen-turbo: ¥0.002/1000 tokens（更便宜）
+
+**获取 API Key**：
+1. 访问 https://dashscope.console.aliyun.com/
+2. 创建 API Key
+3. 设置环境变量 `DASHSCOPE_API_KEY`
+
+### 其他选择
+
+| 提供商 | 模型 | 价格 | 优点 | 缺点 |
+|--------|------|------|------|------|
+| **通义千问** | qwen-plus | ¥0.001/次 | 便宜、中文好 | - |
+| **DeepSeek** | deepseek-chat | ¥0.0005/次 | 最便宜 | 新公司 |
+| **OpenAI** | gpt-4o-mini | $0.15/1M tokens | 能力强 | 贵、需翻墙 |
+| **Claude** | claude-3-haiku | $0.25/1M tokens | 理解力强 | 贵、需翻墙 |
+
+## 🚀 部署步骤
+
+### 1. 后端部署
+
+```bash
+# 安装依赖
+pip install openai
+
+# 设置 API Key
+export DASHSCOPE_API_KEY="sk-xxx..."
+
+# 重启服务
+sudo systemctl restart mcp-server
+
+# 测试聊天端点
+curl -X POST https://valuefrontier.cn/mcp/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "查询贵州茅台的股票信息"}'
+```
+
+### 2. 前端部署
+
+```bash
+# 构建
+npm run build
+
+# 部署
+scp -r build/* user@server:/var/www/valuefrontier.cn/
+```
+
+### 3. 验证
+
+访问 https://valuefrontier.cn/agent-chat，测试对话：
+
+**测试用例**：
+1. "查询贵州茅台的股票信息" → 应返回自然语言总结
+2. "今日涨停的股票有哪些" → 应返回涨停股票列表并总结
+3. "新能源概念板块表现如何" → 应搜索概念并分析
+
+## 📊 对比总结
+
+| 特性 | 简单匹配 | 前端LLM | 后端LLM ⭐ |
+|------|---------|---------|-----------|
+| 实现难度 | 简单 | 中等 | 中等 |
+| 用户体验 | 差 | 好 | 好 |
+| 安全性 | 高 | 低 | 高 |
+| 成本 | 无 | 用户承担 | 服务器承担 |
+| 可维护性 | 差 | 中 | 好 |
+| **推荐指数** | ⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ |
+
+## 🎯 最终推荐
+
+**生产环境：后端集成 LLM (方案 B)**
+- 使用通义千问（qwen-plus）
+- 成本低（约 ¥50/月，10000次对话）
+- 安全可靠
+
+**快速原型：前端集成 LLM (方案 A)**
+- 适合演示
+- 快速验证可行性
+- 后续再迁移到后端