@johnny-joster/n9e-plugin 1.0.0

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

@@ -0,0 +1,165 @@
+---
+name: query-historical-alerts
+description: 查询夜莺平台历史告警事件
+---
+
+# 查询历史告警
+
+## 何时使用
+
+当用户询问过去某段时间的告警记录时使用。典型场景:
+
+- "昨天有哪些告警"
+- "过去一周的告警趋势"
+- "上个月的告警统计"
+- "查看历史告警记录"
+- "某个时间段发生了什么告警"
+
+## 使用方法
+
+调用 `n9e_query_historical_alerts` 工具,根据用户提及的时间范围设置参数。
+
+### 参数说明
+
+- **severity** (可选): 严重级别 (1=严重, 2=警告, 3=提示)
+- **rule_name** (可选): 规则名称关键词
+- **stime** (可选): 开始时间戳(秒) - 需要转换相对时间
+- **etime** (可选): 结束时间戳(秒)
+- **limit** (可选): 返回数量,默认50条
+
+### 时间转换
+
+用户常用相对时间表达,需要转换为Unix时间戳(秒):
+
+- "昨天": stime = 昨天0点, etime = 昨天23:59
+- "过去24小时": stime = 当前时间 - 86400秒
+- "本周": stime = 本周一0点, etime = 当前时间
+- "上周": stime = 上周一0点, etime = 上周日23:59
+
+### 调用示例
+
+```json
+// 查询昨天的告警
+{
+  "stime": 1707667200,
+  "etime": 1707753599,
+  "limit": 50
+}
+
+// 查询过去24小时严重告警
+{
+  "severity": 1,
+  "stime": 1707753600,
+  "limit": 20
+}
+
+// 查询CPU相关历史告警
+{
+  "rule_name": "CPU",
+  "stime": 1707580800,
+  "etime": 1707753600
+}
+```
+
+## 返回数据结构
+
+### summary 摘要
+- total: 总告警数
+- showing: 当前显示数量
+- severity_distribution: 严重级别分布
+- recovered_count: 已恢复数量
+- unrecovered_count: 未恢复数量
+
+### alerts 告警列表
+每条告警包含:
+- id: 告警事件ID
+- rule_name: 规则名称
+- severity / severity_label: 严重级别
+- trigger_time: 触发时间
+- recover_time: 恢复时间(可能为null)
+- is_recovered: 是否已恢复(布尔值)
+- target_ident: 目标标识
+- trigger_value: 触发值
+- tags: 标签对象
+- rule_note: 规则说明
+- group_name: 业务组名
+
+## 如何回答用户
+
+1. **时间范围确认**
+   - 明确告知用户查询的时间范围
+
+2. **总结统计**
+   - 总告警数、恢复率、严重级别分布
+
+3. **趋势分析** (如适用)
+   - 哪个时段告警最多
+   - 哪些规则触发最频繁
+   - 恢复时间的长短
+
+4. **重点展示**
+   - 优先展示严重级别高的
+   - 优先展示未恢复的
+
+## 使用示例
+
+### 示例 1: 昨天的告警
+
+**用户**: "昨天有哪些告警"
+
+**操作**: 计算昨天的时间范围并调用工具
+
+**回答模板**:
+> 昨天(2月11日)共有15条告警事件,其中12条已恢复、3条未恢复。
+>
+> 严重级别分布:
+> - 严重: 5条
+> - 警告: 8条
+> - 提示: 2条
+>
+> 未恢复告警:
+> 1. **数据库连接池耗尽** (db-server-01) - 触发于 11日 18:30
+> 2. **磁盘IO异常** (storage-02) - 触发于 11日 20:15
+> 3. **API响应超时** (api-gateway) - 触发于 11日 22:45
+
+### 示例 2: 过去一周趋势
+
+**用户**: "过去一周的告警趋势"
+
+**操作**: 计算过去7天时间范围
+
+**回答模板**:
+> 过去一周(2月5日-2月11日)共有87条告警:
+>
+> 趋势分析:
+> - 2月9日告警最多(23条),主要是网络波动导致
+> - CPU使用率告警占比最高(32条,37%)
+> - 恢复率: 91%(79/87)
+>
+> 最频繁的告警规则:
+> 1. CPU使用率过高 - 32次
+> 2. 内存不足 - 18次
+> 3. 磁盘空间不足 - 15次
+
+### 示例 3: 特定时间段特定规则
+
+**用户**: "上周CPU相关的严重告警有哪些"
+
+**操作**: 设置上周时间范围、severity=1、rule_name="CPU"
+
+**回答模板**:
+> 上周(2月5日-2月11日)共有8条CPU相关的严重告警:
+>
+> 1. **CPU使用率持续过高** (web-01)
+>    - 触发: 2月6日 14:20 → 恢复: 2月6日 15:30 (持续1小时10分)
+>
+> 2. **CPU负载异常** (app-03)
+>    - 触发: 2月7日 09:15 → 恢复: 2月7日 09:45 (持续30分钟)
+> ...
+
+## 注意事项
+
+1. **时间转换准确性**: 确保正确转换用户的时间表达
+2. **恢复状态**: 明确标识哪些告警已恢复、哪些仍在持续
+3. **持续时长**: 如果有恢复时间,可以计算告警持续时长
+4. **数据量提示**: 如果历史数据很多,建议分页或缩小范围

