@zhin.js/plugin-earthquake 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# @zhin.js/plugin-earthquake
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+地震查询与群推送插件：合并中国地震台网（CENC）与 USGS 的公开数据，按震级和地区订阅速报。不需要任何 API Key，不含适配器专用代码，所有平台通用。
+
+## Installation
+
+```bash
+pnpm exec zhin install @zhin.js/plugin-earthquake
+```
+
+## Usage
+
+安装命令会在主配置 `plugins` 映射中挂载 `earthquake` 实例。对应的 `zhin.config.yml` 节点：
+
+```yaml
+configVersion: 2
+plugins:
+  earthquake: "@zhin.js/plugin-earthquake"
+earthquake: {}
+```
+
+### 命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `地震 [条数]` | 查询最近地震。选项：`--min/-m` 最小震级（默认 3）、`--region/-r` 地区关键词、`--hours/-t` 时间范围（小时，默认 24，最多 168）。每人 5 秒冷却 |
+| `地震 订阅 [最小震级] [地区...]` | 在当前会话订阅速报（群聊限群主、管理员或机器人主人，见下文权限），例如 `地震 订阅 5 中国`、`地震 订阅 6 日本 Japan`。不写震级时用 `defaultMinMagnitude`（默认 5）；不写地区表示全球。再次执行会覆盖原订阅 |
+| `地震 退订` | 取消当前会话的订阅（权限同上） |
+| `地震 订阅状态` | 查看当前会话的订阅与各数据源健康状况 |
+
+### 权限
+
+- **群聊 / 频道**：只有群主（`owner`）、群管理员（`admin`）或机器人主人（`master`）可以执行 `地震 订阅`、`地震 退订`；其他成员会收到“只有群主、群管理员或机器人主人可以在群聊中修改地震订阅”的提示。
+- **私聊**：用户可以直接订阅、退订自己的私聊会话，不受限制。
+- `地震` 查询与 `地震 订阅状态` 对所有人开放。
+
+判断使用框架内置的 permit 检查器（`private()` 或 `role(owner,admin,master)`），角色来自适配器投影的通用 `sender.role`，不含平台专用代码。如果某个平台的适配器不提供群角色，群里只有机器人主人能修改订阅。
+
+地区是对地点文字的关键词匹配（不区分大小写），同时匹配 CENC 的中文地名与 USGS 的英文地名；`中国` / `国内` 是预设，匹配 CENC 中以省级行政区开头的地点以及 USGS 中含 China / Taiwan 的地点。震级阈值按各数据源报告中的最大震级判断。
+
+### Agent 工具
+
+技能 `earthquake` 提供只读工具 `recent_earthquakes`（参数 `limit`、`minMagnitude`、`region`、`hours`），回答“刚才哪里地震了”之类的问题。
+
+### 推送前提
+
+订阅推送需要 Outbound Host 与 Schedule Host（标准 Runtime 默认提供）。配置数据库时订阅持久保存在插件状态中；没有数据库时保存在内存里，重启后丢失。
+
+## 数据源
+
+| 数据源 | 默认地址 | 说明 |
+| --- | --- | --- |
+| CENC | `https://api.wolfx.jp/cenc_eqlist.json`（主，第三方公开镜像） → `https://ceic.ac.cn/data/data.json`（备用，官网“最新地震”页面的静态数据） | 中文地名；时间为北京时间；可用 `cencUrls` 改为自建镜像 |
+| USGS | `https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/<usgsFeed>.geojson` | 全球覆盖，作为 CENC 失败时的兜底；`usgsFeed` 默认 `2.5_day`（24 小时内 M2.5+） |
+
+旧的 CENC 接口（`news.ceic.ac.cn/ajax/google`、`www.ceic.ac.cn/ajax/*`）已不可用，本插件不使用。两个数据源都没有公开的接口契约，解析按“容错”设计：数字字符串可接受，坏记录逐条跳过；整批都无法解析时视为该地址失败并切换下一个地址或数据源。
+
+`地震 --hours` 超过 USGS 汇总源的时间跨度时（例如 `2.5_day` 只有 24 小时），更早的数据只来自 CENC。
+
+## 去重
+
+同一地震在不同数据源中的 ID、时间、震中和震级类型（CENC 的 M 与 USGS 的 mb/Mw）都会略有差异。满足以下全部条件即视为同一事件：
+
+- 发震时间相差 ≤ 60 秒；
+- 震中距离（大圆距离）≤ 100 km；
+- 震级相差 ≤ 1.0（CENC M 与 USGS mb 常相差约 1 级）。
+
+同一数据源内 ID 相同，或时间相差 ≤ 5 秒且距离 ≤ 50 km 也视为同一事件（不同 CENC 镜像会给同一地震分配不同 ID）。合并后的事件以 `sources` 中靠前的数据源作为主报告（提供地点文字）。
+
+## 容错设计
+
+- **超时**：每次 HTTP 请求单独超时（`requestTimeoutMs`，默认 10 秒）。
+- **重试**：网络错误、超时、408/425/429/5xx 按指数退避加随机抖动重试（`maxRetries` 默认 2 次，首次等待 `retryBaseDelayMs` 1 秒，单次上限 `retryMaxDelayMs` 30 秒）；其他 4xx 不重试。
+- **Retry-After**：遵守秒数或 HTTP 日期格式；要求的等待超过单次上限时本轮放弃，并让该数据源冷却到指定时间（最长 1 小时）。
+- **冷却**：一轮全部失败的数据源按 30 秒、60 秒、120 秒……递增冷却，上限 10 分钟，期间由其他数据源兜底。
+- **镜像切换**：CENC 的多个地址按顺序尝试。
+- **条件请求**：使用 ETag / Last-Modified，数据未变化时服务器返回 304，复用缓存。
+- **过期数据兜底**：所有数据源都失败时，`地震` 查询返回上次成功获取的数据并明确标注。
+- **轮询不中断**：轮询从不抛错，失败只记录日志，下一轮照常执行；上一轮未结束时跳过本轮。
+- **不刷屏**：每个数据源的第一次成功获取只建立基线、不推送；超过 `maxEventAgeMinutes`（默认 60 分钟）的事件不推送；每个事件只推送一次（发送前标记，发送失败只记录日志、不重试，避免重复投递）。
+- **推送限流**：每个会话每 `pushWindowMinutes`（默认 10 分钟）最多 `pushLimit`（默认 3）条消息；一轮中的多个事件合并为一条消息，最多列出 `maxEventsPerMessage`（默认 5）个。被限流跳过的事件数会在下一条推送中注明。限流状态只保存在内存中。
+
+## Configuration
+
+所有字段均可省略，越界数值会被收敛到安全范围。完整字段见 `schema.json` 与生成的配置参考。
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `sources` | `["cenc", "usgs"]` | 启用的数据源及优先顺序 |
+| `cencUrls` | 见上表 | CENC 地址，按顺序尝试；仅 HTTPS，最多 5 个 |
+| `usgsFeed` | `2.5_day` | USGS 汇总源 |
+| `pollCron` | `0 */2 * * * *` | 订阅轮询频率（6 段 Cron） |
+| `timezone` | `Asia/Shanghai` | 显示时间使用的 IANA 时区 |
+| `requestTimeoutMs` | `10000` | 单次请求超时 |
+| `maxRetries` | `2` | 瞬时错误重试次数 |
+| `retryBaseDelayMs` | `1000` | 退避首次等待 |
+| `retryMaxDelayMs` | `30000` | 单次退避 / Retry-After 上限 |
+| `defaultMinMagnitude` | `5` | 订阅默认最小震级 |
+| `queryMinMagnitude` | `3` | 查询默认最小震级 |
+| `queryLimit` | `5` | 查询默认条数 |
+| `maxEventAgeMinutes` | `60` | 只推送这么多分钟以内发生的地震 |
+| `pushLimit` / `pushWindowMinutes` | `3` / `10` | 每会话推送限流 |
+| `maxEventsPerMessage` | `5` | 单条推送最多列出的地震数 |
+| `maxSubscriptions` | `100` | 本实例订阅总数上限 |
+
+```yaml
+earthquake:
+  sources: [cenc, usgs]
+  defaultMinMagnitude: 4.5
+  pushLimit: 2
+```
+
+## 说明
+
+- 地震数据仅供参考，不能替代官方预警与应急信息。
+- 功能设计参考了 kivibot 的地震速报插件，但仅参考功能，代码与数据均为独立实现。

