net-connector 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3ed9fc4eb5accaa27d54868fab18082ec076db16d0a41c46c52dcf2d700b79c
-  data.tar.gz: c89082dfd48d20024a07abca986c19320be6a385d78f95f15b01ed5e1a1c68ed
+  metadata.gz: 5f018d69d8d4cf234bd90fcdd4e56a60e4184ef5ddb4f4cf15f4ff49206d5631
+  data.tar.gz: f8e0afe1a9131435134e5580dc0f3ffdc9823e55b7fc5665d60b1768f3c223fc
 SHA512:
-  metadata.gz: 7bbb0cd9634b952fd1dd84f9283fa30c008866f6a9494b52191927817514eb5d3662286f890782ef5d9ce3fcbdf540ff7a24d057923ba1ac22a9245b998b6429
-  data.tar.gz: 4151ff303d38cbf7ff2dad8262d60793e3aef0fc1b0170ab21fc52931a9ca9b74f45a3bcdf7574bfcab06b04ddd6e1949bae422673adb05cf25bac9ad1e9ccfb
+  metadata.gz: 620f62156a11192ae6648f48878ef61cb810830ee3c9dee8c7e8c6bc12b2b88e4c3f8ba420535bbb82b94a423328897c52844a4b7d76c4a404ae4e59b9f54c95
+  data.tar.gz: dc0ea681afb4a9a9cbeef79778d1cfebdf009004ee036a61dfcc8e9cb9f53579ad1967088a784bc2ed730874bdb1770207a57603b800caa55545dec8c8089915

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 更新记录
 
+## 0.13.0 - 2026-10-18
+
+- 不兼容调整：H3C 的 LLDP 列序变体合并为 `h3c/display_lldp_neighbor_information_list.textfsm`，显式引用旧模板路径的调用方需要更新。
+- Huawei VRP 增加 LLDP 邻居和接口描述读取，FortiOS 增加当前视图的接口描述读取，Junos 分别返回物理接口与逻辑单元描述。
+- 补齐各平台配置解析索引，修复 H3C 本地接口首列时的字段错位，并要求厂商名和命令完整匹配，避免选择错误模板。
+- 接口描述缺少值、引号未闭合或配置作用域不明时拒绝解析，Radware 端口名称中的转义引号可正确还原。
+- 拓扑计划和备份批次固定各自拥有的嵌套数据，调用方修改原始容器不再改变已生成结果，更新需通过 `with` 创建新快照。
+- 批量报告复用状态计数，减少重复统计时对设备结果的遍历，未知状态仍不能满足成功策略。
+- 修复 Ruby 3.2 下远程备份目标及回执的 `with` 绕过校验的问题，拒绝非法协议、路径及没有核验证据的完成声明。
+
 ## 0.12.0 - 2026-10-17
 
 - 不兼容调整：模块命名空间和加载路径按领域重组，厂商类改为 `Vendor::CiscoIos` 等直接入口，清单与报告存储分别使用 `inventory:`、`report_store:` 注入，旧名称及兼容别名已移除。

data/docs/VERIFICATION.md

@@ -246,3 +246,17 @@ TFTP 远端未核验回执以及自定义日志目录；离线复核同时支持
 源码根目录 `RENAMES.md` 记录批准的改名与兼容边界。完整验收仍运行 `bundle exec rake ci`；
 临时 PostgreSQL 使用 `bundle exec rake test:postgres`，可通过 `NC_TEST_PG_BINDIR` 指定服务端工具目录。
 最低 Ruby 3.2 必须在对应解释器中运行 lint/test；RuboCop 的 TargetRubyVersion 和 Ruby 4.0 测试不能替代此项。
+
+## 报告统计基准
+
+```sh
+bundle exec ruby script/benchmarks/report_workload.rb 100000 20
+```
+
+脚本分别输出批次构造、首次统计及重复统计的单调时钟耗时与对象分配数；合成结果的创建不计入测量。比较两个源码版本时，在同一 Ruby 与主机上各运行至少三次。批次构造会复制结果容器并累计状态，重复统计复用计数；不读取报告的调用方也承担构造成本。TFTP 文件核验与逐设备明细仍有线性成本，此基准不测网络吞吐或现场设备性能。
+
+## 厂商能力与模板一致性
+
+`test/capabilities_test.rb` 离线核对全部已注册平台的能力；`test/vendor_topology_parity_test.rb` 覆盖 Huawei LLDP 简表与接口描述、FortiOS 顶层接口描述/嵌套表隔离，以及 Junos 物理接口和逻辑单元描述。`test/textfsm_test.rb` 同时检查 H3C 两种列序在通用命令解析入口中的语义、内置厂商/命令的完整匹配，以及各配置方言的索引入口。完整性拒绝路径覆盖缺失表头、残缺记录、未闭合接口表/引号、VDOM 作用域不明和没有值的 Junos description。
+
+新增样本来自官方结构说明构造的离线会话，尚无设备联机验收；模板解析成功不能证明固件覆盖或候选配置写入安全。

data/docs/architecture.md

@@ -247,10 +247,10 @@ Ruby 对象显式拥有资源并使用关键字参数。`Profile` 提供有限
 | Cisco NX-OS | 是 | 是 | 是 | 是 | 是 | 是 |
 | Radware Alteon | 是 | 是 | 是 | 否 | 是 | 否 |
 | PAN-OS | 是 | 否 | 是 | 是 | 是 | 否，候选隔离未验证 |
-| 华为 | 是 | 是 | 是 | 否 | 否 | 否 |
+| 华为 VRP | 是 | 是 | 是 | 是，LLDP 简表 | 是 | 否，提交阶段未验证 |
 | 山石 | 是 | 是 | 是 | 是 | 是 | 是 |
 | Topsec TopOS | 是 | 否 | 否 | 否 | 否 | 否 |
-| Fortinet FortiOS | 是 | 是 | 是 | 是 | 否 | 否 |
+| Fortinet FortiOS | 是 | 是 | 是 | 是 | 是，当前视图顶层接口表 | 否 |
 | Juniper Junos | 是 | 否 | 否，原生 FTP/SCP | 是 | 是 | 否，候选库提交未开放 |
 
 Junos 的 `remote_backup` 通过 `RemoteBackup` 协调与厂商策略导出已提交配置；回执区分设备报告与远端核验。其余平台保持明确的能力声明，见[平台说明](vendors.md)。
@@ -290,7 +290,7 @@ router.supports?(:tftp_backup) # => true，不连接设备
 
 配置采集可把 `running_config_strategy` 绑定到 `Net::Connector::RunningConfig::Strategy` 子类。策略实现 `clean`、`result_step`、`prompt_text` 和 `validate_response!`；PAN-OS 候选差异只影响配置采集，直接 `execute_command("show config diff")` 返回该命令输出。静态命令列表留在档案中。`clean_config` 和受保护的 `config_result_step` 钩子可覆盖并调用 `super`。Base 负责通用脚本与锁内回调，不决定配置是否完整。
 
-拓扑策略通过 `topology_strategy YourStrategy` 绑定。类方法和实例方法 `supports?` 声明三种拓扑能力，其余方法提供命令、模板、输出完整性和接口拼写。Profile 校验完整接口，包括 `validate_descriptions!`、`change_error_code`、`enter_configuration_command`、`leave_configuration_commands`、`verification_commands`、`persistence_commands` 和 `persistence_confirmed?`。只读策略继承默认空阶段；可写策略必须明确每个阶段，不能用合并的收尾命令推断保存边界。即时生效且使用 interface 块的设备可继承 `Topology::ImmediateStrategy`。自定义采集必须执行已列入计划的命令并返回完成步骤；自定义厂商标签通过 `neighbor_template` 提供模板。
+拓扑策略通过 `topology_strategy YourStrategy` 绑定。类方法和实例方法 `supports?` 声明三种拓扑能力，其余方法提供命令、模板、输出完整性和接口拼写。Profile 校验完整接口，包括 `description_key`、`validate_descriptions!`、`change_error_code`、`enter_configuration_command`、`leave_configuration_commands`、`verification_commands`、`persistence_commands` 和 `persistence_confirmed?`。只读策略继承默认空阶段；可写策略必须明确每个阶段，不能用合并的收尾命令推断保存边界。即时生效且使用 interface 块的设备可继承 `Topology::ImmediateStrategy`。自定义采集必须执行已列入计划的命令并返回完成步骤；自定义厂商标签通过 `neighbor_template` 提供模板。
 
 业务操作针对单个连接器构造，并提供 `call`。TFTP 策略只处理厂商传输差异，公共操作统一成功和失败规则。生成的文件名经过 `TftpTarget` 校验及长度限制；带作用域的 IPv6 地址会转为安全 ASCII 标记，特别长的地址使用稳定 SHA-256 标记。原本合法的文件名保留拼写，只有整体过长才缩短清单名称。TFTP 返回值表示设备报告上传完成，服务器文件核对仍由调用方负责。
 
