列出 eNSP 支持的设备型号，以及每种型号的接口清单。

搭拓扑前先调这个，就知道有哪些型号可选、每个型号有几个口、口叫什么名字。 连线时 fromPort / toPort 填的就是这里的接口名。

Args: category: 只看某一类，可选 AR（路由器）、LSW（交换机）、WLAN（无线）、 FW（防火墙）、CLIENT（终端）、OTHER（其它）。留空看全部。 model: 只看某一个型号，例如 "S5700"。填了会连完整接口列表一起返回。 topo_path: 可选。给一份现成 .topo，会顺带核对内置型号表和这份文件 里实际写出的接口布局是否一致，用于确认 eNSP 版本差异。

新建一个空的 .topo 文件。

Args: path: 要写到哪，例如 "D:/work/campus.topo"。 overwrite: 目标已存在时是否覆盖，默认不覆盖。

读一份 .topo，返回设备清单、链路清单和每台设备的空闲接口。

每台设备会带上 consolePort，那就是 device_* 工具要用的端口号。

往拓扑里批量加设备。

Args: path: .topo 文件路径。 devices: 设备列表，每项支持这些字段：

    - model（必填）：型号，见 list_models。
    - name：设备名，省略则按 eNSP 习惯自动编号（S5700 叫 LSW1、
      AR2220 叫 AR1，重名自动往后排）。
    - count：一次加几台，默认 1；配合省略 name 可以批量生成。
    - x / y：画布坐标，省略则先堆在原点，之后跑 topo_layout 自动摆开。
    - settings：终端类设备的初始参数，PC/Server 可填
      {"ip": "...", "mask": "...", "gateway": "..."}，
      AP 可填 {"mac": "...", "sn": "..."}。具体字段见
      list_models 返回的 settingsFields。

举例：[{"model": "S5700", "name": "Core", "count": 2},
      {"model": "PC", "settings": {"ip": "192.168.1.10"}}]

console 端口会自动从 2000 起顺序分配，不会和已有设备冲突。

批量连线。

Args: path: .topo 文件路径。 links: 链路列表，每项支持：

    - from / to（必填）：两端设备名。
    - fromPort / toPort：接口名（"GE0/0/1"、"GigabitEthernet0/0/1"
      都认）或接口序号。省略则自动挑该设备第一个空闲口。
    - lineType：线型，默认按接口类型自动判断（串口给 Serial，
      其余给 Copper）。也可显式写 Copper / Fiber / Serial。

举例：[{"from": "Core1", "to": "Core2", "fromPort": "GE0/0/1",
       "toPort": "GE0/0/1"},
      {"from": "Core1", "to": "PC1"}]

一个接口只能连一条线，重复占用会直接报错并指出是哪个口。

删设备或删连线。

Args: path: .topo 文件路径。 devices: 要删的设备名列表，删设备会连带删掉它身上所有的线。 links: 要断开的链路，每项 {"from": "A", "to": "B"}。

自动排布设备坐标，不用手工填 x/y。

Args: path: .topo 文件路径。 mode: 布局方式。

    - layered（默认）：按连线关系自动分层，出口在上、终端在下，
      最贴近常见的园区网拓扑图。
    - tree：从 root 出发按层级展开。
    - grid：网格铺开，适合还没连线的时候。
    - ring：环形，适合环网。
groups: 只在 layered 下有效。手工指定每一层放哪些设备，
    例如 [["Internet"], ["AR1"], ["Core1","Core2"]]。
    没列进去的设备会自动补到最后一层。
root: 只在 tree 下有效，指定树根设备名。省略则挑连线最多的那台。
columns: 只在 grid 下有效，每行几台。省略则自动取平方根。
zones: 可选的分区列表。每项包含 title（或 name）、devices，可选
    color（#RRGGBB）和 columns。给了 zones 后会使用分区布局，
    mode/groups/root/columns 不再参与排布。
replace_annotations: 拓扑已有背景图形或文字时，是否明确清空并按 zones
    重建。默认拒绝覆盖，因为 eNSP 标注没有稳定 ID，无法可靠区分手工项。
