oclaw/skills/_workspace/ops/ops-netx-ume-playbook/reference.md

Ops Netx UME 快速参考

0) 数据新鲜度（必做）

• runUmeDiagnostics / aggregateUmeAlarms → meta.last_seen_min / last_seen_max
• 快照数据：时间窗落在 min~max 内；不要默认 now()-30 minutes

1) 当前告警明细（轻量）

• 工具：queryUmeAlarms
• 参数：severity, host_name, ne_id(仅过滤), keyword, time_from, time_to, page, page_size
• 建议：page_size=50；默认最多 2 页

2) 原始明细（证据）

• 工具：queryUmeAlarmsRaw
• 先 listUmeAlarmFields（可选）
• field_preset：brief / evidence / ne_debug
• 展示主键：alarm_host_name（首列）

3) 聚合

• aggregateUmeAlarms：severity(可选，如 critical)、top_ne(默认50)、exclude_missing_host(默认true)、time_from/time_to
  • 高危 Top：severity=critical；看 by_ne_missing；Top 默认不含 missing
  • 也可传 group_by=alarm_host_name：自动走动态聚合（等同 aggregateUmeAlarmsRaw）
• aggregateUmeAlarmsRaw：group_by=alarm_host_name 等；按 host 分组时默认排除 missing（by_ne_missing）

3b) WhatsApp 最短路径

意图	调用
Critical Top	aggregateUmeAlarms(severity=critical, top_ne=20)
按 host 统计+Excel	ume_alarm_xlsx_report(mode=aggregate_by_host, severity=critical)
断纤/LOS 清单+Excel	ume_alarm_xlsx_report(mode=fiber_cut)（默认 keyword=LOS）；纯 Fiber Break 再加 keyword=Fiber Break
离线/BN EMS+Excel	ume_alarm_xlsx_report(mode=offline)（默认 BN EMS）
区域光功率门限	queryUmeAlarmsRaw(keyword=optical power) → 保留 AREA- 前缀；不要 fiber_cut
发 Excel（已有表数据）	write_xlsx(..., deliverable=true)
区域 + 关键字（CRC/bandwidth/license）	queryUmeAlarmsRaw(keyword=…) → 过滤 host 前缀 AREA-
单网元当前告警	queryUmeAlarms(host_name=…) — 禁止误跑 License 定时 playbook
dying gasp	本端 dying gasp → 对端 BN EMS（近时间窗）+ 端口/拓扑；见 SKILL
两端 capacity/optical	解析两端 hostname → findTopologyPaths / LLDP → CLI optic（见 managed-ne）
时间窗历史（WIB）	freshness → time_from/time_to（按 Asia/Jakarta）

3c) 现场口语 → 动作

用户说法	正确理解
congestion / bandwidth usage in ACH	UME keyword=bandwidth + hostname ACH-；要验真再 CLI top N
optical power threshold in BPP/PBR/PAL	keyword=optical power + 区域前缀；≠ fiber cut
fiber cut / LOS sitelist	mode=fiber_cut / keyword=LOS 或 Fiber Break；回 host 列表
capacity A to B / optical power A <> B / SEMBAWA <> ANGKATAN	链路口 SFP/光功率 CLI，不是单独告警 tally
dying gasp on HOST + port	关联对端 BN EMS near timestamp（现场强制配方）
which segment cut? + LOS host	object_name + topology/LLDP 找对端
BGP/OSPF/LDP on HOST / A <> B	双端协议告警 + 时间对齐；peer 可按后两段 octet
site SEMBAWA / ANGKATAN_EP	先 inventory/wiki 解析成真实 host_name
17.50 - 18.15	WIB 当天 17:50–18:15
check alarm on MDN-xxx	仅该 host；勿触发 daily license 等无关 playbook
alarm code 4758	按 code 过滤；列出 host_name

3d) 现场 cause 关键字（CSV 高频）

• LOS / Fiber Break / Missing laser → 断纤类
• Input/Output optical power(dBm) threshold → 光功率门限（区域清单）
• bandwidth usage rate threshold → 拥塞
• CRC error → CRC
• BN EMS … communication failure → 离线/非管
• Remote dying gasp → 临终掉电类，必做对端关联
• Permanent license / No enough license → license
• BGP/OSPF/ISIS/LDP Neighbour down、State of PW、Tunnel down → 控制面/伪线噪声，勿当断纤

4) 诊断

• runUmeDiagnostics
• top_event_types：事件类型
• top_alarm_codes：UME alarmCode（有则）
• top_ne：已排除 missing host
• meta.last_seen_*：新鲜度

4b) 网元清单

• queryUmeNeInventory(keyword=…)
• getUmeNe(ne_id=UUID) — 仅内部关联 / raw_json

4c) 拓扑路径（告警关联）

• findTopologyPaths
  • from_ume_ne_id + to_ume_ne_id（来自告警 ne_id）
  • 或 managed 侧 from_managed_ne_id / to_managed_ne_id
  • 默认 detail=summary：看 paths[].label（含端口）与精简 nodes/edges；需要 attrs 时再 detail=full
• 返回最短路径优先；0 条路径也要说明，再考虑 CLI

5) SQL

• sqlQueryUme；表：ume_alarms_current / ume_inventory_ne
• statement_timeout_ms=8000
• 时间窗相对 meta.last_seen_max，示例：

select coalesce(nullif(trim(a.host_name), ''), '(host_name missing)') as host_name,
       count(*) as alarm_count
from ume_alarms_current a
where a.last_seen_at >= timestamp '2026-08-07 00:00:00'
  and lower(coalesce(a.perceived_severity, '')) in ('critical','major')
group by 1
order by alarm_count desc
limit 50

6) 登设备

• 见 ops-netx-managed-ne-playbook
• UME ne_id → listCliTargets / execManagedNe(ume_ne_id=…)（需已配 UME→CLI）；多台同 show → execManagedNe(ume_ne_ids=[…], commands=[…]) 一次；每台命令不同 → execManagedNe(targets=[{ume_ne_id, commands},…]) 一次。同轮 N 次单台调用会串行，不算并行；勿逐台循环 / fan-out

示例：

// ✓ 同命令
{"ume_ne_ids": ["uuid-1", "uuid-2"], "commands": ["show version"], "read_timeout_sec": 60}

// ✓ 混厂商
{"targets": [
  {"ume_ne_id": "uuid-zte", "commands": ["show opticalinfo brief"]},
  {"ume_ne_id": "uuid-hw", "commands": ["display optical-module brief"]}
]}

// ✗ 同轮三次单台（串行）— 禁止
// execManagedNe(ume_ne_id=uuid-1, …); execManagedNe(ume_ne_id=uuid-2, …); …