net-connector 0.4.0 → 0.4.1

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

@@ -50,7 +50,7 @@ module Net
                  end
           if options[:host]
             host = IPAddr.new(options[:host]).to_s
-            raise ArgumentError, "host #{options[:host]} was not found in inventory" unless plan.inventory.any? { |device| device.host == host }
+            raise ArgumentError, "清单中未找到设备 #{options[:host]}" unless plan.inventory.any? { |device| device.host == host }
           end
           if options[:plan]
             @output.puts JSON.pretty_generate(plan_summary(plan))
@@ -74,7 +74,7 @@ module Net
           @error.puts "net-connector-backup: #{exception.message}"
           2
         rescue StandardError => exception
-          @error.puts "net-connector-backup failed (#{exception.class})"
+          @error.puts "net-connector-backup 失败（#{exception.class}）"
           2
         end
 
@@ -84,25 +84,25 @@ module Net
         def parse_options
           options = { config: @env["NET_CONNECTOR_CONFIG"] }
           parser = OptionParser.new do |args|
-            args.banner = "Usage: net-connector-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
-            args.on("--config FILE", "Read non-secret YAML settings") { |value| options[:config] = value }
-            args.on("--show-config", "Print effective non-secret settings") { options[:show_config] = true }
-            args.on("--plan", "Preview selected inventory without device connections") { options[:plan] = true }
-            args.on("--tftp", "Use device-initiated TFTP backup") { options[:tftp] = true }
-            args.on("--export IP", "Export a saved local configuration") { |value| options[:export] = value }
-            args.on("--output FILE", "Write exported configuration to a private file") { |value| options[:output] = value }
-            args.on("--directory PATH", "Backup and report directory") { |value| options[:directory] = value }
-            args.on("--host IP", "Select one inventory device by management IP") { |value| options[:host] = value }
-            args.on("--concurrency N", Integer, "Maximum simultaneous devices") { |value| options[:concurrency] = value }
-            args.on("--limit-per-vendor N", Integer, "Select N devices per vendor (1..5)") do |value|
+            args.banner = "用法：net-connector-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
+            args.on("--config FILE", "读取不含凭据的 YAML 设置") { |value| options[:config] = value }
+            args.on("--show-config", "显示生效的非敏感设置") { options[:show_config] = true }
+            args.on("--plan", "预览设备清单，不连接设备") { options[:plan] = true }
+            args.on("--tftp", "由设备发起 TFTP 备份") { options[:tftp] = true }
+            args.on("--export IP", "导出已保存的本地配置") { |value| options[:export] = value }
+            args.on("--output FILE", "将导出配置写入私有文件") { |value| options[:output] = value }
+            args.on("--directory PATH", "备份和报告目录") { |value| options[:directory] = value }
+            args.on("--host IP", "按管理地址选择一台设备") { |value| options[:host] = value }
+            args.on("--concurrency N", Integer, "最大并发设备数") { |value| options[:concurrency] = value }
+            args.on("--limit-per-vendor N", Integer, "每厂商选择 N 台设备（1 至 5）") do |value|
               options[:limit] = value
             end
-            args.on("--all", "Select all ready devices") { options[:all] = true }
-            args.on("-v", "--version", "Print version") do
+            args.on("--all", "选择全部就绪设备") { options[:all] = true }
+            args.on("-v", "--version", "显示版本") do
               @output.puts Net::Connector::VERSION
               options[:done] = true
             end
-            args.on("-h", "--help", "Show help") do
+            args.on("-h", "--help", "显示帮助") do
               @output.puts args
               options[:done] = true
             end
@@ -116,11 +116,11 @@ module Net
         # 拒绝互斥或缺少依赖的命令行选项。
         def validate_options!(options)
           modes = [:show_config, :plan, :export].count { |key| options[key] }
