mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-19 18:03:22 +08:00
oliver
685e3ffa8d
Document 14 netx tools, snapshot time windows, severity Top-N, and compact topology path usage for alarm workflows. Co-authored-by: Cursor <cursoragent@cursor.com>
4.6 KiB
4.6 KiB
| name | description |
|---|---|
| ops-netx-ume-playbook | 面向 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。
工具选择顺序
- 新鲜度（先做）：
runUmeDiagnostics或aggregateUmeAlarms→ 看meta.last_seen_min/last_seen_max。- 若最大值远早于「现在」，按 快照数据 处理：时间窗用数据范围内的日期，禁止套
now()-30 minutes。
- 若最大值远早于「现在」，按 快照数据 处理：时间窗用数据范围内的日期，禁止套
- 基础视图：
aggregateUmeAlarms+runUmeDiagnostics；样本用queryUmeAlarms（默认 1 页）。 - 证据明细：
listUmeAlarmFields→queryUmeAlarmsRaw（field_preset=evidence/select_fields）。 - 自定义聚合：
aggregateUmeAlarmsRaw（group_by=alarm_host_name等）。 - SQL：
sqlQueryUme（仅 SELECT；设statement_timeout_ms）。 - 告警关联拓扑：两台相关网元取
ne_id→findTopologyPaths（最短路径优先）。 - 登设备查 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。
- 高危 Top-N：
- 时间收敛：
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。
约束与护栏
- 优先非 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()。 WITHCTE 可用；禁止WITH RECURSIVE。
输出约定
- 结论 + 工具证据 + 可执行下一步。
- 无工具证据不得臆测告警事实。
- 英文提问：回复不得含汉字；工具中文字段须译成英文。
网元展示：以 host_name 为主键（强制）
- 表格首列、Top、分组键、结论中的网元名 =
host_name。 - 来源：
queryUmeAlarms.host_name/ rawalarm_host_name/ 聚合alarm_host_name。 - 禁止对用户展示裸
ne_id；ne_id仅作过滤与findTopologyPaths入参。 - host 缺失时用
user_label，并标注「host_name 缺失」；仍不得退回 UUID。
推荐分析模式
- 高风险网元：
aggregateUmeAlarmsRaw+group_by=alarm_host_name+severity。 - 严重度：
aggregateUmeAlarms或group_by=alarm_perceived_severity。 - 事件类型：看 diagnostics
top_event_types；真正告警码看top_alarm_codes（UMEalarmCode）。 - 关联路径：critical Port down / LOS →
findTopologyPaths(from_ume_ne_id, to_ume_ne_id)。
参考模板
- 快速模板见：reference.md