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

package/package.json

@@ -1,6 +1,108 @@
 {
   "name": "@zhin.js/plugin-earthquake",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Earthquake query and group alert plugin for Zhin.js — CENC + USGS, magnitude/region subscriptions (Plugin Runtime)",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "plugin.js",
+    "schema.json",
+    "commands",
+    "!commands/**/*.ts",
+    "skills",
+    "!skills/**/*.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "zhin",
+    "zhin.js",
+    "bot",
+    "plugin",
+    "earthquake",
+    "地震",
+    "cenc",
+    "usgs",
+    "alert"
+  ],
+  "author": {
+    "name": "lc-cn",
+    "email": "admin@liucl.cn",
+    "url": "https://github.com/lc-cn"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@zhin.js/skill": "1.1.8",
+    "@zhin.js/tool": "1.1.8"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/command": "1.1.9",
+    "@zhin.js/testing": "1.0.5",
+    "zhin.js": "1.1.13"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0",
+    "@zhin.js/command": "^1.1.9",
+    "zhin.js": "^1.1.13"
+  },
+  "peerDependenciesMeta": {
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "plugins/utils/earthquake"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/tool",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc -p tsconfig.check.json",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/utils/earthquake/tests"
+  }
 }

package/plugin.js

@@ -0,0 +1,71 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { databaseHostToken, definePlugin, logger, outboundHostToken, scheduleHostToken, } from 'zhin.js';
+import { assertEarthquakeTimezone, resolveEarthquakeConfig, } from "./lib/config.js";
+import { earthquakeServiceToken } from "./lib/runtime.js";
+import { EarthquakeService } from "./lib/service.js";
+import { createMemoryState, SubscriptionStore } from "./lib/subscriptions.js";
+/**
+ * Plugin Runtime:
+ * - Commands: `地震` query, `地震 订阅` / `地震 退订` / `地震 订阅状态`.
+ * - Agent tool: `recent_earthquakes` (skill `earthquake`).
+ * - DB: subscriptions persist in `databaseHostToken.state` when available; else in memory.
+ * - Outbound + Schedule: when both hosts exist, a cron job polls and pushes alerts.
+ */
+export default definePlugin({
+    name: 'earthquake',
+    metadata: {
+        displayName: '地震速报',
+    },
+    setup(context) {
+        const config = resolveEarthquakeConfig(context.config.get());
+        assertEarthquakeTimezone(config.timezone);
+        let state;
+        if (context.resources.has(databaseHostToken)) {
+            try {
+                state = context.resources.use(databaseHostToken).state;
+            }
+            catch {
+                // No persistent state port: fall back to memory below.
+            }
+        }
+        const store = new SubscriptionStore(state ?? createMemoryState(), {
+            maxSubscriptions: config.maxSubscriptions,
+        });
+        let push;
+        if (context.resources.has(outboundHostToken)) {
+            const outbound = context.resources.use(outboundHostToken);
+            push = async (subscription, content) => {
+                await outbound.send({
+                    adapter: subscription.adapter,
+                    endpointKey: subscription.endpointKey,
+                    conversation: {
+                        kind: subscription.conversationKind,
+                        id: subscription.conversationId,
+                    },
+                    content,
+                });
+            };
+        }
+        const service = new EarthquakeService({
+            config,
+            store,
+            push,
+            logger: { warn: (message) => logger.warn(message) },
+        });
+        context.resources.provide(earthquakeServiceToken, service);
+        context.lifecycle.add(() => service.stop());
+        if (!push || !context.resources.has(scheduleHostToken))
+            return;
+        const schedule = context.resources.use(scheduleHostToken);
+        const dispose = schedule.register({
+            id: 'earthquake/poll',
+            cron: config.pollCron,
+            description: 'Poll CENC/USGS earthquake feeds and push subscription alerts',
+            async execute() {
+                // poll() never throws; failures are logged and the next tick tries again.
+                await service.poll();
+            },
+        });
+        context.lifecycle.add(dispose);
+    },
+});