package/commands//345/234/260/351/234/207/index.js

@@ -0,0 +1,25 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { renderRecentEarthquakes } from "../../lib/query-text.js";
+import { earthquakeServiceToken } from "../../lib/runtime.js";
+export default defineCommand({
+    description: '查询最近的地震（CENC 中国地震台网 / USGS）',
+    params: {
+        count: { type: 'integer', optional: true, min: 1, max: 20, description: '列出条数' },
+    },
+    options: {
+        min: { type: 'float', alias: 'm', min: 0, max: 10, description: '最小震级' },
+        region: { type: 'string', alias: 'r', description: '地区关键词，如 四川、日本、中国' },
+        hours: { type: 'integer', alias: 't', min: 1, max: 168, description: '时间范围（小时），默认 24' },
+    },
+    execution: { cooldownMs: 5_000, progressAfterMs: 3_000 },
+    async execute({ params, options, use }) {
+        const service = use(earthquakeServiceToken);
+        return renderRecentEarthquakes(service, {
+            limit: params.count,
+            minMagnitude: options.min,
+            region: options.region,
+            hours: options.hours,
+        });
+    },
+});

package/commands//345/234/260/351/234/207/manage-permission.js

@@ -0,0 +1,20 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Who may change a conversation's earthquake subscription.
+ *
+ * - Private chat: the user manages their own conversation, no restriction.
+ * - Group or channel: only the group owner, group admins or the bot master.
+ *
+ * `permit` lists are AND-only, so this "private OR role(...)" rule is evaluated
+ * with the same built-in permit checker the command router uses. Roles come
+ * from the adapter's platform-agnostic projection (`sender.role`).
+ */
+import { checkBuiltinPermit } from '@zhin.js/command';
+export const SUBSCRIPTION_MANAGER_ROLES_PERMIT = 'role(owner,admin,master)';
+export const PRIVATE_CHAT_PERMIT = 'private()';
+export const SUBSCRIPTION_PERMISSION_DENIED_MESSAGE = '只有群主、群管理员或机器人主人可以在群聊中修改地震订阅；私聊中可以直接订阅本会话。';
+export function canManageSubscription(subject) {
+    if (checkBuiltinPermit(PRIVATE_CHAT_PERMIT, subject))
+        return true;
+    return checkBuiltinPermit(SUBSCRIPTION_MANAGER_ROLES_PERMIT, subject);
+}

