@johnny-joster/n9e-plugin 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx tsc:*)",
+      "Bash(npm install)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,191 @@
+# 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

package/docs/plans/2026-02-12-n9e-plugin-design.md

@@ -0,0 +1,377 @@
+# 夜莺(Nightingale) OpenClaw 插件设计文档
+
+**日期**: 2026-02-12
+**版本**: 1.0
+**状态**: 已批准
+
+## 概述
+
+为 OpenClaw 平台开发一个夜莺告警平台查询插件，支持通过自然语言查询告警事件、历史告警、告警规则和告警屏蔽配置。
+
+## 设计目标
+
+- **自然语言交互**: 用户使用自然语言提问，AI agent 自动选择合适的工具调用
+- **全面覆盖**: 支持活跃告警、历史告警、告警规则、告警屏蔽四大数据类型
+- **全局查询**: 跨所有业务组查询，无需配置特定业务组
+- **简单认证**: 使用静态 API Key (X-API-Key header) 认证
+
+## 架构设计
+
+### 项目结构
+
+```
+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/
+    │   └── SKILL.md
+    ├── query-historical-alerts/
+    │   └── SKILL.md
+    ├── query-alert-rules/
+    │   └── SKILL.md
+    └── query-alert-mutes/
+        └── SKILL.md
+```
+
+### 配置 Schema
+
+```typescript
+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("请求超时(毫秒)")
+});
+```
+
+**配置示例**:
+```json
+{
+  "plugins": {
+    "entries": {
+      "n9e-plugin": {
+        "enabled": true,
+        "config": {
+          "apiBaseUrl": "https://n9e-dev.inner.youdao.com/api/n9e",
+          "apiKey": "your-api-key-here",
+          "timeout": 30000
+        }
+      }
+    }
+  }
+}
+```
+
+## Agent Tools 设计
+
+### 1. n9e_query_active_alerts
+
+**功能**: 查询当前活跃的告警事件
+
+**参数**:
+- `severity` (optional, number): 严重级别 (1=严重, 2=警告, 3=提示)
+- `rule_name` (optional, string): 按规则名称筛选
+- `limit` (optional, number): 返回数量限制 (默认: 50)
+- `query` (optional, string): 搜索查询字符串
+
+**API 端点**: `GET /api/n9e/alert-cur-events/list`
+
+**返回格式**:
+```json
+{
+  "total": 5,
+  "alerts": [
+    {
+      "id": 12345,
+      "rule_name": "CPU使用率过高",
+      "severity": 1,
+      "severity_label": "严重",
+      "trigger_time": "2026-02-12 14:30:00",
+      "status": "triggered",
+      "tags": {"host": "server-01"}
+    }
+  ]
+}
+```
+
+**使用场景**:
+- "查一下最近的告警"
+- "有严重级别的告警吗"
+- "CPU相关的告警有哪些"
+
+### 2. n9e_query_historical_alerts
+
+**功能**: 查询历史告警事件
+
+**参数**:
+- `severity` (optional, number): 严重级别
+- `rule_name` (optional, string): 规则名称
+- `stime` (optional, number): 开始时间戳(秒)
+- `etime` (optional, number): 结束时间戳(秒)
+- `limit` (optional, number): 返回数量限制 (默认: 50)
+
+**API 端点**: `GET /api/n9e/alert-his-events/list`
+
+**使用场景**:
+- "昨天有哪些告警"
+- "过去一周的告警趋势"
+- "查看历史告警记录"
+
+### 3. n9e_query_alert_rules
+
+**功能**: 查询告警规则配置
+
+**参数**:
+- `rule_name` (optional, string): 规则名称搜索
+- `datasource_ids` (optional, array): 数据源ID列表
+- `disabled` (optional, number): 0=启用, 1=禁用
+
+**API 端点**: `GET /api/n9e/alert-rules`
+
+**使用场景**:
+- "有哪些告警规则"
+- "CPU相关的规则配置"
+- "查看内存监控规则"
+
+### 4. n9e_query_alert_mutes
+
+**功能**: 查询告警屏蔽配置
+
+**参数**:
+- `query` (optional, string): 搜索查询
+
+**API 端点**: `GET /api/n9e/v1/n9e/alert-mutes`
+
+**使用场景**:
+- "哪些告警被屏蔽了"
+- "查看告警屏蔽规则"
+- "为什么没有收到告警"
+
+## API 客户端设计
+
+### N9eClient 类
+
+```typescript
+class N9eClient {
+  constructor(private config: N9ePluginConfig) {}
+
+  private async request<T>(
+    method: string,
+    path: string,
+    params?: Record<string, any>
+  ): Promise<T> {
+    // 构建 URL 和查询参数
+    // 添加 X-API-Key header
+    // 处理超时和错误
+    // 返回解析后的 JSON
+  }
+
+  // 活跃告警
+  async getActiveAlerts(params: ActiveAlertQuery): Promise<AlertCurEvent[]>
+  async getActiveAlertById(eid: number): Promise<AlertCurEvent>
+
+  // 历史告警
+  async getHistoricalAlerts(params: HistoricalAlertQuery): Promise<AlertHisEvent[]>
+  async getHistoricalAlertById(eid: number): Promise<AlertHisEvent>
+
+  // 告警规则
+  async getAlertRules(params: AlertRuleQuery): Promise<AlertRule[]>
+  async getAlertRuleById(arid: number): Promise<AlertRule>
+
+  // 告警屏蔽
+  async getAlertMutes(params: AlertMuteQuery): Promise<AlertMute[]>
+}
+```
+
+### 错误处理策略
+
+| 错误类型 | 用户提示 |
+|---------|---------|
+| 网络错误 | "无法连接到夜莺平台，请检查网络或配置" |
+| 401/403 | "认证失败，请检查API Key配置" |
+| 404 | "未找到指定的资源" |
+| 500 | "夜莺服务器错误，请稍后重试" |
+| 超时 | "请求超时，请检查网络连接" |
+
+## Skills 设计
+
+### Skill 1: query-active-alerts
+
+```markdown
+---
+name: query-active-alerts
+description: 查询夜莺平台当前活跃的告警事件
+---
+
+# 查询活跃告警
+
+## 何时使用
+
+- 用户询问"当前有哪些告警"、"最近的告警"、"帮我查一下告警"
+- 用户询问特定严重级别的告警："有没有严重告警"、"warning级别的告警"
+- 用户想了解当前系统状态
+
+## 使用方法
+
+调用 `n9e_query_active_alerts` 工具，根据用户意图填充参数：
+- severity: 1(严重), 2(警告), 3(提示)
+- rule_name: 从用户消息中提取规则名称
+- limit: 默认50条
+
+## 返回后如何回答
+
+- 总结告警数量和严重程度分布
+- 列出最重要的几条告警（ID、规则、触发时间）
+- 提供进一步查询建议
+
+## 示例
+
+用户: "查一下最近的告警"
+→ 调用 `n9e_query_active_alerts({ limit: 10 })`
+→ 总结: "当前有5条活跃告警，其中2条严重、3条警告..."
+```
+
+### Skill 2: query-historical-alerts
+
+用于查询历史告警、分析趋势，支持时间范围过滤。
+
+### Skill 3: query-alert-rules
+
+用于查看配置的告警规则、搜索特定规则配置。
+
+### Skill 4: query-alert-mutes
+
+用于查看告警屏蔽配置，了解为什么某些告警被抑制。
+
+## 数据格式与响应
+
+### 响应格式化原则
+
+1. **结构化 JSON**: 便于 AI agent 解析和理解
+2. **包含摘要**: 总数、分布统计
+3. **时间戳转换**: Unix 时间戳 → "2026-02-12 14:30:00"
+4. **严重级别标签化**: 1 → "严重", 2 → "警告", 3 → "提示"
+
+### 大数据集处理
+
+- 默认限制: 50 条
+- 超出提示: "显示前50条，共有120条结果"
+- 建议筛选: "可以通过严重级别或规则名称筛选"
+
+### 时间戳处理
+
+- 支持相对时间: "last 1 hour", "yesterday"
+- 转换为可读格式: "2026-02-12 14:30:00"
+- 使用服务器时区
+
+## 验证与安全
+
+### 输入验证
+
+- 严重级别: 仅允许 1-3
+- 时间范围: stime < etime
+- 限制参数: 1-1000
+- 查询字符串: 防注入清理
+
+### 日志策略
+
+- DEBUG: 所有 API 请求 (方法、路径、参数)
+- INFO: 成功响应
+- ERROR: 错误详情和上下文
+- **禁止**: 记录敏感数据 (API Key)
+
+### 错误响应格式
+
+```typescript
+{
+  content: [{
+    type: "text",
+    text: "❌ 查询失败: 认证错误，请检查API Key配置"
+  }],
+  isError: true
+}
+```
+
+## 测试清单
+
+- [ ] 有效 API 凭证测试
+- [ ] 无效/过期 API Key 测试
+- [ ] 网络超时场景测试
+- [ ] 空结果集测试
+- [ ] 大数据集测试
+- [ ] 各种查询参数组合测试
+- [ ] Skills 正确加载测试
+- [ ] Agent 理解和调用工具测试
+
+## 部署流程
+
+1. 安装插件: `openclaw plugins install -l ./n9e-plugin`
+2. 配置文件中添加配置 (apiBaseUrl, apiKey)
+3. 重启 Gateway: `openclaw gateway restart`
+4. 验证加载: `openclaw plugins list`
+5. 测试自然语言查询
+
+## 开发检查清单
+
+- [ ] 插件清单 (`openclaw.plugin.json`) 完整
+- [ ] 每个工具都有配套 Skill
+- [ ] 配置 Schema 使用 Zod 定义
+- [ ] API Key 标记为 sensitive
+- [ ] 工具的 description 清晰准确
+- [ ] 错误处理完善
+- [ ] 日志记录完整
+- [ ] 所有功能测试通过
+
+## 示例用户交互
+
+**用户**: "查一下最近的告警"
+**Agent**: 调用 `n9e_query_active_alerts({ limit: 10 })`
+**回复**: "当前有5条活跃告警，其中2条严重级别、3条警告级别。最近的告警是..."
+
+**用户**: "有严重级别的告警吗"
+**Agent**: 调用 `n9e_query_active_alerts({ severity: 1 })`
+**回复**: "有2条严重告警: 1) CPU使用率过高 (server-01) ..."
+
+**用户**: "昨天有哪些告警"
+**Agent**: 调用 `n9e_query_historical_alerts({ stime: yesterday_ts, etime: today_ts })`
+**回复**: "昨天共有15条告警事件，包括..."
+
+**用户**: "CPU相关的告警规则"
+**Agent**: 调用 `n9e_query_alert_rules({ rule_name: "CPU" })`
+**回复**: "找到3条CPU相关的告警规则: 1) CPU使用率 > 80% ..."
+
+**用户**: "哪些告警被屏蔽了"
+**Agent**: 调用 `n9e_query_alert_mutes()`
+**回复**: "当前有2条告警屏蔽规则: 1) 维护窗口期屏蔽 ..."
+
+## 技术栈
+
+- **语言**: TypeScript (ESM)
+- **运行时**: jiti (OpenClaw Gateway 进程内)
+- **HTTP 客户端**: node-fetch 或 内置 fetch
+- **验证**: Zod
+- **API 文档**: Swagger JSON from n9e
+
+## 后续扩展可能性
+
+- 支持告警事件操作 (确认、屏蔽、删除)
+- 支持告警统计和聚合查询
+- 支持订阅规则查询
+- 添加告警趋势分析功能
+- 集成告警通知功能
+
+## 参考资料
+
+- OpenClaw 插件开发指南: `/Users/yaobinze/workarea/youdao/ts/clawdbot_popo_plugin/docs/plugin-development-guide.md`
+- 夜莺 API 文档: `/Users/yaobinze/workarea/youdao/go/n9e/center/docs/swagger.json`
+- OpenClaw 插件 SDK: `openclaw/plugin-sdk`