Merge branch 'main' of https://github.com/yangyuan-zhen/PolyWeather

README_ZH.md

@@ -1,6 +1,6 @@
 # 🌡️ PolyWeather: 实时天气查询与分析机器人
 
-一个智能天气信息机器人，专为提供超快、实时的气象数据、高保真预报和智能趋势分析而设计。通过绕过网络缓存，直接从全球气象站获取最新数据。
+专为预测市场和天气博弈设计的智能天气机器人。通过绕过 CDN 缓存直接从全球气象站获取最新数据，并提供**模型共识评分**和**入场时机信号**等通俗易懂的自动趋势分析。
 
 ## 🚀 快速开始
 
@@ -8,19 +8,55 @@
 
 - **Python 3.11+**
 - 依赖安装: `pip install -r requirements.txt`
+<<<<<<< HEAD
 - **环境变量**: 需在 `.env` 中配置 `METEOBLUE_API_KEY` 以激活伦敦高精度预报。
+=======
+- **环境变量**: 在 `.env` 中设置 `TELEGRAM_BOT_TOKEN`（必需）。可选设置 `METEOBLUE_API_KEY` 以激活伦敦高精度预报。
+>>>>>>> e575440acfd8b5f1e8c30e83dfcb972d26175729
 
-### 本地运行 (Windows/Linux)
+### VPS 部署 (推荐)
+
+**首次部署：**
 
 ```bash
-# Windows
-py -3.11 run.py
-
-# Linux/VPS
-python3 run.py
+git clone https://github.com/yangyuan-zhen/PolyWeather.git
+cd PolyWeather
+pip install -r requirements.txt
+cp .env.example .env  # 编辑 .env 填入你的 Token 和 API Key
 ```
 
-_注意：系统当前处于 **天气查询模式**。主动市场监控和自动交易模块已暂停。_
+**创建一键更新脚本（只需执行一次）：**
+
+```bash
+cat > ~/update.sh << 'EOF'
+#!/bin/bash
+cd ~/PolyWeather
+git fetch origin
+git reset --hard origin/main
+pkill -f run.py
+pkill -f bot_listener.py
+sleep 1
+nohup python3 run.py > bot.log 2>&1 &
+echo "✅ 已更新并重启！"
+EOF
+chmod +x ~/update.sh
+```
+
+**日常更新（每次代码推送后）：**
+
+```bash
+~/update.sh
+```
+
+> 一条命令完成：拉取最新代码 → 杀旧进程 → 启动新进程。无需手动处理分支冲突。
+
+### 本地开发 (Windows)
+
+```bash
+py -3.11 run.py
+```
+
+> 本地笔记本**不需要安装依赖**，只用来编辑代码和 Git 推送。IDE 的 import 报错是因为本地没装依赖，不影响 VPS 运行。
 
 ---
 
@@ -32,20 +68,49 @@ _注意：系统当前处于 **天气查询模式**。主动市场监控和自
 | `/id`          | **获取 Chat ID** | 获取当前 Telegram 聊天 ID        |
 | `/help`        | **帮助**         | 显示所有可用指令                 |
 