package/commands//345/234/260/351/234/207//350/256/242/351/230/205/index.js

@@ -0,0 +1,51 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { conversationError, extractConversation } from "../../../lib/conversation.js";
+import { canManageSubscription, SUBSCRIPTION_PERMISSION_DENIED_MESSAGE } from '../manage-permission.js';
+import { earthquakeServiceToken } from "../../../lib/runtime.js";
+import { parseSubscribeArgs } from "../../../lib/subscribe-args.js";
+import { SubscriptionLimitError } from "../../../lib/subscriptions.js";
+export default defineCommand({
+    description: '在当前会话订阅地震速报：地震 订阅 [最小震级] [地区...]（群聊限群主、管理员或机器人主人）',
+    params: {
+        filters: { type: 'word', rest: true, description: '可选：最小震级与地区关键词，如 5 四川 云南' },
+    },
+    async execute({ params, input, use, adapter, scene, sender }) {
+        const service = use(earthquakeServiceToken);
+        const target = extractConversation(input);
+        if (!target)
+            return conversationError(input);
+        if (!canManageSubscription({ adapter, scene, sender }))
+            return SUBSCRIPTION_PERMISSION_DENIED_MESSAGE;
+        const parsed = parseSubscribeArgs(params.filters ?? []);
+        if ('error' in parsed)
+            return parsed.error;
+        const minMagnitude = parsed.minMagnitude ?? service.config.defaultMinMagnitude;
+        try {
+            const { created } = await service.store.upsert({
+                adapter: target.adapter,
+                endpointKey: target.endpointKey,
+                conversationKind: target.conversationKind,
+                conversationId: target.conversationId,
+                minMagnitude,
+                regions: parsed.regions,
+                createdBy: target.senderId,
+                createdAt: new Date().toISOString(),
+            });
+            const regionText = parsed.regions.length > 0 ? parsed.regions.join('、') : '全球';
+            const lines = [
+                `${created ? '已订阅' : '已更新订阅'}：M${minMagnitude.toFixed(1)} 以上，地区：${regionText}`,
+            ];
+            if (!service.canPush) {
+                lines.push('⚠️ 当前运行环境没有出站发送能力，订阅已保存但暂时不会推送');
+            }
+            lines.push('取消订阅请发送：地震 退订');
+            return lines.join('\n');
+        }
+        catch (error) {
+            if (error instanceof SubscriptionLimitError)
+                return error.message;
+            throw error;
+        }
+    },
+});

