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

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

使用 MCP 名称（mcp__netx__*）；勿使用已移除的旧 inline netx_* 工具名。

工具选择顺序

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（含对/错 JSON 示例）；多台必须 一次 execManagedNe batch（同命令用 ne_ids|ume_ne_ids；每台命令不同用 targets=[{ume_ne_id, commands},…]）。同轮连发多次单台 execManagedNe 不会并行（stdio 串行），禁止。
   • 例：{"ume_ne_ids":["uuid-a","uuid-b"],"commands":["show version"]}；混厂商用 targets=[…] 仍一次调用。

快速决策树

• 整体态势 / 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 / 断纤 / sitelist	Prefer ume_alarm_xlsx_report(mode=fiber_cut) (defaults keyword=LOS → ETPI LOS; not optical-power threshold). For explicit Fiber Break rows also/instead keyword=Fiber Break or queryUmeAlarmsRaw(keyword=Fiber Break). Reply with host_name list + counts
offline NE / board offline / unmanaged / 离线	Prefer ume_alarm_xlsx_report(mode=offline) (defaults BN EMS / NE communication failure). Unmanaged ME list → same family + clarify BN EMS / unreachable
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
CRC in area PAD / ACH / …	queryUmeAlarmsRaw(keyword=CRC) then keep rows whose alarm_host_name / ne_host_name starts with area prefix (PAD-, ACH-, …). Optional xlsx via write_xlsx(deliverable=true)
bandwidth / congestion / usage rate (+ area)	keyword=bandwidth (matches Send/Receive bandwidth usage rate threshold crossed; do not require event_type). Filter hostname prefix for area; if CLI confirm: top 3–5 NEs in one batch
optical power threshold in area (BPP/PBR/PAL/…)	keyword=optical power (or Input optical power) + keep AREA- hosts. Not fiber_cut mode. Distinct from capacity A<>B CLI
BN EMS / dying gasp / unmanaged (+ area)	See Dying gasp / BN EMS correlation below — do not stop at one NE
power / temperature / fan / undervoltage / System Power off	keyword=power / temperature / fan / undervoltage / Power off; scope to host or area prefix. Optical power(dBm) ≠ board voltage
license	keyword=License (causes: Permanent license abnormal, No enough license resource)
BGP / OSPF / ISIS / LDP / PW / Tunnel on host	queryUmeAlarmsRaw(host or keyword=BGP|OSPF|LDP|…) on named host(s); for peer correlation see below
Port down / ETPI / which segment cut?	keyword=Port down or LOS on the named host; use object_name + findTopologyPaths / LLDP to name the far end
alarm code NNNN	queryUmeAlarmsRaw / diagnostics top_alarm_codes; keyword or raw filter on code; return host_name list
alarm on one hostname (e.g. MDN-PLSP, MKS-SWBP-EN1)	queryUmeAlarms / queryUmeAlarmsRaw with host_name / keyword=hostname. Never start a scheduled License/daily playbook
alarm history / time range (e.g. 17.50-18.15)	Resolve WIB (UTC+7) wall clock → time_from/time_to on last_seen_at / history fields; first check freshness; name hosts exactly (MKS-KIM-CN1)
is NE rebooted? / alarm history for NE	Host-scoped alarm history (reboot/reload/power related causes); answer yes/no + evidence times

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 / 继续 / ya / yea): continue the previous task; do not restart the query.

Field vocabulary (prod-learned; enforce)

• Area = hostname prefix before first -: MDN-, LPG-, MKS-, PLG-, BJM-, PTK-, ACH-, PBR-, MDO-, SMD-, PAD-, BTM-, PLK-, BPP-, BKL-, JBI-, KND-, PAL-, GRO-, JAP-, … Case-insensitive starts-with.
• Capacity / bandwidth between A and B / A <> B / site nicknames (SEMBAWA, ANGKATAN_EP): means SFP/optical link on the interconnect — not UME bandwidth usage rate alarms alone. Resolve both NEs → ports (findTopologyPaths / LLDP) → optic CLI. See ops-netx-managed-ne-playbook.
• Optical power threshold crossed (area list): UME cause Input/Output optical power(dBm) threshold crossed — keyword=optical power; not mode=fiber_cut.
• Fiber cut / LOS sitelist: causes Ethernet physical (ETPI) LOS, Fiber Break, Missing laser module — report mode=fiber_cut (LOS-biased) and/or keyword=Fiber Break.
• Site nicknames: resolve via inventory/wiki/queryUmeNeInventory(keyword=…) before CLI; never invent hostnames.
• Local clock phrases (17.50, today, yesterday): treat as Asia/Jakarta (WIB, UTC+7) unless user says otherwise.

