MCP: add bizMonitor server, align ops/topology tools, harden CLI exec

- New packages/netx-bizmonitor-mcp: 8 read-only cutover/biz-state tools
  mirroring the netxops bizMonitor group.
- Align netx-mcp (15) and netx-topology-mcp (16) with backend HTTP
  contracts; surface partial batch failures as tool errors.
- CLI hard gate: single-line show/display only; exec job IDs, path
  containment, owner and ne:exec checks.
- Cisco IOSv collection: stable prompt/echo handling over CR.
- Remove legacy netx_api/mcp and mcp_server.py; add mcp.all.json;
  sync skills and docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

skills/README.md

@@ -6,7 +6,7 @@
 |-------|--------------|----------------------------------------|
 | `ops` | `ops/netx-ops/` | NMS 告警/库存/SQL + managed CLI + `findTopologyPaths` |
 | `topology` | `topology/netx-topology/` | 画布 / Fabric / dual_unit / 布图 |
-| `biz-monitor` | `biz-monitor/netx-biz-monitor/` | 割接/业务监控只读分析（**netxops 宿主工具**直连 REST；非 netx-mcp） |
+| `bizMonitor` | `biz-monitor/netx-biz-monitor/` | 割接/业务监控只读分析（独立 `netx-bizmonitor-mcp` 或 netxops 宿主工具） |
 | `biz-state` | `biz-state/netx-biz-state/` | 状态监控：TextFSM / parser / Profile（Cursor Agent；无 DSH 工具） |
 
 ## DSH 怎么用
@@ -14,8 +14,8 @@
 1. 运行时优先：`NETX_SKILLS_ROOT` → 旁路 `../netx/skills` → 包内 `presets/netxops/skills`
 2. 发 npm 前：`powershell -File netxops/scripts/sync-skills-from-netx.ps1`
 3. Settings → 能力组开关：开哪组就注册哪组的 **tools + 对应 skill**（含 **bizMonitor**）
-4. 其它预设可强制挂：`dsh-netxops/tools-ops|topology|biz-monitor`（旧别名 `tools-nms` / `tools-common` → ops）
+4. 其它预设可强制挂：`dsh-netxops/tools-ops|topology|biz-monitor`
 
-MCP / Cursor：skill 根直接指本目录。MCP 包内不镜像 skills。业务监控分析工具只在 **netxops**，不要往 netx-mcp 加。
+MCP / Cursor：skill 根直接指本目录，包内不镜像 skills。不装 netxops 时，分别使用 `netx-mcp`（15 工具）、`netx-topology-mcp`（16 工具）和 `netx-bizmonitor-mcp`（8 工具）；配置见根 `mcp.all.json`。独立包均通过 HTTP 访问 netx，不直连数据库。
 
 **Cursor Agent**：加 biz_state 监控命令时启用或点名 **netx-biz-state**（`skills/biz-state/netx-biz-state/`）。

skills/biz-monitor/netx-biz-monitor/SKILL.md

@@ -1,32 +1,30 @@
 ---
 name: netx-biz-monitor
 description: >-
-  Overnight cutover / biz_state monitor analysis via netxops host tools
-  (netx__listBizMonitors / listBizMonitorBatches / getBizMonitor*). List
-  projects/tasks then batches when no id is given; read definitions, board,
-  reds/diffs with evidence (device-raw A/B, show commands), and judge tool
-  false-positive vs real business fault. Does not create templates/tasks.
+  通过独立 netx-bizmonitor-mcp 或 netxops 分析割接与业务状态。
+  无 ID 先查目录和批次，结合看板、变红项、双侧原始 A/B 键和采集命令原文判断故障。
+  只读已有项目与评价结果，不创建模板、触发采集、执行评价或关闭红票。
 ---
 
 # netx-biz-monitor（割接 / 业务监控只读分析）
 
 人配好监控与任务；AI 当晚做归因。  
