feat(ops): add UME alarm playbook skill and tool guardrails

- Add ops-netx-ume-playbook skill (zh-CN) with presets, paging and SQL safety defaults
- Strengthen ops identity disclosure rules (always 'oclaw智能运维')
- Improve netx UME anchor context and add raw/aggregate/SQL tooling ergonomics

Co-authored-by: Cursor <cursoragent@cursor.com>

runtime/tools/experts/network_ops/netx_tools.py

@@ -16,6 +16,42 @@ import httpx
 
 from oclaw.runtime.tools.base import ToolSpec
 
+_UME_RAW_GROUP_FIELDS = [
+    "alarm_alarm_key",
+    "alarm_ne_id",
+    "alarm_object_name",
+    "alarm_event_type",
+    "alarm_native_probable_cause",
+    "alarm_perceived_severity",
+    "alarm_is_cleared",
+    "alarm_time_created",
+    "alarm_root_cause_alarm_indication",
+    "ne_ne_id",
+    "ne_ne_name",
+    "ne_user_label",
+    "ne_ip_address",
+    "ne_ipv6_address",
+    "ne_ne_type",
+    "ne_device_level",
+    "ne_host_name",
+    "ne_location",
+    "ne_hardware_version",
+    "ne_loopback",
+    "ne_consistent_state",
+    "ne_interface_version",
+    "ne_mac",
+    "ne_admin_status",
+    "ne_address_type",
+    "ne_connection_status",
+    "ne_maintain_status",
+    "ne_net_mask",
+    "ne_create_time",
+    "ne_creator",
+    "ne_vendor",
+    "ne_source_type",
+    "ne_exists",
+]
+
 
 def _netx_base_url() -> str:
     return (os.getenv("OCLAW_NETX_BASE_URL") or "http://127.0.0.1:8890").strip().rstrip("/")
@@ -62,6 +98,30 @@ def _resolve_latest_import_batch_id() -> dict[str, Any]:
     return {"ok": True, "batch_id": bid, "batch_row": first}
 
 
+def _resolve_ume_anchor() -> dict[str, Any]:
+    """Resolve current UME alarm anchor from netx sync status."""
+    r = _http_json("GET", "/v1/ume/sync/status", params={"page": 1, "page_size": 20})
+    if not r.get("ok"):
+        return {"ok": False, "error": "netx_ume_sync_status_failed", "detail": r.get("detail"), "upstream": r}
+    data = r.get("data") or {}
+    latest = data.get("latest_by_domain") if isinstance(data.get("latest_by_domain"), dict) else {}
+    cur = latest.get("alarms_current") if isinstance(latest.get("alarms_current"), dict) else {}
+    return {
+        "ok": True,
+        "anchor": {
+            "domain": "alarms_current",
+            "status": str(cur.get("status") or ""),
+            "trigger_mode": str(cur.get("trigger_mode") or ""),
+            "started_at": str(cur.get("started_at") or ""),
+            "ended_at": str(cur.get("ended_at") or ""),
+            "pulled_count": int(cur.get("pulled_count") or 0),
+            "inserted_count": int(cur.get("inserted_count") or 0),
+            "updated_count": int(cur.get("updated_count") or 0),
+            "error_message": str(cur.get("error_message") or ""),
+        },
+    }
+
+
 _OPS_NETX_SYS_CTX_LOCK = threading.Lock()
 # Lang code -> (monotonic_ts, formatted extension text); short TTL to avoid hammering netx each tool round.
 _OPS_NETX_SYS_CTX_CACHE: dict[str, tuple[float, str]] = {}
@@ -70,35 +130,45 @@ _OPS_NETX_SYS_CTX_TTL_SEC = 5.0
 
 def _format_ops_netx_system_extension(r: dict[str, Any], *, lang_en: bool) -> str:
     if r.get("ok"):
-        bid = str(r.get("batch_id") or "")
-        row = r.get("batch_row") if isinstance(r.get("batch_row"), dict) else {}
-        created = str(row.get("created_at") or "")
-        src = str(row.get("source_file") or "")
+        row = r.get("anchor") if isinstance(r.get("anchor"), dict) else {}
         status = str(row.get("status") or "")
