koishi-plugin-weather-alert

一个面向 QQ 群的 Koishi 气象预警推送插件。插件定时查询和风天气 Weather Alert API，将监测地区的气象预警通过 OneBot v11 机器人发送到指定 QQ 群。

特性

• 支持在 Koishi 控制台完成全部配置。
• 支持为每个 QQ 群分别配置监测地区、机器人账号和经纬度坐标。
• 不同 QQ 群只会收到自己订阅地区的预警。
• 使用 Ed25519 JWT 认证
• 默认每 15 分钟查询一次，查询间隔可调整。
• 持久化保存发送记录，避免轮询和重启造成重复推送。
• 自动将预警时间转换为中国标准时间。
• 提供管理员手动检查命令。

前置条件

• Koishi 4.18 或更高版本。
• 已开通和风天气开发服务，并创建使用 Ed25519 公钥的 JWT 凭据。

JWT 密钥

和风天气 JWT 需要一对 Ed25519 密钥。开发者可以在插件项目目录执行以下命令生成：

npm run generate-keys

命令会在本地 keys/ 目录生成：

• qweather-public.pem：上传至和风天气控制台的 JWT 凭据。
• qweather-private.pem：仅用于本地签名，禁止上传或公开。

配置

在 Koishi 控制台填写以下配置：

| 配置项 | 说明 | | --- | --- | | apiHost | 和风天气控制台分配给当前用户的专属 API Host | | projectId | 和风天气项目 ID，对应 JWT 的 sub | | keyId | JWT 凭据 ID，对应 JWT Header 的 kid | | privateKey | 可选，直接粘贴 Ed25519 私钥 PEM，填写后优先使用 | | privateKeyPath | privateKey 留空时读取的私钥文件路径 | | targetGroups | 每个群分别填写群号、可选的机器人 QQ 号，以及该群专属的监测地区列表 | | intervalMinutes | 查询间隔，默认 15 分钟 | | runOnStart | 插件启动后是否立即查询 | | stateFile | 已发送预警的去重状态文件 |

API Host 可以填写纯域名或完整 HTTPS 地址，例如：

your-api-host.qweatherapi.com
https://your-api-host.qweatherapi.com

每个 targetGroups 项都包含一个 locations 列表。例如，A 群可以订阅北京和天津，B 群可以只订阅上海；A 群不会收到上海的预警，B 群也不会收到北京或天津的预警。

消息格式

预警标题
生效时间:YYYY-MM-DD hh:mm
失效时间:YYYY-MM-DD hh:mm
详细:预警详细内容
提示:防御指南

管理命令

立即查询并推送尚未发送的预警：

weather-alert.check

强制重新发送当前预警：

weather-alert.check -f

命令默认要求 Koishi 权限等级 3。

数据来源

预警数据由和风天气开发服务提供，实际预警以中国气象局及当地气象主管机构发布的信息为准。部署者应遵守和风天气的数据署名要求与服务许可。

许可证

MIT