扫描 eNSP 设备的 Telnet 端口（默认 2000-2100）。

返回 {"host": str, "ports": [int, ...]}。

建立到指定 eNSP 设备的 Telnet 会话。

port 为 eNSP 分配的 Telnet 端口（通常 2000+）。 若 reuse=True 且已存在同 (host, port) 的活跃会话则直接复用。

列出当前所有活跃会话的快照。

关闭一个会话并释放其 Telnet 连接。

关闭所有会话。

清理闲置超过 idle_seconds 秒的会话。

把指定会话切换到 system-view。

下发单条命令，返回命令输出、耗时与命令层报错标记。

errored=True 表示设备回显中包含 Error:（如命令不存在 / 参数错误）， 此时应据 errors 回显修正命令后重试，而不是继续下发后续配置。

批量下发命令，每条命令返回独立的 :class:TelnetResult。

stop_on_error=True 时，遇到连接错误 或 设备命令报错（errored）会立刻中断。 auto_diagnose=True 时，对每条失败命令自动调用诊断引擎，返回 diagnosis 字段。 返回中 has_error 汇总是否存在任意一条命令报错。

触发 save 流程：先 quit 退到用户视图，再 save 并确认 y。

获取指定会话输出缓冲中最近 lines 行。

清空指定会话的输出缓冲。

获取设备元信息（hostname、型号、版本、uptime）。

refresh=True 时重新执行 display version；否则只返回已缓存的值。

获取设备当前运行配置（display current-configuration）。

这是配置前必须做的探查步骤。eNSP 不同镜像 / VRP 版本支持的命令集并不一致， 直接套用记忆中的命令很可能报错（Error: Unrecognized command）。正确做法是：

1. 先用 :func:ensp_get_device_info 拿到型号与 VRP 版本；

2. 再用本工具拿到设备 已有的 配置（已存在的接口 IP、VLAN、路由、特性开关等）；

3. 基于这两份真实信息生成配置命令，而非凭空猜测；

4. 下发后用 :func:ensp_send_command 的 errored 回显 / :func:ensp_verify_interfaces 等校验，失败则据设备反馈修正。

在指定会话上执行 display ip interface brief，解析后返回。

执行 display ip routing-table，可按 protocol 过滤（如 ospf static）。

执行 display ospf peer brief + display ospf routing，合并返回。

执行 display vlan，可按 vlan_id 过滤。

在指定设备上开启 LLDP（用于让设备广播 / 接收邻居信息）。

LLDP（Link Layer Discovery Protocol）是华为 eNSP 设备默认支持的链路层发现协议， 设备互相通告自己的接口和系统名。开启后即可用 ensp_verify_lldp_neighbors 看到哪些接口连到了对端设备的哪个接口。

工作流程：

1. system-view 进入系统视图

2. lldp enable 全局使能（华为默认全局开启后所有接口都广播）

3. 若指定了 interfaces，进每个接口视图执行 lldp enable （仅在接口视图下需要单独使能时才需要；默认情况下全局开即可）

参数：

• session_id_or_name：会话 ID 或设备名

• interfaces：可选，要单独使能 LLDP 的接口列表（如 ["GigabitEthernet0/0/2"]）； 留空表示仅全局使能

返回每步的执行结果（命令 / elapsed / output / errored），失败时停止并标记。

采集指定设备的 LLDP 邻居信息（真实物理连接）。

与 ensp_verify_interfaces 的区别：

• ensp_verify_interfaces 只看本设备接口状态，不知道对端是谁

• 本工具通过 LLDP 看到的是「对端设备 + 对端接口」，是物理事实

自动使能 LLDP（默认开启）：

1. 先发 display lldp neighbor brief（默认）或 display lldp neighbor

2. 若回显表明 LLDP 未使能（命令报错，或含 LLDP is not enabled / LLDP功能未使能 等关键字），且 auto_enable=True，自动走： system-view → lldp enable → quit，等 enable_retry_delay 秒 让邻居收敛，再发一次采集命令

3. 若第二次仍然失败，返回 status="error" 并附带 hint

把 auto_enable 设为 False 时，行为退回到「仅采集，未使能则报错」， 便于在已经手工开启 LLDP 的脚本里复用。

输出格式：

• neighbors 列表：每条含 local_interface / remote_device / remote_interface / remote_chassis_id 等字段

• 返回的接口名已归一化（GE0/0/0 → GigabitEthernet0/0/0）

• lldp_was_enabled / auto_enable_attempts 字段告诉调用方 本次是否自动使能过 LLDP（避免 LLM 重复操作）

典型用法：

• 在每台路由器 / 交换机上各调一次，收集到全网 LLDP 邻居后 传给 ensp_cross_validate_topology 做交叉验证

核心实现见 :func:grbj_ensp_mcp.lldp_verifier.collect_lldp_neighbors_with_auto_enable。

把 .topo 文件解析结果与设备 LLDP 邻居做交叉验证。

这是「拓扑纠错」的核心入口——ensp_parse_topology 只看拓扑文件， 而 ensp_verify_lldp_neighbors 反映物理事实。两者不一致时就是 拓扑图错位 / 线缆未接 / 对端设备未启 / 老拓扑需要更新等问题的信号。

工作流程：

1. 解析 topo_path（XML 或 ZIP 自动识别）

2. 接收 lldp_results（每台设备调 ensp_verify_lldp_neighbors 返回的 scan 字段或整个返回对象）

3. 对每条边做双向比对：

   • matched：.topo 和 LLDP 都看到的连线（接口端点完全一致）

   • topo_only：.topo 记录了但 LLDP 没看到（线没接 / 对端未启 / LLDP 未使能）

   • lldp_only：物理上接了但 .topo 没记（拓扑图过时）

   • mismatched：两端点都对得上，但至少一个接口号错位（拓扑图错位）

