# 黄金交易智能体 (Gold Agent) 技术调研与系统设计

## 一、项目概述

### 1.1 目标
构建一个基于 LLM 驱动的黄金 (XAUUSD) 行情分析智能体，对接 MetaTrader 5 (MT5) 进行实盘交易。

### 1.2 核心功能
- 实时获取黄金行情数据（通过 MT5）
- LLM 驱动的市场分析与信号生成
- 自动化交易执行（MT5 实盘）
- 风险管理与仓位控制
- 飞书/Telegram 通知推送

---

## 二、技术调研

### 2.1 MetaTrader 5 (MT5) API 调研

#### MT5 Python 库
```python
import MetaTrader5 as mt5

# 初始化
mt5.initialize()

# 获取行情数据
rates = mt5.copy_rates_from_pos("XAUUSD", mt5.TIMEFRAME_M15, 0, 100)

# 获取当前价格
tick = mt5.symbol_info_tick("XAUUSD")
bid = tick.bid
ask = tick.ask

# 下单
request = {
    "action": mt5.TRADE_ACTION_DEAL,
    "symbol": "XAUUSD",
    "volume": 0.01,  # 手数
    "type": mt5.ORDER_TYPE_BUY,
    "price": ask,
    "deviation": 20,
    "magic": 234000,
    "comment": "Gold Agent",
    "type_time": mt5.ORDER_TIME_GTC,
    "type_filling": mt5.ORDER_FILLING_IOC,
}
mt5.order_send(request)
```

#### MT5 核心概念
| 概念 | 说明 |
|------|------|
| **手数 (Lot)** | 黄金最小 0.01 手，1 手 = 100 盎司 |
| **点值 (Point)** | 0.01 美元/点，1 点 = 0.01 USD |
| **杠杆** | 通常 1:100 - 1:500，由经纪商设定 |
| **交易时间** | 周一 00:00 - 周六 00:00 (服务器时间) |
| **点差** | 通常 20-50 点 (0.2-0.5 USD) |

### 2.2 黄金交易特点

#### XAUUSD 特性
| 特性 | 说明 | 交易策略影响 |
|------|------|-------------|
| **波动性高** | 日波动 50-200 点 | 需要宽止损 (30-50 点) |
| **流动性强** | 24 小时交易 | 可设置夜间交易 |
| **美元相关** | 与美元指数负相关 | 需关注 USD 数据 |
| **避险属性** | 市场恐慌时上涨 | 需关注 VIX 指数 |
| **交易时段** | 伦敦盘 (15:00-24:00) 和 纽约盘 (21:00-04:00) 最活跃 | 重点交易时段 |
| **周末停盘** | 周末不交易 | 周五收盘前需要平仓或宽止损 |

#### 技术指标适用性
- **趋势类**: MA, EMA, MACD 效果较好
- **震荡类**: RSI, KDJ 在盘整市有效
- **波动率类**: ATR 对止损设置重要
- **支撑阻力**: 黄金的关键整数位 ($2000, $2050, $2100) 效果明显

---

## 三、系统架构设计

### 3.1 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                      Gold Agent 主控制器                      │
│                   (gold_agent/gold_agent.py)                 │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   MT5 服务      │ │ 市场信号分析器  │ │  交易决策器     │
│  (mt5_service)  │ │ (market_signal_  │ │ (trading_       │
│                 │ │  analyzer)      │ │  decision)      │
└─────────────────┘ └─────────────────┘ └─────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   飞书/Telegram │ │   模拟交易      │ │   实盘交易      │
│     通知        │ │  (paper_        │ │  (mt5_          │
│                 │ │   trading)      │ │   trading)      │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```

### 3.2 目录结构

```
backend/app/
├── gold_agent/                    # 黄金智能体模块
│   ├── __init__.py
│   ├── gold_agent.py             # 主控制器
│   ├── market_signal_analyzer.py # 市场信号分析器
│   ├── trading_decision_maker.py # 交易决策器
│   └── strategy.py               # 交易策略定义
│
├── services/                      # 服务层
│   ├── mt5_service.py            # MT5 数据服务
│   ├── mt5_trading_service.py    # MT5 实盘交易服务
│   └── gold_paper_trading.py     # 黄金模拟交易服务
│
├── models/                        # 数据模型
│   └── gold_order.py             # 黄金订单模型
│
└── api/                           # API 接口
    └── gold.py                   # 黄金智能体 API
