From a842f0688f0ca3add677e30c110d22415d8a537d Mon Sep 17 00:00:00 2001 From: 3030332422 <3030332422@qq.com> Date: Tue, 2 Sep 2025 12:36:04 +0800 Subject: [PATCH] =?UTF-8?q?fix:=E4=BC=98=E5=8C=96=E5=A4=A9=E6=B0=94?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/weather-integration.md | 263 +++--------------------------------- 1 file changed, 16 insertions(+), 247 deletions(-) diff --git a/docs/weather-integration.md b/docs/weather-integration.md index 021b3f90..c13446fc 100644 --- a/docs/weather-integration.md +++ b/docs/weather-integration.md @@ -4,38 +4,6 @@ 天气插件 `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. 注册和风天气账号 @@ -46,11 +14,11 @@ plugins: ### 2. 创建应用获取API Key -1. 进入控制台后，点击右侧"项目管理" → "创建项目" +1. 进入控制台后，点击右侧"项目管理"(https://console.qweather.com/project?lang=zh) → "创建项目" 2. 填写项目信息： - **项目名称**：如"小智语音助手" 3. 点击保存 -4. 创建完成后，在该项目中点击"创建凭据" +4. 项目创建完成后，在该项目中点击"创建凭据" 5. 填写凭据信息： - **凭据名称**：如"小智语音助手" - **身份认证方式**：选择"API Key" @@ -59,7 +27,7 @@ plugins: ### 3. 获取API Host -1. 在控制台中点击"设置" → "API Host" +1. 在控制台中点击"设置"(https://console.qweather.com/setting?lang=zh) → "API Host" 2. 查看分配给你的专属API Host地址 3. 将地址复制到配置文件的 `api_host` 字段 @@ -69,224 +37,25 @@ plugins: - **付费计划**：超出免费额度后按调用次数计费 - **建议**：个人使用免费额度通常足够 -## 使用方法 +## 配置方式(任选一种) -### 基本语音指令 +### 方式1. 通过Web管理界面配置（推荐） -#### 1. 查询当前位置天气 -``` -用户：天气怎么样？ -用户：今天天气如何？ -用户：现在天气情况 -``` +1. 登录智控台 +2. 进入"角色配置"页面 +3. 选择要配置的智能体 +4. 点击"编辑功能"按钮 +5. 在右侧参数配置区域找到"天气查询"插件 +6. 配置相关参数（天气插件API密钥、默认查询城市等） -#### 2. 查询指定城市天气 -``` -用户：北京天气 -用户：上海的天气怎么样？ -用户：查询杭州天气 -用户：广州今天天气如何？ -``` +### 方式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. 自定义默认位置 - -根据用户群体设置合适的默认城市： +在 `config.yaml` 中配置： ```yaml plugins: get_weather: - default_location: "上海" # 针对华东用户 - # default_location: "深圳" # 针对华南用户 - # default_location: "成都" # 针对西南用户 + api_host: "你的和风天气API主机地址" # 和风天气API主机地址 + api_key: "你的和风天气API密钥" # 必填：API密钥 + 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或联系开发团队。*