-          raise ArgumentError, "choose one of --show-config, --plan, or --export" if modes > 1
-          raise ArgumentError, "--output requires --export" if options[:output] && !options[:export]
-          raise ArgumentError, "--all and --limit-per-vendor cannot be combined" if options[:all] && options[:limit]
+          raise ArgumentError, "--show-config、--plan 和 --export 只能选择一项" if modes > 1
+          raise ArgumentError, "--output 需要同时指定 --export" if options[:output] && !options[:export]
+          raise ArgumentError, "--all 不能与 --limit-per-vendor 同时使用" if options[:all] && options[:limit]
           if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:concurrency] || options[:host])
-            raise ArgumentError, "--export cannot be combined with backup options"
+            raise ArgumentError, "--export 不能与备份选项同时使用"
           end
         end
 

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

@@ -48,18 +48,14 @@ module Net
 
         # 生成设备 CLI 可用的 ASCII 远端文件名。
         def tftp_filename
-          return "running-config.xml" if vendor == :palo_alto
-
           label = name.to_s.encode(Encoding::US_ASCII, invalid: :replace, undef: :replace, replace: "-")
                       .gsub(/[^A-Za-z0-9._-]+/, "-").byteslice(0, 180)
                       .gsub(/\A[._-]+|[._-]+\z/, "")
           label = vendor&.to_s || "device" if label.empty?
-          extension = case vendor
-                      when :radware then "tgz"
-                      when :hillstone then "dat"
-                      else "cfg"
-                      end
-          TftpTarget.filename(host, extension: extension, label: label)
+          strategy = Net::Connector.vendor_class(vendor).profile.tftp_strategy if vendor
+          # 旧版自定义策略只需实现实例接口，缺少命名接口时沿用通用 cfg 名称。
+          strategy = Operations::Tftp::Strategy unless strategy.respond_to?(:filename)
+          TftpTarget.validate_path!(strategy.filename(host, label: label))
         end
 
         # 按厂商及设备地址实例化连接器。

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

@@ -63,7 +63,7 @@ module Net
           end
         end
 
-        # 让设备主动导出配置，避免 PAN-OS 固定远端文件名在同批任务中冲突。
+        # 让设备主动导出配置，在执行前检查同批目标文件名冲突。
         def tftp_backup_all(server:, source_files: {}, concurrency: @settings.concurrency,
                             limit_per_vendor: 5, vrfs: {}, on_start: nil, on_result: nil, plan: nil,
                             report_directory: @settings.backup_directory)
@@ -131,53 +131,7 @@ module Net
         def validate_plan!(plan, mode)
           raise ArgumentError, "plan must be a #{mode} Netdisco plan" unless plan.is_a?(Plan) && plan.mode == mode
 
