From d533bd5b21c9a6d28dd23fdaa320bd762cdfdf58 Mon Sep 17 00:00:00 2001 From: AmandaloveYang <2569718930@qq.com> Date: Wed, 18 Feb 2026 09:49:40 +0800 Subject: [PATCH] docs: comprehensive update of all documentation - Paris, wind analysis, VPS deploy, supported cities table --- MARKET_DISCOVERY.md | 3 + README.md | 148 +++++++++++++++++++++++++++++++------------- README_ZH.md | 103 ++++++++++++++++++------------ 3 files changed, 173 insertions(+), 81 deletions(-) diff --git a/MARKET_DISCOVERY.md b/MARKET_DISCOVERY.md index 06f46ff4..a7003168 100644 --- a/MARKET_DISCOVERY.md +++ b/MARKET_DISCOVERY.md @@ -1,5 +1,8 @@ # Polymarket Weather Market Discovery Technical Documentation +> ⚠️ **Current Status: Suspended** +> The automated market discovery and monitoring engine described here has been commented out in `run.py`. The system currently operates in "passive query mode" — weather analysis is only triggered by the `/city` command. + This document explains the technical implementation of how PolyWeather identifies and tracks weather markets on Polymarket. ## 1. Data Sources diff --git a/README.md b/README.md index d627a505..e050cd48 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 🌡️ PolyWeather: Real-time Weather Query & Analysis Bot -An intelligent weather information bot designed to provide ultra-fast, live meteorological data, high-fidelity forecasts, and smart trend analysis. Built for speed and accuracy, it bypasses network caching to deliver the most up-to-date reports from global weather stations. +An intelligent weather bot for prediction markets and professional weather betting. Fetches ultra-fresh data directly from global weather stations, bypassing CDN caches, and provides automated trend analysis in plain language. ## 🚀 Quick Start @@ -8,19 +8,53 @@ An intelligent weather information bot designed to provide ultra-fast, live mete - **Python 3.11+** - Dependencies: `pip install -r requirements.txt` -- **Environment**: Configure `METEOBLUE_API_KEY` in `.env` to enable high-precision London forecasts. +- **Environment Variables**: Set `TELEGRAM_BOT_TOKEN` in `.env` (required). Optionally set `METEOBLUE_API_KEY` for London high-precision forecasts. -### Running Locally (Windows/Linux) +### VPS Deployment (Recommended) + +**First-time setup:** ```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 # Edit .env with your Token and API Keys ``` -_Note: The system is currently in **Weather Query Mode**. Legacy active market monitoring and automated trading modules are suspended._ +**Create one-click update script (run once):** + +```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 "✅ Updated and restarted!" +EOF +chmod +x ~/update.sh +``` + +**Daily updates (after each code push):** + +```bash +~/update.sh +``` + +> One command: pull latest code → kill old process → start new process. No branch conflict handling needed. + +### Local Development (Windows) + +```bash +py -3.11 run.py +``` + +> Local machine is for editing code and Git push only. IDE import errors are expected (dependencies not installed locally) and do not affect VPS operation. + +_Note: The system is currently in **Weather Query Mode**. Legacy market monitoring and automated trading modules are suspended._ --- @@ -32,50 +66,75 @@ _Note: The system is currently in **Weather Query Mode**. Legacy active market m | `/id` | **Get Chat ID** | Retrieve your current Telegram Chat ID | | `/help` | **Help** | Display all available commands | +### Supported Cities + +| City | Aliases | METAR Station | Extra Sources | +|:---|:---|:---|:---| +| 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) | — | + +### Example + +``` +/city 巴黎 +/city london +/city par +``` + --- ## ✨ Key Features -### 1. 🏛️ Multi-Source Data Fusion (High-Fidelity) - -The bot aggregates data from multiple authoritative sources, layered by reliability: +### 1. 🏛️ Multi-Source Data Fusion | Source | Role | Coverage | Strength | | :----------------- | :---------------------- | :-------------- | :--------------------------------------------------------------------------------- | -| **Open-Meteo** | Base Forecast | Global | Provides detailed 72-hour temperature curves for all cities. | -| **Meteoblue (MB)** | **Precision Consensus** | London Only | **Traders' choice**. Aggregates multiple models; excellent for microclimates. | -| **METAR** | **Settlement Standard** | Global Airports | The absolute truth for Polymarket settlement; real-time station data. | -| **NWS** | Official (US) | US Only | High-fidelity forecasts for US cities, critical for extreme weather events. | -| **MGM** | Official (Turkey) | Ankara | Direct access to Turkish State Meteorological Service for local official accuracy. | +| **Open-Meteo** | Base Forecast | Global | 72-hour hourly temperature curves, sunrise/sunset times | +| **Meteoblue (MB)** | **Precision Consensus** | London Only | Multi-model aggregation; excellent for microclimates | +| **METAR** | **Settlement Standard** | Global Airports | Polymarket settlement source; real-time airport observations | +| **NWS** | Official (US) | US Only | US National Weather Service high-fidelity forecasts | +| **MGM** | Official (Turkey) | Ankara Only | Turkish State Met Service: pressure, cloud cover, feels-like, 24h rainfall | -### 2. ⚡ Ultra-Fresh Data (Cache-Busting) +### 2. ⚡ Ultra-Fresh Data (Zero-Cache) -To counter second-by-second variations in weather betting, we implemented **Zero-Cache Technology**: +- **Dynamic Timestamps**: Every API request includes a unique token to force servers to bypass CDN caches. +- **MGM Real-time Sync**: Specialized header camouflaging and timezone correction for Turkish API. -- **Micro-timestamp Tokens**: Every request includes a dynamic token to force servers to bypass CDN caches. -- **MGM Real-time Sync**: Specialized header camouflaging to bypass local Turkish API anti-crawling for Ankara. +### 3. 🧠 Smart Trend Analysis (Plain Language) -### 3. ⏱️ Automated Trend Analysis +The bot generates human-readable insights automatically: -The bot doesn't just fetch data; it interprets it: +- **🚨 Forecast Breakthrough Alerts**: Detects when METAR observed max exceeds all forecast highs. +- **⏱️ Peak Window Prediction**: Identifies the exact hours when today's high is expected. +- **🌬️ Wind Direction Cross-Validation**: Compares METAR and MGM wind data; alerts on conflicts (>90° difference). +- **☁️ Cloud Impact Analysis**: Evaluates cloud cover's effect on warming potential. +- **📉 Pressure Analysis**: Low pressure indicates warm/moist air passage. +- **🌧️ Rain Detection**: Cross-validates METAR weather codes with actual rainfall data to avoid false positives. +- **📊 Max Temperature Time Tracking**: Shows exactly when the daily high was recorded (e.g., `最高: 12°C @14:20`). -- **Peak Window Prediction**: Automatically identifies the timeframe when today's record is most likely to be hit. -- **Risk Profiling**: Assigns risk levels based on geographic traits (e.g., Ankara high-altitude swings, London coastal microclimates). -- **Source Attribution**: Every data point is clearly labeled ([MGM], [METAR], [MB]) to help you weigh the data. +### 4. 📊 Risk Profiling -### 4. 📊 Smart Max-Temp Tracking +Every city has a data bias risk profile based on airport-to-city-center distance: -Optimized for Polymarket settlement logic: - -- **Local Day Filtering**: Uses city UTC offsets to strictly count observations after 00:00 local time. -- **Multi-dimension Monitoring**: Includes "Feels Like" temperatures and 24h precipitation to assist in nuanced trade decisions. +- 🔴 **High Risk**: Seoul (48.8km), Chicago (25.3km) — large bias expected +- 🟡 **Medium Risk**: Ankara (24.5km), Paris (25.2km), Dallas, Buenos Aires — systematic bias +- 🟢 **Low Risk**: London (12.7km), Wellington (5.1km) — reliable data --- ## 🏗️ System Architecture -PolyWeather uses a **Lightweight, Plugin-based** architecture for millisecond responses. - ```mermaid graph TD User[/Telegram User/] --> Bot[bot_listener.py] @@ -83,25 +142,30 @@ graph TD subgraph "Data Engine" Collector --> OM[Open-Meteo API] - Collector --> MB[Meteoblue Weather API] - Collector --> NOAA[METAR Data Center] + Collector --> MB[Meteoblue API] + Collector --> NOAA[METAR / NOAA] Collector --> MGM[Turkish MGM API] Collector --> NWS[US NWS API] end Collector --> Processing[Smart Analysis & Formatting] Processing --> Bot - Bot --> Reponse[/Compact Betting Snapshot/] + Bot --> Response[/Compact Betting Snapshot/] ``` -- **Logic Decoupling**: `weather_sources.py` handles parsing; `bot_listener.py` handles rendering. -- **Legacy Modules**: `main.py` contains the old automated trading engine. Focus has shifted to "assisted manual decision-making." +- **Logic Decoupling**: `weather_sources.py` handles data fetching & parsing; `bot_listener.py` handles analysis & rendering. +- **City Config**: `city_risk_profiles.py` contains all METAR station mappings and risk assessments. --- ## 🎯 Betting Strategy Tips -1. **Check Consensus**: Compare Open-Meteo and Meteoblue (MB). Consensus usually implies higher probability. -2. **Watch the Peak**: Use `/city` frequently during predicted peak windows to catch momentum. -3. **Weighting Hierarchy**: Settlement is **METAR**; high-accuracy trend is **MB** (London); Official (NWS/MGM) is the "anchor." -4. **Geographic Risk**: Pay close attention to cities where "Bias will significantly amplify." +1. **Check Consensus**: Compare Open-Meteo, Meteoblue (MB), and NWS/MGM forecasts. +2. **Watch the Peak Window**: Use `/city` frequently during predicted peak hours. +3. **Settlement Priority**: Settlement is always based on **METAR** data. +4. **Geographic Risk**: Pay attention to bias warnings, especially for high-risk cities. +5. **Wind Conflicts**: When METAR and MGM show opposite wind directions, expect temperature volatility. + +--- + +_Last updated: 2026-02-18_ diff --git a/README_ZH.md b/README_ZH.md index c7bda6ef..90d1e3af 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -1,6 +1,6 @@ # 🌡️ PolyWeather: 实时天气查询与分析机器人 -一个智能天气信息机器人，专为提供超快、实时的气象数据、高保真预报和智能趋势分析而设计。通过绕过网络缓存，直接从全球气象站获取最新数据。 +专为预测市场和天气博弈设计的智能天气机器人。通过绕过 CDN 缓存直接从全球气象站获取最新数据，并提供通俗易懂的自动趋势分析。 ## 🚀 快速开始 @@ -8,7 +8,7 @@ - **Python 3.11+** - 依赖安装: `pip install -r requirements.txt` -- **环境变量**: 需在 `.env` 中配置 `METEOBLUE_API_KEY` 以激活伦敦高精度预报。 +- **环境变量**: 在 `.env` 中设置 `TELEGRAM_BOT_TOKEN`（必需）。可选设置 `METEOBLUE_API_KEY` 以激活伦敦高精度预报。 ### VPS 部署 (推荐) @@ -52,7 +52,7 @@ chmod +x ~/update.sh py -3.11 run.py ``` -> 本地笔记本**不需要安装 Python**，只用来编辑代码和 Git 推送。IDE 的 import 报错是因为本地没装依赖，不影响 VPS 运行。 +> 本地笔记本**不需要安装依赖**，只用来编辑代码和 Git 推送。IDE 的 import 报错是因为本地没装依赖，不影响 VPS 运行。 _注意：系统当前处于 **天气查询模式**。主动市场监控和自动交易模块已暂停。_ @@ -66,56 +66,76 @@ _注意：系统当前处于 **天气查询模式**。主动市场监控和自 | `/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. 🏛️ 多源数据融合 -机器人聚合了全球最权威的几个数据源，并按权重进行分层： +| 数据源 | 数据角色 | 覆盖范围 | 优势 | +| :----------------- | :------------- | :--------- | :--------------------------------------------------- | +| **Open-Meteo** | 基础预测 | 全球 | 72 小时逐小时温度曲线、日出日落时间 | +| **Meteoblue (MB)** | **高精度共识** | 仅限伦敦 | 聚合多家模型，对微气候处理极佳 | +| **METAR** | **结算标准** | 全球机场 | Polymarket 结算参考的绝对真理，实时机场观测 | +| **NWS** | 官方预测(美) | 仅限美国 | 美国国家气象局高精度预报 | +| **MGM** | 官方预测(土) | 仅限安卡拉 | 土耳其气象局：气压、云量、体感温度、24h 降水 | -| 数据源 | 数据角色 | 覆盖范围 | 优势 | -| :----------------- | :------------- | :--------- | :----------------------------------------------- | -| **Open-Meteo** | 基础预测 | 全球 | 提供所有城市的 72 小时精细化温度曲线 | -| **Meteoblue (MB)** | **高精度共识** | 仅限伦敦 | **交易员首选**。聚合多家模型，对微气候处理极佳 | -| **METAR** | **结算标准** | 全球机场 | Polymarket 结算参考的绝对真理，实时机场观测 | -| **NWS** | 官方预测(美) | 仅限美国 | 美国国家气象局，对美国城市的极端天气预判准确 | -| **MGM** | 官方预测(土) | 仅限安卡拉 | 土耳其气象局，提供安卡拉 Esenboğa 机场的官方数据 | +### 2. ⚡ 超新鲜数据 (零缓存) -### 2. ⚡ 超新鲜数据 (Cache-Busting) - -为了应对气象博弈中秒级的变化，我们实现了 **0 缓存技术**： - -- **微秒级令牌**：每个 API 请求都附带动态时间戳，强制气象服务器绕过 CDN 缓存返回最新值。 +- **动态时间戳**：每个 API 请求都附带唯一令牌，强制服务器绕过 CDN 缓存。 - **MGM 实时同步**：针对土耳其 MGM API 做了专门的 Header 伪装和时区校正。 -### 3. ⏱️ 自动态势分析 +### 3. 🧠 智能趋势分析（通俗语言） -机器人不仅仅搬运数据，它还会进行逻辑加工： +机器人自动生成人类可读的分析洞察： -- **峰值时刻预测**：自动计算今天气温最高点出现的概率窗口（如：14:00 - 15:00）。 -- **风险等级 (Risk-Profile)**：根据地理特征（如安卡拉的高原温差、伦敦的近海微气候）自动分配风险等级。 -- **数据溯源**：报表明确标注每个数字的来源（[MGM], [METAR], [MB]）。 +- **🚨 预报击穿预警**：当 METAR 实测最高温超过所有预报时自动警报。 +- **⏱️ 峰值时段预测**：精确预测当日最高温出现的时间窗口。 +- **🌬️ 风向交叉验证**：同时对比 METAR 和 MGM 风向数据，差异超 90° 自动告警。 +- **🍃 风速分析**：标注风速并结合风向判断对温度的影响。 +- **☁️ 云层遮挡分析**：评估云量对升温潜力的影响（晴天/多云/阴天）。 +- **📉 气压分析**：低气压意味着暖湿气流过境，有利升温。 +- **🌧️ 降雨检测**：交叉验证 METAR 天气代码和实际降水量，避免误报。 +- **📊 最高温时间追踪**：精确显示每日最高温出现的时间（如 `最高: 12°C @14:20`）。 -### 4. 📊 智能最高温追踪 +### 4. 📊 风险等级 -针对 Polymarket 的结算逻辑进行优化： +每个城市都有基于机场-市区距离的数据偏差风险档案： -- **当地日历日过滤**：基于城市 UTC 偏移，严格统计当地时间 00:00 之后的实测最高温。 -- **多维度监测**：集成体感温度 (`feels_like`) 和 24h 累计降雨量，辅助多维度判断。 +- 🔴 **高危**：首尔 (48.8km)、芝加哥 (25.3km) — 偏差大 +- 🟡 **中危**：安卡拉 (24.5km)、巴黎 (25.2km)、达拉斯、布宜诺斯艾利斯 — 有系统偏差 +- 🟢 **低危**：伦敦 (12.7km)、惠灵顿 (5.1km) — 数据靠谱 --- ## 🏗️ 系统架构 -本项目采用 **“轻量化、插件式”** 架构，旨在实现毫秒级响应。 - ```mermaid graph TD User[/Telegram User/] --> Bot[bot_listener.py] @@ -123,25 +143,30 @@ graph TD subgraph "Data Engine" Collector --> OM[Open-Meteo API] - Collector --> MB[Meteoblue Weather API] - Collector --> NOAA[METAR Data Center] + Collector --> MB[Meteoblue API] + Collector --> NOAA[METAR / NOAA] Collector --> MGM[Turkish MGM API] Collector --> NWS[US NWS API] end 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 机场映射和风险评估。 --- ## 🎯 博弈策略提示 -1. **检查模型共识**：查看 Open-Meteo 和 Meteoblue (MB) 是否达成共识。 -2. **关注峰值窗口**：在预测的峰值时段多次使用 `/city` 刷新。 -3. **数据权重优先级**：结算以 **METAR** 为准，趋势预测以 **MB** 为准（仅限伦敦）。 -4. **地理风险评估**：重点关注提示中的“偏差会显著放大”警告（如安卡拉、伦敦）。 +1. **检查模型共识**：对比 Open-Meteo、Meteoblue (MB) 和 NWS/MGM 的预报。 +2. **关注峰值窗口**：在预测的峰值时段频繁使用 `/city` 刷新。 +3. **结算优先级**：结算永远以 **METAR** 数据为准。 +4. **地理风险**：重点关注高危城市的偏差警告。 +5. **风向冲突**：METAR 和 MGM 风向相反时，温度波动风险增大。 + +--- + +_最后更新: 2026-02-18_