Expand netx-ops into a field playbook with clear CLI batch rules.

Document host_name-only replies, vendor/? exploration, and same-vendor command variance without abandoning working commands.
2026-10-08 23:33:21 +08:00 · 2026-09-06 20:58:22 +08:00 · 2026-09-06 20:58:22 +08:00 · 0f8a06bfba
commit 0f8a06bfba
parent e732e1a0a7
2 changed files with 222 additions and 73 deletions
--- a/skills/ops/netx-ops/SKILL.md
+++ b/skills/ops/netx-ops/SKILL.md
@ -1,94 +1,218 @@
 ---
 name: netx-ops
-description: >-
-  Netx Ops playbook (MCP + DSH): NMS alarms/inventory/SQL plus managed-NE CLI
-  login (execManagedNe batch-first) and findTopologyPaths. Trigger: alarms,
-  host_name, Critical Top, LOS, 能否登录, show/display, optical, capacity A<>B,
-  path between sites, netx ops.
+description: netx 运维：告警、网元、只读 CLI。
 ---

-# netx-ops（告警 + 纳管登录）
+# netx-ops（告警 · 清单 · 纳管登录）

-**一组一个 skill。** 问「能否登录 / CLI / show」必须走本 skill 的 managed 工具，不要只查 NMS inventory。
+处理 netx **告警 / 网元清单 / 只读 CLI** 时遵循本手册。  
+画布布图不在本 skill（见 **netx-topology**）。本手册里的「路径」仅指 `findTopologyPaths` 查两端关联。

-## Hosts
+**工具名**：DSH 为 `netx__` + stem（如 `netx__queryNmsAlarms`）；MCP 多为同名裸 stem。下文一律写 stem。

-| Host | Tools |
-|------|--------|
-| **MCP** `netx-mcp` | 裸名 `queryNmsAlarms` / `execManagedNe` / … |
-| **DSH** `dsh-netxops` | `netx__` + 同 stem；能力组 **ops**（默认开） |
+**两套「一批」（勿混）：**

-REST NMS 仍 `/v1/ume/*`（`nmsProvider=zte-ume`）。优先 `nms_ne_id`；`ume_*` 别名可用。  
-画布 / dual_unit → **netx-topology**（能力组 topology）。
+| 说法 | 含义 | 写法 |
+|------|------|------|
+| **多台一批** | 一次工具调用打多台设备 | `nms_ne_ids`/`ne_ids` + 共享 `commands`，或 `targets` |
+| **同台多条** | 一次工具调用、**一台**上发多条命令 | 单个 `ne_id`/`nms_ne_id` + `commands:[…]` |

-## Tools
+禁止：同轮对多台各调一次 `execManagedNe`（假并行、会串行）。

-### NMS
+---

-| Purpose | Tool |
-|---------|------|
-| Alarm list / aggregate / diagnostics | `queryNmsAlarms` / `aggregateNmsAlarms` / `runNmsDiagnostics` |
-| Inventory / detail | `queryNmsNeInventory` / `getNmsNe` |
-| Raw / fields / SQL | `queryNmsAlarmsRaw` / `listNmsAlarmFields` / `aggregateNmsAlarmsRaw` / `sqlQueryNms` |
+## 1. 总原则

-### Managed CLI + paths
+1. **先新鲜度，再结论**：`runNmsDiagnostics` 或 `aggregateNmsAlarms` → 读 `meta.last_seen_*`。过旧则按快照：时间窗落在 min~max 内，禁止默认「现在−30 分钟」。
+2. **证据优先**：有告警须有级别计数和/或 Top `host_name`；否则写「证据不足」，禁止臆造根因。
+3. **对用户**：只展示 **host_name**；**严禁**出现任何 UUID/`ne_id`。无 `host_name` 的行当垃圾丢弃（不顶替 label、不提「缺失」）。工具入参仍可用 id，但不得写入对用户可见正文。
+4. **短问**：能 ≤3 次工具调用就闭环的，先聚合/过滤，禁止无过滤翻全库。复杂关联（dying gasp、A<>B CLI）不受 3 次硬顶，但仍须有过滤与目标。
+5. **「能否登录」**：必须走 §3；禁止只查 inventory 下结论。