include_unassigned: zones 未包含的设备是否自动放入“未分区”背景框，默认是。
zone_columns: 整体画布每行放几个分区；0 表示自动。
allow_annotation_desync: 普通布局遇到已有标注时是否仍移动设备。默认否，
    避免背景框和文字留在旧位置；仅在确认标注无需同步时才设为 true。

检查拓扑有没有问题，建议在交给 eNSP 打开之前跑一次。

errors 会让 eNSP 打开异常或链路失效，必须改；warnings 只是提醒。 查的内容包括：设备重名、接口序号越界、一个口接了多条线、 console 端口冲突、孤立设备、图标/文字/背景框重叠，以及条件型号风险。

可选：把拓扑画成辅助 PNG，不用开 eNSP 就能粗看布局。

PNG 不是 eNSP 原生界面，也不能证明 VirtualBox、镜像或设备能启动； 正常建图和验收流程不依赖它。

Args: path: .topo 文件路径。 out_path: 图片输出路径，省略则和 .topo 同名同目录，扩展名换成 .png。 scale: 缩放比例，设备多、连线挤的时候调大到 1.5 左右。 show_ports: 是否在连线两端标出接口名，默认标。

只读检查 eNSP、VirtualBox、模板机和设备镜像，不启动或修改任何虚拟机。

检查结果的 readyForTopology=true 才表示这份拓扑的已知前置条件 已满足。检查会识别 VirtualBox 版本、Hyper-V/VBS 冲突、Host-Only 网卡、 AR/WLAN 基机、SVRP 镜像和 USG6000V 镜像/注册状态。

Args: path: 可选的 .topo。给出后按其中实际型号判断 readyForTopology。 models: 可选的计划型号列表；还没创建拓扑时可先检查，例如 ["AR2220", "USG5500"]。与 path 同时给出时合并检查。 ensp_home: 可选的 eNSP 安装目录；省略时从环境、注册表和常见目录查找。

把拓扑导成写文档用得上的格式。

Args: path: .topo 文件路径。 format: mermaid（流程图源码）、drawio（可导入 draw.io）、 csv（设备表 + 接口连接表）。 out_path: 输出文件路径，省略则只把内容返回、不落盘。 csv 会写成两个文件，分别加 _devices / _links 后缀。

在已启动的 eNSP 设备 console 上逐条执行命令。

target 为设备名（配 topo_path）或端口号。view 为 keep/user/system。 username/password 用于需要登录的 console，只有密码的 console 可只给 password。 new_password 仅在设备要求初次设置或修改密码时使用；不主动修改已有密码。 stop_on_error 默认遇错停止；失败时不 save。confirm 为 Y/N/YES/NO。 返回 ok、逐条 results、errorCount、stoppedEarly 和 saveStatus；超时断线不会重试命令。

从文本或 UTF-8 .cfg 下发配置，config/config_file 必须且只能选一个。

自动进入系统视图，支持带 # 分段的 display current-configuration 配置文本， 分段时退出子视图再进入系统视图。默认遇错停止且不保存；不会自动回滚已生效配置。 username/password/new_password 与 device_exec 相同。save 默认 true。 CE 提示符标记存在未提交改动时，保存前先 commit；任何保存异常都返回失败状态。

读回运行配置；save_to 可保存 UTF-8 文件，compare_with 可与基线文件比较。

diff 同时提供 identical、onlyOnDevice、onlyInFile 和带上下文的 unifiedDiff， 保留行顺序及重复行。命令失败或超时不写出配置文件。登录参数与 device_exec 相同。

设备连通性和状态查询。action: ping/tracert/interfaces/arp/mac/route/vlan/ospf。

ping/tracert 需要 destination；ping count 为 1–100。ping 返回统计和 reachable， 无法解析时 reachable 为 null；其他查询返回 output 原文。ok 表示命令执行状态， ping 是否连通看 parsed.reachable。登录参数与 device_exec 相同。

查看或关闭 console 会话。action 为 list/close/close_all。

close 时 target 为端口号。后台每 30 秒回收空闲超过 5 分钟的连接； 服务退出时关闭所有连接。关闭操作等待该连接正在执行的命令结束。