Converge netx-topology MCP to dual-unit drain + orbit/polish mainline.

Trim public tools to 14, expose only kept layout actions/recipes, merge Fabric queries, drop createTopologyView/listTopologyViews, and align skill/docs with the live catalog.

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

.cursor/skills/netx-topology/SKILL.md

@@ -1,58 +1,148 @@
 ---
 name: netx-topology
 description: >-
-  用 netx-topology MCP 查链路、画拓扑（不污染 Fabric）。触发：画拓扑、LLDP、Fabric、netx-topology。先读再调。
-user-invocable: true
-disable-model-invocation: false
+  用 netx-topology MCP 查邻接、dual_unit 分批沉入、扫角压交叉（不污染 Fabric）。
+  触发：画拓扑、布图、拖图、LLDP、Fabric、netx-topology。先读本 skill 再调工具。
 ---
 
-# netx 拓扑 MCP
+# netx 拓扑（通用）
 
-通过 **`netx-topology`** MCP（包 `netx-topology-mcp`）操作 netx 拓扑。与告警/CLI 的 **`netx`** MCP **分开**；画图只用本包工具。
+只用 **`netx-topology`** MCP（包 `netx-topology-mcp`）。安装与 scopes：仓库 [`docs/MCP_TOPOLOGY.md`](../../../docs/MCP_TOPOLOGY.md)。
 
-安装与 scopes 真源：仓库 [`docs/MCP_TOPOLOGY.md`](../../../docs/MCP_TOPOLOGY.md)。
+**原则**：复杂图先拆 **dual_units** 再拼；交叉少、边短、近轴优先。  
+**禁止**写临时 py 穷举坐标或直接调 HTTP；验证与压交叉**只调 MCP**。不造 Fabric 边。  
+**勿**把客户网元名、区域名、具体交叉数写进本 skill。
 
-## 硬规则
+---
 
-1. **先读后写**：任何建图/摆点前先 `getTopologyTree`；改已有图前可 `getTopologyView`（大图慎拉整图）。
-2. **筛选交给 API**：加/挪/删优先传 `keyword` / `role` / `vendor` / `link_status`（加节点再用 `limit`/`offset`）。**不要**先 list 全量再回传成千上万 id。
-3. **只动已有 Fabric**：禁止 `managed_ne_ids` / `ume_ne_ids`；禁止臆造 fabric id。
-4. **不污染 Fabric**：不能手工建链、不能 populate、不能删 Fabric / 整图。邻居用 `projectTopologyNeighbors`。
-5. **写权限**：需要 `ne:write`。tools/list 没有写工具 → 停，让用户用「MCP + 拓扑写」签发 Token。
-6. **无区域则先建**：`createTopologyView` 需要 `folder_id`；没有合适区域时用 `createTopologyFolder`，再 `createTopologyView` 建画布。
-7. **单画布硬顶 2000**：满了 `truncated` / 触顶 → 新建另一张画布继续；全网五万设备靠多画布切片。
-
-## 推荐流水线（从零画一张图）
+## 主路径（必循）
 
 ```
-1 getTopologyTree                         → 看有无区域；没有则 createTopologyFolder → folder_id
-2 createTopologyView                      → view_id
-3 addTopologyViewNodes(keyword=…, limit)  → 看 added / next_offset，循环 offset 直到无更多或满 cap
-4 projectTopologyNeighbors                → 可选
-5 updateTopologyViewPositions(layout=grid|offset|stack, keyword=…)  → API 自己筛并摆
-6 （少量微调才用 positions[]）
+analyze(structure) → 认 dual_units / shape
+→ 核心层：手拖或小图 layout(compact|corridor|rings)
+→ sinkTopologyDualUnits（一批，layout_batch=true）
+   或 move_nodes(park=true) 指定 ids
+→ orbit_sweep(round) → polish_crossings → clear_edge_hits
+→ 手拖微调 updateTopologyViewPositions
+→ 下一批 sink…（禁止 until_empty 日常连抽）
 ```
 