@@ -449,3 +449,13 @@ end
 `Settings#inventory` 为原始清单适配器包裹 `Inventory::Cache`，默认三天有效。缓存仅保存完整白名单 rows，Rules 和重复地址判定每次重做。身份、SQL 及绑定参数只参与摘要分区，不写入文件；凭据缺失仍在缓存读取前拒绝。过期刷新在有界、按身份的跨进程文件锁内完成，成功后原子替换；失败使用原时间的已验证历史，成功空清单替换旧值。最新查询成功与本地缓存持久化成功是两个事实，不能因写盘失败回退旧数据或重复查询。强刷跳过有效期，不跳过身份、限额、文件校验和失败回退边界。
 
 后台心跳和 HTTP 超时观察使用内部 `Concurrency::Observer` 作用域，前台保留主业务值和原始故障；观察线程的异常同步交付所有者，不受宿主全局线程异常策略影响。创建至登记期间延后中断，停止和等待期间保证线程回收；心跳普通故障转换为显示诊断，正常 HTTP 请求的未知观察故障仍传播。
+
+## 领域值与更新边界
+
+`Topology::Neighbor`、`Topology::Change`、`Topology::Plan` 各有同名文件，构造时复制并冻结自己拥有的字符串与容器。不可变子对象可在单设备、批次和结果之间共享；调用方的原始容器与格式化回调返回的字符串仍归调用方所有。计划构造校验数据形状，执行边界继续负责地址规范化、命令预检、现场证据重验及读回。
+
+`Netdisco::Batch` 复制结果数组和回调诊断，在构造时累计状态计数；`counts` 返回可修改的独立 Hash。未知状态不能满足成功策略。更新结果集合须使用 `with`，它重新计算计数。上述领域值和远程备份目标、回执的 `with` 显式经过构造函数，避免依赖不同 Ruby 版本中原生 `Data#with` 的初始化行为。
+
+拓扑的 `InterfaceBlocks` 模块集中核对 interface 块与解析记录的完整性，由立即生效的变更策略和 Huawei 的只读策略共同组合，读取能力不必继承写入流程。`description_key(row)` 把描述记录映射为领域身份；Junos 逻辑单元使用 `<物理接口>.<单元号>`，保留物理接口描述。FortiOS 读取当前视图顶层 `config system interface`，接口 `description` 与显示 `alias` 分开处理，嵌套 IPv6 表不产生接口记录；无法确认作用域、闭合或记录数量时拒绝结果。
+
+`Topology::QuotedText` 是描述字段的纯解码边界，不接触设备会话；厂商策略选择无引号文本的处理规则，解析异常统一携带 host、parse 阶段和 unrecognized_output 代码，不携带字段原文或底层异常 cause。配置模板保留完整带引号字段供业务层解码，不能先删外层引号而留下未还原的转义字符。

data/docs/templates.md

@@ -6,7 +6,7 @@
 
 `lib/net/connector/templates/` 统一采用 `<平台>/<完整命令名>[_格式变体].textfsm`。命令使用小写，空格、连字符和路径分隔符转为下划线；不使用缩写命令、字段用途名或额外的命令子目录。管道的输出格式选项保留为命令词，纯分页控制 `no-more` 不进入文件名。
 
-例如，`show running-config` 对应 `show_running_config.textfsm`，`display current-configuration` 对应 `display_current_configuration.textfsm`，`/cfg/dump` 对应 `cfg_dump.textfsm`，`show configuration | display set` 对应 `show_configuration_display_set.textfsm`。PAN-OS 配置视图的命令是 `show`，其 set 输出对应 `palo_alto/show.textfsm`。H3C 同一命令的列序变体使用 `_name_first` 和 `_local_first` 后缀。
+例如，`show running-config` 对应 `show_running_config.textfsm`，`display current-configuration` 对应 `display_current_configuration.textfsm`，`/cfg/dump` 对应 `cfg_dump.textfsm`，`show configuration | display set` 对应 `show_configuration_display_set.textfsm`。PAN-OS 配置视图的命令是 `show`，其 set 输出对应 `palo_alto/show.textfsm`。H3C 同一命令的列序由同一模板按表头切换状态。
 
 | 路径 | 输入与用途 |
 | --- | --- |
@@ -17,22 +17,24 @@
 | `cisco_nxos/show_running_config.textfsm` | NX-OS 运行配置中的接口和描述 |
 | `cisco_nxos/show_ip_interface_brief.textfsm` | NX-OS 多 VRF 接口、IP 及 protocol/link/admin 状态 |
 | `h3c/display_current_configuration.textfsm` | Comware 运行配置中的接口和描述 |
-| `h3c/display_lldp_neighbor_information_list_name_first.textfsm` | 邻居名称位于首列的 LLDP 列表 |
-| `h3c/display_lldp_neighbor_information_list_local_first.textfsm` | 本地接口位于首列的 LLDP 列表 |
+| `h3c/display_lldp_neighbor_information_list.textfsm` | 按表头识别名称首列或本地接口首列的 LLDP 列表 |
+| `huawei/display_lldp_neighbor_brief.textfsm` | VRP LLDP 邻居简表，保留端口类型与编号之间的空格 |
+| `huawei/display_current_configuration.textfsm` | VRP 运行配置中的接口和描述 |
 | `hillstone/show_configuration_running.textfsm` | StoneOS 运行配置中的接口和描述 |
 | `hillstone/show_lldp_neighbor_information.textfsm` | StoneOS 的 LLDP 邻居表 |
 | `palo_alto/show.textfsm` | PAN-OS set 格式中的接口和备注 |
 | `palo_alto/show_lldp_neighbors_all.textfsm` | PAN-OS 按接口分块的 LLDP 邻居输出 |
 | `radware/cfg_dump.textfsm` | Alteon 配置转储中的端口名称 |
+| `fortinet/show_full_configuration.textfsm` | 当前视图顶层接口表的描述，跳过嵌套表 |
 | `fortinet/diagnose_lldp_rx_neighbor.textfsm` | FortiOS 改名前后 LLDP 邻居查询的共同输出 |
 | `juniper/show_lldp_neighbors_detail.textfsm` | Junos LLDP 详细邻居块 |
-| `juniper/show_configuration_display_set.textfsm` | Junos 已提交 set 配置中的物理接口描述 |
+| `juniper/show_configuration_display_set.textfsm` | Junos 已提交 set 配置中的物理接口与逻辑单元描述 |
 
-H3C Wireless 沿用 H3C 模板。H3C 邻居策略检查表头后选择列顺序变体；未知表头直接拒绝，不尝试多个模板后采用碰巧解析出的部分结果。
+H3C Wireless 沿用 H3C 模板。H3C 邻居策略与通用命令解析共用按表头切换列序的模板；未知表头直接拒绝，不尝试多个模板后采用碰巧解析出的部分结果。
 
 ## 索引与显式选择
 
-根目录的 `index` 保持 TextFSM 的 `Template, Vendor, Command` 格式。Template 使用相对资源根目录的路径，Vendor 是连接器平台标识，Command 是命令匹配规则。一个共享模板可以被多个平台索引项引用。
+根目录的 `index` 保持 TextFSM 的 `Template, Vendor, Command` 格式。Template 使用相对资源根目录的路径，Vendor 是连接器平台标识，Command 是命令匹配规则。内置索引的 Vendor 与 Command 均使用 `\A...\z` 完整匹配，防止前缀厂商名称及带额外命令片段的输入误选模板。一个共享模板可以被多个平台索引项引用。
 
 ```ruby
 parser = Net::Connector::TextFSM.new
@@ -40,7 +42,7 @@ rows = parser.call(output, vendor: :cisco_ios, command: "show ip interface brief
 interfaces = parser.call(config, template: "cisco/show_running_config.textfsm")
 ```
 
-命令索引处理固定输出格式。依赖输出表头或视图上下文的模板由对应厂商策略显式选择。调用方也可以提供独立的 `template_dir:`，其索引和路径遵循相同规则。
+命令索引覆盖内置配置及邻居模板；H3C 列序在模板状态机内选择。模板本身只解析记录，厂商策略仍负责表头、完整性及作用域校验。调用方也可以提供独立的 `template_dir:`，其索引和路径遵循相同规则。
 
 ## 修改与验证
 
