国内天气预报 - 和风天气(QWeather)驱动

基于中国气象局数据的完整天气服务Skill，提供准确、本地化的天气信息。

目标

给用户提供可靠的实时天气与预报（不依赖通用 web_search）。 自动处理地点输入（城市名/经纬度/locationId）。 支持"今天/明天/后天/未来N天"等表达。

触发条件

用户提到：天气、气温、下雨、降温、风、湿度、预报、今天/明天/后天、未来几天。 一旦判定是天气问题，优先本 skill。

功能特点

✅ 核心功能

1. 实时天气 - 当前温度、体感温度、湿度、风速、降水等
2. 天气预报 - 3天/7天详细预报，包含白天夜间天气
3. 生活指数 - 穿衣、洗车、运动、紫外线等生活建议
4. 空气质量 - 实时AQI、污染物浓度
5. 天气预警 - 官方天气预警信息

✅ 数据优势

• 数据源: 中国气象局官方数据
• 准确性: 针对中国气候特点优化
• 本地化: 中文天气描述，符合中国用户习惯
• 完整性: 日出日落、月相、能见度等全方位信息

✅ 用户体验

• 智能建议: 基于天气的穿衣、出行建议
• 多城市支持: 支持全国主要城市
• 缓存优化: 减少API调用，提高响应速度
• 错误处理: 完善的错误处理和降级机制
• 智能地点处理: 自动识别城市名、经纬度、locationId
• 自然语言理解: 支持"今天/明天/后天/未来N天"等表达

工作流

1. 获取地点

• 若用户提供地点：调用 qweather_location_lookup({location})
• 若未提供地点：
  • 若 env 存在 QWEATHER_DEFAULT_LOCATION：使用默认地点，并明确说明"按默认地点查询"
  • 否则追问用户城市/地点

2. 判断查询类型

• "现在/当前/实时"：调用 weather_now({location})
• "今天/明天/后天/未来N天"：调用 weather_forecast({location, days})
  • 建议 days 映射：
    • 今天：days=1
    • 明天：days=2（输出前2天，重点标明第2天）
    • 后天：days=3（重点标明第3天）
    • "未来几天"：默认 days=3；用户说 N 天则用 N（上限 15）

3. 输出格式

• 地点：解析后的 name
• 实时：天气现象、气温/体感、湿度、风向风力、观测时间
• 预报：每天最高/最低、白天/夜间天气、降水（如有）、风力

约束

• 不要使用 web_search 代替天气数据源。
• API 失败时：返回明确错误，并提示检查 env：
  • QWEATHER_API_HOST
  • QWEATHER_PROJECT_ID
  • QWEATHER_CREDENTIALS_ID
  • QWEATHER_PRIVATE_KEY_PATH
• 默认地点：使用 QWEATHER_DEFAULT_LOCATION 设置默认查询地点

配置要求

必需配置

1. 和风天气API认证

   • 项目ID (sub): YOUR_PROJECT_ID_HERE
   • 凭据ID (kid): YOUR_CREDENTIALS_ID_HERE
   • API Host: YOUR_API_HOST_HERE.re.qweatherapi.com
   • 私钥文件: PATH_TO_YOUR_PRIVATE_KEY.pem

2. Python依赖

   • pyjwt>=2.0.0
   • cryptography>=3.0
   • requests>=2.25

使用方法

基本查询

# 查询北京实时天气
python qweather.py now --city beijing

# 查询3天预报
python qweather.py forecast --city beijing --days 3

# 查询生活指数
python qweather.py indices --city beijing

# 查询空气质量
python qweather.py air --city shanghai

# 完整天气报告
python qweather.py full --city guangzhou

OpenClaw集成

在OpenClaw中直接使用自然语言查询：

用户: 北京天气怎么样？
助手: 🌤️ 北京当前天气...

用户: 上海未来3天预报
助手: 📅 上海未来3天预报...

用户: 广州生活指数
助手: 📊 广州今日生活指数...

用户: 杭州空气质量
助手: 🌫️ 杭州空气质量...

用户: 深圳需要带伞吗？
助手: 🌂 深圳建议带雨伞...

用户: 成都穿什么？
助手: 👕 成都穿衣建议...

支持的自然语言查询

1. [城市]天气 - 查询实时天气
2. [城市]温度 - 查询当前温度
3. [城市]今天/明天/后天天气 - 查询特定日期
4. [城市]预报 - 查询3天预报
5. [城市]未来N天预报 - 查询N天预报
6. [城市]生活指数 - 查询生活指数
7. [城市]空气质量 - 查询空气质量
8. [城市]需要带伞吗 - 雨伞建议
9. [城市]穿什么 - 穿衣建议
10. 天气帮助 - 显示帮助信息

错误处理

常见错误

• 400: 请求参数错误
• 401: 认证失败
• 403: 权限不足
• 404: 城市不存在
• 429: 请求频率超限
• 500: 服务器错误

降级策略

1. 缓存上次成功的数据
2. 使用备用数据源（Open-Meteo）
3. 返回友好的错误提示

更新日志

v1.2.0 (2026-03-16)

• 软件名称: 改为"国内天气预报 - 和风天气(QWeather)驱动"
• 作者: 改为 uni-huang
• 隐私安全: 移除所有敏感API信息
• 编码修复: 统一为UTF-8 without BOM
• 合规性: 符合ClawHub上传规范

v1.1.1 (2026-03-15)

• 跨平台兼容性: 完全支持Windows、Linux、macOS系统
• 编码自动处理: 智能处理不同系统的编码问题
• 安全输出函数: 使用safe_print替代print，避免编码错误

v1.0.0 (2026-03-13)

• 初始版本发布
• 支持实时天气和3天预报
• 基础的生活指数查询
• JWT认证集成

许可证

基于和风天气API服务条款，仅供个人和非商业使用。

技术支持

• 和风天气文档: https://dev.qweather.com/docs/
• 问题反馈: 通过GitHub Issues
• 紧急支持: 联系和风天气客服