xiaozhi-esp32-server/docs/weather-integration.md

# 天气插件使用指南

## 概述

天气插件 `get_weather` 是小智ESP32语音助手的核心功能之一，支持通过语音查询全国各地的天气信息。插件基于和风天气API，提供实时天气和7天天气预报功能。

## 功能特性

- **智能位置识别**：根据用户IP自动识别所在城市
- **多地点查询**：支持全国各城市、地区天气查询
- **详细天气信息**：包含当前天气、温度、湿度、风力等详细参数
- **7天预报**：提供未来一周的天气趋势
- **缓存机制**：优化查询速度，减少API调用
- **智能解析**：支持省份、城市、地标等多种地点表达方式

## 配置方式

### 1. 通过Web管理界面配置（推荐）

1. 登录智控台
2. 进入"角色配置"页面
3. 选择要配置的智能体
4. 点击"编辑功能"按钮
5. 在右侧参数配置区域找到"天气查询"插件
6. 配置相关参数（天气插件API密钥、默认查询城市等）

### 2. 配置文件方式

在 `config.yaml` 中配置：

```yaml
plugins:
  get_weather:
    api_host: "你的和风天气API主机地址"  # 和风天气API主机地址
    api_key: "你的和风天气API密钥"              # 必填：API密钥
    default_location: "广州"                   # 默认查询城市
```

## API Key 申请指南

### 1. 注册和风天气账号