-          inventory = plan.inventory
-          ready = plan.ready
-          outcomes = plan.outcomes
-          unless inventory.is_a?(Array) && inventory.all?(Device) && ready.is_a?(Array) &&
-                 outcomes.is_a?(Array) && outcomes.size == inventory.size
-            raise ArgumentError, "plan inventory and outcomes must have the same device slots"
-          end
-
-          selected = {}
-          previous_index = -1
-          ready.each do |task|
-            unless task.is_a?(Array) && task.size == 2 && task.first.is_a?(Integer)
-              raise ArgumentError, "plan contains an invalid device task"
-            end
-
-            index, device = task
-            unless index > previous_index && index < inventory.size && inventory[index].equal?(device) && device.ready?
-              raise ArgumentError, "plan tasks must reference ready inventory devices in order"
-            end
-
-            selected[index] = true
-            previous_index = index
-          end
-          if mode == :tftp && ready.count { |_index, device| device.vendor == :palo_alto } > 1
-            raise ArgumentError, "plan cannot upload multiple Palo Alto devices to one TFTP filename"
-          end
-
-          inventory.each_with_index do |device, index|
-            result = outcomes[index]
-            next if selected[index] && result.nil?
-
-            unless !selected[index] && valid_skipped_outcome?(result, device, mode)
-              raise ArgumentError, "plan outcome does not match its inventory slot"
-            end
-          end
-        end
-
-        # 未执行设备必须保留与清单一致的跳过原因，且不能带有执行产物。
-        def valid_skipped_outcome?(result, device, mode)
-          return false unless result.is_a?(Outcome) && result.device.equal?(device) && result.backup.nil? &&
-                              result.error_code.nil? && result.error_type.nil? &&
-                              result.started_at.nil? && result.finished_at.nil?
-
-          return result.status == device.issue unless device.ready?
-
-          result.status == :sample_limit ||
-            (mode == :tftp && device.vendor == :palo_alto && result.status == :remote_filename_collision)
+          plan.validate!
         end
 
         # 构造包含错误类型的单台设备结果。

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Netdisco
+      # 固定一份清单上的选择结果与跳过原因，供预览和执行复用。
+      Plan = Data.define(:mode, :inventory, :ready, :outcomes) do
+        # Data 只冻结对象自身；这里复制并冻结可能由调用方修改的计划容器。
+        def initialize(mode:, inventory:, ready:, outcomes:)
+          unless inventory.is_a?(Array) && ready.is_a?(Array) && outcomes.is_a?(Array)
+            raise ArgumentError, "plan inventory, ready tasks, and outcomes must be Arrays"
+          end
+
+          tasks = ready.map { |task| task.is_a?(Array) ? task.dup.freeze : task }.freeze
+          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze)
+        end
+
+        # 按清单顺序返回选中的设备。
+        def selected = ready.map(&:last)
+
+        # 在任何设备 I/O 前校验完整快照，外部构造或修改的计划也必须遵守相同约束。
+        def validate!
+          raise ArgumentError, "plan mode must be backup or tftp" unless %i[backup tftp].include?(mode)
+          unless inventory.all?(Device) && outcomes.size == inventory.size
+            raise ArgumentError, "plan inventory and outcomes must have the same device slots"
+          end
+
+          selected_indices = {}
+          filenames = {}
+          previous_index = -1
+          ready.each do |task|
+            unless task.is_a?(Array) && task.size == 2 && task.first.is_a?(Integer)
+              raise ArgumentError, "plan contains an invalid device task"
+            end
+
+            index, device = task
+            unless index > previous_index && index < inventory.size && inventory[index].equal?(device) && device.ready?
+              raise ArgumentError, "plan tasks must reference ready inventory devices in order"
+            end
+            if mode == :tftp
+              filename = device.tftp_filename
+              raise ArgumentError, "plan cannot upload multiple devices to one TFTP filename" if filenames.key?(filename)
+
+              filenames[filename] = true
+            end
+            selected_indices[index] = true
+            previous_index = index
+          end
+
+          inventory.each_with_index do |device, index|
+            result = outcomes[index]
+            next if selected_indices[index] && result.nil?
+
+            unless !selected_indices[index] && valid_skipped_outcome?(result, device, filenames)
+              raise ArgumentError, "plan outcome does not match its inventory slot"
+            end
+          end
+          self
+        end
+
+        private
+
+        # 跳过结果不携带执行产物；文件冲突必须有本批次实际执行的目标作为依据。
+        def valid_skipped_outcome?(result, device, filenames)
+          return false unless result.is_a?(Outcome) && result.device.equal?(device) && result.backup.nil? &&
+                              result.error_code.nil? && result.error_type.nil? &&
+                              result.started_at.nil? && result.finished_at.nil?
+
+          return result.status == device.issue unless device.ready?
+
+          result.status == :sample_limit ||
+            (mode == :tftp && result.status == :remote_filename_collision && filenames.key?(device.tftp_filename))
+        end
+      end
+    end
+  end
+end

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

@@ -1,24 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "plan"
+
 module Net
   module Connector
     module Netdisco
-      # 固定一份清单上的选择结果与跳过原因，供预览和执行复用。
-      Plan = Data.define(:mode, :inventory, :ready, :outcomes) do
-        # Data 只冻结对象自身；这里复制并冻结可能由调用方修改的计划容器。
-        def initialize(mode:, inventory:, ready:, outcomes:)
-          unless inventory.is_a?(Array) && ready.is_a?(Array) && outcomes.is_a?(Array)
-            raise ArgumentError, "plan inventory, ready tasks, and outcomes must be Arrays"
-          end
-
-          tasks = ready.map { |task| task.is_a?(Array) ? task.dup.freeze : task }.freeze
-          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze)
-        end
-
-        # 按清单顺序返回选中的设备。
-        def selected = ready.map(&:last)
-      end
-
       # 根据设备就绪状态、厂商采样及远端文件冲突建立备份计划。
       class Planner
         # 保存本次规划使用的清单快照。
