@johnny-joster/n9e-plugin 1.0.0

package/index.ts

@@ -0,0 +1,53 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  activeAlertsToolInputSchema,
+  activeAlertsToolHandler
+} from "./src/tools/active-alerts.ts";
+import {
+  historicalAlertsToolInputSchema,
+  historicalAlertsToolHandler
+} from "./src/tools/historical-alerts.ts";
+import {
+  alertRulesToolInputSchema,
+  alertRulesToolHandler
+} from "./src/tools/alert-rules.ts";
+import {
+  alertMutesToolInputSchema,
+  alertMutesToolHandler
+} from "./src/tools/alert-mutes.ts";
+
+export default function(api: OpenClawPluginApi) {
+  // Register tool: Query active alerts
+  api.registerTool({
+    name: "n9e_query_active_alerts",
+    description: "查询夜莺平台当前活跃的告警事件。支持按严重级别(1=严重,2=警告,3=提示)、规则名称筛选。用于回答\"当前有哪些告警\"、\"最近的告警\"、\"有没有严重告警\"等问题。",
+    inputSchema: activeAlertsToolInputSchema,
+    handler: activeAlertsToolHandler
+  });
+
+  // Register tool: Query historical alerts
+  api.registerTool({
+    name: "n9e_query_historical_alerts",
+    description: "查询夜莺平台历史告警事件。支持按时间范围、严重级别、规则名称筛选。用于回答\"昨天有哪些告警\"、\"过去一周的告警趋势\"、\"历史告警记录\"等问题。",
+    inputSchema: historicalAlertsToolInputSchema,
+    handler: historicalAlertsToolHandler
+  });
+
+  // Register tool: Query alert rules
+  api.registerTool({
+    name: "n9e_query_alert_rules",
+    description: "查询夜莺平台配置的告警规则。支持按规则名称、数据源、启用状态筛选。用于回答\"有哪些告警规则\"、\"CPU相关的规则配置\"、\"查看内存监控规则\"等问题。",
+    inputSchema: alertRulesToolInputSchema,
+    handler: alertRulesToolHandler
+  });
+
+  // Register tool: Query alert mutes
+  api.registerTool({
+    name: "n9e_query_alert_mutes",
+    description: "查询夜莺平台告警屏蔽配置。用于回答\"哪些告警被屏蔽了\"、\"查看告警屏蔽规则\"、\"为什么没有收到告警\"等问题。",
+    inputSchema: alertMutesToolInputSchema,
+    handler: alertMutesToolHandler
+  });
+
+  api.logger.info("N9e plugin loaded successfully");
+}

package/openclaw.plugin.json

@@ -0,0 +1,41 @@
+{
+  "id": "n9e-plugin",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiBaseUrl": {
+        "type": "string",
+        "format": "uri",
+        "description": "夜莺API基础地址"
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "API访问密钥"
+      },
+      "timeout": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 120000,
+        "default": 30000,
+        "description": "请求超时时间(毫秒)"
+      }
+    },
+    "required": ["apiBaseUrl", "apiKey"]
+  },
+  "uiHints": {
+    "apiBaseUrl": {
+      "label": "API基础地址",
+      "placeholder": "https://n9e-dev.inner.youdao.com/api/n9e"
+    },
+    "apiKey": {
+      "label": "API密钥",
+      "sensitive": true,
+      "placeholder": "输入您的API密钥"
+    },
+    "timeout": {
+      "label": "超时时间(毫秒)",
+      "placeholder": "30000"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@johnny-joster/n9e-plugin",
+  "version": "1.0.0",
+  "description": "Nightingale alert platform query plugin for OpenClaw",
+  "type": "module",
+  "main": "index.ts",
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "scripts": {
+    "dev": "openclaw plugins install -l .",
+    "test": "echo \"No tests yet\""
+  },
+  "keywords": ["openclaw", "plugin", "nightingale", "n9e", "alerts"],
+  "author": "Youdao",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  }
+}