package/commands//345/234/260/351/234/207//350/256/242/351/230/205/347/212/266/346/200/201/index.js

@@ -0,0 +1,41 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { conversationError, extractConversation } from "../../../lib/conversation.js";
+import { formatEventTime, sourceLabel } from "../../../lib/format.js";
+import { earthquakeServiceToken } from "../../../lib/runtime.js";
+import { subscriptionKey } from "../../../lib/subscriptions.js";
+export default defineCommand({
+    description: '查看当前会话的地震订阅与数据源状态',
+    async execute({ input, use }) {
+        const service = use(earthquakeServiceToken);
+        const target = extractConversation(input);
+        if (!target)
+            return conversationError(input);
+        const subscription = await service.store.get(subscriptionKey(target));
+        const timezone = service.config.timezone;
+        const lines = [];
+        if (subscription) {
+            const regionText = subscription.regions.length > 0 ? subscription.regions.join('、') : '全球';
+            lines.push(`本会话订阅：M${subscription.minMagnitude.toFixed(1)} 以上，地区：${regionText}`);
+        }
+        else {
+            lines.push('本会话未订阅。订阅示例：地震 订阅 5 中国');
+        }
+        lines.push('数据源：');
+        for (const health of service.health()) {
+            let status = '正常';
+            if (health.coolingDownUntil > 0) {
+                status = `冷却至 ${formatEventTime(health.coolingDownUntil, timezone)}`;
+            }
+            else if (health.consecutiveFailures > 0) {
+                status = `连续失败 ${health.consecutiveFailures} 次`;
+            }
+            else if (health.lastSuccessAt === undefined) {
+                status = '尚未请求';
+            }
+            const reason = health.lastError ? `（${health.lastError}）` : '';
+            lines.push(`- ${sourceLabel(health.id)}：${status}${reason}`);
+        }
+        return lines.join('\n');
+    },
+});

package/commands//345/234/260/351/234/207//351/200/200/350/256/242/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { conversationError, extractConversation } from "../../../lib/conversation.js";
+import { canManageSubscription, SUBSCRIPTION_PERMISSION_DENIED_MESSAGE } from '../manage-permission.js';
+import { earthquakeServiceToken } from "../../../lib/runtime.js";
+import { subscriptionKey } from "../../../lib/subscriptions.js";
+export default defineCommand({
+    description: '取消当前会话的地震速报订阅（群聊限群主、管理员或机器人主人）',
+    async execute({ input, use, adapter, scene, sender }) {
+        const service = use(earthquakeServiceToken);
+        const target = extractConversation(input);
+        if (!target)
+            return conversationError(input);
+        if (!canManageSubscription({ adapter, scene, sender }))
+            return SUBSCRIPTION_PERMISSION_DENIED_MESSAGE;
+        const removed = await service.store.remove(subscriptionKey(target));
+        return removed ? '已取消本会话的地震速报订阅' : '本会话没有地震速报订阅';
+    },
+});