-工具在 **netxops**（`netx__*`），直连 netx REST，**不是** netx-mcp。
+独立 **netx-bizmonitor-mcp** 提供下表裸名；netxops 使用 `netx__` 加同名。两者均访问 netx REST，需 `biz-monitor:read`。安装和三组配置见 [MCP_BIZMONITOR.md](../../../docs/MCP_BIZMONITOR.md)。
 
 ## 工具（能力组 `bizMonitor`）
 
 | 工具 | 用途 |
 |------|------|
-| `netx__listBizMonitors` | **入口目录**：列出割接/监控对比项目 + 业务监控任务（**无需** project_id） |
-| `netx__listBizMonitorBatches` | **批次目录**：`project_id`→割接批次；`task_id`→采集批次；`kind=runs`→evaluate run |
-| `netx__getBizMonitorContext` | 任务定义：项目、监控/对比模板、归一化规则、端口映射、关联任务与命令项 |
-| `netx__getBizMonitorBoard` | 批次进度、evaluate run、sheet 卡、verdict 统计 |
-| `netx__listBizMonitorReds` | 红单 + **evidence** |
-| `netx__getBizMonitorDiffs` | run 明细（可滤 color=red） |
-| `netx__getBizCollectBatch` | 某次采集：commands / metrics |
-| `netx__getBizCollectCommandRaw` | 单命令全量 show 输出 |
+| `listBizMonitors` | **入口目录**：列出割接/监控对比项目 + 业务监控任务（**无需** project_id） |
+| `listBizMonitorBatches` | **批次目录**：`project_id`→割接批次；`task_id`→采集批次；`batch_id,kind=runs`→evaluate run |
+| `getBizMonitorContext` | 任务定义：项目、监控/对比模板、归一化规则、端口映射、关联任务与命令项 |
+| `getBizMonitorBoard` | 批次进度、evaluate run、sheet 卡、verdict 统计 |
+| `listBizMonitorReds` | 红单 + **evidence** |
+| `getBizMonitorDiffs` | run 明细，`color=red`；`offset/limit` 分页；`q` 为关键词 |
+| `getBizCollectBatch` | 采集工作簿摘要、commands 和 sheet 目录；不含全部指标行或原文 |
+| `getBizCollectCommandRaw` | 以采集 batch_id + command_id 获取单命令原文，按需调用，可能很大 |
 
-交叉验证真障时再用 ops：`netx__execManagedNe` / 拓扑路径。
+交叉验证真障时再用 ops 的 `execManagedNe` / 拓扑路径。独立 MCP 仅允许单行 `show` / `display`，不执行配置或 shell 脚本。
 
 ## 字段约定（必守）
 
@@ -41,9 +39,9 @@ description: >-
 2. `listBizMonitorBatches(project_id)` 或 `(task_id)` — 拿到 **完整 batch_id**；需要 run 时再 `kind=runs` / `include_runs`  
 3. `getBizMonitorContext(project_id)` — 弄清盯什么  
 4. `getBizMonitorBoard(batch_id)` — 进度 / missing / skipped  
-5. `listBizMonitorReds` 或 `getBizMonitorDiffs(color=red)`  
+5. `listBizMonitorReds` 或 `getBizMonitorDiffs(run_id,color=red,limit=100,offset=0)`；按 total 翻页，不能只看第一页就宣称全部红项。
 6. 看 evidence：parse 失败？current_missing？映射 miss？归一化误伤？  
-7. 需要原文 → `getBizCollectCommandRaw`  
+7. 从差异 evidence 的 collect/command 取两侧**采集** batch_id/command_id → `getBizCollectCommandRaw`；若证据不全，用对应 task_id 查采集批次，再 getBizCollectBatch 查命令。不要把割接 batch_id 当成采集 batch_id。
 8. 像真障 → `execManagedNe` 现场核对  
 
 ## Verdict 速查（skill 解释，工具不硬编码）
@@ -64,3 +62,5 @@ description: >-
 4. 再谈真实业务问题  
 
 配置整改与关红单由人做；本 skill **只读分析**。
