QWeather China Skill

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

目标

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

触发条件

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

功能特点

✅ 核心功能

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

✅ 数据优势

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

✅ 用户体验

智能建议: 基于天气的穿衣、出行建议
多城市支持: 支持全国主要城市
缓存优化: 减少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 失败时：返回明确错误，并提示检查环境变量：
- QWEATHER_API_HOST - API 主机地址
- QWEATHER_PROJECT_ID - 项目ID (sub)
- QWEATHER_CREDENTIALS_ID - 凭据ID (kid)
- QWEATHER_PRIVATE_KEY_PATH - 私钥文件路径（建议使用 ~/.config/qweather/private.pem）
默认地点：使用 QWEATHER_DEFAULT_LOCATION 设置默认查询地点
安全注意：私钥文件应存放在独立目录（如 ~/.config/qweather/），并设置 600 权限

跨平台兼容性

✅ 完全支持的操作系统

Windows (7/8/10/11, Server 2012+)
Linux (Ubuntu, Debian, CentOS, Fedora, etc.)
macOS (10.15+)

✅ 编码自动处理

Windows控制台：自动处理GBK编码，将Unicode表情转换为文本描述
Linux/macOS终端：原生支持UTF-8，完整显示Unicode字符
智能检测：运行时自动检测系统编码并适配

✅ 新增工具模块

encoding_utils.py：编码处理核心模块
safe_print()函数：替代标准print，自动处理编码
系统检测：自动识别平台和编码设置

✅ 向后兼容

完全兼容v1.1.0的所有功能
现有配置无需修改
API接口保持不变

配置要求

必需配置

和风天气API认证（通过环境变量或 config.json 配置）
- QWEATHER_API_HOST: API 主机地址（如 p54up4xhmm.re.qweatherapi.com）
- QWEATHER_PROJECT_ID: 项目ID (sub)
- QWEATHER_CREDENTIALS_ID: 凭据ID (kid)
- QWEATHER_PRIVATE_KEY_PATH: 私钥文件路径（如 ~/.config/qweather/private.pem）

私钥文件准备

# 创建配置目录
mkdir -p ~/.config/qweather

# 将和风天气私钥复制到独立位置
cp /path/to/your/qweather-private.pem ~/.config/qweather/private.pem
chmod 600 ~/.config/qweather/private.pem

Python依赖（安装时自动处理）
- pyjwt>=2.0.0
- cryptography>=3.0
- requests>=2.25

可选配置

QWEATHER_DEFAULT_LOCATION: 默认查询城市
QWEATHER_CACHE_DIR: 缓存目录（默认 ~/.cache/qweather）

使用方法

基本查询

# 查询北京实时天气
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天预报...

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

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

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

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

支持的自然语言查询

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

支持的城市

北京 (beijing)
上海 (shanghai)
广州 (guangzhou)
深圳 (shenzhen)
杭州 (hangzhou)
成都 (chengdu)
武汉 (wuhan)
南京 (nanjing)
西安 (xian)
重庆 (chongqing)

或直接使用城市代码：101010100 (北京)

API端点

天气相关

/v7/weather/now - 实时天气
/v7/weather/3d - 3天预报
/v7/weather/7d - 7天预报
/v7/weather/24h - 24小时预报

生活指数

/v7/indices/1d - 今日生活指数
/v7/indices/3d - 3天生活指数

环境数据

/v7/air/now - 实时空气质量
/v7/air/5d - 5天空气质量预报

预警信息

/v7/warning/now - 当前预警
/v7/warning/list - 预警列表

城市代码

常用城市代码：

北京: 101010100
上海: 101020100
广州: 101280101
深圳: 101280601
杭州: 101210101

完整城市代码参考：https://dev.qweather.com/docs/resource/city/

错误处理

常见错误

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

降级策略

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

性能优化

缓存策略

实时数据: 10分钟缓存
预报数据: 1小时缓存
生活指数: 3小时缓存
空气质量: 30分钟缓存

请求优化

批量请求减少API调用
智能重试机制
连接池复用

更新日志

v1.2.2 (2026-04-13)

🔒 安全合规更新：
- 在 skill.yaml 中完整声明所有必需环境变量及其用途
- 在 skill.yaml 中详细声明文件系统权限和网络端点
- 在 config.json 中将敏感值改为占位符格式 (YOUR_*)
- 添加安全说明和风险评估
- 添加安装前注意事项
📋 元数据修复：解决 ClawHub 安全扫描中的元数据不匹配问题

v1.2.1 (2026-04-13)

🔧 修复发布问题：解决 ClawHub 发布中的文件路径问题

v1.2.0 (2026-04-12)

🔒 安全修复：私钥路径改为独立目录（~/.config/qweather/），不再读取 OpenClaw 代理私钥
✨ 环境变量支持：新增 QWEATHER_PROJECT_ID, QWEATHER_CREDENTIALS_ID 等环境变量
📦 ClawHub 兼容：新增 skill.yaml 文件，支持通过 ClawHub 安装
📝 配置简化：支持 ~ 路径自动展开，跨平台配置更简单
🔧 权限修复：明确声明文件系统权限，避免安全风险

v1.1.1 (2026-03-15)

跨平台兼容性：完全支持Windows、Linux、macOS系统
编码自动处理：智能处理不同系统的编码问题
安全输出函数：使用safe_print替代print，避免编码错误
表情符号兼容：自动将Unicode表情转换为文本描述

v1.1.0 (2026-03-15)

智能地点处理：自动识别城市名、经纬度、locationId
自然语言理解：支持"今天/明天/后天/未来N天"等表达
默认地点支持：支持QWEATHER_DEFAULT_LOCATION环境变量
优化触发条件：明确的天气相关关键词触发
改进错误处理：API失败时返回明确错误提示
简洁工作流：获取地点 → 判断查询类型 → 调用对应API

v1.0.0 (2026-03-13)

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

贡献指南

Fork本仓库
创建功能分支
提交更改
创建Pull Request

许可证

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

技术支持

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