-### /city 指令示例
+### 支持的城市
+
+| 城市 | 缩写/别名 | METAR 机场 | 额外数据源 |
+|:---|:---|:---|:---|
+| 伦敦 London | `lon`, `伦敦` | EGLC (City Airport) | Meteoblue |
+| 巴黎 Paris | `par`, `巴黎` | LFPG (Charles de Gaulle) | — |
+| 安卡拉 Ankara | `ank`, `安卡拉` | LTAC (Esenboğa) | MGM |
+| 纽约 New York | `nyc`, `ny`, `纽约` | KLGA (LaGuardia) | NWS |
+| 芝加哥 Chicago | `chi`, `芝加哥` | KORD (O'Hare) | NWS |
+| 达拉斯 Dallas | `dal`, `达拉斯` | KDAL (Love Field) | NWS |
+| 迈阿密 Miami | `mia`, `迈阿密` | KMIA (International) | NWS |
+| 亚特兰大 Atlanta | `atl`, `亚特兰大` | KATL (Hartsfield-Jackson) | NWS |
+| 西雅图 Seattle | `sea`, `西雅图` | KSEA (Sea-Tac) | NWS |
+| 多伦多 Toronto | `tor`, `多伦多` | CYYZ (Pearson) | — |
+| 首尔 Seoul | `sel`, `首尔` | RKSI (Incheon) | — |
+| 布宜诺斯艾利斯 Buenos Aires | `ba`, `布宜诺斯艾利斯` | SAEZ (Ezeiza) | — |
+| 惠灵顿 Wellington | `wel`, `惠灵顿` | NZWN (Wellington) | — |
+
+### 使用示例
 
 ```
-/city 伦敦
+/city 巴黎
+/city london
+/city par
 ```
 
 ---
 
 ## ✨ 核心功能
 
-### 1. 🏛️ 多源数据融合 (Multi-Source Fusion)
+### 1. 🏛️ 多源数据融合
 
-机器人聚合了全球最权威的几个数据源，并按权重进行分层：
+| 数据源                  | 数据角色       | 覆盖范围   | 优势                                                         |
+| :---------------------- | :------------- | :--------- | :----------------------------------------------------------- |
+| **多模型 (5 NWP)**       | **共识评分**     | 全球       | ECMWF、GFS、ICON、GEM、JMA — 5 个完全独立的数值预报模型，经 Open-Meteo 统一获取 |
+| **Open-Meteo**          | 基础预测       | 全球       | 72h 逐小时温度曲线、日出日落、**日照时长**、**短波辐射**     |
+| **Open-Meteo Ensemble** | **不确定性区间** | 全球     | 51 成员集合预报：中位数、P10、P90 散度用于置信度评估         |
+| **Meteoblue (MB)**      | 高精度共识   | 仅限伦敦   | 聚合多家模型，对微气候处理极佳                               |
+| **METAR**               | **结算标准**   | 全球机场   | Polymarket 结算参考的绝对真理，实时机场观测                   |
+| **NWS**                 | 官方预测(美)   | 仅限美国   | 美国国家气象局高精度预报                                     |
+| **MGM**                 | 实测数据(土)   | 仅限安卡拉 | 土耳其气象局：气压、云量、体感温度、24h 降水                 |
 
+<<<<<<< HEAD
 | 数据源             | 数据角色       | 覆盖范围   | 优势                                             |
 | :----------------- | :------------- | :--------- | :----------------------------------------------- |
 | **Open-Meteo**     | 基础预测       | 全球       | 提供所有城市的 72 小时精细化温度曲线             |
@@ -53,61 +118,181 @@ _注意：系统当前处于 **天气查询模式**。主动市场监控和自
 | **METAR**          | **结算标准**   | 全球机场   | Polymarket 结算参考的绝对真理，实时机场观测      |
 | **NWS**            | 官方预测(美)   | 仅限美国   | 美国国家气象局，对美国城市的极端天气预判准确     |
 | **MGM**            | 官方预测(土)   | 仅限安卡拉 | 土耳其气象局，提供安卡拉 Esenboğa 机场的官方数据 |
+=======
+> ⚠️ **所有 NWP 模型查询使用机场坐标**（与 METAR 站点一致），而非市中心。这消除了预报位置与结算位置之间的系统性偏差。
+>>>>>>> e575440acfd8b5f1e8c30e83dfcb972d26175729
 
-### 2. ⚡ 超新鲜数据 (Cache-Busting)
+**Open-Meteo API 架构关系**：三个 API 调用都经过 Open-Meteo 平台，但获取的是不同维度的数据：
 
-为了应对气象博弈中秒级的变化，我们实现了 **0 缓存技术**：
+```
+                    Open-Meteo (API 平台)
+                          │
+            ┌─────────────┼─────────────┐
+            │             │             │
+     ┌──────┴──────┐      │      ┌──────┴──────┐
+     │ /forecast   │      │      │ /forecast   │
+     │ (默认模式)   │      │      │ ?models=... │
+     │ = best_match│      │      │ = 多模型模式 │
+     └──────┬──────┘      │      └──────┬──────┘
+            │             │             │
+            ▼             │             ▼
+     自动选最佳模型        │      返回每个模型单独结果
+     (通常 ≈ ECMWF)       │      ECMWF / GFS / ICON
+     → 逐小时曲线         │      GEM / JMA
+     → 日出日落           │      → 共识评分
+     → 日照/辐射          │
+                   ┌──────┴──────┐
+                   │  /ensemble  │
+                   │  51成员集合  │
+                   └──────┬──────┘
+                          │
+                          ▼
+                   中位数 / P10 / P90
+                   → 不确定性区间
+```
 
-- **微秒级令牌**：每个 API 请求都附带动态时间戳，强制气象服务器绕过 CDN 缓存返回最新值。
+> 💡 OM 默认预报本质上是 5 个模型中的**某一个**（自动选择），因此**不参与共识评分**，避免双重计数。
+
+### 2. ⚡ 超新鲜数据 (零缓存)
+
+- **动态时间戳**：每个 API 请求都附带唯一令牌，强制服务器绕过 CDN 缓存。
 - **MGM 实时同步**：针对土耳其 MGM API 做了专门的 Header 伪装和时区校正。
 
-### 3. ⏱️ 自动态势分析
+### 3. 🎯 多模型共识评分
 
-机器人不仅仅搬运数据，它还会进行逻辑加工：
+机器人同时查询 **5 个独立 NWP 模型**（ECMWF、GFS、ICON、GEM、JMA）来评估预报一致性：
 
-- **峰值时刻预测**：自动计算今天气温最高点出现的概率窗口（如：14:00 - 15:00）。
-- **风险等级 (Risk-Profile)**：根据地理特征（如安卡拉的高原温差、伦敦的近海微气候）自动分配风险等级。
-- **数据溯源**：报表明确标注每个数字的来源（[MGM], [METAR], [MB]）。
+| 等级 | 条件（摄氏/华氏） | 含义 |
+|:---|:---|:---|
+| 🎯 **高共识** | 极差 ≤ 0.8°C / 1.5°F | 5 个模型高度收敛 — 高置信，低风险 |
+| ⚖️ **中共识** | 极差 ≤ 1.5°C / 3.0°F | 轻微分歧 — 中等置信 |
+| ⚠️ **低共识** | 极差 > 1.5°C / 3.0°F | 模型严重分歧 — 不确定性大，建议观察 |
 
-### 4. 📊 智能最高温追踪
+主要模型：**ECMWF IFS**（欧洲）、**GFS**（美国 NOAA）、**ICON**（德国 DWD）、**GEM**（加拿大）、**JMA**（日本）。伦敦额外有 Meteoblue，美国城市额外有 NWS。集合预报中位数不参与评分，避免双重计数。
 
-针对 Polymarket 的结算逻辑进行优化：
+**核心逻辑**：当 5 个独立模型在温度区间上高度收敛，而市场定价尚未反映时，这就是典型的**结构性定价错误**——低风险套利的黄金机会。
 
-- **当地日历日过滤**：基于城市 UTC 偏移，严格统计当地时间 00:00 之后的实测最高温。
-- **多维度监测**：集成体感温度 (`feels_like`) 和 24h 累计降雨量，辅助多维度判断。
+### 4. 📊 集合预报散度（新功能）
+
+从 Open-Meteo 获取 51 成员集合预报，量化预测不确定性：
+
+> 📊 **集合预报**：中位数 10.8°C，90% 区间 [9.5°C - 12.1°C]，波动幅度 2.6°。
+
+区间窄 = 大气状态明确，预报可信。区间宽 = 大气混沌，风险高。
+
+**确定性 vs 集合偏差检测**：当 OM 确定性预报超过集合 P90 或低于 P10 时，机器人会发出警告。如果实测数据随后验证了预报，警告会升级为 ✅ **预报验证** 消息。
+
+### 5. ⏰ 入场时机信号（新功能）
+
+综合三个因子打分，给出入场建议：
+
+| 因子 | 分值 |
+|:---|:---|
+| 最热已过 | +3 |
+| 距峰值 ≤ 2h | +2 |
+| 距峰值 ≤ 4h | +1 |
+| 模型高共识 | +2 |
+| 模型中共识 | +1 |
+| 实测 ≈ 预报（差 ≤ 0.5°）| +2 |
+| 实测接近预报（差 ≤ 1.5°）| +1 |
+
+| 总分 ≥ | 信号 | 建议 |
+|:---|:---|:---|
+| 5 | ⏰ **理想** | 不确定性低，适合下注 |
+| 3 | ⏰ **较好** | 可以考虑小仓位入场 |
+| 2 | ⏰ **谨慎** | 建议继续观察 |
+| <2 | ⏰ **不建议** | 不确定性大，等更多数据 |
+
+**核心理念**：拒绝过早布局，选择接近解析时刻、波动率压缩时晚入场，降低不确定性风险。
+
+### 6. 🧠 智能趋势分析（通俗语言）
+
+机器人自动生成人类可读的分析洞察：
+
+- **🚨 预报击穿预警**：当 METAR 实测最高温超过所有预报时自动警报。
+- **⏱️ 峰值时段预测**：精确预测当日最高温出现的时间窗口。
+- **🌬️ 风向交叉验证**：同时对比 METAR 和 MGM 风向数据，差异超 90° 自动告警。
+- **🍃 风速分析**：标注风速并结合风向判断对温度的影响。
+- **☁️ 云层遮挡分析**：评估云量对升温潜力的影响（晴天/多云/阴天）。
+- **📉 气压分析**：低气压意味着暖湿气流过境，有利升温。
+- **🌧️ 降雨检测**：交叉验证 METAR 天气代码和实际降水量，避免误报。
+- **📊 最高温时间追踪**：精确显示每日最高温出现的时间（如 `最高: 12°C @14:20`）。
+- **☀️ 天气状况一览**：综合 METAR 天气现象 + 云量，生成一目了然的天气图标 + 文字（如 `⛅ 晴间多云`）。
+- **🌤️ 太阳辐射分析**：追踪累计短波辐射 vs 全天总量；当云层严重遮挡阳光时发出预警。
+- **🌙 暖平流检测**：当最高温出现在太阳辐射为零的时段（如凌晨 3 点），自动识别并标注"气温由暖空气推高，而非太阳晒热"。
+
+### 7. 📊 风险等级
+
+每个城市都有基于机场-市区距离的数据偏差风险档案：
+
+- 🔴 **高危**：首尔 (48.8km)、芝加哥 (25.3km) — 偏差大
+- 🟡 **中危**：安卡拉 (24.5km)、巴黎 (25.2km)、达拉斯、布宜诺斯艾利斯 — 有系统偏差
+- 🟢 **低危**：伦敦 (12.7km)、惠灵顿 (5.1km) — 数据靠谱
+
+### 8. 🌅 增强显示
+
+- **日出日落 + 日照时长**：`🌅 07:34 | 🌇 18:29 | ☀️ 9.9h`
+- **天气状况一目了然**：`✈️ 实测 (METAR): 9°C | ⛅ 晴间多云 | 15:00`
+- **WU 结算预览**：显示 Wunderground 四舍五入后的值，方便结算参考。
 
 ---
 
 ## 🏗️ 系统架构
 
-本项目采用 **“轻量化、插件式”** 架构，旨在实现毫秒级响应。
-
 ```mermaid
 graph TD
     User[/Telegram User/] --> Bot[bot_listener.py]
     Bot --> Collector[WeatherDataCollector]
 
+<<<<<<< HEAD
     subgraph "Data Engine"
         Collector --> OM[Open-Meteo API]
         Collector --> MB[Meteoblue Weather API]
         Collector --> NOAA[METAR Data Center]
         Collector --> MGM[Turkish MGM API]
+=======
+    subgraph "数据引擎"
+        Collector --> MM[多模型 API<br/>ECMWF/GFS/ICON/GEM/JMA]
+        Collector --> OM[Open-Meteo 预报]
+        Collector --> ENS[Open-Meteo Ensemble]
+        Collector --> MB[Meteoblue API]
+        Collector --> NOAA[METAR / NOAA]
+        Collector --> MGM[MGM 实测数据]
+>>>>>>> e575440acfd8b5f1e8c30e83dfcb972d26175729
         Collector --> NWS[US NWS API]
     end
 
-    Collector --> Processing[智能分析 & 格式化]
+    Collector --> Processing[共识评分 & 趋势分析]
     Processing --> Bot
-    Bot --> Reponse[/精简版博弈快照/]
+    Bot --> Response[/附带入场信号的天气快照/]
 ```
 
-- **逻辑解耦**：`weather_sources.py` 负责外部数据的解析；`bot_listener.py` 负责消息模板渲染。
-- **遗留模块说明**：项目根目录下的 `main.py` 包含旧版本的自动交易引擎。目前重心在“手动辅助决策”，如需开启请查阅 [MARKET_DISCOVERY_ZH.md](./MARKET_DISCOVERY_ZH.md)。
+- **逻辑解耦**：`weather_sources.py` 负责数据获取与解析；`bot_listener.py` 负责分析与渲染。
+- **城市配置**：`city_risk_profiles.py` 包含所有 METAR 机场映射和风险评估。
+- **多模型共识**：5 个独立 NWP 模型（ECMWF、GFS、ICON、GEM、JMA）提供稳健的共识评分。
+- **集合预报集成**：51 成员集合预报提供 P10/P90 不确定性区间和偏差检测。
+- **机场坐标对齐**：所有 NWP 查询均使用 METAR 机场坐标，而非市中心。
 
 ---
 
 ## 🎯 博弈策略提示
 
+<<<<<<< HEAD
 1. **检查模型共识**：查看 Open-Meteo 和 Meteoblue (MB) 是否达成共识。
 2. **关注峰值窗口**：在预测的峰值时段多次使用 `/city` 刷新。
 3. **数据权重优先级**：结算以 **METAR** 为准，趋势预测以 **MB** 为准（仅限伦敦）。
 4. **地理风险评估**：重点关注提示中的“偏差会显著放大”警告（如安卡拉、伦敦）。
+=======
+1. **看模型共识**：🎯/⚖️/⚠️ 评级让你一眼判断预报是否可靠。高共识 + 市场低定价 = 套利机会。
+2. **用入场信号**：等 ⏰ **理想** 或 **较好** 时机再下注。不确定性高时绝不提前入场。
+3. **关注集合散度**：90% 区间越窄（< 2°），模型置信越高 — 这才是 edge 所在。
+4. **紧盯峰值窗口**：在预测的峰值时段频繁使用 `/city` 刷新。
+5. **结算优先级**：结算永远以 **METAR** 数据为准，通过 Wunderground 四舍五入到整数。
+6. **地理风险**：重点关注高危城市（如首尔、芝加哥）的偏差警告。
+7. **太阳辐射线索**：如果机器人报告"暖平流驱动" 🌙，说明温度由暖空气推高 — 这种模式经常打破模型预测。
+8. **风向冲突**：METAR 和 MGM 风向相反时，温度波动风险增大。
+
+---
+
+_最后更新: 2026-02-22_
+>>>>>>> e575440acfd8b5f1e8c30e83dfcb972d26175729