---
name: weather-querys
description: 全国3000多个省市天气预报查询，包括实时气温、风级、湿度、空气质量、7天预报等。适用于"天气预报查询""天气查询""实时天气""7天天气预报""空气质量查询""PM2.5查询""城市天气"等请求。需专属 API Key，首次使用时引导用户前往产品页注册获取。
---

# 天气预报查询

## 功能简介

全国3000多个省市的天气预报查询，包括实时天气气温、最高最低温度、风级、风力、湿度、气压，穿衣、运动、洗车、感冒、空气污染扩散、紫外线等指数，7天天气、风力、最低最高温度、日出日落时间，未来24小时的时天气、气温，空气质量指数、PM2.5指数等信息。

**核心能力**：
- 查询全国3000多个省市的实时天气和7天预报
- 返回气温、湿度、风力、空气质量（AQI/PM2.5）等完整数据
- 支持按城市名、城市ID、经纬度、IP等多种方式查询

**适用范围**：本 Skill 只覆盖"全国天气预报"接口，不用于其他同类功能。

## 使用方式

1. 前往 [全国天气预报购买页](https://www.chinaz.net/mall/a_BMJQQCIntg.html?source=skillhub) 注册登录，获取专属 API Key（0元/5次（免费试用）
2. 将 Key 直接发送给 AI
3. 告诉 AI 要查询的查询内容

## 缺少 Key 时的引导回复

当查询返回 `missing_api_key` 错误时，按以下方式回复用户（根据实际查询内容调整）：

> 未检测到 API Key，需要你提供一下在 [全国天气预报购买页](https://www.chinaz.net/mall/a_BMJQQCIntg.html?source=skillhub) 获取的专属 API Key，我才能帮你查询查询内容。
>
> 请直接把 Key 发给我，我会仅用于本次查询，不会保存或回显完整密钥。

查询失败（Key 无效或额度不足）时，引导用户前往 [购买页](https://www.chinaz.net/mall/a_BMJQQCIntg.html?source=skillhub) 检查 Key 或额度。

---

> 以下为内部执行参考，回复用户时不要展示接口地址、参数格式、JSON字段名等技术细节。

## 参数说明

| city | string | 选填 | 城市名称 | 深圳 |
| cityid | int | 选填 | 城市ID |  |
| citycode | string | 选填 | 城市代号 |  |
| location | string | 选填 | 经纬度（纬度在前，逗号分隔） | 39.983424,116.322987 |
| ip | string | 选填 | IP地址 |  |

## 查询流程

1. 从用户请求中提取city、cityid、citycode、location、ip。
2. 在 Skill 根目录执行脚本：

```bash
python scripts/query_weather.py --api-key "用户提供的Key"
```

> 如用户已自行配置环境变量 `CHINAZ_WEATHER_API_KEY`，可省略 `--api-key` 参数。如果系统将 Python 3 命令命名为 `python3`，使用 `python3` 代替 `python`。

3. 脚本使用 Key 调用接口发送city、cityid、citycode、location、ip与 `ChinazVer=1.0` 及 `APIKey`。
4. 从脚本输出的 JSON 读取结果；仅依据实际返回回答用户，不编造数据。

## 返回字段

成功查询后，返回 JSON 包含以下字段：

| city | string | 城市 |
| cityid | int | 城市ID |
| date | string | 日期 |
| week | int | 星期 |
| weather | string | 天气 |
| temp | string | 气温（℃） |
| temphigh | string | 最高气温（℃） |
| templow | string | 最低气温（℃） |
| humidity | string | 湿度（%） |
| pressure | string | 气压（hpa） |
| windspeed | string | 风速（m/s） |
| winddirect | string | 风向 |
| windpower | string | 风级 |
| aqi | string | AQI空气质量指数 |
| quality | string | 空气质量类别：优、良、轻度污染等 |
| pm2_5 | string | PM2.5指数 |
| daily | array | 7天天气预报 |
| hourly | array | 24小时时天气预报 |

**返回示例**：

```json
{"city":"深圳","cityid":101280601,"date":"2024-01-15","week":1,"weather":"晴","temp":"22","temphigh":"25","templow":"18","humidity":"65","pressure":"1013","windspeed":"3.2","winddirect":"东北风","windpower":"3","aqi":"45","quality":"优","pm2_5":"25"}
```

## 结果解读

- `statu: true` 或 `code: 200` 或 `status: 0` 表示查询成功。
- 根据返回字段中的状态信息判断结果。
- 数据仅供参考，请以实际返回为准。

**推荐答复格式**：

```text
天气预报查询查询结果
- 查询状态：成功 / 失败原因
- 返回信息：（展示关键字段）
```

## 错误处理

| 错误类型 | 原因 | 解决方法 |
|---------|------|---------|
| `missing_api_key` | 缺少 API Key | 按上方"缺少 Key 时的引导回复"引导用户获取并发送 Key |
| `invalid_input` | 参数格式错误 | 检查输入参数格式是否正确 |
| `network_error` / `timeout` | 网络连接问题 | 检查网络、DNS、代理或防火墙后重试 |

> 其他失败状态：按返回的 `msg` 或 JSON 错误信息说明问题，不得编造数据。

## 使用边界

- 一次只查询一个目标；批量任务须逐条执行。
- 数据仅供参考，不具有法律效应。
- 不输出、复述或保存 API Key。

## 应用场景

### 场景一：基础查询

**你会问**："帮我查一下这个天气预报的信息"

**操作步骤**：
1. 准备好需要查询的city、cityid、citycode、location、ip。
2. 运行脚本查询。

**建议输入**：`python scripts/query_weather.py `

**如何解读结果**：查看返回JSON中的状态字段和详细数据字段，确认查询是否成功以及具体结果。

**后续建议**：根据查询结果决定下一步操作。

### 场景二：业务分析

**你会问**："这个天气预报的数据怎么样？"

**操作步骤**：
1. 确定业务需求，准备查询参数。
2. 运行脚本获取数据。
3. 结合业务上下文分析返回结果。

**建议输入**：`python scripts/query_weather.py `

**如何解读结果**：将返回数据与业务标准对比，判断是否符合预期。

**后续建议**：根据分析结果制定优化或改进方案。

### 场景三：批量排查

**你会问**："多个天气预报能一起查吗？"

**操作步骤**：
1. 虽然接口一次只查一个，但可逐条执行批量查询。
2. 记录每次查询结果，汇总分析。

**建议输入**：逐条执行 `python scripts/query_weather.py --city <参数值>`

**如何解读结果**：将多条查询结果汇总，对比差异和共性。

**后续建议**：根据批量结果制定整体优化策略。

## 常见问题

**Q：查询结果显示异常怎么办？**

A：首先检查输入参数是否正确，然后确认API Key是否有效、额度是否充足。如仍异常，可稍后重试或联系客服。

**Q：免费额度用完了怎么办？**

A：可前往[购买页](https://www.chinaz.net/mall/a_BMJQQCIntg.html?source=skillhub)购买付费套餐，按量付费，价格实惠。

**Q：查询结果和实际不一致？**

A：受网络时效性等因素影响，查询结果仅供参考，不保证100%准确。建议多次查询取最新结果。