Field cause cheat-sheet (2026-08 snapshot vocabulary)

Use these as keyword / evidence labels (exact strings appear in native_probable_cause):

Intent	Typical cause substrings
Fiber / LOS	ETPI) LOS, Fiber Break, Missing laser module
Optical threshold	Input optical power(dBm) threshold crossed, Output optical power
Congestion	Send bandwidth usage rate, Receive bandwidth usage rate
CRC	Receive CRC error frames, Received CRC error packet
Offline / unmanaged	BN EMS alarm NE communication failure
Dying gasp	Remote dying gasp event
License	Permanent license abnormal, No enough license resource
Power / env	System Power off, Input undervoltage, temperature, Fan module
Control-plane (noisy)	BGP Neighbour down, OSPF Neighbour, ISIS Neighbour, LDP Neighbour, State of PW in L2VPN, Tunnel down, NTP server

Do not treat PW/BGP volume leaders as “fiber cut” unless the user asked for those families.

Dying gasp / BN EMS correlation (field-mandated)

When user mentions dying gasp (or correlates BN EMS with a port):

1. On the named NE: queryUmeAlarmsRaw with keyword=dying gasp (and/or host_name) — note object_name / slot-port and last_seen_at.
2. Find peer: findTopologyPaths and/or LLDP/CLI on that port; identify far-end host_name.
3. On the peer: look for BN EMS / NE communication failure (and related offline) with near timestamp (± window from step 1).
4. Reply with both sides + times + whether correlation holds. Save this as the default dying-gasp playbook — do not answer only one NE.

Peer / protocol correlation (BGP·OSPF·LDP)

Field pattern: alarms on HOST-A with peer IP → confirm on HOST-B (or peer from topology).

1. Query both hosts (or keyword + both host filters) for the protocol family.
2. Align occurrence / clear times when asked.
3. Peer match: prefer exact peer / router-id; if user says so, also match identical 3rd+4th octet of the peer address from the alarm text.
4. Keep answers scoped to the named link (A <> B); do not dump unrelated area noise.

Anti-patterns seen in field (do not repeat)

1. Wrong playbook hijack — User: query alarm on MDN-AHJ-AN1 → must NOT run License/daily scheduled playbook. Answer that host’s current alarms only.
2. Narration-only turns — Avoid “Let me start by…” / “I’ll fetch fields…” as the only WhatsApp message. Prefer: progress throttle already exists; final reply = findings first (counts + top hosts), then optional detail.
3. Markdown tables on WhatsApp — Do not send |---|+ pipe tables or ## headings. Use *bold* labels and - bullets (outbound converter helps, but write WA-native).
4. Apology loops — If user asks “are you still running / why no response?”, resume the quoted task immediately; one short status line, then results. Do not ask what a Run ID might mean if schedule_list / job tools can answer.
5. Group noise — Pure emoji / mention-only / “hi” with no ops ask: stay minimal or silent per group policy; do not give a long “how can I help” menu.
6. Blind CLI retries — Wrong ZTE optic command once → switch to show opticalinfo brief (see managed-ne skill); do not retry the failed spelling.
7. fiber_cut vs optical power — Area “optical power threshold” lists must not use mode=fiber_cut (that is LOS/Fiber Break biased).
8. Unfiltered dump — Snapshot has ~80k uncleared rows; never list without severity/keyword/host/area/time.

Answer shape (WhatsApp EN) — strict ops bot

Final user-visible reply must follow ROLE_SYSTEM shell (*topic* / Result / Evidence / Next). See ROLE_SYSTEM Good vs bad examples — copy the good shape.

*<topic> — <area/NE>*
- Result: …
- Evidence: N alarms / Top hosts / CLI ok|fail · as-of WIB if known
- Next: … (omit if none)

• Final reply = findings only — do not lead with Let me… / I'll check….
• About ≤15 lines in chat; large detail → xlsx.
• Include severity counts and/or Top host_name when alarm data exists.
• Casual emoji/hi: one short line or silence — stay an ops bot, not a chat buddy.

约束与护栏

• 优先非 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=...)。失败时跟 hint 换工具，禁止相同 id 盲重试。

输出约定

• 结论 + 工具证据 + 可执行下一步。
• 无工具证据不得臆测告警事实。
• 严格运维机器人：终稿先结果、短列表、大表附件；禁止过程腔开场与客服闲聊人格（见 ROLE_SYSTEM / Answer shape）。
• 现场默认英文：用户用英文提问或渠道 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