package/src/config-schema.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const n9ePluginConfigSchema = z.object({
+  apiBaseUrl: z.string().url().describe("夜莺API地址"),
+  apiKey: z.string().min(1).describe("API访问密钥"),
+  timeout: z.number().min(1000).max(120000).default(30000).describe("请求超时(毫秒)")
+});
+
+export type N9ePluginConfig = z.infer<typeof n9ePluginConfigSchema>;

package/src/n9e-client.ts

@@ -0,0 +1,251 @@
+import type {
+  N9ePluginConfig,
+  AlertCurEvent,
+  AlertHisEvent,
+  AlertRule,
+  AlertMute,
+  ActiveAlertQuery,
+  HistoricalAlertQuery,
+  AlertRuleQuery,
+  AlertMuteQuery,
+  N9eApiResponse,
+  N9eListResponse
+} from "./types.ts";
+
+export class N9eClient {
+  constructor(private config: N9ePluginConfig) {}
+
+  /**
+   * Generic HTTP request handler
+   */
+  private async request<T>(
+    method: "GET" | "POST" | "PUT" | "DELETE",
+    path: string,
+    params?: Record<string, any>,
+    body?: any
+  ): Promise<T> {
+    const url = new URL(path, this.config.apiBaseUrl);
+
+    // Add query parameters for GET requests
+    if (method === "GET" && params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "X-API-Key": this.config.apiKey
+    };
+
+    const options: RequestInit = {
+      method,
+      headers,
+      signal: AbortSignal.timeout(this.config.timeout)
+    };
+
+    if (body && method !== "GET") {
+      options.body = JSON.stringify(body);
+    }
+
+    try {
+      const response = await fetch(url.toString(), options);
+
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "Unknown error");
+
+        // Map HTTP status to user-friendly messages
+        switch (response.status) {
+          case 401:
+          case 403:
+            throw new Error("认证失败,请检查API Key配置");
+          case 404:
+            throw new Error("未找到指定的资源");
+          case 500:
+            throw new Error("夜莺服务器错误,请稍后重试");
+          default:
+            throw new Error(`HTTP ${response.status}: ${errorText}`);
+        }
+      }
+
+      const data = await response.json();
+      return data as T;
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.name === "AbortError" || error.name === "TimeoutError") {
+          throw new Error("请求超时,请检查网络连接");
+        }
+        if (error.message.includes("fetch failed")) {
+          throw new Error("无法连接到夜莺平台,请检查网络或配置");
+        }
+        throw error;
+      }
+      throw new Error("未知错误");
+    }
+  }
+
+  /**
+   * Query active alerts
+   */
+  async getActiveAlerts(params: ActiveAlertQuery = {}): Promise<{ total: number; list: AlertCurEvent[] }> {
+    const queryParams = {
+      p: params.p || 1,
+      limit: params.limit || 50,
+      ...(params.severity && { severity: params.severity }),
+      ...(params.rule_name && { rule_name: params.rule_name }),
+      ...(params.query && { query: params.query })
+    };
+
+    const response = await this.request<N9eListResponse<AlertCurEvent>>(
+      "GET",
+      "/api/n9e/alert-cur-events/list",
+      queryParams
+    );
+
+    if (response.err) {
+      throw new Error(response.err);
+    }
+
+    return response.dat;
+  }
+
+  /**
+   * Get active alert by ID
+   */
+  async getActiveAlertById(id: number): Promise<AlertCurEvent> {
+    const response = await this.request<N9eApiResponse<AlertCurEvent>>(
+      "GET",
+      `/api/n9e/alert-cur-event/${id}`
+    );
+
+    if (response.err) {
+      throw new Error(response.err);
+    }
+
+    return response.dat;
+  }
+
+  /**
+   * Query historical alerts
+   */
+  async getHistoricalAlerts(params: HistoricalAlertQuery = {}): Promise<{ total: number; list: AlertHisEvent[] }> {
+    const queryParams = {
+      p: params.p || 1,
+      limit: params.limit || 50,
+      ...(params.severity && { severity: params.severity }),
+      ...(params.rule_name && { rule_name: params.rule_name }),
+      ...(params.stime && { stime: params.stime }),
+      ...(params.etime && { etime: params.etime })
+    };
+
+    const response = await this.request<N9eListResponse<AlertHisEvent>>(
+      "GET",
+      "/api/n9e/alert-his-events/list",
+      queryParams
+    );
+
+    if (response.err) {
+      throw new Error(response.err);
+    }
+
+    return response.dat;
+  }
+
+  /**
+   * Get historical alert by ID
+   */
+  async getHistoricalAlertById(id: number): Promise<AlertHisEvent> {
+    const response = await this.request<N9eApiResponse<AlertHisEvent>>(
+      "GET",
+      `/api/n9e/alert-his-event/${id}`
+    );
+
+    if (response.err) {
+      throw new Error(response.err);
+    }
+
+    return response.dat;
+  }
+
+  /**
+   * Query alert rules
+   */
+  async getAlertRules(params: AlertRuleQuery = {}): Promise<{ total: number; list: AlertRule[] }> {
+    const queryParams = {
+      p: params.p || 1,
+      limit: params.limit || 50,
+      ...(params.rule_name && { rule_name: params.rule_name }),
+      ...(params.disabled !== undefined && { disabled: params.disabled }),
+      ...(params.datasource_ids && { datasource_ids: params.datasource_ids.join(",") })
+    };
+
+    const response = await this.request<N9eListResponse<AlertRule>>(
+      "GET",
+      "/api/n9e/alert-rules",
+      queryParams
+    );
+
+    if (response.err) {
+      throw new Error(response.err);
+    }
+
+    return response.dat;
+  }
+
+  /**
+   * Get alert rule by ID
+   */
+  async getAlertRuleById(id: number): Promise<AlertRule> {
+    const response = await this.request<N9eApiResponse<AlertRule>>(
+      "GET",
+      `/api/n9e/alert-rule/${id}`
+    );
+
+    if (response.err) {
+      throw new Error(response.err);
+    }
+
+    return response.dat;
+  }
+
+  /**
+   * Query alert mutes
+   */
+  async getAlertMutes(params: AlertMuteQuery = {}): Promise<{ total: number; list: AlertMute[] }> {
+    const queryParams = {
+      p: params.p || 1,
+      limit: params.limit || 50,
+      ...(params.query && { query: params.query })
+    };
+
+    const response = await this.request<N9eListResponse<AlertMute>>(
+      "GET",
+      "/api/n9e/v1/n9e/alert-mutes",
+      queryParams
+    );
+
+    if (response.err) {
+      throw new Error(response.err);
+    }
+
+    return response.dat;
+  }
+
+  /**
+   * Get alert mute by ID
+   */
+  async getAlertMuteById(id: number): Promise<AlertMute> {
+    const response = await this.request<N9eApiResponse<AlertMute>>(
+      "GET",
+      `/api/n9e/alert-mutes-detail/${id}`
+    );
+
+    if (response.err) {
+      throw new Error(response.err);
+    }
+
+    return response.dat;
+  }
+}

