docs: 添加天气插件使用指南

2026-07-21 10:55:38 +00:00 · 2025-09-02 11:23:46 +08:00
parent 63dfcde4c8
commit 0364d1199b
2 changed files with 294 additions and 1 deletions
@@ -476,7 +476,8 @@ ws://你电脑局域网的ip:8000/xiaozhi/v1/
 4、[如何部署MCP接入点](./mcp-endpoint-enable.md)<br/>
 5、[如何接入MCP接入点](./mcp-endpoint-integration.md)<br/>
 6、[如何开启声纹识别](./voiceprint-integration.md)<br/>
-10、[新闻插件源配置指南](./newsnow_plugin_config.md)<br/>
+7、[新闻插件源配置指南](./newsnow_plugin_config.md)<br/>
+8、[天气插件使用指南](./weather-integration.md)<br/>
 ## 语音克隆、本地语音部署相关教程
 1、[如何部署集成index-tts本地语音](./index-stream-integration.md)<br/>
 2、[如何部署集成fish-speech本地语音](./fish-speech-integration.md)<br/>
@@ -0,0 +1,292 @@
+# 天气插件使用指南
+
+## 概述
+
+天气插件 `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或联系开发团队。*