weather-skill

Weather Skill

使用两个免费 API 提供任意地点的当前天气和预报：

• Nominatim（OpenStreetMap），用于地点地理编码 → scripts/geocode.py
• Open-Meteo，用于获取天气数据 → scripts/fetch_weather.py

---

工作流

1. 理解用户的请求。 提取地点、时间范围，以及用户是否计划出行。请参阅下方示例。
2. 对地点进行地理编码，运行 scripts/geocode.py "<location>"。该脚本会返回包含 display_name、lat、lon 和 ambiguous 标志的 JSON。如果地点不明确，请询问用户以确认。
3. 获取天气，运行 scripts/fetch_weather.py，并传入纬度/经度及适当的标志。请参阅下方脚本用法。
4. 向用户作出回复，提供清晰的摘要。请参阅下方示例输出。
5. 如果检测到出行意图，还要读取 references/clothing_guide.md，并提供相关的穿衣建议。

---

脚本

地理编码：scripts/geocode.py

将地点字符串转换为坐标。

python scripts/geocode.py "Tokyo"
python scripts/geocode.py "King Abdullah Financial District, Riyadh"
python scripts/geocode.py "Times Square, New York"

返回 JSON：

{
  "display_name": "Tokyo, Japan",
  "lat": 35.6764,
  "lon": 139.6500,
  "importance": 0.82,
  "ambiguous": false
}

如果 ambiguous 为 true，则会包含 alternatives 列表——询问用户指的是哪一个地点。

天气：scripts/fetch_weather.py

获取指定坐标的天气数据。

# Current conditions only
python scripts/fetch_weather.py --lat 35.6764 --lon 139.65 --resolution current

# Hourly forecast (good for today, tomorrow, next 12 hours, specific day)
python scripts/fetch_weather.py --lat 35.6764 --lon 139.65 --resolution hourly

# Daily forecast (good for multi-day ranges, next week, etc.)
python scripts/fetch_weather.py --lat 35.6764 --lon 139.65 --resolution daily

# Custom timezone (default is "auto" which uses the location's timezone)
python scripts/fetch_weather.py --lat 35.6764 --lon 139.65 --resolution hourly --timezone Asia/Tokyo

# Include historical data when user asks about past weather
python scripts/fetch_weather.py --lat 35.6764 --lon 139.65 --resolution daily --past-days 7

根据分辨率不同，返回包含 meta、current、hourly 和/或 daily 部分的 JSON。

示例 JSON 响应（--resolution current）：

{
  "meta": {
    "lat": 35.6764,
    "lon": 139.65,
    "timezone": "Asia/Tokyo",
    "resolution": "current",
    "forecast_days": 16,
    "past_days": 0
  },
  "current": {
    "time": "2026-02-25T14:00",
    "temperature_c": 12.3,
    "apparent_temperature_c": 10.8,
    "weather_code": 1,
    "weather_description": "Mainly clear",
    "wind_speed_kmh": 14.2,
    "humidity_pct": 48,
    "precipitation_mm": 0.0
  },
  "hourly": null,
  "daily": null
}

该脚本始终请求 forecast_days=16（最大预报时长）。 仅在查询过去天气时使用 --past-days（0..92）。

---

如何解读用户请求

Agent 应解读用户的自然语言，确定以下三项：

1. 地点

从查询中提取地点名称。示例：

• “Jeddah 现在的天气怎么样？” → "Jeddah"
• “London 这个周末的天气预报” → "London"
• “我下周要去 Tokyo” → "Tokyo"
• “AlUla 星期五会有多大风？” → "AlUla"

如果没有提到地点，请询问用户。

2. 时间范围、分辨率和过去天气

用户说	分辨率	past_days	备注
“现在” / “当前” / 未指定时间	current（同时包含未来 24 小时的逐小时数据）	0	预报请求始终使用 16 天。
“今天” / “今晚” / “明天” / “明天早上”	hourly	0	使用逐小时数据回答具体时间段的问题。
“这个周末” / “星期五” / “未来 12 小时的逐小时天气”	hourly	0	在回复中筛选返回的时间序列。
“未来 3 天”	hourly	0	根据逐小时数据进行摘要。
“未来 7 天” / “下周” / “3 月的第一周”	daily	0	根据每日数据概述相关日期。
“3 月” / “4 月” / “05/01 到 06/30”	daily	0	如果超出预报时长上限，请明确说明限制。
“过去的天气” / “过去 3 天” / “昨天”	daily（较短时间段可用 hourly）	根据请求设置	如果用户提到“过去”但未指定天数，默认使用 7。

