香港天气信息

概述

基于香港天文台（HKO）OpenData API 的香港天气技能。提供当前天气实况和本地天气预报。支持按区域筛选及多语言输出（英文、繁体中文、简体中文）。

数据来源

HKO OpenData API — 免费开放，无需 API 密钥。

• 当前天气： https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=rhrread&lang=
• 天气预报： https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=flw&lang=

变量

步骤 1：获取用户输入

(a) 目标区域

向用户询问目标区域/分区。若用户拒绝提供，或表示“整体/全港”，则设 HK_WEATHER_INFO_REGION = None。

(b) 语言偏好

默认使用 tc（繁体中文），除非用户另行指定。支持以下选项：

• tc — 繁体中文（繁體中文）— 默认
• en — English
• sc — 简体中文（简体中文）

存储为 HK_WEATHER_INFO_LANG。若未设置，默认为 tc。

步骤 2：工作流程

(a) 当前天气实况

调用：

GET https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=rhrread&lang=

API 返回 JSON，包含以下字段：

• temperature — 数组，元素为 {place, value, unit}
• humidity — {value, unit}
• rainfall — 数组，元素为 {place, value, unit}
• icon — 天气图标代码
• uvindex — 紫外线指数（如可用）
• updateTime — 时间戳
• warningMessage — 当前生效的预警信息（字符串）
• rainstormReminder — 暴雨提醒（字符串）

区域筛选逻辑： 若设置了 HK_WEATHER_INFO_REGION（非 None）：

1. 在 temperature 数组中查找 place 字段与目标区域**不区分大小写的部分匹配**的条目
2. 在 rainfall 数组中执行相同匹配
3. 仅展示匹配到的区域数据

若未找到匹配项，或 HK_WEATHER_INFO_REGION 为 None：

• 展示全港整体天气（即所有气温观测站、所有降雨量观测站的数据）

(b) 本地天气预报

调用：

GET https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=flw&lang=

API 返回 JSON，包含以下字段：

• generalSituation — 天气总体概况
• forecastDesc — 预报描述（面向用户的可读文本）
• outlook — 展望
• forecastPeriod — 字符串（风向缩写字母，不是数组）。请使用 forecastDesc 获取人类可读的预报正文。
• updateTime — 时间戳

区域筛选逻辑： 若设置了 HK_WEATHER_INFO_REGION：

• 预报本身为全港范围；呈现时需注明该区域上下文。

默认展示今日与明日预报。

步骤 3：1 分钟平均气温（CSV）

完成步骤 1 和步骤 2 后，从 HKO 提供的 CSV 文件中获取最新 1 分钟平均气温。

参考文档： references/1min-temp-csv.md — 包含实际列名、别名映射、常见注意事项等详细说明。

(a) 确定 CSV URL

依据 HK_WEATHER_INFO_LANG 值确定：

(b) 带重试机制下载

• 通过 curl（或 urllib）尝试下载 CSV。
• 若下载失败（网络错误、超时、空响应），最多重试 2 次。
• 若所有重试均失败，则跳过 1 分钟气温数据 — 不应阻塞其余天气信息的输出。

(c) 提取气温值

CSV 列名因语言而异。实际观察到的列名如下：

CSV 文件以 UTF-8 BOM（ufeff）开头 — 解析前必须去除，否则首列键名将损坏。

CSV 包含约 39 个自动气象站，其站名具有特定性（例如：荃灣可觀、赤鱲角、京士柏），并非通用分区名称。进行区域匹配时：

• 若设置了 HK_WEATHER_INFO_REGION：优先尝试直接的部分匹配；若失败，则尝试英文→中文别名映射（例如 “Tsuen Wan” → 荃灣，“Central” → 中環）。采用首个匹配站点的气温值。
• 若未设置 HK_WEATHER_INFO_REGION 或无匹配项：计算所有站点气温值的算术平均值，作为全港整体的 1 分钟平均气温。

(d) 追加至输出结果

若成功获取 1 分钟平均气温，则将其追加至最终回复末尾：

繁体中文（TC）输出：

🕒 1分鐘平均氣溫：XX°C（[地區名稱 / 全港平均]）

英文（EN）输出：

🕒 1-Min Avg Temp: XX°C ([Region Name / HK Average])

简体中文（SC）输出：

🕒 1分钟平均气温：XX°C（[地区名称 / 全港平均]）

输出格式

当 lang=tc（默认）时，HKO API 所有文本字段均返回繁体中文。为保持一致性，请使用中文标签：

当前天气（TC）

🇭🇰 香港天氣 [地區]

🌡️ 氣溫：XX°C（測站名稱）
💧 濕度：XX%
🌧️ 雨量：XXmm（測站名稱）
☀️ 紫外線指數：XX（如有）