package/lib/config.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Plugin configuration with conservative, documented defaults.
+ *
+ * Every field is optional. `resolveEarthquakeConfig` fills defaults and clamps
+ * out-of-range numbers so a typo in `zhin.config.yml` degrades to a safe value
+ * instead of hammering the public feeds or flooding a group.
+ */
+export declare const EARTHQUAKE_SOURCE_IDS: readonly ["cenc", "usgs"];
+export type EarthquakeSourceId = (typeof EARTHQUAKE_SOURCE_IDS)[number];
+/** USGS summary feeds that make sense for alerts (larger feeds are wasteful). */
+export declare const USGS_FEEDS: readonly ["significant_hour", "significant_day", "4.5_hour", "4.5_day", "2.5_hour", "2.5_day", "1.0_hour", "1.0_day"];
+export type UsgsFeed = (typeof USGS_FEEDS)[number];
+export interface EarthquakeConfig {
+    /** Sources in preference order. The first one wins location text when events merge. */
+    readonly sources?: readonly EarthquakeSourceId[];
+    /** CENC catalogue URLs: primary first, then mirrors/fallbacks. HTTPS only. */
+    readonly cencUrls?: readonly string[];
+    /** USGS GeoJSON summary feed name. */
+    readonly usgsFeed?: UsgsFeed;
+    /** 6-field solar cron for the subscription poller. */
+    readonly pollCron?: string;
+    /** IANA time zone used to display event times. */
+    readonly timezone?: string;
+    /** Per-attempt HTTP timeout. */
+    readonly requestTimeoutMs?: number;
+    /** Retries after the first attempt for transient failures (network, 408, 425, 429, 5xx). */
+    readonly maxRetries?: number;
+    /** Base delay for exponential backoff with jitter. */
+    readonly retryBaseDelayMs?: number;
+    /** Upper bound for a single backoff or Retry-After wait inside one request. */
+    readonly retryMaxDelayMs?: number;
+    /** Magnitude threshold for new subscriptions that do not name one. */
+    readonly defaultMinMagnitude?: number;
+    /** Magnitude threshold for the `地震` query when none is given. */
+    readonly queryMinMagnitude?: number;
+    /** Default number of events listed by the `地震` query. */
+    readonly queryLimit?: number;
+    /** Events older than this are never pushed (protects against late or replayed feeds). */
+    readonly maxEventAgeMinutes?: number;
+    /** Messages allowed per conversation inside one push window. */
+    readonly pushLimit?: number;
+    /** Length of the push rate-limit window. */
+    readonly pushWindowMinutes?: number;
+    /** Events listed in one push message; the rest are summarised as a count. */
+    readonly maxEventsPerMessage?: number;
+    /** Total subscriptions across all conversations for this plugin instance. */
+    readonly maxSubscriptions?: number;
+}
+export type ResolvedEarthquakeConfig = {
+    readonly [K in keyof EarthquakeConfig]-?: NonNullable<EarthquakeConfig[K]>;
+};
+export declare const DEFAULT_EARTHQUAKE_CONFIG: ResolvedEarthquakeConfig;
+/** Maximum regions a single subscription may name. */
+export declare const MAX_REGIONS_PER_SUBSCRIPTION = 5;
+/** Throws when the configured time zone is unknown to the runtime's Intl data. */
+export declare function assertEarthquakeTimezone(timezone: string): void;
+export declare function resolveEarthquakeConfig(raw: unknown): ResolvedEarthquakeConfig;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,qBAAqB,2BAA4B,CAAC;AAC/D,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,iFAAiF;AACjF,eAAO,MAAM,UAAU,uHASb,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,iEAAiE;IACjE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,CAAC,IAAI,MAAM,gBAAgB,CAAC,CAAC,GAAG,WAAW,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAC3E,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,wBAqBtC,CAAC;AAEH,sDAAsD;AACtD,eAAO,MAAM,4BAA4B,IAAI,CAAC;AA6D9C,kFAAkF;AAClF,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAM/D;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,wBAAwB,CAwB9E"}

package/lib/config.js

