net-connector 0.4.0 → 0.4.2

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

@@ -28,7 +28,7 @@ module Net
                                            code: :neighbor_discovery_unsupported, host: @device.host, phase: :discover)
           end
 
-          output = @device.execute(command).value!
+          output = @parser.utf8(@device.execute(command).value!, host: @device.host)
           template = @strategy.neighbor_template(output)
           rows = @parser.call(output, template: template, vendor: @device.vendor, command: command, host: @device.host)
           if rows.size != @strategy.expected_neighbor_count(output, template) || (rows.empty? && !@strategy.empty_neighbor_output?(output))
@@ -46,14 +46,21 @@ module Net
         end
 
         # 从运行配置读取已设置的接口描述或端口名称。
-        def descriptions
+        def descriptions = read_descriptions
+
+        # 内部读取先交付执行步骤，再处理解析；解析失败也不能抹去已经完成的采集命令。
+        def read_descriptions
           template = @strategy.description_template
           unless @strategy.supports?(:interface_descriptions) && template
             raise UnsupportedOperation.new("interface descriptions are unsupported for this vendor",
                                            code: :description_unsupported, host: @device.host, phase: :discover)
           end
-          config = @device.running_config.value!
-          @parser.call(config, template: template, host: @device.host).each_with_object({}) do |row, found|
+          result = @device.running_config
+          yield result if block_given?
+          config = result.value!
+          rows = @parser.call(config, template: template, host: @device.host)
+          @strategy.validate_descriptions!(config, rows) if @strategy.respond_to?(:validate_descriptions!)
+          rows.each_with_object({}) do |row, found|
             interface = @strategy.interface_key(row.fetch("INTERFACE"))
             description = @strategy.decode_description(row.fetch("DESCRIPTION", ""))
             previous = found[interface]
@@ -65,6 +72,8 @@ module Net
           end
         end
 
+        private :read_descriptions
+
         # 比对邻居和现有描述，生成包含确切命令的只读变更计划。
         def plan_descriptions(abbreviate: true, lowercase: false, &formatter)
           check_change_support!(:plan) if @strategy.supports?(:neighbors)
@@ -88,7 +97,7 @@ module Net
           commands = if changes.empty?
                        []
                      else
-                       [@strategy.enter_configuration] + changes.flat_map { |change| change_commands(change) } + @strategy.finish_commands
+                       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,
@@ -102,18 +111,65 @@ module Net
                                            host: @device.host, phase: :apply)
           end
           raise ArgumentError, "plan must be a topology plan for this device" unless plan.is_a?(Plan) &&
-                                                                           plan.host == @device.host &&
-                                                                           plan.vendor == @device.vendor
-          return Result.new if plan.changes.empty?
+                                                                                     plan.host == @device.host &&
+                                                                                     plan.vendor == @device.vendor
+          if plan.changes.empty?
+            raise ArgumentError, "empty topology plan cannot contain commands" unless plan.commands.empty?
+
+            return Result.new
+          end
 
-          check_change_support!(:apply) if @strategy.supports?(:neighbors)
+          @strategy.supports?(:neighbors) ? check_change_support!(:apply) : neighbors
           @device.with_operation(:apply) { apply_plan(plan) }
         end
 
         private
 
-        # 现场复核、修改和回读属于同一次独占操作。
+        # 同一租约覆盖重验、修改、读回与保存；有完成步骤后发生的错误必须带回这些步骤。
         def apply_plan(plan)