```

### 3.3 数据流设计

```
MT5 行情数据
    │
    ▼
┌─────────────────────────┐
│  技术指标计算            │
│  (MA, EMA, RSI, MACD...) │
└─────────────────────────┘
    │
    ▼
┌─────────────────────────┐
│  市场信号分析 (LLM)      │
│  - 趋势判断              │
│  - 关键价位              │
│  - 信号生成              │
└─────────────────────────┘
    │
    ▼
┌─────────────────────────┐
│  交易决策 (LLM)          │
│  - 开仓/平仓/观望        │
│  - 仓位大小              │
│  - 止损止盈              │
└─────────────────────────┘
    │
    ▼
┌─────────────────────────┐
│  风险检查                │
│  - 仓位限制              │
│  - 价格合理性验证        │
│  - 交易时段检查          │
└─────────────────────────┘
    │
    ▼
┌─────────────────────────┐
│  执行交易                │
│  - 模拟交易 (回测)       │
│  - 实盘交易 (MT5)        │
└─────────────────────────┘
    │
    ▼
┌─────────────────────────┐
│  通知推送                │
│  - 飞书卡片              │
│  - Telegram 消息         │
└─────────────────────────┘
```

---

## 四、核心模块设计

### 4.1 MT5 服务 (mt5_service.py)

```python
class MT5Service:
    """MT5 数据服务 - 获取行情数据"""

    def __init__(self):
        self.connected = False
        self.symbol = "XAUUSD"

    def initialize(self, account: int, password: str, server: str) -> bool
    def get_rates(self, timeframe: str, count: int) -> pd.DataFrame
    def get_current_price(self) -> Tuple[float, float]  # (bid, ask)
    def get_tick(self) -> Dict
    def get_positions(self) -> List[Dict]
    def get_orders(self) -> List[Dict]
    def get_account_info(self) -> Dict
```

#### 时间周期映射
| 代码 | MT5 常量 | 用途 |
|------|----------|------|
| `M1` | `TIMEFRAME_M1` | 短线交易 |
| `M5` | `TIMEFRAME_M5` | 主要分析周期 |
| `M15` | `TIMEFRAME_M15` | 中线交易 |
| `H1` | `TIMEFRAME_H1` | 趋势确认 |
| `H4` | `TIMEFRAME_H4` | 日内趋势 |
| `D1` | `TIMEFRAME_D1` | 长期趋势 |

### 4.2 市场信号分析器 (market_signal_analyzer.py)

```python
class GoldMarketSignalAnalyzer:
    """黄金市场信号分析器"""

    MARKET_ANALYSIS_PROMPT = """你是一位专业的黄金交易员...

    ## 黄金交易特点
    - XAUUSD 极其活跃，日波动 50-200 点
    - 关键整数位: $2000, $2050, $2100, $2150, $2200
    - 伦敦盘 (15:00-24:00) 和 纽约盘 (21:00-04:00) 最活跃
    - 周五收盘前需要谨慎持仓

    ## 输出格式
    {
      "trend_direction": "uptrend/downtrend/neutral",
      "trend_strength": "strong/medium/weak",
      "signals": [
        {
          "action": "buy/sell",
          "entry_zone": 2050.50,
          "stop_loss": 2045.00,
          "take_profit": 2060.00,
          "confidence": 85,
          "grade": "A",
          "reasoning": "..."
        }
      ],
      "key_levels": {
        "support": [2045.00, 2040.00],
        "resistance": [2060.00, 2065.00]
      }
    }
    """

    async def analyze(self, symbol: str, data: Dict) -> Dict