@@ -0,0 +1,138 @@
+/**
+ * Plugin configuration with conservative, documented defaults.
+ *
+ * Every field is optional. `resolveEarthquakeConfig` fills defaults and clamps
+ * out-of-range numbers so a typo in `zhin.config.yml` degrades to a safe value
+ * instead of hammering the public feeds or flooding a group.
+ */
+export const EARTHQUAKE_SOURCE_IDS = ['cenc', 'usgs'];
+/** USGS summary feeds that make sense for alerts (larger feeds are wasteful). */
+export const USGS_FEEDS = [
+    'significant_hour',
+    'significant_day',
+    '4.5_hour',
+    '4.5_day',
+    '2.5_hour',
+    '2.5_day',
+    '1.0_hour',
+    '1.0_day',
+];
+export const DEFAULT_EARTHQUAKE_CONFIG = Object.freeze({
+    sources: Object.freeze(['cenc', 'usgs']),
+    cencUrls: Object.freeze([
+        'https://api.wolfx.jp/cenc_eqlist.json',
+        'https://ceic.ac.cn/data/data.json',
+    ]),
+    usgsFeed: '2.5_day',
+    pollCron: '0 */2 * * * *',
+    timezone: 'Asia/Shanghai',
+    requestTimeoutMs: 10_000,
+    maxRetries: 2,
+    retryBaseDelayMs: 1_000,
+    retryMaxDelayMs: 30_000,
+    defaultMinMagnitude: 5,
+    queryMinMagnitude: 3,
+    queryLimit: 5,
+    maxEventAgeMinutes: 60,
+    pushLimit: 3,
+    pushWindowMinutes: 10,
+    maxEventsPerMessage: 5,
+    maxSubscriptions: 100,
+});
+/** Maximum regions a single subscription may name. */
+export const MAX_REGIONS_PER_SUBSCRIPTION = 5;
+function clampNumber(value, fallback, min, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.min(max, Math.max(min, value));
+}
+function resolveSources(value) {
+    if (!Array.isArray(value)) {
+        return DEFAULT_EARTHQUAKE_CONFIG.sources;
+    }
+    const known = new Set(EARTHQUAKE_SOURCE_IDS);
+    const unique = [];
+    for (const entry of value) {
+        if (typeof entry !== 'string')
+            continue;
+        if (!known.has(entry))
+            continue;
+        if (unique.includes(entry))
+            continue;
+        unique.push(entry);
+    }
+    if (unique.length === 0) {
+        return DEFAULT_EARTHQUAKE_CONFIG.sources;
+    }
+    return Object.freeze(unique);
+}
+const MAX_CENC_URLS = 5;
+function resolveCencUrls(value) {
+    if (!Array.isArray(value)) {
+        return DEFAULT_EARTHQUAKE_CONFIG.cencUrls;
+    }
+    const urls = [];
+    for (const entry of value) {
+        if (typeof entry !== 'string')
+            continue;
+        const trimmed = entry.trim();
+        if (!trimmed.startsWith('https://'))
+            continue;
+        if (urls.includes(trimmed))
+            continue;
+        urls.push(trimmed);
+    }
+    if (urls.length === 0) {
+        return DEFAULT_EARTHQUAKE_CONFIG.cencUrls;
+    }
+    return Object.freeze(urls.slice(0, MAX_CENC_URLS));
+}
+function resolveUsgsFeed(value) {
+    const known = new Set(USGS_FEEDS);
+    if (typeof value === 'string' && known.has(value)) {
+        return value;
+    }
+    return DEFAULT_EARTHQUAKE_CONFIG.usgsFeed;
+}
+function resolveString(value, fallback) {
+    if (typeof value !== 'string')
+        return fallback;
+    const trimmed = value.trim();
+    return trimmed || fallback;
+}
+/** Throws when the configured time zone is unknown to the runtime's Intl data. */
+export function assertEarthquakeTimezone(timezone) {
+    try {
+        new Intl.DateTimeFormat('zh-CN', { timeZone: timezone });
+    }
+    catch {
+        throw new Error(`地震插件 timezone 无效：${timezone}（需要 IANA 时区，例如 Asia/Shanghai）`);
+    }
+}
+export function resolveEarthquakeConfig(raw) {
+    const input = (raw !== null && typeof raw === 'object' ? raw : {});
+    const defaults = DEFAULT_EARTHQUAKE_CONFIG;
+    const retryBaseDelayMs = clampNumber(input.retryBaseDelayMs, defaults.retryBaseDelayMs, 100, 10_000);
+    const retryMaxDelayMs = clampNumber(input.retryMaxDelayMs, defaults.retryMaxDelayMs, 1_000, 120_000);
+    return Object.freeze({
+        sources: resolveSources(input.sources),
+        cencUrls: resolveCencUrls(input.cencUrls),
+        usgsFeed: resolveUsgsFeed(input.usgsFeed),
+        pollCron: resolveString(input.pollCron, defaults.pollCron),
+        timezone: resolveString(input.timezone, defaults.timezone),
+        requestTimeoutMs: clampNumber(input.requestTimeoutMs, defaults.requestTimeoutMs, 1_000, 60_000),
+        maxRetries: Math.round(clampNumber(input.maxRetries, defaults.maxRetries, 0, 5)),
+        retryBaseDelayMs,
+        retryMaxDelayMs: Math.max(retryBaseDelayMs, retryMaxDelayMs),
+        defaultMinMagnitude: clampNumber(input.defaultMinMagnitude, defaults.defaultMinMagnitude, 0, 10),
+        queryMinMagnitude: clampNumber(input.queryMinMagnitude, defaults.queryMinMagnitude, 0, 10),
+        queryLimit: Math.round(clampNumber(input.queryLimit, defaults.queryLimit, 1, 20)),
+        maxEventAgeMinutes: clampNumber(input.maxEventAgeMinutes, defaults.maxEventAgeMinutes, 5, 1_440),
+        pushLimit: Math.round(clampNumber(input.pushLimit, defaults.pushLimit, 1, 60)),
+        pushWindowMinutes: clampNumber(input.pushWindowMinutes, defaults.pushWindowMinutes, 1, 1_440),
+        maxEventsPerMessage: Math.round(clampNumber(input.maxEventsPerMessage, defaults.maxEventsPerMessage, 1, 10)),
+        maxSubscriptions: Math.round(clampNumber(input.maxSubscriptions, defaults.maxSubscriptions, 1, 1_000)),
+    });
+}
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/lib/conversation.d.ts