1. 访问 [和风天气控制台](https://console.qweather.com/)
2. 注册账号并完成邮箱验证
3. 登录控制台

### 2. 创建应用获取API Key

1. 进入控制台后，点击右侧"项目管理" → "创建项目"
2. 填写项目信息：
   - **项目名称**：如"小智语音助手"
3. 点击保存
4. 创建完成后，在该项目中点击"创建凭据"
5. 填写凭据信息：
    - **凭据名称**：如"小智语音助手"
    - **身份认证方式**：选择"API Key"
6. 点击保存
7. 在凭据中复制API Key到配置文件中

### 3. 获取API Host

1. 在控制台中点击"设置" → "API Host"
2. 查看分配给你的专属API Host地址
3. 将地址复制到配置文件的 `api_host` 字段

### 4. 额度说明

- **免费额度**：每天1000次免费调用
- **付费计划**：超出免费额度后按调用次数计费
- **建议**：个人使用免费额度通常足够

## 使用方法

### 基本语音指令

#### 1. 查询当前位置天气
```
用户：天气怎么样？
用户：今天天气如何？
用户：现在天气情况
```

#### 2. 查询指定城市天气
```
用户：北京天气
用户：上海的天气怎么样？
用户：查询杭州天气
用户：广州今天天气如何？
```

#### 3. 查询省份天气（自动使用省会城市）
```
用户：山东天气
用户：浙江省天气怎么样？
用户：四川的天气
```

#### 4. 查询地标或区域天气
```
用户：西湖天气          # 自动解析为杭州
用户：外滩天气          # 自动解析为上海
用户：天安门天气        # 自动解析为北京
```

### 返回信息格式

插件会返回以下信息：

```
您查询的位置是：北京

当前天气: 晴，26°C

详细参数：
  · 湿度: 45%
  · 风力: 3级
  · 气压: 1013hPa
  · 能见度: 10km

未来7天预报：
今天: 晴，气温 18°C~28°C
明天: 多云，气温 16°C~25°C
后天: 小雨，气温 14°C~22°C
周四: 阴，气温 15°C~20°C
周五: 晴，气温 17°C~24°C
周六: 多云，气温 19°C~26°C
周日: 晴，气温 21°C~28°C

（如需某一天的具体天气，请告诉我日期）
```

## 支持的天气类型

插件支持以下天气现象的识别和显示：

### 晴天类型
- 晴
- 多云
- 少云
- 晴间多云

### 阴雨类型
- 阴
- 阵雨、强阵雨
- 雷阵雨、强雷阵雨
- 雷阵雨伴有冰雹
- 小雨、中雨、大雨
- 极端降雨、暴雨、大暴雨、特大暴雨
- 毛毛雨/细雨、冻雨

### 雪天类型
- 小雪、中雪、大雪、暴雪
- 雨夹雪、雨雪天气
- 阵雨夹雪、阵雪

### 特殊天气
- 薄雾、雾、浓雾
- 霾、中度霾、重度霾、严重霾
- 扬沙、浮尘、沙尘暴、强沙尘暴

## 智能位置解析

### 1. IP地址定位
- 自动获取用户设备IP地址
- 解析IP对应的城市信息
- 缓存IP位置信息，提高响应速度

### 2. 地点名称智能匹配
- **城市名**：直接查询该城市天气
- **省份名**：自动使用省会城市
- **地标名**：解析到所在城市
- **区县名**：解析到所属市级城市

### 3. 默认位置机制
- 当无法识别用户位置时，使用配置的默认城市
- 建议设置为用户常居住的城市

## 缓存机制

### 1. IP位置缓存
- 缓存用户IP对应的城市信息
- 避免重复调用IP定位API
- 提高查询响应速度

### 2. 天气数据缓存
- 缓存完整的天气报告
- 缓存时间：通常为10-30分钟
- 减少API调用次数，节省配额

## 故障排除

### 1. 查询失败

**现象**：提示"未找到相关的城市"

**原因及解决方案**：
- 检查城市名称拼写是否正确
- 尝试使用标准城市名称（如"北京"而非"北京市"）
- 检查API Key是否有效
- 确认网络连接正常

### 2. API调用超限

**现象**：返回API错误信息

**解决方案**：
- 检查和风天气控制台的配额使用情况
- 考虑升级到付费计划
- 优化缓存策略，减少API调用

### 3. 网络连接问题

**现象**：查询超时或连接失败

**解决方案**：
- 检查服务器网络连接
- 确认和风天气API服务状态
- 检查防火墙设置

### 4. 配置问题

**现象**：插件无法正常工作

**解决方案**：
```yaml
# 检查配置格式是否正确
plugins:
  get_weather:
    api_host: "你的API主机地址"
    api_key: "你的API密钥"
    default_location: "默认城市"
```

## 高级配置

### 1. 自定义缓存时间

修改缓存管理器配置：

```python
# 在 core/utils/cache/manager.py 中调整缓存时间
WEATHER_CACHE_DURATION = 1800  # 30分钟
```

### 2. 多语言支持

插件支持多语言查询：

```yaml
# 在函数调用时指定语言
get_weather(location="北京", lang="en_US")  # 英文
get_weather(location="北京", lang="ja_JP")  # 日文
```

### 3. 自定义默认位置

根据用户群体设置合适的默认城市：

```yaml
plugins:
  get_weather:
    default_location: "上海"  # 针对华东用户
    # default_location: "深圳"  # 针对华南用户
    # default_location: "成都"  # 针对西南用户
```

## 注意事项

1. **API配额管理**：合理使用免费配额，避免频繁查询
2. **地点准确性**：使用标准的城市名称获得最准确的结果
3. **网络依赖**：功能依赖网络连接，确保服务器能访问外网
4. **隐私保护**：IP定位信息仅用于天气查询，不会存储个人隐私
5. **数据准确性**：天气数据来源于和风天气，准确性以官方为准

## 更新记录

- **v1.0.0**：基础天气查询功能
- **v1.1.0**：增加IP自动定位功能
- **v1.2.0**：优化缓存机制，提升查询速度
- **v1.3.0**：支持7天天气预报
- **v1.4.0**：智能地点解析，支持地标查询

## 相关链接

- [和风天气官网](https://www.qweather.com/)
- [和风天气开发文档](https://dev.qweather.com/)
- [API Key申请](https://console.qweather.com/#/apps/create-key/over)
- [项目GitHub](https://github.com/xinnan-tech/xiaozhi-esp32-server)

---

*如有问题或建议，请在项目GitHub仓库提交Issue或联系开发团队。*