mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-17 20:50:49 +08:00
oliver
47fd83597e
Default progress, quote wrappers, tool-error copy, and playbook recipes to English unless lang is explicitly zh. Co-authored-by: Cursor <cursoragent@cursor.com>
108 lines
6.5 KiB
Markdown
108 lines
6.5 KiB
Markdown
---
|
||
name: ops-netx-ume-playbook
|
||
description: 面向 ops 专家的 netx UME 运维作业手册。覆盖告警查询/聚合/诊断、网元清单与单网元详情、raw 字段过滤、UME 只读 SQL、以及告警关联拓扑路径。
|
||
---
|
||
|
||
# Ops Netx UME 作业手册
|
||
|
||
## 强制使用范围
|
||
|
||
凡是涉及 netx/UME **告警**或 **网元信息** 的 ops 请求，必须优先加载并遵循本技能。
|
||
|
||
## MCP 工具名（强制）
|
||
|
||
使用 Cursor / oclaw MCP 时，工具名为 **camelCase**（`server_id=netx`）：
|
||
|
||
| 用途 | MCP 工具 |
|
||
|------|----------|
|
||
| 告警列表 | `queryUmeAlarms` |
|
||
| 告警聚合 | `aggregateUmeAlarms` |
|
||
| 诊断摘要 | `runUmeDiagnostics` |
|
||
| 网元清单 | `queryUmeNeInventory` |
|
||
| 网元详情 | `getUmeNe` |
|
||
| 字段清单 | `listUmeAlarmFields` |
|
||
| 原始明细 | `queryUmeAlarmsRaw` |
|
||
| 动态聚合 | `aggregateUmeAlarmsRaw` |
|
||
| SQL | `sqlQueryUme` |
|
||
| 拓扑路径 | `findTopologyPaths` |
|
||
| 纳管/CLI（另册） | `listManagedNe` / `getManagedNe` / `execManagedNe` / `listCliTargets` |
|
||
|
||
旧名 `netx_query_ume_alarms` 等仅在 `OCLAW_NETX_BUILTIN_TOOLS=1` 时可用；**优先 MCP**。
|
||
|
||
## 工具选择顺序
|
||
|
||
1. **新鲜度（先做）**：`runUmeDiagnostics` 或 `aggregateUmeAlarms` → 看 `meta.last_seen_min` / `last_seen_max`。
|
||
- 若最大值远早于「现在」，按 **快照数据** 处理：时间窗用数据范围内的日期，禁止套 `now()-30 minutes`。
|
||
2. 基础视图：`aggregateUmeAlarms` + `runUmeDiagnostics`；样本用 `queryUmeAlarms`（默认 1 页）。
|
||
3. 证据明细：`listUmeAlarmFields` → `queryUmeAlarmsRaw`（`field_preset=evidence` / `select_fields`）。
|
||
4. 自定义聚合：`aggregateUmeAlarmsRaw`（`group_by=alarm_host_name` 等）。
|
||
5. SQL：`sqlQueryUme`（仅 SELECT；设 `statement_timeout_ms`）。
|
||
6. **告警关联拓扑**：两台相关网元取 `ne_id` → `findTopologyPaths`（最短路径优先）。
|
||
7. **登设备查 CLI**：见 `ops-netx-managed-ne-playbook`（`listCliTargets` / `execManagedNe`）。
|
||
|
||
## 快速决策树
|
||
|
||
- **整体态势 / Top 风险**：`runUmeDiagnostics` + `aggregateUmeAlarms`（默认已排除 missing host；看 `by_ne_missing`）。
|
||
- 高危 Top-N：`aggregateUmeAlarms(severity=critical, top_ne=10)`，勿只看总量 Top。
|
||
- 按 host 自定义分组：`aggregateUmeAlarms(group_by=alarm_host_name, …)`（内部等同 Raw）或显式 `aggregateUmeAlarmsRaw`。
|
||
- **时间收敛**：`queryUmeAlarms` / `aggregateUmeAlarms` / raw 均支持 `time_from`/`time_to`（语义=`last_seen_at`）。先看 freshness，再填时间窗。
|
||
- **可引用证据**：`queryUmeAlarmsRaw` + `field_preset=evidence`。
|
||
- **任意字段统计**：`aggregateUmeAlarmsRaw`（按 host 分组时默认排除 missing；看 `by_ne_missing`）。
|
||
- **复杂条件**：`sqlQueryUme`。
|
||
- **critical 口类/光路类告警**：抽 1–2 个 `ne_id` → `findTopologyPaths`（默认 `detail=summary`，看 `paths[].label`）→ 再决定是否 CLI。
|
||
- **查网元身份**：`queryUmeNeInventory(keyword=host_name)`；完整 `raw_json` 用 `getUmeNe`。
|
||
|
||
## WhatsApp short-intent recipes (≤3 tools; English field primary)
|
||
|
||
Prefer these fixed paths for short group/DM asks (EN first; ZH aliases still work). **Target ≤3 tool calls** — do not paginate or re-list CLI targets.
|
||
|
||
| User says (examples) | Recipe |
|
||
|----------------------|--------|
|
||
| fiber cut / LOS / cable cut / 断纤 | Prefer `ume_alarm_xlsx_report(mode=fiber_cut)` (xlsx + deliver); or summarize via `queryUmeAlarmsRaw` |
|
||
| offline NE / board offline / 离线 | Prefer `ume_alarm_xlsx_report(mode=offline)` |
|
||
| Critical Top / alarm tally | ① `aggregateUmeAlarms(severity=critical, top_ne=20)`; for file: `ume_alarm_xlsx_report(mode=aggregate_by_host, severity=critical)` |
|
||
| how many alarms / tally | ① `runUmeDiagnostics` or `aggregateUmeAlarms`; ② report by_severity + freshness |
|
||
| export Excel / send spreadsheet | `ume_alarm_xlsx_report` **or** `write_xlsx(..., deliverable=true)`; never split into 3 steps |
|
||
|
||
Delivery rules:
|
||
- `ume_alarm_xlsx_report` defaults `deliverable=true` so WhatsApp receives the file.
|
||
- Generic sheets: `write_xlsx(..., deliverable=true)` can skip `save_deliverable_attachment`.
|
||
- Do not build xlsx via `run_command` + openpyxl.
|
||
- Confirm short replies (`YES` / `confirm` / `继续`): continue the previous task; do not restart the query.
|
||
|
||
## 约束与护栏
|
||
|
||
- 优先非 SQL；参数表达不了再用 SQL。
|
||
- 过滤优先级：`severity` → `keyword`/`host_name` → `time_from/time_to` → `event_type`/`ne_id`。
|
||
- 禁止无脑翻页：列表默认 ≤2 页；扩大前必须先过滤。
|
||
- 体积：`page_size` 默认 50；聚合 `top_ne` 默认 50；raw 用 preset；动态聚合 `limit≤200`。
|
||
- **Top 网元**：默认忽略 `(host_name missing)`；结论中说明 missing 数量，勿把 UUID/`unknown`/空串当网元名。
|
||
- SQL：建议 `statement_timeout_ms=8000`；非 `count(*)` 应带过滤；时间窗相对 **数据新鲜度**，不是盲目 `now()`。
|
||
- 若返回 `insufficient_scope:sql:query`：改用 `aggregateUmeAlarms` / `queryUmeAlarmsRaw` / `ume_alarm_xlsx_report`，勿盲重试 SQL。
|
||
- `WITH` CTE 可用；**禁止** `WITH RECURSIVE`。
|
||
- `getManagedNe` 只要 **纳管 ne_id**（来自 listManagedNe）；UME UUID 用 `getUmeNe` / `execManagedNe(ume_ne_id=...)`。
|
||
|
||
## 输出约定
|
||
|
||
- 结论 + 工具证据 + 可执行下一步。
|
||
- 无工具证据不得臆测告警事实。
|
||
- **现场默认英文**：用户用英文提问或渠道 lang=en 时，回复 **不得含汉字**；工具返回的中文字段必须译成英文后再展示。
|
||
- 仅当用户明确用中文提问且渠道为 zh 时，才用中文回复。
|
||
|
||
### 网元展示：以 host_name 为主键（强制）
|
||
|
||
- 表格首列、Top、分组键、结论中的网元名 = **`host_name`**。
|
||
- 来源：`queryUmeAlarms.host_name` / raw `alarm_host_name` / 聚合 `alarm_host_name`。
|
||
- **禁止**对用户展示裸 `ne_id`；`ne_id` 仅作过滤与 `findTopologyPaths` 入参。
|
||
- host 缺失时用 `user_label`，并标注「host_name 缺失」；仍不得退回 UUID。
|
||
|
||
## 推荐分析模式
|
||
|
||
- 高风险网元：`aggregateUmeAlarms(group_by=alarm_host_name, severity=critical)` 或显式 `aggregateUmeAlarmsRaw`。
|
||
- 严重度：`aggregateUmeAlarms`（默认 by_severity + by_ne）；自定义维度才用 `group_by`。
|
||
- 事件类型：看 diagnostics `top_event_types`；真正告警码看 `top_alarm_codes`（UME `alarmCode`）。
|
||
- 关联路径：critical Port down / LOS → `findTopologyPaths(from_ume_ne_id, to_ume_ne_id)`。
|
||
|
||
## 参考模板
|
||
|
||
- 快速模板见：[reference.md](reference.md)
|