+          stages = stage_scripts(plan.changes)
+          unless stages.values.flat_map { |script| script.map(&:text) } == plan.commands
+            raise ArgumentError, "plan commands were modified or use an older execution sequence; regenerate the plan"
+          end
+          revalidate_plan!(plan)
+          steps = []
+          result = execute_stage(stages.fetch(:change), steps)
+          return Result.new(steps: steps, error: result.error) if result.failure?
+
+          verify_descriptions!(plan.changes, stages.fetch(:verify), steps)
+          persisting = true
+          result = execute_stage(stages.fetch(:persist), steps)
+          if result.failure? || !@strategy.persistence_confirmed?(result)
+            return Result.new(steps: steps, error: persistence_error(result.error))
+          end
+          Result.new(steps: steps)
+        rescue Error => error
+          raise unless steps
+
+          Result.new(steps: steps, error: persisting ? persistence_error(error) : error)
+        end
+
+        # 读回命令与审批一致，并且每个目标描述均得到确认，才允许进入保存阶段。
+        def verify_descriptions!(changes, script, steps)
+          unless Script.new(@device.config_commands).map(&:text) == script.map(&:text)
+            raise DeviceError.new("configuration readback commands changed after approval",
+                                  code: :verification_plan_changed, host: @device.host, phase: :verify)
+          end
+          updated = read_descriptions do |readback|
+            steps.concat(readback.steps)
+            if readback.success? && readback.steps.map { |step| step.command.text } != script.map(&:text)
+              raise DeviceError.new("configuration readback did not execute the approved commands",
+                                    code: :verification_plan_changed, host: @device.host, phase: :verify)
+            end
+          end
+          unless changes.all? { |change| updated[@strategy.interface_key(change.interface)] == change.new_description }
+            raise DeviceError.new("interface descriptions were not confirmed by readback",
+                                  code: :description_unconfirmed, host: @device.host, phase: :verify)
+          end
+        end
+
+        # 重验失败仍在写入前直接抛异常，保持 stale_plan 的既有契约。
+        def revalidate_plan!(plan)
           discovered = neighbors
           evidence = evidence_for(discovered, descriptions)
           current_neighbors = discovered.to_h { |neighbor| [@strategy.interface_key(neighbor.local_interface), neighbor] }
@@ -132,41 +188,54 @@ module Net
               raise ArgumentError, "plan changes do not match its discovery evidence"
             end
           end
-          commands = [@strategy.enter_configuration] + plan.changes.flat_map { |change| change_commands(change) } + @strategy.finish_commands
-          raise ArgumentError, "plan commands were modified" unless commands == plan.commands
+        end
 
-          script = commands.map do |command|
-            @strategy.script_command(command)
+        # 审批列表保留真正执行的读回命令，使旧版“先保存后读回”计划无法静默复用。
+        def stage_scripts(changes)
+          phases = %i[leave_configuration verification_commands persistence_commands].map do |method|
+            @strategy.public_send(method) if @strategy.respond_to?(method)
           end
-          result = @device.execute_script(Script.new(script, name: "interface descriptions"))
-          return result if result.failure?
-
-          updated = descriptions
-          return result if plan.changes.all? do |change|
-            updated.fetch(@strategy.interface_key(change.interface), "") == change.new_description
+          unless phases.all? { |commands| commands.is_a?(Array) && !commands.empty? }
+            raise UnsupportedOperation.new("topology strategy must declare separate readback and persistence stages",
+                                           code: :description_stages_unsupported, host: @device.host, phase: :plan)
+          end
+          leave, verify, persist = phases
+          sequences = {
+            change: [@strategy.enter_configuration] + changes.flat_map { |change| change_commands(change) } + leave,
+            verify: verify, persist: persist
+          }
+          sequences.transform_values do |commands|
+            Script.new(commands.map { |command| @strategy.script_command(command) }, name: "interface descriptions")
           end
+        end
 
-          Result.new(steps: result.steps,
-                     error: DeviceError.new("interface descriptions were not confirmed by readback",
-                                            code: :description_unconfirmed, host: @device.host, phase: :verify))
-        rescue Error => error
-          raise unless result&.success?
+        def execute_stage(script, steps)
+          result = @device.execute_script(script)
+          steps.concat(result.steps)
+          result
+        end
 
-          Result.new(steps: result.steps, error: error)
+        # 保存可能已执行，超时、失败或缺少完成行均不自动重放；诊断不附带回显正文。
+        def persistence_error(error = nil)
+          underlying = UnderlyingError.new(error, nil, sensitive: true) if error
+          DeviceError.new("interface descriptions were verified; persistence was not confirmed",
+                          code: :persistence_unconfirmed, host: @device.host, phase: :persist, underlying: underlying)
         end
 
+        # 下发描述前确认厂商提供配置能力，避免把只读发现当成可写能力。
         def check_change_support!(phase)
           return if @strategy.supports?(:interface_description_changes)
 
-          raise UnsupportedOperation.new("interface description changes are unsupported for this vendor",
-                                         code: :description_unsupported, host: @device.host, phase: phase)
+          code = @strategy.respond_to?(:change_error_code) ? @strategy.change_error_code : :description_unsupported
+          raise UnsupportedOperation.new("automatic interface description changes are unavailable; use a verified manual workflow",
+                                         code: code, host: @device.host, phase: phase)
         end
 
         # 汇总邻居身份和当前描述，并要求每个目标接口都有配置证据。
         def evidence_for(discovered, current)
           interfaces = discovered.group_by { |neighbor| @strategy.interface_key(neighbor.local_interface) }
           if interfaces.any? { |_interface, peers| peers.size != 1 || peers.first.neighbor_name.empty? ||
-                                 peers.first.neighbor_interface.empty? }
+            peers.first.neighbor_interface.empty? }
             raise ParsingError.new("neighbor identity is incomplete or ambiguous", code: :ambiguous_neighbor,
                                    host: @device.host, phase: :plan)
           end