-| Purpose | Tool |
-|---------|------|
-| List CLI targets | `listManagedNe` / `listCliTargets` |
-| Managed detail | `getManagedNe`（**仅**纳管 id） |
-| Login / show | `execManagedNe`（batch-first） |
-| Fabric paths | `findTopologyPaths` |
+---

-## 「能否登录」决策树（强制）
+## 2. 工具选用（按需，非逐步必跑）

-1. `listCliTargets(keyword=host_or_ip)` 或 `listManagedNe(keyword=…, connect_status=pass)`  
-   - 命中 → `execManagedNe(ne_id|nms_ne_id, commands=["show version"])` **验证真正能登**  
-   - 未命中 → `queryNmsNeInventory(keyword=…)` 说明 NMS 有无 / `connection_status`，并明确：**未纳管 netx CLI 则不能用本通道登录**
-2. 禁止只查 inventory 就下「不能登录」或「能登录」结论而不尝试 `execManagedNe`（已纳管时）。
-3. NMS UUID 不要塞进 `getManagedNe`；用 `execManagedNe(nms_ne_id=…)` 或先 list 拿 managed `ne_id`。
+按意图选步，**不是**每次从 ① 跑到 ⑧。

-## NMS 工具顺序
+| 意图 | 工具 |
+|------|------|
+| 新鲜度 / 态势 / Top | `runNmsDiagnostics`、`aggregateNmsAlarms` |
+| 一页现告警 | `queryNmsAlarms` |
+| 可引用明细 | `queryNmsAlarmsRaw`（`field_preset=evidence`）；字段不明可先 `listNmsAlarmFields` |
+| 自定义聚合 | `aggregateNmsAlarmsRaw`（如 `group_by=alarm_host_name`） |
+| 复杂条件 | `sqlQueryNms`（只读 SELECT，设超时） |
+| 绰号→真名 / 是否在 NMS | `queryNmsNeInventory` / `getNmsNe` |
+| 两端路径 / 对端 | `findTopologyPaths` |
+| 只读登录 | `listCliTargets` 或 `listManagedNe` → **一次** `execManagedNe` |

-1. Freshness: `runNmsDiagnostics` / `aggregateNmsAlarms` → `meta.last_seen_*`
-2. Overview + one-page `queryNmsAlarms`
-3. Evidence: `queryNmsAlarmsRaw` (`field_preset=evidence`)
-4. Paths / CLI as needed (same skill)
+`getManagedNe` **仅**接受纳管 `ne_id`。NMS 侧 id 用 `execManagedNe(nms_ne_id=…)`，禁止塞进 `getManagedNe`。

-## CLI order
+---

-1. `listManagedNe` / `listCliTargets`（每会话最多一次，缓存 id）
-2. 多台 → **一次** `execManagedNe`（`ne_ids` / `nms_ne_ids` / `targets`）
-3. 路径 → `findTopologyPaths`
+## 3. 「能否登录」决策树（强制）

-### Batch 示例
+1. `listCliTargets(keyword=主机或IP)` **或** `listManagedNe(keyword=…, connect_status=pass)`  
+   - **命中** → `execManagedNe`，命令按厂商：`show version`（中兴/Cisco 等）或 `display version`（华为）；以实测为准  
+   - **未命中** → `queryNmsNeInventory(keyword=…)`：说明 NMS 有无及 `connection_status`；并写明：**未进 netx CLI 通道则本通道不能登录**（不等于设备不存在）
+2. 已在 CLI 目标列表中：禁止只凭 inventory 说能/不能登。
+3. 本会话 `listCliTargets`、`listManagedNe` **各最多一次**，缓存结果；同台多条命令进同一次 `commands[]`。
+
+---
+
+## 4. CLI：多台一批（强制）
+
+查 **≥2 台** 时：必须 **一次** `execManagedNe`。
+
+- 命令相同：`nms_ne_ids` 或 `ne_ids` + 共享 `commands`
+- 命令不同（厂商/角色不同）：`targets=[{nms_ne_id|ne_id, commands:[…]}, …]`，仍一次调用
+- 超时：加大 `read_timeout_sec` 或减条数；禁止同参盲重试
+- 只读：`show` / `display` / `ping` / `traceroute` 及带 `?` 的探索；配置类不做
+
+**✓ 同命令多台**

 ```json
 { "nms_ne_ids": ["uuid-a", "uuid-b"], "commands": ["show version"], "concurrency": 4 }
 ```