@@ -0,0 +1,14 @@
+import type { ConversationKind } from './subscriptions.js';
+export interface ConversationTarget {
+    readonly adapter: string;
+    readonly endpointKey: string;
+    readonly conversationKind: ConversationKind;
+    readonly conversationId: string;
+    readonly senderId: string;
+}
+export declare const CONVERSATION_REQUIRED_MESSAGE = "\u8BF7\u5728\u673A\u5668\u4EBA\u79C1\u804A\u3001\u7FA4\u804A\u6216\u9891\u9053\u4E2D\u4F7F\u7528\u6B64\u547D\u4EE4";
+export declare const THREAD_UNSUPPORTED_MESSAGE = "\u6682\u4E0D\u652F\u6301\u5728\u8BDD\u9898\uFF0F\u5B50\u9891\u9053\u5185\u8BA2\u9605\uFF0C\u8BF7\u5728\u4E3B\u4F1A\u8BDD\u4E2D\u4F7F\u7528";
+export declare function conversationError(input: unknown): string;
+/** Returns null when the input has no complete, un-threaded conversation address. */
+export declare function extractConversation(input: unknown): ConversationTarget | null;
+//# sourceMappingURL=conversation.d.ts.map

package/lib/conversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,6BAA6B,uHAAwB,CAAC;AACnE,eAAO,MAAM,0BAA0B,+IAA4B,CAAC;AAYpE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGxD;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAuB7E"}

package/lib/conversation.js