package/skills/query-active-alerts/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: query-active-alerts
+description: 查询夜莺平台当前活跃的告警事件
+---
+
+# 查询活跃告警
+
+## 何时使用
+
+当用户询问当前系统告警状态时使用此工具。典型场景包括:
+
+- 用户询问"当前有哪些告警"、"最近的告警"、"帮我查一下告警"
+- 用户询问特定严重级别的告警:"有没有严重告警"、"warning级别的告警"、"严重级别的问题"
+- 用户询问特定规则的告警:"CPU相关的告警有哪些"、"内存告警"
+- 用户想了解当前系统健康状态
+
+## 使用方法
+
+调用 `n9e_query_active_alerts` 工具,根据用户意图填充参数:
+
+### 参数说明
+
+- **severity** (可选): 严重级别筛选
+  - 1 = 严重 (critical)
+  - 2 = 警告 (warning)
+  - 3 = 提示 (info)
+- **rule_name** (可选): 从用户消息中提取的规则名称关键词,支持模糊匹配
+- **query** (可选): 通用搜索关键词
+- **limit** (可选): 返回数量,默认50条
+
+### 调用示例
+
+```json
+// 查询所有活跃告警
+{
+  "limit": 10
+}
+
+// 查询严重级别告警
+{
+  "severity": 1,
+  "limit": 20
+}
+
+// 查询CPU相关告警
+{
+  "rule_name": "CPU",
+  "limit": 10
+}
+```
+
+## 返回数据结构
+
+工具返回JSON格式,包含两部分:
+
+### summary 摘要
+- total: 总告警数
+- showing: 当前显示数量
+- severity_distribution: 各严重级别分布统计
+
+### alerts 告警列表
+每条告警包含:
+- id: 告警事件ID
+- rule_name: 触发的规则名称
+- severity: 严重级别(数字)
+- severity_label: 严重级别(中文标签)
+- trigger_time: 触发时间(格式化)
+- target_ident: 目标标识(如主机名)
+- trigger_value: 触发值
+- tags: 标签信息(对象)
+- rule_note: 规则说明
+- group_name: 所属业务组
+
+## 如何回答用户
+
+1. **总结关键信息**
+   - 首先说明总共有多少条活跃告警
+   - 按严重级别分类汇总:"其中X条严重、Y条警告、Z条提示"
+
+2. **重点展示严重告警**
+   - 优先列出严重级别(severity=1)的告警
+   - 每条告警说明: 规则名称、触发时间、影响目标
+
+3. **提供建议**
+   - 如果结果很多,建议用户缩小范围:"可以通过严重级别或规则名称进一步筛选"
+   - 如果没有结果,确认:"当前没有活跃告警"
+
+## 使用示例
+
+### 示例 1: 查询所有告警
+
+**用户**: "查一下最近的告警"
+
+**操作**: 调用 `n9e_query_active_alerts({ limit: 10 })`
+
+**回答模板**:
+> 当前有5条活跃告警,其中2条严重级别、3条警告级别。
+>
+> 严重告警:
+> 1. **CPU使用率过高** - 触发时间: 2026-02-12 14:30:00, 影响主机: server-01
+> 2. **内存不足** - 触发时间: 2026-02-12 14:25:00, 影响主机: server-02
+>
+> 警告告警:
+> 1. **磁盘空间不足** - 触发时间: 2026-02-12 14:20:00, 影响主机: server-03
+> ...
+
+### 示例 2: 查询严重告警
+
+**用户**: "有严重级别的告警吗"
+
+**操作**: 调用 `n9e_query_active_alerts({ severity: 1 })`
+
+**回答模板**:
+> 有2条严重告警:
+> 1. **CPU使用率过高** (server-01) - 触发于 2026-02-12 14:30:00, 当前CPU使用率: 95%
+> 2. **内存不足** (server-02) - 触发于 2026-02-12 14:25:00, 可用内存: 512MB
+
+### 示例 3: 查询特定规则告警
+
+**用户**: "CPU相关的告警有哪些"
+
+**操作**: 调用 `n9e_query_active_alerts({ rule_name: "CPU" })`
+
+**回答模板**:
+> 找到3条CPU相关的活跃告警:
+> 1. **CPU使用率过高** - server-01, 触发时间: 14:30, 当前值: 95%
+> 2. **CPU负载过高** - server-03, 触发时间: 14:15, 当前值: 8.5
+> 3. **CPU温度异常** - server-04, 触发时间: 14:10, 当前值: 85°C
+
+### 示例 4: 无告警情况
+
+**用户**: "有告警吗"
+
+**操作**: 调用 `n9e_query_active_alerts({})`
+
+**回答模板**:
+> 当前没有活跃告警,系统运行正常✅
+
+## 注意事项
+
+1. **时间格式**: 返回数据中的时间已格式化为北京时间,直接使用即可
+2. **数量限制**: 如果total > showing,提醒用户:"显示前N条,共M条结果"
+3. **标签信息**: tags字段已解析为对象,可以提取关键标签展示
+4. **错误处理**: 如果工具返回错误,向用户说明错误原因并建议检查配置