+**✓ 混厂商（多台一批）**
+
 ```json
 {
  "targets": [
-    {"nms_ne_id": "uuid-zte", "commands": ["show opticalinfo brief"]},
-    {"nms_ne_id": "uuid-hw", "commands": ["display optical-module brief"]}
-  ]
+    { "nms_ne_id": "uuid-zte", "commands": ["show opticalinfo brief"] },
+    { "nms_ne_id": "uuid-hw", "commands": ["display optical-module brief"] }
+  ],
+  "read_timeout_sec": 90
 }
 ```

-## Short recipes
+（示例中的 uuid 仅作工具入参示意，**禁止**出现在对用户回复里。）

-| User says | Recipe |
-|-----------|--------|
-| 能否登录 / login / SSH | 上表「能否登录」决策树 |
-| fiber / LOS | Raw `keyword=LOS` / `Fiber Break` |
-| Critical Top | `aggregateNmsAlarms(severity=critical, top_ne=20)` |
-| capacity A<>B | paths / LLDP → 两端 optic CLI（一批） |
+记不清命令、要用 `?` 探索 → 见 **§8**（同台多条分裂，不是多台同探）。

-## Guardrails
+---

- 展示 **host_name**；勿对用户甩裸 UUID
- CLI 白名单：`show` / `display` / `ping` / `traceroute` …
- 同轮禁止 N× 单台 `execManagedNe`
+## 5. 现场短问配方