package/schema.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "sources": {
+      "type": "array",
+      "description": "启用的数据源及优先顺序；合并同一地震时排在前面的数据源提供地点文字，某个数据源失败时由其余数据源兜底",
+      "items": {
+        "type": "string",
+        "enum": [
+          "cenc",
+          "usgs"
+        ]
+      },
+      "minItems": 1,
+      "uniqueItems": true,
+      "default": [
+        "cenc",
+        "usgs"
+      ]
+    },
+    "cencUrls": {
+      "type": "array",
+      "description": "CENC 地震目录地址，按顺序尝试（首个为主源，其余为备用镜像）；仅支持 HTTPS，最多 5 个",
+      "items": {
+        "type": "string",
+        "pattern": "^https://"
+      },
+      "minItems": 1,
+      "maxItems": 5,
+      "uniqueItems": true,
+      "default": [
+        "https://api.wolfx.jp/cenc_eqlist.json",
+        "https://ceic.ac.cn/data/data.json"
+      ]
+    },
+    "usgsFeed": {
+      "type": "string",
+      "description": "USGS GeoJSON 汇总源名称（震级下限_时间范围）",
+      "enum": [
+        "significant_hour",
+        "significant_day",
+        "4.5_hour",
+        "4.5_day",
+        "2.5_hour",
+        "2.5_day",
+        "1.0_hour",
+        "1.0_day"
+      ],
+      "default": "2.5_day"
+    },
+    "pollCron": {
+      "type": "string",
+      "description": "订阅轮询频率（6 段 Cron：秒 分 时 日 月 周）",
+      "default": "0 */2 * * * *"
+    },
+    "timezone": {
+      "type": "string",
+      "description": "显示发震时刻使用的 IANA 时区",
+      "default": "Asia/Shanghai"
+    },
+    "requestTimeoutMs": {
+      "type": "number",
+      "description": "单次 HTTP 请求超时（毫秒）",
+      "default": 10000,
+      "minimum": 1000,
+      "maximum": 60000
+    },
+    "maxRetries": {
+      "type": "number",
+      "description": "网络错误、超时、429 与 5xx 的重试次数（不含首次请求）",
+      "default": 2,
+      "minimum": 0,
+      "maximum": 5,
+      "multipleOf": 1
+    },
+    "retryBaseDelayMs": {
+      "type": "number",
+      "description": "指数退避的首次等待（毫秒），每次重试翻倍并加入随机抖动",
+      "default": 1000,
+      "minimum": 100,
+      "maximum": 10000
+    },
+    "retryMaxDelayMs": {
+      "type": "number",
+      "description": "单次退避或 Retry-After 等待上限（毫秒）；服务端要求更久时本轮放弃并冷却该数据源",
+      "default": 30000,
+      "minimum": 1000,
+      "maximum": 120000
+    },
+    "defaultMinMagnitude": {
+      "type": "number",
+      "description": "订阅未指定震级时使用的最小震级",
+      "default": 5,
+      "minimum": 0,
+      "maximum": 10
+    },
+    "queryMinMagnitude": {
+      "type": "number",
+      "description": "「地震」查询未指定震级时使用的最小震级",
+      "default": 3,
+      "minimum": 0,
+      "maximum": 10
+    },
+    "queryLimit": {
+      "type": "number",
+      "description": "「地震」查询默认列出的条数",
+      "default": 5,
+      "minimum": 1,
+      "maximum": 20,
+      "multipleOf": 1
+    },
+    "maxEventAgeMinutes": {
+      "type": "number",
+      "description": "只推送发震时间在此分钟数以内的地震，避免推送迟到或重放的旧事件",
+      "default": 60,
+      "minimum": 5,
+      "maximum": 1440
+    },
+    "pushLimit": {
+      "type": "number",
+      "description": "每个会话在一个限流窗口内最多推送的消息数",
+      "default": 3,
+      "minimum": 1,
+      "maximum": 60,
+      "multipleOf": 1
+    },
+    "pushWindowMinutes": {
+      "type": "number",
+      "description": "推送限流窗口长度（分钟）",
+      "default": 10,
+      "minimum": 1,
+      "maximum": 1440
+    },
+    "maxEventsPerMessage": {
+      "type": "number",
+      "description": "单条推送消息最多列出的地震数，其余以数量概括",
+      "default": 5,
+      "minimum": 1,
+      "maximum": 10,
+      "multipleOf": 1
+    },
+    "maxSubscriptions": {
+      "type": "number",
+      "description": "本实例所有会话的订阅总数上限（每个会话最多一个订阅）",
+      "default": 100,
+      "minimum": 1,
+      "maximum": 1000,
+      "multipleOf": 1
+    }
+  }
+}

package/skills/earthquake/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: earthquake
+description: >-
+  地震查询能力。当用户询问最近哪里地震、某地是否地震、震级多大或想了解地震速报时使用。
+  数据来自中国地震台网（CENC）与 USGS，合并去重后返回。
+keywords:
+  - earthquake
+  - 地震
+  - 震级
+  - 余震
+  - 地震速报
+tags:
+  - earthquake
+  - realtime
+tools:
+  - recent_earthquakes
+---
+
+# 地震查询技能
+
+## 工具
+
+| 工具 | 用途 | 参数 |
+|------|------|------|
+| `recent_earthquakes` | 查询最近的地震 | `limit`（条数，默认 5）、`minMagnitude`（最小震级，默认 3）、`region`（地区关键词）、`hours`（时间范围，默认 24） |
+
+**Example:**
+```
+用户: 刚才四川是不是地震了？
+→ recent_earthquakes(region="四川", hours=6, minMagnitude=2)
+```
+
+## 注意
+
+- 地区是对地点文字的关键词匹配；`中国` / `国内` 表示中国境内（含台湾）。
+- 回答时说明数据来源与发震时刻的时区；数据源不可用时如实告知，不要编造地震信息。
+- 订阅群推送请引导用户使用聊天命令 `地震 订阅 [最小震级] [地区...]`。

package/skills/earthquake/tools/recent_earthquakes/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { renderRecentEarthquakes } from "../../../../lib/query-text.js";
+import { earthquakeServiceToken } from "../../../../lib/runtime.js";
+export default defineAgentTool({
+    description: '查询最近发生的地震（中国地震台网 CENC 与 USGS 合并去重），可按最小震级、地区关键词和时间范围过滤',
+    inputSchema: z.object({
+        limit: z.number().int().min(1).max(20).optional().describe('返回条数，默认 5'),
+        minMagnitude: z.number().min(0).max(10).optional().describe('最小震级，默认 3'),
+        region: z.string().max(20).optional().describe('地区关键词，如「四川」「日本」「Japan」；「中国」表示国内'),
+        hours: z.number().int().min(1).max(168).optional().describe('时间范围（小时），默认 24'),
+    }),
+    keywords: ['地震', '震级', '余震', '地震速报', 'earthquake', 'quake', 'seismic'],
+    tags: ['地震', '查询', '实时'],
+    async execute({ limit, minMagnitude, region, hours }, context) {
+        return renderRecentEarthquakes(context.use(earthquakeServiceToken), { limit, minMagnitude, region, hours });
+    },
+});