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>

docs/MCP.md

@@ -116,7 +116,7 @@ pip install "git+https://github.com/hansjone/netx.git#subdirectory=packages/netx
 
 1. 完成上文 **§1**（用 **oclaw 同机同一个 `python`** 安装 `netx-mcp`）。
 2. Admin → MCP → 粘贴 `mcp.json` 全文 → 点击 **Install from JSON**（安装状态在下方一行小字）。
-3. **Health** → **Sync Tools**（应看到 **14** 个工具）。
+3. **Health** → **Sync Tools**（完整 scope 下应看到 **15** 个工具）。
 4. 在 **MCP 专家绑定** 中为 ops 专家勾选 `server_id=netx`。
 
 更细的 oclaw 说明（双轨内置工具、锚点注入等）见 oclaw 仓库：  
@@ -141,9 +141,11 @@ pip install "git+https://github.com/hansjone/netx.git#subdirectory=packages/netx
 | NMS 原始/SQL | `queryNmsAlarmsRaw`, `aggregateNmsAlarmsRaw`, `listNmsAlarmFields`, `sqlQueryNms` |
 | common（CLI + 路径） | `listManagedNe`, `getManagedNe`, `execManagedNe`, `getNeExecJob`, `listCliTargets`, `findTopologyPaths` |
 
-参数优先 `nms_ne_id` / `nms_ne_ids`（保留 `ume_*` 别名）。拓扑 Fabric / 画布工具在 **[`netx-topology-mcp`](./MCP_TOPOLOGY.md)**。oclaw 中名称带前缀：`mcp__netx__<toolName>`；DSH：`netx__<toolName>`。
+参数使用 `nms_ne_id` / `nms_ne_ids`，旧 `ume_*` 模型参数已删除；`getManagedNe` 只接受 `ne_id`。拓扑 Fabric / 画布工具在 **[`netx-topology-mcp`](./MCP_TOPOLOGY.md)**。oclaw 中名称带前缀：`mcp__netx__<toolName>`；DSH：`netx__<toolName>`。
 
-**业务监控 / 割接分析**：不走 netx-mcp。DSH **netxops** 宿主工具组 `bizMonitor`（`netx__listBizMonitors` / `netx__getBizMonitorContext` 等）直连 netx REST（`/v1/biz-migration/*`、`/v1/biz-state/*`，需 token scope `biz-monitor:read`）。
+**业务监控 / 割接分析**：独立 [`netx-bizmonitor-mcp`](./MCP_BIZMONITOR.md) 提供 8 个工具，需 `biz-monitor:read`；netxops 的 bizMonitor 组使用相同 stem。三组统一配置见根 [`mcp.all.json`](../mcp.all.json)，不需要安装 netxops。
+
+**CLI 安全边界**：独立 MCP 强制单行只读 `show` / `display`，可用只读输出过滤；配置、shell 操作符、重定向和多行脚本在 HTTP 前拒绝。后端开放 exec_policy 或 capability 的脚本提示也不能解除这个 MCP 门禁，Linux/RouterOS 原生 CLI 当前未暴露。异步 job_id 仅表示开始，按 poll_after_ms 有界轮询；terminal 后检查 result.ok，批量还须检查 summary.failed 和每条 results[].ok，不能只凭作业 succeeded 宣称全部成功。
 
 ---
 
@@ -191,10 +193,10 @@ pip show netx-mcp
 
 | 旧方式 | 新方式 |
 |--------|--------|
-| `python -m netx_api.mcp` | `python -m netx_mcp`（推荐） |
+| `python -m netx_api.mcp` | `python -m netx_mcp`（唯一 Python 模块入口） |
 | `NETX_MCP_MODE=db` 直连库 | 已废弃；使用 HTTP 模式 |
 
-根目录 `python -m netx_api.mcp` 仍会委托到 `netx_mcp`，新环境请只装 `netx-mcp` 包。
+旧入口 `netx_api.mcp`、`netx_api/mcp_server.py` 和 `NETX_MCP_MODE=db` 已删除。请安装独立 `netx-mcp` 包并迁移配置；不再保留兼容委托。旧 DB 模式独有的导入告警查询/聚合/批次/诊断、同步触发、历史告警查询仍有 HTTP API，但不属于当前 ops 15 工具。
 
 ---
 
@@ -233,7 +235,7 @@ $p = Start-Process python -ArgumentList "-m","netx_mcp" -RedirectStandardInput p
 | 工具调用连不上 API | 检查 `NETX_API_URL`、防火墙、远端 API 是否启动 |
 | Windows 乱码 / JSON 解析失败 | 配置里保留 `PYTHONIOENCODING=utf-8`、`PYTHONUTF8=1`（见 `mcp.json`） |
 | oclaw 工具数为 0 | Admin **Health → Sync Tools**；确认 `server_id=netx` 已绑定 ops 专家 |