data/lib/net/connector/operations.rb

@@ -10,11 +10,17 @@ module Net
       autoload :RunningConfig, File.expand_path("operations/running_config", __dir__)
       autoload :ParseOutput, File.expand_path("operations/parse_output", __dir__)
       autoload :LocalBackup, File.expand_path("operations/local_backup", __dir__)
+      autoload :BackupLock, File.expand_path("operations/backup_lock", __dir__)
       autoload :TftpBackup, File.expand_path("operations/tftp_backup", __dir__)
       autoload :Tftp, File.expand_path("operations/tftp/strategy", __dir__)
     end
     autoload :TftpTarget, File.expand_path("operations/tftp_backup", __dir__)
     autoload :TftpBackup, File.expand_path("operations/tftp_backup", __dir__)
+    autoload :TftpReceipt, File.expand_path("operations/tftp_receipt", __dir__)
+    autoload :TftpCompletionError, File.expand_path("operations/tftp_receipt", __dir__)
     autoload :Backup, File.expand_path("operations/local_backup", __dir__)
+    autoload :BackupPersistenceError, File.expand_path("operations/local_backup", __dir__)
+    autoload :BackupBusy, File.expand_path("operations/backup_lock", __dir__)
+    autoload :SavedConfigChanged, File.expand_path("operations/saved_config/legacy_index", __dir__)
   end
 end

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/tftp_backup.rb

@@ -6,10 +6,17 @@ module Net
   module Connector
     module CiscoIos
       class TftpBackup < Operations::Tftp::Strategy
+        # 在连接前拒绝当前厂商不支持的参数组合。
+        def validate_options!(_target, source_file:, vrf: nil)
+          raise ArgumentError, "Cisco IOS does not use source_file" unless source_file.nil?
+          raise ArgumentError, "Cisco IOS TFTP backup does not use vrf" unless vrf.nil?
+        end
+
+        def receipt_metadata(_target, **) = { configuration_kind: :running, format: :cfg }
+
         # 构造当前厂商的 TFTP 导出交互脚本。
         def script(target, source_file:, vrf: nil)
