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 中档、edge_clearance.status≠fail、edge_axis.status≠fail 方可交付。勿只看 crossing——orbit_sweep 的 improving_n=0 只代表交叉维度卡壳，须逐项检查 edge_clearance/edge_axis/rings，任一 fail 即继续处理。

---

阶段 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 把通路切开。

---

分层布局（特殊场景）

当网络需呈现层级结构（外部→接入→核心→汇聚→客户等）时，优化策略不同于通用 mesh：

分层通用规则

1. 顶层：外部/对接网络
2. 次顶层：终端客户接入层
3. 中间层：核心层
4. 核心下层：汇聚层
5. 底层：接入层/孤立层

优化流程

1. 先手动后算法：用户手动拖拽保证业务结构，再用算法优化
2. 分层约束：用 updateTopologyViewPositions 按层级设定 y 坐标（同层 y 落在区间内可错落，勿跨层）；orbit_sweep 传 y_min/y_max 约束搜索在本层区间内
3. 分步迭代：
   • polish_crossings 减少交叉（可能破坏分层）
   • 若分层被破坏，保留 x 坐标，恢复 y 坐标重新分层
   • clear_edge_hits 消除贴边
   • fix_overlaps 修复重叠

冲突处理原则

冲突场景	处理方式
交叉 vs 结构	结构优先，接受少量跨层交叉
算法 vs 手动	手动优先，算法辅助
polish 破坏分层	保留 x 坐标，恢复 y 坐标分层

关键经验

1. 跨层交叉是结构性的：跨层连线必然穿越中间层，属正常
2. 外层节点必须在外部层：与 PS/PE 连接的外部网元（RNC、华为设备等）应放在最上方
3. orbit_sweep 卡壳更早：分层约束下 improving_n=0 来得快；改传 objective=total 让 orbit_sweep 按 crossing+edge_clearance 综合排序
4. 验收以层级清晰为先：verdict.total 次于结构可读性；同层 y 在区间内、层间不串层即可交付

---

根图 → 子区域排水

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）；objective=total 综合 crossing+edge_clearance；y_min/y_max 分层约束
polish_crossings	一键：straighten→press→untangle
clear_edge_hits	网元贴非关联边时正交弹开
fix_overlaps / resolve_overlaps	只拉开重叠
untangle	贪心降交叉；默认可冻门户
straighten_channels	拉直 deg≤2 走廊
job_status / job_cancel	后台 job

阶段2是多目标循环，非单向链：

1. orbit_sweep 压交叉 → polish_crossings
2. orbit_sweep improving_n=0 时勿停——立即转看 edge_clearance（贴边对视觉可读性影响 ≥ 交叉）→ clear_edge_hits 正交弹开
3. 再看 edge_axis（斜边过多）→ straighten_channels / 手拖归轴
4. 回头复检 crossing 是否因上步变动出现新机会 → 再 orbit_sweep

orbit_round 只在全局交叉严格下降时落笔；卡顿加大 max_jump / 单点 preview→pick。

关键：单节点 updateTopologyViewPositions 拖动时，某节点移动可能增交叉但解多个贴边——以 verdict.total 升降为准，勿只盯 crossing 数。drag_candidates 可能为空，此时看 edge_clearance.top / crossing.top_nodes 自行判断拖谁。

---

验收

块	看什么
overlap	硬零（权重 0.24，硬门控）
crossing	crossings/cpl；top_nodes / top_edges（权重 0.18）
rings	最小环被穿（权重 0.10）
edge_clearance	贴边 → clear_edge_hits；权重 0.08 但视觉影响 ≥ crossing，优先处理
edge_axis	斜边过多 → straighten_channels / 手拖归轴（权重 0.06）
verdict.total	≈70 可交付（ov=0）；总分升降为准，勿只盯 crossing

评分优化快速方法

1. 消除 overlap → 硬门控项，必须为 0
2. 减少 crossings → polish_crossings 大幅降低
3. 处理 edge_clearance → clear_edge_hits 消除贴边
4. 结构检查 → 分层清晰 > 交叉最少

图标 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 + 验收

---

通用优化策略（实战经验）

算法与手动的最佳组合

Step 1: 用户手动拖拽 → 保证业务结构和分层
Step 2: polish_crossings → 大幅减少交叉（接受可能破坏分层）
Step 3: 检查分层 → 若被破坏，保留 x 恢复 y 重新分层
Step 4: clear_edge_hits → 处理贴边问题
Step 5: fix_overlaps → 修复节点重叠
Step 6: 最终验收 → 结构清晰 > 交叉最少

工具使用优先级

场景	首选工具	参数建议
整体减交叉	polish_crossings	top_n=10, max_moves=50
单点微调	orbit_sweep	objective=total, y_min/y_max
处理贴边	clear_edge_hits	top_n=15, max_moves=30
修复重叠	fix_overlaps	直接调用
批量调坐标	updateTopologyViewPositions	保留 x，恢复 y

常见问题解决方案

问题	原因	解决方案
polish 破坏分层	算法优先减少交叉	保留 x 坐标，恢复 y 分层
orbit_sweep 无改善	位置已优化	接受现状或手动调整
节点重叠	坐标调整太近	fix_overlaps 自动修复
交叉突然增加	clear_edge_hits 移动节点	重新 polish_crossings

关键原则

1. 业务结构优先于算法优化：网络拓扑的分层结构比最少交叉更重要
2. 局部微调优于全局重置：用 orbit_sweep/updateTopologyViewPositions 单点调整，而非 layout 全局布局
3. 预览模式优先于应用模式：先用 mode=preview 查看效果，确认后再 mode=apply
4. 分步迭代优于一次性操作：polish → clear_edge_hits → fix_overlaps 分步骤执行

---

代码热更

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

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