-| 仍想用仓库脚本路径 | 未 pip 安装时可临时 `"args": ["D:/.../netx_api/mcp_server.py"]`（开发用） |
+| 旧脚本路径或模块不存在 | 安装 `packages/netx-mcp`，配置改为 `"args": ["-m", "netx_mcp"]` |
 
 ---
 

docs/MCP_BIZMONITOR.md

@@ -0,0 +1,41 @@
+# 割接与业务监控 MCP
+
+`netx-bizmonitor-mcp` 独立提供 bizMonitor 的 8 个只读工具。不安装 netxops 也能读取已有项目、批次、看板、红票、差异和采集原文。它只依赖 Python 3.11+ 与 httpx，通过 HTTP 使用正在运行的 netx。
+
+## 三组一起配置
+
+在运行 MCP 客户端的 Python 环境分别安装：
+
+```powershell
+python -m pip install -e ./packages/netx-mcp
+python -m pip install -e ./packages/netx-topology-mcp
+python -m pip install -e ./packages/netx-bizmonitor-mcp
+```
+
+将根 [mcp.all.json](../mcp.all.json) 的三个 server 放入客户端 MCP 配置。也可以不安装包，分别将该包的 `src` 绝对路径设为对应 server 的 `PYTHONPATH`。三个模块分别为 `netx_mcp`、`netx_topology_mcp`、`netx_bizmonitor_mcp`；console scripts 属于各独立包，安装 API 本体不会提供一个缺少依赖的 MCP 假入口。
+
+统一设置 `NETX_API_URL`。凭据优先用 `NETX_API_TOKEN`，否则读取 `NETX_MCP_TOKEN_FILE`，再尝试工作目录 `data/auth/mcp_token`。客户端工作目录不确定时，给 `NETX_MCP_TOKEN_FILE` 配置绝对路径。不要把真实令牌提交到仓库。
+
+业务组需 `biz-monitor:read`；ops 需 `alarms:read`、`ne:read`、`ne:exec`，SQL 另需 `sql:query`；topology 读取需 `ne:read`，建图/布局需 `ne:write`。默认 bootstrap token 不含 SQL 和拓扑写权限，因此工具数量会按 scope 缩减；有完整权限时分别列出 **15、16、8** 个工具。
+
+## 入口与证据链
+
+MCP 使用裸名；netxops 使用 `netx__` 加相同名称。
+
+1. `listBizMonitors`：无 ID 的入口，取得 project_id/task_id。
+2. `getBizMonitorContext`：读取模板、归一化、端口映射、两侧任务和基线。
+3. `listBizMonitorBatches(project_id,include_runs=true)`：取得割接批次与 run_id；也可 `kind=runs,batch_id=...`。
+4. `getBizMonitorBoard(batch_id)`：检查完成状态、缺失数据和统计。
+5. `listBizMonitorReds(project_id)` / `getBizMonitorDiffs(run_id,color=red)`：逐页取得红项和证据。`q` 自动映射后端 `kw`。
+6. `getBizCollectBatch`：采集批次的命令目录；需要时由 `listBizMonitorBatches(task_id)` 找采集批次。
+7. `getBizCollectCommandRaw(batch_id,command_id)`：两侧原文取证。这里使用采集 batch_id，不能传割接 batch_id。
+
+`old_key/new_key` 保留设备原始 A/B；`match_*` 和归一化映射用于内部配对。原文按需获取，可能很大；凭据会脱敏，不把内部匹配键冒充设备原始端口。
+
+本组不会创建任务/模板、启动采集、执行 evaluate、关闭红票。没有批次时不能得出“割接通过”。完整行为和参数见 [包 README](../packages/netx-bizmonitor-mcp/README.md) 与 [skill](../skills/biz-monitor/netx-biz-monitor/SKILL.md)。
+
+## 可复现验收
+
+`scripts/mcp_acceptance.py` 启动当前 worktree 的真实 stdio MCP，记录去敏 JSONL；仅允许本机 8890 或隔离样例 8891。工具源目录可用 `--source-root` 显式指定，不会静默导入主仓库的 editable 包。
+
+没有现场割接数据时，可用 `scripts/seed_mcp_acceptance.py` 在 `agent-wt/netx-mcp-lead/artifacts/` 的新 acceptance SQLite 文件生成明确标注的离线样例，真实运行业务评价，再通过本地 API/MCP 验证读取链路。样例不代表现场故障；不要将样例库替换应用库。脚本拒绝覆盖、外部路径、网络连接和监听端口。

docs/MCP_TOPOLOGY.md

@@ -60,11 +60,11 @@ pip install "git+https://github.com/hansjone/netx.git#subdirectory=packages/netx
 
 与告警 MCP 并存时，把两个 server 都放进 `mcpServers` 即可；未勾选/未安装的不会加载工具。
 
