# 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/月）