+
+目录或批次为空时，明确说明没有可评价的数据；不把空红票当作割接通过。run 尚未完成或存在 current_missing/采集失败时，不给通过结论。工具本身不启动 evaluate；需要人先在 Web 完成定义、采集和评价。`old_key/new_key` 是设备原始端口；例：归一化和映射将 GE-old 匹配到 xgei-new，结论仍分别展示 GE-old 与 xgei-new，不能用内部匹配键替代。

skills/ops/netx-ops/SKILL.md

@@ -8,7 +8,7 @@ description: netx 运维：告警、网元、只读 CLI。
 处理 netx **告警 / 网元清单 / 只读 CLI** 时遵循本手册。  
 画布布图不在本 skill（见 **netx-topology**）。本手册里的「路径」仅指 `findTopologyPaths` 查两端关联。
 
-**工具名**：DSH 为 `netx__` + stem（如 `netx__queryNmsAlarms`）；MCP 多为同名裸 stem。下文一律写 stem。
+**工具名**：DSH 为 `netx__` + stem（如 `netx__queryNmsAlarms`）；独立 `netx-mcp` 使用同名裸 stem，共 15 个。下文一律写 stem。模型入参只用 `nms_ne_id/nms_ne_ids`；旧 `ume_*`、getManagedNe 的 `id/managed_ne_id` 别名已删除。
 
 **两套「一批」（勿混）：**
 
@@ -23,7 +23,7 @@ description: netx 运维：告警、网元、只读 CLI。
 
 ## 1. 总原则
 
-1. **先新鲜度，再结论**：`runNmsDiagnostics` 或 `aggregateNmsAlarms` → 读 `meta.last_seen_*`。过旧则按快照：时间窗落在 min~max 内，禁止默认「现在−30 分钟」。
+1. **先新鲜度，再结论**：`runNmsDiagnostics` → 读全库 `meta.last_seen_*`。用户问最近一小时则按用户时区查询真实时间窗；若为空且快照过旧，只能说当前数据无法判断。可另按快照 max 前一小时补充历史分析，明确日期，不冒充当前告警。带过滤的 aggregate 元数据只代表过滤后的窗口。
 2. **证据优先**：有告警须有级别计数和/或 Top `host_name`；否则写「证据不足」，禁止臆造根因。
 3. **对用户**：只展示 **host_name**；**严禁**出现任何 UUID/`ne_id`。无 `host_name` 的行当垃圾丢弃（不顶替 label、不提「缺失」）。工具入参仍可用 id，但不得写入对用户可见正文。
 4. **短问**：能 ≤3 次工具调用就闭环的，先聚合/过滤，禁止无过滤翻全库。复杂关联（dying gasp、A<>B CLI）不受 3 次硬顶，但仍须有过滤与目标。
@@ -67,7 +67,10 @@ description: netx 运维：告警、网元、只读 CLI。
 - 命令相同：`nms_ne_ids` 或 `ne_ids` + 共享 `commands`
 - 命令不同（厂商/角色不同）：`targets=[{nms_ne_id|ne_id, commands:[…]}, …]`，仍一次调用
 - 超时：加大 `read_timeout_sec` 或减条数；禁止同参盲重试
-- 只读：`show` / `display` / `ping` / `traceroute` 及带 `?` 的探索；配置类不做
+- 独立 MCP 只允许单行 `show` / `display`，支持只读输出过滤和 `?` 探索；禁止配置、shell、重定向、命令拼接。后端 `linux_shell/unrestricted` 不能解除 MCP 门禁。
+- `async=true` 或多台自动异步返回 job_id 仅代表开始；约 5 秒后用 `getNeExecJob` 有界轮询，期间可继续独立工作。单台须 `terminal=true` 且 `result.ok=true`；批量还须核对 `result.summary.failed=0` 和每条 `result.results[].ok=true`。`status=succeeded` / `result.ok=true` 仍可能是部分成功，要分别报告成功和失败目标。连接失败/timeout 不能当作登录成功，也不要重提相同 job 或整批重跑已成功设备。
+- `getManagedNe.capability` 是后端设备能力；独立 MCP 仍只允许单行 show/display，后端 Linux/RouterOS 开放策略不会放宽此门禁。NAS/VPS/RouterOS 原生 CLI 当前不能通过这组 MCP 执行；连接测试须明确另用 netx Web/API，不能把 API 登录证据写成 MCP 原生 CLI 执行成功。
+- 同一 IP 有多个纳管记录时，结合用户指定厂商与 `vendor/device_type` 选择 ID，不能取第一条 generic 记录就执行。`connect_status` 是上次连接测试状态，exec 成功不会自动刷新；本次登录/查询结论以本次 job 的逐台结果和有效正文为准。空正文或只有命令头不算查询通过。
 
 **✓ 同命令多台**
 