package/skills/query-alert-mutes/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: query-alert-mutes
+description: 查询夜莺平台告警屏蔽配置
+---
+
+# 查询告警屏蔽
+
+## 何时使用
+
+当用户想了解哪些告警被屏蔽或为什么没收到告警时使用。典型场景:
+
+- "哪些告警被屏蔽了"
+- "查看告警屏蔽规则"
+- "为什么没有收到告警"
+- "有屏蔽规则吗"
+- "维护窗口期的屏蔽配置"
+
+## 使用方法
+
+调用 `n9e_query_alert_mutes` 工具查询屏蔽配置。
+
+### 参数说明
+
+- **query** (可选): 搜索关键词,在cause(原因)和tags中搜索
+- **limit** (可选): 返回数量,默认50条
+
+### 调用示例
+
+```json
+// 查询所有屏蔽规则
+{
+  "limit": 50
+}
+
+// 搜索维护相关的屏蔽
+{
+  "query": "维护"
+}
+
+// 搜索特定主机的屏蔽
+{
+  "query": "server-01"
+}
+```
+
+## 返回数据结构
+
+### summary 摘要
+- total: 总屏蔽规则数
+- showing: 当前显示数量
+- active_count: 生效中的规则数
+- disabled_count: 已禁用的规则数
+- past_count: 已过期的规则数
+- future_count: 未生效的规则数
+
+### mutes 屏蔽规则列表
+每条规则包含:
+- id: 屏蔽规则ID
+- cause: 屏蔽原因(重要!)
+- tags: 匹配标签(对象)
+- status: 状态("生效中"/"已禁用"/"已过期"/"未生效")
+- disabled: 是否禁用(布尔)
+- begin_time: 生效开始时间
+- end_time: 生效结束时间
+- group_id: 业务组ID
+- cluster: 集群名称
+- created_at / created_by: 创建信息
+- updated_at / updated_by: 更新信息
+
+## 状态说明
+
+屏蔽规则有4种状态:
+1. **生效中**: disabled=0 且当前时间在 [begin_time, end_time] 内
+2. **已禁用**: disabled=1
+3. **已过期**: end_time < 当前时间
+4. **未生效**: begin_time > 当前时间
+
+## 如何回答用户
+
+1. **总结屏蔽状态**
+   - 有多少条规则、多少生效中、多少已过期
+
+2. **重点展示生效中的规则**
+   - 屏蔽原因
+   - 匹配的标签范围
+   - 生效时间范围
+
+3. **解释为什么没收到告警**
+   - 如果有匹配的屏蔽规则,说明原因
+   - 提示屏蔽的时间范围
+
+## 使用示例
+
+### 示例 1: 查询所有屏蔽规则
+
+**用户**: "哪些告警被屏蔽了"
+
+**操作**: 调用 `n9e_query_alert_mutes({})`
+
+**回答模板**:
+> 当前共有5条告警屏蔽规则:
+> - 生效中: 2条
+> - 已过期: 2条
+> - 未生效: 1条
+>
+> **生效中的屏蔽规则:**
+>
+> 1. **机房维护窗口**
+>    - 屏蔽范围: datacenter=A, 所有告警
+>    - 生效时间: 2026-02-12 02:00 - 2026-02-12 06:00
+>    - 原因: 机房设备升级维护
+>
+> 2. **测试环境屏蔽**
+>    - 屏蔽范围: env=test, 所有告警
+>    - 生效时间: 2026-02-01 00:00 - 2026-03-01 00:00
+>    - 原因: 测试环境告警不需要通知
+
+### 示例 2: 为什么没收到告警
+
+**用户**: "为什么server-01的告警没有收到通知"
+
+**操作**: 调用 `n9e_query_alert_mutes({ query: "server-01" })`
+
+**回答模板**:
+> 找到1条相关的屏蔽规则:
+>
+> **server-01维护屏蔽** (生效中)
+> - 屏蔽范围: host=server-01
+> - 生效时间: 2026-02-12 14:00 - 2026-02-12 18:00
+> - 原因: 服务器系统升级
+> - 创建人: ops-admin, 创建时间: 2026-02-12 13:50
+>
+> 这条屏蔽规则导致server-01的所有告警都不会发送通知,预计18:00后恢复通知。
+
+### 示例 3: 查询维护相关屏蔽
+
+**用户**: "查看维护窗口期的屏蔽配置"
+
+**操作**: 调用 `n9e_query_alert_mutes({ query: "维护" })`
+
+**回答模板**:
+> 找到3条维护相关的屏蔽规则:
+>
+> **1. 机房维护窗口** (生效中)
+> - 范围: datacenter=A
+> - 时间: 2026-02-12 02:00 - 06:00
+>
+> **2. 数据库维护** (已过期)
+> - 范围: service=database
+> - 时间: 2026-02-10 22:00 - 2026-02-11 02:00
+> - 状态: 已结束
+>
+> **3. 网络设备维护** (未生效)
+> - 范围: device_type=switch
+> - 时间: 2026-02-15 01:00 - 05:00
+> - 状态: 计划中
+
+### 示例 4: 没有屏蔽规则
+
+**用户**: "有屏蔽规则吗"
+
+**操作**: 调用 `n9e_query_alert_mutes({})`
+
+**回答模板**:
+> 当前没有配置告警屏蔽规则,所有告警都会正常发送通知。
+
+## 注意事项
+
+1. **时间范围**: 明确告知用户屏蔽的开始和结束时间
+2. **标签匹配**: 解释tags字段,说明哪些告警会被匹配
+3. **过期清理**: 提示已过期的规则可以清理
+4. **状态区分**: 清楚区分"生效中"、"已过期"、"未生效"、"已禁用"
+5. **原因说明**: cause字段很重要,帮助用户理解为什么要屏蔽