-        total = row.get("total_rows")
+        mode = str(row.get("trigger_mode") or "")
+        started = str(row.get("started_at") or "")
+        ended = str(row.get("ended_at") or "")
+        pulled = int(row.get("pulled_count") or 0)
+        inserted = int(row.get("inserted_count") or 0)
+        updated = int(row.get("updated_count") or 0)
+        err = str(row.get("error_message") or "").strip()
         lines_en = [
-            "[Netx alarm import anchor]",
-            f"- batch_id: {bid}",
-            f"- source_file: {src}",
-            f"- created_at: {created}",
+            "[Netx UME current-alarms anchor]",
+            f"- status: {status}",
+            f"- trigger_mode: {mode}",
+            f"- started_at: {started}",
+            f"- ended_at: {ended}",
         ]
         lines_zh = [
-            "[当前 netx 告警导入锚点]",
-            f"- batch_id: {bid}",
-            f"- 源文件: {src}",
-            f"- 导入时间: {created}",
+            "[当前 netx UME告警锚点]",
+            f"- 状态: {status}",
+            f"- 触发方式: {mode}",
+            f"- 开始时间: {started}",
+            f"- 结束时间: {ended}",
         ]
-        if status:
-            (lines_en if lang_en else lines_zh).append(f"- status: {status}" if lang_en else f"- 状态: {status}")
-        if total is not None:
-            (lines_en if lang_en else lines_zh).append(f"- rows: {total}" if lang_en else f"- 行数: {total}")
+        (lines_en if lang_en else lines_zh).append(
+            f"- pulled/inserted/updated: {pulled}/{inserted}/{updated}"
+            if lang_en
+            else f"- 拉取/新增/更新: {pulled}/{inserted}/{updated}"
+        )
+        if err:
+            (lines_en if lang_en else lines_zh).append(
+                f"- last_error: {err[:200]}" if lang_en else f"- 最近错误: {err[:200]}"
+            )
         tail_en = (
-            "- tools: netx_query_alarms, netx_aggregate_alarms, netx_run_diagnostics (pass batch_id above)\n"
-            "- note: numbers below are not alarm facts—call tools for evidence."
+            "- tools: netx_query_ume_alarms, netx_aggregate_ume_alarms, netx_run_ume_diagnostics\n"
+            "- note: this is only runtime anchor; use tools for alarm evidence."
         )
         tail_zh = (
-            "- 工具: netx_query_alarms、netx_aggregate_alarms、netx_run_diagnostics（使用上述 batch_id）\n"
-            "- 说明: 此处仅为批次锚点；具体告警必须以工具返回为准，勿臆测。"
+            "- 工具: netx_query_ume_alarms、netx_aggregate_ume_alarms、netx_run_ume_diagnostics\n"
+            "- 说明: 此处仅为运行锚点；具体告警必须以工具返回为准，勿臆测。"
         )
         return "\n".join(lines_en + [tail_en]) if lang_en else "\n".join(lines_zh + [tail_zh])
     err = str(r.get("error") or "")
@@ -117,13 +187,13 @@ def _format_ops_netx_system_extension(r: dict[str, Any], *, lang_en: bool) -> st
         )
     if lang_en:
         return (
-            "[Netx alarm import anchor]\n"
+            "[Netx UME current-alarms anchor]\n"
             f"- error: {err}\n"
             f"- detail: {detail}\n"
             "- fix: check OCLAW_NETX_BASE_URL and that netx API is reachable."
         )
     return (
-        "[当前 netx 告警导入锚点]\n"
+        "[当前 netx UME告警锚点]\n"
         f"- 错误: {err}\n"
         f"- 详情: {detail}\n"
         "- 处理: 检查 OCLAW_NETX_BASE_URL 与 netx 服务是否可达。"
@@ -144,7 +214,7 @@ def ops_netx_system_context_extension(*, lang: str = "zh") -> str:
         hit = _OPS_NETX_SYS_CTX_CACHE.get(lk)
         if hit and (now - hit[0]) < _OPS_NETX_SYS_CTX_TTL_SEC:
             return hit[1]
-    r = _resolve_latest_import_batch_id()
+    r = _resolve_ume_anchor()
     text = _format_ops_netx_system_extension(r, lang_en=lang_en)
     store_ts = time.monotonic()
     with _OPS_NETX_SYS_CTX_LOCK:
@@ -455,12 +525,348 @@ def netx_sql_query_tool() -> ToolSpec:
     )
 
 