-See [reference.md](reference.md).
+| 用户说法 | 做法 |
+|----------|------|
+| Critical Top / 高危排名 | `aggregateNmsAlarms(severity=critical, top_ne=20)` |
+| 现网告警多少 / 态势 | `runNmsDiagnostics` 或 `aggregateNmsAlarms` → 级别 + 新鲜度 |
+| 断纤 / LOS / 光缆 | Raw：`keyword=LOS` 和/或 `Fiber Break` → **有 host_name 的列表 + 计数** |
+| 光功率**门限**（某区域） | Raw：`keyword=optical power`（或 Input optical power）+ 主机名前缀；**禁止**当断纤配方 |
+| 离线 / BN EMS / 失联 | Raw：`keyword=BN EMS` 或 communication failure |
+| dying gasp | 本端 dying gasp → `findTopologyPaths`/端口找对端 → 对端近时窗 BN EMS；**禁止只答一端** |
+| CRC / 拥塞 bandwidth / license / 风扇温度 | Raw 对应 keyword；区域用主机名前缀 |
+| 单机当前告警（已给 host） | 限定该 `host_name`；**禁止**跑无关日报/license 流程 |
+| 告警码 NNNN | 按 code 过滤；只列有 `host_name` 的 |
+| 时间窗（如 17:50–18:15） | 先新鲜度；时区以用户为准（未声明则沿用对话语境，现场常见 WIB/UTC+7） |
+| 能否登录 / SSH | §3 |
+| A<>B 容量 / 两端光功率 | **两端端口光模块 CLI 实读**，不是带宽利用率告警 tally（除非用户只要告警）：解析两端 host → 路径/LLDP → **多台一批** optic CLI |
+| 哪段断了 + LOS 主机 | `object_name` + `findTopologyPaths` |
+| BGP/OSPF/LDP 等 | 指定 host 或双端协议类 Raw；要比时间就对齐；**默认不当断纤** |
+
+### 口语约定
+
+- **区域** = `host_name` 在第一个 `-` 之前的前缀（如 `ACH-`），大小写不敏感 starts-with。
+- **A<>B / capacity / 两端光功率** = 互联口 SFP/光功率 CLI；≠「带宽利用率超阈值」告警清单。
+- **断纤清单** ≠ **光功率门限清单**（后者 keyword=`optical power`）。
+- 绰号：先 `queryNmsNeInventory` 解析成 `host_name`；解析不到则说明无法解析，禁止瞎编。
+- 「继续 / YES / 确认」：接着上一未完成任务，不整段重开。
+
+### 常见 cause 子串（keyword / 证据标签）
+
+| 意图 | 典型子串 |
+|------|----------|
+| 断纤 / LOS | `ETPI) LOS`、`Fiber Break`、`Missing laser module` |
+| 光功率门限 | `Input optical power(dBm) threshold`、`Output optical power` |
+| 拥塞 | `bandwidth usage rate` |
+| CRC | `CRC error` |
+| 离线 | `BN EMS`、`NE communication failure` |
+| dying gasp | `Remote dying gasp` |
+| License | `Permanent license`、`No enough license` |
+| 环境 | `System Power off`、`undervoltage`、`temperature`、`Fan` |
+
+Neighbour / PW / Tunnel 等控制面量多 **不当断纤**，除非用户问的就是该协议族。
+
+---
+
+## 6. 禁止
+
+1. 无 severity / keyword / host / 区域 / 时间过滤翻全量告警。  
+2. 把 NMS UUID 当作 `getManagedNe` 的 `ne_id`。  
+3. 同轮对多台各调一次 `execManagedNe`。  
+4. 光功率门限清单误用断纤/LOS 配方。  
+5. 单机告警问句跑无关定时/license 流程。  
+6. 终稿只有过程叙述、无 Result/Evidence。  
+7. CLI 失败后对**同一错误命令、同一台**盲重试（应换命令或 `?` 探索）。  
+8. 对用户输出 UUID，或用无 `host_name` 的行凑数。  
+9. 因一台设备命令失败，就放弃该命令在其他设备上的使用。
+
+---
+
+## 7. 终稿
+
+`*主题 — 范围*` + Result / Evidence / Next；短、可扫读；大表只给 Top（且仅含有 `host_name` 的）。  
+速查：[reference.md](reference.md)。
+
+---
+
+## 8. 附录：厂商差异与 `?` 探索
+
+仅在记不清命令、报错或需盲查时用。与 §4「多台一批」不同：此处是 **一台设备上多条探索命令**。
+
+### 厂商前缀
+
+| 厂商 | 只读习惯 |
+|------|----------|
+| 华为（含部分 VRP） | 多为 `display …` |
+| 中兴 / Cisco / 多数其他 | 多为 `show …` |
+
+混厂商多台：用 `targets`。同厂商多台：可先共享 `commands`，但须接受下面「同厂也可能不一致」。
+
+### 同厂不同设备命令也可能不一致
+
+检查整网时**一定会**碰到：同为中兴/华为，A 台能敲的命令 B 台报错或参数不同（版本、牌号、角色差异）。
+
+- **禁止**因一台失败就认定「这条命令全网作废、以后都不用」。
+- **应**：失败台单独换命令或走 `?` 探索；其余已成功的台继续用原命令。
+- **优先复用本会话已成功过的命令**（含同厂其他台验证过的）：新台/下一批先试这些，再对失败子集另探；不要一失败就换全员命令。
+- 多台一批时：用 `targets` 给失败台换命令，或先一批共同命令 → 只对失败子集再一批探测；不要为了一台把成功台的结果丢掉重来。
+
+### `?` 规则（`show` / `display` / `ping` 等同一套）
+
+1. 报错中的 **`^`** 标出错位置 → **`^` 之前**已正确 → 对该前缀加 `?` 列下一级。  
+2. `?` 可紧接在部分单词后（`show optical?`、`display inter?`），不必强制空格再写 `?`。  
+3. 输出含 `<cr>` → 命令已完整，可回车执行。  
+4. Incomplete → 未写完，继续 `?`；Unrecognized → 走错，退回上一层换词。  
+5. **禁止**对同一错误整句反复重试。
+
+例：
+
+```text
+<r1>display interface briaf
+                      ^
+Error: Wrong parameter found at '^' position.
+```
+
+→ 改为 `display interface ?`，再选 `brief` 等合法下级。`show` 同理。
+
+### 同台分裂（一台、多条、一次调用）
+
+某一层 `… ?` 列出多个候选且还需下钻时：在 **同一台** 一次 `execManagedNe` 的 `commands[]` 中放入多条同级探索，综合结果再往下裂。  
+**不是**多台同时探同一条 `?`。
+
+例（已见 `display ip routing-table ?` 后）：
+
+```text
+display ip routing-table protocol ?
+display ip routing-table all-vpn-instance ?
+display ip routing-table all-routes ?
+```
+
+对应一次调用形如：`execManagedNe(nms_ne_id=…, commands=["display ip routing-table protocol ?", "… all-vpn-instance ?", "… all-routes ?"])`。
+
+### ZTE 光模块
+
+优先 `show opticalinfo brief` → 其次 `show optical brief` → 仍不对则 `show optical?` / `show opticalinfo?`；同级候选用上面的同台分裂，勿盲猜整句。
--- a/skills/ops/netx-ops/reference.md
+++ b/skills/ops/netx-ops/reference.md
@ -1,22 +1,47 @@
-# netx-ops quick reference
+# netx-ops 速查

