苏州天气（Suzhou Weather）
针对江苏省苏州市（含全部区县）的天气查询技能，一次提供 实时、预报、历史 三种能力。
> v1.1.0 更新：实时/预报接入 和风天气（QWeather，CMA 授权） 与 腾讯天气（CMA 数据） 双数据源，相比 v1.0.0 的 Open-Meteo，中国城市数据更权威、更精确。历史能力不变。
触发场景
当用户提出以下类型的问题时使用本技能：
- 实时天气：「苏州现在多少度？」「今天苏州天气怎么样？」
- 天气预报：「苏州明天会下雨吗？」「苏州未来一周天气」
- 历史天气：「苏州去年今天多少度？」「查一下苏州 2023 年 7 月的历史天气」「苏州 6 月平均气温」
能力概览
| 命令 | 说明 | 数据源（按优先级自动切换） |
|---|---|---|
now |
苏州实时天气（温度、体感、风速、湿度、天气代码） | 和风天气 → 腾讯天气 → Open-Meteo |
forecast [days] |
未来 N 天预报（默认 7 天，最高/最低温、降水、风速、AQI） | 和风天气 → 腾讯天气 → Open-Meteo |
history <date> |
指定日期（YYYY-MM-DD）或指定年月的历史天气 | 聚合数据（配 Key）→ Open-Meteo Archive |
> 实时/预报数据源说明：
> 1. 和风天气（QWeather）：配置 QWEATHER_API_KEY 后启用，数据源自 CMA 授权，支持全部区县（经纬度查询），最权威；
> 2. 腾讯天气（CMA）：无需 Key，数据为 CMA 官方口径，支持苏州市级（市区及六区）；
> 3. Open-Meteo：兜底，全球免费。
>
> 历史能力说明：默认使用 Open-Meteo Archive（ERA5 再分析，1940 年至今，免费无 Key）。若配置了 JUHE_HISTORY_KEY，历史查询将切换为聚合数据（CMA 系国内历史气象库，2011 年至今，2000+ 城市），对中国城市更权威。
使用方法
脚本仅使用 Python 标准库，无需 pip 安装任何依赖。
# 实时天气
python3 scripts/suzhou_weather.py now
# 未来 3 天预报
python3 scripts/suzhou_weather.py forecast --days 3
# 未来 7 天预报（默认）
python3 scripts/suzhou_weather.py forecast
# 查询指定日期历史天气（2023-07-01）
python3 scripts/suzhou_weather.py history --date 2023-07-01
# 查询某月历史天气汇总（2023 年 7 月，返回日均温、最高/最低、降水总量）
python3 scripts/suzhou_weather.py history --month 2023-07
# 指定区县（默认苏州市区）
python3 scripts/suzhou_weather.py now --district 昆山
python3 scripts/suzhou_weather.py history --date 2023-07-01 --district 张家港
支持的区县
市区（默认）、姑苏、虎丘、吴中、相城、吴江、园区（工业园区）、昆山、张家港、常熟、太仓。
> 注：和风天气（配 Key）与 Open-Meteo 支持全部区县；腾讯天气（无 Key）仅支持苏州市级，区县查询会自动降级到 Open-Meteo。
配置（可选）
默认零配置即可用（实时/预报走腾讯天气 CMA，历史走 Open-Meteo）。以下环境变量为可选增强：
| 环境变量 | 作用 | 获取方式 |
|---|---|---|
QWEATHER_API_KEY |
实时/预报升级为和风天气（CMA 授权，支持全部区县） | 和风天气开放平台 id.qweather.com 免费注册创建项目，获取 API Key |
JUHE_HISTORY_KEY |
历史天气切换为聚合数据（国内 CMA 系，更权威） | 聚合数据官网 juhe.cn 免费注册申请「历史天气查询」API |
SUZHOU_WEATHER_DISTRICT |
默认区县（默认 市区） |
无需申请 |
# Linux / macOS
export QWEATHER_API_KEY="your_qweather_key"
export JUHE_HISTORY_KEY="your_appkey_here"
# Windows PowerShell
$env:QWEATHER_API_KEY="your_qweather_key"
$env:JUHE_HISTORY_KEY="your_appkey_here"
返回字段说明
- 实时（和风）：temperature / feels_like / humidity / precipitation / weather / wind_direction / wind_power / observation_time
- 实时（腾讯）：temperature / humidity / precipitation / weather / wind_direction / wind_power / pressure / observation_time
- 实时（Open-Meteo）：temperature / feels_like / wind_speed / wind_direction / humidity / precipitation / weather_code / observation_time
- 预报：每日 date / weather / temp_max / temp_min / precipitation_sum / wind_speed_max（腾讯源另有 wind_direction / aqi / aqi_name）
- 历史（Open-Meteo）：date / weather / temp_max / temp_min / precipitation_sum / wind_speed_max；支持按年月聚合输出日均温与极值
- 历史（聚合数据，配置 Key 后）：cityname / date / weather / temphigh / templow / humidity / pressure / windspeed / windpower / aqi / sunrise / sunset
常见问题
- 没有 API Key 能用吗？ 能。实时/预报自动走腾讯天气（CMA，无需 Key），历史走 Open-Meteo，完全免费。
- 如何获得最权威的数据？ 配置
QWEATHER_API_KEY（和风，CMA 授权，支持全部区县）+JUHE_HISTORY_KEY（聚合数据，历史 CMA 系）。 - 历史天气最远能查多久？ 默认 Open-Meteo Archive 可回溯至 1940 年；配置聚合数据 Key 后可查 2011 年至今的国内 CMA 系记录。
- 查询失败怎么办？ 数据源自动逐级降级（和风 → 腾讯 → Open-Meteo；聚合 → Open-Meteo）；检查网络连接与 Key 有效性即可。