package/src/openclaw-plugin-sdk.d.ts

@@ -0,0 +1,47 @@
+// Type declarations for openclaw/plugin-sdk
+declare module "openclaw/plugin-sdk" {
+  export interface ToolHandler {
+    (input: any, context: ToolContext): Promise<ToolResult>;
+  }
+
+  export interface ToolContext {
+    config: {
+      plugins?: {
+        entries?: {
+          [key: string]: {
+            config?: any;
+          };
+        };
+      };
+    };
+    logger: {
+      info: (...args: any[]) => void;
+      error: (...args: any[]) => void;
+      warn: (...args: any[]) => void;
+      debug: (...args: any[]) => void;
+    };
+  }
+
+  export interface ToolResult {
+    content: Array<{
+      type: string;
+      text: string;
+    }>;
+    isError?: boolean;
+  }
+
+  export interface OpenClawPluginApi {
+    registerTool: (tool: {
+      name: string;
+      description: string;
+      inputSchema: any;
+      handler: ToolHandler;
+    }) => void;
+    logger: {
+      info: (...args: any[]) => void;
+      error: (...args: any[]) => void;
+      warn: (...args: any[]) => void;
+      debug: (...args: any[]) => void;
+    };
+  }
+}

package/src/tools/active-alerts.ts

@@ -0,0 +1,109 @@
+import type { ToolHandler } from "openclaw/plugin-sdk";
+import { N9eClient } from "../n9e-client.ts";
+import { n9ePluginConfigSchema } from "../config-schema.ts";
+import { SEVERITY_LABELS, type AlertSeverity } from "../types.ts";
+
+export const activeAlertsToolInputSchema = {
+  type: "object",
+  properties: {
+    severity: {
+      type: "number",
+      enum: [1, 2, 3],
+      description: "严重级别: 1=严重, 2=警告, 3=提示"
+    },
+    rule_name: {
+      type: "string",
+      description: "按规则名称筛选(支持模糊匹配)"
+    },
+    limit: {
+      type: "number",
+      minimum: 1,
+      maximum: 1000,
+      default: 50,
+      description: "返回数量限制"
+    },
+    query: {
+      type: "string",
+      description: "搜索查询字符串"
+    }
+  }
+} as const;
+
+export const activeAlertsToolHandler: ToolHandler = async (input, context) => {
+  try {
+    // Parse and validate config
+    const rawConfig = context.config.plugins?.entries?.["n9e-plugin"]?.config;
+    if (!rawConfig) {
+      return {
+        content: [{
+          type: "text",
+          text: "❌ 插件配置未找到,请在配置文件中添加n9e-plugin配置"
+        }],
+        isError: true
+      };
+    }
+
+    const config = n9ePluginConfigSchema.parse(rawConfig);
+    const client = new N9eClient(config);
+
+    // Query active alerts
+    const { total, list } = await client.getActiveAlerts({
+      severity: input.severity as AlertSeverity | undefined,
+      rule_name: input.rule_name,
+      limit: input.limit || 50,
+      query: input.query
+    });
+
+    // Format response
+    const alerts = list.map(alert => {
+      const tags = alert.tags ? JSON.parse(alert.tags) : {};
+      return {
+        id: alert.id,
+        rule_name: alert.rule_name,
+        severity: alert.severity,
+        severity_label: SEVERITY_LABELS[alert.severity],
+        trigger_time: new Date(alert.trigger_time * 1000).toLocaleString("zh-CN", {
+          timeZone: "Asia/Shanghai"
+        }),
+        status: "triggered",
+        target_ident: alert.target_ident,
+        trigger_value: alert.trigger_value,
+        tags,
+        rule_note: alert.rule_note,
+        group_name: alert.group_name
+      };
+    });
+
+    // Count by severity
+    const severityCount = alerts.reduce((acc, alert) => {
+      const label = alert.severity_label;
+      acc[label] = (acc[label] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+
+    const result = {
+      summary: {
+        total,
+        showing: alerts.length,
+        severity_distribution: severityCount
+      },
+      alerts
+    };
+
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }]
+    };
+  } catch (error) {
+    context.logger.error("Failed to query active alerts:", error);
+    return {
+      content: [{
+        type: "text",
+        text: `❌ 查询活跃告警失败: ${error instanceof Error ? error.message : String(error)}`
+      }],
+      isError: true
+    };
+  }
+};

