From 6f754ee5ea22344e561357152deca6c487d2fd6a Mon Sep 17 00:00:00 2001 From: oliver Date: Wed, 20 May 2026 00:04:33 +0800 Subject: [PATCH] ops: use host_name as primary key for alarm NE display Co-authored-by: Cursor --- .../tools/experts/network_ops/netx_tools.py | 8 ++++++-- runtime/workspaces/ops/ROLE_SYSTEM.en.md | 14 ++++++++------ runtime/workspaces/ops/ROLE_SYSTEM.md | 14 ++++++++------ .../ops/ops-netx-ume-playbook/SKILL.md | 19 ++++++++++--------- .../ops/ops-netx-ume-playbook/reference.md | 5 +++-- 5 files changed, 35 insertions(+), 25 deletions(-) diff --git a/runtime/tools/experts/network_ops/netx_tools.py b/runtime/tools/experts/network_ops/netx_tools.py index 897490b3..68a4a269 100644 --- a/runtime/tools/experts/network_ops/netx_tools.py +++ b/runtime/tools/experts/network_ops/netx_tools.py @@ -29,6 +29,7 @@ _PROTOCOL_KEY_ZH_TO_EN: dict[str, str] = { _UME_RAW_GROUP_FIELDS = [ "alarm_alarm_key", + "alarm_host_name", "alarm_ne_id", "alarm_object_name", "alarm_event_type", @@ -592,7 +593,8 @@ def netx_query_ume_alarms_tool() -> ToolSpec: return ToolSpec( name="netx_query_ume_alarms", description=( - "读取 netx UME 当前告警明细（实时表）；支持 severity/ne_id/keyword(含 ne_name 映射) 与分页。" + "读取 netx UME 当前告警明细（实时表）；每条含 host_name（网元主展示键，同步时已写入告警表）。" + "支持 severity/ne_id/keyword 与分页。" "当需要字段级控制或复杂分析时，优先 netx_list_ume_alarm_fields + netx_query_ume_alarms_raw/netx_sql_query_ume。" ), parameters={ @@ -725,6 +727,7 @@ def netx_query_ume_alarms_raw_tool() -> ToolSpec: presets: dict[str, list[str]] = { "brief": [ "alarm_alarm_key", + "alarm_host_name", "alarm_perceived_severity", "alarm_event_type", "alarm_last_seen_at", @@ -736,6 +739,7 @@ def netx_query_ume_alarms_raw_tool() -> ToolSpec: ], "evidence": [ "alarm_alarm_key", + "alarm_host_name", "alarm_object_name", "alarm_event_type", "alarm_native_probable_cause", @@ -944,7 +948,7 @@ def netx_aggregate_ume_alarms_raw_tool() -> ToolSpec: "group_by": { "type": "string", "enum": _UME_RAW_GROUP_FIELDS, - "description": "主分组字段（网元维度优先 ne_host_name；勿用 alarm_ne_id/ne_ne_id 作对外展示）", + "description": "主分组字段（网元主键优先 alarm_host_name 或 ne_host_name；勿用 alarm_ne_id/ne_ne_id）", }, "group_by2": {"type": "string", "enum": _UME_RAW_GROUP_FIELDS, "description": "可选第二分组字段"}, "severity": {"type": "string"}, diff --git a/runtime/workspaces/ops/ROLE_SYSTEM.en.md b/runtime/workspaces/ops/ROLE_SYSTEM.en.md index fe78a736..b67b3ed1 100644 --- a/runtime/workspaces/ops/ROLE_SYSTEM.en.md +++ b/runtime/workspaces/ops/ROLE_SYSTEM.en.md @@ -23,11 +23,13 @@ You are the ops specialist (network operations expert). ## Output format - Conclusion first, then evidence and minimal remediation steps. -## Network element display (mandatory) -- In user-visible conclusions, tables, lists, and Top-N rankings, **always use the network element name** from `ume_inventory_ne.host_name` (tool fields `ne_host_name` / inventory `host_name`). -- **Never** show raw `ne_id` (UUID) in readable output; `ne_id` is for tool filters only. -- When alarms/aggregates only have `ne_id` or `alarm_ne_id`, resolve names via `netx_get_ume_ne`, `netx_query_ume_ne_inventory`, or SQL `LEFT JOIN ume_inventory_ne ne ON ne.ne_id = a.ne_id` before answering. -- If `host_name` is missing after lookup, you may fall back to `user_label` / `ne_name` and note "host_name missing"; never fall back to bare `ne_id`. +## Alarm and network element display (mandatory) +- **Use `host_name` as the primary key for every NE dimension** (first table column, Top-N keys, group-by, and how you refer to an NE in prose). After sync, netx stores it on the alarm row — prefer: + - List/paged alarms: **`host_name`** from `netx_query_ume_alarms` + - Raw/SQL: **`alarm_host_name`** (over `ne_host_name` when both exist) +- **Never** use `ne_id` / `alarm_ne_id` (UUID) as the user-facing primary key; `ne_id` is for filters and joins only. +- If `host_name` is empty, fall back to `user_label` / `ne_name` with a "host_name missing" note — never bare `ne_id`. +- NE stats/aggregates: prefer `group_by=alarm_host_name` or `group_by=ne_host_name`; do not group by `alarm_ne_id` / `ne_ne_id` for user output. ## Required skill - For every netx/UME **alarm or NE** request, load and follow skill: `ops-netx-ume-playbook` (skill text may be Chinese; **user-facing output must still match the user's language**). @@ -37,7 +39,7 @@ You are the ops specialist (network operations expert). Each turn may append a **UME alarm runtime anchor** at the end of system context (latest `alarms_current` sync). Still call tools for alarm/NE evidence when answering. - Default UME current-alarm path; no import `batch_id`. -- `netx_query_ume_alarms`: current alarm rows (`severity` / `ne_id` / `keyword`). +- `netx_query_ume_alarms`: current alarm rows (each includes **`host_name`**; filters: `severity` / `ne_id` / `keyword`). - `netx_aggregate_ume_alarms` / `netx_run_ume_diagnostics`: aggregates and diagnostic summary. - `netx_query_ume_ne_inventory`: synced NE list (`keyword`). - `netx_get_ume_ne`: single NE by `ne_id` (includes `raw_json`). diff --git a/runtime/workspaces/ops/ROLE_SYSTEM.md b/runtime/workspaces/ops/ROLE_SYSTEM.md index ab725d46..5c681e35 100644 --- a/runtime/workspaces/ops/ROLE_SYSTEM.md +++ b/runtime/workspaces/ops/ROLE_SYSTEM.md @@ -16,11 +16,13 @@ ## 输出格式： - 先结论，再给证据与最小修复步骤。 -## 网元展示（强制） -- 面向用户的结论、表格、列表、Top 排名等，**必须使用网元名称**，以网元表 `ume_inventory_ne.host_name`（工具字段 `ne_host_name` / 清单 `host_name`）为准。 -- **禁止**在可读输出中直接展示 `ne_id`（UUID）；`ne_id` 仅可作为工具过滤参数在内部使用。 -- 告警/聚合结果若只有 `ne_id` 或 `alarm_ne_id`：必须用 `netx_get_ume_ne(ne_id=…)` 或 `netx_query_ume_ne_inventory`，或 SQL `LEFT JOIN ume_inventory_ne ne ON ne.ne_id = a.ne_id` 解析出 `host_name` 后再作答。 -- 若联查后 `host_name` 为空，可用 `user_label` / `ne_name` 作后备显示名，并注明「host_name 缺失」；仍不得回退为裸 `ne_id`。 +## 告警与网元展示（强制） +- **网元维度一律以 `host_name` 为主键展示**（表格首列、Top 排名键、分组维度、结论中的网元指称）。告警同步后 netx 已把 `host_name` 写入告警表，优先读： + - 列表/分页：`netx_query_ume_alarms` 返回的 **`host_name`** + - Raw/SQL：`alarm_host_name`（与 `ne_host_name` 同值时优先用 `alarm_host_name`） +- **禁止**用 `ne_id` / `alarm_ne_id`（UUID）作为对用户的主展示键；`ne_id` 仅用于工具过滤或内部关联。 +- 若 `host_name` 为空，再用 `user_label` / `ne_name` 并标注「host_name 缺失」；仍不得用裸 `ne_id`。 +- 按网元统计/聚合：优先 `group_by=alarm_host_name` 或 `group_by=ne_host_name`，勿按 `alarm_ne_id` / `ne_ne_id` 对外展示。 ## 必须加载技能 - 每次处理 netx/UME **告警或网元** 问题时，必须加载并遵循技能：`ops-netx-ume-playbook`。 @@ -30,7 +32,7 @@ 每轮对话 **system 末尾会自动附带当前 UME 告警运行锚点**（最近一次 `alarms_current` 同步状态），用于快速判断数据新鲜度。涉及告警/统计时仍应用工具拉明细。 - 默认使用 UME 当前告警链路，不再依赖导入批次 `batch_id`。 -- `netx_query_ume_alarms`：查询 UME 当前告警明细（支持 `severity/ne_id/keyword`）。 +- `netx_query_ume_alarms`：查询 UME 当前告警明细（每条含 **`host_name`**；支持 `severity/ne_id/keyword`）。 - `netx_aggregate_ume_alarms` / `netx_run_ume_diagnostics`：查询 UME 聚合与诊断摘要。 - `netx_query_ume_ne_inventory`：分页查询已同步的 UME 网元清单（可选 `keyword`）。 - `netx_get_ume_ne`：按 `ne_id`（UUID）取单网元详情（含 `raw_json`）。 diff --git a/skills/_workspace/ops/ops-netx-ume-playbook/SKILL.md b/skills/_workspace/ops/ops-netx-ume-playbook/SKILL.md index 3468e4ca..fd0bb931 100644 --- a/skills/_workspace/ops/ops-netx-ume-playbook/SKILL.md +++ b/skills/_workspace/ops/ops-netx-ume-playbook/SKILL.md @@ -75,19 +75,20 @@ description: 面向 ops 专家的 netx UME 运维作业手册。覆盖告警查 - 没有工具证据时，不得臆测告警事实。 - **用户用英文提问时（强制）**：回复中**不得出现任何汉字**；工具里的中文告警字段（原因、对象名、描述等）必须先**译成英文**再写入表格或正文，禁止原样粘贴；网元名用 `host_name`，协议类维度用英文类别名（Other/Clock/…）。 -### 网元名称（强制） +### 网元展示：以 host_name 为主键（强制） -- 凡涉及网元，用户可见文本一律用 **网元名称** = 网元表 `host_name`（告警 raw：`ne_host_name`；清单/`netx_get_ume_ne`：`host_name`）。 -- **禁止**在表格、结论、Top 列表里写裸 `ne_id`（UUID）。 -- 仅有 `ne_id` 时必须先解析名称，再输出： - 1. 少量 ID：`netx_get_ume_ne` 逐条取 `host_name`； - 2. 多条 / 统计：`netx_query_ume_ne_inventory` 分页，或 `netx_sql_query_ume` 中 `JOIN ume_inventory_ne ne ON ne.ne_id = …` 选出 `ne.host_name`； - 3. 原始告警证据：`netx_query_ume_alarms_raw` 的 `select_fields` 或 `field_preset` 须含 `ne_host_name`（勿只取 `alarm_ne_id`）。 -- `host_name` 为空时可用 `user_label` / `ne_name` 作显示后备，并标注缺失；仍不得用 `ne_id` 顶替。 +- **告警/统计里标识网元时，主键永远是 `host_name`**（主机名），不是 `ne_id`。表格第一列、Top 网元、分组键、结论里的网元名都用它。 +- **优先数据源**（同步时已写入告警表）： + - `netx_query_ume_alarms` → 字段 **`host_name`** + - `netx_query_ume_alarms_raw` → **`alarm_host_name`**（`select_fields` / `brief` / `evidence` 预设已包含） + - 聚合 → `group_by=alarm_host_name` 或 `group_by=ne_host_name` +- **禁止**对用户展示裸 `ne_id` / `alarm_ne_id`；`ne_id` 仅作查询参数。 +- `host_name` 为空时：用 `user_label` / `ne_name` 并注明缺失；仍不得退回 UUID。 +- 仅当列表接口缺 `host_name` 时再 `netx_get_ume_ne` / 网元清单 / SQL JOIN 补全。 ## 推荐分析模式 -- 高风险网元：`netx_aggregate_ume_alarms_raw` + `group_by=ne_host_name`（勿按 `alarm_ne_id` / `ne_ne_id` 分组对外展示）+ 严重度过滤。 +- 高风险网元：`netx_aggregate_ume_alarms_raw` + `group_by=alarm_host_name`（首选）或 `ne_host_name` + 严重度过滤；勿按 `alarm_ne_id` 分组对外展示。 - 严重度分布：`group_by=alarm_perceived_severity`。 - 事件趋势切片：raw 查询中组合 `time_from/time_to` + `event_type`。 diff --git a/skills/_workspace/ops/ops-netx-ume-playbook/reference.md b/skills/_workspace/ops/ops-netx-ume-playbook/reference.md index 8f63a325..cc6fe016 100644 --- a/skills/_workspace/ops/ops-netx-ume-playbook/reference.md +++ b/skills/_workspace/ops/ops-netx-ume-playbook/reference.md @@ -23,7 +23,8 @@ - `alarm_alarm_key` - `alarm_perceived_severity` - `alarm_last_seen_at` - - `ne_host_name`（网元名称，对外展示首选） + - `alarm_host_name`（告警表已冗余的网元主机名，**对外展示主键，放首列**） + - `ne_host_name`（与上同义，优先 `alarm_host_name`） - `ne_user_label` - `ne_ip_address` - **禁止**在用户可见输出中只列 `alarm_ne_id`；需要网元身份时必须带 `ne_host_name` 或先联查网元表。 @@ -33,7 +34,7 @@ - 工具：`netx_aggregate_ume_alarms_raw` - 常用分组： - `group_by=alarm_perceived_severity` - - `group_by=ne_host_name`（网元名称；勿用 `alarm_ne_id` / `ne_ne_id` 作对外维度） + - `group_by=alarm_host_name` 或 `group_by=ne_host_name`（网元主键；勿用 `alarm_ne_id` / `ne_ne_id`） - `group_by=alarm_event_type` - `group_by=ne_connection_status` - `group_by=alarm_perceived_severity, group_by2=ne_host_name`