-## Can it log in?
+## 两套「一批」

-1. `listCliTargets` / `listManagedNe` → if found, `execManagedNe(…, commands=["show version"])`
-2. Else `queryNmsNeInventory` → report NMS presence; say CLI not managed if absent from managed list
+- **多台一批**：一次调用打多台（`nms_ne_ids`/`targets`）
+- **同台多条**：一台上一次 `commands[]` 多条（含多个 `… ?` 分裂）
+- 禁止：同轮多台各调一次 `execManagedNe`

-## NMS freshness
+## 新鲜度

- `runNmsDiagnostics` / `aggregateNmsAlarms` → `meta.last_seen_min` / `max`
+- `runNmsDiagnostics` / `aggregateNmsAlarms` → `meta.last_seen_*`
+- 快照：时间窗 ∈ min~max；勿默认「现在−30 分钟」

-## Shortcuts
+## 能否登录

-| Intent | Call |
-|--------|------|
+1. `listCliTargets` / `listManagedNe` → 命中则实测 `show version` 或 `display version`
+2. 未命中 → inventory 说明有无；未进 CLI 通道则本通道不能登
+
+## 短路径
+
+| 意图 | 调用 |
+|------|------|
 | Critical Top | `aggregateNmsAlarms(severity=critical, top_ne=20)` |
-| Fiber / LOS | Raw `keyword=LOS` / `Fiber Break` |
-| Inventory | `queryNmsNeInventory(keyword=…)` / `getNmsNe` |
-| CLI batch | `execManagedNe(nms_ne_ids=[…], commands=[…])` |
-| Paths | `findTopologyPaths(from_nms_ne_id, to_nms_ne_id)` |
+| 态势 | `runNmsDiagnostics` / `aggregateNmsAlarms` |
+| 断纤 / LOS | Raw `keyword=LOS` / `Fiber Break` |
+| 光功率门限 | Raw `keyword=optical power` + 前缀（≠ 断纤） |
+| 离线 | Raw `keyword=BN EMS` |
+| 单机告警 | 限定 `host_name` |
+| 证据 | `queryNmsAlarmsRaw(field_preset=evidence)` |
+| 清单 | `queryNmsNeInventory` / `getNmsNe` |
+| 多台 CLI | `execManagedNe(nms_ne_ids=…)` 或 `targets` |
+| 路径 | `findTopologyPaths` |
+| A<>B 光 | 两端 host → 路径 → 多台一批 optic CLI |

-DSH: prefix tools with `netx__`.
+## 展示
+
+- 只展示 **host_name**；严禁 UUID
+- 无 `host_name`：丢弃
+- DSH：前缀 `netx__`
+
+## 厂商与 `?`
+
+- 华为 `display`；其他多 `show`；方法同一套 `?`
+- **同厂也可能命令不一**：一台失败 ≠ 全网作废；失败台另探，成功台继续原命令；**已成功过的命令优先复用**
+- `^` 前正确 → 加 `?`（可接词尾）
+- **同台分裂**：一台 `commands[]` 多条 `… ?`；**不是**多台同探
+- ZTE 光：`opticalinfo brief` → `optical brief` → `show optical?`