@@ -37,22 +23,25 @@ module Net
                      else
                        candidates
                      end
-          # PAN-OS 导出使用固定远端文件名，同批只允许一台设备写入。
-          palo_alto_index = selected.find { |device, _index| device.vendor == :palo_alto }&.last if mode == :tftp
           selected_indices = selected.to_h { |_device, index| [index, true] }
+          filenames = {}
+          if mode == :tftp
+            # 先按采样顺序保留每个目标的首台设备，再按清单顺序输出结果。
+            selected.each { |device, index| filenames[device.tftp_filename] ||= index }
+          end
           outcomes = Array.new(@inventory.size)
           ready = @inventory.each_with_index.filter_map do |device, index|
             if !device.ready?
               outcomes[index] = skipped(device, device.issue)
               nil
-            elsif mode == :tftp && device.vendor == :palo_alto && index != palo_alto_index
+            elsif !selected_indices.key?(index)
+              outcomes[index] = skipped(device, :sample_limit)
+              nil
+            elsif mode == :tftp && filenames.fetch(device.tftp_filename) != index
               outcomes[index] = skipped(device, :remote_filename_collision)
               nil
-            elsif selected_indices.key?(index)
-              [index, device].freeze
             else
-              outcomes[index] = skipped(device, :sample_limit)
-              nil
+              [index, device].freeze
             end
           end
           Plan.new(mode: mode, inventory: @inventory, ready: ready.freeze, outcomes: outcomes.freeze)

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

@@ -21,37 +21,44 @@ module Net
           worker_count = [tasks.size, @concurrency].min
           worker_count.times { queue << nil }
           callback_errors = Queue.new
-          threads = Array.new(worker_count) do
-            Thread.new do
-              Thread.current.report_on_exception = false
-              while (task = queue.pop)
-                index, device = task
-                started_at = Time.now.utc
-                begin
-                  on_start&.call(device)
-                rescue StandardError => error
-                  callback_errors << { host: device.host, error_type: error.class.name }.freeze
-                end
-                result = begin
-                           yield device
-                         rescue StandardError => error
-                           on_error.call(device, error)
-                         end
-                result = result.with(started_at: started_at, finished_at: Time.now.utc)
-                outcomes[index] = result
-                Array(on_result).each do |callback|
+          finished = Queue.new
+          threads = []
+          completed = false
+          begin
+            # 创建线程也属于批次生命周期；后续创建失败时要关闭已有任务。
+            worker_count.times do
+              threads << Thread.new do
+                Thread.current.report_on_exception = false
+                while (task = queue.pop)
+                  index, device = task
+                  started_at = Time.now.utc
                   begin
-                    callback.call(result)
+                    on_start&.call(device)
                   rescue StandardError => error
                     callback_errors << { host: device.host, error_type: error.class.name }.freeze
                   end
+                  result = begin
+                             yield device
+                           rescue StandardError => error
+                             on_error.call(device, error)
+                           end
+                  result = result.with(started_at: started_at, finished_at: Time.now.utc)
+                  outcomes[index] = result
+                  Array(on_result).each do |callback|
+                    begin
+                      callback.call(result)
+                    rescue StandardError => error
+                      callback_errors << { host: device.host, error_type: error.class.name }.freeze
+                    end
+                  end
                 end
+              ensure
+                finished << Thread.current
               end
             end
-          end
-          completed = false
-          begin
-            threads.each(&:value)
+            # 按完成顺序观察失败，避免后启动线程的中断被前面的慢设备阻塞。
+            # 结果仍写回清单槽位，完成通知不会改变公开结果的顺序。
+            worker_count.times { finished.pop.value }
             completed = true
           ensure
             # 中断或某个 worker 抛出非 StandardError 时，不让其他设备任务

