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 中配置：

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

API Key 申请指南

1. 注册和风天气账号

1. 访问 和风天气控制台
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. 配置问题

现象：插件无法正常工作

解决方案：

# 检查配置格式是否正确
plugins:
  get_weather:
    api_host: "你的API主机地址"
    api_key: "你的API密钥"
    default_location: "默认城市"

高级配置

1. 自定义缓存时间

修改缓存管理器配置：

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

2. 多语言支持

插件支持多语言查询：

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

3. 自定义默认位置

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

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：智能地点解析，支持地标查询

相关链接

• 和风天气官网
• 和风天气开发文档
• API Key申请
• 项目GitHub

---

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