+def netx_query_ume_alarms_tool() -> ToolSpec:
+    """Paginated UME current alarms from netx."""
+
+    def handler(args: dict[str, Any]) -> dict[str, Any]:
+        # Guardrail: avoid accidental full scans by endless paging.
+        page = max(1, int(args.get("page") or 1))
+        if page > 2:
+            page = 2
+        page_size = min(500, max(1, int(args.get("page_size") or 50)))
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        if str(args.get("severity") or "").strip():
+            params["severity"] = str(args.get("severity")).strip()
+        ne_name = str(args.get("ne_name") or "").strip()
+        keyword = str(args.get("keyword") or "").strip()
+        if keyword:
+            params["keyword"] = keyword
+        elif ne_name:
+            params["keyword"] = ne_name
+        if str(args.get("ne_id") or "").strip():
+            params["ne_id"] = str(args.get("ne_id")).strip()
+        return _http_json("GET", "/v1/ume/alarms", params=params)
+
+    return ToolSpec(
+        name="netx_query_ume_alarms",
+        description=(
+            "读取 netx UME 当前告警明细（实时表）；支持 severity/ne_id/keyword(含 ne_name 映射) 与分页。"
+            "当需要字段级控制或复杂分析时，优先 netx_list_ume_alarm_fields + netx_query_ume_alarms_raw/netx_sql_query_ume。"
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "severity": {"type": "string"},
+                "ne_id": {"type": "string"},
+                "ne_name": {"type": "string", "description": "兼容参数，会映射到 keyword"},
+                "keyword": {"type": "string", "description": "按网元名/标签/IP/对象名等关键字检索"},
+                "page": {"type": "integer", "minimum": 1, "default": 1},
+                "page_size": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50},
+            },
+            "required": [],
+            "additionalProperties": False,
+        },
+        handler=handler,
+        tags=frozenset({"netx", "ops", "ume", "alarms", "read_only"}),
+        risk_level="low",
+        read_only=True,
+    )
+
+
+def netx_aggregate_ume_alarms_tool() -> ToolSpec:
+    """Aggregate UME current alarms from netx."""
+
+    def handler(args: dict[str, Any]) -> dict[str, Any]:
+        _ = args
+        return _http_json("GET", "/v1/ume/alarms/aggregate", params=None)
+
+    return ToolSpec(
+        name="netx_aggregate_ume_alarms",
+        description="读取 netx UME 当前告警聚合（by_severity/by_ne）。",
+        parameters={"type": "object", "properties": {}, "required": [], "additionalProperties": False},
+        handler=handler,
+        tags=frozenset({"netx", "ops", "ume", "alarms", "aggregate", "read_only"}),
+        risk_level="low",
+        read_only=True,
+    )
+
+
+def netx_run_ume_diagnostics_tool() -> ToolSpec:
+    """Diagnostics summary for UME current alarms."""
+
+    def handler(args: dict[str, Any]) -> dict[str, Any]:
+        _ = args
+        return _http_json("GET", "/v1/ume/diagnostics", params=None)
+
+    return ToolSpec(
+        name="netx_run_ume_diagnostics",
+        description="读取 netx UME 告警诊断摘要（级别分布、Top 告警码、Top 网元、协议归类）。",
+        parameters={"type": "object", "properties": {}, "required": [], "additionalProperties": False},
+        handler=handler,
+        tags=frozenset({"netx", "ops", "ume", "diagnostics", "read_only"}),
+        risk_level="low",
+        read_only=True,
+    )
+
+
+def netx_query_ume_alarms_raw_tool() -> ToolSpec:
+    """Power query UME current alarms with full alarm+NE fields."""
+
+    presets: dict[str, list[str]] = {
+        "brief": [
+            "alarm_alarm_key",
+            "alarm_perceived_severity",
+            "alarm_event_type",
+            "alarm_last_seen_at",
+            "ne_user_label",
+            "ne_ne_name",
+            "ne_ip_address",
+            "ne_exists",
+        ],
+        "evidence": [
+            "alarm_alarm_key",
+            "alarm_ne_id",
+            "alarm_object_name",
+            "alarm_event_type",
+            "alarm_native_probable_cause",
+            "alarm_perceived_severity",
+            "alarm_is_cleared",
+            "alarm_time_created",
+            "alarm_last_seen_at",
+            "ne_user_label",
+            "ne_ne_name",
+            "ne_ip_address",
+            "ne_connection_status",
+            "ne_exists",
+        ],
+        "ne_debug": [
+            "alarm_alarm_key",
+            "alarm_ne_id",
+            "alarm_perceived_severity",
+            "alarm_last_seen_at",
+            "ne_user_label",
+            "ne_ne_name",
+            "ne_ip_address",
+            "ne_ipv6_address",
+            "ne_device_level",
+            "ne_host_name",
+            "ne_connection_status",
+            "ne_admin_status",
+            "ne_address_type",
+            "ne_maintain_status",
+            "ne_exists",
+        ],
+    }
+
+    def handler(args: dict[str, Any]) -> dict[str, Any]:
+        page = max(1, int(args.get("page") or 1))
+        page_size = min(500, max(1, int(args.get("page_size") or 50)))
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        for k in ("severity", "is_cleared", "ne_id", "event_type", "keyword", "time_from", "time_to", "order_by", "order"):
+            v = str(args.get(k) or "").strip()
+            if v:
+                params[k] = v
+        sf = args.get("select_fields")
+        fields: list[str] = []
+        if isinstance(sf, list):
+            fields = [str(x).strip() for x in sf if str(x).strip()]
+        if not fields:
+            preset = str(args.get("field_preset") or "").strip().lower()
+            fields = list(presets.get(preset) or [])
+        if fields:
+            params["select_fields"] = ",".join(fields)
+        return _http_json("GET", "/v1/ume/alarms/raw", params=params)
+
+    return ToolSpec(
+        name="netx_query_ume_alarms_raw",
+        description=(
+            "自由查询 netx UME 当前告警原始视图，返回 alarm_* + ne_* 全字段。"
+            "可按 severity/is_cleared/ne_id/event_type/keyword/time_from/time_to 过滤，支持排序分页。"
+            "select_fields 可按需指定返回字段，降低输出体积。"
+            "field_preset 可快速选用默认字段集（brief/evidence/ne_debug）。"
+            "建议先调用 netx_list_ume_alarm_fields 查看可用字段。"
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "severity": {"type": "string"},
+                "is_cleared": {"type": "string"},
+                "ne_id": {"type": "string"},
+                "event_type": {"type": "string"},
+                "keyword": {"type": "string"},
+                "time_from": {"type": "string", "description": "ISO8601 时间下界（按 last_seen_at）"},
+                "time_to": {"type": "string", "description": "ISO8601 时间上界（按 last_seen_at）"},
+                "order_by": {"type": "string", "enum": ["last_seen_at", "time_created", "perceived_severity", "event_type", "ne_id"]},
+                "order": {"type": "string", "enum": ["asc", "desc"]},
+                "select_fields": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "可选返回字段，如 alarm_alarm_key/ne_user_label/ne_exists",
+                },
+                "field_preset": {
+                    "type": "string",
+                    "enum": ["brief", "evidence", "ne_debug"],
+                    "description": "字段集预设；当未传 select_fields 时生效",
+                },
+                "page": {"type": "integer", "minimum": 1, "default": 1},
+                "page_size": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50},
+            },
+            "required": [],
+            "additionalProperties": False,
+        },
+        handler=handler,
+        tags=frozenset({"netx", "ops", "ume", "alarms", "power_query", "read_only"}),
+        risk_level="low",
+        read_only=True,
+    )
+
+
+def netx_list_ume_alarm_fields_tool() -> ToolSpec:
+    """List field names for UME raw alarm query."""
+
+    def handler(args: dict[str, Any]) -> dict[str, Any]:
+        _ = args
+        return _http_json("GET", "/v1/ume/alarms/fields", params=None)
+
+    return ToolSpec(
+        name="netx_list_ume_alarm_fields",
+        description="列出 UME 当前告警 raw 查询可用字段（alarm_fields/ne_fields/order_by_allowed）。",
+        parameters={"type": "object", "properties": {}, "required": [], "additionalProperties": False},
+        handler=handler,
+        tags=frozenset({"netx", "ops", "ume", "alarms", "schema", "read_only"}),
+        risk_level="low",
+        read_only=True,
+    )
+
+
+def netx_sql_query_ume_tool() -> ToolSpec:
+    """Execute read-only SQL on UME tables in netx."""
+
+    def handler(args: dict[str, Any]) -> dict[str, Any]:
+        sql = str(args.get("sql") or "").strip()
+        limit = max(1, min(2000, int(args.get("limit") or 200)))
+        statement_timeout_ms = max(0, min(30000, int(args.get("statement_timeout_ms") or 0)))
+        if not sql:
+            return {"ok": False, "error": "sql_required"}
+        base = _netx_base_url()
+        url = f"{base}/v1/sql/ume_query"
+        try:
+            with httpx.Client(timeout=60.0) as client:
+                resp = client.post(
+                    url,
+                    json={"sql": sql, "limit": limit, "statement_timeout_ms": statement_timeout_ms},
+                    headers=_netx_headers(),
+                )
+                text = resp.text
+                if not resp.is_success:
+                    return {"ok": False, "error": f"netx_http_{resp.status_code}", "detail": text[:800]}
+                data = resp.json() if text else {}
+                return {"ok": True, "data": data if isinstance(data, dict) else {"raw": data}}
+        except Exception as exc:
+            return {"ok": False, "error": "netx_request_failed", "detail": str(exc)[:800]}
+
+    return ToolSpec(
+        name="netx_sql_query_ume",
+        description=(
+            "在 netx 上执行 UME 只读 SQL（服务端强制 SELECT-only、单语句、限制表为 "
+            "ume_alarms_current/ume_inventory_ne，并强制 limit）。"
+            "推荐默认模板：设置 statement_timeout_ms=8000，且 SQL 带时间窗过滤（last_seen_at >= now() - interval '30 minutes'）。"
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "sql": {"type": "string", "description": "只读 SELECT SQL；仅允许 UME 当前告警与网元表"},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 2000, "default": 200},
+                "statement_timeout_ms": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 30000,
+                    "default": 0,
+                    "description": "可选查询超时(ms)，0表示使用数据库默认超时",
+                },
+            },
+            "required": ["sql"],
+            "additionalProperties": False,
+        },
+        handler=handler,
+        tags=frozenset({"netx", "ops", "ume", "sql", "power_query", "read_only"}),
+        risk_level="low",
+        read_only=True,
+    )
+
+
+def netx_aggregate_ume_alarms_raw_tool() -> ToolSpec:
+    """Dynamic aggregation on UME raw fields."""
+
+    def handler(args: dict[str, Any]) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        for k in (
+            "group_by",
+            "group_by2",
+            "severity",
+            "is_cleared",
+            "ne_id",
+            "event_type",
+            "keyword",
+            "time_from",
+            "time_to",
+            "limit",
+        ):
+            v = args.get(k)
+            if v is None:
+                continue
+            sv = str(v).strip()
+            if sv:
+                params[k] = sv
+        return _http_json("GET", "/v1/ume/alarms/aggregate/raw", params=params)
+
+    return ToolSpec(
+        name="netx_aggregate_ume_alarms_raw",
+        description=(
+            "按 UME raw 字段做动态聚合（group_by/group_by2），支持与 raw 同口径过滤条件。"
+            "group_by 需使用 alarm_*/ne_* 字段，建议先 netx_list_ume_alarm_fields。"
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "group_by": {
+                    "type": "string",
+                    "enum": _UME_RAW_GROUP_FIELDS,
+                    "description": "主分组字段（建议常用 alarm_perceived_severity / ne_user_label / ne_ne_name）",
+                },
+                "group_by2": {"type": "string", "enum": _UME_RAW_GROUP_FIELDS, "description": "可选第二分组字段"},
+                "severity": {"type": "string"},
+                "is_cleared": {"type": "string"},
+                "ne_id": {"type": "string"},
+                "event_type": {"type": "string"},
+                "keyword": {"type": "string"},
+                "time_from": {"type": "string"},
+                "time_to": {"type": "string"},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 2000, "default": 200},
+            },
+            "required": ["group_by"],
+            "additionalProperties": False,
+        },
+        handler=handler,
+        tags=frozenset({"netx", "ops", "ume", "alarms", "aggregate", "power_query", "read_only"}),
+        risk_level="low",
+        read_only=True,
+    )
+
+
 __all__ = [
-    "netx_query_alarms_tool",
-    "netx_aggregate_alarms_tool",
-    "netx_run_diagnostics_tool",
-    "netx_list_import_batches_tool",
-    "netx_list_alarm_fields_tool",
-    "netx_query_alarms_raw_tool",
-    "netx_sql_query_tool",
+    # "netx_query_alarms_tool",
+    # "netx_aggregate_alarms_tool",
+    # "netx_run_diagnostics_tool",
+    # "netx_list_import_batches_tool",
+    # "netx_list_alarm_fields_tool",
+    # "netx_query_alarms_raw_tool",
+    # "netx_sql_query_tool",
+    "netx_query_ume_alarms_tool",
+    "netx_aggregate_ume_alarms_tool",
+    "netx_run_ume_diagnostics_tool",
+    "netx_query_ume_alarms_raw_tool",
+    "netx_aggregate_ume_alarms_raw_tool",
+    "netx_list_ume_alarm_fields_tool",
+    "netx_sql_query_ume_tool",
 ]