data/lib/net/connector/operations/tftp/file_upload.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "strategy"
+
+module Net
+  module Connector
+    module Operations
+      module Tftp
+        # H3C 和华为共用已保存文件上传流程，源文件发现仍由厂商策略负责。
+        class FileUpload < Strategy
+          # 未指定目标名时，设备使用配置源文件的 basename。
+          def default_path(source_file) = File.basename(source_file)
+
+          # 仅在调用方指定目标名时追加参数，保留设备原生命名行为。
+          def script(target, source_file:, vrf: nil)
+            raise ArgumentError, "TFTP file upload does not use vrf" if vrf
+
+            destination = target.explicit_path? ? " #{target.path}" : ""
+            Script.new([Command.new("tftp #{target.host} put #{source_file}#{destination}", timeout: 180)])
+          end
+
+          # 只接受明确的成功消息、非零传输字节数或完整进度行。
+          def complete?(result)
+            completion_lines(result).any? { |line| completed_upload?(line) }
+          end
+
+          private
+
+          # 两个厂商的上传完成消息使用相同的文本及进度格式。
+          def completed_upload?(line)
+            line.match?(/\A
+              (?:File\s+)?(?:transfer|upload)(?:\s+(?:is|was))?\s+
+              (?:success(?:ful(?:ly)?)?|succeeded|complete(?:d)?(?:\s+successfully)?)[.!]?
+              \z/ix) ||
+              line.match?(/\A[1-9]\d*\s+bytes?\s+sent(?:\s+in\s+[\d.]+\s+(?:secs?|seconds?))?[.!]?\z/i) ||
+              completed_progress?(line)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/operations/tftp/strategy.rb

@@ -13,6 +13,14 @@ module Net
         autoload :PaloAlto, File.expand_path("palo_alto", __dir__)
 
         class Strategy
+          # 厂商只声明格式差异，清单规划与设备直连共用同一命名规则。
+          def self.file_extension = "cfg"
+
+          # 不创建会话即可生成目标名，供批量计划检查文件覆盖风险。
+          def self.filename(host, label: nil)
+            TftpTarget.filename(host, extension: file_extension, label: label)
+          end
+
           # 保存 TFTP 厂商策略使用的设备对象。
           def initialize(device)
             @device = device
@@ -23,7 +31,7 @@ module Net
           def source_file(value) = value
 
           # 根据设备地址生成默认远端文件名。
-          def default_path(_source_file) = TftpTarget.filename(@device.host, extension: "cfg")
+          def default_path(_source_file) = self.class.filename(@device.host)
 
           # 返回目标中指定的远端文件名。
           def remote_path(target, _result) = target.path
@@ -53,16 +61,6 @@ module Net
             line.match?(/\A100\s+([1-9]\d*(?:\.\d+)?[kMGT]?)\s+0\s+0\s+100\s+\1(?:\s+[\d.:kMGT-]+)*\z/i)
           end
 