@@ -0,0 +1,54 @@
+/**
+ * Extracts a push destination from the public Message fields of a command input.
+ * Platform-agnostic: only adapter name, endpoint, conversation kind/id and sender id.
+ */
+import { isRecord } from './sources/parse-helpers.js';
+export const CONVERSATION_REQUIRED_MESSAGE = '请在机器人私聊、群聊或频道中使用此命令';
+export const THREAD_UNSUPPORTED_MESSAGE = '暂不支持在话题／子频道内订阅，请在主会话中使用';
+function isIdentifier(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isThreaded(input) {
+    const conversation = input.conversation;
+    if (!isRecord(conversation))
+        return false;
+    return conversation.parent !== undefined || conversation.threadId !== undefined;
+}
+export function conversationError(input) {
+    if (isRecord(input) && isThreaded(input))
+        return THREAD_UNSUPPORTED_MESSAGE;
+    return CONVERSATION_REQUIRED_MESSAGE;
+}
+/** Returns null when the input has no complete, un-threaded conversation address. */
+export function extractConversation(input) {
+    if (!isRecord(input))
+        return null;
+    if (isThreaded(input))
+        return null;
+    const conversation = input.conversation;
+    if (!isRecord(conversation))
+        return null;
+    const kind = conversation.kind;
+    if (kind !== 'private' && kind !== 'group' && kind !== 'channel')
+        return null;
+    // Same precedence as core: explicit message fields, then the conversation's endpoint.
+    const endpoint = isRecord(conversation.endpoint) ? conversation.endpoint : {};
+    const adapter = isIdentifier(input.clientAdapter) ? input.clientAdapter : endpoint.adapter;
+    const endpointKey = isIdentifier(input.endpointId) ? input.endpointId : endpoint.id;
+    if (!isIdentifier(adapter))
+        return null;
+    if (!isIdentifier(endpointKey))
+        return null;
+    if (!isIdentifier(conversation.id))
+        return null;
+    const sender = input.sender;
+    const senderId = isRecord(sender) && isIdentifier(sender.id) ? sender.id : '';
+    return {
+        adapter,
+        endpointKey,
+        conversationKind: kind,
+        conversationId: conversation.id,
+        senderId,
+    };
+}
+//# sourceMappingURL=conversation.js.map

package/lib/conversation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.js","sourceRoot":"","sources":["../src/conversation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAWtD,MAAM,CAAC,MAAM,6BAA6B,GAAG,qBAAqB,CAAC;AACnE,MAAM,CAAC,MAAM,0BAA0B,GAAG,yBAAyB,CAAC;AAEpE,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,UAAU,CAAC,KAA8B;IAChD,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IACxC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,YAAY,CAAC,MAAM,KAAK,SAAS,IAAI,YAAY,CAAC,QAAQ,KAAK,SAAS,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,0BAA0B,CAAC;IAC5E,OAAO,6BAA6B,CAAC;AACvC,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IACxC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC;IAC/B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC9E,sFAAsF;IACtF,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;IAC3F,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;IACpF,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,OAAO;QACL,OAAO;QACP,WAAW;QACX,gBAAgB,EAAE,IAAI;QACtB,cAAc,EAAE,YAAY,CAAC,EAAE;QAC/B,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/lib/dedupe.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Cross-source de-duplication.
+ *
+ * CENC and USGS report the same physical event with different ids, slightly
+ * different origin times, epicentres and magnitude types (Ms vs Mw). Two reports
+ * are the same event when all three tolerances hold:
+ *
+ * - origin time within `timeToleranceMs`   (default 60 s)
+ * - epicentres within `distanceToleranceKm` (default 100 km, great-circle)
+ * - magnitudes within `magnitudeTolerance`  (default 1.0; CENC M vs USGS mb often differ by ~1)
+ *
+ * Reports from the same source match when their ids match, or when origin
+ * times are within `sameSourceTimeToleranceMs` (default 5 s) and epicentres
+ * within `sameSourceDistanceKm` (default 50 km). The second rule covers CENC
+ * mirrors that assign different ids to one event, and revised reports.
+ */
+import type { EarthquakeSourceId } from './config.js';
+import type { EarthquakeEvent, SourceEarthquake } from './types.js';
+export interface DedupeTolerance {
+    readonly timeToleranceMs: number;
+    readonly distanceToleranceKm: number;
+    readonly magnitudeTolerance: number;
+    readonly sameSourceTimeToleranceMs: number;
+    readonly sameSourceDistanceKm: number;
+}
+export declare const DEFAULT_DEDUPE_TOLERANCE: DedupeTolerance;
+/** Great-circle distance (haversine) in kilometres. */
+export declare function distanceKm(a: {
+    readonly latitude: number;
+    readonly longitude: number;
+}, b: {
+    readonly latitude: number;
+    readonly longitude: number;
+}): number;
+/** True when two reports describe the same physical event. */
+export declare function isSameEvent(a: SourceEarthquake, b: SourceEarthquake, tolerance?: DedupeTolerance): boolean;
+/**
+ * Merges reports into events. The primary report of each event is the one from
+ * the most preferred source. Output is sorted newest first.
+ */
+export declare function mergeReports(reports: readonly SourceEarthquake[], preference: readonly EarthquakeSourceId[], tolerance?: DedupeTolerance): EarthquakeEvent[];
+/**
+ * Remembers events that were already announced so the poller pushes each
+ * physical event once, even when the second source reports it minutes later.
+ * Bounded by count and age.
+ */
+export declare class SeenEventLog {
+    #private;
+    constructor(options?: {
+        readonly maxEntries?: number;
+        readonly maxAgeMs?: number;
+        readonly tolerance?: DedupeTolerance;
+    });
+    get size(): number;
+    has(event: EarthquakeEvent): boolean;
+    /** Records every report of the event so later reports from either source match. */
+    add(event: EarthquakeEvent): void;
+    prune(now: number): void;
+}
+//# sourceMappingURL=dedupe.d.ts.map

package/lib/dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../src/dedupe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED,eAAO,MAAM,wBAAwB,EAAE,eAMrC,CAAC;AAQH,uDAAuD;AACvD,wBAAgB,UAAU,CACxB,CAAC,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAC5D,CAAC,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC3D,MAAM,CAQR;AAED,8DAA8D;AAC9D,wBAAgB,WAAW,CACzB,CAAC,EAAE,gBAAgB,EACnB,CAAC,EAAE,gBAAgB,EACnB,SAAS,GAAE,eAA0C,GACpD,OAAO,CAST;AAOD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,UAAU,EAAE,SAAS,kBAAkB,EAAE,EACzC,SAAS,GAAE,eAA0C,GACpD,eAAe,EAAE,CAiCnB;AAED;;;;GAIG;AACH,qBAAa,YAAY;;gBAMX,OAAO,GAAE;QACnB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;KACjC;IAMN,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO;IAIpC,mFAAmF;IACnF,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAOjC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAWzB"}