# Qweather China

> 基于中国气象局数据的完整天气服务，通过和风天气API提供实时天气、天气预报、生活指数、空气质量等全方位天气信息。专为中国用户优化，数据更准确，功能更全面。

- Skill: `dvcrn/qweather-china` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add dvcrn/qweather-china`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/qweather-china/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/qweather-china

---


# QWeather China Skill

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

## 功能特点

### ✅ 核心功能
1. **实时天气** - 实时温度、体感温度、风力风向、相对湿度、大气压强、降水量、能见度、露点温度、云量等
2. **天气预报** - 3天/7天/10天/15天/30天预报，包含白天夜间天气
3. **生活指数** - 穿衣、洗车、运动、紫外线、感冒、钓鱼、旅游等30+种生活指数
4. **空气质量** - 实时AQI、主要污染物浓度、空气质量预报
5. **天气预警** - 官方天气预警信息，包括台风、暴雨、暴雪等
6. **天文数据** - 日出日落、月升月落、月相、潮汐等
7. **格点天气** - 任意经纬度的精细化天气数据
8. **历史天气** - 过去30天的历史天气数据

### ✅ 数据优势
- **数据源**: 中国气象局官方数据 + 国际权威数据源
- **覆盖范围**: 中国3000+市县区 + 海外20万个城市
- **准确性**: 针对中国气候特点优化，数据实时更新
- **完整性**: 从实时天气到长期预报的全方位天气服务
- **权威性**: 和风天气是中国气象局战略合作伙伴

### ✅ 用户体验
- **智能建议**: 基于天气的穿衣、出行建议
- **多城市支持**: 支持全国主要城市
- **缓存优化**: 减少API调用，提高响应速度
- **错误处理**: 完善的错误处理和降级机制

## 配置要求

### 必需配置
1. **和风天气API认证**
   - 项目ID (sub): 从和风天气开发者平台获取
   - 凭据ID (kid): 从和风天气API密钥管理获取
   - API Host: 从和风天气开发控制台获取（设置 → 开发者信息）
   - 私钥文件: 下载的私钥文件路径

2. **Python依赖**
   - `pyjwt>=2.0.0`
   - `cryptography>=3.0`
   - `requests>=2.25`

### 配置方法
1. **通过ClawHub安装**：安装时会提示输入配置参数
2. **手动配置**：设置环境变量：
   ```bash
   export QWEATHER_SUB="your_project_id"
   export QWEATHER_KID="your_credential_id"
   export QWEATHER_API_HOST="your_api_host"
   export QWEATHER_PRIVATE_KEY_PATH="/path/to/private_key.pem"
   ```
3. 详细配置指南见 [CONFIGURATION.md](CONFIGURATION.md)

## 使用方法

### 基本查询
```bash
# 查询北京实时天气
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. `天气帮助` - 显示帮助信息

### 支持的城市
**覆盖全球范围**：
- **中国**: 3000+市县区，包括所有地级市、县级市、县、区
- **海外**: 20万个城市，覆盖全球主要城市

**常用城市示例**：
- 北京 (beijing) - 代码: `101010100`
- 上海 (shanghai) - 代码: `101020100`
- 广州 (guangzhou) - 代码: `101280101`
- 深圳 (shenzhen) - 代码: `101280601`
- 纽约 (newyork) - 代码: `USNY0996`
- 伦敦 (london) - 代码: `GBLO0483`
- 东京 (tokyo) - 代码: `JAXX0085`

**查询方式**：
1. 使用城市拼音（如 `beijing`）
2. 使用城市代码（如 `101010100`）
3. 使用经纬度坐标
4. 使用城市中文名称（如 `北京`）

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

## API端点（基于和风天气V7 API）

### 天气数据
- `/v7/weather/now` - 实时天气（3000+中国城市，20万海外城市）
- `/v7/weather/3d` - 3天预报
- `/v7/weather/7d` - 7天预报
- `/v7/weather/10d` - 10天预报
- `/v7/weather/15d` - 15天预报
- `/v7/weather/24h` - 逐小时预报
- `/v7/weather/30d` - 30天预报
- `/v7/weather/warning` - 天气预警

### 生活指数
- `/v7/indices/1d` - 今日生活指数（30+种指数）
- `/v7/indices/3d` - 3天生活指数

### 环境数据
- `/v7/air/now` - 实时空气质量
- `/v7/air/5d` - 5天空气质量预报

### 天文数据
- `/v7/astronomy/sun` - 日出日落
- `/v7/astronomy/moon` - 月升月落、月相

### 格点天气
- `/v7/grid-weather/now` - 格点实时天气
- `/v7/grid-weather/3d` - 格点3天预报
- `/v7/grid-weather/24h` - 格点逐小时预报

### 历史数据
- `/v7/historical/weather` - 历史天气（过去30天）

## 城市代码

常用城市代码：
- 北京: `101010100`
- 上海: `101020100`
- 广州: `101280101`
- 深圳: `101280601`
- 杭州: `101210101`

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

## 错误处理

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

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

## 性能优化

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

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

## 更新日志

详细更新日志请查看 [CHANGELOG.md](CHANGELOG.md)

### v1.0.0 (2026-03-14) - 发布版本
- 完整和风天气V7 API集成
- 全球城市覆盖（中国3000+市县区 + 海外20万个城市）
- 全方位天气服务（实时、预报、指数、空气质量、预警等）
- 环境变量配置，无硬编码敏感信息
- 详细的配置指南和安装向导

## 贡献指南

1. Fork本仓库
2. 创建功能分支
3. 提交更改
4. 创建Pull Request

## 许可证

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

## 技术支持

- 和风天气官方文档: https://dev.qweather.com/docs/
- API参考文档: https://dev.qweather.com/docs/api/
- 位置列表文档: https://dev.qweather.com/docs/resource/location-list/
- 常见问题: https://dev.qweather.com/help/
- 控制台支持: https://console.qweather.com/support
- 问题反馈: 通过GitHub Issues或ClawHub