-查链路不画图：`queryTopologyEdges` / `queryTopologyNeighborhood`。
+停手：`overlaps=0` 且 `verdict.total≈70`、cpl 中档内即可交付。
+
+---
+
+## 阶段 0 — 画布与成员
+
+1. `getTopologyTree` → **`view_id`**（文件夹 physical 画布）。
+2. 建根/子区域只用 `createTopologyFolder`。
+3. `analyzeTopologyViewLayout({ view_id, detail: "structure" })` 读 `dual_units` / `shape`。
+4. `addTopologyViewNodes` / `projectTopologyNeighbors`（区域画布务必 `region_folder_id`）。
+5. 多余点用 `removeTopologyViewNodes` **移出画布**（不删 Fabric）。`region:…` 幽灵点勿当网元拖。
+
+---
+
+## 形状与 dual_units
+
+```
+analyzeTopologyViewLayout({ view_id, detail: "structure" })
+```
+
+| 字段 | 用途 |
+|------|------|
+| `shape.primary` | `chains` / `star` / `mesh` / `mixed_blocks` |
+| `dual_units` | 两端门户 + ≥2 条内部不交走廊；成员可重叠 |
+| `advice.block_plan` | 每块怎么拖 |
+| `gravity.type` | 链图勿当 hub 花瓣 |
+
+- **链图**：脊柱水平 + stub；小图 preview `corridor`/`compact`（跳过 rings）。
+- **巨图 / 多门户**：勿全图一把揉；走 **sink 分批 dual_unit**。
+- **禁止**再用互斥 soft_block 把通路切开。
+
+---
+
+## 根图 → 子区域排水
+
+```
+sinkTopologyDualUnits({
+  source_view_id: <根图>,
+  sink_view_id: <子区域>,
+  max_units: 3,
+  max_batch_nodes: 120,
+  layout_batch: true,   // 每单元 layout_dual_unit → 块扫挂 sink
+})
+→ orbit_sweep / polish_crossings / clear_edge_hits
+→ 再调下一批（source_remaining>0）
+```
+
+- **一次只沉一批**；勿日常 `until_empty`。
+- 落点：**块扫**（交叉/重叠/桥长择优），禁止固定往右排。
+- 指定迁移：
+  ```
+  layoutTopologyView({
+    action: "move_nodes",
+    source_view_id: <FROM>, view_id: <TO>,
+    mode: "apply",
+    params: { fabric_node_ids: [...], park: true, remove_from_source: true },
+  })
+  ```
+  `park=true` = 扫角停靠；回迁对调两 view_id。
+
+---
+
+## layoutTopologyView（精简）
+
+| action | 用途 |
+|--------|------|
+| `layout` | 小图配方：`compact` / `corridor` / `rings` / `unstick` |
+| `layout_dual_unit` | 双门户眼形；单元内交叉≠0 拒绝 |
+| `move_nodes` / `sink_nodes` | 指定 ids 双向迁移；`park` 块扫 |
+| `orbit_sweep` | 压交叉；`round` + 大 `max_jump`（约 1800–2800） |
+| `polish_crossings` | 一键：straighten→press→untangle |
+| `clear_edge_hits` | 网元贴非关联边时正交弹开 |
+| `fix_overlaps` / `resolve_overlaps` | 只拉开重叠 |
+| `untangle` | 贪心降交叉；默认可冻门户 |
+| `straighten_channels` | 拉直 deg≤2 走廊 |
+| `job_status` / `job_cancel` | 后台 job |
+
+阶段2顺序：先 `orbit_sweep` 压交叉 → `polish_crossings` → 看 `edge_clearance` 再 `clear_edge_hits`。  
+`orbit_round` 只在全局交叉严格下降时落笔；卡顿加大 `max_jump` / 单点 preview→pick。
+
+---
+
+## 验收
+
+| 块 | 看什么 |
+|----|--------|
+| `overlap` | 硬零 |
+| `crossing` | crossings/cpl；`top_nodes` / `top_edges` |
+| `edge_clearance` | 贴边 → clear_edge_hits |
+| `verdict.total` | ≈70 可交付（ov=0） |
+
+图标 25px；推荐中心距 Δx≥200、Δy≥170。交叉 = 无向 NE↔NE 真交叉（共端点不算）。
+
+---
 
 ## 工具速查
 
-| 目的 | 工具 |
+| 工具 | 作用 |
 |------|------|
-| 树 / 区域 / 画布 | `getTopologyTree`, `createTopologyFolder`, `listTopologyViews`, `getTopologyView`, `createTopologyView` |
-| 筛选批量加 | `addTopologyViewNodes`（filters + limit/offset） |
-| 筛选批量挪 | `updateTopologyViewPositions`（layout + filters） |
-| 筛选批量删 | `removeTopologyViewNodes`（filters） |
-| 投影邻居 | `projectTopologyNeighbors` |
-| Fabric 读 | `search…` / `list…` / `queryTopologyEdges` / `…Neighborhood` / summary |
+| `getTopologyTree` / `getTopologyView` | 树与画布 |
+| `createTopologyFolder` | 新建根/区域（返回 view_id） |
+| `add` / `remove` / `updateTopologyViewPositions` | 成员与手拖 |
+| `sinkTopologyDualUnits` | dual_units 分批沉入 |
+| `copyTopologyViewNodes` | 克隆沙箱 |
+| `projectTopologyNeighbors` | 投影邻居 |
+| `queryTopologyFabricNodes` | 库存（summary\|list\|search） |
+| neighborhood / edges | 邻接 |
+| `layoutTopologyView` | 上表 action |
+| `analyzeTopologyViewLayout` | structure + 验收 |
 
-## 对人说清楚
+---
 
-- 网页观看：拓扑页开 **「实时同步」**（默认关）。
-- 回报：`folder_id` / `view_id`、画布名、`added`/`updated`/`removed`、是否 `truncated`/`next_offset`。
+## 代码热更
 
-## 不要做
+1. 本仓 MCP 用 `PYTHONPATH=…/src`，改源码后不必为加载而 pip install。
+2. **必须重启** stdio 进程；`catalog` 含 `rev`（当前 `NETX_MCP_REV`）。
+3. `layoutTopologyView(catalog=true)` 核对 action/recipe 清单。
 
-- 不要用 `netx` 告警 MCP 冒充拓扑写。
-- 不要为画图去造 Fabric / 改 managed-NE。
-- 不要在未确认 folder/view 时连环盲写。
+拓扑页开「实时同步」可看落笔。勿用告警/CLI MCP 写拓扑。