4. 输出结构化 JSON + Markdown 报告，便于 LLM 直接理解和用户存档

参数：

• topo_path：.topo 文件绝对路径

• lldp_results：列表，元素为 ensp_verify_lldp_neighbors 的返回 （建议传 scan 字段；为了容错，传整个返回对象也可）

• device_aliases：可选，把 LLDP 的 system-name 映射到 .topo 里的设备名（如 {"AR1": "R1"}），处理 sysname 与拓扑名不一致的情况

典型使用场景：

• 生成配置前验证接口号：调用本工具确认 .topo 的 GE0/0/0 是否真的接在物理 GE0/0/0 上，避免下发配置时把 IP 配到错误接口

• 拓扑图纠错：发现接口错位后，用 ensp_gather_diagnostic_context 收集上下文，让 LLM 给出修改建议（更新 .topo 或重新接线）

• 实验前环境检查：学生实验前用本工具确认 eNSP GUI 接的线与设计一致

在指定会话上执行 ping -c {count} {target}，解析丢包率。

对一条命令错误进行智能诊断，返回根因分析与修复建议。

参数：

• session_id_or_name：会话 ID 或设备名

• error_text：设备回显中的错误文本（如 ensp_send_command 返回的 errors）

• command：触发该错误的命令（可选，用于更精准的诊断）

返回：

• category：错误分类标签

• severity：严重级别（critical/error/warning/info）

• root_causes：可能的根因列表

• probe_commands：建议先执行的探查命令

• fix_suggestions：修复建议列表

• confidence：诊断置信度（high/medium/low）

使用场景： 当 ensp_send_command 返回 errored=True 时，将 errors 字段 传入本工具获取诊断，而不是直接放弃或盲目重试。

对批量命令结果（ensp_send_commands 的 results 列表）进行批量诊断。

返回每个失败命令的诊断结果，并汇总修复建议。

当命令执行失败时，自动收集设备全貌供 LLM 深度推理。

与 ensp_diagnose_error 的区别：

• ensp_diagnose_error 返回规则引擎的快速匹配结果

• 本工具收集设备真实状态（配置、接口、最近输出），生成结构化推理 prompt， 供 LLM 像网络工程师一样分析根因

本工具会自动执行以下探查命令（无需手动调用）：

1. display version — 设备信息

2. display current-configuration — 运行配置

3. display ip interface brief — 接口状态

返回的 reasoning_prompt 字段可直接用于 LLM 推理， 引导 LLM 按四步分析：错误类型判断 → 根因分析 → 修复方案 → 验证步骤。

典型使用场景：

• ensp_smart_config 返回 has_error=true 且规则诊断置信度为 low 时

• 规则引擎未覆盖的未知错误

• 需要 LLM 结合配置上下文做深度推理的复杂场景

对设备进行全面健康检查，自动诊断异常。

检查项：

1. 会话状态（连接是否正常）

2. 设备元信息（VRP 版本、型号）

3. 接口状态（物理/协议状态，自动诊断 down 的接口）

4. OSPF 邻居状态（可选，需 check_ospf=True）

5. 路由表完整性（可选，需 check_routes=True）

返回结构化诊断报告，包含每个检查项的 issues 列表和修复建议。

智能配置下发：逐条下发命令，遇到错误时自动诊断并提供修复建议。

与 ensp_send_commands 的区别：

• 每条命令执行后，若 errored=True 自动调用诊断引擎

• 返回中包含每条失败命令的 diagnosis 字段

• stop_on_error=True 时首条失败即停止，避免级联错误

• auto_gather_llm_context=True 时，失败后自动收集设备全貌供 LLM 深度推理

参数：

• session_id_or_name：会话 ID 或设备名

• commands：命令列表

• stop_on_error：遇错即停（推荐 True）

• auto_diagnose：自动对失败命令执行规则诊断（默认 True）

• auto_gather_llm_context：失败后自动收集设备全貌生成 LLM 推理上下文（默认 False）

• experiment_description：用户实验需求描述（用于 LLM 推理上下文）

一站式下发实验配置：按设备规划的命令序列逐台下发 + 校验 + 报告。

参数：

• plan：{ "设备名": ["system-view", "interface GE0/0/0", "ip address ...", ...], ... }

• verify_targets：可选校验项，元素为 {"device": str, "kind": "ospf"|"vlan"|"routes"|"interfaces"|"ping", "args": {...}}

• auto_save：下发完成后自动 save

工作流：

1. 对 plan 中每台设备调用 ensp_send_commands（自动进 system-view 后再下发）

2. 跑 verify_targets

3. auto_save=True 时全部 save

4. 返回结构化报告 + Markdown

解析本地 .topo 文件（XML 或 ZIP 格式）。

解析 base64 编码的 .topo 字节（用于 MCP 客户端直接上传）。

输入是标准 base64 字符串。返回与 ensp_parse_topology 一致的结构。

加载 .topo 拓扑：解析 → 探测每个设备的 com_port → 自动建连 → 输出启动指引。

典型工作流：

1. 调用本工具解析 .topo，获得设备清单与连线；

2. 工具对每个 com_port 做 TCP 探测（无需 telnet 登录）；

3. 对可达端口自动调用 ensp_connect_device 建连；

4. 对不可达端口，把设备列入 pending_devices 并附带 eNSP GUI 启动步骤；

5. 用户在 eNSP GUI 中启动设备后，再次调用本工具（或 ensp_scan_devices + ensp_connect_device 组合）补齐剩余会话。

返回 JSON + Markdown 报告（markdown_report 字段）。