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

name	description
netx-topology	用 netx-topology MCP 查邻接、dual_unit 分批沉入、扫角压交叉（不污染 Fabric）。 触发：画拓扑、布图、拖图、LLDP、Fabric、netx-topology。先读本 skill 再调工具。

netx 拓扑（通用）

只用 netx-topology MCP（包 netx-topology-mcp）。安装与 scopes：仓库 docs/MCP_TOPOLOGY.md。

原则：复杂图先拆 dual_units 再拼；交叉少、边短、近轴优先。
禁止写临时 py 穷举坐标或直接调 HTTP；验证与压交叉只调 MCP。不造 Fabric 边。
勿把客户网元名、区域名、具体交叉数写进本 skill。

---

主路径（必循）

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 日常连抽）

停手：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 / getTopologyView	树与画布
createTopologyFolder	新建根/区域（返回 view_id）
add / remove / updateTopologyViewPositions	成员与手拖
sinkTopologyDualUnits	dual_units 分批沉入
copyTopologyViewNodes	克隆沙箱
projectTopologyNeighbors	投影邻居
queryTopologyFabricNodes	库存（summary|list|search）
neighborhood / edges	邻接
layoutTopologyView	上表 action
analyzeTopologyViewLayout	structure + 验收

---

代码热更

1. 本仓 MCP 用 PYTHONPATH=…/src，改源码后不必为加载而 pip install。
2. 必须重启 stdio 进程；catalog 含 rev（当前 NETX_MCP_REV）。
3. layoutTopologyView(catalog=true) 核对 action/recipe 清单。

拓扑页开「实时同步」可看落笔。勿用告警/CLI MCP 写拓扑。