-oclaw：Install from JSON → Health → Sync Tools（应看到 **14** 个工具，含 `layoutTopologyView` / `sinkTopologyDualUnits` / `queryTopologyFabricNodes`）→ 专家绑定勾选 `server_id=netx-topology`。
+oclaw：Install from JSON → Health → Sync Tools（完整 scope 下应看到 **16** 个工具，含 `layoutTopologyView` / `sinkTopologyDualUnits` / `queryTopologyFabricNodes`）→ 专家绑定勾选 `server_id=netx-topology`。
 
 Cursor：改包后若 Sync 工具数不对，请 **禁用/启用** `netx-topology` 或重载窗口（须重启 stdio 进程）。可选在 env 加 `PYTHONPATH=.../packages/netx-topology-mcp/src` 强制最新源码。
 
-配套 Agent Skill（dual_unit 排水 → 扫角/polish → 手拖）：[`.cursor/skills/netx-topology/SKILL.md`](../.cursor/skills/netx-topology/SKILL.md)。Cursor / oclaw 读 skill 后再调 MCP。
+配套 Agent Skill（dual_unit 排水 → 扫角/polish → 手拖）：[`skills/topology/netx-topology/SKILL.md`](../skills/topology/netx-topology/SKILL.md)。Cursor / oclaw 读 skill 后再调 MCP。
 
 ---
 
@@ -97,7 +97,7 @@ Cursor：改包后若 Sync 工具数不对，请 **禁用/启用** `netx-topolog
 | `removeTopologyViewNodes` | 筛选或 id 从画布移除（不删 Fabric），摘要 |
 | `sinkTopologyDualUnits` | 根图 dual_units 分批沉入子区域；默认 `layout_batch`→`layout_dual_unit`→块扫挂载；日常禁 `until_empty` |
 | `copyTopologyViewNodes` | 一键克隆画布成员+坐标到另一画布（`clear_target` 可选）；源画布不动，测沙箱用 |
-| `layoutTopologyView` `move_nodes` | 指定 `fabric_node_ids` 从 `source_view_id`→`view_id`（默认同移出源）；对调两 view 回迁；别名 `sink_nodes`；`park=true` 扫角停靠 |
+| `layoutTopologyView` `move_nodes` | 指定 `fabric_node_ids` 从 `source_view_id`→`view_id`（默认同移出源）；对调两 view 回迁；`park=true` 扫角停靠 |
 | `updateTopologyViewPositions` | **优先** `layout=grid\|offset\|stack` + 筛选，API 自己挪点；`positions[]` 仅少量微调 |
 | `layoutTopologyView` | **布图/局部修**：公开 `action=layout\|layout_dual_unit\|orbit_sweep\|clear_edge_hits\|pull_far_chains\|compact_bbox\|polish_crossings\|fix_overlaps\|untangle\|straighten_channels\|level_bands\|move_nodes`；recipe 仅 `compact\|corridor\|rings\|unstick`。眼 sink 主路径：`until_limit(crossing→total)` → `clear_edge_hits` → `pull_far_chains` → `compact_bbox` → 手拖；禁对眼跑 polish/fix_overlaps/untangle/round。stall 且 moved≈0 即算法到头。巨图 apply 可能返回 `job_id` → 轮询 `job_status` / `job_cancel`。Job=**子进程+`data/runtime/layout_jobs` 落盘**。`mode=preview\|apply` |
 | `projectTopologyNeighbors` | 投影**已有** LLDP 邻居到画布；区域画布务必传 `region_folder_id`，读 `out_of_region_skipped` |
@@ -120,8 +120,11 @@ Cursor：改包后若 Sync 工具数不对，请 **禁用/启用** `netx-topolog
 
 | 包 | server_id | 职责 |
 |----|-----------|------|
-| `netx-mcp` | `netx` | 告警、UME、托管网元 CLI（**13** 工具） |
-| `netx-topology-mcp` | `netx-topology` | 拓扑画布 / Fabric 只读 + 分类打标 + 安全画图（**15** 工具） |
+| `netx-mcp` | `netx` | NMS 告警、网元和只读 CLI（**15** 工具） |
+| `netx-topology-mcp` | `netx-topology` | topology 组 15 工具及额外 sinkTopologyDualUnits（共 **16**） |
+| `netx-bizmonitor-mcp` | `netx-bizmonitor` | 割接 / 业务状态只读分析（**8** 工具） |
+
+显式后台保存：`layoutTopologyView(view_id=...,action=layout,recipe=compact,mode=apply,params={background:true})`。用 `layoutTopologyView(action=job_status,params={job_id:...})` 轮询，成功后 getTopologyView 回读。任务是 MCP 本地子进程与落盘 JSON，没有 HTTP layout job API；跨目录或机器不能轮询同一 job。失败后可能已有部分写入，先回读，不盲重试。布局保存成功与评分诊断分别判断；评分校准另行安排，本轮不改算法/阈值。
 
 `queryTopologyEdges` 已从 `netx-mcp` **迁出**到本包，避免重复。