@johnny-joster/n9e-plugin 1.0.0

package/docs/plans/implementation-plan.md

@@ -0,0 +1,2338 @@
+# N9e Plugin Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build a production-ready OpenClaw plugin for Nightingale alert platform integration with natural language query support.
+
+**Architecture:** TypeScript ESM plugin that registers 4 agent tools with N9eClient for API communication. Each tool paired with a skill for agent guidance. All queries are global (cross business group).
+
+**Tech Stack:** TypeScript (ESM), jiti runtime, node-fetch/native fetch, Zod validation, OpenClaw Plugin SDK
+
+---
+
+## Task 1: Project Foundation
+
+**Files:**
+- Create: `package.json`
+- Create: `openclaw.plugin.json`
+- Create: `tsconfig.json`
+- Create: `.gitignore`
+
+**Step 1: Write package.json**
+
+Create the package manifest with proper ESM configuration:
+
+```json
+{
+  "name": "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"
+  }
+}
+```
+
+**Step 2: Write openclaw.plugin.json**
+
+Create the plugin manifest:
+
+```json
+{
+  "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"
+    }
+  }
+}
+```
+
+**Step 3: Write tsconfig.json**
+
+Create TypeScript configuration:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": false,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*", "index.ts"],
+  "exclude": ["node_modules"]
+}
+```
+
+**Step 4: Write .gitignore**
+
+Create git ignore file:
+
+```
+node_modules/
+dist/
+*.log
+.DS_Store
+.env
+.vscode/
+```
+
+**Step 5: Create directory structure**
+
+Run: `mkdir -p src/tools skills`
+
+**Step 6: Verify structure**
+
+Run: `ls -R`
+Expected: Directory tree showing package.json, openclaw.plugin.json, src/, skills/
+
+**Step 7: Commit**
+
+```bash
+git init
+git add package.json openclaw.plugin.json tsconfig.json .gitignore
+git commit -m "feat: project foundation and configuration
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 2: Type Definitions
+
+**Files:**
+- Create: `src/types.ts`
+- Create: `src/config-schema.ts`
+
+**Step 1: Write src/types.ts**
+
+Define all TypeScript interfaces matching N9e API:
+
+```typescript
+// Configuration types
+export interface N9ePluginConfig {
+  apiBaseUrl: string;
+  apiKey: string;
+  timeout: number;
+}
+
+// Alert severity mapping
+export type AlertSeverity = 1 | 2 | 3;  // 1=严重, 2=警告, 3=提示
+
+export const SEVERITY_LABELS: Record<AlertSeverity, string> = {
+  1: "严重",
+  2: "警告",
+  3: "提示"
+};
+
+// Active alert (current event)
+export interface AlertCurEvent {
+  id: number;
+  cluster: string;
+  group_id: number;
+  group_name?: string;
+  hash: string;
+  rule_id: number;
+  rule_name: string;
+  rule_note: string;
+  severity: AlertSeverity;
+  prom_for_duration: number;
+  prom_ql: string;
+  prom_eval_interval: number;
+  callbacks: string;
+  runbook_url?: string;
+  notify_recovered: number;
+  notify_channels: string;
+  notify_groups: string;
+  notify_repeat_step: number;
+  notify_max_number: number;
+  recover_duration: number;
+  created_at: number;
+  updated_at: number;
+  tags: string;
+  target_ident: string;
+  target_note: string;
+  first_trigger_time?: number;
+  trigger_time: number;
+  trigger_value: string;
+  annotations?: string;
+  rule_config?: string;
+}
+
+// Historical alert event
+export interface AlertHisEvent {
+  id: number;
+  is_recovered: number;
+  cluster: string;
+  group_id: number;
+  group_name?: string;
+  hash: string;
+  rule_id: number;
+  rule_name: string;
+  rule_note: string;
+  severity: AlertSeverity;
+  prom_for_duration: number;
+  prom_ql: string;
+  prom_eval_interval: number;
+  callbacks: string;
+  runbook_url?: string;
+  notify_recovered: number;
+  notify_channels: string;
+  notify_groups: string;
+  notify_repeat_step: number;
+  notify_max_number: number;
+  recover_duration: number;
+  created_at: number;
+  updated_at: number;
+  tags: string;
+  target_ident: string;
+  target_note: string;
+  first_trigger_time?: number;
+  trigger_time: number;
+  trigger_value: string;
+  recover_time?: number;
+  last_eval_time?: number;
+  annotations?: string;
+  rule_config?: string;
+}
+
+// Alert rule
+export interface AlertRule {
+  id: number;
+  group_id: number;
+  cluster: string;
+  name: string;
+  note: string;
+  severity: AlertSeverity;
+  disabled: number;  // 0=enabled, 1=disabled
+  prom_for_duration: number;
+  prom_ql: string;
+  prom_eval_interval: number;
+  enable_stime?: string;
+  enable_etime?: string;
+  enable_days_of_week?: string;
+  enable_in_bg?: number;
+  notify_recovered: number;
+  notify_channels: string;
+  notify_repeat_step: number;
+  notify_max_number: number;
+  recover_duration: number;
+  callbacks: string;
+  runbook_url?: string;
+  append_tags?: string;
+  create_at: number;
+  create_by: string;
+  update_at: number;
+  update_by: string;
+  datasource_ids?: number[];
+  extra_config?: string;
+}
+
+// Alert mute
+export interface AlertMute {
+  id: number;
+  group_id: number;
+  cluster: string;
+  tags: string;
+  cause: string;
+  btime: number;
+  etime: number;
+  disabled: number;  // 0=enabled, 1=disabled
+  create_at: number;
+  create_by: string;
+  update_at: number;
+  update_by: string;
+}
+
+// Query parameters
+export interface ActiveAlertQuery {
+  severity?: AlertSeverity;
+  rule_name?: string;
+  limit?: number;
+  query?: string;
+  p?: number;  // page number
+}
+
+export interface HistoricalAlertQuery {
+  severity?: AlertSeverity;
+  rule_name?: string;
+  stime?: number;  // start timestamp (seconds)
+  etime?: number;  // end timestamp (seconds)
+  limit?: number;
+  p?: number;
+}
+
+export interface AlertRuleQuery {
+  rule_name?: string;
+  datasource_ids?: number[];
+  disabled?: 0 | 1;
+  p?: number;
+  limit?: number;
+}
+
+export interface AlertMuteQuery {
+  query?: string;
+  p?: number;
+  limit?: number;
+}
+
+// API response wrapper
+export interface N9eApiResponse<T> {
+  dat: T;
+  err: string;
+}
+
+export interface N9eListResponse<T> {
+  dat: {
+    list: T[];
+    total: number;
+  };
+  err: string;
+}
+```
+
+**Step 2: Write src/config-schema.ts**
+
+Create Zod schema for configuration validation:
+
+```typescript
+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>;
+```
+
+**Step 3: Verify types compile**
+
+Run: `npx tsc --noEmit`
+Expected: No compilation errors
+
+**Step 4: Commit**
+
+```bash
+git add src/types.ts src/config-schema.ts
+git commit -m "feat: add TypeScript type definitions and config schema
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 3: N9eClient Implementation
+
+**Files:**
+- Create: `src/n9e-client.ts`
+
+**Step 1: Write N9eClient class**
+
+Implement the API client with error handling:
+
+```typescript
+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;
+  }
+}
+```
+
+**Step 2: Verify client compiles**
+
+Run: `npx tsc --noEmit`
+Expected: No compilation errors
+
+**Step 3: Commit**
+
+```bash
+git add src/n9e-client.ts
+git commit -m "feat: implement N9eClient with error handling
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 4: Active Alerts Tool
+
+**Files:**
+- Create: `src/tools/active-alerts.ts`
+
+**Step 1: Write the tool implementation**
+
+```typescript
+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
+    };
+  }
+};
+```
+
+**Step 2: Verify tool compiles**
+
+Run: `npx tsc --noEmit`
+Expected: No compilation errors
+
+**Step 3: Commit**
+
+```bash
+git add src/tools/active-alerts.ts
+git commit -m "feat: implement active alerts tool
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 5: Historical Alerts Tool
+
+**Files:**
+- Create: `src/tools/historical-alerts.ts`
+
+**Step 1: Write the tool implementation**
+
+```typescript
+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 historicalAlertsToolInputSchema = {
+  type: "object",
+  properties: {
+    severity: {
+      type: "number",
+      enum: [1, 2, 3],
+      description: "严重级别: 1=严重, 2=警告, 3=提示"
+    },
+    rule_name: {
+      type: "string",
+      description: "按规则名称筛选(支持模糊匹配)"
+    },
+    stime: {
+      type: "number",
+      description: "开始时间戳(秒)"
+    },
+    etime: {
+      type: "number",
+      description: "结束时间戳(秒)"
+    },
+    limit: {
+      type: "number",
+      minimum: 1,
+      maximum: 1000,
+      default: 50,
+      description: "返回数量限制"
+    }
+  }
+} as const;
+
+export const historicalAlertsToolHandler: 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);
+
+    // Validate time range
+    if (input.stime && input.etime && input.stime >= input.etime) {
+      return {
+        content: [{
+          type: "text",
+          text: "❌ 开始时间必须早于结束时间"
+        }],
+        isError: true
+      };
+    }
+
+    // Query historical alerts
+    const { total, list } = await client.getHistoricalAlerts({
+      severity: input.severity as AlertSeverity | undefined,
+      rule_name: input.rule_name,
+      stime: input.stime,
+      etime: input.etime,
+      limit: input.limit || 50
+    });
+
+    // 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"
+        }),
+        recover_time: alert.recover_time
+          ? new Date(alert.recover_time * 1000).toLocaleString("zh-CN", {
+              timeZone: "Asia/Shanghai"
+            })
+          : null,
+        is_recovered: alert.is_recovered === 1,
+        target_ident: alert.target_ident,
+        trigger_value: alert.trigger_value,
+        tags,
+        rule_note: alert.rule_note,
+        group_name: alert.group_name
+      };
+    });
+
+    // Statistics
+    const severityCount = alerts.reduce((acc, alert) => {
+      const label = alert.severity_label;
+      acc[label] = (acc[label] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+
+    const recoveredCount = alerts.filter(a => a.is_recovered).length;
+
+    const result = {
+      summary: {
+        total,
+        showing: alerts.length,
+        severity_distribution: severityCount,
+        recovered_count: recoveredCount,
+        unrecovered_count: alerts.length - recoveredCount
+      },
+      alerts
+    };
+
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }]
+    };
+  } catch (error) {
+    context.logger.error("Failed to query historical alerts:", error);
+    return {
+      content: [{
+        type: "text",
+        text: `❌ 查询历史告警失败: ${error instanceof Error ? error.message : String(error)}`
+      }],
+      isError: true
+    };
+  }
+};
+```
+
+**Step 2: Verify tool compiles**
+
+Run: `npx tsc --noEmit`
+Expected: No compilation errors
+
+**Step 3: Commit**
+
+```bash
+git add src/tools/historical-alerts.ts
+git commit -m "feat: implement historical alerts tool
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 6: Alert Rules Tool
+
+**Files:**
+- Create: `src/tools/alert-rules.ts`
+
+**Step 1: Write the tool implementation**
+
+```typescript
+import type { ToolHandler } from "openclaw/plugin-sdk";
+import { N9eClient } from "../n9e-client.ts";
+import { n9ePluginConfigSchema } from "../config-schema.ts";
+import { SEVERITY_LABELS } from "../types.ts";
+
+export const alertRulesToolInputSchema = {
+  type: "object",
+  properties: {
+    rule_name: {
+      type: "string",
+      description: "按规则名称搜索(支持模糊匹配)"
+    },
+    datasource_ids: {
+      type: "array",
+      items: { type: "number" },
+      description: "数据源ID列表"
+    },
+    disabled: {
+      type: "number",
+      enum: [0, 1],
+      description: "规则状态: 0=启用, 1=禁用"
+    },
+    limit: {
+      type: "number",
+      minimum: 1,
+      maximum: 1000,
+      default: 50,
+      description: "返回数量限制"
+    }
+  }
+} as const;
+
+export const alertRulesToolHandler: 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 rules
+    const { total, list } = await client.getAlertRules({
+      rule_name: input.rule_name,
+      datasource_ids: input.datasource_ids,
+      disabled: input.disabled as 0 | 1 | undefined,
+      limit: input.limit || 50
+    });
+
+    // Format response
+    const rules = list.map(rule => ({
+      id: rule.id,
+      name: rule.name,
+      note: rule.note,
+      severity: rule.severity,
+      severity_label: SEVERITY_LABELS[rule.severity],
+      disabled: rule.disabled === 1,
+      status: rule.disabled === 1 ? "禁用" : "启用",
+      prom_ql: rule.prom_ql,
+      prom_for_duration: rule.prom_for_duration,
+      prom_eval_interval: rule.prom_eval_interval,
+      notify_channels: rule.notify_channels,
+      datasource_ids: rule.datasource_ids,
+      group_id: rule.group_id,
+      cluster: rule.cluster,
+      created_at: new Date(rule.create_at * 1000).toLocaleString("zh-CN", {
+        timeZone: "Asia/Shanghai"
+      }),
+      created_by: rule.create_by,
+      updated_at: new Date(rule.update_at * 1000).toLocaleString("zh-CN", {
+        timeZone: "Asia/Shanghai"
+      }),
+      updated_by: rule.update_by
+    }));
+
+    // Statistics
+    const enabledCount = rules.filter(r => !r.disabled).length;
+    const disabledCount = rules.filter(r => r.disabled).length;
+    const severityCount = rules.reduce((acc, rule) => {
+      const label = rule.severity_label;
+      acc[label] = (acc[label] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+
+    const result = {
+      summary: {
+        total,
+        showing: rules.length,
+        enabled_count: enabledCount,
+        disabled_count: disabledCount,
+        severity_distribution: severityCount
+      },
+      rules
+    };
+
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }]
+    };
+  } catch (error) {
+    context.logger.error("Failed to query alert rules:", error);
+    return {
+      content: [{
+        type: "text",
+        text: `❌ 查询告警规则失败: ${error instanceof Error ? error.message : String(error)}`
+      }],
+      isError: true
+    };
+  }
+};
+```
+
+**Step 2: Verify tool compiles**
+
+Run: `npx tsc --noEmit`
+Expected: No compilation errors
+
+**Step 3: Commit**
+
+```bash
+git add src/tools/alert-rules.ts
+git commit -m "feat: implement alert rules tool
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 7: Alert Mutes Tool
+
+**Files:**
+- Create: `src/tools/alert-mutes.ts`
+
+**Step 1: Write the tool implementation**
+
+```typescript
+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
+    };
+  }
+};
+```
+
+**Step 2: Verify tool compiles**
+
+Run: `npx tsc --noEmit`
+Expected: No compilation errors
+
+**Step 3: Commit**
+
+```bash
+git add src/tools/alert-mutes.ts
+git commit -m "feat: implement alert mutes tool
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 8: Plugin Entry Point
+
+**Files:**
+- Create: `index.ts`
+
+**Step 1: Write plugin entry point**
+
+```typescript
+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");
+}
+```
+
+**Step 2: Verify plugin entry compiles**
+
+Run: `npx tsc --noEmit`
+Expected: No compilation errors
+
+**Step 3: Commit**
+
+```bash
+git add index.ts
+git commit -m "feat: implement plugin entry point with all tools
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 9: Skill - Query Active Alerts
+
+**Files:**
+- Create: `skills/query-active-alerts/SKILL.md`
+
+**Step 1: Write the skill file**
+
+```markdown
+---
+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. **错误处理**: 如果工具返回错误,向用户说明错误原因并建议检查配置
+```
+
+**Step 2: Create directory**
+
+Run: `mkdir -p skills/query-active-alerts`
+
+**Step 3: Commit**
+
+```bash
+git add skills/query-active-alerts/SKILL.md
+git commit -m "feat: add query-active-alerts skill documentation
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 10: Skill - Query Historical Alerts
+
+**Files:**
+- Create: `skills/query-historical-alerts/SKILL.md`
+
+**Step 1: Write the skill file**
+
+```markdown
+---
+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. **数据量提示**: 如果历史数据很多,建议分页或缩小范围
+```
+
+**Step 2: Create directory**
+
+Run: `mkdir -p skills/query-historical-alerts`
+
+**Step 3: Commit**
+
+```bash
+git add skills/query-historical-alerts/SKILL.md
+git commit -m "feat: add query-historical-alerts skill documentation
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 11: Skill - Query Alert Rules
+
+**Files:**
+- Create: `skills/query-alert-rules/SKILL.md`
+
+**Step 1: Write the skill file**
+
+```markdown
+---
+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,可以说明规则关联的数据源
+```
+
+**Step 2: Create directory**
+
+Run: `mkdir -p skills/query-alert-rules`
+
+**Step 3: Commit**
+
+```bash
+git add skills/query-alert-rules/SKILL.md
+git commit -m "feat: add query-alert-rules skill documentation
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 12: Skill - Query Alert Mutes
+
+**Files:**
+- Create: `skills/query-alert-mutes/SKILL.md`
+
+**Step 1: Write the skill file**
+
+```markdown
+---
+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字段很重要,帮助用户理解为什么要屏蔽
+```
+
+**Step 2: Create directory**
+
+Run: `mkdir -p skills/query-alert-mutes`
+
+**Step 3: Commit**
+
+```bash
+git add skills/query-alert-mutes/SKILL.md
+git commit -m "feat: add query-alert-mutes skill documentation
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 13: README Documentation
+
+**Files:**
+- Create: `README.md`
+
+**Step 1: Write README**
+
+```markdown
+# N9e Plugin for OpenClaw
+
+夜莺(Nightingale)告警平台查询插件,支持通过自然语言查询告警事件、历史告警、告警规则和告警屏蔽配置。
+
+## 功能特性
+
+- ✅ 查询当前活跃告警
+- ✅ 查询历史告警记录
+- ✅ 查询告警规则配置
+- ✅ 查询告警屏蔽规则
+- ✅ 自然语言交互
+- ✅ 全局查询(跨所有业务组)
+- ✅ 完善的错误处理
+
+## 快速开始
+
+### 1. 安装插件
+
+```bash
+# 从本地目录安装(开发模式)
+openclaw plugins install -l ./n9e-plugin
+
+# 或从npm安装
+openclaw plugins install @youdao/n9e-plugin
+```
+
+### 2. 配置插件
+
+编辑OpenClaw配置文件,添加以下配置:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "n9e-plugin": {
+        "enabled": true,
+        "config": {
+          "apiBaseUrl": "https://n9e-dev.inner.youdao.com/api/n9e",
+          "apiKey": "your-api-key-here",
+          "timeout": 30000
+        }
+      }
+    }
+  }
+}
+```
+
+### 3. 重启Gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 4. 验证安装
+
+```bash
+openclaw plugins list
+```
+
+## 使用示例
+
+与Agent对话即可使用:
+
+```
+用户: 查一下最近的告警
+→ Agent调用 n9e_query_active_alerts
+→ 返回: 当前有5条活跃告警...
+
+用户: 昨天有哪些告警
+→ Agent调用 n9e_query_historical_alerts
+→ 返回: 昨天共有15条告警...
+
+用户: CPU相关的告警规则
+→ Agent调用 n9e_query_alert_rules
+→ 返回: 找到3条CPU相关规则...
+
+用户: 哪些告警被屏蔽了
+→ Agent调用 n9e_query_alert_mutes
+→ 返回: 当前有2条屏蔽规则...
+```
+
+## API Tools
+
+### 1. n9e_query_active_alerts
+
+查询当前活跃告警。
+
+**参数:**
+- `severity`: 严重级别(1=严重,2=警告,3=提示)
+- `rule_name`: 规则名称(支持模糊匹配)
+- `limit`: 返回数量(默认50)
+- `query`: 搜索关键词
+
+### 2. n9e_query_historical_alerts
+
+查询历史告警记录。
+
+**参数:**
+- `severity`: 严重级别
+- `rule_name`: 规则名称
+- `stime`: 开始时间戳(秒)
+- `etime`: 结束时间戳(秒)
+- `limit`: 返回数量(默认50)
+
+### 3. n9e_query_alert_rules
+
+查询告警规则配置。
+
+**参数:**
+- `rule_name`: 规则名称
+- `datasource_ids`: 数据源ID列表
+- `disabled`: 规则状态(0=启用,1=禁用)
+- `limit`: 返回数量(默认50)
+
+### 4. n9e_query_alert_mutes
+
+查询告警屏蔽规则。
+
+**参数:**
+- `query`: 搜索关键词
+- `limit`: 返回数量(默认50)
+
+## 项目结构
+
+```
+n9e-plugin/
+├── openclaw.plugin.json    # 插件清单
+├── package.json
+├── index.ts                 # 插件入口
+├── src/
+│   ├── config-schema.ts     # Zod配置Schema
+│   ├── n9e-client.ts       # 夜莺API客户端
+│   ├── types.ts            # TypeScript类型定义
+│   └── tools/              # 工具实现
+│       ├── active-alerts.ts
+│       ├── historical-alerts.ts
+│       ├── alert-rules.ts
+│       └── alert-mutes.ts
+└── skills/                  # Agent技能
+    ├── query-active-alerts/
+    ├── query-historical-alerts/
+    ├── query-alert-rules/
+    └── query-alert-mutes/
+```
+
+## 开发
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 链接模式开发
+
+```bash
+npm run dev
+# 等同于: openclaw plugins install -l .
+```
+
+### 类型检查
+
+```bash
+npx tsc --noEmit
+```
+
+## 配置说明
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `apiBaseUrl` | string | ✅ | 夜莺API地址 |
+| `apiKey` | string | ✅ | API访问密钥 |
+| `timeout` | number | ❌ | 请求超时(毫秒),默认30000 |
+
+## 错误处理
+
+| 错误类型 | 提示信息 |
+|---------|---------|
+| 网络错误 | 无法连接到夜莺平台,请检查网络或配置 |
+| 401/403 | 认证失败,请检查API Key配置 |
+| 404 | 未找到指定的资源 |
+| 500 | 夜莺服务器错误,请稍后重试 |
+| 超时 | 请求超时,请检查网络连接 |
+
+## 许可证
+
+MIT
+
+## 作者
+
+Youdao DevOps Team
+```
+
+**Step 2: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: add comprehensive README documentation
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 14: Final Verification
+
+**Step 1: Verify all files exist**
+
+Run: `find . -type f -not -path './node_modules/*' -not -path './.git/*' | sort`
+Expected: Complete file listing matching project structure
+
+**Step 2: Verify TypeScript compilation**
+
+Run: `npx tsc --noEmit`
+Expected: No errors
+
+**Step 3: Verify plugin manifest**
+
+Run: `cat openclaw.plugin.json | head -20`
+Expected: Valid JSON with correct structure
+
+**Step 4: Verify skills directory**
+
+Run: `find skills -name "SKILL.md"`
+Expected: 4 SKILL.md files
+
+**Step 5: Final commit**
+
+```bash
+git add -A
+git commit -m "chore: final verification and cleanup
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+**Step 6: Create summary**
+
+Run: `git log --oneline`
+Expected: All commits listed in chronological order
+
+---
+
+## Execution Handoff
+
+Plan complete and saved to `docs/plans/implementation-plan.md`. Two execution options:
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+**Which approach?**