用户可能会使用各种格式指定日期（MM/DD、DD/MM、“May 1st”、“1 March”等）——请结合上下文进行解读，并据此筛选返回的时间线。除非另有说明或暗示，否则使用当前年份。

超过 3 天的范围使用 daily，较短的时间段使用 hourly，询问当前天气时使用 current（但仍要包含逐小时数据作为参考）。

默认情况（未指定时间）：当前天气状况 + 未来 24 小时的逐小时数据。

请记住： 预报固定为 16 天。查询过去天气时，使用 past_days（0..92）。

3. 出行意图

检测用户是否计划前往某处。留意以下关键词： 打包、穿、旅行、游览、前往、出发去、行程、度假、假期、出游、航班、我应该带上

如果检测到出行意图 → 还要提供穿衣建议（见下文）。

---

输出示例

示例 1：简单的当前天气

用户：“吉达现在天气怎么样？”

回复：

沙特阿拉伯吉达的天气

现在是晴空，气温为 28°C（体感温度为 30°C）。北风轻柔，风速为 12 km/h，湿度为 45%。预计没有降水。

未来几小时：

• 下午 3 点：29°C，晴空，降雨概率 0%
• 下午 4 点：28°C，局部多云，降雨概率 0%
• 下午 5 点：26°C，晴空，降雨概率 0% （依此类推……）

示例 2：周末天气预报

用户：“伦敦本周末的天气预报”

回复：

英国伦敦周末天气预报

**3 月 1 日，星期六：**最高气温 11°C，最低气温 5°C。预计有中雨（降水概率 70%，约 4mm）。风速最高可达 25 km/h。

**3 月 2 日，星期日：**最高气温 13°C，最低气温 6°C。局部多云，降雨概率为 20%。风力较小，风速为 15 km/h。

总体而言：周六有雨，周日转干爽。周六请带上雨伞。

示例 3：旅行规划与穿衣建议

用户：“我下周要去东京，应该带些什么衣服？”

回复：

日本东京 — 下周天气预报（3 月 3–9 日）

日期	最高气温	最低气温	天气状况	降雨概率	风速
周一	12°C	4°C	局部多云	10%	15 km/h
周二	10°C	3°C	小雨	65%	20 km/h
...	...	...	...	...	...

穿衣建议： 天气预计会寒冷（最低气温接近 3°C），且周中会有降雨。建议携带：

• 保暖衣物：抓绒衣或羊毛衫 + 保暖外套
• 周二、周三穿的防水外套和雨伞
• 防水包头鞋
• 早晚穿的围巾和薄手套

参见：clothing_guide.md — 章节：cold、rainy

示例 4：查询特定天气状况

用户：“阿尔乌拉星期五的风有多大？”

回复：

沙特阿拉伯阿尔乌拉周五风力预报 — 2 月 28 日

风速将在下午早些时候达到 35 km/h，到傍晚降至约 15 km/h。早晨风力较小，风速约为 10 km/h。

⚠️ 午间预计风力中等偏强——请固定好松散物品；如果要在户外活动，可以考虑穿防风衣。

---

警告

天气状况值得注意时，请添加警告：

• **酷热：**气温 ≥ 40°C
• **严寒：**气温 ≤ -10°C
• 强风：≥ 50 km/h
• **大雨：**降水量 ≥ 20mm

---

穿衣指南

检测到旅行意图时，请阅读 references/clothing_guide.md，并在回复中提供相关建议。

---

错误处理

• **未找到地点：**请用户提供更具体的信息（补充城市、国家）。
• **地点不明确：**列出可能的地点，并询问用户指的是哪一个。
• **API 故障 / 网络受阻：**脚本会返回 JSON 错误封装，而不是回溯信息：

  {
    "error": {
      "code": "NETWORK_UNAVAILABLE",
      "message": "Unable to reach remote weather service.",
      "details": "URLError: ...",
      "retryable": true,
      "hint": "Enable outbound network access or rerun with elevated permissions."
    }
  }
  

• 错误代码：
  • INVALID_INPUT：用户输入无效（past_days 无效、缺少地点、没有结果）。
  • NETWORK_UNAVAILABLE：与上游天气 API 的 DNS 解析、连接或请求超时问题。
  • UPSTREAM_API_ERROR：上游 HTTP/API 响应问题。
• 退出代码：
  • 0：成功。
  • 1：用法或输入验证失败。
  • 2：网络或上游 API 故障。
• **操作指南：**如果沙盒中网络受阻，请申请提升权限，或在可访问外网的环境中运行脚本。
• **超出天气预报范围：**告知用户预报范围上限为 16 天，并返回可用信息。
• **未指定时间：**默认提供当前时段及未来 24 小时的天气。