-          raise ArgumentError, "Cisco IOS does not use source_file" if source_file
-          raise ArgumentError, "Cisco IOS TFTP backup does not use vrf" if vrf
+          validate_options!(target, source_file: source_file, vrf: vrf)
 
           Script.new([Command.new("copy running-config tftp:", timeout: 180,
                                   interactions: [

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

@@ -1,29 +1,44 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/topology/strategy"
+require_relative "../../operations/topology/immediate_strategy"
 
 module Net
   module Connector
     module CiscoIos
-      class Topology < Operations::Topology::Strategy
+      class Topology < Operations::Topology::ImmediateStrategy
+        # 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
 
+        # 先回到执行视图读回，随后才执行档案中的保存命令。
+        def leave_configuration = ["end"]
+
+        def persistence_pattern = /\A(?:\[OK\]|Copy complete\.)\z/i
+
+        # 每个 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/cisco_nxos/tftp_backup.rb

@@ -6,9 +6,16 @@ module Net
   module Connector
     module CiscoNxos
       class TftpBackup < Operations::Tftp::Strategy
+        # 在连接前拒绝当前厂商不支持的参数组合。
+        def validate_options!(_target, source_file:, **)
+          raise ArgumentError, "Cisco NX-OS does not use source_file" unless source_file.nil?
+        end
+
+        def receipt_metadata(_target, **) = { configuration_kind: :running, format: :cfg }
+
         # 构造当前厂商的 TFTP 导出交互脚本。
         def script(target, source_file:, vrf: nil)
-          raise ArgumentError, "Cisco NX-OS does not use source_file" if source_file
+          validate_options!(target, source_file: source_file, vrf: vrf)
 
           vrf ||= "management"
           command = "copy running-config tftp://#{target.host}/#{target.path} vrf #{vrf}"

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

@@ -1,11 +1,16 @@
 # 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
+        # 自动探测选择的是启动配置；显式文件仍不能推断为运行或启动配置。
+        def receipt_metadata(target, source_file:, explicit_source:)
+          super.merge(configuration_kind: explicit_source ? :saved_file : :startup)
+        end
+
         # 选取并校验 H3C 启动配置文件路径。
         def source_file(value)
           return TftpTarget.validate_source_file!(value) if value
@@ -21,22 +26,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

@@ -1,21 +1,32 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/topology/strategy"
+require_relative "../../operations/topology/immediate_strategy"
 
 module Net
   module Connector
     module H3c
-      class Topology < Operations::Topology::Strategy
+      class Topology < Operations::Topology::ImmediateStrategy
         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
 
+        # 返回用户视图读回；保存交给后续独立阶段。
+        def leave_configuration = ["return"]
+
+        def persistence_pattern = /\ASaved the current configuration to mainboard device successfully\.\z/i
+
+        # 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 +35,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 +50,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

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

@@ -6,12 +6,24 @@ module Net
   module Connector
     module Hillstone
       class TftpBackup < Operations::Tftp::Strategy
-        # 构造当前厂商的 TFTP 导出交互脚本。
-        def script(target, source_file:, vrf: nil)
-          raise ArgumentError, "Hillstone TFTP export does not use source_file" if source_file
+        # 山石原生导出的配置文件使用 dat 扩展名。
+        def self.file_extension = "dat"
+
+        # 在连接前拒绝源文件及远端目录；未指定文件名时仍由设备生成。
+        def validate_options!(target, source_file:, **)
+          raise ArgumentError, "Hillstone TFTP export does not use source_file" unless source_file.nil?
           if target.explicit_path? && target.path.include?("/")
             raise ArgumentError, "Hillstone TFTP filename cannot contain a directory"
           end
+        end
+
+        def receipt_metadata(target, **)
+          { configuration_kind: :startup, format: :dat, requested_path: target.explicit_path? ? target.path : nil }
+        end
+
+        # 构造当前厂商的 TFTP 导出交互脚本。
+        def script(target, source_file:, vrf: nil)
+          validate_options!(target, source_file: source_file, vrf: vrf)
 
           command = "export configuration startup to tftp server #{target.host} vrouter #{vrf || "mgt-vr"}"
           command += " #{target.path}" if target.explicit_path?
@@ -31,6 +43,7 @@ module Net
 
         private
 
+        # 仅认可设备明确给出目标文件名的 Export ok 回显。
         def completion_line(result)
           completion_lines(result).find { |line| line.match?(/\AExport\s+ok\s*,\s*target\s+file\s+name\s+\S+\z/i) }
         end

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

@@ -1,20 +1,31 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/topology/strategy"
+require_relative "../../operations/topology/immediate_strategy"
 
 module Net
   module Connector
     module Hillstone
-      class Topology < Operations::Topology::Strategy
+      class Topology < Operations::Topology::ImmediateStrategy
+        # 山石提供 LLDP 邻居、配置描述读取和描述变更。
         def self.supports?(capability)
           %i[neighbors interface_descriptions interface_description_changes].include?(capability)
         end
 
+        # 读取 LLDP 邻居信息。
         def neighbor_command = "show lldp neighbor-information"
+
+        # 从运行配置解析接口描述。
         def description_template = "hillstone_interface_descriptions.textfsm"
+
+        # 进入配置视图。
         def enter_configuration = "configure"
-        def finish_commands = ["exit"] + @device.profile.save_commands
 
+        # 退出配置视图后先读回，保存动作随后单独执行。
+        def leave_configuration = ["exit"]
+
+        def persistence_pattern = /\ASaving configuration is finished\.?\z/i
+
+        # 用数据行和设备报告的总数交叉核对，避免遗漏邻居。
         def expected_neighbor_count(output, _template)
           reported = output[/Total lldp neighbor number:\s*(\d+)/i, 1]
           lines = neighbor_lines(output)
@@ -24,17 +35,20 @@ module Net
           lines.size
         end
 
+        # 仅在列表为空且有明确零邻居证据时认可空表。
         def empty_neighbor_output?(output)
           neighbor_lines(output).empty? && (output.match?(/Total lldp neighbor number:\s*0\b/i) ||
             output.match?(/System Name\s+Local Interface/i))
         end
 
+        # 复用公共接口描述命令。
         def change_commands(change)
           InterfaceDescription.commands(interface: change.interface, description: change.new_description)
         end
 
         private
 
+        # 去掉命令、表头、总数和提示符，只保留邻居数据行。
         def neighbor_lines(output)
           output.lines.map(&:strip).reject do |line|
             line.empty? || line == neighbor_command || line.match?(/\ASystem Name\s+Local Interface\b/i) ||

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

@@ -1,33 +1,23 @@
 # frozen_string_literal: true
 
-require_relative "../../operations/tftp/strategy"
+require_relative "../../operations/tftp/file_upload"
 
 module Net
   module Connector
     module Huawei
-      class TftpBackup < Operations::Tftp::Strategy
+      class TftpBackup < Operations::Tftp::FileUpload
+        # 缺少源文件也必须在首次设备 I/O 之前拒绝。
+        def validate_options!(target, source_file:, vrf: nil)
+          super
+          raise ArgumentError, "Huawei TFTP backup requires source_file" if source_file.nil?
+        end
+
         # 要求调用方提供合法的华为启动配置文件路径。
         def source_file(value)
           raise ArgumentError, "Huawei TFTP backup requires source_file" unless value
 
           TftpTarget.validate_source_file!(value)
         end
-
-        # 根据华为配置源文件确定默认导出名称。
-        def default_path(source_file) = File.basename(source_file)
-
-        # 构造当前厂商的 TFTP 导出交互脚本。
-        def script(target, source_file:, vrf: nil)
-          raise ArgumentError, "Huawei 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/palo_alto/running_config.rb

@@ -7,6 +7,7 @@ module Net
   module Connector
     module PaloAlto
       class RunningConfig < Net::Connector::RunningConfig::Strategy
+        # 配置位于 show 步骤，最后的 exit 只负责离开候选视图。
         def result_step(result)
           result.steps.find { |step| step.command.text == "show" }
         end
@@ -21,6 +22,7 @@ module Net
           end
         end
 
+        # 采集前后都检查候选差异，拒绝把未提交配置误作运行配置。
         def check_response(command, response, _execution)
           return unless command.text == "show config diff"
           return if body(response.output, command.text).empty?
@@ -29,6 +31,7 @@ module Net
                                 code: :uncommitted_configuration, host: @device.host, phase: :collect)
         end
 
+        # 只接受完整的 set 命令文本，排除 XML 或截断的引号配置。
         def clean(text)
           normalized = body(text, "show").sub(/(?:\A|\n)[ \t]*\[edit\][ \t]*\z/, "").strip
           unless set_commands?(normalized)
@@ -60,6 +63,7 @@ module Net
           pending.empty?
         end
 
+        # 去掉命令回显和提示符，保留真正需要校验的设备响应。
         def body(text, command)
           text.gsub("\r\n", "\n").sub(/\A[ \t]*#{Regexp.escape(command)}[ \t]*\n/, "")
               .sub(@device.profile.command_prompt, "").strip

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

@@ -6,18 +6,29 @@ module Net
   module Connector
     module PaloAlto
       class TftpBackup < Operations::Tftp::Strategy
+        FILENAME = "running-config.xml"
+
         # 返回 PAN-OS 固定使用的运行配置文件名。
-        def default_path(_source_file) = "running-config.xml"
+        def self.filename(_host, **) = FILENAME
+
+        # 默认文件名尚未生成时只校验显式目标；固定名冲突仍由批量计划拒绝。
+        def validate_options!(target, source_file:, vrf: nil)
+          raise ArgumentError, "PAN-OS does not use source_file" unless source_file.nil?
+          raise ArgumentError, "PAN-OS TFTP backup does not use vrf" unless vrf.nil?
+          if target.explicit_path? && target.path != FILENAME
+            raise ArgumentError, "PAN-OS TFTP export uses the fixed filename #{FILENAME}"
+          end
+        end
+
+        def receipt_metadata(_target, **)
+          { configuration_kind: :running, format: :xml, source_file: FILENAME }
+        end
 
         # 构造当前厂商的 TFTP 导出交互脚本。
         def script(target, source_file:, vrf: nil)
-          raise ArgumentError, "PAN-OS does not use source_file" if source_file
-          raise ArgumentError, "PAN-OS TFTP backup does not use vrf" if vrf
-          unless target.path == "running-config.xml"
-            raise ArgumentError, "PAN-OS TFTP export uses the fixed filename running-config.xml"
-          end
+          validate_options!(target, source_file: source_file, vrf: vrf)
 
-          Script.new([Command.new("tftp export configuration to #{target.host} from running-config.xml",
+          Script.new([Command.new("tftp export configuration to #{target.host} from #{FILENAME}",
                                   timeout: 180)])
         end
 
@@ -29,7 +40,7 @@ module Net
         end
 
         # 返回 PAN-OS 实际上传的固定文件名。
-        def remote_path(_target, _result) = "running-config.xml"
+        def remote_path(_target, _result) = FILENAME
       end
     end
   end