PolyWeather/README_ZH.md

# 🌡️ PolyWeather: Polymarket 天气交易监控系统

基于多源实时气象数据与 Polymarket 市场定价偏差分析的智能监控与指令系统。

## 🚀 运行指令

### 环境要求

- **Python 3.11** (必须，`py-clob-client` 依赖要求)
- 已安装所有依赖：`pip install -r requirements.txt`

### Windows 启动方式

```powershell
# 方式一：使用 Python 3.11 启动器
py -3.11 run.py

# 方式二：激活虚拟环境后运行
.venv\Scripts\activate  # 激活虚拟环境
python run.py
```

### Linux/VPS 启动方式

```bash
# 使用 screen 保持后台运行
screen -S polyweather
python3.11 run.py

# 按 Ctrl+A 然后 D 退出但保持运行
# 恢复：screen -r polyweather
```

该命令会同时启动：

1. **监控引擎**: 负责 7x24h 扫描并推送 **85¢-95¢ 价格预警** 与 **市场异常**。
2. **指令监听器**: 监听电报指令并返回实时信号。

---

## 🤖 电报机器人指令集

| 指令              | 描述             | 用法                          |
| :---------------- | :--------------- | :---------------------------- |
| `/signal`         | **获取交易信号** | 返回最早结算市场的 Top 5 档位 |
| `/city [城市名]`  | **查询城市详情** | 获取指定城市的市场、预测和实测温度 |
| `/portfolio`      | **查看模拟仓位** | 获取实时模拟交易盈亏汇总报告  |
| `/status`         | **检查系统状态** | 确认监控引擎是否在线          |
| `/help`           | **指令帮助**     | 显示所有可用指令              |

### /city 指令示例

```
/city chicago
```

返回内容：
```
📍 Chicago 市场详情
════════════════════

🕐 当地时间: 08:30

📊 Open-Meteo 预测
👉 今天: 最高 38°F
   02-08: 最高 42°F
   02-09: 最高 45°F

✈️ 机场实测 (KORD)
   🌡️ 32.0°F
   💨 风速: 12kt
   🕐 观测: 14:00 UTC

📅 2026-02-07 预测:38°F
──────────────────
🔥 40-41°F: No 94¢ →买NO
🔥 38-39°F: Yes 91¢ →买YES
⭐ 36-37°F: No 87¢ →买NO
```

支持城市缩写: `chi` (Chicago), `nyc` (New York), `atl` (Atlanta), `sea` (Seattle), `dal` (Dallas), `mia` (Miami)

---

## 🎯 智能动态仓位策略

系统结合 **Open-Meteo 天气预测**、**成交量** 和 **价格锁定程度** 自动决定仓位大小：

| 条件组合                        | 仓位    | 标签       | 说明           |
| ------------------------------- | ------- | ---------- | -------------- |
| 价格 ≥90¢ + 天气支持 + 高成交量 | **$10** | 🔥高置信   | 三重确认，重注 |
| 价格 ≥90¢ + 天气支持            | **$7**  | ⭐中置信   | 双重确认       |
| 价格 ≥92¢                       | **$5**  | 📌价格锁定 | 纯价格锁定     |
| 其他 85-91¢                     | **$3**  | 💡试探     | 最小仓位试探   |

### 天气支持判断逻辑

- **买 NO**：Open-Meteo 预测温度在选项区间 **之外** (±2° 容差)
- **买 YES**：Open-Meteo 预测温度 **落入** 选项区间

### 成交量判断

- **高成交量**：单个选项成交量 ≥ $5,000

---

## 📢 推送维度说明

### 1. 📂 城市预警汇总 (主动推送)

- **优化机制**: 同一轮扫描中，同一城市的所有异动将**合并为一条消息**发送，拒绝刷屏。
- **触发内容**: 包含该城市下所有符合条件的"价格预警"与"市场异常"。
- **价格来源**: 推送使用真实 **Ask 价格**（实际可成交价格），而非中间价
- **推送格式**:

  ```
  📍 Chicago 市场动态
  🕐 当地 08:30 | 预测最高:38°F
  ═══════════════════════

  ✈️ 机场实测 (KORD):
     🌡️ 32.0°F | 风速:12kt
     🕐 观测: 14:00 UTC

  ⚡ 40-41°F (2026-02-07): Buy No 87¢ | 预测:38°F [🛒 $10.0 🔥高置信]

  💡 策略建议:
  • 预测温度38.0°F落在40-41°F区间，市场与模型一致
  ```

### 2. ✈️ METAR 航空气象实测数据

当天结算的市场会自动获取 **METAR 机场实测数据**，在预警中显示真实观测值：

```
✈️ 机场实测 (KORD):
   🌡️ 12.0°F | 风速:15kt
   🕐 观测: 11:00 UTC
```

**ICAO 机场代码映射表**:

| 城市          | ICAO | 机场名称                    |
| ------------- | ---- | --------------------------- |
| Seattle       | KSEA | Seattle-Tacoma International |
| London        | EGLC | London City Airport          |
| Dallas        | KDAL | Dallas Love Field            |
| Miami         | KMIA | Miami International          |
| Atlanta       | KATL | Hartsfield-Jackson Atlanta   |
| Chicago       | KORD | O'Hare International         |
| New York      | KLGA | LaGuardia Airport            |
| Seoul         | RKSI | Incheon International        |
| Ankara        | LTAC | Esenboga Airport             |
| Toronto       | CYYZ | Pearson International        |
| Wellington    | NZWN | Wellington International     |
| Buenos Aires  | SAEZ | Ministro Pistarini           |