-          # H3C 和华为的上传完成消息使用相同的文本及进度格式。
-          def completed_upload?(line)
-            line.match?(/\A
-              (?:File\s+)?(?:transfer|upload)(?:\s+(?:is|was))?\s+
-              (?:success(?:ful(?:ly)?)?|succeeded|complete(?:d)?(?:\s+successfully)?)[.!]?
-              \z/ix) ||
-              line.match?(/\A[1-9]\d*\s+bytes?\s+sent(?:\s+in\s+[\d.]+\s+(?:secs?|seconds?))?[.!]?\z/i) ||
-              completed_progress?(line)
-          end
-
           # Cisco 明确报告复制完成的字节数，可附带耗时和速率。
           def copied_bytes?(line)
             line.match?(/\A

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

@@ -15,24 +15,38 @@ module Net
 
         # 厂商拓扑规则；默认不提供任何设备能力。
         class Strategy
+          # 保存设备供厂商规则查询档案和会话状态。
           def initialize(device)
             @device = device
           end
 
+          # 声明策略类支持的拓扑能力，默认全部关闭。
           def self.supports?(_capability) = false
+          # 将实例级能力查询交给策略类声明。
           def supports?(capability) = self.class.supports?(capability)
 
+          # 返回读取邻居的命令，未定义时不支持发现。
           def neighbor_command = nil
+          # 根据原始输出选择邻居解析模板。
           def neighbor_template(_output) = nil
+          # 返回当前接口描述所用的解析模板。
           def description_template = nil
+          # 返回输出中应解析出的邻居数量，供完整性校验使用。
           def expected_neighbor_count(_output, _template) = 0
+          # 只有明确的空表证据才允许返回空邻居列表。
           def empty_neighbor_output?(_output) = false
+          # 返回进入设备配置视图的命令。
           def enter_configuration = nil
+          # 返回离开配置视图和保存配置所需的命令。
           def finish_commands = []
+          # 为一条接口描述变更生成厂商命令。
           def change_commands(_change) = []
+          # 标明邻居发现使用的协议。
           def protocol = :lldp
+          # 在下发前允许厂商调整命令对象及超时。
           def script_command(command) = command
 
+          # 将发现接口名归一为查找当前配置所用的键。
           def interface_key(name) = InterfaceName.key(name)
 
           # 将发现协议常用的接口简称展开为配置视图可识别的名称。

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

@@ -155,6 +155,7 @@ module Net
           Result.new(steps: result.steps, error: error)
         end
 
+        # 下发描述前确认厂商提供配置能力，避免把只读发现当成可写能力。
         def check_change_support!(phase)
           return if @strategy.supports?(:interface_description_changes)
 

data/lib/net/connector/vendor/cisco_ios/running_config.rb

@@ -6,6 +6,7 @@ module Net
   module Connector
     module CiscoIos
       class RunningConfig < Net::Connector::RunningConfig::Rendered
+        # 去掉终端长度设置、保存命令回显和易变化的配置时间注释。
         def clean(text)
           config = super
           config.gsub!(/^[^\n]*#\s*terminal\s+length\s+0\s*\n/i, "")

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

@@ -6,24 +6,33 @@ module Net
   module Connector
     module CiscoIos
       class Topology < Operations::Topology::Strategy
+        # IOS 提供 CDP 邻居、配置描述读取和描述变更。
         def self.supports?(capability)
           %i[neighbors interface_descriptions interface_description_changes].include?(capability)
         end
 
+        # 使用详细 CDP 输出获取对端设备与端口。
         def neighbor_command = "show cdp neighbors detail"
+        # 从运行配置解析接口描述。
         def description_template = "cisco_ios_running_config_interfaces.textfsm"
+        # 标记发现协议，供邻居记录使用。
         def protocol = :cdp
+        # 进入全局配置视图。
         def enter_configuration = "configure terminal"
+        # 退出配置视图并执行档案定义的保存命令。
         def finish_commands = ["end"] + @device.profile.save_commands
 
+        # 每个 Device ID 表示一条应由模板解析的邻居记录。
         def expected_neighbor_count(output, _template)
           output.scan(/^\s*Device ID:\s*\S+/i).size
         end
 
+        # 只有设备明确报告零 CDP 邻居时才认可空表。
         def empty_neighbor_output?(output)
           output.match?(/Total cdp entries displayed\s*:\s*0|no cdp neighbors/i)
         end
 
+        # 复用公共接口描述命令，保留本机接口原名。
         def change_commands(change)
           InterfaceDescription.commands(interface: change.interface, description: change.new_description)
         end

data/lib/net/connector/vendor/cisco_nxos/running_config.rb

@@ -6,6 +6,7 @@ module Net
   module Connector
     module CiscoNxos
       class RunningConfig < CiscoIos::RunningConfig
+        # 先清除 NX-OS 分页与进度回显，再复用 IOS 的配置清理规则。
         def clean(text)
           without_pager = text.to_s.gsub(
             /[ \t]*(?:\x1b\[[0-9;]*[A-Za-z])*--More--

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

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/tftp/strategy"
+require_relative "../../operations/tftp/file_upload"
 
 module Net
   module Connector
     module H3c
-      class TftpBackup < Operations::Tftp::Strategy
+      class TftpBackup < Operations::Tftp::FileUpload
         # 选取并校验 H3C 启动配置文件路径。
         def source_file(value)
           return TftpTarget.validate_source_file!(value) if value
@@ -21,22 +21,6 @@ module Net
 
           TftpTarget.validate_source_file!(path.sub(/\(\*\)\z/, ""))
         end
-
-        # 根据 H3C 源文件确定默认导出名称。
-        def default_path(source_file) = File.basename(source_file)
-
-        # 构造当前厂商的 TFTP 导出交互脚本。
-        def script(target, source_file:, vrf: nil)
-          raise ArgumentError, "H3C TFTP backup does not use vrf" if vrf
-
-          destination = target.explicit_path? ? " #{target.path}" : ""
-          Script.new([Command.new("tftp #{target.host} put #{source_file}#{destination}", timeout: 180)])
-        end
-
-        # 检查设备回显是否确认 TFTP 传输完成。
-        def complete?(result)
-          completion_lines(result).any? { |line| completed_upload?(line) }
-        end
       end
     end
   end

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

@@ -7,15 +7,21 @@ module Net
     module H3c
       class Topology < Operations::Topology::Strategy
         TABLE_HEADER = /^\s*(?:System Name\s+Local Interface\b|(?:Local Interface|LocalIf)\s+)/i
+        # H3C 提供 LLDP 邻居、配置描述读取和描述变更。
         def self.supports?(capability)
           %i[neighbors interface_descriptions interface_description_changes].include?(capability)
         end
 
+        # 读取设备的 LLDP 邻居列表。
         def neighbor_command = "display lldp neighbor-information list"
+        # 从运行配置解析当前接口描述。
         def description_template = "h3c_interface_descriptions.textfsm"
+        # 进入系统视图以修改接口描述。
         def enter_configuration = "system-view"
+        # 返回用户视图并执行保存命令。
         def finish_commands = ["return"] + @device.profile.save_commands
 
+        # H3C 不同版本的列顺序不同，按表头选对应模板。
         def neighbor_template(output)
           return "h3c_lldp_name_first.textfsm" if output.match?(/^\s*System Name\s+Local Interface\b/im)
           return "h3c_lldp_local_first.textfsm" if output.match?(/^\s*(?:Local Interface|LocalIf)\s+/im)
@@ -24,6 +30,7 @@ module Net
                                  host: @device.host, phase: :discover)
         end
 
+        # 按表头后的有效数据行计数，未知行会让完整性校验失败。
         def expected_neighbor_count(output, template)
           local_column = template == "h3c_lldp_name_first.textfsm" ? 1 : 0
           lines = neighbor_lines(output)
@@ -38,12 +45,14 @@ module Net
         # 表头之后的未知行不能作为零邻居证据。
         def empty_neighbor_output?(output) = neighbor_lines(output).empty?
 
+        # 在接口视图设置描述后用 quit 返回系统视图。
         def change_commands(change)
           InterfaceDescription.commands(interface: change.interface, description: change.new_description, leave: "quit")
         end
 
         private
 
+        # 过滤表头、分隔线和设备提示符，保留待解析的邻居行。
         def neighbor_lines(output)
           output.lines.drop_while { |line| !line.match?(TABLE_HEADER) }.map(&:strip).reject do |line|
             line.empty? || line.match?(TABLE_HEADER) || line.match?(/\A[-=+ ]+\z/) ||

data/lib/net/connector/vendor/hillstone/running_config.rb

@@ -6,6 +6,7 @@ module Net
   module Connector
     module Hillstone
       class RunningConfig < Net::Connector::RunningConfig::Strategy
+        # 去掉山石 CLI 用退格控制符绘制的分页痕迹。
         def clean(text) = text.gsub(/\x00?\x08+[ \t]+\x08+/, "")
       end
     end