```

### 4.3 交易决策器 (trading_decision_maker.py)

```python
class GoldTradingDecisionMaker:
    """黄金交易决策器"""

    TRADING_DECISION_PROMPT = """你是黄金交易执行者...

    ## 账户信息
    - 余额: {balance}
    - 持仓: {positions}
    - 杠杆: 1:100

    ## 黄金交易规则
    - 最小手数: 0.01 手
    - 1 手 = 100 盎司
    - 点值: 0.01 USD/点
    - 建议止损: 30-50 点
    - 建议止盈: 1:2 或 1:3

    ## 输出格式
    {
      "decision": "OPEN/CLOSE/HOLD",
      "action": "buy/sell",
      "quantity": 0.01,  # 手数
      "entry_zone": 2050.50,
      "stop_loss": 2045.00,
      "take_profit": 2060.00,
      "reasoning": "..."
    }
    """

    async def make_decision(self, market_signal, positions, account) -> Dict
```

### 4.4 MT5 实盘交易服务 (mt5_trading_service.py)

```python
class MT5TradingService:
    """MT5 实盘交易服务"""

    def __init__(self):
        self.mt5 = mt5
        self.magic_number = 234000  # 识别 Gold Agent 的订单

    def connect(self, account: int, password: str, server: str) -> bool
    def open_order(self, action: str, volume: float, price: float,
                   sl: float, tp: float) -> Dict
    def close_order(self, order_id: int) -> Dict
    def close_all_positions(self) -> Dict
    def get_positions(self) -> List[Dict]
    def modify_position(self, ticket: int, sl: float, tp: float) -> Dict
```

#### 订单类型说明
| 类型 | MT5 常量 | 说明 |
|------|----------|------|
| 市价买单 | `ORDER_TYPE_BUY` | 以 Ask 价格成交 |
| 市价卖单 | `ORDER_TYPE_SELL` | 以 Bid 价格成交 |
| 限价买单 | `ORDER_TYPE_BUY_LIMIT` | 低于当前价挂单 |
| 限价卖单 | `ORDER_TYPE_SELL_LIMIT` | 高于当前价挂单 |

### 4.5 风险控制规则

```python
# 仓位管理
MAX_POSITIONS = 3  # 最大同时持仓数
MAX_LOTS_PER_ORDER = 0.1  # 单笔最大手数
MAX_TOTAL_LOTS = 0.3  # 总持仓上限

# 止损止盈规则
MIN_STOP_LOSS_POINTS = 30  # 最小止损 30 点 (0.30 USD)
TAKE_PROFIT_RATIO = 2.0  # 止盈/止损比 1:2

# 价格合理性验证
MAX_PRICE_DEVIATION = 0.20  # 价格偏离不超过 20%

# 交易时段
WEEKEND_CLOSE_HOUR = 20  # 周五 20:00 后不开新仓
NEWS_FILTER_WINDOW = 30  # 重大新闻前后 30 分钟不开仓
```

---

## 五、实现计划

### Phase 1: 基础设施 (第 1-2 周)
- [ ] MT5 服务封装
  - [ ] 连接管理
  - [ ] 行情数据获取
  - [ ] 账户信息查询
- [ ] 数据模型定义
  - [ ] 黄金订单模型
  - [ ] 持仓记录模型
- [ ] 配置项添加
  - [ ] MT5 账户配置
  - [ ] 飞书 webhook 配置

### Phase 2: 分析与决策 (第 3-4 周)
- [ ] 市场信号分析器
  - [ ] 技术指标计算
  - [ ] LLM 提示词设计
  - [ ] 信号生成逻辑
- [ ] 交易决策器
  - [ ] 持仓状态判断
  - [ ] 开平仓决策
  - [ ] 仓位大小计算

### Phase 3: 交易执行 (第 5-6 周)
- [ ] 模拟交易服务
  - [ ] 订单管理
  - [ ] 止损止盈执行
  - [ ] 移动止损逻辑
- [ ] MT5 实盘交易服务
  - [ ] 订单发送
  - [ ] 持仓查询
  - [ ] 订单修改/平仓

### Phase 4: 风险管理与通知 (第 7 周)
- [ ] 风险控制模块
  - [ ] 仓位限制
  - [ ] 价格验证
  - [ ] 交易时段检查
- [ ] 通知推送
  - [ ] 飞书卡片格式
  - [ ] Telegram 消息推送

### Phase 5: 测试与优化 (第 8 周)
- [ ] 模拟盘测试
- [ ] 实盘小资金测试
- [ ] 性能优化
- [ ] 文档完善

---

## 六、风险考虑

### 6.1 技术风险

| 风险 | 应对措施 |
|------|----------|
| MT5 连接断开 | 自动重连机制，连接状态监控 |
| 订单执行失败 | 超时重试，失败告警 |
| 数据延迟 | 多时间周期数据验证 |
| 系统崩溃 | 持久化状态，重启恢复 |

### 6.2 交易风险

| 风险 | 应对措施 |
|------|----------|
| 市场剧烈波动 | 宽止损 + 小仓位 |
| 流动性枯竭 | 避开非交易时段 |
| 滑点风险 | 使用限价单，设置最大滑点 |
| 重大新闻事件 | 新闻过滤窗口，避免开仓 |

### 6.3 LLM 相关风险

| 风险 | 应对措施 |
|------|----------|
| 幻觉导致错误价格 | 价格合理性验证 |
| 信号质量不稳定 | 多信号确认，降低单次权重 |
| 延迟影响执行 | 缓存机制，异步处理 |

---

## 七、配置项设计

### 7.1 config.py 新增配置

```python
# ==================== 黄金交易智能体配置 ====================
# MT5 连接配置
mt5_account: int = 0  # MT5 账号
mt5_password: str = ""  # MT5 密码
mt5_server: str = ""  # MT5 服务器地址