**数据源**: NOAA Aviation Weather Center (免费 API，无需 Key)

### 3. ⚡ 价格预警 (触发模拟买入)

- **触发条件**: Buy Yes 或 Buy No 价格在 **85¢-95¢** 区间。
- **关联动作**: 系统根据智能仓位策略自动执行 **$3-$10** 的模拟开仓。
- **用途**: 高胜率/即将锁定区间提醒，适合平仓或收割。

### 4. 👀 市场异常

- **大户入场**: 检测到单笔 >$5000 的大额交易且买卖比失衡。
- **异常交易流**: 成交量突然放大 (>2倍历史标准差)。

### 5. 📅 每日盈亏总结

- **触发时间**: 北京时间 23:55 左右自动推送。
- **内容**: 汇总当日所有模拟仓位的浮动盈亏、余额变动及胜率统计。

### 6. 🎯 交易信号 (`/signal` 指令)

优先显示**最早结算日期**的市场，按机会价值排序，返回 **Top 5** 档位：

```
🎯 即将结算市场 (2026-02-06)
共 43 个活跃选项

🔥 1. Dallas 76-77°F
   💡 预测80.7°高于77° → 买NO ✓
   📊 Buy No 94¢ | ⏳接近锁定

🔥 2. Atlanta 56-57°F
   💡 预测60.4°高于57° → 买NO ✓
   📊 Buy No 94¢ | ⏳接近锁定

⭐ 3. Miami 62-63°F
   💡 预测65.3°高于63° → 买NO ✓
   📊 Buy No 88¢ | ⏳接近锁定
```

**锁定状态说明**:

- 🔒锁定: 价格 ≥95¢
- ⏳接近锁定: 价格 85-94¢
- 👀观望: 价格 70-84¢
- ⚖️均衡: 价格 <70¢

---

## 📊 模拟交易报告格式

通过 `/portfolio` 指令查看，报告按**目标日期分组**显示：

```
📊 模拟交易报告
════════════════════

📈 【2026-02-06】 小计: +2.45$
──────────────────
🟢 Chicago 40-41°F
   NO 87¢→92¢ 预测:38 | +0.47$
🟢 Chicago 32-33°F
   NO 94¢→98¢ 预测:38 | +0.12$

💰 持仓总计: +6.89$

📈 历史战绩:
累计成交: 18笔 | 胜率: 100.0%
已投入: $90.00 | 盈亏: +12.50$ (+13.9%)

════════════════════
💳 账户余额: $639.11
```

---

## 🛠️ 环境配置 (.env)

```bash
# Telegram 机器人
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# Polymarket API (用于批量获取实时盘口价格与交易历史)
POLYMARKET_API_KEY=your_api_key_here

# 代理设置 (如需要，VPS 部署时可删除)
HTTPS_PROXY=http://127.0.0.1:7890
HTTP_PROXY=http://127.0.0.1:7890
```

## 🏗️ 项目架构

本项目基于 **py-clob-client** 官方客户端，并配备 REST API 备用方案：

- 主要方式：使用 `py-clob-client` SDK 获取市场数据、订单簿、下单等
- 备用方式：当 SDK 失败时，自动切换到直接 REST API 调用 (`/price`, `/book`)
- 核心 API 封装在 `src/data_collection/polymarket_api.py`

### 价格获取

```python
# SDK 方式 (主要)
price = clob_client.get_price(token_id, side="BUY")

# REST API 备用 (当 SDK 失败时)
resp = requests.get("https://clob.polymarket.com/price", params={
    "token_id": token_id,
    "side": "BUY"
})
```

## 📂 数据文件说明

| 文件                        | 说明                       |
| --------------------------- | -------------------------- |
| `data/paper_positions.json` | 模拟仓持仓、余额、交易历史 |
| `data/pushed_signals.json`  | 已推送信号记录（防刷屏）   |
| `data/active_signals.json`  | 当前活跃交易信号           |
| `data/all_markets.json`     | 全量市场缓存               |
| `data/price_history.json`   | 价格历史（用于趋势计算）   |

---

## 📋 核心功能特性

- ✅ **智能动态仓位**: 结合天气预测、成交量、价格锁定程度自动调整仓位 ($3-$10)。
- ✅ **预测温度追踪**: 每笔交易记录买入时的 Open-Meteo 预测温度，方便复盘验证。
- ✅ **智能合并推送**: 按城市汇总预警，界面整洁不刷屏。
- ✅ **全自动模拟交易**: 内置模拟仓位系统，支持 85-95¢ 区间自动跟单，记录实战胜率。
- ✅ **极速价格同步**: 采用 Polymarket 批量 API 接口，一次同步全量城市，无延迟、无 404。
- ✅ **北京时间适配**: 所有推送时间戳与每日总结均自动转换为北京时间 (UTC+8)。
- ✅ **智能日期选择**: 自动定位最早的活跃市场日期，结算后自动顺延。
- ✅ **温度单位自适应**: 美国市场切换华氏度 (°F)，其他地区显示摄氏度 (°C)。
- ✅ **全量数据持久化**: 信号记录、推送历史、交易仓位均保存至本地 JSON。

---

## 🔄 VPS 更新步骤

```bash
# 1. 本地推送代码
git add . && git commit -m "update" && git push

# 2. VPS 拉取并重启
ssh root@VPS_IP "cd ~/PolyWeather && git pull && screen -S polyweather -X quit; screen -dmS polyweather python run.py"
```