package/src/tools/alert-mutes.ts

@@ -0,0 +1,123 @@
+import type { ToolHandler } from "openclaw/plugin-sdk";
+import { N9eClient } from "../n9e-client.ts";
+import { n9ePluginConfigSchema } from "../config-schema.ts";
+
+export const alertMutesToolInputSchema = {
+  type: "object",
+  properties: {
+    query: {
+      type: "string",
+      description: "搜索查询字符串"
+    },
+    limit: {
+      type: "number",
+      minimum: 1,
+      maximum: 1000,
+      default: 50,
+      description: "返回数量限制"
+    }
+  }
+} as const;
+
+export const alertMutesToolHandler: ToolHandler = async (input, context) => {
+  try {
+    // Parse and validate config
+    const rawConfig = context.config.plugins?.entries?.["n9e-plugin"]?.config;
+    if (!rawConfig) {
+      return {
+        content: [{
+          type: "text",
+          text: "❌ 插件配置未找到,请在配置文件中添加n9e-plugin配置"
+        }],
+        isError: true
+      };
+    }
+
+    const config = n9ePluginConfigSchema.parse(rawConfig);
+    const client = new N9eClient(config);
+
+    // Query alert mutes
+    const { total, list } = await client.getAlertMutes({
+      query: input.query,
+      limit: input.limit || 50
+    });
+
+    // Format response
+    const now = Math.floor(Date.now() / 1000);
+    const mutes = list.map(mute => {
+      const tags = mute.tags ? JSON.parse(mute.tags) : {};
+      const isActive = mute.disabled === 0 && mute.btime <= now && mute.etime >= now;
+      const isPast = mute.etime < now;
+      const isFuture = mute.btime > now;
+
+      let status = "未知";
+      if (mute.disabled === 1) {
+        status = "已禁用";
+      } else if (isPast) {
+        status = "已过期";
+      } else if (isFuture) {
+        status = "未生效";
+      } else if (isActive) {
+        status = "生效中";
+      }
+
+      return {
+        id: mute.id,
+        cause: mute.cause,
+        tags,
+        status,
+        disabled: mute.disabled === 1,
+        begin_time: new Date(mute.btime * 1000).toLocaleString("zh-CN", {
+          timeZone: "Asia/Shanghai"
+        }),
+        end_time: new Date(mute.etime * 1000).toLocaleString("zh-CN", {
+          timeZone: "Asia/Shanghai"
+        }),
+        group_id: mute.group_id,
+        cluster: mute.cluster,
+        created_at: new Date(mute.create_at * 1000).toLocaleString("zh-CN", {
+          timeZone: "Asia/Shanghai"
+        }),
+        created_by: mute.create_by,
+        updated_at: new Date(mute.update_at * 1000).toLocaleString("zh-CN", {
+          timeZone: "Asia/Shanghai"
+        }),
+        updated_by: mute.update_by
+      };
+    });
+
+    // Statistics
+    const activeCount = mutes.filter(m => m.status === "生效中").length;
+    const disabledCount = mutes.filter(m => m.disabled).length;
+    const pastCount = mutes.filter(m => m.status === "已过期").length;
+    const futureCount = mutes.filter(m => m.status === "未生效").length;
+
+    const result = {
+      summary: {
+        total,
+        showing: mutes.length,
+        active_count: activeCount,
+        disabled_count: disabledCount,
+        past_count: pastCount,
+        future_count: futureCount
+      },
+      mutes
+    };
+
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }]
+    };
+  } catch (error) {
+    context.logger.error("Failed to query alert mutes:", error);
+    return {
+      content: [{
+        type: "text",
+        text: `❌ 查询告警屏蔽失败: ${error instanceof Error ? error.message : String(error)}`
+      }],
+      isError: true
+    };
+  }
+};