⚠️ 生效警告：[警告內容 / 無]
🕐 更新時間：

天气预报（TC）

📅 天氣預測

📋 概況：

📅 今日： | 溫度：°C | 濕度：%
📅 明日： | 溫度：°C | 濕度：%

🔮 展望：

🕐 更新時間：

当 lang=en 时，使用英文标签：

🌤️ Hong Kong Weather [Region if set]
Temperature: XX°C (Station Name)
Humidity: XX%
...
Forecast: 

时区与日期处理

务必首先检查系统时间。 运行 date '+%Y-%m-%d %H:%M:%S %Z' 并转换为香港标准时间（HKT，UTC+8）后再响应。切勿依赖对话上下文或系统提示中的时间戳推断日期 — 对话可能跨越多日。

无需 API 密钥。HKO OpenData 完全免费开放。

依赖项

• 仅需 Python 3.10+ 标准库（urllib、json、datetime）

脚本

scripts/hk_weather.py — 命令行客户端，内置 10 分钟文件缓存。默认语言为 tc（繁体中文）。

python3 scripts/hk_weather.py                          # 全港整体天气，繁体中文（默认）
python3 scripts/hk_weather.py --region "Tsuen Wan"     # 指定区域，繁体中文
python3 scripts/hk_weather.py --lang en                 # 英文输出
python3 scripts/hk_weather.py --action current          # 仅当前天气
python3 scripts/hk_weather.py --action forecast         # 仅天气预报

常见陷阱

0. 默认语言为繁体中文（TC） — 脚本默认使用 --lang tc。所有输出（包括标签）均应为繁体中文，除非用户明确指定 --lang en 或 --lang sc。HKO API 在 lang=tc 时返回中文文本字段，因此输出标签也须统一使用中文以确保一致性。
1. 无需 API 密钥 — HKO OpenData 完全免费开放
2. 请求频率限制 — 请合理轮询，并对结果缓存 10–15 分钟
3. 区域名称匹配 — 使用不区分大小写的部分匹配。部分气象站名称与行政区划名称存在差异
4. 紫外线指数（UV index） — 夜间或阴天可能为空值
5. 预警信息（warning message） — 若无生效预警，该字段可能为空字符串
6. 预报语言 — lang 参数影响所有文本字段
7. 降雨量条目可能缺失 value 键 — 访问前务必检查 "value" in matched。不同站点对空/缺失降雨数据的表示方式不一致。
8. forecastPeriod 是字符串而非数组 — flw API 返回的 forecastPeriod 是一个字符串（风向缩写），不是 预报时段对象数组。请始终使用 forecastDesc 获取人类可读的预报正文。
9. 1 分钟 CSV 含 UTF-8 BOM — HKO CSV 文件以 ufeff 开头。解析前必须去除，否则首列键名将损坏。CSV 同时使用语言特定的中文列名（如 自動氣象站、氣溫（攝氏）），而非通用的 地區/溫度 等名称。
10. CSV 区域匹配需依赖别名映射 — CSV 中的站点名称是具体自动气象站名称（如 荃灣可觀、赤鱲角），并非行政区划名称。“Tsuen Wan” 等英文区域名无法直接匹配中文站名 — 必须使用别名映射（如 “Tsuen Wan” → 荃灣）。

验证清单

• 已使用 HKO OpenData API（无需 API 密钥）
• 已实现区域筛选功能
• 已支持语言偏好（en/tc/sc）
• 已同时获取当前天气与天气预报
• 已明确定义输出格式
• 无外部依赖（仅使用 Python 标准库）

更新日志

v1.1.0 — 修复 Bug 并新增 1 分钟平均气温 CSV 支持

• 修复 warningMessage 格式化问题：HKO API 可能返回警告字符串列表，而非单个字符串。现改为遍历并逐行打印每条预警。
• 修正 SKILL.md 中 forecastPeriod 描述：其为字符串（风向），非数组。已移除矛盾描述。
• 新增步骤 3：从 HKO regional-weather CSV 获取最新 1 分钟平均气温。
• 支持全部三种语言（en/tc/sc），各语言对应独立 CSV URL。
• 下载失败时最多重试 2 次。
• 区域匹配逻辑：提取所请求区域的气温值；若未匹配则计算全港平均值。
• 将 1 分钟气温信息追加至天气回复末尾。
• 修复 match_region 函数，使其支持当前天气区域筛选中的英文→中文别名映射。
• 修复湿度单位显示问题：HKO API 返回 "percent" 字符串，而非 "%" 符号。

v1.0.0 — 初始发布

• 集成 HKO OpenData API（rhrread + flw）、区域筛选、多语言支持（en/tc/sc），默认语言为繁体中文。