# 黄金交易配置
gold_symbol: str = "XAUUSD"  # 黄金交易品种
gold_analysis_interval: int = 300  # 分析间隔（秒）
gold_enabled: bool = False  # 是否启用黄金智能体

# 仓位管理
gold_max_positions: int = 3  # 最大持仓数
gold_max_lots_per_order: float = 0.1  # 单笔最大手数
gold_max_total_lots: float = 0.3  # 总持仓上限
gold_default_lots: float = 0.01  # 默认手数

# 止损止盈
gold_min_stop_loss_points: float = 30  # 最小止损（点）
gold_take_profit_ratio: float = 2.0  # 止盈/止损比

# 交易时段
gold_weekend_close_hour: int = 20  # 周五收盘时间
gold_news_filter_minutes: int = 30  # 新闻过滤窗口（分钟）

# 通知配置
feishu_gold_webhook_url: str = ""  # 黄金智能体飞书通知
```

### 7.2 环境变量 (.env)

```bash
# MT5 配置
MT5_ACCOUNT=12345678
MT5_PASSWORD=your_password
MT5_SERVER=your_broker_server

# 黄金智能体
GOLD_ENABLED=True
GOLD_SYMBOL=XAUUSD

# 飞书通知
FEISHU_GOLD_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/...
```

---

## 八、监控指标

### 8.1 系统监控
- MT5 连接状态
- 分析执行频率
- LLM 调用延迟
- 订单执行成功率

### 8.2 交易监控
- 当前持仓数
- 总盈亏 (USD)
- 胜率
- 最大回撤
- 平均持仓时间

### 8.3 信号监控
- 信号生成频率
- A/B/C/D 级信号分布
- 信号执行率
- 信号盈亏比

---

## 九、后续优化方向

1. **多品种支持** - 扩展到 XAGUSD (白银)、其他贵金属
2. **智能参数调优** - 基于历史数据自动优化参数
3. **策略回测** - 使用 MT5 历史数据进行策略回测
4. **风险模型升级** - VaR 计算、凯利公式仓位管理
5. **机器学习增强** - 使用 ML 模型辅助 LLM 决策

---

## 十、总结

本设计方案基于现有 Crypto Agent 架构，复用了：
- LLM 驱动的市场分析框架
- 交易决策框架
- 风险验证逻辑
- 通知推送机制

主要新增：
- MT5 数据与交易接口
- 黄金特定的交易规则
- 适配黄金特点的提示词

预计开发周期：**8 周**
风险等级：**中等** (实盘交易需谨慎)
投入建议：**先模拟盘充分测试后再小资金实盘**