@@ -51,3 +53,7 @@ interfaces = parser.call(config, template: "cisco/show_running_config.textfsm")
 NX-OS 模板独立放在 `cisco_nxos/`，CDP 按邻居块清理状态并与设备块数量核对，残缺块不能借用下一条记录的字段。接口描述在空行或下一个顶层配置段结束，防止 route-map 等后续段落的描述覆盖接口描述。IP 接口摘要保留 `VRF`、`INTERFACE`、`IP_ADDRESS`、`PROTOCOL`、`LINK_STATUS`、`ADMIN_STATUS` 六个字段；`show ip interface brief` 与带 `vrf` 参数的命令共用此模板。
 
 输出字段参考 [Cisco NX-OS CDP 命令](https://developer.cisco.com/docs/nx-api-cli-reference-for-the-cisco-nexus-7000-series-platform/cdp-commands/)与 [Cisco Nexus IP 接口摘要](https://developer.cisco.com/docs/cisco-nexus-3000-and-9000-series-nx-api-rest-sdk-user-guide-and-api-reference-release-103x/querying-a-summary-of-ip-interface-status-and-configuration-information/)。测试使用脱敏合成输出，不代表真实设备及所有固件均已验证。
+
+## 描述字段的词法与业务值
+
+带引号的描述字段在模板中保留完整词法文本，`Topology::QuotedText` 负责还原引号与转义，并将不完整字段转为不含原文的领域错误。Junos、FortiOS、PAN-OS 与 Radware 使用同一解码边界；是否拆分无引号文本由厂商策略明确指定。接口不存在描述语句时可返回空描述，`description ""` 等显式空字符串也有明确含义；缺少值的 description/comment/name 语句则是残缺输入，不能被默认空字段掩盖。

data/docs/vendors.md

@@ -5,8 +5,8 @@
 | 平台键 | 系统与登录视图 | 采集命令 | 保存 | 原生远端备份 | 拓扑读取 |
 | --- | --- | --- | --- | --- | --- |
 | `topsec` | TopOS 防火墙，`TopsecOS#` 或 `#` 管理视图 | `show-running nostop` | 未开放 | 使用本地采集备份 | 未开放 |
-| `fortinet` | FortiGate/FortiOS，当前账号授权的根或 VDOM 视图 | `show full-configuration` | `execute cfg save` | TFTP `execute backup full-config tftp` | LLDP 邻居 |
-| `juniper` | Junos OS，`user@host>` 操作视图 | `show configuration \| display set \| no-more` | 已提交配置已持久化；不隐式提交候选库 | FTP/SCP `show configuration \| save` | LLDP 邻居、物理接口描述 |
+| `fortinet` | FortiGate/FortiOS，当前账号授权的根或 VDOM 视图 | `show full-configuration` | `execute cfg save` | TFTP `execute backup full-config tftp` | LLDP 邻居、当前视图接口描述 |
+| `juniper` | Junos OS，`user@host>` 操作视图 | `show configuration \| display set \| no-more` | 已提交配置已持久化；不隐式提交候选库 | FTP/SCP `show configuration \| save` | LLDP 邻居、物理接口及逻辑单元描述 |
 
 这些能力通过合成会话、解析样例和安装检查验证，尚无真实设备验收记录。Topsec 只实现有检索依据的 TopOS 配置读取方言；其他系列需依据其 CLI 手册接入，不能套用 Cisco 的命令。
 
@@ -36,7 +36,7 @@ TFTP 导出包括默认值，不接受 `source_file:` 或 `vrf:`。成功必须
 
 LLDP 查询先读取 `get system status`，明确解析版本后选择命令：7.6.2 及以前使用 `diagnose lldprx neighbor`，7.6.3 起使用 `diagnose lldp rx neighbor`。无法识别版本时直接报解析错误，不猜测命令。接口行数量与解析记录必须一致，空响应不会被当作零邻居。
 
-Junos LLDP 使用 `show lldp neighbors detail | no-more`，逐个本地接口块核对记录。残缺记录及只有标题的输出会报错；接口描述从已提交的 set 配置中读取，保留 `ge-`、`xe-`、`ae` 等原接口身份。
+Junos LLDP 使用 `show lldp neighbors detail | no-more`，逐个本地接口块核对记录。残缺记录及只有标题的输出会报错；接口描述从已提交的 set 配置中读取，逻辑单元用 `接口.单元号` 独立返回，保留 `ge-`、`xe-`、`ae` 等原接口身份。
 
 ## 命令依据
 
@@ -48,3 +48,14 @@ Junos LLDP 使用 `show lldp neighbors detail | no-more`，逐个本地接口块
 - [Juniper save 配置模式语义](https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/statement/save-cli-config.html)：配置模式的层级导出与远端 SCP。
 - [Juniper file copy 协议](https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/command/file-copy.html)：支持的远端文件传输 URL。
 - [Juniper LLDP 邻居字段](https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/command/show-lldp-neighbors.html)：接口、机箱、端口和系统名字段，`detail` 选项要求 Junos 19.1R2 或以上。
+
+## 拓扑读取能力对齐
+
+Huawei VRP 通过 `display lldp neighbor brief` 提供 LLDP 邻居，运行配置提供接口描述。简表不包含机箱 ID，邻居的 `chassis_id` 保留为空；接口类型与编号之间的空格在返回值中保留，在配置身份关联时移除。没有已验证的提交与保存阶段，因此只开放读取。
+
+FortiOS 从既有 `show full-configuration` 结果中读取顶层 `config system interface` 的 `description`，不把 `alias` 当作描述，不切换 VDOM 或全局视图。嵌套 VDOM 接口表、多个顶层接口表、缺少 next/end 或未闭合描述会报解析错误。输入按标准 CLI 的四空格缩进组织；不对其他导出格式作静默猜测。
+
+- [Huawei LLDP 邻居简表](https://info.support.huawei.com/hedex/api/pages/EDOC1100277650/AZM1016J/04/resources/command/yunshan/LLDPDISPLAYNEIBRIEF%28LLDPOM%29.html)：查询视图、字段及端口拼写。
+- [Huawei 当前接口配置](https://info.support.huawei.com/hedex/api/pages/EDOC1100363264/AEN0403J/05/resources/command/yunshan/BUILDRUNINTERFACE1%28CLIOM%29.html)：接口块及生效配置的范围。
+- [FortiOS 接口配置结构](https://docs.fortinet.com/document/fortigate/7.4.4/cli-reference/317104469/config-system-interface)：description、alias 与 IPv6 等嵌套配置。
+- [Junos 物理接口与逻辑单元描述示例](https://www.juniper.net/documentation/en_US/day-one-books/DayOne-Intro-SRv6.pdf)：物理描述与 unit 描述的独立配置层级。

data/lib/net/connector/device/profile.rb

@@ -74,7 +74,7 @@ module Net
         end
         @topology_strategy = strategy_class(topology_strategy, :topology_strategy,
                                             %i[neighbor_command neighbor_template expected_neighbor_count empty_neighbor_output?
-                                               protocol description_template interface_key configuration_interface
+                                               protocol description_template description_key interface_key configuration_interface
                                                decode_description validate_descriptions! change_error_code supports?
                                                enter_configuration_command change_commands script_command
                                                leave_configuration_commands verification_commands persistence_commands persistence_confirmed?])

data/lib/net/connector/device/remote_backup/receipt.rb

@@ -16,6 +16,10 @@ module Net
           super(server: server.dup.freeze, path: path.dup.freeze, protocol: protocol, username: username.dup.freeze,
                 completed_at: completed_at.dup.freeze, configuration_kind: configuration_kind, verification: verification)
         end
+
+        # Ruby 3.2 的原生更新跳过构造校验；更新也必须建立经过校验的快照。
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
       end
 
       # 完成后出现收尾错误时保留上传事实，避免调用方盲目重传。

data/lib/net/connector/device/remote_backup/target.rb

@@ -23,6 +23,9 @@ module Net
           super(host: host.dup.freeze, path: path.dup.freeze, username: username.dup.freeze, protocol: protocol)
         end
 
+        # Ruby 3.2 的原生更新跳过构造校验；更新也必须建立经过校验的快照。
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
         def url
           "#{protocol}://#{username}@#{host}/#{path}"
         end

data/lib/net/connector/device/topology/change.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "neighbor"
+
+module Net
+  module Connector
+    class Topology
+      # 变更的描述和接口归本对象所有；邻居值对象可安全共享。
+      Change = Data.define(:interface, :old_description, :new_description, :neighbor) do
+        def initialize(interface:, old_description:, new_description:, neighbor:)
+          fields = { interface: interface, old_description: old_description, new_description: new_description }
+          raise ArgumentError, "description change fields must be Strings" unless fields.values.all?(String)
+          raise ArgumentError, "description change requires a Neighbor" unless neighbor.instance_of?(Neighbor)
+
+          super(**fields.transform_values { |value| value.frozen? ? value : value.dup.freeze }, neighbor: neighbor)
+        end
+
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/immediate_strategy.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "strategy"
+require_relative "interface_blocks"
 require_relative "../../engine/terminal/renderer"
 
 module Net
@@ -8,18 +9,11 @@ module Net
     class Topology
       # 接口描述立即生效的设备：退出视图、读回、保存是不同阶段，不能在 finish 中提前保存。
       class ImmediateStrategy < Strategy
+        include InterfaceBlocks
+
         def verification_commands = @device.config_commands
         def persistence_commands = @device.profile.save_commands
 
-        # TextFSM 不能静默跳过未知接口头；否则目标行正确也不足以证明读回证据完整。
-        def validate_descriptions!(config, rows)
-          expected = config.scan(/^interface[ \t]+([^\r\n]*)/).flatten.map(&:strip)
-          return if expected == rows.map { |row| row.fetch("INTERFACE").strip }
-
-          raise ParsingError.new("interface description output was not fully recognized", code: :unrecognized_output,
-                                 host: @device.host, phase: :verify)
-        end
-
         # 完成提示必须来自保存步骤；原文和渲染文本中的失败优先，单独提示符/进度不算确认。
         def persistence_confirmed?(result)
           !result.steps.empty? && result.steps.all? do |step|

data/lib/net/connector/device/topology/interface_blocks.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Topology
+      # interface 块方言共用完整性校验；解析器不能静默遗漏未知接口头。
+      module InterfaceBlocks
+        def validate_descriptions!(config, rows)
+          expected = config.scan(/^interface[ \t]+([^\r\n]*)/).flatten.map(&:strip)
+          return if expected == rows.map { |row| row.fetch("INTERFACE").strip }
+
+          raise ParsingError.new("interface description output was not fully recognized", code: :unrecognized_output,
+                                 host: @device.host, phase: :verify)
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/neighbor.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Topology
+      # 邻居身份拥有独立字符串，格式化回调不能改写发现证据。
+      Neighbor = Data.define(:local_interface, :neighbor_name, :neighbor_interface, :chassis_id, :protocol) do
+        def initialize(local_interface:, neighbor_name:, neighbor_interface:, chassis_id:, protocol:)
+          fields = { local_interface: local_interface, neighbor_name: neighbor_name,
+                     neighbor_interface: neighbor_interface, chassis_id: chassis_id }
+          raise ArgumentError, "neighbor fields must be Strings" unless fields.values.all?(String)
+          raise ArgumentError, "neighbor protocol must be a Symbol" unless protocol.is_a?(Symbol)
+
+          super(**fields.transform_values { |value| value.frozen? ? value : value.dup.freeze }, protocol: protocol)
+        end
+
+        # Ruby 3.2 的 Data#with 不调用初始化，更新也必须重新建立快照。
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/plan.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "change"
+
+module Net
+  module Connector
+    class Topology
+      # 审批树在领域边界固定；单设备与批量操作共享同一不可变计划。
+      Plan = Data.define(:host, :vendor, :evidence, :changes, :commands) do
+        def initialize(host:, vendor:, evidence:, changes:, commands:)
+          unless host.is_a?(String) && vendor.is_a?(Symbol) && evidence.is_a?(Hash) &&
+                 changes.is_a?(Array) && changes.all? { |change| change.instance_of?(Change) } &&
+                 commands.is_a?(Array) && commands.all?(String)
+            raise ArgumentError, "description plan contains invalid fields"
+          end
+
+          super(host: host.frozen? ? host : host.dup.freeze, vendor: vendor,
+                evidence: copy_evidence(evidence), changes: changes.dup.freeze,
+                commands: commands.map { |command| command.frozen? ? command : command.dup.freeze }.freeze)
+        end
+
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
+        private
+
+        def copy_evidence(evidence)
+          evidence.to_h do |interface, fields|
+            unless interface.is_a?(String) && fields.is_a?(Array) && fields.size == 3 && fields.all?(String)
+              raise ArgumentError, "description plan contains invalid evidence"
+            end
+
+            [interface.frozen? ? interface : interface.dup.freeze,
+             fields.map { |field| field.frozen? ? field : field.dup.freeze }.freeze]
+          end.freeze
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/quoted_text.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "../../engine/errors"
+
+module Net
+  module Connector
+    class Topology
+      # 配置字段的引号解码是纯文本边界，不执行 shell，也不把原文写入错误。
+      module QuotedText
+        def self.decode(value, host:, split_unquoted: false)
+          value = value.strip
+          return value unless split_unquoted || value.start_with?('"')
+
+          Shellwords.split(value).join(" ")
+        rescue ArgumentError
+          raise ParsingError.new("interface description is not a complete single-line value",
+                                 code: :unrecognized_output, host: host, phase: :parse), cause: nil
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/strategy.rb

@@ -2,6 +2,7 @@
 
 require "shellwords"
 require_relative "interface_description"
+require_relative "quoted_text"
 
 module Net
   module Connector
@@ -56,6 +57,9 @@ module Net
         # 在下发前允许厂商调整命令对象及超时。
         def script_command(command) = command
 
+        # 描述记录默认表示物理接口；厂商可保留逻辑单元的独立身份。
+        def description_key(row) = interface_key(row.fetch("INTERFACE"))
+
         # 将发现接口名归一为查找当前配置所用的键。
         def interface_key(name) = InterfaceName.key(name)
 

data/lib/net/connector/device/topology.rb

@@ -2,6 +2,7 @@
 
 require_relative "topology/strategy"
 require_relative "topology/stages"
+require_relative "topology/plan"
 
 module Net
   module Connector
@@ -31,10 +32,6 @@ module Net
         end
       end
 
-      Neighbor = Data.define(:local_interface, :neighbor_name, :neighbor_interface, :chassis_id, :protocol)
-      Change = Data.define(:interface, :old_description, :new_description, :neighbor)
-      Plan = Data.define(:host, :vendor, :evidence, :changes, :commands)
-
       # 仅承载厂商档案的离线上下文，不能连接、查询或下发设备命令。
       PlanningContext = Data.define(:host, :vendor, :profile) do
         def config_commands = profile.config_commands
@@ -129,7 +126,7 @@ module Net
         rows = @parser.call(config, template: template, host: @device.host)
         @strategy.validate_descriptions!(config, rows)
         rows.each_with_object({}) do |row, found|
-          interface = @strategy.interface_key(row.fetch("INTERFACE"))
+          interface = @strategy.description_key(row)
           description = @strategy.decode_description(row.fetch("DESCRIPTION", ""))
           previous = found[interface]
           if previous && !previous.empty? && !description.empty? && previous != description
@@ -159,7 +156,6 @@ module Net
         validate_change_support!(:plan) if @strategy.supports?(:neighbors)
         discovered = neighbors
         current = interface_descriptions
-        current.each_value(&:freeze)
         evidence = evidence_for(discovered, current)
         changes = discovered.filter_map do |neighbor|
           old = current.fetch(@strategy.interface_key(neighbor.local_interface))
@@ -171,17 +167,16 @@ module Net
           InterfaceDescription.validate!(proposed)
           next if old == proposed
 
-          Change.new(interface: @strategy.configuration_interface(neighbor.local_interface).freeze, old_description: old.freeze,
-                     new_description: proposed.freeze, neighbor: neighbor).freeze
+          Change.new(interface: @strategy.configuration_interface(neighbor.local_interface), old_description: old,
+                     new_description: proposed, neighbor: neighbor)
         end.freeze
         commands = if changes.empty?
                      []
                    else
                      stage_scripts(changes).values.flat_map { |script| script.map(&:text) }
                    end
-        commands.each(&:freeze)
-        Plan.new(host: @device.host.dup.freeze, vendor: @device.vendor, evidence: evidence,
-                 changes: changes, commands: commands.freeze).freeze
+        Plan.new(host: @device.host, vendor: @device.vendor, evidence: evidence,
+                 changes: changes, commands: commands)
       end
 
       # 只有明确确认且邻居和旧描述未变化时，才下发计划中的命令。

data/lib/net/connector/netdisco/batch.rb

@@ -15,9 +15,10 @@ module Net
           unless duration_ms.nil? || (duration_ms.is_a?(Numeric) && duration_ms.real? && duration_ms.finite? && duration_ms >= 0)
             raise ArgumentError, "duration_ms must be nonnegative and finite"
           end
+          raise ArgumentError, "status must be a Symbol or String" unless status.is_a?(Symbol) || status.is_a?(String)
           raise ArgumentError, "diagnostic must be a Diagnostic" unless diagnostic.nil? || diagnostic.instance_of?(Diagnostic)
 
-          super(device: device, status: status, backup: backup, error_code: error_code,
+          super(device: device, status: status.is_a?(String) ? status.dup.freeze : status, backup: backup, error_code: error_code,
                 error_type: error_type.is_a?(String) ? error_type.dup.freeze : error_type,
                 started_at: started_at&.dup&.freeze, finished_at: finished_at&.dup&.freeze,
                 duration_ms: duration_ms, diagnostic: diagnostic)
@@ -46,17 +47,45 @@ module Net
       # 汇总一次批量任务的设备结果、回调故障和报告写入状态。
       Batch = Data.define(:mode, :outcomes, :started_at, :finished_at, :callback_errors,
                           :report_location, :report_error) do
-        # 按设备最终状态统计数量。
-        def counts = outcomes.map(&:status).tally
+        # 批次拥有容器与审计元数据；调用方只能通过 with 构造新快照。
+        def initialize(mode:, outcomes:, started_at:, finished_at:, callback_errors:, report_location:, report_error:)
+          unless outcomes.is_a?(Array) && outcomes.all? { |outcome| outcome.instance_of?(Outcome) } && callback_errors.is_a?(Array)
+            raise ArgumentError, "batch requires outcome and callback error Arrays"
+          end
+
+          outcomes = outcomes.dup.freeze
+          @counts = outcomes.each_with_object({}) { |outcome, found| found[outcome.status] = found.fetch(outcome.status, 0) + 1 }.freeze
+          super(mode: mode, outcomes: outcomes,
+                started_at: started_at&.dup&.freeze, finished_at: finished_at&.dup&.freeze,
+                callback_errors: callback_errors.map { |entry| copy_callback_error(entry) }.freeze,
+                report_location: report_location&.dup&.freeze, report_error: report_error&.dup&.freeze)
+        end
+
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
+        # 只累计最终计数，不创建与清单等长的中间状态数组。
+        def counts = @counts.dup
 
         # 仅在所有设备成功且回调、报告均正常时判定整批成功。
-        def success? = !outcomes.empty? && outcomes.all?(&:success?) && callback_errors.empty? && report_error.nil?
+        def success? = !outcomes.empty? && @counts.fetch(:backed_up, 0) + @counts.fetch(:reported_uploaded, 0) == outcomes.size &&
+                       callback_errors.empty? && report_error.nil?
 
         # 空清单与已尝试但未全部成功的批次分别标记。
         def status = outcomes.empty? ? :no_devices : (success? ? :succeeded : :incomplete)
 
         # 显式从原始执行结果构造报告。
         def build_report(policy: :strict) = Report.new(self, policy: policy)
+
+        private
+
+        def copy_callback_error(entry)
+          unless entry.is_a?(Hash) && (entry[:host].nil? || entry[:host].is_a?(String))
+            raise ArgumentError, "callback errors must contain a host and error type"
+          end
+
+          { host: entry[:host]&.dup&.freeze, error_type: Error::Metadata.type(entry[:error_type]) }.freeze
+        end
+
       end
 
       autoload :Report, File.expand_path("report", __dir__)

data/lib/net/connector/netdisco/operations/outcome.rb

@@ -30,7 +30,6 @@ module Net
               raise ArgumentError, "operation duration must be nonnegative and finite"
             end
 
-            value = immutable_plan_value(value) if value.is_a?(Topology::Plan)
             super(device: device, status: status, value: value, error: error,
                   started_at: started_at.dup.freeze, finished_at: finished_at.dup.freeze, duration_ms: duration_ms)
           end
@@ -69,19 +68,6 @@ module Net
                     end
             raise ArgumentError, "operation state contradicts its domain value or error" unless valid && same_error
           end
-
-          # 外部构造或 with 更新也复制审批树，不仅冻结 Data 的最外层。
-          def immutable_plan_value(value)
-            case value
-            when String then value.frozen? ? value : value.dup.freeze
-            when Array then value.map { |item| immutable_plan_value(item) }.freeze
-            when Hash then value.to_h { |key, item| [immutable_plan_value(key), immutable_plan_value(item)] }.freeze
-            when Topology::Plan, Topology::Change, Topology::Neighbor
-              fields = value.to_h.transform_values { |item| immutable_plan_value(item) }
-              value.class.new(**fields).freeze
-            else value
-            end
-          end
         end
 
       end

data/lib/net/connector/netdisco/operations.rb

@@ -65,14 +65,14 @@ module Net
             result = connector.plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
             raise TypeError, "description planning must return a Topology::Plan" unless result.is_a?(Topology::Plan)
 
-            copy_plan(result)
+            normalize_plan(result)
           end
         end
 
-        # 审批计划整体复制并验证；单设备应用仍执行现场重验、读回和保存，不直接重放 commands。
+        # 审批计划固定并验证；单设备应用仍执行现场重验、读回和保存，不直接重放 commands。
         def apply_interface_descriptions(plans:, confirmed: false, concurrency: DEFAULT_SETTING, on_start: nil, on_result: nil)
           validate_confirmation!(confirmed)
-          tasks = normalize_mapping(plans, :plans) { |plan| copy_plan(plan) }
+          tasks = normalize_mapping(plans, :plans) { |plan| normalize_plan(plan) }
           tasks.each do |host, plan|
             raise ArgumentError, "plan host does not match its target" unless normalize_host(plan.host) == host
           end
@@ -125,38 +125,20 @@ module Net
           end.freeze
         end
 
-        # 外部审批容器不与执行共享可变子对象，非法领域结构在任何连接前拒绝。
-        def copy_plan(plan)
-          raise ArgumentError, "plans must contain Topology::Plan values" unless plan.is_a?(Topology::Plan)
-          normalize_host(plan.host)
-          unless Net::Connector.vendors.include?(plan.vendor) && plan.evidence.is_a?(Hash) &&
-                 plan.changes.is_a?(Array) && plan.commands.is_a?(Array) && plan.commands.all?(String)
-            raise ArgumentError, "description plan contains invalid fields"
-          end
-          commands = Script.new(plan.commands).map { |command| command.text.dup.freeze }.freeze
-          evidence = plan.evidence.to_h do |interface, fields|
-            unless interface.is_a?(String) && fields.is_a?(Array) && fields.size == 3 && fields.all?(String)
-              raise ArgumentError, "description plan contains invalid evidence"
-            end
-            [interface.dup.freeze, fields.map { |field| field.dup.freeze }.freeze]
-          end.freeze
-          changes = plan.changes.map { |change| copy_change(change) }.freeze
-          raise ArgumentError, "empty description plan cannot contain commands" if changes.empty? && !commands.empty?
+        # 计划自身拥有不可变审批树；这里仅处理批次的地址和输入预检。
+        def normalize_plan(plan)
+          raise ArgumentError, "plans must contain Topology::Plan values" unless plan.instance_of?(Topology::Plan)
+          host = normalize_host(plan.host)
+          raise ArgumentError, "description plan contains an unsupported vendor" unless Net::Connector.vendors.include?(plan.vendor)
 
-          Topology::Plan.new(host: normalize_host(plan.host), vendor: plan.vendor, evidence: evidence,
-                             changes: changes, commands: commands).freeze
-        end
-
-        def copy_change(change)
-          unless change.is_a?(Topology::Change) && change.old_description.is_a?(String) &&
-                 change.neighbor.is_a?(Topology::Neighbor) && change.neighbor.to_h.values.all? { |value| value.is_a?(String) || value.is_a?(Symbol) }
-            raise ArgumentError, "description plan contains an invalid change"
+          Script.new(plan.commands)
+          plan.changes.each do |change|
+            Topology::InterfaceDescription.validate_interface!(change.interface)
+            Topology::InterfaceDescription.validate!(change.new_description)
           end
-          Topology::InterfaceDescription.validate_interface!(change.interface)
-          Topology::InterfaceDescription.validate!(change.new_description)
-          neighbor = Topology::Neighbor.new(**change.neighbor.to_h.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }).freeze
-          Topology::Change.new(interface: change.interface.dup.freeze, old_description: change.old_description.dup.freeze,
-                               new_description: change.new_description.dup.freeze, neighbor: neighbor).freeze
+          raise ArgumentError, "empty description plan cannot contain commands" if plan.changes.empty? && !plan.commands.empty?
+
+          host == plan.host ? plan : plan.with(host: host)
         end
 
         # 策略只固定一次；清单与连接使用同一快照，凭据仍在每台任务开始时动态读取。

data/lib/net/connector/netdisco/report.rb

@@ -46,8 +46,9 @@ module Net
 
           return false if policy == :verified && outcomes.any? { |outcome| outcome.success? && !server_verified?(outcome) }
 
-          outcomes.any? { |outcome| SUCCESS_STATUSES.include?(outcome.status) } &&
-            outcomes.all? { |outcome| SUCCESS_STATUSES.include?(outcome.status) || IGNORABLE_STATUSES.include?(outcome.status) }
+          statuses = counts
+          SUCCESS_STATUSES.any? { |status| statuses.key?(status) } &&
+            statuses.keys.all? { |status| SUCCESS_STATUSES.include?(status) || IGNORABLE_STATUSES.include?(status) }
         end
 
         def with(**attributes)
@@ -61,14 +62,14 @@ module Net
                           policy: policy, duration_ms: duration_ms, report_diagnostic: diagnostic, log_directory: log_directory)
         end
 
-        # 统计不创建逐设备明细；文本与进度输出复用此入口，不缓存调用方持有的批次。
+        # 统计不创建逐设备明细；文本与进度输出复用此入口，复用批次拥有的状态计数。
         def statistics
           batch_data = batch_summary
+          attempted = ATTEMPTED_STATUSES.sum { |status| batch_data[:counts].fetch(status, 0) }
           batch_data.merge(
             schema_version: 2, policy: policy, policy_success: policy_success?, duration_ms: duration_ms,
-            coverage: { complete: !outcomes.empty? && outcomes.all? { |outcome| ATTEMPTED_STATUSES.include?(outcome.status) },
-                        attempted: outcomes.count { |outcome| ATTEMPTED_STATUSES.include?(outcome.status) },
-                        skipped: outcomes.count { |outcome| !ATTEMPTED_STATUSES.include?(outcome.status) } },
+            coverage: { complete: !outcomes.empty? && attempted == outcomes.size,
+                        attempted: attempted, skipped: outcomes.size - attempted },
             callback_errors: callback_errors.map { |entry| { host: entry[:host], error_type: Error::Metadata.type(entry[:error_type]) } },
             report_location: report_location, report_error: Error::Metadata.type(report_error),
             verification: mode == :tftp ? { verified: outcomes.count { |outcome| server_verified?(outcome) },
@@ -86,14 +87,16 @@ module Net
 
         # 生成可写入报告及供命令行展示的结构化摘要。
         def batch_summary
+          statuses = counts
+          succeeded = SUCCESS_STATUSES.sum { |status| statuses.fetch(status, 0) }
+          partial = statuses.fetch(:saved_with_error, 0) + statuses.fetch(:reported_with_error, 0)
+          failed = statuses.fetch(:failed, 0)
           {
             mode: mode, status: status, started_at: started_at.iso8601, finished_at: finished_at.iso8601,
             total: outcomes.size,
-            succeeded: outcomes.count(&:success?),
-            partial: outcomes.count(&:partial?),
-            failed: outcomes.count { |outcome| outcome.status == :failed },
-            skipped: outcomes.count(&:skipped?),
-            counts: counts,
+            succeeded: succeeded, partial: partial, failed: failed,
+            skipped: outcomes.size - succeeded - partial - failed,
+            counts: statuses,
             callback_errors: callback_errors
           }
         end

data/lib/net/connector/templates/cisco/show_running_config.textfsm

@@ -5,6 +5,7 @@ Start
   ^interface ${INTERFACE}$$ -> Interface
 
 Interface
+  ^\s+description\s*$$ -> Error "interface description has no value"
   ^\s+description ${DESCRIPTION}$$
   ^!$$ -> Record Start
   ^interface .+ -> Continue.Record

data/lib/net/connector/templates/cisco_nxos/show_running_config.textfsm

@@ -5,6 +5,7 @@ Start
   ^interface ${INTERFACE}$$ -> Interface
 
 Interface
+  ^\s+description\s*$$ -> Error "interface description has no value"
   ^\s+description ${DESCRIPTION}$$
   ^interface .+ -> Continue.Record
   ^interface ${INTERFACE}$$

data/lib/net/connector/templates/fortinet/show_full_configuration.textfsm

@@ -0,0 +1,21 @@
+Value Required INTERFACE ((?:[^"\\\s]|\\.)+)
+Value DESCRIPTION (.*)
+
+Start
+  ^config system interface\s*$$ -> Interfaces
+
+Interfaces
+  ^    edit "${INTERFACE}"\s*$$ -> Interface
+  ^    edit ${INTERFACE}\s*$$ -> Interface
+  ^end\s*$$ -> Start
+
+Interface
+  ^        set description\s*$$ -> Error "interface description has no value"
+  ^        set description ${DESCRIPTION}$$
+  ^        config .+$$ -> Nested
+  ^    next\s*$$ -> Record Interfaces
+
+Nested
+  ^        end\s*$$ -> Interface
+
+EOF

data/lib/net/connector/templates/h3c/display_current_configuration.textfsm

@@ -5,6 +5,7 @@ Start
   ^interface ${INTERFACE}$$ -> Interface
 
 Interface
+  ^\s+description\s*$$ -> Error "interface description has no value"
   ^\s+description ${DESCRIPTION}$$
   ^#$$ -> Record Start
   ^interface .+ -> Continue.Record

data/lib/net/connector/templates/h3c/{display_lldp_neighbor_information_list_local_first.textfsm → display_lldp_neighbor_information_list.textfsm}

@@ -4,5 +4,11 @@ Value Required CHASSIS_ID (\S+)
 Value Required NEIGHBOR_INTERFACE (Port\s+\d+|\S+)
 
 Start
-  ^\s*display lldp neighbor-information list\s*$$
+  ^\s*System Name\s+Local Interface\b.*$$ -> NameFirst
+  ^\s*(?:Local Interface|LocalIf)\s+.*$$ -> LocalFirst
+
+NameFirst
+  ^\s*${NEIGHBOR_NAME}\s+${LOCAL_INTERFACE}\s+${CHASSIS_ID}\s+${NEIGHBOR_INTERFACE}\s*$$ -> Record
+
+LocalFirst
   ^\s*${LOCAL_INTERFACE}\s+${CHASSIS_ID}\s+${NEIGHBOR_INTERFACE}\s+${NEIGHBOR_NAME}\s*$$ -> Record

data/lib/net/connector/templates/hillstone/show_configuration_running.textfsm

@@ -5,6 +5,7 @@ Start
   ^interface ${INTERFACE}$$ -> Interface
 
 Interface
+  ^\s+description\s*$$ -> Error "interface description has no value"
   ^\s+description ${DESCRIPTION}$$
   ^\s*exit\s*$$ -> Record Start
   ^interface .+ -> Continue.Record

data/lib/net/connector/templates/huawei/display_current_configuration.textfsm

@@ -0,0 +1,13 @@
+Value Required INTERFACE (\S+(?:[ \t]+\d[\w/.:_-]*)?)
+Value DESCRIPTION (.*)
+
+Start
+  ^interface ${INTERFACE}$$ -> Interface
+
+Interface
+  ^\s+description\s*$$ -> Error "interface description has no value"
+  ^\s+description ${DESCRIPTION}$$
+  ^#$$ -> Record Start
+  ^interface .+ -> Continue.Record
+  ^interface ${INTERFACE}$$
+  ^return$$ -> Record End

data/lib/net/connector/templates/huawei/display_lldp_neighbor_brief.textfsm

@@ -0,0 +1,9 @@
+Value Required LOCAL_INTERFACE ([A-Za-z][A-Za-z0-9-]*[ \t]*\d[\w/.:-]*)
+Value Required NEIGHBOR_NAME (\S+)
+Value Required NEIGHBOR_INTERFACE ([A-Za-z][A-Za-z0-9-]*[ \t]*\d[\w/.:-]*|\S+)
+
+Start
+  ^\s*Local Intf\s+Neighbor Dev\s+Neighbor Intf\s+Exptime.*$$ -> Neighbors
+
+Neighbors
+  ^\s*${LOCAL_INTERFACE}\s+${NEIGHBOR_NAME}\s+${NEIGHBOR_INTERFACE}\s+\d+\s*$$ -> Record

data/lib/net/connector/templates/index

@@ -1,13 +1,23 @@
 Template, Vendor, Command
-cisco_ios/show_ip_interface_brief.textfsm, cisco_ios, show ip interface brief$
-cisco/show_cdp_neighbors_detail.textfsm, cisco_ios, show cdp neighbors detail$
-cisco_nxos/show_cdp_neighbors_detail.textfsm, cisco_nxos, show cdp neighbors detail$
-h3c/display_lldp_neighbor_information_list_name_first.textfsm, h3c, display lldp neighbor-information list$
-h3c/display_lldp_neighbor_information_list_name_first.textfsm, h3c_wireless, display lldp neighbor-information list$
-hillstone/show_lldp_neighbor_information.textfsm, hillstone, show lldp neighbor-information$
-palo_alto/show_lldp_neighbors_all.textfsm, palo_alto, show lldp neighbors all$
-fortinet/diagnose_lldp_rx_neighbor.textfsm, fortinet, diagnose lldp rx neighbor$
-fortinet/diagnose_lldp_rx_neighbor.textfsm, fortinet, diagnose lldprx neighbor$
-juniper/show_lldp_neighbors_detail.textfsm, juniper, show lldp neighbors detail \| no-more$
-cisco_nxos/show_ip_interface_brief.textfsm, cisco_nxos, show ip interface brief(?: vrf [A-Za-z0-9_.-]+)?$
-cisco_nxos/show_running_config.textfsm, cisco_nxos, show running-config$
+cisco_ios/show_ip_interface_brief.textfsm, \Acisco_ios\z, \Ashow ip interface brief\z
+cisco/show_cdp_neighbors_detail.textfsm, \Acisco_ios\z, \Ashow cdp neighbors detail\z
+cisco_nxos/show_cdp_neighbors_detail.textfsm, \Acisco_nxos\z, \Ashow cdp neighbors detail\z
+h3c/display_lldp_neighbor_information_list.textfsm, \Ah3c\z, \Adisplay lldp neighbor-information list\z
+h3c/display_lldp_neighbor_information_list.textfsm, \Ah3c_wireless\z, \Adisplay lldp neighbor-information list\z
+hillstone/show_lldp_neighbor_information.textfsm, \Ahillstone\z, \Ashow lldp neighbor-information\z
+palo_alto/show_lldp_neighbors_all.textfsm, \Apalo_alto\z, \Ashow lldp neighbors all\z
+fortinet/diagnose_lldp_rx_neighbor.textfsm, \Afortinet\z, \Adiagnose lldp rx neighbor\z
+fortinet/diagnose_lldp_rx_neighbor.textfsm, \Afortinet\z, \Adiagnose lldprx neighbor\z
+juniper/show_lldp_neighbors_detail.textfsm, \Ajuniper\z, \Ashow lldp neighbors detail(?: \| no-more)?\z
+cisco_nxos/show_ip_interface_brief.textfsm, \Acisco_nxos\z, \Ashow ip interface brief(?: vrf [A-Za-z0-9_.-]+)?\z
+cisco_nxos/show_running_config.textfsm, \Acisco_nxos\z, \Ashow running-config\z
+cisco/show_running_config.textfsm, \Acisco_ios\z, \Ashow running-config\z
+h3c/display_current_configuration.textfsm, \Ah3c\z, \A(?:display current-configuration|dis cur)\z
+h3c/display_current_configuration.textfsm, \Ah3c_wireless\z, \A(?:display current-configuration|dis cur)\z
+huawei/display_current_configuration.textfsm, \Ahuawei\z, \A(?:display current-configuration|dis cur)\z
+huawei/display_lldp_neighbor_brief.textfsm, \Ahuawei\z, \Adisplay lldp neighbor brief\z
+hillstone/show_configuration_running.textfsm, \Ahillstone\z, \Ashow configuration running\z
+radware/cfg_dump.textfsm, \Aradware\z, \A/cfg/dump\z
+palo_alto/show.textfsm, \Apalo_alto\z, \Ashow\z
+fortinet/show_full_configuration.textfsm, \Afortinet\z, \Ashow full-configuration\z
+juniper/show_configuration_display_set.textfsm, \Ajuniper\z, \Ashow configuration \| display set(?: \| no-more)?\z

data/lib/net/connector/templates/juniper/show_configuration_display_set.textfsm

@@ -1,6 +1,10 @@
 Value Required INTERFACE (\S+)
+Value UNIT (\d+)
 Value DESCRIPTION (.*)
 
 Start
+  ^set interfaces \S+ (?:unit \d+ )?description\s*$$ -> Error "interface description has no value"
+  ^set interfaces ${INTERFACE} unit ${UNIT} description ${DESCRIPTION}$$ -> Record
+  ^set interfaces ${INTERFACE} unit ${UNIT}\s+.*$$ -> Continue.Record
   ^set interfaces ${INTERFACE} description ${DESCRIPTION}$$ -> Record
   ^set interfaces ${INTERFACE}\s+.*$$ -> Record

data/lib/net/connector/templates/palo_alto/show.textfsm

@@ -2,5 +2,6 @@ Value Required INTERFACE (\S+)
 Value DESCRIPTION (.*)
 
 Start
+  ^set network interface ethernet \S+ comment\s*$$ -> Error "interface comment has no value"
   ^set network interface ethernet ${INTERFACE} comment ${DESCRIPTION}$$ -> Record
   ^set network interface ethernet ${INTERFACE}\s+.*$$ -> Record

data/lib/net/connector/templates/radware/cfg_dump.textfsm

@@ -2,12 +2,14 @@ Value Required INTERFACE (\d+)
 Value DESCRIPTION (.*)
 
 Start
-  ^/(?:c|cfg)/port ${INTERFACE}/name "${DESCRIPTION}"\s*$$ -> Record
+  ^/(?:c|cfg)/port \d+/name\s*$$ -> Error "port name has no value"
+  ^/(?:c|cfg)/port ${INTERFACE}/name ${DESCRIPTION}$$ -> Record
   ^/(?:c|cfg)/port ${INTERFACE}\s*$$ -> Port
 
 Port
-  ^\s+name "${DESCRIPTION}"\s*$$
+  ^/(?:c|cfg)/port \d+/name\s*$$ -> Error "port name has no value"
+  ^\s+name\s*$$ -> Error "port name has no value"
   ^\s+name ${DESCRIPTION}$$
   ^/.* -> Continue.Record
-  ^/(?:c|cfg)/port ${INTERFACE}/name "${DESCRIPTION}"\s*$$ -> Record Start
+  ^/(?:c|cfg)/port ${INTERFACE}/name ${DESCRIPTION}$$ -> Record Start
   ^/(?:c|cfg)/port ${INTERFACE}\s*$$

data/lib/net/connector/vendor/fortinet/topology.rb

@@ -9,7 +9,7 @@ module Net
       class Fortinet < Net::Connector::Base
         # LLDP 命令自 7.6.3 改名；先核对只读版本信息，不通过失败重试猜测方言。
         class Topology < Net::Connector::Topology::Strategy
-          def self.supports?(capability) = capability == :neighbors
+          def self.supports?(capability) = %i[neighbors interface_descriptions].include?(capability)
 
           def neighbor_command
             status = @device.execute_command("get system status").value!
@@ -22,6 +22,29 @@ module Net
             (release <=> [7, 6, 3]) >= 0 ? "diagnose lldp rx neighbor" : "diagnose lldprx neighbor"
           end
 
+          def description_template = "fortinet/show_full_configuration.textfsm"
+
+          # 接口名称大小写与设备配置一致，不套用 Cisco 接口简称。
+          def interface_key(name) = decode_description(name)
+
+          def configuration_interface(name) = name
+
+          def decode_description(value) = Net::Connector::Topology::QuotedText.decode(value, host: @device.host, split_unquoted: true)
+
+          # 模板只接受当前视图的顶层接口表，嵌套 VDOM 或残缺配置不能冒充完整结果。
+          def validate_descriptions!(config, rows)
+            tables = config.scan(/^config system interface[ \t]*$/).size
+            nested = config.match?(/^[ \t]+config system interface[ \t]*$/)
+            table = config[/^config system interface[ \t]*\n(.*?)^end[ \t]*$/m, 1]
+            expected = table&.scan(/^    edit[ \t]+([^\r\n]+)/)&.flatten
+            names = expected&.map { |name| decode_description(name) }
+            return if !nested && tables == 1 && names == rows.map { |row| interface_key(row.fetch("INTERFACE")) } &&
+                      table.scan(/^    next[ \t]*$/).size == names.size
+
+            raise ParsingError.new("FortiOS interface table is incomplete or outside the current view",
+                                   code: :unrecognized_output, host: @device.host, phase: :parse)
+          end
+
           def neighbor_template(_output) = "fortinet/diagnose_lldp_rx_neighbor.textfsm"
 
           def expected_neighbor_count(output, _template) = output.scan(/^\s*\d+\s+port\b/).size

data/lib/net/connector/vendor/h3c/topology.rb

@@ -30,18 +30,17 @@ module Net
           # 只认可本厂商明确的保存完成行，设备提示符返回本身不能证明持久化。
           def persistence_pattern = /\ASaved the current configuration to mainboard device successfully\.\z/i
 
-          # H3C 不同版本的列顺序不同，按表头选对应模板。
+          # H3C 列顺序由同一模板按表头分支；策略先拒绝未知表头。
           def neighbor_template(output)
-            return "h3c/display_lldp_neighbor_information_list_name_first.textfsm" if output.match?(/^\s*System Name\s+Local Interface\b/im)
-            return "h3c/display_lldp_neighbor_information_list_local_first.textfsm" if output.match?(/^\s*(?:Local Interface|LocalIf)\s+/im)
+            return "h3c/display_lldp_neighbor_information_list.textfsm" if output.match?(TABLE_HEADER)
 
             raise ParsingError.new("H3C LLDP table header was not recognized", code: :unrecognized_output,
                                    host: @device.host, phase: :discover)
           end
 
           # 按表头后的有效数据行计数，未知行会让完整性校验失败。
-          def expected_neighbor_count(output, template)
-            local_column = template == "h3c/display_lldp_neighbor_information_list_name_first.textfsm" ? 1 : 0
+          def expected_neighbor_count(output, _template)
+            local_column = output.match?(/^[ \t]*System Name[ \t]+Local Interface\b/i) ? 1 : 0
             lines = neighbor_lines(output)
             return unless lines.all? do |line|
               interface = line.split.fetch(local_column, nil)

data/lib/net/connector/vendor/huawei/topology.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../../device/base"
+require_relative "../../device/topology/strategy"
+require_relative "../../device/topology/interface_blocks"
+
+module Net
+  module Connector
+    module Vendor
+      class Huawei < Net::Connector::Base
+        # VRP 简表支持统一的 LLDP 读取；不假设不同 VRP 的提交与保存阶段相同。
+        class Topology < Net::Connector::Topology::Strategy
+          include Net::Connector::Topology::InterfaceBlocks
+
+          HEADER = /^[ \t]*Local Intf[ \t]+Neighbor Dev[ \t]+Neighbor Intf[ \t]+Exptime/i
+          private_constant :HEADER
+
+          def self.supports?(capability) = %i[neighbors interface_descriptions].include?(capability)
+
+          def neighbor_command = "display lldp neighbor brief"
+
+          def neighbor_template(_output) = "huawei/display_lldp_neighbor_brief.textfsm"
+
+          def description_template = "huawei/display_current_configuration.textfsm"
+
+          def expected_neighbor_count(output, _template)
+            return unless output.match?(HEADER)
+
+            neighbor_lines(output).size
+          end
+
+          def empty_neighbor_output?(output) = output.match?(HEADER) && neighbor_lines(output).empty?
+
+          # VRP 的端口类型和编号允许用空格分开；身份比较去掉该空格。
+          def interface_key(name) = super(name.delete(" \t"))
+
+          private
+
+          def neighbor_lines(output)
+            output.lines("\n").drop_while { |line| !line.match?(HEADER) }.drop(1).map(&:strip).reject do |line|
+              line.empty? || line.match?(/\A[-=]+\z/) || line.match?(/\A(?:<[^>]+>|\[[^\]]+\])\z/)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/vendor/huawei.rb

@@ -2,6 +2,7 @@
 
 require_relative "../device/base"
 require_relative "huawei/tftp"
+require_relative "huawei/topology"
 
 module Net
   module Connector
@@ -13,6 +14,7 @@ module Net
         profile do
           running_config_strategy Net::Connector::RunningConfig::Rendered
           tftp_strategy Tftp
+          topology_strategy Topology
           commands do
             running_config "dis cur"
             save_config "save force"

data/lib/net/connector/vendor/juniper/topology.rb

@@ -17,6 +17,12 @@ module Net
 
           def neighbor_template(_output) = "juniper/show_lldp_neighbors_detail.textfsm"
 
+          # 逻辑单元的描述独立于物理端口，不能覆盖端口的 LLDP 身份。
+          def description_key(row)
+            unit = row.fetch("UNIT", "")
+            unit.empty? ? interface_key(row.fetch("INTERFACE")) : "#{interface_key(row.fetch("INTERFACE"))}.#{unit}"
+          end
+
           def description_template = "juniper/show_configuration_display_set.textfsm"
 
           def expected_neighbor_count(output, _template) = output.scan(/^\s*Local Interface\s*:/i).size
@@ -27,12 +33,7 @@ module Net
           end
 
           # 不闭合的描述必须报错，不能把截断的首行当作完整描述。
-          def decode_description(value)
-            Shellwords.split(value).join(" ")
-          rescue ArgumentError
-            raise ParsingError.new("Junos interface description is incomplete", code: :unrecognized_output,
-                                   host: @device.host, phase: :parse), cause: nil
-          end
+          def decode_description(value) = Net::Connector::Topology::QuotedText.decode(value, host: @device.host, split_unquoted: true)
         end
       end
     end

data/lib/net/connector/vendor/palo_alto/topology.rb

@@ -40,13 +40,7 @@ module Net
           end
 
           # 模板按行读取；未闭合的引号表示证据不完整，不能把首行当成旧描述。
-          def decode_description(value)
-            value = value.strip
-            value.start_with?('"') ? Shellwords.split(value).join(" ") : value
-          rescue ArgumentError
-            raise ParsingError.new("PAN-OS interface comment is not a complete single-line value",
-                                   code: :unrecognized_output, host: @device.host, phase: :parse)
-          end
+          def decode_description(value) = Net::Connector::Topology::QuotedText.decode(value, host: @device.host)
 
           # 用 PAN-OS set 语法生成接口备注变更。
           def change_commands(change)

data/lib/net/connector/vendor/radware/topology.rb

@@ -12,6 +12,8 @@ module Net
           # Alteon 只支持读取端口描述，不提供邻居发现或自动改写。
           def self.supports?(capability) = capability == :interface_descriptions
 
+          def decode_description(value) = Net::Connector::Topology::QuotedText.decode(value, host: @device.host)
+
           # 从设备配置转储解析端口名称。
           def description_template = "radware/cfg_dump.textfsm"
         end

data/lib/net/connector/version.rb

@@ -3,6 +3,6 @@
 module Net
   module Connector
     # gemspec、CLI 与发布工具共用此版本，运行时读取不触发设备依赖加载。
-    VERSION = "0.12.0"
+    VERSION = "0.13.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - net-connector contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expect-pty
@@ -362,9 +362,14 @@ files:
 - lib/net/connector/device/tftp/strategy.rb
 - lib/net/connector/device/tftp/target.rb
 - lib/net/connector/device/topology.rb
+- lib/net/connector/device/topology/change.rb
 - lib/net/connector/device/topology/immediate_strategy.rb
+- lib/net/connector/device/topology/interface_blocks.rb
 - lib/net/connector/device/topology/interface_description.rb
 - lib/net/connector/device/topology/interface_name.rb
+- lib/net/connector/device/topology/neighbor.rb
+- lib/net/connector/device/topology/plan.rb
+- lib/net/connector/device/topology/quoted_text.rb
 - lib/net/connector/device/topology/stages.rb
 - lib/net/connector/device/topology/strategy.rb
 - lib/net/connector/engine/authentication.rb
@@ -439,11 +444,13 @@ files:
 - lib/net/connector/templates/cisco_nxos/show_ip_interface_brief.textfsm
 - lib/net/connector/templates/cisco_nxos/show_running_config.textfsm
 - lib/net/connector/templates/fortinet/diagnose_lldp_rx_neighbor.textfsm
+- lib/net/connector/templates/fortinet/show_full_configuration.textfsm
 - lib/net/connector/templates/h3c/display_current_configuration.textfsm
-- lib/net/connector/templates/h3c/display_lldp_neighbor_information_list_local_first.textfsm
-- lib/net/connector/templates/h3c/display_lldp_neighbor_information_list_name_first.textfsm
+- lib/net/connector/templates/h3c/display_lldp_neighbor_information_list.textfsm
 - lib/net/connector/templates/hillstone/show_configuration_running.textfsm
 - lib/net/connector/templates/hillstone/show_lldp_neighbor_information.textfsm
+- lib/net/connector/templates/huawei/display_current_configuration.textfsm
+- lib/net/connector/templates/huawei/display_lldp_neighbor_brief.textfsm
 - lib/net/connector/templates/index
 - lib/net/connector/templates/juniper/show_configuration_display_set.textfsm
 - lib/net/connector/templates/juniper/show_lldp_neighbors_detail.textfsm
@@ -473,6 +480,7 @@ files:
 - lib/net/connector/vendor/hillstone/topology.rb
 - lib/net/connector/vendor/huawei.rb
 - lib/net/connector/vendor/huawei/tftp.rb
+- lib/net/connector/vendor/huawei/topology.rb
 - lib/net/connector/vendor/juniper.rb
 - lib/net/connector/vendor/juniper/remote_backup.rb
 - lib/net/connector/vendor/juniper/topology.rb

data/lib/net/connector/templates/h3c/display_lldp_neighbor_information_list_name_first.textfsm

@@ -1,8 +0,0 @@
-Value Required LOCAL_INTERFACE (\S+)
-Value NEIGHBOR_NAME (\S+)
-Value Required CHASSIS_ID (\S+)
-Value Required NEIGHBOR_INTERFACE (Port\s+\d+|\S+)
-
-Start
-  ^\s*display lldp neighbor-information list\s*$$
-  ^\s*${NEIGHBOR_NAME}\s+${LOCAL_INTERFACE}\s+${CHASSIS_ID}\s+${NEIGHBOR_INTERFACE}\s*$$ -> Record