package/skills/query-alert-rules/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: query-alert-rules
+description: 查询夜莺平台配置的告警规则
+---
+
+# 查询告警规则
+
+## 何时使用
+
+当用户想了解系统配置的告警规则时使用。典型场景:
+
+- "有哪些告警规则"
+- "CPU相关的规则配置"
+- "查看内存监控规则"
+- "这个规则是怎么配置的"
+- "有多少告警规则是禁用的"
+
+## 使用方法
+
+调用 `n9e_query_alert_rules` 工具查询规则配置。
+
+### 参数说明
+
+- **rule_name** (可选): 规则名称关键词,支持模糊匹配
+- **datasource_ids** (可选): 数据源ID列表,筛选特定数据源的规则
+- **disabled** (可选): 规则状态
+  - 0 = 仅查询启用的规则
+  - 1 = 仅查询禁用的规则
+  - 不传 = 查询所有规则
+- **limit** (可选): 返回数量,默认50条
+
+### 调用示例
+
+```json
+// 查询所有规则
+{
+  "limit": 50
+}
+
+// 查询CPU相关规则
+{
+  "rule_name": "CPU"
+}
+
+// 查询禁用的规则
+{
+  "disabled": 1
+}
+
+// 查询特定数据源的规则
+{
+  "datasource_ids": [1, 2, 3]
+}
+```
+
+## 返回数据结构
+
+### summary 摘要
+- total: 总规则数
+- showing: 当前显示数量
+- enabled_count: 启用规则数
+- disabled_count: 禁用规则数
+- severity_distribution: 严重级别分布
+
+### rules 规则列表
+每条规则包含:
+- id: 规则ID
+- name: 规则名称
+- note: 规则说明
+- severity / severity_label: 严重级别
+- disabled: 是否禁用(布尔)
+- status: 状态文本("启用"/"禁用")
+- prom_ql: Prometheus查询语句(核心配置)
+- prom_for_duration: 持续时长(秒)
+- prom_eval_interval: 评估间隔(秒)
+- notify_channels: 通知渠道
+- datasource_ids: 关联的数据源ID列表
+- group_id: 业务组ID
+- cluster: 集群名称
+- created_at / created_by: 创建信息
+- updated_at / updated_by: 更新信息
+
+## 如何回答用户
+
+1. **总结规则概况**
+   - 总数、启用/禁用数量、严重级别分布
+
+2. **展示规则详情**
+   - 规则名称和说明
+   - 核心查询语句(prom_ql)
+   - 触发条件(持续时长)
+   - 通知配置
+
+3. **突出重要信息**
+   - 如果查询禁用规则,说明为什么可能被禁用
+   - 如果查询特定规则,详细解释其配置逻辑
+
+## 使用示例
+
+### 示例 1: 查询所有规则
+
+**用户**: "有哪些告警规则"
+
+**操作**: 调用 `n9e_query_alert_rules({ limit: 20 })`
+
+**回答模板**:
+> 系统共配置了45条告警规则,其中:
+> - 启用: 38条
+> - 禁用: 7条
+>
+> 严重级别分布:
+> - 严重: 15条
+> - 警告: 22条
+> - 提示: 8条
+>
+> 部分规则列表:
+> 1. **CPU使用率过高** (严重) - 当CPU使用率 > 80% 持续5分钟时触发
+> 2. **内存不足** (严重) - 当可用内存 < 10% 持续3分钟时触发
+> 3. **磁盘空间不足** (警告) - 当磁盘使用率 > 85% 持续10分钟时触发
+> ...
+
+### 示例 2: 查询特定规则
+
+**用户**: "CPU相关的规则配置"
+
+**操作**: 调用 `n9e_query_alert_rules({ rule_name: "CPU" })`
+
+**回答模板**:
+> 找到3条CPU相关的告警规则:
+>
+> **1. CPU使用率过高** (严重级别, 已启用)
+> - 查询语句: `100 - (avg by (instance) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80`
+> - 触发条件: 持续5分钟
+> - 评估间隔: 每1分钟
+> - 通知渠道: 企业微信、邮件
+> - 最后更新: 2026-01-15, 更新人: admin
+>
+> **2. CPU负载异常** (警告级别, 已启用)
+> - 查询语句: `node_load5 / count(node_cpu_seconds_total{mode="idle"}) without (cpu, mode) > 4`
+> - 触发条件: 持续3分钟
+> - 评估间隔: 每1分钟
+>
+> **3. CPU温度过高** (提示级别, 已禁用)
+> - 说明: 此规则已被禁用,可能是因为监控项不适用于虚拟化环境
+
+### 示例 3: 查询禁用的规则
+
+**用户**: "有多少告警规则是禁用的"
+
+**操作**: 调用 `n9e_query_alert_rules({ disabled: 1 })`
+
+**回答模板**:
+> 共有7条规则处于禁用状态:
+>
+> 1. **CPU温度过高** - 禁用原因可能: 虚拟化环境不支持
+> 2. **网卡丢包率** - 禁用时间: 2025-12-20
+> 3. **TCP连接数过高** - 禁用时间: 2025-11-15
+> ...
+>
+> 如需启用这些规则,请联系系统管理员。
+
+## 注意事项
+
+1. **PromQL解释**: 对于复杂的Prometheus查询,用通俗语言解释其含义
+2. **时间单位**: prom_for_duration和prom_eval_interval是秒,转换为分钟展示
+3. **规则说明**: 优先使用note字段的说明,如果没有则根据prom_ql推断
+4. **数据源**: 如果有datasource_ids,可以说明规则关联的数据源