@@ -180,7 +183,7 @@ Neighbour / PW / Tunnel 等控制面量多 **不当断纤**，除非用户问的
 - **优先复用本会话已成功过的命令**（含同厂其他台验证过的）：新台/下一批先试这些，再对失败子集另探；不要一失败就换全员命令。
 - 多台一批时：用 `targets` 给失败台换命令，或先一批共同命令 → 只对失败子集再一批探测；不要为了一台把成功台的结果丢掉重来。
 
-### `?` 规则（`show` / `display` / `ping` 等同一套）
+### `?` 规则（`show` / `display`）
 
 1. 报错中的 **`^`** 标出错位置 → **`^` 之前**已正确 → 对该前缀加 `?` 列下一级。  
 2. `?` 可紧接在部分单词后（`show optical?`、`display inter?`），不必强制空格再写 `?`。  

skills/topology/netx-topology/SKILL.md

@@ -317,7 +317,7 @@ sinkTopologyDualUnits({
 |--------|------|
 | `layout` | 小图 / 剩余块：`compact` / `corridor` / `rings` / `unstick` |
 | `layout_dual_unit` | **仅**重布已沉的那一只眼；椭圆弧带 + 空心眼 |
-| `move_nodes` / `sink_nodes` | **后续下沉主路径**；`park` 块扫 |
+| `move_nodes` | **后续下沉主路径**；`park` 块扫 |
 | `orbit_sweep` | **眼后精修主工具**：`until_limit` 或 `node_id`；`objective=crossing\|total` |
 | `clear_edge_hits` | 眼 sink **可**（须 `portal_ids`；交叉不升） |
 | `pull_far_chains` | 眼 sink **可**：朝门户中点收远走廊/孤立点 |
@@ -376,3 +376,13 @@ sinkTopologyDualUnits({
 4. 机器上常残留多份旧 MCP 进程 → 精修前 catalog 若仍缺 action，**杀光再启**；勿用旧进程半截交付，勿改走 HTTP/临时 py。
 
 拓扑页开「实时同步」可看落笔。勿用告警/CLI MCP 写拓扑。
+
+## MCP 异步与失败处理
+
+小图先用 `layoutTopologyView(view_id=...,action=layout,recipe=compact,mode=preview)` 看提案，再 `mode=apply,params={background:true}` 保存。`job_id/status=running/applied=false` 表示尚未完成；用同一台机器、同一任务目录的 `layoutTopologyView(action=job_status,params={job_id:...})` 轮询。成功需 `status=done` 且 `result.applied=true`，随后 `getTopologyView(detail=full)` 回读坐标。没有 HTTP layout job 接口。
+
+任务状态在 MCP 的 `NETX_LAYOUT_JOB_DIR`（默认 data/runtime/layout_jobs）落盘，换机器/目录不能读同一 job。`job_cancel` 只请求协作取消，不承诺回滚。复制/移动/下沉是多步 HTTP 操作；遇到错误或 `write_completed=true` 先读两端现状，不盲重试。坐标保存失败时不继续删除源成员。
+
+只读 token 不包含 `ne:write`，将看不到布局/建图工具；preview/job_status 目前也随 layout 工具受该权限限制。修改的是 netx 画布与 Fabric 元数据，不向真实设备下配置。需要演练时新建验收视图，避免覆盖既有图。
+
+布局任务成功和评分模型评价分别记录。评分仅供诊断，需结合图形与业务需求；不能仅凭总分判定布局通过或失败。评分模型的校准留待后续专项，本轮不调整算法或阈值。